dsh-plugin-dev-kb 1.0.0

package/kb/site/en/reference/subsystems/sandbox.md

@@ -0,0 +1,221 @@
+---
+editSource: "docs/subsystems/sandbox.md"
+outline: [2,3]
+---
+
+# Process Sandbox
+
+The process-sandbox seam of [dsh-sandbox](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/sandbox/sandbox) wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. [dsh-sandbox-local](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/sandbox/sandbox-local) supplies Linux bwrap/Landlock, macOS Seatbelt, and the Windows ACL restricted-token backend; [dsh-bash-sandbox](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/bash-sandbox) and [dsh-pwsh-sandbox](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/pwsh-sandbox) consume it. Containers, microVMs, and remote execution are sibling implementations of whole capability seams, not providers of `ctx.sandbox`.
+
+Source: [`packages/sandbox/sandbox/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts)
+
+## Modes and enforcement
+
+`SandboxMode` governs filesystem effects only. `read-only` asks the backend to deny writes — the POSIX runners additionally grant the `/dev/null` sink their shells require, while the Windows ACL runner grants no explicit writable root and reports partial enforcement for its ambient ACL gaps; `workspace-write` permits writes under the workspace root and the backend's promised temp area; `danger-full-access` bypasses confinement. Network and process visibility are outside this vocabulary.
+
+```ts type-equiv
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
+type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
+```
+
+Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`.
+
+```ts type-equiv
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
+type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
+```
+
+Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction. Older Landlock ABIs and the Windows ACL runner's Everyone/hard-link boundaries are current partial cases.
+
+```ts type-equiv
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
+type SandboxEnforcement = 'full' | 'partial'
+```
+
+## Per-call policy
+
+The complete execution policy is resolved and carried per capability call. It includes `danger-full-access` so a consumer can resolve policy once before deciding whether to bypass confinement. Normal tool calls derive `workspaceRoot` from the calling session's immutable cwd; deployment configuration is the agentless fallback. The root is canonicalized with filesystem semantics before lexical normalization, so a cwd containing `symlink/..` identifies the directory where a spawned process actually runs.
+
+```ts type-equiv
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+interface SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: SandboxMode
+  /** Absolute root directory `workspace-write` may write under. */
+  workspaceRoot: string
+  /**
+   * Opaque identity of the calling session (the branded `dsh-session`
+   * SessionId). Backends key per-session state off it (e.g. windows-acl gives
+   * each live session/workspace pair a random private temp directory and SID,
+   * while the workspace SID and standing grant remain per-workspace); absent
+   * for agentless calls, which fall back to per-call backend state.
+   */
+  sessionId?: SessionId
+}
+```
+
+`ctx.sandboxPolicy.resolve()` accepts the active session and, for an approved retry, an explicit mode. The service owns precedence and root fallback so bash and fs do not repeat it.
+
+```ts type-equiv
+/** Inputs that select the sandbox policy for one capability call. */
+interface SandboxPolicyRequest {
+  /** Calling session; its immutable cwd becomes the workspace boundary. */
+  session?: Session
+  /** Explicit approved mode override, which outranks session policy. */
+  mode?: SandboxMode
+}
+```
+
+Only a confined execution reaches `ctx.sandbox`; its provider policy narrows the mode while retaining the same root. This permits concurrent sessions, consumers, and one-shot escalated retries to ask the same provider for different boundaries without mutating provider state.
+
+```ts type-equiv
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
+ */
+interface SandboxPolicy extends SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: ConfinedSandboxMode
+}
+```
+
+## Wrapped argv and classification dialects
+
+`RunnerFailureRule` combines evidence that a runner failed before executing the command. A consumer requires a nonzero exit, the optional allowed-exit-code gate, and a case-insensitive fatal signature within one remaining stderr line. Case-insensitive exact full-line informational exclusions are removed first, so a benign runner notice cannot prove failure by itself. The matched line remains available as error detail; classification does not rewrite stderr.
+
+```ts type-equiv
+/**
+ * Evidence that identifies a sandbox runner failing before it executes the
+ * wrapped command. A consumer first applies {@link allowedExitCodes} when
+ * present, removes {@link informationalLines} by case-insensitive exact line
+ * equality, then matches {@link fatalSignatures} case-insensitively within
+ * each remaining stderr line. Exit status alone never proves runner failure.
+ */
+interface RunnerFailureRule {
+  /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
+  allowedExitCodes?: readonly number[]
+  /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
+  fatalSignatures: readonly string[]
+  /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
+  informationalLines?: readonly string[]
+}
+```
+
+`ConfinedArgv` is what the consumer spawns. Besides the replacement argv, it carries the backend's enforcement fact and two orthogonal stderr classifiers. `denialSignatures` identify the confined command being blocked while the sandbox works correctly. `runnerFailureRules` identify the sandbox runner refusing or failing before it executes the command; consumers check these first and surface a sandbox infrastructure failure, never an ordinary task failure.
+
+```ts type-equiv
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
+interface ConfinedArgv {
+  /** The wrapped argv (runner, profile, separator, then the caller's argv). */
+  argv: string[]
+  /** How completely the selected backend enforces the policy's file effects. */
+  enforcement: SandboxEnforcement
+  /**
+   * The selected backend's denial DIALECT: the case-insensitive stderr
+   * substrings a file effect denied by THIS backend produces (EROFS text
+   * under bwrap's read-only binds, EACCES under Landlock, EPERM under
+   * Seatbelt). A consumer that infers denials from a failed run's stderr
+   * matches against exactly these rather than a cross-backend union — the
+   * union claims denials a given backend never produces.
+   */
+  denialSignatures: readonly string[]
+  /**
+   * Structured runner-failure evidence rules. Consumers require a matching
+   * fatal stderr line (after informational exclusions) and any rule-specific
+   * exit-code gate before checking denial signatures: runner failure means the
+   * command never ran, while denial means confinement worked and blocked it.
+   */
+  runnerFailureRules: readonly RunnerFailureRule[]
+}
+```
+
+The [local provider](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox-local/README.md) owns operator configuration and maps its runner dialect into these rules. The [sandboxed bash consumer](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/shell/bash-sandbox/README.md) owns spawn and result attribution.
+
+## Provider and fail-closed errors
+
+`ctx.sandbox.confine(argv, policy)` returns a `ConfinedArgv` or throws `SandboxUnavailableError` with code `SANDBOX_UNAVAILABLE` when no usable backend exists. Consumers may also classify a failure while spawning or observing the returned argv; that attribution belongs to the consumer contract. Silent unconfined passthrough is never legal for a confined policy.
+
+Provider selection, probing, caching, and backend-specific enforcement reports belong to the [local provider](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox-local/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+
+Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
+
+```ts cordis-catalog
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
+abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
+```
+
+Source: [`packages/sandbox/sandbox/src/index.ts:158`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts)
+
+<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
+
+### `ctx.sandboxPolicy` — `SandboxPolicyService`
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
+
+```ts cordis-catalog
+/**
+ * Resolve the complete policy for one capability call. An approved explicit
+ * mode outranks the session's last `sandbox/mode` event, which outranks the
+ * deployment default. A session cwd is its workspace-write boundary; the
+ * configured root is the fallback for agentless calls and sessions without a
+ * cwd.
+ * @param request - optional session and approved mode override.
+ * @returns the fully resolved per-call mode and absolute workspace root.
+ */
+resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
+
+/**
+ * Read the session override without applying the deployment default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged mode, or `undefined` without one.
+ */
+overrideOf(session: Session): SandboxMode | undefined
+```
+
+Types: [Session](./session.md)
+
+Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/schedule.md

@@ -0,0 +1,189 @@
+---
+editSource: "docs/subsystems/schedule.md"
+outline: [2,3]
+---
+
+# Session-local Schedule
+
+Schedule owns durable reminders that return to the original live Session as ordinary later conversation turns. The [durable Schedule Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md) owns the persistence and lifecycle decisions, [conversational delivery](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/simplification/2026-08-09-conversational-schedule-delivery.md) owns the no-receipt boundary, the [explicit time-zone boundary](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md) owns browser-local interpretation, and [bounded fixed-rate Schedule](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/simplification/2026-08-09-bounded-fixed-rate-schedule.md) owns recurrence. This page records the durable and model-facing shapes from [`packages/schedule/schedule/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/schedule/schedule/src/types.ts); the [package README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/schedule/schedule/README.md) owns composition, tool behavior, and the exact reminder framing.
+
+## Durable records
+
+`ScheduleId` is a [branded id](./core.md#branded-ids), unique and never reused within one Session. Version 1 supports a positive safe-integer `after_seconds` delay, an explicit absolute `at` target, or a safe-integer `every_seconds` interval of at least five minutes. Creation canonicalizes every first target into a four-digit-year RFC 3339 UTC `scheduledAt`; an `after` record retains its submitted delay, an `at` record stores only the resulting instant, and an `every` record retains its fixed interval and next target.
+
+```ts type-equiv
+/** Durable one-shot reminder created from a positive delay. */
+interface AfterScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for a delayed one-shot reminder. */
+  readonly kind: 'after'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Positive safe-integer delay accepted at creation. */
+  readonly afterSeconds: number
+  /** Four-digit-year RFC 3339 UTC target. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** Durable one-shot reminder created from an absolute instant. */
+interface AtScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for an absolute one-shot reminder. */
+  readonly kind: 'at'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Four-digit-year RFC 3339 UTC target. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** Durable fixed-rate reminder whose next target remains creation-anchor-aligned. */
+interface EveryScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for a fixed-rate recurring reminder. */
+  readonly kind: 'every'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Fixed safe-integer interval, never below five minutes. */
+  readonly everySeconds: number
+  /** Earliest anchor-aligned occurrence not yet dispatched. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** One-shot record variants that terminate on an id-only dispatch. */
+type OneShotScheduleRecord = AfterScheduleRecord | AtScheduleRecord
+```
+
+```ts type-equiv
+/** The v1 durable reminder record union. */
+type ScheduleRecord = OneShotScheduleRecord | EveryScheduleRecord
+```
+
+## Absolute-time input
+
+The `at` selector is either a strict offset-bearing RFC 3339 string or an exact local-calendar object. The local form keeps its interpretation explicit at the tool boundary:
+
+```ts type-equiv
+/** Structured local-calendar input accepted by `schedule_create`. */
+interface LocalAtInput {
+  /** Four-digit ISO calendar date. */
+  readonly date: string
+  /** Local wall-clock time with optional one-to-three digit milliseconds. */
+  readonly time: string
+  /** Explicit UTC or IANA Area/Location zone. */
+  readonly time_zone: string
+}
+```
+
+```ts type-equiv
+/** Absolute selector accepted by `schedule_create`. */
+type AtInput = string | LocalAtInput
+```
+
+The official Web overlay samples the browser's IANA zone for every prompt. Time-context tells the model to interpret otherwise-unqualified natural-language dates and times in that request-local zone when the open turn has one unambiguous browser zone; mixed or missing provenance tells the model to ask. That guidance is not a durable Session default: the model must still pass an offset in the string form or `time_zone` in the local form, and Schedule never reads browser, Session, process, or model context.
+
+Schedule rejects invalid offsets and zones, offset-free strings, non-future targets, and local times inside daylight-saving gaps. A daylight-saving overlap chooses its first, earlier instant. Successful creation stores only canonical UTC `scheduledAt`, so replay never depends on ambient time-zone state.
+
+## Fixed-rate input and catch-up
+
+`every_seconds` is a per-record interval of at least 300 seconds, anchored to creation time. It is fixed-rate recurrence only: the protocol has no calendar or Cron expression, recurrence time zone, shared cooldown, or cross-record admission gate.
+
+When a Session was cold or busy across several targets, one Every record contributes only its latest due occurrence. The dispatch advances it directly to the first creation-anchor-aligned target after the dispatch decision time, without enumerating, persisting, or replaying missed intervals. If that next target cannot fit in a four-digit UTC year, the final dispatch terminates the record.
+
+When multiple distinct Every records are overdue and no one-shot is due, each contributes one occurrence to the same follow-up batch in target and creation order. Every record keeps independent state, while all dispatches in that admitted batch use the same decision time. Batching bounds model turns; the five-minute minimum bounds each record's timer frequency.
+
+## Durable changes and replay
+
+The version-1 `schedule/change` Session event is the only durable Schedule authority. Create stores the complete record, and delete is a terminal id-only transition. A one-shot dispatch is also terminal and id-only. An Every dispatch carries the wall-clock decision time used to select its latest due occurrence and normally advances the active record instead of terminating it. Dispatch means the follow-up was synchronously queued, not that a model answer succeeded or the user read it.
+
+```ts type-equiv
+/** Creates one durable reminder record. */
+interface ScheduleCreateChange {
+  readonly version: 1
+  readonly operation: 'create'
+  readonly schedule: ScheduleRecord
+}
+```
+
+```ts type-equiv
+/** Deletes one currently active reminder. */
+interface ScheduleDeleteChange {
+  readonly version: 1
+  readonly operation: 'delete'
+  readonly id: ScheduleId
+}
+```
+
+```ts type-equiv
+/** Records that one active one-shot reminder entered the durable dispatch history. */
+interface OneShotScheduleDispatchChange {
+  readonly version: 1
+  readonly operation: 'dispatch'
+  readonly id: ScheduleId
+}
+```
+
+```ts type-equiv
+/** Records one fixed-rate decision and advances directly past missed occurrences. */
+interface EveryScheduleDispatchChange {
+  readonly version: 1
+  readonly operation: 'dispatch'
+  readonly id: ScheduleId
+  /** Wall-clock decision time used to select the latest due occurrence. */
+  readonly acceptedAt: string
+}
+```
+
+```ts type-equiv
+/** Durable dispatch shapes supported by the current rule set. */
+type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange
+```
+
+```ts type-equiv
+/** Strict version-1 durable Schedule mutation union. */
+type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
+```
+
+The strict decoder and fold reject unknown versions, extra fields, reused ids, mismatched one-shot or Every dispatch shapes, and delete or dispatch transitions against inactive records. A normal Session folds its complete event stream. A fork folds only events at or after `SessionHeader.seedLength`, so it retains history without adopting the parent Session's active reminders. The `schedule/change` declaration and source location are also indexed in the [persistence catalog](../persistence-catalog.md#schedulechange--log-only).
+
+## Active views and management
+
+Tool values combine the durable record with delivery state derived from the current wall clock. `session-local` means the original Session must be live: no external notification channel or cold-session scheduler exists.
+
+```ts type-equiv
+/** Current delivery timing derived from the durable record and wall clock. */
+type ScheduleState = 'scheduled' | 'overdue'
+```
+
+```ts type-equiv
+/** Fixed v1 delivery boundary: the original session must be live. */
+type ScheduleDeliveryMode = 'session-local'
+```
+
+```ts type-equiv
+/** Complete model-facing view of one active reminder. */
+type ScheduleView = ScheduleRecord & {
+  /** Whether the target remains in the future. */
+  readonly state: ScheduleState
+  /** Reminder delivery never leaves the owning session. */
+  readonly deliveryMode: ScheduleDeliveryMode
+}
+```
+
+The generated [tool catalog](../tool-catalog.md#deepseek-aidsh-schedule) owns the argument and result schemas for `schedule_create`, `schedule_list`, and `schedule_delete`. Management calls serialize with due work in one Agent-scoped queue. Every read or decision first waits for the shared Session persistence barrier; create and an actual delete wait again after appending. A barrier failure reports `persistence_uncertain` instead of guessing whether an eager write committed. The other stable error codes are `invalid_prompt`, `invalid_selector`, `invalid_rule`, `invalid_time_zone`, `not_future`, `time_out_of_range`, `frequency_too_high`, `corrupt_schedule_log`, and `internal_error`.
+
+## Live delivery
+
+The process-local owner derives its earliest timer from the durable fold and rereads the wall clock after every bounded wait. Cold Sessions do no work; reopening one reconstructs timers and makes past targets overdue. Due one-shots take priority and enter one later turn at a time. When no one-shot is due, all overdue Every records form the single batch described above.
+
+Due work waits for the Agent to become fully idle and claims the maintenance phase before it refolds state, samples the decision, queues one `followup()`, and appends the corresponding dispatch changes. It never calls `steer()` and never interrupts a current turn.
+
+The admitted one-shot or fixed-rate batch starts one normal later turn and appears only through the ordinary conversation transcript; Schedule has no independent durable Web receipt or browser renderer. If framing or synchronous queue admission fails, no dispatch is recorded and the reminder stays active. The narrow crash interval after admission but before durable dispatch can repeat reminder content after recovery, so the boundary is best-effort at-least-once rather than exactly-once delivery.

package/kb/site/en/reference/subsystems/scope.md

@@ -0,0 +1,62 @@
+---
+editSource: "docs/subsystems/scope.md"
+outline: [2,3]
+---
+
+# Scoped Registration
+
+The [scope package](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/scope) supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the lifecycle rationale, the [shared-storage Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md) owns the registry-layer decision, and the package [README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/scope/README.md) owns the callable API and filtering semantics.
+
+Sources: [`packages/core/scope/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/scope/src/index.ts) and [`packages/core/scope/src/store.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/scope/src/store.ts).
+
+## Identity and dispatch carrier
+
+`ScopeKey` is an opaque object identity. The shipped loop uses the live `Agent` object as its own key, but the primitive never inspects the object.
+
+```ts type-equiv
+/** An opaque, identity-compared scope key. */
+type ScopeKey = object
+```
+
+`Scoped<T>` is the compile-time brand on the opaque routing receiver returned by `scopeTarget(base, key)`. Scope-filtered event declarations require this carrier as their `this` type, while the real event subject remains an explicit argument.
+
+```ts type-equiv
+/**
+ * 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.
+ */
+type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
+```
+
+## Owned registration context
+
+`Scope` pairs the tagged registration context with two teardown paths. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
+
+```ts type-equiv
+/** A minted registration scope and its quiescent disposal boundaries. */
+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>
+}
+```
+
+## Scoped registry layer
+
+`ScopeLayer` represents one registry's complete contribution at the global or exact-scope level. A concrete layer may aggregate multiple named and anonymous tables; whole-layer emptiness lets `ScopedLayers` reclaim scoped state without discarding a sibling table.
+
+```ts type-equiv
+/** One scope's aggregate contribution to a registry. */
+interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+```
+
+`ScopedLayers<L>` owns the eager global layer and lazily created exact-scope layers. Reads do not create layers: `peek(undefined)` means no overlay, while `merge()` materializes insertion-ordered global named entries followed by scoped shadows. Registrations use one context for both visibility and Cordis effect ownership, collect one synchronous undo before optional notification, return Cordis's exact disposer, and reclaim a scoped layer only when its complete `ScopeLayer` is empty.
+
+`NamedEntries<V>` supplies insertion-ordered lookup and live iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Iteration stays live within one nonempty table generation; draining the table detaches existing iterators from later insertions. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.