super-dsh 0.3.0-c → 0.3.0-d

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch08-internals-pipelines.md

@@ -1,111 +0,0 @@
-# Chapter 8: Internals — Module Graph & Core Pipelines
-
-## Core Idea
-dsh's packages form a peer-dependency graph of *shared service instances*, wired at runtime by typed events and by a fixed three-waterfall tool-execution pipeline; two generated matrices (module graph, event producer–consumer matrix) tell you who owns an instance, who dispatches an event, and where policy inserts into a tool call.
-
-## Frameworks Introduced
-- **Shared-instance dependency graph** (`pnpm run gen-module-graph`): peer deps among `@deepseek-ai/dsh-*` packages; edge `a --> b` = `a` requires `b` as a host-provided shared instance. Runtime deps and dev-only relations deliberately absent.
-  - When to use: deciding which services a new package/plugin may consume, or which peers it must declare.
-  - How: Mermaid chart grouped by `packages/<group>/<pkg>` (50 groups, ~790 edges, names omit `@deepseek-ai/dsh-`) or the table `Package | Group | Peer dependencies`.
-- **Event Producer–Consumer Matrix** (`pnpm run gen-doc-graphs`): every harness-owned event as `Event | Mode | Declared in | Dispatchers | Listeners`; types also cover contained dispatch sites that deliberately bypass `ctx.emit` (subagent lifecycle containment).
-  - When to use: choosing a hook point, or auditing blast radius before changing an event payload.
-  - How: Mode = contract, Dispatchers = owner, Listeners = insertion precedent; empty Listeners = open extension point.
-- **Tool Execution Pipeline**: fixed stage order from model `tool_call` to model-facing `tool/result` hosting policy, hooks, sandboxing, rewriting, observation, UI "without changing the loop".
-  - When to use: adding approval, guards, timeout/retry, result post-processing, or tool UI.
-  - How: listen on the right waterfall (`tools/pre-execute` → guards → `tools/execute` → `tools/post-execute`); all three may transform a call.
-
-## Key Concepts
-- **Peer dependency**: a requirement for the host's shared instance; bundling your own copy breaks service identity.
-- **Event mode**: `emit` (broadcast), `waterfall` (value-transform chain), `serial` (ordered await), `parallel` (fan-out await).
-- **Monotonic guard**: registered deny-or-abstain check with protected identity, running after `tools/pre-execute` allow and before `tools/execute`; owner policy that must not be reordered lives here.
-- **`ctx.approval`**: one-shot user prompt resolving `ask` verdicts *before* monotonic guards; absent or unanswerable approver = deny.
-- **`ToolDefinition.finalizeContent`**: definition-owned last content-only invariant, synchronous, applied to a snapshotted result.
-- **Registry outer normalization**: the registry losslessly snapshots the candidate result; snapshot throws become `isError` so failures never escape the pipeline.
-- **`additionalContexts` FIFO**: active-batch extra contexts injected as user/message *after* recorded tool results.
-- **PTC sub-calls**: serialized sub-calls of the reserved `run_code` transport; carry the parent token, log `tool/code-dispatch`, return denials as binding rejections, omit `additionalContexts` to preserve call/result adjacency.
-- **`internal/*` events**: undeclared strings (`internal/dispatch`, `internal/plugin`, `internal/service`, `internal/status`) consumed by core machinery (loader, gateway, inspector) — not a public surface.
-
-## Mental Models
-- Think of the module graph as a *sharing contract*, not an import graph: edges mark services you receive, never services you bundle.
-- Use the event matrix as a *bus map*: the dispatcher owns the stop; listeners are the passengers you ride with.
-- Think of tool execution as *fixed track, movable signals*: stage order never changes; you add behavior by listening at a waterfall.
-
-## Anti-patterns
-- **Bundling a peer**: a second instance breaks shared identity; consume the host's copy.
-- **Putting reorder-sensitive owner policy in `tools/pre-execute`**: it can be bypassed/reshaped by other listeners; register it as a monotonic guard instead.
-- **Doing read-before-edit fs checks above `tool-fs`**: they stay below `tool-fs` on `fs/*` events.
-- **Reading `agent/status`/`whenIdle()` as "my follow-up finished"**: several queued follow-ups share one `running` interval; an owner must define its interval explicitly (durable inbox receipt → next whole-agent `idle`) and handle the "nothing to wait for" branch or hang.
-
-## Code Examples
-```ts
-// fs gates (dispatched by tool-fs / tool-str-replace-editor)
-ctx.waterfall('fs/write-intent', intent)    // → fs-observation-policy
-ctx.emit('fs/observed', obs)                // → fs-observation-policy, skill-filesystem
-
-// Both-sides contract: LlmAdapter vs LlmRuntime
-adapter.stream():  may throw OR emit finish { kind: 'error' | 'aborted' }
-runtime.stream():  model-request failures ONLY as terminal finish chunks
-
-// Dispose to quiescence
-registry.close(); proc.kill(); await done   // close listeners BEFORE killing
-
-// Unlink link-shaped paths
-if (lstatSync(p).isSymbolicLink()) unlinkSync(p)  // rmSync(junction) → ERR_FS_EISDIR
-```
-
-## Reference Tables
-
-### Tool execution stages (exact order)
-| # | Stage | Notes |
-|---|---|---|
-| 1 | model tool-call block | assistant message contains tool-call |
-| 2 | `tool/call` session event | logged before execution |
-| 3 | UI pending card | `presentCall(args)` |
-| 4 | `tools/pre-execute` waterfall | hooks, permission, sandbox → allow / deny / ask |
-| 5 | `ctx.approval` (ask path) | one-shot; rejected/cancelled/unavailable → denied |
-| 6 | monotonic guards | deny or abstain; identity protected |
-| 7 | `tools/execute` waterfall | around-dispatch: timeout, retry, metrics |
-| 8 | tool `execute()` body | may fire fs gates + tool-owned events (`todo/write`, `fs/observed`, `hook/invoked`, `hook/result`, `tool/code-dispatch`) |
-| 9 | `tools/post-execute` waterfall | accept, block, replace, add context |
-| 10 | registry outer normalization | snapshot throws → `isError` |
-| 11 | `ToolDefinition.finalizeContent` | last content-only invariant |
-| 12 | `tools/result` emit | frozen authoritative outcome |
-| 13 | `tool/result` session event | single model-facing outcome; batch settled |
-| 14 | `additionalContexts` FIFO | injected after recorded tool results |
-| 15 | UI completed card | `presentResult(args, result)` |
-
-Throws from stages 4–9 route to stage 10; denied calls skip the body but still traverse `tools/post-execute`.
-
-### Load-bearing events
-| Event | Mode | Dispatcher → listeners |
-|---|---|---|
-| `agent/pre-step` | waterfall | agent-loop → 15 pkgs (time-context, agent-instructions, plan-mode, hooks-*, tool-skill, tool-subagent…) |
-| `agent/request` · `agent/request-error` | waterfall | agent-loop → agent, webhook · compaction-basic, llm-retry |
-| `agent/turn-stopping` | serial | agent-loop → hooks-claude-code, hooks-codex |
-| `llm/stream` | waterfall | llm → agent-loop, llm-replay, session-checkpoint-policy, session-title |
-| `session/event` | emit | session → 27 pkgs (persistence, projection, telemetry, tools, server…) |
-| `session/flush` | parallel | session → session-persistence-jsonl, session-telemetry |
-| `system-prompt/assemble` | waterfall | system-prompt → agent, agent-presets |
-| `tools/pre-execute` · `execute` · `post-execute` | waterfall | tools → hooks-*, tool-jobs · session-checkpoint-policy, timeout-policy · spill-policy, repeat-tool-reminder, tool-fs-search |
-| `fs/write-intent` · `fs/edit-intent` | waterfall | tool-fs, tool-str-replace-editor → fs-observation-policy |
-| `approval/request` | waterfall | user-approval → acp, remotes |
-| `webserver/index-inject` | emit | webserver → inspector, modules |
-
-### Shared-instance hubs (fan-in, ~790 peer edges)
-`session` (92) > `llm` (83) > `agent` (64) > `tools` (42) > `invariants` (34) > `system-prompt`/`session-projection` (29) > `scope` (21). Top consumers: `api-session-controller` (26 peers), `subagent` (19). `llm` has zero outgoing peers (pure foundation); `tools --> agent` but not reverse; `session --> scope` only.
-
-## Key Takeaways
-1. Read the peer graph before adding a dependency — an edge means "require the host's shared instance", and fan-in hubs (session, llm, agent, tools) are the services everyone shares.
-2. Pick event hooks by matrix lookup, not guesswork: Mode defines the contract, Dispatchers define the owner, empty Listeners mark open extension points.
-3. Insert tool policy only at its designated waterfall; keep order-sensitive rules as registered monotonic guards, with `ctx.approval` resolving asks before guards.
-4. Normalize both sides of every public contract (adapter throws vs runtime terminal finish chunks) and report orthogonal outcome flags (`timedOut`, `signal`, `exitCode`) independently.
-5. Teardown must reach quiescence: close listener registries before killing, then `kill → await done`; dispatch loops must contain listener exceptions.
-6. Scrub env (`*KEY*/*SECRET*/*TOKEN*/*PASSWORD*`) and use 0700 dirs + random `'wx' 0o600` files around untrusted output; unlink — never recursively delete — link-shaped paths.
-
-## Connects To
-- **Ch 4**: peer = shared Cordis service instance; duplicate-identity errors.
-- **Ch 6**: the package groups/layers the graph visualizes.
-- **Ch 7**: the event matrix is the canonical capability-seam inventory.
-- **Ch 14**: agent-loop as chief dispatcher of `agent/*` events.
-- **Ch 15**: tool-execution subsystem detail behind the stage table.
-- **Ch 17**: `LlmAdapter`/`LlmRuntime` failure contract.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch09-api-gateway.md

