dsh-ptc-plus 0.3.1 → 0.4.1

package/docs/README.md

@@ -3,6 +3,7 @@
 ## Getting Started
 
 - [Installation](installation.md): npm, Git, source, tarball, development snapshot, and Desktop installation.
+- [Global binding guide](user-bindings.en.md) ([中文](user-bindings.md)): author, review, save, configure, and test reusable helpers.
 - [Runtime Reference](runtime-reference.md): cell behavior, capability discovery, configuration, diagnostics, and limits.
 - [Evaluation](evaluation.md): paired ordinary-task protocol, metrics, configuration, and limitations.
 
@@ -13,9 +14,14 @@
 - [Program Data Plane](program-data-plane.md): canonical values and result completeness.
 - [Durable / Volatile Recovery](durability-design.md): replay model and external-input boundaries.
 - [PTC Value Graph V1](value-wire.md): supported JavaScript value encoding.
+- [Global User Bindings](adr/0023-global-user-bindings.md): persistent helper ownership, model projection, runtime activation, recovery, and Agent-assisted authoring.
+- [Binding Review Placement](binding-review-placement-design.md): the implemented full draft panel above the current composer, using the published input dock and one review controller.
+- [Logical Binding Identities](adr/0025-use-versioned-logical-binding-identities.md): stateful declarations, scope, candidate publication and language generations.
 - [Architecture Decisions](adr/): stable design constraints and their consequences.
 
 ## Maintenance
 
+- [Deterministic Verification](verification.md): complete checks, backend test concurrency, coverage, and focused diagnostics.
+- [Semantic Validation](semantic-validation.md): pinned Test262 cases, dialect contracts, native differential matrices and their limits.
 - [Publishing](publishing.md): release checks, package contents, permissions, and platform validation.
 - [Client UI](client-ui.md): current UI boundary and reevaluation criteria.

package/docs/adr/0004-declare-program-bindings-at-the-host.md

@@ -1,5 +1,5 @@
 # Declare Program Bindings At The Owner
 
-PTC Plus does not create a private cross-plugin registry or reflective invocation bus. The current public CodeRuntime request surface has no registry for discovering non-tool program bindings.
+PTC Plus does not create a private cross-plugin registry or reflective invocation bus. The public execution-seam request surface ([ADR 0028](0028-attach-to-the-host-ptc-execution-seam.md)) has no registry for discovering non-tool program bindings.
 
 If DSH later provides one, capability owners should publish explicit typed contracts, semantic metadata, source references, and binding factories. DSH should own discovery, scope, authority, leasing, dispatch, and settlement. Explicit registration, generated manifests, decorators, or scanning are assembly choices; none replaces those contracts. PTC Plus would consume only bindings already present in the live request.

package/docs/adr/0006-rewrite-module-syntax-with-an-ast.md

@@ -1,16 +1,18 @@
 # Rewrite Module Syntax With An AST
 
+The AST and native module-resolution decision remains in force. The alias storage, readonly writes and collision rules below describe the frozen `legacy-v1` compiler; [ADR 0025](0025-use-versioned-logical-binding-identities.md) supersedes those rules for new cells and unifies plugin-owned module compilation. `internal/legacy-cell-rewriter.js`, `internal/legacy-cell-parser.js` and `internal/legacy-cell-analysis.js` preserve that historical contract.
+
 ## Problem
 
 PTC Plus evaluates each cell as an async function body, where static `import` and `export` declarations are syntactically invalid. The adapter must accept TypeScript type syntax, preserve cell-relative source positions and line counts, classify the rewritten program for replay durability, record every automatic rewrite, and reject malformed or unrecognized module syntax without partially deleting or transforming it. Token-by-token text scanning duplicated parser responsibilities and could accept a recognized prefix while leaving an invalid suffix or erase malformed type-only declarations.
 
 ## Decision
 
-[`internal/cell-rewriter.js`](../../internal/cell-rewriter.js) owns module-syntax adaptation. `@babel/parser` parses the original cell with its TypeScript plugin under script semantics while explicitly allowing top-level module declarations, `return`, and `await`; recognizing a module declaration therefore does not impose module strict mode on the surrounding async-function body. Before any edit or module preload record is produced, `@babel/traverse` builds the original Program scope. Its declaration and hoisting rules reject same-scope collisions between value imports and lexical, `var`, function, or other import bindings while retaining block shadowing and the separate TypeScript type namespace. The same scope validates local exports and drives imported-reference rewriting, supplemented by top-level TypeScript declaration names because Babel intentionally excludes the type namespace from runtime scope. The rewriter derives every accepted import, export, type-only declaration, specifier, source value, and edit range from that AST. One batch edit assembler validates non-overlapping ranges, produces generated source, and composes source mappings without rebuilding either artifact per edit. [`internal/cell-analysis.js`](../../internal/cell-analysis.js) then wraps the rewritten cell as an async function body and first parses it with Acorn. Already-valid JavaScript proceeds unchanged; only a cell that Acorn cannot parse is passed through Node's `stripTypeScriptTypes` and parsed again for binding and durability analysis.
+[`internal/legacy-cell-rewriter.js`](../../internal/legacy-cell-rewriter.js) owns historical module-syntax adaptation. `@babel/parser` parses the original cell with its TypeScript plugin under script semantics while explicitly allowing top-level module declarations, `return`, and `await`; recognizing a module declaration therefore does not impose module strict mode on the surrounding async-function body. Before any edit or module preload record is produced, `@babel/traverse` builds the original Program scope. Its declaration and hoisting rules reject same-scope collisions between value imports and lexical, `var`, function, or other import bindings while retaining block shadowing and the separate TypeScript type namespace. The same scope validates local exports and drives imported-reference rewriting, supplemented by top-level TypeScript declaration names because Babel intentionally excludes the type namespace from runtime scope. The rewriter derives every accepted import, export, type-only declaration, specifier, source value, and edit range from that AST. One batch edit assembler validates non-overlapping ranges, produces generated source, and composes source mappings without rebuilding either artifact per edit. [`internal/legacy-cell-parser.js`](../../internal/legacy-cell-parser.js) owns executable parsing of the prepared cell: it wraps the rewritten cell as an async function body, parses it with Acorn, and relocates every returned AST range to original-cell coordinates. Already-valid JavaScript proceeds unchanged; only a cell that Acorn cannot parse is passed through Node's `stripTypeScriptTypes` and parsed again. [`internal/legacy-cell-analysis.js`](../../internal/legacy-cell-analysis.js) consumes that single parse for binding and durability analysis.
 
