{"_id":"@buddhilive/dsh-scope","name":"@buddhilive/dsh-scope","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-scope","description":"Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/core/scope"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-scope@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-otZmaS1X/FxCZjuy7ao4lr14sTsPpiOlb9dhbE+LXsLx4zOvu1qa4IEXzeHVaxkIWTDnlZKNxtdP9/kVoI72Zw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-scope-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-scope-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-otZmaS1X/FxCZjuy7ao4lr14sTsPpiOlb9dhbE+LXsLx4zOvu1qa4IEXzeHVaxkIWTDnlZKNxtdP9/kVoI72Zw==","shasum":"7d238bb8eca375129f0b0c75c568bb988181937c","tarball":"https://registry.npmjs.org/@buddhilive/dsh-scope/-/dsh-scope-0.1.2-alpha.3.tgz","fileCount":11,"unpackedSize":44897,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDIhzzCheNkql8dNBY3okD6Ipk/jnjIiAboUFGuopu4EwIhALyj/Sq5q76aL5zAMfGVSaoqA5n3x2v7y8BWn/S5Bnl4"}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-scope_0.1.2-alpha.3_1788164950051_0.5302830186875831"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:29:09.860Z","0.1.2-alpha.3":"2026-08-31T08:29:10.177Z","modified":"2026-08-31T08:29:10.411Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/core/scope"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向插件作者与维护者的作用域注册库，用于构建按 agent 或按分组隔离贡献的注册表或事件表面。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-scope\n\n[English](README.md) | 中文\n\n## 概述\n\n零依赖的 `dsh-scope` 库让注册拥有按 agent 归属的家。用 `createScope(ctx, key)` 创建带标签的上下文，通过它进行的每项注册只在一个作用域内可见，并随该作用域 dispose（资源释放）而撤销；用 `scopeOf(ctx)` 读取上下文的作用域标签；用 `scopeTarget(base, key)` 把带作用域的事件路由到键相同的监听器，同时让无标签监听器保持全局可见。键可以构成父链：子作用域看得见祖先的各层（近者遮蔽远者），标签为祖先的监听器能收到子孙键的事件——反向永不成立。该机制与键的具体含义无关：agent loop（智能体循环）为每个存活的 agent 创建一个作用域，agent preset 的常驻挂载则是其 agent 们的父作用域，但底层包无需依赖两者即可使用。构建必须按 agent 或按分组隔离贡献的注册表或事件表面时，请选择本包。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n插件作者使用 `dsh-scope` 为单个 agent（或单个分组）提供独立的注册世界。core 分组中的注册表都构建在它之上——通过 `agent.ctx` 注册的工具只对该 agent 可见——同样的原语也服务于任何自定义注册表或带作用域的事件。\n\n### 创建作用域\n\n`createScope(ctx, key)` 在 `ctx` 的 fiber 下创建作用域：其 `ctx` 携带作用域标签，通过它进行的每项注册既具备作用域可见性，也服从作用域生命周期。`dispose()` 撤销通过该作用域进行的每项注册；`rawDispose` 是确切 Cordis disposer，用于把 teardown 嵌套进有序组合 effect。\n\n```text\nconst scope = createScope(ctx, agent)\nscope.ctx.on('agent/status', ({ agent, status }) => track(agent, status))\n// later:\nawait scope.dispose()   // unwinds every registration made through scope.ctx\n```\n\n### 路由带作用域的事件\n\n`scopeTarget(base, key)` 构造带作用域事件分发所用的不透明载体。无标签监听器保持全局；标签为 `key` 的监听器接收该键及其后代的事件。载体只携带路由状态——真实主体由事件参数携带。\n\n### 构建带作用域的注册表层\n\n注册表作者使用 `ScopedLayers`、`NamedEntries` 与 `AnonymousEntries` 持有一个立即构造的全局层加惰性创建的精确作用域层：读取从不创建层，`merge()` 沿作用域链物化按插入序的具名遮蔽，`effect()` 从同一上下文推导可见性与所有权。只有当整个聚合为空时才回收作用域层。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释该包如何实现上述行为；可观察约定已在[使用本包](#use-this-package)中完整说明。\n\n### 设计理念\n\n注册上下文同时决定可见性与所有权：通过带作用域上下文进行的注册在该作用域内可见、并随其 dispose，从而防止贡献在一个作用域中可见、却随另一个作用域拆除。该原语用于路由受信任的同进程插件；它不是沙箱或权限边界。交出带作用域的上下文，也会交出创建该上下文的插件的服务解析范围（解析沿创建者 fiber 的依赖链行进），因此作用域应由具备这些带作用域注册所需依赖的插件来创建。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | `createScope`、`scopeOf`、`scopeTarget`、`bindScopeParent`/`scopeParentOf`/`scopeChainOf`、载体标记 |\n| [`src/store.ts`](src/store.ts) | `ScopedLayers`、`NamedEntries`、`AnonymousEntries`、`ScopeLayer` |\n| [`src/invariant.ts`](src/invariant.ts) | 基于生成的作用域事件映射的不变式配套 |\n| [`src/scoped-events.generated.ts`](src/scoped-events.generated.ts) | 已声明带作用域事件的生成解析器映射 |\n\n### 父链\n\n一个关系支撑两个方向：注册视图沿链**向下**继承（子作用域看得见祖先的各层），事件放行沿链**向上**扩展（标签为祖先的监听器收到分发到后代键的事件）。绑定仅此一次——已有父级的键直接抛错，只有返回的绑定句柄才能重新绑定——且每次链接都拒绝闭环。`scopeChainOf` 返回 `[key, parent, …]`，最近者在前。\n\n### 事件筛选\n\n`scopeTarget` 把基对象的现有 `Context.filter` 与作用域谓词组合起来：无标签监听器放行；有标签监听器仅当标签为分发键或其祖先时放行；`key === undefined` 只放行无标签监听器。带 `{ global: true }` 的监听器绕过筛选。`Scoped<T>` brand 要求带作用域事件以载体作为 `this` 类型，因此用裸主体分发会产生编译错误。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n包级约定对大多数消费方已经足够；需要周边领域与设计原理时再阅读以下页面。\n\n- [作用域注册子系统](../../../docs/subsystems/scope.zh.md)——身份、载体与层类型。\n- [agent 作用域上下文 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md)——安全非目标与上下文设计。\n- [作用域层存储 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md)——注册表层决策。\n- [agent 作用域 runtime 设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md)——循环如何构建按 agent 的作用域。\n- [core 分组地图](../README.zh.md)——core 各包如何组合。\n\n-----\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n这些限制说明该原语何时需要特别留意。它们是当前包约束，不是任务积压。\n\n- **只有感知作用域的表层才会隔离状态**：注册表必须按 `scopeOf()` 归档，事件必须通过 `scopeTarget()` 分发；仅仅通过带作用域的上下文调用任意 Cordis 服务，并不会改变该服务仍为上下文全局这一事实。\n- **一个上下文只携带一个最近的作用域键**：层级关系存在于键级父关系中而非上下文标签里；嵌套作用域上下文仍遮蔽为单一标签，多成员策略集仍不受支持。\n- **服务可达性来自作用域创建者**：交出 `Scope.ctx` 也会交出创建插件注入的服务范围，因此，若作用域创建者提供的服务范围较宽，持有者之后也无法将其收窄。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-3aa714c7e6f112843edcc24c9522de98"}