@@ -1,106 +0,0 @@
-# Chapter 9: API Gateway & LLM Wire Extensions
-
-## Core Idea
-dsh exposes Host business logic to the Client through the **Typert API Gateway**: `@Remote`/`@RemoteScope` decorators select unary service methods, the build generates strict Host+Client contracts, and calls reuse the Connection RPC over `POST /api/<namespace>/<method>`. Separately, `@deepseek-ai/dsh-llm-deepseek` adds DeepSeek-specific HTTP headers and additive request-body fields (`dsh_plugin_packages`, `dsh_session_log`) that never enter model input.
-
-## Frameworks Introduced
-- **Typert API Gateway**: unary-only Remote-method bridge. Layers run `remotes → gateway → connection → webserver`; `packages/api` holds BFF+Typert, `packages/client/connection` and `packages/host/webserver` hold transport.
-  - When to use: any Host service method a browser/SDK client must call with one request → one result.
-  - How: mark methods `@Remote`/`@RemoteScope`, extend `TypertRemoteService`, generate contracts, mount via `api-remotes`, call `ctx.remote.<namespace>.<method>(...)`.
-- **`@Remote`**: calls a Cordis service registered on the root Host Context. Host objects (e.g. `Agent`) cannot cross the wire — declare a `TypertLookupMap` so a parameter `agent` becomes an `agentId` wire field the Gateway resolves back to the object.
-- **`@RemoteScope(key)`**: resolves an identity to a scoped Context via `ctx.typert.contexts`, gets the service from that Context. Use when the method depends on scoped composition and needn't receive objects like `Agent` explicitly.
-- **`TypertRemoteService` / `bindTypertRemote(this, serviceKey)`**: explicit service-key + namespace binding (no compiler-injected symbol). `bindTypertRemote` for services with another base class.
-- **Strict generation pipeline**: root build runs `build:lib:host` → `build:lib:client` → `build:web`. Host pass = `tsc -b tsconfig.host.json` then `tsdown --env.DSH_BUILD_FACE host` (runs Typert generator); Client pass = `tsc -b tsconfig.client.json` + `tsdown --env.DSH_BUILD_FACE client`, consuming generated artifacts without restarting Typert.
-- **SRC development fallback**: `node --import tsx/esm` skips the Typert compiler; decorator initializers still record a versioned descriptor so the Gateway builds a weaker descriptor with no `ts.Program`. Solves Host dispatch from source only — Client still refuses SRC descriptors lacking strict codecs.
-- **`DeepSeekLlmApiExtensionRegistry`**: one provider per top-level extension name; empty/padded names, duplicate registrations, and collisions with the base request fail before HTTP dispatch.
-- **Body-extension transaction**: serialize base body (incl. exact `messages`) → ask registered providers to `prepare()` fields → merge as top-level siblings → on HTTP 2xx run `accept()` before reading SSE. No registry = unextended base body sent.
-
-## Key Concepts
-- **`ctx.remote.<namespace>`** (root) / **`agentCtx.remote.<namespace>`** (scoped): concrete Client functions on ordinary objects; each namespace is a traced Cordis child Service registered as `remote.<namespace>`, mounted through `ctx.remote.$mount()`.
-- **`TypertLookupMap`**: wire-identity association for complex Host params; `ctx.typert.lookups.register()` = declaration+default resolver, `.configure()` = async Host-composition override scoped to an effect lifetime.
-- **`api-remotes` assembly**: only `@deepseek-ai/dsh-api-remotes` is assembled; it imports business packages' `/remote` subpaths, mounts contributions, re-exports declaration merges. Host-method surface = only what's selected at generation time.
-- **`/api` route**: Client calls `connection.rpc.call('/api', '<ns>/<method>', { args }, signal)` → `POST /api/<ns>/<method>` with `{ args }`. Gateway claims only two-segment endpoints with a strict descriptor or SRC marker; other requests 404.
-- **Wire namespaces**: HTTP fields = lowercase kebab (`x-deepseek-harness-session-id`); request-body extensions = snake with reserved `dsh_` prefix; DSH-owned nested JSON = camelCase (`afterSeq`); tagged values = kebab, durable events `domain/action`.
-- **`dsh_plugin_packages`** (enabled by default): complete active Loader-backed `{name,version}` package inventory; deduped, sorted by name then version; disabled/failed/unloading entries and non-package provenance absent; `packages: []` when none qualify.
-- **`dsh_session_log`** (disabled by default): contiguous suffix of the canonical Session log, version 2. First upload `afterSeq: -1`; later uploads start after the greatest accepted watermark. `session` member projects `Session.header` (id, createdAt, `isSeeded` lineage bit, optional cwd/parentSession/origin/delegationDepth/agentPreset).
-- **`delivery-accepted` watermark event**: appended after HTTP 2xx — type `session-log-deepseek/delivery-accepted`, data `{sessionId, sessionFormatVersion, throughSeq}`. Binds watermark to the logical format generation.
-- **At-least-once delivery**: crash after acceptance but before persistence may resend an already-accepted range → duplicates, never a gap. Fork ignores inherited watermarks naming another Session.
-
-## Mental Models
-- **Use `@Remote` for root-Host services, `@RemoteScope` for scoped-composition methods.** Complex Host objects never cross the wire — think of the lookup map as the wire↔object identity table.
-- **Think of Remote as unary-only.** Session event streams, pagination, incremental reduce, projection, entity substreams → register an exact Connection Fetch route, never a Remote method.
-- **Think of the extension transaction as prepare-then-accept.** Only a 2xx endpoint accepts any contribution; a non-2xx or transport failure sends nothing and appends no watermark.
-- **Think of extension fields as "outside the model."** They sit outside `messages`/system prompt/tool schemas, so they add no input tokens and don't alter the model-visible prefix.
-
-## Anti-patterns
-- **Modeling a streamed/browser-native feature as a Remote method**: Remote is strictly one request → one result; streaming must use a separate data protocol + registration model even if it shares the Connection.
-- **Guessing whether an `Agent` object came from restoration**: lookup policy is per-key, so all `agent`/`session` params share cold-resume behavior; the method must not assume live-vs-restored provenance.
-- **Treating `delivery-accepted` as persistence**: it asserts endpoint-level HTTP 2xx only — not SSE completion, not remote persistence.
-- **Collapsing `dsh_plugin_packages` by package name**: receivers must preserve distinct simultaneous versions and ignore array order.
-- **Reading generated `.d.ts` as ground truth for dispatch**: the strict contract (types/codecs) always comes from `lib/typert.remote-client.*`, never from a running source Host.
-
-## Code Examples
-```ts
-export class GoalService extends TypertRemoteService {
-  constructor(ctx: Context) { super(ctx, 'goals') }   // namespace 'goals'
-  @Remote('create')
-  createForClient(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): CreateGoalResult {
-    signal.throwIfAborted(); return this.create(agent, request)
-  }
-  @RemoteScope('agent', 'current')                    // scoped: agentId → context → service
-  currentForClient(): CreateGoalResult { return { accepted: true } }
-}
-// Client — inject ['remote', 'remote.goals']; single lookup param collapses the wire field:
-await ctx.remote.goals.create(agentId, { objective: 'ship it' })
-await agentCtx.remote.goals.create({ objective: 'ship it' })
-```
-```jsonc
-// dsh_plugin_packages (version 1)
-{ "dsh_plugin_packages": { "version": 1, "packages": [ { "name": "@deepseek-ai/dsh-example", "version": "0.1.1-rc.2" } ] } }
-// dsh_session_log suffix (version 2)
-{ "dsh_session_log": { "version": 2, "sessionFormatVersion": 2,
-    "session": { "version": 2, "id": "session-id", "createdAt": 1780000000000, "isSeeded": false },
-    "afterSeq": -1, "throughSeq": 0,
-    "events": [ { "type": "turn/start", "seq": 0, "time": 1780000000001, "data": { "turn": 1 } } ] } }
-// watermark appended after 2xx
-{ "type": "session-log-deepseek/delivery-accepted", "seq": 8, "time": 1780000000002,
-  "data": { "sessionId": "session-id", "sessionFormatVersion": 2, "throughSeq": 7 } }
-```
-
-## Reference Tables
-
-**Request headers (`dsh-llm-deepseek`)**
-| Header | Presence | Value |
-|---|---|---|
-| `user-agent` | every provider HTTP request | `product/version (+url)`; default product `deepseek-harness` |
-| `x-deepseek-harness-user-id` | every authorized chat-completion | stable anonymous Harness-home UUID |
-| `x-deepseek-harness-session-id` | chat-completion with a Session id | exact `sessionId` string |
-| `x-deepseek-harness-compact` | purpose `compaction` | literal `1` |
-
-**Component responsibilities**
-| Package | Role |
-|---|---|
-| `dsh-typert-protocol` | decorators, Gateway bindings, invocation descriptors (no analysis/services) |
-| `dsh-typert-generator` | build-time strict signature/type/lookup/Context analysis → artifacts |
-| `dsh-typert-registry` + Loader | Host descriptors/schemas into `ctx.typert`, lookup+Context providers |
-| `dsh-api-session-controller` | Agent/Session identity policy; standard `agent`/`session` resolvers |
-| `dsh-api-gateway` | `ctx.typertGateway`; claims endpoints, resolves objects, invokes, validates |
-| `dsh-api-gateway/client` | `ctx.remote`; mounts descriptors, initiates/validates/cancels |
-| `dsh-api-remotes/client` | selects+mounts allowed `/remote` contributions |
-| `dsh-client-connection` | RPC carrier, correlation, trust boundary, cancellation, `/api` bridge |
-
-**Generated files per business package (`lib/`)**: `typert.host.js/.d.ts`, `typert.remote-client.js/.d.ts`, `typert.remote-client.d.ts.map`; entries exposed via `./typert` (Host) and `./remote` (Client).
-
-## Key Takeaways
-1. Gateway owns only the Remote data protocol + business dispatch; Connection owns transport, RPC ids, envelopes, cancellation — swap the carrier without touching descriptors.
-2. The trust fence runs in Connection **before** the HTTP bridge, then dispatches inside the shared FetchHandler.
-3. A strict endpoint withdrawn on the Host does **not** degrade to SRC inference — hot unload can't silently weaken validation.
-4. `session/not-found` and `session/agent-busy` `RemoteError` codes pass to the wire unchanged; only unclassified throws fold into `gateway/internal`.
-5. Extension fields are versioned independently per field; JSON member order is not protocol.
-
-## Connects To
-- **Ch06 architecture**: the `remotes → gateway → connection → webserver` layer stack and package split.
-- **Ch07 capability-seams**: Remote is the unary seam; streaming seams use a different registration model.
-- **Ch02 plugin-basics**: declaring `@Remote` methods and `inject`-ing `remote.<namespace>` is the plugin-author wiring.
-- **Ch08 internals-pipelines**: the `build:lib:host`/`client`/`web` order and `DSH_BUILD_FACE` split.
-- **Ch10 config-catalog**: `host-webserver.{host,port}`, `client-connection.trustedHosts`, `api-gateway.websocketHeartbeatIntervalMs` (default 2000 ms), `llm-deepseek.*`.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch10-config-catalog.md