-Each static import or remote re-export creates an ordered module preload record. A value-bearing record carries its source, import attributes, original position, generated temporary-global identifier, and the default or named exports required by its AST specifiers. The dedicated worker uses Node's synchronous module resolve hook to give REPL imports and static-link adapters one parent at the session cwd, falling back to the worker process cwd when the session has no recorded cwd. Node's ESM resolver therefore owns relative URLs, bare packages, conditional `exports`, URL schemes, import conditions, and platform path conversion; plugin and target-module dependency imports retain their natural parents. Each ephemeral data-URL adapter expresses the required members as static re-exports, so Node completes export linkage before evaluating the target module, then returns the namespace for a value-bearing preload. The worker resolves records before compiling the cell and exposes each namespace under its temporary identifier. One generated lexical prologue after the original directive prologue and before every executable cell statement captures each temporary identifier into a distinct persistent namespace identifier in source order; import declarations are erased at their original ranges, and the temporary globals are removed when the cell settles. Both identities are allocated outside current source identifiers, persistent REPL bindings, reserved program bindings, and every live private namespace. The prologue references the generated host identifier directly, so a lexical `globalThis` binding has ordinary JavaScript semantics and cannot redirect capture. A binding catalog stores only the persistent namespace identity and maps public import aliases to it and the export name; scope-aware rewriting routes unshadowed reads through the namespace, keeps bare, optional, and tagged calls detached from the namespace receiver with the language's comma-reference form, and lowers writes to a deterministic `TypeError`. Private namespace names remain reserved after a public alias is redeclared, so closures from earlier cells cannot be redirected by a later import. The catalog is rebuilt during journal replay. In loose REPL mode an explicit later declaration replaces the alias for future cells, while closures compiled before that declaration retain their namespace read. Destructuring, loop, nested, and delete writes that cannot preserve native evaluation semantics are rejected before execution. Direct `eval` and `WithStatement` are rejected on the original Program while value import aliases are active because generated namespace reads cannot reproduce their dynamic lexical resolution; this validation precedes module preload. Indirect or locally shadowed eval, non-strict `with` without value aliases, and cells containing only type imports retain ordinary JavaScript semantics. Side-effect, default, namespace, named, default-plus-named, and default-plus-namespace forms remain supported. Export modifiers are removed while declarations remain; default exports bind the fixed public name `__default`; anonymous default function and class lowering emits an explicit statement terminator, while default expressions retain their parsed continuation; remote re-exports become preload-only side-effect modules; local export lists are removed; and declaration-level or specifier-level type-only syntax is erased.
+Each static import or remote re-export creates an ordered module preload record. A value-bearing record carries its source, import attributes, original position, generated temporary-global identifier, and the default or named exports required by its AST specifiers. The dedicated worker uses Node's synchronous module resolve hook to give REPL imports and static-link adapters one parent at the session cwd, falling back to the worker process cwd when the session has no recorded cwd. Node's ESM resolver therefore owns relative URLs, bare packages, conditional `exports`, URL schemes, import conditions, and platform path conversion; plugin and target-module dependency imports retain their natural parents. Each ephemeral data-URL adapter expresses the required members as static re-exports, so Node completes export linkage before evaluating the target module, then returns the namespace for a value-bearing preload. The worker resolves records before compiling the cell and exposes each namespace under its temporary identifier. One generated lexical prologue after the original directive prologue and before every executable cell statement captures each temporary identifier into a distinct persistent namespace identifier in source order; import declarations are erased at their original ranges, and the temporary globals are removed when the cell settles. Both identities are allocated outside current source identifiers, persistent REPL bindings, reserved program bindings, and every live private namespace. The prologue references the generated host identifier directly, so a lexical `globalThis` binding has ordinary JavaScript semantics and cannot redirect capture. A binding catalog stores only the persistent namespace identity and maps public import aliases to it and the export name; scope-aware rewriting routes unshadowed reads through the namespace, keeps bare, optional, and tagged calls detached from the namespace receiver with the language's comma-reference form, and lowers writes to a deterministic `TypeError`. Private namespace names remain reserved after a public alias is redeclared, so closures from earlier cells cannot be redirected by a later import. The catalog is rebuilt during journal replay. In loose REPL mode an explicit later declaration replaces the alias for future cells, while closures compiled before that declaration retain their namespace read. Destructuring, loop, nested, and delete writes that cannot preserve native evaluation semantics are rejected before execution. Direct `eval` and `WithStatement` are rejected on the original Program while value import aliases are active because generated namespace reads cannot reproduce their dynamic lexical resolution; this validation precedes module preload. Indirect or locally shadowed eval, non-strict `with` without active aliases, and cells containing only type imports retain ordinary JavaScript semantics. Side-effect, default, namespace, named, default-plus-named, and default-plus-namespace forms remain supported. Export modifiers are removed while declarations remain; default exports map the fixed public name `__default` through the same alias lowering to a generated persistent private slot. Later default exports update that slot at their source position independently of variable-redeclaration policy, and the binding catalog adopts the alias definition only after the worker reports the generated post-update commit signal. This keeps `__default` live and read-only while preventing an early return or failed class evaluation from publishing an update that did not execute. Anonymous default function and class lowering emits an explicit statement terminator, while default expressions retain their parsed continuation; remote re-exports become preload-only side-effect modules; local export lists are removed; and declaration-level or specifier-level type-only syntax is erased.
 
-The rewriter normalizes Babel syntax and local-export validation failures as original-cell positions before they cross the module boundary. Executable wrapper parsing retains Acorn's wrapper-relative positions, and only those positions receive the one-line wrapper subtraction during `PTC-C001` rendering. [`internal/cell-analysis.js`](../../internal/cell-analysis.js) then applies return, redeclaration, collision, and durability analysis to the successfully rewritten program. Return control-flow lowering addresses its per-cell worker-global signal through the top-level `this` receiver, which bypasses both lexical `globalThis` shadowing and `with` object-environment resolution; worker startup validates that this receiver is the evaluator's global context, and settlement removes the signal property. Lowered returns emit an explicit statement terminator so a return in a `switch` clause remains valid after replacement. Rewrite provenance remains parallel to the closed journal schema under `meta.dshPtcPlusRewrites` and does not alter replay equality. A successful rewrite remains private audit metadata; only a failed rewrite or missing valid journal may project its description as a bounded recovery context.
+The rewriter normalizes Babel syntax and local-export validation failures as original-cell positions before they cross the module boundary. Executable parsing normalizes AST ranges and parse failures to original-cell coordinates inside that parse owner, so `PTC-C001` renders `ModuleRewriteError.cellPosition` without applying any wrapper offset; a failure raised while parsing the module-rewrite output is mapped back through that rewrite's source map before preparation returns. [`internal/legacy-cell-analysis.js`](../../internal/legacy-cell-analysis.js) then applies return, redeclaration, collision, and durability analysis to the successfully rewritten program. Return control-flow lowering addresses its per-cell worker-global signal through the top-level `this` receiver, which bypasses both lexical `globalThis` shadowing and `with` object-environment resolution; worker startup validates that this receiver is the evaluator's global context, and settlement removes the signal property. Lowered returns emit an explicit statement terminator so a return in a `switch` clause remains valid after replacement. Rewrite provenance remains parallel to the closed journal schema under `meta.dshPtcPlusRewrites` and does not alter replay equality. A successful rewrite remains private audit metadata; only a failed rewrite or missing valid journal may project its description as a bounded recovery context.
 
 ## Alternatives considered
 
@@ -42,4 +44,4 @@ The rewriter normalizes Babel syntax and local-export validation failures as ori
 
 ## Consequences
 
-Each accepted transformation corresponds to a complete TypeScript AST node, and every automatic type erasure produces provenance without recovering module names from source text. Static modules resolve from the session project in source order before cell compilation; their aliases are initialized before body execution regardless of textual declaration position or an earlier return. A resolution, linkage, or evaluation failure leaves REPL declarations and aliases uncommitted, although a successfully completed earlier preload may already have produced effects. A preload with a missing requested export does not evaluate its target module. Imported reads add one namespace property access; bare, optional, and tagged calls use an indirect reference so the namespace cannot become `this` and nullish optional calls still short-circuit. Malformed module or type syntax and unsupported imported writes fail before execution. The production dependency set includes `@babel/parser` and `@babel/traverse`; Acorn remains the executable-JavaScript and scope-analysis authority downstream. Module resolution uses Node's `registerHooks` primitive available at the engine floor. Node's `stripTypeScriptTypes` is invoked only when the rewritten cell is not already valid JavaScript and remains experimental at the current engine floor, so the compatibility suite must be rerun when the supported Node version changes.
+Each accepted transformation corresponds to a complete TypeScript AST node, and every automatic type erasure produces provenance without recovering module names from source text. Static modules resolve from the session project in source order before cell compilation; their aliases are initialized before body execution regardless of textual declaration position or an earlier return. A resolution, linkage, or evaluation failure leaves REPL declarations and aliases uncommitted, although a successfully completed earlier preload may already have produced effects. A preload with a missing requested export does not evaluate its target module. Imported reads add one namespace property access; bare, optional, and tagged calls use an indirect reference so the namespace cannot become `this` and nullish optional calls still short-circuit. Malformed module or type syntax and unsupported imported writes fail before execution. The production dependency set includes `@babel/parser`, `@babel/traverse`, and `acorn`; Acorn remains the executable-JavaScript and scope-analysis authority downstream. TypeScript lowering of global binding modules is a separate mechanism with its own owner, [`internal/typescript-transform.js`](../../internal/typescript-transform.js), which pins its transform generation and does not parse or rewrite cells ([ADR 0023](0023-global-user-bindings.md)). Module resolution uses Node's `registerHooks` primitive available at the engine floor. Node's `stripTypeScriptTypes` is invoked only when the rewritten cell is not already valid JavaScript and remains experimental at the current engine floor, so the compatibility suite must be rerun when the supported Node version changes.

package/docs/adr/0007-separate-worker-transport-from-session-semantics.md

@@ -8,7 +8,11 @@ The session runtime coordinates two different lifecycles: transport ownership fo
 
 [`internal/worker-client.js`](../../internal/worker-client.js) exclusively owns worker creation, the readiness handshake, the private port, bounded stderr capture, reset, concurrent termination tracking, scratch allocation, and scratch cleanup. It reports private-channel messages and terminal failures through callbacks. [`internal/session-runtime.js`](../../internal/session-runtime.js) owns the active cell and decides how a reported message or failure settles the journal, durability state, replay transaction, or binding call. Messages reach the kernel only from the client's current worker, while each active semantic transaction retains its worker identity for lease and replay checks.
 
