@hasna-internal/kai-scope 0.1.1-rc.2 → 0.1.1-rc.3

package/README.md

@@ -1,37 +1,3 @@
-# dsh-scope
+# @hasna-internal/kai-scope
 
-English | [中文](README.zh.md)
-
-Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis context whose backing fiber owns every registration made through it. `scopeOf(ctx)` reads the tag, and `scopeTarget(base, key)` routes scoped events to listeners with the same key while leaving unscoped listeners global. Keys form an optional parent chain (`bindScopeParent`): registration views inherit DOWN it — a child scope sees its ancestors' layers, nearest shadowing farthest — and event admission extends UP it — a listener tagged with an ancestor receives a descendant key's events, never the reverse. The agent loop creates one scope per live agent and an agent preset's standing mount is a parent scope over its agents, but the mechanism is key-agnostic so lower-level packages can use it without depending on either.
-
-## Public API
-
-- `createScope(ctx: Context, key: ScopeKey, options?): Scope` Mint a scope under `ctx`'s fiber. Usable synchronously (effect collection is uid-gated; service resolution falls through to the minting plugin's dependency surface). The typed, same-process key is trusted; an inactive minting context still fails through Cordis (`INACTIVE_EFFECT`). `options.parent` binds the enclosing scope via `bindScopeParent` before the scope is usable; the binding stays internal.
-- `bindScopeParent(key, parent): ScopeParentBinding` / `scopeParentOf(key)` / `scopeChainOf(key)` The parent relation behind both chain directions. Binding is once: a key that already has a parent throws, and only the returned binding's `rebind(parent)` may re-link it — the blank-session recompose operation, valid only while nothing produced under the old parent is retained (the holder's contract — this relation cannot see what a session logged). Both the bind and every rebind reject a link closing a cycle. `scopeChainOf` returns `[key, parent, …]` nearest-first.
-- `Scope.ctx` The tagged context: registrations through it are scope-visible AND scope-lifetime. Derived contexts (an `extend`, a fiber mounted under it) inherit the tag; nested scopes shadow (nearest tag wins).
-- `Scope.rawDispose` The EXACT Cordis disposer for the backing fiber — a composite (generator) effect yields THIS function to nest the scope's teardown at that yield position (Cordis dedupes nested effects by function identity; yielding a wrapper leaves the scope disposing as a concurrent sibling).
-- `Scope.dispose(): Promise<void>` Idempotent, shared quiescence boundary for every registration made through the scope. Racing/repeat calls await the same teardown, including when `rawDispose` invoked the underlying single-shot Cordis disposer first.
-- `scopeOf(ctx: Context): ScopeKey | undefined` The tag a context (or any context derived from it) carries; `undefined` = context-global.
-- `scopeTarget(base: T, key: ScopeKey | undefined): Scoped<T>` Build the opaque dispatch `thisArg` for a scope-filtered event. It composes `base`'s existing `Context.filter` with the scope predicate (untagged listener ⇒ admitted; tagged ⇒ admitted iff its tag is the key or an ancestor of it; `key === undefined` ⇒ untagged only). The carrier contains routing state only; the real subject is carried by the event arguments. `{ global: true }` listeners bypass filtering (Cordis semantics).
-- `Scoped<T>` The compile-time opaque carrier brand: scope-filtered events demand it as their `this` type, so dispatching with a bare subject is a compile error. The type parameter records the subject type but does not expose its properties.
-- `isScopeCarrier(value)` / `carrierKeyOf(value)` Runtime carrier marks, used by the dev invariants to assert every scope-filtered dispatch carries a carrier keyed to the subject its arguments name.
-- `ScopeLayer` Aggregate contract for one registry's complete global or exact-scope contribution; `isEmpty()` controls scoped-layer reclamation.
-- `ScopedLayers<L>` Own one eager global layer and lazy exact-scope layers. `peek()` never creates and stays chain-blind (a scope's OWN contributions — restrictions, guards — must not silently pick up an ancestor's), `chainLayers()` returns existing overlays farthest-ancestor-first, `merge()` materializes insertion-ordered named shadows along the chain, and `effect()` derives visibility and ownership from the same context while returning the exact Cordis disposer.
-- `NamedEntries<V>` Insertion-ordered named storage with caller-owned duplicate diagnostics, lookup, and live iteration within one nonempty table generation; draining the table detaches existing iterators from later insertions, and `insert()` returns an idempotent exact-entry undo.
-- `AnonymousEntries<V>` Insertion-ordered anonymous storage whose unique internal keys keep equal values as independent registrations; it uses the same drained-generation iterator boundary, and `append()` returns an idempotent exact-entry undo.
-
-The optional `@hasna-internal/kai-scope/invariant` companion owns that runtime assertion. It uses the generated `scoped-events.generated.ts` resolver map to require a carrier for every declared scoped event and, when the payload exposes its routing subject, require identity with the carrier key. The Program-backed generator derives the map from event declarations and real `scopeTarget(base, key)` calls.
-
-## Design contract
-
-The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals) for rationale and security non-goals.
-
-Scope-aware services define a concrete `ScopeLayer` that aggregates their heterogeneous tables and domain helpers. `ScopedLayers.effect()` accepts one synchronous action returning one synchronous undo, installs that undo before optional notification, and reclaims an exact-scope layer only when the complete aggregate is empty. `notify` defaults to `true`; the supplied callback owns whether observer failures throw or are contained. `EntryValues` remains internal, the storage classes are imported from the package root rather than a `/store` subpath, and the shared storage does not define registry-specific filtering or iteration policy. See the [shared scoped-layer storage Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md).
-
-Handing out a scoped context hands out the minting plugin's service-resolution API (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.
-
-## Known Limitations and Deferred Work
-
-- **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.
+This package has been retired by its owner. This release is an empty placeholder with no dependencies or supported functionality. Do not use it.