@@ -1,97 +0,0 @@
-# Chapter 10: Config Catalog
-
-## Core Idea
-`config-catalog.md` is the **deployment-axis** reference: for every loadable harness package it pastes the verbatim `config:` block a `cordis.yml` entry can set, plus each plugin's `Requires:` injection line. It is **generated** from source (`scripts/gen-config-catalog.ts`), not a layering spec — the paste is the plugin's *full declared config type*, and any field the runtime schema deliberately excludes is a runtime-only seam that is **not settable from `cordis.yml`**.
-
-## Frameworks Introduced
-- **`config:` block (cordis.yml)**: the only settable surface catalogued here. The plugin's `apply`/service constructor receives the declared config type; referenced types are pasted (package-local) or linked.
-- **`Requires:` line**: lists the service keys the plugin `inject`s — its `cordis.yml` tree must also load providers for those services. Scope = harness tier (`packages/`); vendored cordis plugins (`hmr`, console logger) are pinned upstream and not catalogued.
-- **`static Config` / schemastery schema**: most plugins supply defaults statically and validate via a same-named schemastery schema; the generator cross-checks the schema against the pasted declaration so the paste cannot hide a loader-accepted field.
-- **Generated + verified**: `pnpm run gen-config-catalog` regenerates; `verify-config-catalog` (part of `doc-sync`) checks freshness. Do not hand-edit.
-- **Three package classes**: (1) **loadable** — with a `config:` block; (2) **loadable no-config** — a `cordis.yml` entry with no `config:`; (3) **seam** — abstract service classes (`AttachmentStore`, `SandboxProvider`, `SessionPersistence`, `CredentialProvider`, …) not directly loadable; (4) **library** — no plugin entry, cannot be loaded.
-
-## Key Concepts
-- **Home path convention**: `dshHome` (settings/credentials/shell-env/agent-instructions) defaults to `$DSH_HOME` then `~/.dsh`.
-- **Runtime-only seam**: a field the schema excludes by design — its JSDoc says so; not settable from `cordis.yml`.
-- **Preset-root precedence**: `agent-presets` `roots[]` scanned in precedence order (earlier wins a duplicate id); `includeShippedRoot` prepends the bundled `system` root, `includeUserRoot` appends the home `user` root.
-- **`SandboxMode` / `ApprovalPolicy`**: shared deployment knobs — `sandbox-policy.mode` default `read-only`; `user-approval.policy` = `ask` (fail-closed) or `never` (deterministic CI/unattended).
-- **Backend routing**: `storage-domain.backend` = default route, `routes` overrides per domain name; unknown backend fails `open` with `backend-not-found`.
-- **No-default `root`s**: `session-persistence-jsonl.root`, `storage-json.root` have no default on purpose — a `process.cwd()` fallback would scatter files as cwd changes (bash/subprocess).
-
-## Mental Models
-- **Read the config type as the wire surface, not the runtime object**: the paste is exactly what `cordis.yml` may set; anything else is a runtime-only seam.
-- **Think of each capability seam as "abstract service + concrete package"**: the *concrete* package (`dsh-bash-sandbox`, `dsh-storage-sqlite`, …) carries the config; the abstract seam package is never loaded directly.
-- **Think of sandbox policy vs runner as split**: `sandbox-policy` owns `mode`/`workspaceRoot` (per-session resolution); the runner choice is the `ctx.sandbox` provider's config, not the executor's.
-
-## Anti-patterns
-- **Setting a runtime-only seam from `cordis.yml`**: it is deliberately excluded from the schema and will not apply.
-- **Loading a seam or library package in `cordis.yml`**: seams are abstract (load a concrete impl), libraries have no plugin entry.
-- **Defaulting storage/session `root` to `process.cwd()`**: scatters unit files across whatever cwd the process is in — the doc forces an explicit `root` for exactly this reason.
-- **Assuming a full CLI>env>home>profile precedence chain lives in this doc**: it does not — this file documents the `config:` surface only; the layering/merge model is in ch01/ch02.
-
-## Reference Tables
-
-**Most-needed config keys** (`@deepseek-ai/` prefix omitted; type + default where declared)
-
-| Key (package) | Type | Default | Purpose |
-|---|---|---|---|
-| `agent-default-model.provider` / `.model` | string | required | default provider route + model id |
-| `agent-loop.agents[]` | array | required | agents created/resumed at startup (`id`, `sessionId`, `cwd`, `resumeSessionId`) |
-| `agent-loop.maxParallelToolCalls` | number | `DEFAULT_MAX_PARALLEL_TOOL_CALLS` | parallel-safe calls per agent step (1 = serial) |
-| `agent-presets.default` | string | required | preset id when caller names none (missing = loud fail) |
-| `agent-presets.roots[]` | array | required | preset scan roots in precedence order |
-| `agent-presets.includeShippedRoot` / `includeUserRoot` | bool | `true` | prepend bundled `system` / append home `user` root |
-| `agent-tool-presentation.mode` | `'native'\|'ptc'\|'both'` | required | model-visible tool form |
-| `agent-instructions.maxBytes` | number | required | UTF-8 byte cap per rendered baseline/dynamic batch |
-| `llm-deepseek.apiKeyEnv` | string | `DEEPSEEK_API_KEY` | credential env-var name, resolved per request |
-| `llm-deepseek.baseURL` | string | `$DEEPSEEK_BASE_URL` → public API | endpoint base |
-| `llm-deepseek.thinking` | `'enabled'\|'disabled'` | provider default | deployment thinking policy |
-| `llm-deepseek.reasoningEffort` | `'off'\|'low'\|'high'\|'max'` | `high` | default thinking effort |
-| `llm-deepseek.maxTokens` | number | `256000` | default per-request output cap |
-| `llm-deepseek.defaultContextWindow` | number | `1000000` | context capacity fallback |
-| `llm-deepseek.models[]` | `DeepSeekCatalogModel[]` | V4 Flash/Pro/Flash Vision Exp | advertised selector models |
-| `bash-local.cwd` | string | `process.cwd()` | default command working dir |
-| `bash-local.timeoutMs` / `maxTimeoutMs` | number | — | foreground timeout + per-call override cap |
-| `bash-local.maxOutputBytes` / `maxSpillBytes` | number | — | in-memory output / spill-file caps |
-| `host-webserver.host` | `'127.0.0.1'\|'0.0.0.0'` | — | listen host |
-| `host-webserver.port` | number | — | listen port (0 = OS-assigned) |
-| `host-webserver.compression` | `'none'\|'gzip'` | `none` | response compression |
-| `client-connection.trustedHosts` | string[] | — | non-loopback authorities for `/api` trust fence |
-| `client-connection.cookieMaxAgeDays` | number | `30` | browser-session lifetime |
-| `client-connection.maxRequestBodyBytes` | number | `300 MiB` | max buffered `/api` JSON body |
-| `sandbox-policy.mode` | `SandboxMode` | `read-only` | file-sandbox default (fail-safe) |
-| `sandbox-policy.workspaceRoot` | string | `process.cwd()` | fallback root (agentless / no-cwd) |
-| `user-approval.policy` | `'ask'\|'never'` | `ask` | approval default (never = CI/unattended) |
-| `permission-presets.presets` / `defaultPreset` | map / string | `workspace-write`,`danger-full-access` | preset knob table + new-session default |
-| `session-persistence-jsonl.root` | string | required | session files root |
-| `session-persistence-jsonl.compression` | `'zstd'\|'none'` | `zstd` | physical encoding |
-| `storage-domain.backend` / `routes` | string / map | required | default backend + per-domain overrides |
-| `storage-json.root` | string | required | `<unit>.json` file dir |
-| `storage-sqlite.path` / `journalMode` | string / `'wal'\|'delete'\|'truncate'\|'persist'` | `:memory:` / `wal` | DB file + journal pragma |
-| `mcp-client` (per server) | `StdioConfig`\|`StreamableHttpConfig` | — | `transport`, `serverName` (`mcp__<name>__<tool>`), `command`/`url`, `toolCallTimeoutMs` |
-| `web.searchProvider` / `fetchProvider` | string | auto-select | pin which provider wins per capability |
-| `web-app.openBrowser` / `printUrl` / `surfaceContext` / `trustedHosts` | bool/bool/bool/string[] | — | browser handoff, URL line, `app:web-surface` context, `--trusted-host` |
-| `settings-file.path` | string | `settings.yaml` under home | settings doc location |
-| `credentials-local.path` | string | `.credentials.yaml` under home | credentials doc location |
-| `compaction-basic.thresholdRatio` / `retainRatio` | number | `0.8` / `0.16` | compact-at / retain fractions of context window |
-| `persona.text` / `complete` | string / bool | — | persona prose; `complete` = whole system prompt |
-| `tool-web.search` / `fetch` / `fetchMaxOutputChars` | bool/bool/number | `true`/`true`/`200000` | tool registration + fetch output cap |
-| `tool-todo.allowParallelInProgress` | bool | required | allow multiple `in_progress` todos |
-| `api-gateway.websocketHeartbeatIntervalMs` | number | `2000` | WS ping interval (1…2147483647 ms) |
-
-**Where the rest lives**: the source doc's `## @deepseek-ai/dsh-*` sections (one per package, ~110 packages) carry the full verbatim declarations + JSDoc; its tail lists `Loadable plugins with no config`, `Seam packages`, and `Library packages`. For the runtime wire surface, see the generated Cordis API region on each `subsystems/core.md` page; model-facing tool schemas live in `tool-catalog.md`.
-
-## Key Takeaways
-1. Config is delivered through `cordis.yml` `config:` blocks — this catalog is the authoritative list of what each package accepts.
-2. Every key's default and validation come from the plugin's `static Config` + schemastery schema, not from a central registry.
-3. `Requires:` is load-critical: a config tree that omits an injected service fails to compose.
-4. Storage/session `root` paths are deliberately default-less — state them explicitly to avoid cwd-scatter.
-5. Deployment policy (sandbox mode, approval policy, trusted hosts, compaction thresholds) is spread across dedicated policy packages, not one global config.
-
-## Connects To
-- **Ch01 user-guide / Ch02 plugin-basics**: the `cordis.yml` layering and merge semantics (this doc covers only the per-package surface).
-- **Ch05 cordis-api**: the generated Cordis API region on subsystem pages that these declarations reference.
-- **Ch07 capability-seams**: the "seam packages" here are the abstract classes the seams chapter names.
-- **Ch09 api-gateway**: `host-webserver`, `client-connection.trustedHosts`, and `api-gateway.websocketHeartbeatIntervalMs` configure the gateway transport.
-- **Ch11 tool-catalog**: the model-facing tool schemas that `tool-web`, `tool-todo`, `tool-workflow`, `tool-bash` config keys shape.
-- **Ch12 persistence-catalog**: `session-persistence-jsonl`, `storage-*`, `session-query-sqlite`, `session-projection-cache` backends.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch11-tool-catalog.md

