@liusiqi-dev/dsh-scope 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Based on DeepSeek Harness, Copyright © 2026 DeepSeek Harness, MIT License. Modified by Liusiqi.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,52 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/core/scope/README.md
+/:
+  en: 47f2816e2d2cecb9
+  zh: e051427327761450
+/deepseek-ai-dsh-scope:
+  en: a493a184041d2c95
+  zh: af060f6404de90d8
+/deepseek-ai-dsh-scope/summary:
+  en: f645dd571d3c8ca7
+  zh: 781b83572498adf1
+/deepseek-ai-dsh-scope/table-of-contents:
+  en: 80b31a934611cb4a
+  zh: 05f3f7f9cb2fd881
+/deepseek-ai-dsh-scope/use-this-package:
+  en: 14e53a4df086a0de
+  zh: 17ea1f39cfbe007e
+/deepseek-ai-dsh-scope/use-this-package/mint-a-scope:
+  en: e7bfa7a59f61fd72
+  zh: 852d6d4b113babd1
+/deepseek-ai-dsh-scope/use-this-package/route-scoped-events:
+  en: 7439a6c862956a63
+  zh: bfeda5194bb8cdc9
+/deepseek-ai-dsh-scope/use-this-package/build-a-scoped-registry-layer:
+  en: 187aa0e904782395
+  zh: 14fa36d3716eaff2
+/deepseek-ai-dsh-scope/understand-the-implementation:
+  en: ce7e776e9d516bdb
+  zh: 59d2751743db7795
+/deepseek-ai-dsh-scope/understand-the-implementation/design-concept:
+  en: 1d19d421fa6f3546
+  zh: ed6679cfc9166f14
+/deepseek-ai-dsh-scope/understand-the-implementation/source-map:
+  en: 52dd18180452c174
+  zh: 47d0198266697794
+/deepseek-ai-dsh-scope/understand-the-implementation/the-parent-chain:
+  en: f0c433a9b0091de4
+  zh: 21cecb4194aff7d0
+/deepseek-ai-dsh-scope/understand-the-implementation/event-filtering:
+  en: 9ec9b8d491c7dfe7
+  zh: da82e63bac268535
+/deepseek-ai-dsh-scope/further-exploration:
+  en: f6f4e46a89785446
+  zh: ea130e3ffefe1139
+/deepseek-ai-dsh-scope/known-limitations-and-deferred-work:
+  en: 87eea2029792dc14
+  zh: ba020413273d3235
+/deepseek-ai-dsh-scope/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+---
+description: "The scoped-registration library for plugin authors and maintainers building registries or event surfaces that isolate contributions per agent or per group."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @liusiqi-dev/dsh-scope
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-scope` lets plugin authors give each agent or group an isolated contribution set with a shared lifetime. Child scopes inherit ancestor contributions, with the nearest definition taking precedence, while ancestor scopes can observe descendant activity; neither relationship works in reverse. Disposing a scope removes everything owned by it. Use this dependency-free library when per-agent or per-group isolation must work without depending on the agent loop or presets.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Plugin authors use `dsh-scope` to give one agent (or one group) its own registration world. The registries in the core group build on it — a tool registered through `agent.ctx` is visible only to that agent — and the same primitive serves any custom registry or scope-filtered event.
+
+### Mint a scope
+
+`createScope(ctx, key)` creates a scope under `ctx`'s fiber: its `ctx` carries the scope tag, and everything registered through it is both scope-visible and scope-lifetime. `dispose()` unwinds every registration through the scope; `rawDispose` is the exact Cordis disposer for nesting the teardown in an ordered composite effect.
+
+```text
+const scope = createScope(ctx, agent)
+scope.ctx.on('agent/status', ({ agent, status }) => track(agent, status))
+// later:
+await scope.dispose()   // unwinds every registration made through scope.ctx
+```
+
+### Route scoped events
+
+`scopeTarget(base, key)` builds the opaque carrier a scope-filtered event dispatches with. Untagged listeners stay global; a listener tagged with `key` receives events for that key and its descendants. The carrier carries routing state only — the real subject travels in the event arguments.
+
+### Build a scoped registry layer
+
+Registry authors use `ScopedLayers`, `NamedEntries`, and `AnonymousEntries` to hold one eager global layer plus lazily created exact-scope layers: reads never create layers, `merge()` materializes insertion-ordered named shadows along the scope chain, and `effect()` derives visibility and ownership from the same context. A scoped layer is reclaimed only when its whole aggregate is empty.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the package realizes the behavior above; the observable contract is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The registration context determines both visibility and ownership: a registration made through a scoped context is visible in that scope and disposed with it, preventing a contribution from being visible in one scope but torn down with another. The primitive routes trusted same-process plugins; it is not a sandbox or an authority boundary. Handing out a scoped context also hands out the minting plugin's service-resolution API (resolution walks the minting fiber's dependency chain), so a scope is minted from the plugin whose dependencies the scoped registrations need.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `createScope`, `scopeOf`, `scopeTarget`, `bindScopeParent`/`scopeParentOf`/`scopeChainOf`, carrier marks |
+| [`src/store.ts`](src/store.ts) | `ScopedLayers`, `NamedEntries`, `AnonymousEntries`, `ScopeLayer` |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion over the generated scoped-event map |
+| [`src/scoped-events.generated.ts`](src/scoped-events.generated.ts) | Generated resolver map of declared scoped events |
+
+### The parent chain
+
+One relation powers both directions: registration views inherit DOWN the chain (a child scope sees its ancestors' layers), while event admission extends UP it (a listener tagged with an ancestor receives events dispatched to a descendant key). Binding is once — a key that already has a parent throws, and only the returned binding may re-link it — and every link rejects a cycle. `scopeChainOf` returns `[key, parent, …]` nearest-first.
+
+### Event filtering
+
+`scopeTarget` composes the base's existing `Context.filter` with the scope predicate: an untagged listener is admitted; a tagged listener is admitted iff its tag is the dispatch key or an ancestor of it; `key === undefined` admits untagged listeners only. `{ global: true }` listeners bypass filtering. The `Scoped<T>` brand demands the carrier as the `this` type of a scope-filtered event, so dispatching with a bare subject is a compile error.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+The package-level contract is enough for most consumers; read these when you need the surrounding domain and the design rationale.
+
+- [Scoped registration subsystem](../../../docs/subsystems/scope.md) — the identity, carrier, and layer types.
+- [Agent-scope contexts Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) — the security non-goals and context design.
+- [Agent-scope runtime design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md) — how the loop builds per-agent scopes.
+- [Core group map](../README.md) — how the core packages compose.
+
+-----
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+These limits define when the primitive needs special care. They are current package constraints, not a task backlog.
+
+- **Only scope-aware APIs isolate state** — registries must file by `scopeOf()` and events must dispatch through `scopeTarget()`; an arbitrary Cordis service remains context-global merely because it is called through a scoped context.
+- **A context carries one nearest scope key** — the hierarchy lives in the key-level parent relation, not in context tags; nested scope contexts still shadow to a single tag, and multi-membership policy sets remain unsupported.
+- **Service reachability comes from the scope minter** — handing out `Scope.ctx` also hands out the minting plugin's injected services, so a broader minter cannot later be narrowed by the holder.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,113 @@
+---
+description: "面向插件作者与维护者的作用域注册库，用于构建按 agent（智能体）或按分组隔离贡献的注册表或事件接口。"
+kind: "package-library"
+---
+
+# @liusiqi-dev/dsh-scope
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-scope` 让插件作者能够为每个 agent 或分组提供隔离的贡献集合与统一生命周期。子作用域继承祖先贡献，且较近的定义优先；祖先作用域可以观察后代活动，这两种关系均不反向成立。释放作用域会移除它拥有的一切。按 agent 或分组隔离必须脱离 agent loop（智能体循环）与 preset 工作时，请使用这个零依赖库。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+插件作者使用 `dsh-scope` 为单个 agent（或单个分组）提供独立的注册世界。core 分组中的注册表都构建在它之上——通过 `agent.ctx` 注册的工具只对该 agent 可见——同样的原语也服务于任何自定义注册表或带作用域的事件。
+
+### 创建作用域
+
+`createScope(ctx, key)` 在 `ctx` 的 fiber 下创建作用域：其 `ctx` 携带作用域标签，通过它进行的每项注册既具备作用域可见性，也服从作用域生命周期。`dispose()` 撤销通过该作用域进行的每项注册；`rawDispose` 是确切 Cordis disposer，用于把 teardown 嵌套进有序组合 effect。
+
+```text
+const scope = createScope(ctx, agent)
+scope.ctx.on('agent/status', ({ agent, status }) => track(agent, status))
+// later:
+await scope.dispose()   // unwinds every registration made through scope.ctx
+```
+
+### 路由带作用域的事件
+
+`scopeTarget(base, key)` 构造带作用域事件分发所用的不透明载体。无标签监听器保持全局；标签为 `key` 的监听器接收该键及其后代的事件。载体只携带路由状态——真实主体由事件参数携带。
+
+### 构建带作用域的注册表层
+
+注册表作者使用 `ScopedLayers`、`NamedEntries` 与 `AnonymousEntries` 持有一个立即构造的全局层加惰性创建的精确作用域层：读取从不创建层，`merge()` 沿作用域链物化按插入序的具名遮蔽，`effect()` 从同一上下文推导可见性与所有权。只有当整个聚合为空时才回收作用域层。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释该包如何实现上述行为；可观察约定已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+注册上下文同时决定可见性与所有权：通过带作用域上下文进行的注册在该作用域内可见、并随其 dispose（资源释放），从而防止贡献在一个作用域中可见、却随另一个作用域拆除。该原语用于路由受信任的同进程插件；它不是沙箱或权限边界。交出带作用域的上下文，也会交出创建该上下文的插件的服务解析范围（解析沿创建者 fiber 的依赖链行进），因此作用域应由具备这些带作用域注册所需依赖的插件来创建。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `createScope`、`scopeOf`、`scopeTarget`、`bindScopeParent`/`scopeParentOf`/`scopeChainOf`、载体标记 |
+| [`src/store.ts`](src/store.ts) | `ScopedLayers`、`NamedEntries`、`AnonymousEntries`、`ScopeLayer` |
+| [`src/invariant.ts`](src/invariant.ts) | 基于生成的作用域事件映射的不变式配套 |
+| [`src/scoped-events.generated.ts`](src/scoped-events.generated.ts) | 已声明带作用域事件的生成解析器映射 |
+
+### 父链
+
+一个关系支撑两个方向：注册视图沿链**向下**继承（子作用域看得见祖先的各层），事件放行沿链**向上**扩展（标签为祖先的监听器收到分发到后代键的事件）。绑定仅此一次——已有父级的键直接抛错，只有返回的绑定句柄才能重新绑定——且每次链接都拒绝闭环。`scopeChainOf` 返回 `[key, parent, …]`，最近者在前。
+
+### 事件筛选
+
+`scopeTarget` 把基对象的现有 `Context.filter` 与作用域谓词组合起来：无标签监听器放行；有标签监听器仅当标签为分发键或其祖先时放行；`key === undefined` 只放行无标签监听器。带 `{ global: true }` 的监听器绕过筛选。`Scoped<T>` brand 要求带作用域事件以载体作为 `this` 类型，因此用裸主体分发会产生编译错误。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+包级约定对大多数消费方已经足够；需要周边领域与设计原理时再阅读以下页面。
+
+- [作用域注册子系统](../../../docs/subsystems/scope.zh.md)——身份、载体与层类型。
+- [agent 作用域上下文 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md)——安全非目标与上下文设计。
+- [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md)——循环如何构建按 agent 的作用域。
+- [core 分组地图](../README.zh.md)——core 各包如何组合。
+
+-----
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+这些限制说明该原语何时需要特别留意。它们是当前包约束，不是任务积压。
+
+- **只有感知作用域的 API 才会隔离状态**：注册表必须按 `scopeOf()` 归档，事件必须通过 `scopeTarget()` 分发；仅仅通过带作用域的上下文调用任意 Cordis 服务，并不会改变该服务仍为上下文全局这一事实。
+- **一个上下文只携带一个最近的作用域键**：层级关系存在于键级父关系中而非上下文标签里；嵌套作用域上下文仍遮蔽为单一标签，多成员策略集仍不受支持。
+- **服务可达性来自作用域创建者**：交出 `Scope.ctx` 也会交出创建插件注入的服务范围，因此，若作用域创建者提供的服务范围较宽，持有者之后也无法将其收窄。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,357 @@
+import { Context } from "@liusiqi-dev/cordis";
+//#region lib/types/store.js
+/**
+* Shared insertion-ordered storage and effect ownership for scope-aware registries.
+*
+* @module @liusiqi-dev/dsh-scope
+*/
+/**
+* Insertion-ordered named entries with caller-owned duplicate diagnostics.
+*
+* Values are borrowed. Iterators are live within one nonempty table
+* generation; draining the table detaches them from later insertions. Each
+* successful insertion returns an idempotent undo for that exact entry.
+*/
+var NamedEntries = class {
+	duplicateError;
+	data = /* @__PURE__ */ new Map();
+	constructor(duplicateError) {
+		this.duplicateError = duplicateError;
+	}
+	/**
+	* Insert one unique name.
+	* @param name - name unique within this table.
+	* @param value - borrowed value to retain.
+	* @returns an idempotent undo that removes only this insertion.
+	*/
+	insert(name, value) {
+		const data = this.data;
+		if (data.has(name)) throw this.duplicateError(name);
+		data.set(name, value);
+		let active = true;
+		return () => {
+			if (!active) return;
+			active = false;
+			data.delete(name);
+			if (data.size === 0 && this.data === data) this.data = /* @__PURE__ */ new Map();
+		};
+	}
+	/**
+	* Read one named value.
+	* @param name - name to resolve.
+	* @returns the retained value, or `undefined` when absent.
+	*/
+	get(name) {
+		return this.data.get(name);
+	}
+	/**
+	* Test one name for membership.
+	* @param name - name to test.
+	* @returns whether the table contains that name.
+	*/
+	has(name) {
+		return this.data.has(name);
+	}
+	/**
+	* Iterate live names in insertion order.
+	* @returns the native live key iterator.
+	*/
+	keys() {
+		return this.data.keys();
+	}
+	/**
+	* Iterate live entries in insertion order.
+	* @returns the native live entry iterator.
+	*/
+	entries() {
+		return this.data.entries();
+	}
+	/**
+	* Iterate live values in insertion order.
+	* @returns the native live value iterator.
+	*/
+	values() {
+		return this.data.values();
+	}
+	/**
+	* Test whether this table has no entries.
+	* @returns whether the table is empty.
+	*/
+	isEmpty() {
+		return this.data.size === 0;
+	}
+};
+/**
+* Insertion-ordered anonymous entries with independent registration identity.
+*
+* Equal values remain separate registrations. Values are borrowed, and
+* iterators are live within one nonempty table generation; draining the table
+* detaches them from later appends.
+*/
+var AnonymousEntries = class {
+	data = /* @__PURE__ */ new Map();
+	/**
+	* Append one independently owned value.
+	* @param value - borrowed value to retain.
+	* @returns an idempotent undo for this exact append.
+	*/
+	append(value) {
+		const data = this.data;
+		const key = Symbol();
+		data.set(key, value);
+		let active = true;
+		return () => {
+			if (!active) return;
+			active = false;
+			data.delete(key);
+			if (data.size === 0 && this.data === data) this.data = /* @__PURE__ */ new Map();
+		};
+	}
+	/**
+	* Iterate live values in insertion order.
+	* @returns the native live value iterator.
+	*/
+	values() {
+		return this.data.values();
+	}
+	/**
+	* Test whether this table has no entries.
+	* @returns whether the table is empty.
+	*/
+	isEmpty() {
+		return this.data.size === 0;
+	}
+};
+/**
+* Own the global and exact-scope layers for one registry.
+*
+* Reads never create scoped layers. Registrations derive both visibility and
+* effect ownership from the supplied Cordis context, collect undo before
+* notification, and reclaim only a completely empty aggregate layer.
+*/
+var ScopedLayers = class {
+	createLayer;
+	onChange;
+	/** The eagerly constructed context-global layer. */
+	global;
+	scoped = /* @__PURE__ */ new Map();
+	constructor(createLayer, onChange) {
+		this.createLayer = createLayer;
+		this.onChange = onChange;
+		this.global = createLayer(void 0);
+	}
+	/**
+	* Read an existing exact-scope overlay. Deliberately chain-blind: callers
+	* addressing one scope's OWN contributions (its restrictions, its guards)
+	* must not silently pick up an ancestor's — use {@link chainLayers} where
+	* inheritance is the point.
+	* @param scope - exact scope key; `undefined` denotes no overlay.
+	* @returns the existing scoped layer, or `undefined` without creating one.
+	*/
+	peek(scope) {
+		if (scope === void 0) return void 0;
+		return this.scoped.get(scope);
+	}
+	/**
+	* Existing overlays along the scope's parent chain ({@link scopeChainOf}),
+	* farthest ancestor first and the exact scope last, so a caller layering
+	* them in order gives the nearest scope the final word.
+	* @param scope - viewing scope, or `undefined` for no overlays.
+	* @returns the existing layers, nearest last; absent overlays are skipped.
+	*/
+	chainLayers(scope) {
+		const layers = [];
+		for (const key of scopeChainOf(scope).reverse()) {
+			const layer = this.scoped.get(key);
+			if (layer !== void 0) layers.push(layer);
+		}
+		return layers;
+	}
+	/**
+	* Materialize global named entries followed by scope-chain shadows,
+	* farthest ancestor first, so the nearest scope's entry wins a name.
+	* @param scope - viewing scope, or `undefined` for the global view.
+	* @param pick - select the named table from a layer.
+	* @returns an insertion-ordered effective map.
+	*/
+	merge(scope, pick) {
+		const merged = new Map(pick(this.global).entries());
+		for (const layer of this.chainLayers(scope)) for (const [name, value] of pick(layer).entries()) merged.set(name, value);
+		return merged;
+	}
+	/**
+	* Attach one synchronous layer mutation to its registration context.
+	* @param ctx - context that determines both scope visibility and effect ownership.
+	* @param action - atomic mutation returning its synchronous undo.
+	* @param options - Cordis effect label and optional change notification.
+	* @returns the exact disposer returned by `ctx.effect()`.
+	*/
+	effect(ctx, action, options) {
+		const scope = scopeOf(ctx);
+		const notify = options.notify ?? true;
+		return ctx.effect(function* () {
+			let layer;
+			let created = false;
+			if (scope === void 0) layer = this.global;
+			else {
+				const existing = this.scoped.get(scope);
+				if (existing === void 0) {
+					layer = this.createLayer(scope);
+					this.scoped.set(scope, layer);
+					created = true;
+				} else layer = existing;
+			}
+			let undo;
+			try {
+				undo = action(layer);
+			} catch (error) {
+				if (scope !== void 0 && created && layer.isEmpty()) this.scoped.delete(scope);
+				throw error;
+			}
+			yield () => {
+				undo();
+				if (scope !== void 0 && layer.isEmpty()) this.scoped.delete(scope);
+				if (notify) this.onChange();
+			};
+			if (notify) this.onChange();
+		}.bind(this), options.label);
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Scoped-context primitive: mint a Cordis context that tags registrations with
+* an opaque identity and build routing-only event carriers for that identity.
+*
+* @module @liusiqi-dev/dsh-scope
+*/
+/** Context tag written by {@link createScope}. */
+const kScope = Symbol("dsh.scope");
+/** The key associated with each carrier. Presence distinguishes an unkeyed carrier from a non-carrier. */
+const carrierKeys = /* @__PURE__ */ new WeakMap();
+/**
+* The enclosing scope of each key. One relation powers both directions of
+* scope nesting: registration views inherit DOWN the chain (a child scope
+* sees its ancestors' layers — {@link ScopedLayers}), and event admission
+* extends UP it (a listener tagged with an ancestor receives events dispatched
+* to a descendant key — {@link scopeTarget}).
+*/
+const scopeParents = /* @__PURE__ */ new WeakMap();
+/** Cycle-checked write shared by the bind and every rebind. */
+function linkScopeParent(key, parent) {
+	for (let cursor = parent; cursor !== void 0; cursor = scopeParents.get(cursor)) if (cursor === key) throw new Error("dsh-scope: scope parent link would form a cycle");
+	scopeParents.set(key, parent);
+}
+/**
+* Bind `parent` as `key`'s enclosing scope, once.
+*
+* A key that already has a parent throws: there is no open re-link path, so a
+* scope's ancestry cannot be moved by anyone but the original binder, who
+* alone receives the {@link ScopeParentBinding}. A link that would close a
+* cycle is rejected, because every chain consumer walks parents to the root.
+* @param key - the child scope key.
+* @param parent - its enclosing scope key.
+* @returns the binding that alone may re-link this key.
+*/
+function bindScopeParent(key, parent) {
+	if (scopeParents.has(key)) throw new Error("dsh-scope: scope key is already bound to a parent; re-linking requires the binding returned by the original bind");
+	linkScopeParent(key, parent);
+	return { rebind(next) {
+		linkScopeParent(key, next);
+	} };
+}
+/**
+* Read one key's enclosing scope.
+* @param key - the scope key to inspect.
+* @returns its parent key, or `undefined` for a root scope.
+*/
+function scopeParentOf(key) {
+	return scopeParents.get(key);
+}
+/**
+* The chain from a key to its root ancestor.
+* @param key - the starting key, or `undefined` for the empty chain.
+* @returns keys nearest-first: `[key, parent, grandparent, …]`.
+*/
+function scopeChainOf(key) {
+	const chain = [];
+	for (let cursor = key; cursor !== void 0; cursor = scopeParents.get(cursor)) chain.push(cursor);
+	return chain;
+}
+/** Follow a Cordis fiber through asynchronous teardown even if its raw disposer was already claimed. */
+async function quiesceFiber(fiber) {
+	await Promise.resolve(fiber.dispose());
+	while (fiber.inertia !== void 0) await fiber.inertia;
+}
+/** Shared no-op plugin used as the backing scope fiber. */
+function scope() {}
+/**
+* Mint a scope under `ctx`. The scoped context inherits the minting plugin's
+* dependency API and owns every registration made through it.
+* @param ctx - active context whose dependency API the scope inherits.
+* @param key - opaque identity used for listener routing.
+* @param options - optional scope-chain placement.
+* @returns the scoped context and exact/shared disposal boundaries.
+*/
+function createScope(ctx, key, options) {
+	if (options?.parent !== void 0) bindScopeParent(key, options.parent);
+	const fiber = ctx.plugin(scope);
+	const scoped = fiber.ctx.extend({ [kScope]: key });
+	let disposing;
+	return {
+		ctx: scoped,
+		rawDispose: fiber.dispose,
+		dispose: () => disposing ??= quiesceFiber(fiber)
+	};
+}
+/**
+* Read the nearest scope tag inherited by a context.
+* @param ctx - context to inspect.
+* @returns its scope key, or `undefined` for an unscoped context.
+*/
+function scopeOf(ctx) {
+	return ctx[kScope];
+}
+/**
+* Build an opaque receiver that preserves the base filter, admits untagged
+* listeners globally, and admits tagged listeners for a matching key or any
+* of its ancestors ({@link bindScopeParent}): a listener owned by an enclosing
+* scope receives every descendant scope's events, which is what lets one
+* standing composition observe each of the agents composed under it. A tag
+* BELOW the dispatch key stays excluded — events flow up the chain, never
+* down.
+* @param base - subject or service whose existing Cordis filter is preserved.
+* @param key - routed scope identity, or `undefined` for an unscoped subject.
+* @returns a carrier whose subject remains available only through event arguments.
+*/
+function scopeTarget(base, key) {
+	const baseFilter = base[Context.filter];
+	const carrier = { [Context.filter](ctx) {
+		if (baseFilter !== void 0 && !baseFilter.call(base, ctx)) return false;
+		const tag = scopeOf(ctx);
+		if (tag === void 0) return true;
+		for (let cursor = key; cursor !== void 0; cursor = scopeParents.get(cursor)) if (cursor === tag) return true;
+		return false;
+	} };
+	carrierKeys.set(carrier, key);
+	return carrier;
+}
+/**
+* Test whether a value is a scope carrier.
+* @param value - dispatch receiver to inspect.
+* @returns whether {@link scopeTarget} created it.
+*/
+function isScopeCarrier(value) {
+	return typeof value === "object" && value !== null && carrierKeys.has(value);
+}
+/**
+* Read a carrier's routing key.
+* @param value - dispatch receiver to inspect.
+* @returns the carrier key, or `undefined` for an unkeyed/non-carrier value.
+*/
+function carrierKeyOf(value) {
+	if (!isScopeCarrier(value)) return void 0;
+	return carrierKeys.get(value);
+}
+//#endregion
+export { AnonymousEntries, NamedEntries, ScopedLayers, bindScopeParent, carrierKeyOf, createScope, isScopeCarrier, scopeChainOf, scopeOf, scopeParentOf, scopeTarget };

package/lib/invariant.js

@@ -0,0 +1,73 @@
+import { carrierKeyOf, isScopeCarrier } from "@liusiqi-dev/dsh-scope";
+//#region lib/types/scoped-events.generated.js
+/**
+* Generated scoped-event routing-subject resolvers for dsh-scope invariants.
+* Do not edit by hand; run `pnpm run gen-scoped-events`.
+*
+* @module @liusiqi-dev/dsh-scope/scoped-events.generated
+*/
+const scopedSubjectResolvers = Object.freeze({
+	"agent/assistant-stream": (args) => args[0]["agent"],
+	"agent/created": (args) => args[0]["agent"],
+	"agent/disposed": (args) => args[0]["agent"],
+	"agent/error": (args) => args[0]["agent"],
+	"agent/inbox/claimed": (args) => args[0]["agent"],
+	"agent/inbox/discarded": (args) => args[0]["agent"],
+	"agent/inbox/inserted": (args) => args[0]["agent"],
+	"agent/pre-step": (args) => args[0]["agent"],
+	"agent/request": (args) => args[0]["agent"],
+	"agent/request-error": (args) => args[0]["agent"],
+	"agent/status": (args) => args[0]["agent"],
+	"agent/turn-stopping": (args) => args[0]["agent"],
+	"approval/request": (args) => args[0]["agent"],
+	"goal/changed": (args) => args[0]["agent"],
+	"session/created": null,
+	"session/disposed": null,
+	"session/event": null,
+	"session/flush": null,
+	"subagent/end": null,
+	"subagent/start": null,
+	"system-prompt/assemble": (args) => args[1]["scope"],
+	"tools/execute": (args) => args[0]["agent"],
+	"tools/post-execute": (args) => args[0]["agent"],
+	"tools/pre-execute": (args) => args[0]["agent"],
+	"tools/ptc-dispatch-log": (args) => args[0]["agent"],
+	"tools/result": (args) => args[0]["agent"],
+	"user-questions/request": (args) => args[0]["agent"]
+});
+/**
+* Resolve the routing key named by one scoped event payload. A null
+* resolver means the payload cannot expose its external routing key, so the
+* invariant checks carrier presence only.
+* @param event - runtime Cordis event name.
+* @returns the generated subject resolver, null for presence-only,
+*   or undefined when the event is not scope-filtered.
+*/
+function scopedSubjectResolverFor(event) {
+	return scopedSubjectResolvers[event];
+}
+//#endregion
+//#region lib/types/invariant.js
+/** Package-owned scoped-dispatch invariants. @module @liusiqi-dev/dsh-scope/invariant */
+const PACKAGE_NAME = "@liusiqi-dev/dsh-scope";
+/** Cordis companion plugin name. */
+const name = "scope-invariant";
+/** Services required before the companion can register. */
+const inject = ["invariants"];
+/** Install the scoped-dispatch contribution into its child registration fiber. */
+const install = (ctx, fail) => {
+	ctx.on("internal/dispatch", (_mode, eventName, args, thisArg) => {
+		const subjectOf = scopedSubjectResolverFor(eventName);
+		if (subjectOf === void 0) return;
+		if (!isScopeCarrier(thisArg)) fail(`"${eventName}" is a scope-filtered event but was dispatched without a scope carrier — pass scopeTarget(base, subject) as the dispatch thisArg (agent events: use agentEvents(ctx, agent))`);
+		if (subjectOf !== null && carrierKeyOf(thisArg) !== subjectOf(args)) fail(`"${eventName}" was dispatched with a scope carrier keyed to a DIFFERENT subject than its arguments name — the carrier key and the event's subject must be the same object (use agentEvents(ctx, agent))`);
+	}, { global: true });
+};
+/**
+* Register the scope invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Scoped-context primitive: mint a Cordis context that tags registrations with
+ * an opaque identity and build routing-only event carriers for that identity.
+ *
+ * @module @liusiqi-dev/dsh-scope
+ */
+import type { Context } from '@liusiqi-dev/cordis';
+export { AnonymousEntries, NamedEntries, ScopedLayers } from './store.ts';
+export type { ScopeLayer } from './store.ts';
+/** An opaque, identity-compared scope key. */
+export type ScopeKey = object;
+declare const ScopedBrand: unique symbol;
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
+export type Scoped<T extends object> = object & {
+    readonly [ScopedBrand]: T;
+};
+/** The privileged handle to move one scope key's parent link. */
+export interface ScopeParentBinding {
+    /**
+     * Re-link the bound key to a different parent, with the same cycle check as
+     * the bind. Valid only while nothing produced under the old parent is
+     * retained — the blank-session recompose contract, which the holder upholds
+     * because this relation cannot see what a session logged.
+     * @param parent - the new enclosing scope key.
+     */
+    rebind(parent: ScopeKey): void;
+}
+/**
+ * Bind `parent` as `key`'s enclosing scope, once.
+ *
+ * A key that already has a parent throws: there is no open re-link path, so a
+ * scope's ancestry cannot be moved by anyone but the original binder, who
+ * alone receives the {@link ScopeParentBinding}. A link that would close a
+ * cycle is rejected, because every chain consumer walks parents to the root.
+ * @param key - the child scope key.
+ * @param parent - its enclosing scope key.
+ * @returns the binding that alone may re-link this key.
+ */
+export declare function bindScopeParent(key: ScopeKey, parent: ScopeKey): ScopeParentBinding;
+/**
+ * Read one key's enclosing scope.
+ * @param key - the scope key to inspect.
+ * @returns its parent key, or `undefined` for a root scope.
+ */
+export declare function scopeParentOf(key: ScopeKey): ScopeKey | undefined;
+/**
+ * The chain from a key to its root ancestor.
+ * @param key - the starting key, or `undefined` for the empty chain.
+ * @returns keys nearest-first: `[key, parent, grandparent, …]`.
+ */
+export declare function scopeChainOf(key: ScopeKey | undefined): ScopeKey[];
+/** A minted registration scope and its quiescent disposal boundaries. */
+export interface Scope {
+    /** Context through which scope-owned registrations are made. */
+    ctx: Context;
+    /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
+    rawDispose: () => Promise<void> | void;
+    /** Dispose every scope-owned registration; racing calls await the same completion. */
+    dispose(): Promise<void>;
+}
+/** Options accepted by {@link createScope}. */
+export interface CreateScopeOptions {
+    /** Enclosing scope bound via {@link bindScopeParent} before the scope is usable; the binding stays internal. */
+    parent?: ScopeKey;
+}
+/**
+ * Mint a scope under `ctx`. The scoped context inherits the minting plugin's
+ * dependency API and owns every registration made through it.
+ * @param ctx - active context whose dependency API the scope inherits.
+ * @param key - opaque identity used for listener routing.
+ * @param options - optional scope-chain placement.
+ * @returns the scoped context and exact/shared disposal boundaries.
+ */
+export declare function createScope(ctx: Context, key: ScopeKey, options?: CreateScopeOptions): Scope;
+/**
+ * Read the nearest scope tag inherited by a context.
+ * @param ctx - context to inspect.
+ * @returns its scope key, or `undefined` for an unscoped context.
+ */
+export declare function scopeOf(ctx: Context): ScopeKey | undefined;
+/**
+ * Build an opaque receiver that preserves the base filter, admits untagged
+ * listeners globally, and admits tagged listeners for a matching key or any
+ * of its ancestors ({@link bindScopeParent}): a listener owned by an enclosing
+ * scope receives every descendant scope's events, which is what lets one
+ * standing composition observe each of the agents composed under it. A tag
+ * BELOW the dispatch key stays excluded — events flow up the chain, never
+ * down.
+ * @param base - subject or service whose existing Cordis filter is preserved.
+ * @param key - routed scope identity, or `undefined` for an unscoped subject.
+ * @returns a carrier whose subject remains available only through event arguments.
+ */
+export declare function scopeTarget<T extends object>(base: T, key: ScopeKey | undefined): Scoped<T>;
+/**
+ * Test whether a value is a scope carrier.
+ * @param value - dispatch receiver to inspect.
+ * @returns whether {@link scopeTarget} created it.
+ */
+export declare function isScopeCarrier(value: unknown): value is Scoped<object>;
+/**
+ * Read a carrier's routing key.
+ * @param value - dispatch receiver to inspect.
+ * @returns the carrier key, or `undefined` for an unkeyed/non-carrier value.
+ */
+export declare function carrierKeyOf(value: unknown): ScopeKey | undefined;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned scoped-dispatch invariants. @module @liusiqi-dev/dsh-scope/invariant */
+import type { Context } from '@liusiqi-dev/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "scope-invariant";
+/** Services required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register the scope invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/scoped-events.generated.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generated scoped-event routing-subject resolvers for dsh-scope invariants.
+ * Do not edit by hand; run `pnpm run gen-scoped-events`.
+ *
+ * @module @liusiqi-dev/dsh-scope/scoped-events.generated
+ */
+type ScopedSubjectResolver = (args: readonly unknown[]) => unknown;
+/**
+ * Resolve the routing key named by one scoped event payload. A null
+ * resolver means the payload cannot expose its external routing key, so the
+ * invariant checks carrier presence only.
+ * @param event - runtime Cordis event name.
+ * @returns the generated subject resolver, null for presence-only,
+ *   or undefined when the event is not scope-filtered.
+ */
+export declare function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined;
+export {};
+//# sourceMappingURL=scoped-events.generated.d.ts.map

package/lib/types/store.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Shared insertion-ordered storage and effect ownership for scope-aware registries.
+ *
+ * @module @liusiqi-dev/dsh-scope
+ */
+import type { Context } from '@liusiqi-dev/cordis';
+import type { ScopeKey } from './index.ts';
+/** One scope's aggregate contribution to a registry. */
+export interface ScopeLayer {
+    /** Whether every table in this layer is empty. */
+    isEmpty(): boolean;
+}
+/** Internal common read contract for the two entry-table implementations. */
+interface EntryValues<V> {
+    values(): IterableIterator<V>;
+    isEmpty(): boolean;
+}
+/**
+ * Insertion-ordered named entries with caller-owned duplicate diagnostics.
+ *
+ * Values are borrowed. Iterators are live within one nonempty table
+ * generation; draining the table detaches them from later insertions. Each
+ * successful insertion returns an idempotent undo for that exact entry.
+ */
+export declare class NamedEntries<V> implements EntryValues<V> {
+    private readonly duplicateError;
+    private data;
+    constructor(duplicateError: (name: string) => Error);
+    /**
+     * Insert one unique name.
+     * @param name - name unique within this table.
+     * @param value - borrowed value to retain.
+     * @returns an idempotent undo that removes only this insertion.
+     */
+    insert(name: string, value: V): () => void;
+    /**
+     * Read one named value.
+     * @param name - name to resolve.
+     * @returns the retained value, or `undefined` when absent.
+     */
+    get(name: string): V | undefined;
+    /**
+     * Test one name for membership.
+     * @param name - name to test.
+     * @returns whether the table contains that name.
+     */
+    has(name: string): boolean;
+    /**
+     * Iterate live names in insertion order.
+     * @returns the native live key iterator.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Iterate live entries in insertion order.
+     * @returns the native live entry iterator.
+     */
+    entries(): IterableIterator<[string, V]>;
+    /**
+     * Iterate live values in insertion order.
+     * @returns the native live value iterator.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Test whether this table has no entries.
+     * @returns whether the table is empty.
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Insertion-ordered anonymous entries with independent registration identity.
+ *
+ * Equal values remain separate registrations. Values are borrowed, and
+ * iterators are live within one nonempty table generation; draining the table
+ * detaches them from later appends.
+ */
+export declare class AnonymousEntries<V> implements EntryValues<V> {
+    private data;
+    /**
+     * Append one independently owned value.
+     * @param value - borrowed value to retain.
+     * @returns an idempotent undo for this exact append.
+     */
+    append(value: V): () => void;
+    /**
+     * Iterate live values in insertion order.
+     * @returns the native live value iterator.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Test whether this table has no entries.
+     * @returns whether the table is empty.
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Own the global and exact-scope layers for one registry.
+ *
+ * Reads never create scoped layers. Registrations derive both visibility and
+ * effect ownership from the supplied Cordis context, collect undo before
+ * notification, and reclaim only a completely empty aggregate layer.
+ */
+export declare class ScopedLayers<L extends ScopeLayer> {
+    private readonly createLayer;
+    private readonly onChange;
+    /** The eagerly constructed context-global layer. */
+    readonly global: L;
+    private readonly scoped;
+    constructor(createLayer: (scope: ScopeKey | undefined) => L, onChange: () => void);
+    /**
+     * Read an existing exact-scope overlay. Deliberately chain-blind: callers
+     * addressing one scope's OWN contributions (its restrictions, its guards)
+     * must not silently pick up an ancestor's — use {@link chainLayers} where
+     * inheritance is the point.
+     * @param scope - exact scope key; `undefined` denotes no overlay.
+     * @returns the existing scoped layer, or `undefined` without creating one.
+     */
+    peek(scope: ScopeKey | undefined): L | undefined;
+    /**
+     * Existing overlays along the scope's parent chain ({@link scopeChainOf}),
+     * farthest ancestor first and the exact scope last, so a caller layering
+     * them in order gives the nearest scope the final word.
+     * @param scope - viewing scope, or `undefined` for no overlays.
+     * @returns the existing layers, nearest last; absent overlays are skipped.
+     */
+    chainLayers(scope: ScopeKey | undefined): L[];
+    /**
+     * Materialize global named entries followed by scope-chain shadows,
+     * farthest ancestor first, so the nearest scope's entry wins a name.
+     * @param scope - viewing scope, or `undefined` for the global view.
+     * @param pick - select the named table from a layer.
+     * @returns an insertion-ordered effective map.
+     */
+    merge<V>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<V>): Map<string, V>;
+    /**
+     * Attach one synchronous layer mutation to its registration context.
+     * @param ctx - context that determines both scope visibility and effect ownership.
+     * @param action - atomic mutation returning its synchronous undo.
+     * @param options - Cordis effect label and optional change notification.
+     * @returns the exact disposer returned by `ctx.effect()`.
+     */
+    effect(ctx: Context, action: (layer: L) => () => void, options: {
+        label: string;
+        notify?: boolean;
+    }): () => void;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@liusiqi-dev/dsh-scope",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@liusiqi-dev/dsh-invariants": "1.0.0",
+    "@liusiqi-dev/cordis": "~4.0.4"
+  },
+  "devDependencies": {
+    "@liusiqi-dev/dsh-invariants": "1.0.0",
+    "@liusiqi-dev/cordis": "~4.0.4"
+  }
 }