package/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = {};

package/package.json

@@ -1,42 +1,16 @@
 {
   "name": "@hasna-internal/kai-scope",
-  "description": "Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness",
-  "version": "0.1.1-rc.2",
-  "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"
-  },
+  "version": "0.1.1-rc.3",
+  "description": "Retired package. Empty placeholder with no dependencies.",
+  "main": "index.js",
   "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts"
+    "index.js",
+    "README.md"
   ],
   "license": "MIT",
-  "peerDependencies": {
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  "deprecated": "Retired by the package owner. Empty placeholder; do not use.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 DeepSeek
-
-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

@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/core/scope/README.md
-README.md: 1ed09acd7ccb864b16fb5d2ac4390264085d1c9e
-README.zh.md: 54edab0be7703a9ead64b42b617ab3ba2f69b7e3

package/README.zh.md

@@ -1,37 +0,0 @@
-# dsh-scope
-
-[English](README.md) | 中文
-
-带作用域的注册原语。`createScope(ctx, key)` 创建一个带标签的 Cordis 上下文，其底层 fiber 拥有通过该上下文进行的每项注册。`scopeOf(ctx)` 读取标签；`scopeTarget(base, key)` 将带作用域的事件路由到键相同的监听器，同时让无作用域监听器保持全局可见。键可以构成可选的父链（`bindScopeParent`）：注册视图沿链**向下**继承——子作用域看得见祖先各层，近者遮蔽远者——事件放行沿链**向上**扩展——标签为祖先的监听器能收到子孙键的事件，反向永不成立。agent loop（智能体循环）为每个存活的 agent 创建一个作用域，agent preset 的常驻挂载则是其 agent 们的父作用域，但该机制与键的具体含义无关，底层包无需依赖两者即可使用。
-
-## 公开 API
-
-- `createScope(ctx: Context, key: ScopeKey, options?): Scope`：在 `ctx` 的 fiber 下创建作用域。可以同步使用（effect 收集受 uid 门禁约束；服务解析会沿创建该作用域的插件依赖范围继续查找）。同进程、带类型的键受信任；处于非活动状态的创建上下文仍会通过 Cordis 失败（`INACTIVE_EFFECT`）。`options.parent` 在作用域可用之前经 `bindScopeParent` 绑定其外围作用域；绑定句柄不外泄。
-- `bindScopeParent(key, parent): ScopeParentBinding` / `scopeParentOf(key)` / `scopeChainOf(key)`：支撑两条链方向的父关系。绑定仅此一次：已有父级的键直接抛错，只有返回的绑定句柄的 `rebind(parent)` 才能重新绑定父级——即空白会话 recompose 的操作，仅当旧父之下产出的东西一概不被保留时才合法（这是持有方的约定——该关系看不见会话记录了什么）。绑定与每次 rebind 都拒绝会闭环的链接。`scopeChainOf` 返回 `[key, parent, …]`，最近者在前。
-- `Scope.ctx`：带标签的上下文。通过它进行的注册既具备作用域可见性，也服从作用域生命周期。派生上下文（一次 `extend`、挂载于其下的 fiber）继承标签；嵌套作用域会遮蔽外层标签（最近的标签生效）。
-- `Scope.rawDispose`：底层 fiber 的确切 Cordis disposer。组合式（generator）effect 会 yield 此函数，从而把作用域 teardown 嵌套在该 yield 位置（Cordis 按函数标识去重嵌套 effect；yield 一个包装函数会使作用域 teardown 成为并行的同级操作）。
-- `Scope.dispose(): Promise<void>`：通过作用域进行的每项注册所共用的幂等完全停稳边界。竞态调用或重复调用会等待同一次 teardown；即使 `rawDispose` 先调用了底层单次 Cordis disposer 也是如此。
-- `scopeOf(ctx: Context): ScopeKey | undefined`：上下文或其任意派生上下文携带的标签；`undefined` 表示上下文全局。
-- `scopeTarget(base: T, key: ScopeKey | undefined): Scoped<T>`：为按作用域筛选的事件构造不透明分发 `thisArg`。它把 `base` 现有的 `Context.filter` 与作用域谓词组合起来（无标签监听器 ⇒ 放行；有标签监听器 ⇒ 仅当标签 === key，或标签为 key 的祖先时放行；`key === undefined` ⇒ 仅放行无标签监听器）。载体只包含路由状态；真实主体由事件参数携带。带 `{ global: true }` 的监听器绕过筛选（Cordis 语义）。
-- `Scoped<T>`：编译期不透明载体 brand。按作用域筛选的事件要求它作为 `this` 类型，因此使用裸主体分发会产生编译错误。类型参数记录主体类型，但不公开其属性。
-- `isScopeCarrier(value)`/`carrierKeyOf(value)`：运行时载体标记，开发不变式使用它们断言每次按作用域筛选的分发都携带载体，而且载体键与参数所指名的主体一致。
-- `ScopeLayer`：一个注册表的完整全局贡献或精确作用域贡献的聚合约定；`isEmpty()` 控制带作用域层的回收。
-- `ScopedLayers<L>`：持有一个立即构造的全局层与惰性的精确作用域层。`peek()` 从不创建且刻意不看链（某作用域**自己**的贡献——限制、守卫——不得悄悄继承祖先的），`chainLayers()` 按最远祖先在前返回已存在的各层，`merge()` 沿链物化按插入序的具名遮蔽，`effect()` 从同一上下文推导可见性与所有权，并返回精确的 Cordis disposer。
-- `NamedEntries<V>`：按插入顺序排列的具名存储，调用方拥有重复项诊断、查找，以及一个非空表世代内的实时迭代。表清空后，现有迭代器与后续插入项脱离；`insert()` 返回幂等的精确条目撤销函数。
-- `AnonymousEntries<V>`：按插入顺序排列的匿名存储；唯一内部键使相同值仍作为独立注册存在。它使用相同的清空世代迭代器边界；`append()` 返回幂等的精确条目撤销函数。
-
-可选配套包 `@hasna-internal/kai-scope/invariant` 拥有该运行时断言。它使用生成的 `scoped-events.generated.ts` 解析器映射，要求每个已声明的带作用域事件都携带载体；当 payload 公开路由主体时，还要求路由主体与载体键严格相等。基于 Program 的生成器根据事件声明和真实的 `scopeTarget(base, key)` 调用生成该映射。
-
-## 设计约定
-
-注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md#security-and-authority-are-non-goals)。
-
-感知作用域的服务会定义具体 `ScopeLayer`，聚合各自不同的表与领域辅助函数。`ScopedLayers.effect()` 接受一个返回同步撤销函数的同步动作，在可选通知前安装该撤销函数，并且只有在完整聚合为空时才回收精确作用域层。`notify` 默认为 `true`；由所提供的回调决定观测方失败是向外抛出还是在内部处理。`EntryValues` 保持内部可见；存储类从包根而非 `/store` 子路径导入；共享存储不定义注册表专属的筛选或迭代策略。详见[共享作用域层存储 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md)。
-
-交出带作用域的上下文，也会交出创建该上下文的插件的服务解析范围（解析会沿创建者 fiber 的依赖链，而非持有者的依赖链行进），因此应由具备这些带作用域注册所需依赖的插件来创建它。
-
-## 已知限制与暂缓事项
-
-- **只有感知作用域的表层才会隔离状态**：注册表必须按 `scopeOf()` 归档，事件必须通过 `scopeTarget()` 分发；仅仅通过带作用域的上下文调用任意 Cordis 服务，并不会改变该服务仍为上下文全局这一事实。
-- **一个上下文只携带一个最近的作用域键**：层级关系存在于键级父关系中而非上下文标签里；嵌套作用域**上下文**仍遮蔽为单一标签，多成员策略集仍不受支持。
-- **服务可达性来自作用域创建者**：交出 `Scope.ctx` 也会交出创建插件注入的服务范围，因此，若作用域创建者提供的服务范围较宽，持有者之后也无法将其收窄。

package/lib/index.js

@@ -1,357 +0,0 @@
-import { Context } from "@deepseek-ai/cordis";
-//#region lib/types/store.js
-/**
-* Shared insertion-ordered storage and effect ownership for scope-aware registries.
-*
-* @module @hasna-internal/kai-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 @hasna-internal/kai-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

@@ -1,72 +0,0 @@
-import { carrierKeyOf, isScopeCarrier } from "@hasna-internal/kai-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 @hasna-internal/kai-scope/scoped-events.generated
-*/
-const scopedSubjectResolvers = Object.freeze({
-	"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/session-start": (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/code-dispatch-log": (args) => args[0]["agent"],
-	"tools/execute": (args) => args[0]["agent"],
-	"tools/post-execute": (args) => args[0]["agent"],
-	"tools/pre-execute": (args) => args[0]["agent"],
-	"tools/result": (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 @hasna-internal/kai-scope/invariant */
-const PACKAGE_NAME = "@hasna-internal/kai-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

@@ -1,110 +0,0 @@
-/**
- * Scoped-context primitive: mint a Cordis context that tags registrations with
- * an opaque identity and build routing-only event carriers for that identity.
- *
- * @module @hasna-internal/kai-scope
- */
-import type { Context } from '@deepseek-ai/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

@@ -1,13 +0,0 @@
-/** Package-owned scoped-dispatch invariants. @module @hasna-internal/kai-scope/invariant */
-import type { Context } from '@deepseek-ai/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

@@ -1,18 +0,0 @@
-/**
- * Generated scoped-event routing-subject resolvers for dsh-scope invariants.
- * Do not edit by hand; run `pnpm run gen-scoped-events`.
- *
- * @module @hasna-internal/kai-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

@@ -1,147 +0,0 @@
-/**
- * Shared insertion-ordered storage and effect ownership for scope-aware registries.
- *
- * @module @hasna-internal/kai-scope
- */
-import type { Context } from '@deepseek-ai/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