-Cross-process policy that must agree on both sides has one source. [`internal/module-policy.js`](../../internal/module-policy.js) defines durable imports, forbidden kernel-control imports, and ambient globals for both static analysis and the worker runtime. [`internal/failure-reporting.js`](../../internal/failure-reporting.js) defines hostile-error normalization, active-cell stack extraction, bounded diagnostic logs, and repeat-failure tracking for the host and worker. Session-log recovery belongs to [`internal/session-journal.js`](../../internal/session-journal.js), which owns journal shape, event association, and branch folding. Live durable nodes, current-call exclusion, no-op confirmations, recovery boundaries, and cold nodes all use persisted `tool/call.seq` identity. During live dispatch, the journal owner uses `callId` only to resolve the unique unpaired top-level call, then passes its sequence into semantic state. Sessionless direct runtime calls do not fabricate a persisted identity. Journal v3 stores confirmed no-ops as sequences; v2 journals with empty confirmations migrate without ambiguity, while a v2 call-id confirmation forms an unknown suffix. A failed durable replay records one log-only recovery boundary in the current settled `tool/result` metadata under `meta.dshPtcPlusRecoveryBoundaries`; its payload identifies the failed call event and its parent frontier without inventing a DSH event type. Every boundary is normalized as it enters recovery, before its event sequence participates in ordering; malformed boundary data therefore rejects reconstruction instead of disappearing from the fold. A completed record enters branch folding at its `tool/result` event position because that event confirms durability. Folding leaves immutable call/result events intact, removes the failed node and dependent descendants, and recomputes checkpoints from the remaining records. [`internal/session-runtime.js`](../../internal/session-runtime.js) resets the worker and retries the contracted frontier, recursively reaching the empty REPL only if every earlier candidate also fails. The exported migration helper converts old custom boundary events into this metadata before DSH restores a session and never mutates its input.
+Cross-process policy that must agree on both sides has one source. [`internal/module-policy.js`](../../internal/module-policy.js) defines durable imports, forbidden kernel-control imports, and ambient globals for both static analysis and the worker runtime. [`internal/failure-reporting.js`](../../internal/failure-reporting.js) defines hostile-error normalization, active-cell stack extraction, bounded diagnostic logs, and repeat-failure tracking for the host and worker. Session-log recovery belongs to [`internal/session-journal-recovery.js`](../../internal/session-journal-recovery.js), which owns event association and branch folding; the closed field sets and generation constants belong to [`internal/session-journal-schema.js`](../../internal/session-journal-schema.js), and journal validation, migration, and creation belong to [`internal/session-journal.js`](../../internal/session-journal.js). Live durable nodes, current-call exclusion, no-op confirmations, recovery boundaries, and cold nodes all use persisted `tool/call.seq` identity. During live dispatch, the journal owner uses `callId` only to resolve the unique unpaired top-level call, then passes its sequence into semantic state. Sessionless direct runtime calls do not fabricate a persisted identity. Journal v3 stores confirmed no-ops as sequences; v2 journals with empty confirmations migrate without ambiguity, while a v2 call-id confirmation forms an unknown boundary. A failed durable replay records one log-only recovery boundary in the current settled `tool/result` metadata under `meta.dshPtcPlusRecoveryBoundaries`; its payload identifies the failed call event and its parent frontier without inventing a DSH event type. Every boundary is normalized as it enters recovery before its event sequence participates in ordering. Malformed boundary or association data is rejected as evidence for old state, but it does not turn historical plugin metadata into an availability gate for the current valid call. A completed record enters branch folding at its `tool/result` event position because that event confirms durability. Folding leaves immutable call/result events intact, removes unproved nodes and dependent descendants, and recomputes checkpoints from the remaining records. [`internal/session-runtime.js`](../../internal/session-runtime.js) resets the worker and retries the greatest verified frontier, recursively reaching the empty REPL if every non-empty candidate fails, then executes the current cell against that actual state. The contraction is recorded on the current settled result and reported once so later recovery does not repeatedly encounter the same boundary. The exported migration helper converts old custom boundary events into this metadata before DSH restores a session and never mutates its input.
+
+Recovery is conservative about state and best-effort about availability. A post-boundary cell or binding may be retained only when owned evidence mechanically proves that its ancestry or independence does not cross the unknown boundary. The current journal does not contain a complete per-binding dependency graph, so recovery treats a cell as atomic and discards its affected suffix when it cannot prove a finer partition. This can lose bindings, including all bindings in the empty-frontier case, but never claims that an unverified heap or historical effect was restored. DSH policy and failures of the current request remain outside this fallback.
+
+The selected frontier must also agree with the state the model can know when it produces the current call. DSH's append-only session log owns durable evidence, while its ordered surface and derived request history own model visibility; raw events shadowed from that surface do not become model knowledge merely because replay can still read them. UI-only `dshPtcPlusBindings` metadata also does not qualify. A cell remains eligible when a result-only replacement leaves the assistant tool call carrying its exact source on the model-visible surface. When compaction shadows that provenance, the live or cold runtime contracts the affected cell and descendants unless an explicitly selected bounded model-visible structure publishes the exact surviving state. Such a projection is not injected by default merely to retain hidden bindings. Recovery never parses a natural-language summary into binding proof. Surface replacement generation is checked before a later cell uses an already-live worker, so this rule is not cold-start-only.
 
 ## Alternatives considered
 