@@ -1,121 +0,0 @@
-# Chapter 11: Tool Catalog
-
-## Core Idea
-This is a GENERATED registry of every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` delivered via system-prompt assembly. It is produced by BOOTING each tool plugin on a real context and reading `ctx.tools.schemas()` — not a static AST pass — because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools).
-
-## Frameworks Introduced
-- **Tool contribution = `{ name, description, parameters }` into `ctx.tools`**: a tool is the model-facing projection of a plugin's execute logic; `ctx.tools.schemas(scope)` projects an allowlist (name/description/parameters only) so `output`/`execute`/callbacks never leak into model requests.
-  - When to use: every model-facing action. How: plugin contributes a `ToolDefinition`; the catalog generator boots it and reads the projected schema.
-- **Capability-seam stability**: a tool keeps its provider behind an abstract seam (`ctx.lsp`, `ctx.web`, `ctx.subagents`, `ctx.codeRuntime`, `ctx.shell`, `ctx.fs`, `ctx.terminals`) so the model-visible schema stays stable across backend swaps.
-  - When to use: any swappable backend (`lsp`, `web_search`/`web_fetch`, `subagent`).
-- **Load-time config names / shipped aliases**: a registered `name` may be a load-time config (e.g. `tool-subagent`'s `toolName` default `subagent`, shipped alias `subagent_fork`); a deployment may expose a package under a different or additional name.
-- **Reserved transport (`run_code`)**: owned by the tool registry outside filterable capability layers under `mode: ptc`/`mode: both`; under `ptc` it is the registry's only wire contribution — other capabilities are declared in a generated SDK section and re-enter the guarded tool pipeline via scheduled bindings (overlap up to `maxParallelSubCalls`).
-- **Boot-and-read verification**: `gen-tool-catalog` generator + `verify-tool-catalog` (part of `doc-sync`); a completeness guard globs `packages/*/tool-*` and fails if a package is missing from the boot manifest, so a new tool cannot be silently undocumented.
-
-## Key Concepts
-- **ctx.tools**: the single registry of model-facing tools (see Ch 15 for the dispatch pipeline behind it).
-- **Capability seam**: `ctx.shell`, `ctx.fs`, `ctx.subprocess`, `ctx.terminals`, `ctx.lsp`, `ctx.web`, `ctx.codeRuntime`, `ctx.subagents`, `ctx.workflowEngine`, `ctx.jobs` — abstract services a tool consumes; one provider per context.
-- **Requires / Writes-affects**: the package map's two metadata columns — which seams a tool needs, and which events/durable effects it produces.
-- **Shipped alias**: a second registered name for the same package (e.g. `subagent_fork` for a fixed-route delegation).
-- **Reserved transport**: `run_code` — excluded from filterable capability layers; registry-owned.
-- **Per-package deployment note**: records opt-in status, config branches, and defaults the generator had to choose (e.g. `todo_write`'s `allowParallelInProgress: true`).
-- **Read-before-write policy**: added by `@deepseek-ai/dsh-fs-observation-policy` (an `fs/*` event-gate plugin) — no schema change; a deployment loading the fs tools is expected to also load it.
-
-## Mental Models
-- Think of the tool catalog as the **system-prompt assembly's menu**: what the model is *offered*, not what the runtime can *execute* (the Cordis surface is the latter).
-- Think of a tool's schema as **runtime-spread**, never statically knowable — always boot to read it, never hand-transcribe.
-- Use a **seam** when a capability may swap backends; keep the tool thin and let the seam own the vocabulary.
-- Think of `run_code` as the **only non-filterable wire contribution** under `ptc` — everything else is reachable only through the code-runtime SDK.
-
-## Anti-patterns
-- **Hand-editing the generated catalog**: it is regenerated and re-verified by `doc-sync`; edits are overwritten.
-- **Guessing an Inspect/LSP provider name**: `cordis_inspect_list`/provider discovery must precede `cordis_inspect_query`/`lsp`; an Inspect method is read-only, not a business Service plugin code can call.
-- **Loading fs tools without the observation-policy plugin**: bare `write`/`edit` lose the read-before-write guard.
-- **Treating `subagent`'s discovery schema as fixed**: model-selection on/off, background mode, and the registration name are per-instance config (`modelSelectionSettings`, `backgroundMode`, `enableRunInBackground`, `toolName`).
-
-## Code Examples
-```jsonc
-// Tool schema shape every entry shares: { name, description, parameters }
-{ "name": "bash",
-  "description": "Execute a bash command (bash -c) and return stdout/stderr.",
-  "parameters": { "type": "object",
-    "properties": {
-      "command": {"type":"string"},
-      "description": {"type":"string"},
-      "timeoutMs": {"type":"number"},
-      "workdir": {"type":"string"},
-      "run_in_background": {"type":"boolean"}
-    }, "required": ["command","description"] } }
-```
-```ts
-// run_code bridge: each nested call re-enters the guarded tool pipeline
-// and links to the outer result via a tool/code-dispatch-start + tool/code-dispatch pair.
-// sub-call id = `<parent>:code:<n>` (submission order); tool/result vocabulary carries content + isError.
-```
-```ts
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover';
-// schedule selectors: after_seconds | at | every_seconds (>= 300) — exactly one.
-```
-
-## Reference Tables
-Full lookup table — name → one-line purpose, grouped by category. Per-tool JSON Schemas and exact field docs live in `src/docs/tool-catalog.md` (generated; ~90KB), package sections below its "Tool Package Map".
-
-| Tool | Package | Purpose |
-|---|---|---|
-| **Human interaction** |||
-| `ask_user_question` | dsh-tool-ask-user | Pause until the UI/provider returns a human answer (confirmation/choice/missing info). |
-| `exit_plan_mode` | dsh-plan-mode | Present a plan for review; reject outside plan mode, no schema churn on policy change. |
-| **Shell (one-shot, fresh process)** |||
-| `bash` | dsh-tool-bash | Run `bash -c`, return stdout/stderr; `run_in_background` → job id. |
-| `pwsh` | dsh-tool-pwsh | Windows `pwsh -Command` counterpart; mirrors bash minus sandbox controls. |
-| **Shell (persistent PTY)** |||
-| `bash` (persistent) | dsh-tool-bash-persistent | Owner-isolated persistent bash; cwd/env persist across calls. |
-| `pwsh` (persistent) | dsh-tool-pwsh-persistent | Owner-isolated persistent pwsh. |
-| **Filesystem** |||
-| `read` / `write` / `edit` | dsh-tool-fs | UTF-8 read (line-numbered) / create-or-replace / literal-replace edit. |
-| `read_image` | dsh-tool-fs | Read PNG/JPEG/WebP/GIF; refuses unless the routed model accepts image input. |
-| `glob` / `grep` | dsh-tool-fs-search | Path discovery / ripgrep content search (packaged `@vscode/ripgrep`, no host rg). |
-| `str_replace_editor` | dsh-tool-str-replace-editor | Standalone view/create/unique-literal-replace/insert editor. |
-| **Terminals (opt-in)** |||
-| `terminal_open`/`close`/`list`/`read`/`send`/`signal` | dsh-tool-terminal | Persistent terminal sessions; `send(run_in_background)` registers with `ctx.jobs`. |
-| **Code runtime** |||
-| `run_code` | dsh-tools | Execute a TypeScript program body against tools (PTC transport). |
-| **Delegation & control** |||
-| `subagent` / `list_subagent_models` | dsh-tool-subagent | Delegate a self-contained task / discover LLM routes. |
-| `send_message` / `interrupt_agent` / `list_agents` | dsh-tool-subagent-control | Steer, interrupt, list continuable background subagents (global names). |
-| `workflow` | dsh-tool-workflow | Orchestrate many subagents via a JS script (`agent`/`pipeline`/`parallel` hooks). |
-| `ralph` | dsh-tool-ralph | Foreground fresh-agent loop; one immutable objective + optional round cap. |
-| `spawn_teammate` | dsh-experimental-tool-agent-team | Create a named durable teammate (Team Lead only). |
-| `team_task_*`, `wait_agent`, team `send_message`/`interrupt_agent`/`list_agents` | dsh-experimental-tool-agent-team | Shared task board (create/get/list/update) + team mailbox/status wait. |
-| **Background jobs** |||
-| `job_list` / `job_output` / `job_kill` | dsh-tool-jobs | Kind-agnostic controller: bash, PTY sends, subagents all through the same three. |
-| **Goal (same-session)** |||
-| `create_goal` / `get_goal` / `update_goal` | dsh-tool-goal | Persisted long-running objective; direct-human root authority for mutations. |
-| **Schedule** |||
-| `schedule_create` / `schedule_delete` / `schedule_list` | dsh-schedule | Session-local reminders (after_seconds | at | every_seconds≥300). |
-| **Session query (opt-in)** |||
-| `session_search` / `session_trace` / `session_event_read` / `session_event_search` / `session_event_trace` | dsh-tool-session-query | Read-only search/trace over the durable event log, authorized by the calling agent. |
-| **Skill** |||
-| `skill` | dsh-tool-skill | Load full instructions for a named skill from the session catalog. |
-| **Web** |||
-| `web_search` / `web_fetch` | dsh-tool-web | Search (1–4 queries) / fetch a URL; provider behind `ctx.web`. |
-| **LSP** |||
-| `lsp` | dsh-tool-lsp | Code navigation (definition/references/implementation/hover); `LSP_UNAVAILABLE` without a provider. |
-| **Dynamic Cordis (opt-in)** |||
-| `cordis_define`/`inspect_list`/`inspect_query`/`inspect_self`/`run`/`stop`/`undefine` | dsh-tool-cordis | Define/inspect/run immutable Cordis packages in a vm sandbox (not in any shipped tree). |
-| **TODO** |||
-| `todo_write` | dsh-tool-todo | Session-owned checklist; whole-list replace (no partial updates). |
-
-## Key Takeaways
-1. The catalog is the *offered* tools (name/description/parameters), generated by booting each plugin and reading `ctx.tools.schemas()` — never a static AST pass.
-2. Every tool maps to a **package** + **seams** (`Requires`) + **durable effects** (`Writes/affects`); the package map is the primary index.
-3. Keep swappable capabilities behind a seam (`ctx.web`, `ctx.lsp`, `ctx.subagents`) so the schema does not change on backend swap.
-4. `run_code` is the registry's reserved transport — the only wire contribution under `ptc`; other capabilities reach it via scheduled bindings.
-5. Registration names can be config-driven and aliased (`subagent`/`subagent_fork`); deployment notes record shipped aliases and generator-chosen defaults.
-
-## Connects To
-- **Ch 15**: `ctx.tools` dispatch pipeline (ToolDefinition, guards, observation policy) behind these schemas.
-- **Ch 07**: capability seams — the Service/Provider/Consumer split each tool leans on.
-- **Ch 16**: `tool/call`, `tool/result`, `tool/code-dispatch*` are the durable session-log facts tools emit.
-- **Ch 10**: config keys that shape tools (`toolName`, `enableRunInBackground`, `sampleOverCapGlobResults`, preset tables).
-- **Ch 14**: the agent loop requests these tools and commits their call/result events.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch12-persistence-catalog.md

@@ -1,109 +0,0 @@
-# Chapter 12: Persistence Catalog
-
-## Core Idea
-Session persistence is one **durable, replayable, append-only event log**: every record is a `SessionEvent` envelope (`type`, monotonic `seq`, epoch-ms `time`, `data`, optional `ignorable`, conditional `surfaceOp`/`sourceEventSeqs`). This catalog documents the *event vocabulary* (`SessionEventMap`) and the surface/log-only split — it does NOT document on-disk store layout, DSH_HOME anatomy, or durability mechanics (those live in `subsystems/persistence.md`, the doc's own cross-ref target). A log event is **not a Cordis event**: it reaches listeners through the single `session/event` emit.
-
-## Frameworks Introduced
-- **`SessionEventMap` (merge-extensible vocabulary)**: the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types`; a downstream plugin can merge further current-version event types (outside this catalog by construction, requiring explicit disposition at a later format edge).
-  - When to use: declaring a new durable event type. How: merge the key into `SessionEventMap`; surface types also join `SurfaceEventType`.
-- **Surface vs log-only split**: `SurfaceEventType` = `'user/message' | 'assistant/message' | 'tool/result'` — the only types that produce LLM messages and may carry `SurfaceOp`. Everything else is **log-only**: durable + replayable, zero derived-history contribution.
-  - When to use: a type enters the model transcript only if it is a surface type; audit/boundary/state records stay log-only.
-- **`SurfaceOp` join rule**: `'append'` (tail) or `{ op:'replace', start, end }` (replaces surface nodes start..end; node's `sourceEventSeqs` must include every shadowed node). Used by compaction; any surface-replacing producer may use it.
-- **`ignorable` marker protocol**: absent = **required** — a reader meeting an unrecognized type without `true` MUST refuse reconstruction (not silently drop), because a required event may change how the rest of the log interprets. A writer sets `true` only on purely informational records whose loss cannot affect reconstruction.
-- **Shadow-price protocol (compaction)**: a surface `replace` event is priced by the metering event *immediately before* it (`compaction/summary` for a summarizing compaction, `compaction/prune` for a model-free prune), stating `shadowedRange`/`shadowedSeqs`/`shadowedTokenCount` — so a pure consumer can subtract the exact replaced range without retaining per-node prices.
-- **Version lifecycle**: current writers stamp `SESSION_FORMAT_VERSION`; supported historical artifacts reach the current vocabulary through the build-static adjacent migration catalog (see `subsystems/persistence.md`).
-- **JSON-serializability gate**: every payload is JSON-serializable, enforced at `Session.append` via `isJsonValue` — a non-serializable `meta` is rejected at the source, so replay reproduces the identical record.
-
-## Key Concepts
-- **SessionEvent**: discriminated union over `type` (so `switch (event.type)` narrows `event.data` without casts); envelope = `{ type, seq, time, data, ignorable?, sourceEventSeqs?, surfaceOp? }`.
-- **SurfaceEventType**: the 3 message-producing types; only these may carry `SurfaceOp`; user/tool may cite `sourceEventSeqs`.
-- **log-only**: durable, replayable, no `surfaceOp`, never in derived history (`deriveMessages()` ignores it).
-- **session/end-seed**: durable projection of `Session.firstLiveSeq`; events before it (smaller seq) came from seed (resume/fork/replay). A fresh fork child owns one `{ inherited: true }` marker at its exact inherited-prefix cut; the last tagged marker is the current Session's cut.
-- **session/event emit**: the single bus wiring — the log is not Cordis events; listeners hear via this one emit.
-- **deriveMessages() projection**: the surface ordering → LLM messages (see `subsystems/session.md`).
-- **Latest-wins fold events**: whole-value, non-surface state knobs whose LAST event is the session override — `plan/mode`, `sandbox/mode`, `approval/policy`, `session/title`, `todo/write`, `permission/preset`, `model/selection`.
-
-## Mental Models
-- Think of the **log as ground truth, the surface as derived history**: only `user/message`/`assistant/message`/`tool/result` join the model transcript; everything else is replayable audit.
-- Think of **compaction as a surface `replace` + an adjacent metering event**: the replacement is priced by the event directly before it, never by per-node bookkeeping.
-- Use **`ignorable: true` sparingly**: defaulting to *required* means a forgotten marker over-refuses (inconvenience) rather than silently resuming a gutted session.
-- Treat **state knobs as latest-wins**: the projection unit folds the log to the last event; the model learns policy from runtime-context snapshot + live notices, not from these events.
-
-## Anti-patterns
-- **Silently dropping an unrecognized required event**: readers must refuse reconstruction unless `ignorable: true` is set — loss can change how the remaining log is interpreted.
-- **A plugin appending `session/end-seed`**: only the `Session` constructor is a legitimate writer; a plugin doing so silently classifies every live bracket before it as seed history.
-- **Appending a non-JSON-serializable `tool/result` `meta`**: rejected at `Session.append` (isJsonValue); the producing tool owns `meta` shape but it MUST be JSON.
-- **Treating a log event as a Cordis event**: the durable log reaches listeners only through `session/event`; do not wire Cordis event listeners to it.
-
-## Code Examples
-```ts
-export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result'
-export type SurfaceOp = 'append' | { op: 'replace'; start: SessionSeq; end: SessionSeq }
-export type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K; seq: SessionSeq; time: number; data: SessionEventMap[K]; ignorable?: true
-  } & (K extends SurfaceEventType
-      ? { sourceEventSeqs?: SessionSeq[]; surfaceOp?: SurfaceOp }
-      : object)
-}[T]
-```
-```ts
-// Shadow price (compaction): metering event immediately precedes the replace.
-'compaction/prune': {
-  shadowedRange: { start: SessionSeq; end: SessionSeq }
-  shadowedSeqs: SessionSeq[]          // all shadowed surface nodes, surface order
-  shadowedTokenCount: number          // heuristic price, fixed estimator
-}
-// tool/call pairs with tool/result by callId; arguments kept as the model's raw JSON string.
-'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string }
-```
-
-## Reference Tables
-Full payload declarations + JSDoc live in `src/docs/persistence-catalog.md` (~38KB, generated by `gen-persistence-catalog`, verified by `verify-persistence-catalog`). ★ = surface type (the only ones joining the model transcript).
-
-| Family | Members | Badge |
-|---|---|---|
-| `user/*` | `user/message` | ★ surface |
-| `assistant/*` | `assistant/message` ★, `assistant/attempt` | surface + log-only |
-| `tool/*` | `tool/result` ★, `tool/call`, `tool/code-dispatch`, `tool/code-dispatch-start` | surface + log-only |
-| `turn/*` | `turn/start`, `turn/end` | log-only |
-| `step/*` | `step/start`, `step/end` | log-only |
-| `request/*` | `request/header`, `request/context` | log-only |
-| `session/*` | `session/end-seed`, `session/title`, `session/title-llm-request` | log-only |
-| `agent/*` | `agent/inbox/spliced` | log-only |
-| `agent-preset/*` | `agent-preset/selected` | log-only |
-| `approval/*` | `approval/asked`, `approval/decided`, `approval/policy` | log-only |
-| `sandbox/*` | `sandbox/mode` | log-only |
-| `permission/*` | `permission/preset` | log-only |
-| `plan/*` | `plan/mode` | log-only |
-| `model/*` | `model/selection` | log-only |
-| `command/*` | `command/run`, `command/done` | log-only |
-| `compaction/*` | `compaction/start`, `compaction/end`, `compaction/summary`, `compaction/prune` | log-only |
-| `feedback/*` | `feedback/record` | log-only |
-| `goal/*` | `goal/change` | log-only |
-| `hook/*` | `hook/invoked`, `hook/result` | log-only |
-| `llm/*` | `llm/retry`, `llm/retry-started` | log-only |
-| `schedule/*` | `schedule/change` | log-only |
-| `session-log-deepseek/*` | `session-log-deepseek/delivery-accepted` | log-only |
-| `subagent/*` | `subagent/descriptor`, `subagent/model-selection-policy` | log-only |
-| `team/*` | `team/member`, `team/task`, `team/message/queued`, `team/message/delivered` | log-only |
-| `todo/*` | `todo/write` | log-only |
-| `tool-workflow/*` | `tool-workflow/run-start`, `run-end`, `agent-start`, `agent-end` | log-only |
-| `web/*` | `web/deepseek-search-llm-request` | log-only |
-
-Envelope facts: `seq` = monotonic per-session; `time` = Unix epoch ms; `data` = `SessionEventMap[K]`; `ignorable?` skip marker; `sourceEventSeqs?`/`surfaceOp?` surface-only. A log-only event never carries surface metadata (compiler-enforced at `Session.append`).
-
-## Key Takeaways
-1. Only three event types touch the model transcript: `user/message`, `assistant/message`, `tool/result` — all others are log-only durable audit.
-2. A log event is **not** a Cordis event; wire to `session/event`, and project the surface with `deriveMessages()`.
-3. Default unrecognized events to *required* (refuse reconstruction); opt into `ignorable: true` only for loss-safe informational records.
-4. Compaction replaces surface nodes with `surfaceOp: { replace }`, priced by the metering event immediately before it (`compaction/summary` or `compaction/prune`).
-5. Versioning: writers stamp `SESSION_FORMAT_VERSION`; historical artifacts migrate via the build-static migration catalog — not by hand.
-6. Store layout / DSH_HOME anatomy / durability are **not** here — they are `subsystems/persistence.md`'s job; this catalog is the event-format vocabulary only.
-
-## Connects To
-- **Ch 13**: `Session.append`, `firstLiveSeq`, `deriveMessages()` projection — the core-session surface this log backs.
-- **Ch 16**: `fs/observed`, preset/audit state — the durable facts consumed as session data.
-- **Ch 17**: `TokenUsage` referenced by `assistant/message` and `compaction/summary` payloads.
-- **Ch 14**: the agent loop commits `turn/start`..`turn/end`, `step/start`..`step/end`, `tool/call`/`tool/result`.
-- **Ch 11**: tools emit `tool/call`, `tool/result`, `tool/code-dispatch*` as their durable effects.