@@ -32,8 +36,16 @@ Cross-process policy that must agree on both sides has one source. [`internal/mo
 
 **Always recover from an empty REPL.** This guarantees a clean worker but discards verified bindings and checkpoints unnecessarily. Parent-by-parent contraction retains the largest frontier whose replay actually succeeds.
 
-**Compare raw boundary sequences before decoding boundary events.** This appears to avoid work for boundaries after the current record, but an absent or nonnumeric sequence is not orderable and can evade the decoder entirely. Normalizing at session-log ingestion gives the fold one trusted boundary shape and makes damaged history fail closed.
+**Reject every future cell until malformed history is repaired.** This preserves a simple reconstruction invariant but lets plugin-owned optimization metadata permanently disable `run_code` in an otherwise usable DSH conversation. Rejecting an unproved binding is required; refusing the current valid call is not. The runtime instead contracts to verified state or an empty REPL and lets the current cell establish a new branch.
+
+**Recover arbitrary bindings after an unknown boundary.** This retains more names in favorable cases, but source text and completion equality do not prove the values, mutations, closures, or transitive reads that produced those bindings. Fine-grained retention requires explicit owned dependency evidence; absent that evidence, the whole affected cell or suffix is discarded.
+
+**Treat every raw-log durable node as model-knowable.** This maximizes continuity after compaction, but can expose names and values whose declaration is absent from the request history that produced the current call. Durability proves reconstruction, not awareness. The runtime uses the intersection of durable and model-visible provenance instead.
+
+**Parse the compaction summary for binding names.** A natural-language summary can omit, rename, or ambiguously describe bindings and does not carry an owner-proven relation to journal nodes. Only an explicit structured model-visible projection can preserve state after exact source provenance leaves the surface.
+
+**Compare raw boundary sequences before decoding boundary events.** This appears to avoid work for boundaries after the current record, but an absent or nonnumeric sequence is not orderable and can evade the decoder entirely. Normalizing at session-log ingestion lets the fold reject the damaged record as state evidence and place a conservative contraction boundary without silently accepting it.
 
 ## Consequences
 
-Worker resource cleanup and startup failures are independently testable, while the kernel retains one owner for journal and replay meaning. The client callback is deliberately narrow: it carries transport facts, not journal decisions. Recovery metadata stays private to the settled `tool/result`; it does not change tool schemas, model messages, truthful top-level tool identity, `edit_run_code`, or recorded-value replay. Adding a private protocol message still requires a kernel handler and contract tests because the client does not interpret semantic payloads. Shared policy modules become load-bearing single sources and must remain usable in both the main thread and worker without importing session state.
+Worker resource cleanup and startup failures are independently testable, while the kernel retains one owner for journal and replay meaning. The client callback is deliberately narrow: it carries transport facts, not journal decisions. Recovery metadata stays private to the settled `tool/result`; it does not change tool schemas, truthful top-level tool identity, `edit_run_code`, or recorded-value replay. The runtime consumes DSH's public surface contract without copying its projection algorithm or adding a DSH version whitelist. A contraction caused by damaged or no-longer-model-visible history can remove previously available bindings, so the first continued cell receives one bounded diagnostic and may need to redeclare them; historical program-binding effects are neither replayed nor described as undone. Adding a private protocol message still requires a kernel handler and contract tests because the client does not interpret semantic payloads. Shared policy modules become load-bearing single sources and must remain usable in both the main thread and worker without importing session state.

package/docs/adr/0009-bound-expensive-acceptance-default.md

@@ -16,6 +16,8 @@ The edit canary covers both a completed cell whose result needs adjustment and a
 
 Both model-backed runners complete keyless verification and resolved-config validation before model invocation. They then run one complete representative canary sequentially and audit its process result, session log, tool transport, runtime contexts, budgets, and task oracle before scheduling broader scenarios, replicates, or concurrency. A canary failure stops the run without starting the remaining paid work. Deterministic tests remain the authority for AST rewrite variants and the acceptance contract itself. The ordinary-task A/B canary is the stable fixture's fixed, cheap, machine-checkable transport task rather than a full repository test run; see ADR 0018.
 
+Resolved tools settings are independently validated by DSH's public configuration schema, in addition to the runner's policy comparison. Workload-specific inspection symbols and operation limits belong to the scenario's `programWork` expectations. These limits use canonical argument evidence and include failed calls; identical arguments never authorize runtime deduplication or prove observation freshness. The fixed typed fixture permits one native read and reuse of that observation. Guarded edits reuse the canonical editor and dispatch-time target projection; explicitly expected guard mismatches require a non-executing result without derived metadata. Deterministic coverage of these contracts does not enlarge the default paid cohort.
+
 Machine acceptance and stochastic comparison are separate from blind semantic review. A/B output reports machine pass or failure independently and keeps overall approval pending until the blind packets have been evaluated; producing packets is not evidence that their review is complete.
 
 ## Alternatives considered

package/docs/adr/0010-session-log-derived-recovery-tips.md

@@ -2,21 +2,75 @@
 
 ## Problem
 
-The persistent REPL contract must stay short enough for every request, while some failures need a model-visible recovery affordance. Repeated binding failures and platform-specific command errors benefit from a precise next action. A real `edit_run_code` call already carries its identity, arguments, and result; restating those facts in a runtime context wastes tokens and causes DSH to append a new aggregate snapshot containing unrelated contributions. Long failed cells are a separate trigger: after the failure is persisted, a bounded context may distinguish a journal-proven no-execution edit candidate from a possibly effectful failure.
+The persistent REPL contract must stay short enough for every request, while some failures need a model-visible recovery affordance. Repeated binding failures and platform-specific command errors benefit from a precise next action. A real `edit_run_code` call already carries its identity, arguments, and result; restating those facts wastes tokens. The former aggregate runtime-context path also repeated unrelated owner contributions whenever any PTC contribution changed. Long-cell failure guidance belongs in the current diagnostic, where pre-execution rejection and possibly effectful failure can be distinguished.
 
 ## Decision
 
-PTC Plus keeps the stable REPL guidance limited to invariants, discovery entry points, and environment-neutral boundaries. `internal/session-log-view.js` scans the event sequence once, pairs settled calls within each open turn, validates execution journals and rewrite records once, and returns immutable facts for edit targeting, successful-run reset, context distance, normalized Cordis call/inspection counts, and canonical DSH system-prompt snapshots. Each snapshot preserves its named sections. `internal/runtime-contexts.js` renders rewrite feedback only when the rewritten cell failed or lacks a valid journal, the fixed `tools:ptc-plus-cordis-recovery` context when a new agent or Cordis enable generation contains historical Cordis transcript without a newer successful live Inspect, plus at most one context from the reserved `tools:ptc-plus-tip/<trigger>/<ordinal>` name family. Successful transparent rewrites remain result metadata and do not create aggregate snapshot churn. It never emits edit provenance or target-lifecycle context: those facts belong to the registered tool call/result and its private derived-execution metadata. These contexts never change the tool list, tool schemas, or system sections.
+PTC-owned dynamic information uses independently sourced, accepted DSH messages.
+Unproved rewrite completion and Cordis recovery form a bounded `ptc-plus`
+`snapshot` with named sections. Configured Global User Binding documentation uses
+DSH's existing `catalog` form, independently of transient recovery state. A recovery tip is a `ptc-plus` `notice` whose
+structured summary is its trigger/ordinal name. A snapshot supersedes only prior
+PTC state snapshots, including PTC sections in historical DSH aggregate snapshots;
+it never supersedes a binding catalog, authoring task, Skill instructions, a tool result, or
+another producer. An empty snapshot explicitly invalidates earlier PTC state.
 
-The default triggers are a repeated binding failure and a failure whose diagnostic or structured cause identifies an executable, shell, or path problem. The first tip is concise. A matching trigger may produce another tip only after `tipCooldownMessages` model-context steps; unresolved matching tips reach the detailed form after `tipEscalationFailures` occurrences. A successful cell resets the unresolved escalation count. Every emitted tip name carries its stable trigger identity and next per-trigger ordinal. Reconstruction accepts only canonical snapshots from DSH's system-prompt owner, treats a named section as one effective-state transition even when another owner's aggregate update repeats it, and ignores legacy or malformed plugin prose. Visible wording does not determine cooldown or escalation identity.
+The binding catalog contains one bounded literal configuration document with a
+fixed owner prefix; its reader recognizes that prefix only within a `ptc-plus`
+`catalog` source. Only a later binding catalog replaces it; an explicit empty
+catalog withdraws it. Host runtime-context clearances and PTC recovery snapshots
+do not withdraw catalogs. Suppression prevents new delivery without changing the
+meaning of a retained catalog. This is API documentation, not proof of successful
+initialization, current values, or recoverable session-local state. The historical
+snapshot reader remains intact: an accepted recovery snapshot retires old binding
+sections once, while a catalog supplies the current configuration. No history or
+journal is rewritten. Catalog and recovery changes never resend each other's text.
 
-Platform wording names execution-world differences without assuming Windows, WSL, POSIX, a shell, or package-runner availability. `edit_run_code` remains independently available as a fixed real tool and does not depend on a recovery-tip trigger.
+The binding catalog wrapper names `run_code` as the invocation location and
+limits replacement to the previous global binding API reference. Its body contains
+only entry labels, optional user prompts and selected declarations; checkpoint
+instructions belong to `repl.state` discovery, and authoring instructions belong
+to the `/binding` task. Initialization failures are reported by execution results.
+Readers accept the exact bounded historical wrappers and empty marker as
+well as the emitted form. A wording change does not reinterpret old records or
+require journal migration. Catalog bodies are compared literally, so revised
+documentation can cause one replacement on upgrade and is then deduplicated.
+
+The public `systemPrompt.context` registry contains one empty PTC delivery witness.
+DSH omits this contribution when `includeRuntimeContext` is false or a scoped
+runtime-context suppressor applies; the empty text never enters its rendered
+aggregate. The assembly listener captures that witness and the exact request's
+PTC facts, leaving unrelated aggregate content unchanged. `agent/pre-step`
+delegates its waterfall first and adds messages only to an accepted, non-cancelled
+step matching that assembly. It neither calls `inject` after inbox claim nor wakes
+the agent with `steer`, and it cannot override admission or runtime suppression.
+
+Delivery is reconstructed from committed messages, never from a proposed step.
+The public ordered Session surface identifies retained current-state snapshots;
+historical aggregate state includes DSH's exact owner-sourced clearance marker.
+An accepted step's pending aggregate replacement can withdraw an old PTC section,
+requiring an independent current declaration in that same step.
+Raw committed history identifies delivered tip ordinals and cooldown distance,
+but cannot make hidden bindings model-visible. Compaction or removal of a state
+snapshot requires a fresh eligible state or an explicit clear. Suppressed steps
+send nothing; the next permitted step reconciles claims. Disabled PTC mode retains
+only the settings surface and a passive presentation cleanup listener, which can
+clear previously delivered claims without mounting runtime tools, reading binding
+storage, or publishing new declarations. Plugin/agent disposal releases pending
+assembly ownership. Resume reconstructs from the same durable source records.
+
+PTC Plus keeps the stable REPL guidance limited to invariants, discovery entry points, and environment-neutral boundaries. `internal/session-log-view.js` projects immutable facts for edit targeting, successful-run reset, context distance, normalized Cordis call/inspection counts, canonical historical DSH snapshots, and formed PTC messages. `internal/runtime-contexts.js` renders rewrite feedback only when the rewritten cell lacks a valid journal, Cordis recovery while historical transcript lacks a newer successful live Inspect, and at most one recovery tip. Known failures already carry partial-execution and retry guidance in their result, so they do not generate duplicate rewrite feedback. `internal/runtime-messages.js` owns bounded message forms: snapshot sections total at most 65536 UTF-16 code units and recognize the two historical binding sections for retirement; a catalog body is at most 65536 code units, with the tighter configured-declaration budget still enforced by the binding owner; a notice is at most 8192 code units with a valid trigger/ordinal identity. Malformed records are not delivery evidence. Transparent rewrites remain result metadata. Edit provenance and target lifecycle remain in real call/results and private derived-execution metadata. These messages never change the tool list, tool schemas, or system sections.
+
+The default triggers are a repeated binding failure and a failure whose diagnostic or structured cause identifies an executable, shell, or path problem. The first tip is concise. A matching trigger may produce another tip only after `tipCooldownMessages` model-context steps; unresolved matching tips reach the detailed form after `tipEscalationFailures` occurrences. A successful cell resets the unresolved escalation count. Every emitted tip name carries its stable trigger identity and next per-trigger ordinal. Reconstruction merges valid PTC notices and canonical historical sections from DSH's system-prompt owner, counting each delivered identity once across both sources. Unformed tasks and malformed plugin prose are not tip evidence. Visible wording does not determine cooldown or escalation identity; an exhausted safe-integer ordinal yields no further tip.
+
+Platform wording names execution-world differences without assuming Windows, WSL, POSIX, a shell, or package-runner availability. Bounded multiline message/stderr facts may supply a missing cause, but generic exit failure alone does not prove an environment problem. Repeated lexical failures point to visible source, scope and initialization; discovery is reserved for worker-owned capability failures. Warning state describes the failed cell conservatively, not the act of emitting a warning. `edit_run_code` remains independently available as a fixed real tool and does not depend on a recovery-tip trigger; a validated result repair only proves syntax/preflight acceptance and retains the target guard and complete-cell execution contract.
 
 The Cordis recovery context is not a failure tip and is not controlled by fatigue settings. It narrows the meaning of recorded values after a lifecycle boundary: they remain historical program data but cannot prove current process-local state. It clears only after a newly settled successful `cordis_inspect*` transcript, does not infer whether the original process survived, and never redispatches a historical effect.
 
 ## Alternatives considered
 
 - **Keep all recovery instructions in the stable system prompt.** This makes every request pay for rare failures and makes platform-specific text look universally applicable.
+- **Keep configured APIs inside recovery snapshots.** A short-lived recovery fact would resend unchanged interfaces on both entry and withdrawal. Catalogs already express the required public Host semantics; a new delta protocol or producer registry is unnecessary.
 - **Emit a tip after every matching failure.** This repeats stale advice, consumes context, and can encourage blind retry loops.
 - **Store mutable tip counters only in the kernel.** A worker restart or replay would then change model-visible behavior without a session-log source.
 - **Infer tip identity from rendered prose or one fixed section name.** Wording changes would reset history, unrelated plugin text could create false matches, and an unchanged aggregate context would not persist repeated occurrences.
@@ -26,4 +80,4 @@ The Cordis recovery context is not a failure tip and is not controlled by fatigu
 
 ## Consequences
 
-Normal requests receive only the persistent REPL invariants in stable system text. Prompt assembly performs one linear event projection regardless of how many PTC runtime contexts consume it; renderers receive facts rather than raw history or search callbacks. Failure recovery becomes an append-only, bounded context contribution with explicit cooldown and escalation semantics. Changing a tip's name records a new effective context even when compact wording repeats, while aggregate snapshots that repeat the same named section do not advance fatigue state. Tip wording and thresholds are configurable, but their defaults remain conservative; disabling tips removes only the runtime context and does not remove `edit_run_code` or any native capability.
+Normal requests receive only the persistent REPL invariants in stable system text. Renderers consume projected facts; accepted-step delivery rechecks committed history and the public surface before proposing bounded messages. A PTC transition appends no unrelated owner text, and another owner's aggregate transition does not resend unchanged PTC state. A new tip ordinal records a separate notice even when compact wording repeats, while repeated historical copies do not advance fatigue state. Tip thresholds are configurable; disabling tips stops future notices without removing `edit_run_code` or any native capability. Historical records require no migration.

package/docs/adr/0011-isolate-the-local-recovery-tip-provider.md

@@ -6,7 +6,7 @@ Recovery tips are a presentation policy, while PTC Plus owns the REPL, diagnosti
 
 ## Decision
 
-Keep the current deterministic recovery policy in `internal/recovery-tips.js` as a replaceable local provider. The provider consumes the immutable facts produced by `internal/session-log-view.js`; it does not traverse raw events, pair calls, parse journals, or query the core through callbacks. The core calls it only for a bounded named runtime context, and the provider does not change execution, journal semantics, tool schemas, or stable system text. Defer an external adapter until a public facts and decision contract exists; the adapter must be optional, fail closed, and leave the local provider or disabled mode available when absent.
+Keep the current deterministic recovery policy in `internal/recovery-tips.js` as a replaceable local provider. The provider consumes the immutable facts produced by `internal/session-log-view.js`; it does not traverse raw events, pair calls, parse journals, or query the core through callbacks. The core calls it for one bounded named tip, delivered as an independent PTC notice under [ADR 0010](0010-session-log-derived-recovery-tips.md). The provider does not change execution, journal semantics, tool schemas, or stable system text. Defer an external adapter until a public facts and decision contract exists; the adapter must be optional, fail closed, and leave the local provider or disabled mode available when absent.
 
 ## Alternatives considered
 

package/docs/adr/0012-preserve-mixed-destructuring-initialization.md

@@ -1,12 +1,14 @@
 # Preserve Mixed Destructuring Initialization
 
+The historical behavior below is retained by the frozen `legacy-v1` compiler. New cells use the logical identities and complete declarator publication in [ADR 0025](0025-use-versioned-logical-binding-identities.md).
+
 ## Problem
 
 Loose cross-cell redeclarations must assign names that already exist while introducing fresh names from one top-level destructuring declarator. A text-level whole-pattern assignment can preserve simple values, but it changes JavaScript binding initialization when a default expression refers to an earlier fresh binding, and a generated helper can also change top-level `await` or initializer ordering.
 
 ## Decision
 
-`internal/repl-convenience.js` evaluates the initializer as a helper argument, then runs the original destructuring pattern unchanged inside the helper. This leaves initializer references outside the new pattern scope while the JavaScript engine owns binding order, TDZ, computed keys, defaults, iterator handling, lexical shadowing, and abrupt completion inside the pattern. After the complete pattern succeeds, the helper passes every bound value positionally to a commit callback: existing names are assigned to their session bindings and fresh values are returned to one outer declaration. Arrays carry the positional values so names such as `__proto__` have no property-key semantics. A pattern containing direct `await` uses an async helper; a synchronous pattern stays synchronous. Declarator replacements remain in source order, and both lexical and `var` mixed declarations use the same native-pattern model with their corresponding outer declaration kind.
+`internal/legacy-repl-convenience.js` evaluates the initializer as a helper argument, then runs the original destructuring pattern unchanged inside the helper. This leaves initializer references outside the new pattern scope while the JavaScript engine owns binding order, TDZ, computed keys, defaults, iterator handling, lexical shadowing, and abrupt completion inside the pattern. After the complete pattern succeeds, the helper passes every bound value positionally to a commit callback: existing names are assigned to their session bindings and fresh values are returned to one outer declaration. Arrays carry the positional values so names such as `__proto__` have no property-key semantics. A pattern containing direct `await` uses an async helper; a synchronous pattern stays synchronous. Declarator replacements remain in source order, and both lexical and `var` mixed declarations use the same native-pattern model with their corresponding outer declaration kind.
 
 ## Alternatives considered
 

package/docs/adr/0013-isolate-repl-redeclaration-convenience.md

@@ -1,12 +1,18 @@
 # Isolate REPL Redeclaration Convenience
 
+The historical behavior below is retained by the frozen `legacy-v1` compiler. New cells use the logical identities and complete declarator publication in [ADR 0025](0025-use-versioned-logical-binding-identities.md).
+
 ## Problem
 
-The persistent REPL uses one worker lexical environment so later cells can refer to earlier top-level bindings. That convenience is not JavaScript's module or function semantics, and mixed old/new destructuring requires a policy for combining declaration and assignment. Keeping that policy inside `internal/cell-analysis.js` makes core parsing and durability analysis depend on one replaceable persistence strategy.
+The persistent REPL uses one worker lexical environment so later cells can refer to earlier top-level bindings. That convenience is not JavaScript's module or function semantics. Mixed old/new destructuring needs a policy for combining declaration and assignment, while ordinary iterative work also needs an explicit policy for replacing an earlier function or class declaration. Keeping either policy inside `internal/cell-analysis.js` makes core parsing and durability analysis depend on one replaceable persistence strategy.
 
 ## Decision
 
-`internal/cell-analysis.js` owns cell parsing, binding inventory, durability classification, return rewriting, and execution preparation. Shared binding-pattern traversal lives in `internal/binding-pattern.js`. `internal/repl-convenience.js` owns the optional loose-redeclaration policy, including all-existing replacement and mixed destructuring lowering; it returns executable source, collisions, redeclaration metadata, and rewrite provenance through one narrow function. The current persistent REPL continues to enable this policy, so the user-facing convenience and journal behavior remain unchanged. A future state/frame persistence implementation can replace this policy without changing the cell language analyzer.
+`internal/legacy-cell-analysis.js` owns legacy cell parsing, binding inventory, durability classification, return rewriting, and execution preparation. Shared binding-pattern traversal lives in `internal/binding-pattern.js`. `internal/legacy-repl-convenience.js` owns two independent, optional cross-cell policies: variable replacement (including mixed destructuring lowering) and named function/class replacement. It returns executable source, collisions, redeclaration metadata, and rewrite provenance through one narrow function. Both policies are enabled by default for the REPL workflow; function/class replacement can still be explicitly disabled with `looseTopLevelFunctionClassRedeclarations`.
+
+Only a top-level named `FunctionDeclaration` or `ClassDeclaration` whose name existed before preparation is eligible. Its catalog provenance must prove that the existing binding is writable: `let`, `var`, function, and class are writable; a source `const` is writable only when that cell's variable policy lowered it to `let`; imports and reserved/private bindings are not writable. Unknown provenance fails closed. A function is lowered at its declaration position to assignment of an anonymous function expression, so recursive reads resolve through the replaceable outer binding. A class is lowered to assignment of a named class expression, preserving its inner self-reference and ensuring a throw during class evaluation leaves the old outer value unchanged. Both forms deliberately take effect at the declaration position rather than acquiring native declaration hoisting. A terminated `void 0` statement prevents the assignment value from becoming the cell completion.
+
+The original Program is validated before lowering. Same-cell duplicates, nested or block declarations, parsing, TypeScript scope rules, and source positions therefore remain owned by the language pipeline. A future state/frame persistence implementation can replace these policies without changing the cell language analyzer.
 
 ## Alternatives considered
 
@@ -18,4 +24,4 @@ The persistent REPL uses one worker lexical environment so later cells can refer
 
 ## Consequences
 
-The core analyzer has no mixed-redeclaration lowering helpers and can be tested independently of the REPL convenience policy. The compatibility module remains responsible for its custom hybrid semantics and its focused tests; it must not be described as native JavaScript semantics. Future persistence work can introduce fresh cell lexical frames while retaining or replacing the convenience adapter at one explicit boundary.
+The core analyzer has no redeclaration lowering helpers and can be tested independently of the REPL convenience policy. The compatibility module remains responsible for its custom replacement semantics and focused tests; neither policy is native JavaScript semantics. Binding assignability is reconstructed from prepared source and each cell's persisted policy rather than runtime-value inspection. Future persistence work can introduce fresh cell lexical frames while retaining or replacing the convenience adapter at one explicit boundary.

package/docs/adr/0014-persist-cell-rewrite-policy.md

@@ -2,13 +2,17 @@
 
 ## Problem
 
-Durable replay prepares the original cell source again. AST module and REPL convenience rewrites are configuration-controlled, so using the current profile during replay can reject a cell that was durable when it was recorded. Replay would then discard recoverable bindings even though the journal still proves the cell's calls and completion.
+Durable replay prepares the original cell source again. AST module rewrites and both REPL redeclaration conveniences are configuration-controlled, so using the current profile during replay can reject a cell that was durable when it was recorded or infer the wrong binding assignability. Replay would then discard recoverable bindings even though the journal still proves the cell's calls and completion.
 
 ## Decision
 
-Journal version 3 records `rewritePolicy` beside `bindingMode` with the three boolean rewrite settings used to prepare the cell. Live journals capture the active profile; replay passes each node's recorded policy to `prepareProgram`. The policy is part of journal normalization and equality, is frozen with the journal, and is required by the closed schema. A profile change therefore affects only new cells; existing durable nodes retain the language policy under which they were evaluated.
+The module-lowering fields below retain the `legacy-v1` contract. Journal v9 additionally selects the complete language through `languageSemantics`; its `stateful-v1` and `protected-v1` contracts are owned by [ADR 0025](0025-use-versioned-logical-binding-identities.md). A historical `live-readonly` field does not independently make a stateful binding read-only.
 
-The journal decoder also owns the predecessor adapters. Version 1 has its original closed field set and migrates with all three later rewrite switches disabled, matching the language pipeline that emitted it; `bindingMode` continues to preserve its top-level redeclaration policy. Its string call-ID confirmations become version 3 event sequences only when the enclosing session log contains exactly one earlier unjournaled `run_code` call with that identity. Missing or repeated candidates are ambiguous and fail closed. Version 2 already contains `rewritePolicy` and normalizes to version 3 only when its confirmed no-op list is absent or empty; version 2 call-ID confirmations remain unsupported.
+Journal version 4 replaces `bindingMode` with the closed `bindingPolicy` object containing the exact `variableRedeclarations` and `functionClassRedeclarations` booleans used to prepare the cell. It retains `rewritePolicy` with the three module and mixed-declaration rewrite booleans, and adds the closed `moduleSemantics.defaultExportBinding` value. Current cells record `live-readonly`; this is a source-lowering generation, not a user setting. Live journals capture both active policies and the fixed module semantics; replay passes every recorded value to `prepareProgram`. These objects participate in normalization and semantic equality, are frozen with the journal, and are required by the closed schema. A profile change therefore affects only new cells; existing durable nodes retain the language policy, module lowering, and writable-binding provenance under which they were evaluated.
+
+Journal version 7 adds the closed `moduleSemantics.importExpressionBoundary` value, which is orthogonal to the default-export binding model and fixes how a module-reference write is lowered relative to its preceding statement. Current cells record `statement-safe`: the lowered write keeps its own statement boundary, so automatic semicolon insertion cannot merge it into a preceding semicolonless expression and change which value receives the write or whether the write runs at all. Versions 1 through 6 normalize to `legacy` so historical cells replay the lowering generation that evaluated them instead of the current one. The value participates in normalization, freezing, and semantic equality like the other closed semantics fields.
+
+The journal decoder also owns the predecessor adapters. Versions 1 through 3 retain their original closed field sets as inputs and normalize forward through the closed generations. Their `bindingMode` maps exactly to `variableRedeclarations`; `functionClassRedeclarations` is always `false` because those language pipelines did not implement the feature. They receive `legacy-variable` default-export semantics so loose journals preserve the historically writable generated binding and strict journals preserve its const behavior. Version 1 receives all three later rewrite switches as disabled and its string call-ID confirmations become event sequences only when the enclosing session log contains exactly one earlier unjournaled `run_code` call with that identity. Missing or repeated candidates are ambiguous, so they cannot prove old state and form an unknown recovery boundary. Versions 2 and 3 retain their recorded `rewritePolicy`; unsupported non-numeric predecessor confirmations receive the same conservative contraction. Each later generation extends the same chain: version 4 records no Global User Binding relation, version 5 adds the snapshot fingerprint, version 6 adds `userBindingsReusePolicy`, version 7 adds `importExpressionBoundary`, and version 8 adds the per-name shadow policy with its name evidence, owned by [ADR 0023](0023-global-user-bindings.md). Version 9 adds the required complete language generation, with versions 1 through 8 fixed to the frozen legacy compiler rather than reinterpreted by current lowering ([ADR 0025](0025-use-versioned-logical-binding-identities.md)). Per [ADR 0007](0007-separate-worker-transport-from-session-semantics.md), rejecting predecessor state evidence does not make historical metadata an availability gate for the current valid call.
 
 ## Alternatives considered
 
@@ -18,8 +22,10 @@ The journal decoder also owns the predecessor adapters. Version 1 has its origin
 
 **Read the current profile during replay.** This keeps the journal small, but makes durable recovery depend on mutable deployment configuration and causes valid historical cells to become unrecoverable after a configuration change.
 
-**Accept every version 2 confirmation by call ID.** Preserving those values would require replay to guess which event a reused provider call ID denotes. Only the empty-confirmation subset has an identity-independent meaning, so broader migration would weaken the version 3 event-sequence contract owned by [ADR 0007](0007-separate-worker-transport-from-session-semantics.md).
+**Infer the default-export lowering from source or journal version during replay.** Source does not identify which implementation generation evaluated it, while version-derived behavior becomes implicit protocol state. Persisting the closed semantic value makes migration explicit and keeps replay deterministic.
+
+**Accept every predecessor confirmation by call ID.** Preserving those values would require replay to guess which event a reused provider call ID denotes. Only the version 1 adapter with a unique enclosing session event has sufficient evidence, so broader migration would weaken the event-sequence contract owned by [ADR 0007](0007-separate-worker-transport-from-session-semantics.md).
 
 ## Consequences
 
-The current journal schema is version 3. Replay remains source-based and deterministic while configuration changes no longer invalidate durable cells. Version 1 histories retain the predecessor language behavior and migrate only uniquely identified confirmations; version 2 histories without call-ID confirmations retain their recorded rewrite policy. Ambiguous identity remains unsupported recovery input rather than receiving guessed defaults. New profile settings apply at the next live cell boundary.
+The journal schema introduced by this decision is version 4; the closed field sets, generation constants, and migration rules are owned by [`internal/session-journal-schema.js`](../../internal/session-journal-schema.js), with validation, migration, and creation in [`internal/session-journal.js`](../../internal/session-journal.js) and event association and fold/recovery in [`internal/session-journal-recovery.js`](../../internal/session-journal-recovery.js). Replay remains source-based and deterministic across configuration changes without invalidating durable cells or altering reconstructed binding assignability. Version 1 histories retain the predecessor rewrite behavior and migrate only uniquely identified confirmations; versions 2 and 3 retain their recorded rewrite policy. Versions 1 through 3 fix function/class replacement to disabled and default-export lowering to `legacy-variable`; versions 1 through 6 fix the import-expression boundary to `legacy`. Later records preserve their independently recorded values instead of guessing from current behavior. Ambiguous identity remains unsupported recovery input rather than receiving guessed defaults. New profile settings apply at the next live cell boundary.

package/docs/adr/0015-preserve-source-positions-through-rewrites.md

@@ -6,7 +6,7 @@ PTC cells are prepared by several source-to-source passes before they reach the
 
 ## Decision
 
-Each source edit carries a compact segment map from generated text back to the original cell. Unchanged text retains exact offsets; generated module bindings and source literals carry token-level anchors to their originating AST nodes, while other introduced text maps to the replaced source span. [`internal/source-position-map.js`](../../internal/source-position-map.js) validates and sorts one pass of non-overlapping edits, then assembles source and composed segments in one traversal. Binary segment lookup handles repeated or non-monotonic explicit token anchors without rescanning the complete map. Maps compose through every preparation pass. Mixed-destructuring generation emits copied pattern, initializer, and binding ranges through the same mapped representation instead of one opaque replacement string. [`internal/cell-analysis.js`](../../internal/cell-analysis.js) converts rewrite-time preflight and collision spans to original-cell coordinates before returning a prepared program; runtime exception positions use the same map after worker execution.
+Each source edit carries a compact segment map from generated text back to the original cell. Unchanged text retains exact offsets; generated module bindings and source literals carry token-level anchors to their originating AST nodes, while other introduced text maps to the replaced source span. [`internal/source-position-map.js`](../../internal/source-position-map.js) validates and sorts one pass of non-overlapping edits, then assembles source and composed segments in one traversal. Binary segment lookup handles repeated or non-monotonic explicit token anchors without rescanning the complete map. Maps compose through every preparation pass. Mixed-destructuring generation emits copied pattern, initializer, and binding ranges through the same mapped representation instead of one opaque replacement string. [`internal/cell-parser.js`](../../internal/cell-parser.js) is the single executable-parse entry: it relocates AST ranges to original-cell coordinates and reports parse failures in those coordinates, so no downstream pass applies a wrapper offset. [`internal/cell-analysis.js`](../../internal/cell-analysis.js) maps parse failures raised against the module-rewrite output, preflight spans, and collision spans back to original-cell coordinates before returning a prepared program; runtime exception positions use the same map after worker execution, except a module-load failure that already carries an original-cell position.
 
 ## Alternatives considered
 

package/docs/adr/0016-archive-resolved-review-findings.md

@@ -10,7 +10,7 @@ An ignored root `REVIEW_FINDINGS.md` prevents unresolved review findings from be
 
 Review output and ledger mutation follow task authority. A read-only review reports records in the ledger's semantic fields without writing checkout state. Every implementation preserves an active ledger, but an ordinary change with no finding does not create one. `npm run review:new` creates the ignored root ledger only when a task authorizes capture or resolution of at least one finding; implementation imports those findings before editing their fixes. Archives move under Git's local `review-findings/archive` metadata path, so they cannot enter a commit and remain associated with the checkout.
 
-Ledger validation, readiness, deterministic verification, archive, and commit proof are distinct states with one implementation. `npm run review:validate` checks schema and tracked-file safety while accepting a valid open ledger. `npm run review:gate` is read-only: it blocks an open ledger, validates durable owners for accepted findings, and never archives. `npm run verify` performs schema validation before syntax and coverage checks, so open-ledger work can collect evidence. `npm run check` applies the readiness gate first, then materializes the current tracked and non-ignored checkout through Git's clean and index semantics in a temporary Git administrative directory. Git selects that directory's default index through `--git-dir` and reads the target checkout through `--work-tree`; it never receives an alternate-index environment path that could fall back to the real repository index. The temporary object database reads the repository's objects through a relative alternates entry and stores new fingerprint objects locally. The resulting tree object ID includes canonical blobs, symlink identity, and file modes while remaining independent of staged content. Sparse checkouts retain skip-worktree paths from the `HEAD` baseline and apply clean conversion only to materialized paths, so an absent out-of-cone file is neither lost nor mistaken for a deletion. Every path discovered by Git is reapplied through NUL-delimited literal input. The command separately snapshots the ignored ledger, runs `verify`, rejects changed source or ledger state, and refreshes the proof before archiving a resolved ledger. Repository scripts that launch npm as a child use one command resolver: an invoking npm process supplies its CLI path and Node executable, while direct script invocation falls back to the platform npm executable. A successful later check without an active ledger also refreshes an older proof. The pre-commit hook rejects open and unverified resolved ledgers, then asks Git for the prospective index tree object ID and requires it to equal the verified source tree. Staging the complete verified tree permits repeated commit attempts; partial staging, additional staged content, mode-only changes, or later checkout changes require reconciliation or another checked workflow. An advanced HEAD proves that the checked commit completed and retires the old proof.
+Ledger validation, readiness, deterministic verification, archive, and commit proof are distinct states with one implementation. `npm run review:validate` checks schema and tracked-file safety while accepting a valid open ledger. `npm run review:gate` is read-only: it blocks an open ledger, validates durable owners for accepted findings, and never archives. `npm run verify` performs schema validation before syntax and coverage checks, so open-ledger work can collect evidence. `npm run check` applies the readiness gate first, then materializes the current tracked and non-ignored checkout through Git's clean and index semantics in a temporary Git administrative directory. Git selects that directory's default index through `--git-dir` and reads the target checkout through `--work-tree`; it never receives an alternate-index environment path that could fall back to the real repository index. The temporary object database reads the repository's objects through a relative alternates entry and stores new fingerprint objects locally. The resulting tree object ID includes canonical blobs, symlink identity, and file modes while remaining independent of staged content. Sparse checkouts retain skip-worktree paths from the `HEAD` baseline and apply clean conversion only to materialized paths, so an absent out-of-cone file is neither lost nor mistaken for a deletion. Every path discovered by Git is reapplied through NUL-delimited literal input. The command separately snapshots the ignored ledger, runs `verify`, rejects changed source or ledger state, and refreshes the proof before archiving a resolved ledger. Repository scripts that launch npm as a child use one command resolver: an invoking npm process supplies its CLI path and Node executable, while direct script invocation falls back to the platform npm executable. A successful later check without an active ledger also refreshes an older proof. The pre-commit hook rejects open and unverified resolved ledgers, requires a verification proof for the current `HEAD`, requires equal source and index tree fingerprints, and requires a clean independent-review verdict bound to the same `HEAD`, fingerprint and scope (ADR 0026). Staging the complete verified tree permits repeated commit attempts; partial staging, additional staged content, mode-only changes, or later checkout changes require reconciliation or another checked workflow. An advanced HEAD, a missing proof, or a verdict that does not match the verified candidate retires the stale evidence and blocks the commit.
 
 Hook installation is explicit. `npm run hooks:install` selects the tracked hook path only when the effective `core.hooksPath` is unset or already `.githooks`. Before the first switch from Git's default hooks directory, installation rejects any non-sample hook file there; it also rejects an incompatible configured path instead of disabling another hook owner. Dependency installation has no Git-configuration side effect.
 

package/docs/adr/0017-track-the-latest-dsh-public-surface.md

@@ -6,8 +6,55 @@ PTC Plus integrates with DSH services, request bindings, prompt assembly, sessio
 
 ## Decision
 
+PTC Plus must remain independently installable on unmodified official DSH distributions. Host source is read-only research evidence, not an implementation workspace for plugin features. Plugin changes must not patch host source or installed packages, introduce install-time host patches, or require a custom host build. Plugin-owned components, panels, styling, portals and public renderer replacements are valid UI choices within the consumed contracts; integration does not require every visual element or layout to be native. A locally invented extension declaration is not a published public capability. Choose among published surfaces according to the required user experience rather than assuming that a UI feature must become a historical message node. If none can satisfy the required behavior, record the actual limitation; do not substitute a custom distribution or present a compatibility fallback as delivery.
+
 The compatibility target is the latest available DSH release. Production behavior, configuration, tests, installation guidance, and current compatibility claims depend on public extension contracts and observed live schemas, never on a DSH version allowlist or comparison. An upstream default projection is not an extension ceiling: when public scoped registration and presentation support a plugin-owned capability, PTC Plus preserves that capability and its model-visible identity instead of deleting or renaming it to match the default. Deterministic normalization remains valid for a call that is outside the declared direct surface when the live schema proves one native target and the lowering preserves arguments, call identity, authority, and result semantics. Deterministic tests exercise the consumed contracts; model-backed and packaging acceptance runners use the installed DSH and record `dsh --version` in generated reports so failures remain attributable without turning the observed value into policy. Concrete DSH release numbers may appear only in source comments that identify historical integration or evaluation evidence and cannot influence execution or acceptance.
 
+Preceding public contracts remain supported where capability detection is
+unambiguous. Tools presentation is selected by the installed public schema;
+Client contributions depend on their slots and supplied hooks rather than unused
+package gates. Preset projection evidence takes precedence over the preceding
+public session-summary field, and the current composer currency takes precedence
+over the earlier session/interactions currency. This compatibility does not
+extend to private stores or inferred binding state.
+
+Compatibility decisions have one owner per public contract and execution
+environment. `src/client-host-compat.js` owns Client preset reads and subscriptions
+and composer compatibility. UI consumers own feature eligibility and slot
+registration. `scripts/dsh-host-contract.mjs` owns selected-installation package
+resolution, tools presentation and persona field adaptation for development and
+acceptance commands. Host runtime contracts remain in their existing focused
+owners, including `internal/session-events.js`, `internal/settings-compat.js`, and
+`internal/execution-seam-compat.js`, which owns which program-execution service the
+plugin attaches to and the call shape and provider descriptors it presents for it
+([ADR 0028](0028-attach-to-the-host-ptc-execution-seam.md)).
+`internal/host-rpc.js` owns UI Remote service registration and withdrawal;
+`src/client-rpc.js` owns Client mounting and result unwrapping. Both consume the
+executable wire definitions in `internal/rpc-contract.js`. Binding and observation
+owners supply operation handlers and retain their domain validation. Consumers
+use these operations instead of repeating transport or field-generation checks.
+Adapters preserve unknown evidence and public subscription disposal; they do not
+cache session capabilities globally. Test-only persistence fixtures and explicit
+offline journal migration retain their own lifecycles and validation contracts.
+
+## UI communication
+
+Plugin UI calls use DSH's public Typert Remote and Gateway over the existing
+`/api` carrier. The shared contract defines `ptcPlusBindings.invoke` and
+`ptcPlusRepl.invoke`, each with an operation string, JSON payload, optional
+cancellation signal and the domain result envelope. The Client unwraps only the
+Gateway result layer. The Host owns authentication, origin checks, transport
+cancellation and dispatch; a connection identity does not confer a draft locator.
+
+The communication owner contributes one package definition containing the active
+services. Disabling Global User Bindings withdraws its service and invocation;
+REPL observation has its own eligibility checks. Service removal aborts pending
+calls and invalidates retained references. Provider replacement cancels the old
+requests and republishes active definitions through Cordis injection. Client
+Remote mounting belongs to its calling fiber and is released with that fiber.
+Writes are never retried by the adapter. Business owners preserve revision,
+capability, storage and observation rules independently of transport.
+
 ## Alternatives considered
 
 **Pin one verified DSH release.** A pin makes one historical environment reproducible but turns normal upstream progress into an artificial incompatibility and allows the implementation to drift from the release users actually install.
@@ -20,4 +67,6 @@ The compatibility target is the latest available DSH release. Production behavio
 
 ## Consequences
 
+Feature completion requires evidence from the actual packaged plugin running on the selected unmodified Host, including the affected user flow. Component fixtures and public-interface unit tests validate narrower properties; they do not prove that a required renderer exists or is loaded in that distribution. A clean code review and passing deterministic checks are separate from product acceptance. Both must cover the final change before a feature is described as delivered; commit and publish authorization remain separate user decisions.
+
 Each upstream DSH release becomes the immediate compatibility target and must pass the public-surface, packaging, and model-backed checks appropriate to the change. Users are not blocked by stale version metadata. Historical reports remain attributable through generated runtime metadata or source comments, while a passing older run never substitutes for validation against the latest release.

package/docs/adr/0018-use-versioned-fixture-for-ab-benchmark.md

@@ -2,11 +2,11 @@
 
 ## Problem
 
-The ordinary-task A/B benchmark previously copied the active PTC Plus checkout into each arm. The workload therefore changed whenever the plugin repository grew, making absolute machine budgets and longitudinal comparisons unstable. The same source tree was also serving as the host, the treatment-under-test workspace, and the measurement workload, which mixes unrelated variables into one measurement.
+Using the active PTC Plus checkout as each ordinary-task A/B arm's workload would make the workload change whenever the plugin repository grows, destabilizing absolute machine budgets and longitudinal comparisons. It would also make one source tree serve as the host, treatment-under-test workspace, and measurement workload, mixing unrelated variables into one measurement.
 
 ## Decision
 
-The primary ordinary-task A/B workload is now a purpose-built, versioned, zero-dependency Node.js fixture in `fixtures/ab-node-project-v1`. The fixture manifest is the single owner of the fixture name, version, content SHA-256, deterministic Git identity/commit, and deterministic dirty state. The runner materializes the fixture independently into each arm workspace, initializes the same deterministic Git history, applies the same uncommitted changes, and never copies the active PTC Plus checkout as the model workload.
+The primary ordinary-task A/B workload is a purpose-built, versioned, zero-dependency Node.js fixture in `fixtures/ab-node-project-v1`. The fixture manifest is the single owner of the fixture name, version, content SHA-256, deterministic Git identity/commit, and deterministic dirty state. The runner materializes the fixture independently into each arm workspace, initializes the same deterministic Git history, applies the same uncommitted changes, and never copies the active PTC Plus checkout as the model workload.
 
 The A/B task set contains a fixed, cheap, machine-checkable canary that exercises `run_code` before the full paired matrix starts. Reports record the fixture path, version, and content hash so future runs are grouped by benchmark version. The current PTC Plus checkout is kept as a separate self-hosting acceptance surface; it is not the stable README headline benchmark.
 
@@ -22,4 +22,4 @@ The A/B task set contains a fixed, cheap, machine-checkable canary that exercise
 
 ## Consequences
 
-The benchmark workload is stable under unrelated PTC Plus source changes and has its own result series tied to `fixtureVersion` and content hash. Existing README totals from the checkout-based series are explicitly non-comparable to the new fixture series. Maintaining a benchmark now requires updating the fixture manifest together with the fixture content, and a materially different task set or fixture change starts a new series rather than reusing old totals.
+The benchmark workload is stable under unrelated PTC Plus source changes and has its own result series tied to `fixtureVersion` and content hash. Results produced from an active-checkout workload are not comparable to the versioned-fixture series. Maintaining the benchmark requires updating the fixture manifest together with the fixture content, and a materially different task set or fixture change starts a new series rather than reusing old totals.