@earendil-works/pi-durable 0.87.0 → 0.87.1

package/docs/pico-v5-chord-usage.md

@@ -12,8 +12,8 @@ This guide uses the contracts in the [Pico5 specification](pico-v5.md).
 - **Durable document:** JSON persisted as a complete base, Chord operations, and
   checkpoints. Its definition token declares schema, version, scope, and initialization;
   conversation scope also declares history and fork behavior.
-- **Transaction draft:** the mutable tracked object from `await tx.doc`, valid
-  only inside that commit callback, including all nested objects.
+- **Transaction draft:** the revocable copy-on-write object from `await tx.doc`,
+  valid only inside that commit callback, including all nested objects.
 - **DocumentSource:** an opaque handle to one document incarnation's committed changes,
   not a mutable value or a public subscription API.
 - **ReplicatedState:** Chord's immutable complete values through `value` and
@@ -32,36 +32,30 @@ Examples build on one another. Pico5 names (`defineDoc`, `defineDocFamily`,
 refer to normative contracts, without a specified import path or runnable Pico5
 package. In those contracts, `ConversationRecord`, `EntryRecord`, and
 `TaskRecord` are persisted records, while `Conversation` is the public
-conversation object and `Entry`/`Task` are typed definitions. These Chord imports
-exist today:
+conversation object and `Entry`/`Task` are typed definitions. The Chord imports
+below are the concrete APIs used by the examples:
 
 ```ts
 import {
   createFacetHost, createRemoteServiceBinding, defineFacet, defineService,
+  replicatedState,
   type Context, type Facet, type JsonValue, type RemoteServiceTransport,
   type ReplicatedState,
 } from "@earendil-works/chord";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { applyImmutable } from "@earendil-works/chord/delta";
 
-// The spec calls this JsonObject; current Chord exports JsonValue, not JsonObject.
+// The Pico specification calls this object-root constraint JsonObject.
 type JsonObject = { [key: string]: JsonValue };
-
-// Required by Pico5, but not a current Chord export yet.
-declare function documentReplicatedState<T extends JsonObject>(
-  source: DocumentSource<T>, context: Context,
-): Promise<{ readonly state: ReplicatedState<T | null>; dispose(): void }>;
 ```
 
-The adapter must register Chord-recognized state, atomically hydrate a matching
-committed value and adapter-owned delivery sequence, and forward committed ops without another
-tracker or re-diff. Disposal releases observation, not the document. Even Chord's
-hydration requests must never flush an uncommitted draft.
-
-Current `env.replicatedState(initial)` creates an **in-memory**, immutable
-latest-value source with transaction-scoped `.change(context, callback)` and
-`.replace(context, value)`, not a durable source adapter. There is no
-`replicatedState.own(source)`. Do not mirror documents into another state source.
+Chord adoption atomically captures a committed snapshot, buffers every later
+source frame, installs the frame listener, and drains the buffer before returning.
+Operations already reflected in the snapshot are never redelivered. It forwards
+committed values and operations without another tracker or re-diff. Disposing the
+adopted state releases observation, not the document. A source-backed state is
+publication-only; Pico remains the sole mutator. Even hydration must never prepare
+or publish an uncommitted draft.
 
 ## 1. A Session-wide canvas
 
@@ -86,20 +80,23 @@ interface CanvasService {
 const Canvas = defineService<CanvasService>("app.canvas");
 
 async function createCanvasFacet(session: Session, context: Context): Promise<Facet> {
-  const target = { scope: "session" } as const;
-  // Get-or-create: an absent canvas is initialized in a serialized commit.
-  const source = await session.documentSource(CanvasDoc, target, context);
-  const replica = await documentReplicatedState(source, context);
+  // Creation is explicit; observation never writes.
+  await session.commit(async tx => {
+    await tx.doc(CanvasDoc);
+  }, context);
+  const source = await session.documentSource(CanvasDoc, context);
+  if (source === undefined) throw new Error("canvas was retired during setup");
   return defineFacet({
     id: "app.canvas/session",
     setup(env) {
-      env.own(() => replica.dispose());
+      const state = replicatedState(source);
+      env.own(() => state.dispose());
       env.provide(Canvas, {
-        state: replica.state,
+        state,
         async addStroke(stroke, context) {
           await session.commit(async tx => {
-            const draft = await tx.doc(CanvasDoc, target);
-            draft.strokes.push(stroke); // The draft now owns stroke; caller must not mutate it.
+            const draft = await tx.doc(CanvasDoc);
+            draft.strokes.push(stroke); // Chord copies the assigned stroke by value.
           }, context);
         },
       });
@@ -133,7 +130,8 @@ async function runCanvasExample(session: Session): Promise<void> {
 }
 ```
 
-The application owns the open Session. Acquire state **before** synchronous
+The application owns the open Session. Acquire the document source
+asynchronously before synchronous `setup`, then adopt it synchronously during
 `setup`; `env.provide` cannot run in `onActivate`. Install one provider per
 Session host. Chord may reload presentation facets independently, but v1 does
 not use facet reload to replace Session-side task or hook implementations. A
@@ -166,7 +164,7 @@ async function connectCanvas(transport: RemoteServiceTransport, context: Context
 ```
 
 ```text
-first acquisition -> commit base { strokes: [] }
+explicit first tx.doc -> commit base { strokes: [] }
 addStroke(A)       -> commit A -> local and remote subscribers see A
 worker restarts   -> open same durable storage; install canvas facet again
 acquire source    -> load base + committed deltas, without rerunning initial()
@@ -181,7 +179,7 @@ A method's successful commit does not promise every remote callback has run yet.
 
 A **document family** uses one definition for many instances. The logical key is
 `(kind, conversationId, key)`; the persisted numeric document ID identifies an
-incarnation and is never reused. Initializer input is not part of the key.
+incarnation and is never reused. The creation seed is not part of the key.
 
 ```ts
 type ReviewInput = { path: string; patch: string };
@@ -190,7 +188,7 @@ type ReviewState = ReviewInput & { comments: ReviewComment[] };
 const ReviewDoc = defineDocFamily<ReviewState, ReviewInput>({
   kind: "app.diff-review", version: 1, family: true, scope: "conversation",
   history: "latest", fork: "current",
-  initial: input => ({ path: input.path, patch: input.patch, comments: [] }),
+  initial: seed => ({ path: seed.path, patch: seed.patch, comments: [] }),
   checkpointWhen: value => value.comments.length % 50 === 0,
 });
 interface DiffReviewService {
@@ -202,7 +200,7 @@ const DiffReviews = defineService<DiffReviewService>("app.diff-reviews");
 
 function reviewFacet(
   session: Session, conversationId: Id,
-  reviews: readonly { key: string; initial: ReviewInput }[], context: Context,
+  reviews: readonly { key: string; seed: ReviewInput }[], context: Context,
 ): Facet {
   return defineFacet({
     id: "app.diff-reviews/session",
@@ -210,18 +208,21 @@ function reviewFacet(
       const instances = env.provideMany(DiffReviews);
       env.onActivate(async () => {
         for (const review of reviews) {
-          const target = { scope: "conversation" as const, conversationId, ...review };
-          const source = await session.documentSource(ReviewDoc, target, context);
-          const replica = await documentReplicatedState(source, context);
-          env.own(() => replica.dispose());
+          await session.commit(async tx => {
+            await tx.doc(ReviewDoc, conversationId, review.key, review.seed);
+          }, context);
+          const source = await session.documentSource(ReviewDoc, conversationId, review.key, context);
+          if (source === undefined) throw new Error("review was retired during setup");
+          const state = replicatedState(source);
+          env.own(() => state.dispose());
           // Chord instance keys route services; they are not numeric document incarnation IDs.
           instances.spawn(JSON.stringify([conversationId, review.key]), {
-            state: replica.state,
+            state,
             async identity() { return { conversationId, key: review.key }; },
             async addComment(comment, context) {
               await session.commit(async tx => {
-                const draft = await tx.doc(ReviewDoc, target);
-                draft.comments.push(comment); // Do not mutate comment after this assignment.
+                const draft = await tx.doc(ReviewDoc, conversationId, review.key, review.seed);
+                draft.comments.push(comment); // Chord copies the assigned comment by value.
               }, context);
             },
           }); // The facet owns spawned service lifetimes automatically.
@@ -232,7 +233,7 @@ function reviewFacet(
 }
 ```
 
-Example input: `[{ key: "review-7", initial: { path: "a.ts", patch: "-old\n+new" } }]`.
+Example input: `[{ key: "review-7", seed: { path: "a.ts", patch: "-old\n+new" } }]`.
 Pass distinct family keys and a real conversation ID; install the facet as above.
 Keyed consumers use `env.observe(DiffReviews, handler)`, not `env.use`. The handler
 receives `(review, context)`; call `review.identity(context)` to identify it and
@@ -249,9 +250,9 @@ fork at E with current: child review-7 contains A and B
 child adds C: parent still contains only A and B
 ```
 
-With `fork: "initial"`, no instance copies; first child access uses supplied input.
+With `fork: "initial"`, no instance copies; the first child `tx.doc()` uses its supplied seed.
 `latest` cannot read history or fork `asOf`; use `history: "rewindable"` with `asOf`
-to reflect E's commit. Reaccess ignores `initial`; updating the patch requires
+to reflect E's commit. Reaccess ignores later seeds; updating the patch requires
 an explicit mutation or a distinct review key.
 
 ## 3. Task-scoped output and a tool/task watch
@@ -267,16 +268,13 @@ const JobOutputDoc = defineDoc<JobOutput>({
   initial: () => ({ stdout: "", chunks: 0 }),
   checkpointWhen: value => value.chunks % 100 === 0,
 });
-function jobOutputTarget(taskId: Id) {
-  return { scope: "task" as const, taskId };
-}
 async function appendJobOutput(
   runtime: TaskRuntime<JobInput, { phase: "running" }, null, {}>,
   chunk: string, context: Context,
 ): Promise<void> {
   // Read process output outside this callback. The runtime gates the live task.
   await runtime.commit(async tx => {
-    const draft = await tx.doc(JobOutputDoc, jobOutputTarget(runtime.taskId));
+    const draft = await tx.doc(JobOutputDoc, runtime.taskId);
     draft.stdout = (draft.stdout + chunk).slice(-50_000);
     draft.chunks += 1;
   }, context);
@@ -285,8 +283,8 @@ async function observeJob(
   api: DocumentObserver, producerTaskId: Id,
   finished: Promise<void>, context: Context,
 ): Promise<void> {
-  const target = jobOutputTarget(producerTaskId);
-  const watch = await api.watchDoc(JobOutputDoc, target, context);
+  const watch = await api.watchDoc(JobOutputDoc, producerTaskId, context);
+  if (watch === undefined) return;
   let value = watch.value;
   console.log(value === null ? "retired" : value.stdout);
   try {
@@ -304,8 +302,9 @@ async function observeJob(
 
 The running phase calls `appendJobOutput` and must also commit its next checkpoint
 or terminal outcome. `api` is the invocation's `DocumentObserver`; `TaskRuntime`
-includes that interface. Acquisition validates the target task is live and
-derives its conversation from the task record.
+includes that interface. `tx.doc()` creation validates that the target task is live and derives its
+conversation from the task record. A later non-creating watch lookup returns
+`undefined` after the task is terminal and its document has retired.
 
 ```text
 watchDoc: capture immutable V0 + register for later committed operation batches
@@ -321,8 +320,9 @@ Watches automatically stop when their invocation ends. A Session-acquired watch
 is caller-owned and stops on Session close. Previously delivered snapshots never
 mutate. Slow or unstarted delivery may coalesce an undelivered suffix into a
 complete reset, so a watch is convergent state observation rather than a
-transition journal. Retirement ends the incarnation's stream; recreation
-requires a new watch/source and a new numeric document ID. A terminal task cannot
+transition journal. Retirement ends the incarnation's stream; a service exposing that source must
+withdraw or remain terminal at `null`. Recreation requires a new watch/source,
+service attachment, and numeric document ID. A terminal task cannot
 create more output. Task-scoped documents
 never copy into forks. Preserve required output in result entries or Session- or
 conversation-scoped documents in the terminal commit before retirement. Use a
@@ -348,28 +348,29 @@ services or trusted invocation watches. A retired source publishes `null`; a
 dynamic service should then withdraw its instance rather than expose stale data.
 
 ```text
-addStroke -> hold Session mutation line -> await tx.doc -> mutate tracked draft
-callback succeeds -> tracker flush: incremental ops + candidate value
+addStroke -> hold Session mutation line -> await tx.doc -> mutate tracker change draft
+callback succeeds -> tracker prepare: immutable candidate + frozen ops
 Session checkpoint predicate selects a base or delta exactly once
 atomic storage commit: persist selected document and record writes
-storage succeeds -> materialize immutable published value + enqueue value/ops, still on line
+storage succeeds -> adopt candidate + enqueue candidate/ops, still on line
 release line -> deliver committed source ops -> adapter -> local/remote Chord consumers
 late subscriber -> atomically capture committed value + adapter sequence + subscription
 ```
 
-No visible-undurable path exists. Callback failure restores the unchanged
-baseline. Failure after flush, including checkpoint/storage failure, publishes
-nothing and poisons the open Session; close and reopen it instead of continuing.
+No visible-undurable path exists. Callback, tracker preparation, and checkpoint
+failure abort normally before Storage admission. An uncertain Storage failure
+publishes nothing and poisons the open Session; close and reopen it instead of
+continuing.
 
 ## Footguns
 
-- Never retain drafts, nested proxies, or bound array methods across commits.
-  Never mutate inserted aliases or insert one mutable object at multiple paths.
+- Never retain drafts, nested proxies, or bound array methods across commits;
+  they are revoked. Assigned containers are copied by value.
 - Async commit holds the line through storage settlement and baseline adoption.
   Await document access there, not models, processes, network calls, or humans.
-- Normal `snapshot`, `documentSource`, and `watchDoc` reads are get-or-create and
-  lazily migrate through the supplied token. Harness open does not scan ordinary
-  documents. Family `initial` is first-creation input, not an update.
+- Only `tx.doc()` creates. `snapshot`, `documentSource`, and `watchDoc` return
+  `undefined` when absent and never write. Family seeds are used only when the
+  first `tx.doc()` creates an incarnation; later seeds are ignored.
 - Initialize from the fixed `watch.value` before `start()`. Slow or unstarted
   delivery may coalesce an undelivered suffix into a root replacement when its
   operation count exceeds the limit, omitting intermediate states. Queue

package/docs/pico-v5-handoff.md

@@ -11,13 +11,13 @@ facades, membranes, document routing, view projection, events, or clone chains.
 
 - Obsolete `pico` and `pico4` prototypes were removed.
 - `pico3` remains.
-- No Pico5 implementation exists.
+- Packages 1–3 are implemented in `packages/durable`; later Pico5 runtime packages remain.
 
 ## 1. Records, cursors, and memory tables
 
 Implement IDs, sequences, reserved root conversation ID `1`,
-`ConversationRecord`, `EntryRecord`, tagged inputs, live/terminal `TaskRecord`
-values, document lifecycle records, storage writes, backend-opaque JSON cursors, and
+`ConversationRecord`, `EntryRecord`, strict input/write `SubmissionRecord`
+values, live/terminal `TaskRecord` values, document records, storage writes, backend-opaque JSON cursors, and
 detached `MemoryStorage` tables.
 Reserve `Conversation` for the public conversation object, `Entry` for the typed
 entry definition, and `Task` for the typed executable definition returned by
@@ -26,14 +26,16 @@ entry definition, and `Task` for the typed executable definition returned by
 Test reserved root identity and immutable creation, mixed atomic commits,
 rollback, detached reads/writes, cursor boundaries,
 fork-aware entry scans through deep ancestor caps, head lookup,
-entry-to-commit lookup, and full task replacement.
+entry-to-commit lookup, full task replacement, and submission replacement/
+request-ID lookup.
 
 ## 2. Memory document records
 
 Add selected document base/delta writes, retirement, reincarnation,
 current/as-of membership, exact logical-address lookup, scoped scans, and
-base-plus-tail reconstruction. Storage receives no definition callbacks or
-unused candidate values.
+materialized point-in-time reads. Storage keeps base/delta revisions private and
+returns a detached value plus its stored definition version. It applies Chord
+`Op[]` directly and receives no definition callbacks or unused candidate values.
 
 Test Session-, conversation-, and task-scoped documents, half-open lifetimes,
 create-plus-retire, retired historical membership, family queries, current-only
@@ -70,28 +72,39 @@ never reclaimed and default no-fsync behavior matches the specification.
 
 ## 6. Tracker transaction core
 
-Keep one tracker per loaded document. Add transaction begin, callback rollback
-from the unchanged baseline, flush, fatal post-flush failure, committed baseline
-adoption, and eviction. After storage succeeds, materialize one immutable
-published value per changed document with `applyImmutable(previous, ops)`,
-separate from mutable tracker and borrowed storage candidates.
-
-Do not add membranes, transaction proxy graphs, capability facades, or defensive
-full-document clones. Test callback failure, no-op transactions, storage failure
-poisoning, immutable prior published values, replacement-payload ownership, and
-unload/reload.
+**Prerequisite:** Chord Delta exposes the normative `beginChange`/`prepare`/
+`abort`/`adopt` tracker contract, including revocable async-lifetime drafts,
+frozen operation batches, and deep no-op normalization.
+
+Keep one Chord Delta tracker per loaded document. On first `tx.doc()` access,
+call `tracker.beginChange()` and memoize its revocable copy-on-write draft by
+logical address before awaiting acquisition. Repeated access returns that same
+draft for the whole possibly async Session callback. On callback failure, abort
+all changes. A callback that settles with an unresolved acquisition rejects;
+seal `Tx`, drain and abort the acquisition, and observe its failure. Otherwise,
+prepare every open change, then evaluate checkpoints and commit Storage. Only after Storage succeeds,
+adopt every prepared tracker change and publish its candidate/ops directly.
+
+Preparation and checkpoint errors roll back normally; an uncertain Storage
+failure poisons the Session. Test callback failure, escaped-draft revocation,
+concurrent duplicate acquisition, callback failure/success with a pending
+acquisition, late acquisition after sealing, family first-seed wins, no-op normalization, multi-document preparation failure, storage
+failure poisoning, immutable prior and candidate values, frozen operation
+metadata, assignment copying, and unload/reload.
 
 ## 7. Document definitions and access
 
-Implement `defineDoc`, `defineDocFamily`, document kind/key validation, the three
-direct scopes, and get-or-create `tx.doc`, `snapshot`, and `documentSource`
-acquisition. Definitions are explicit typed arguments, not registered declarations;
-conflicting definitions that claim one persisted kind are unsupported caller
-misuse.
+Implement scope-preserving singleton/family tokens and overloads for Session,
+conversation, and task owners. Only `tx.doc()` is get-or-create: singleton tokens
+supply `initial()`, while family calls always supply key and seed and use only the
+first seed when absent. Snapshot, source, and watch lookup never create and return
+`undefined` when absent. Definitions are explicit typed arguments, not registered
+declarations; conflicting definitions claiming one persisted kind are unsupported
+caller misuse.
 
 Test concurrent initialization once, initial bases, detached snapshots, family
-initializer use only on first creation, scope/target mismatch, terminal-task
-rejection, task-derived conversation identity, retirement, and
+initializer use only on first creation, scope/token mismatch, non-creating reads,
+terminal-task rejection, task-derived conversation identity, retirement, and
 reincarnation-bound sources. Include create-task-then-document,
 document-after-terminal rejection, and create-document-then-terminal settlement
 in one transaction; internal candidate validation must not trigger
@@ -99,16 +112,18 @@ in one transaction; internal candidate validation must not trigger
 
 ## 8. Checkpoints and migration
 
-After tracker flush, Session evaluates `checkpointWhen(value, ops)` exactly once
+After tracker preparation, Session evaluates `checkpointWhen(value, ops)` exactly once
 for ordinary mutations and sends Storage only the selected base or delta.
 Implement required creation/version bases and lazy all-older-version migration
 on typed access; Harness open does not scan ordinary documents.
 
-Test latest migration persistence, `tx.doc()` migration rollback and coalescing
-with later edits, rewindable migration on current/historical read, first
-post-migration mutation base, newer-version rejection, unaccessed and unavailable-definition
-preservation, predicate failure poisoning, and checkpoint starvation without
-backend heuristics.
+Test read-only in-memory migration, `tx.doc()` migration rollback and coalescing
+with later edits, rewindable migration on current/historical read, the first
+successful `tx.doc()` version base even without a JSON change, newer-version
+rejection, migrated source/watch hydration without a write, subsequent operations
+against that migrated baseline, stored-version fork copying, unaccessed and unavailable-definition
+preservation, predicate failure rollback before Storage admission, and checkpoint
+starvation without backend heuristics.
 
 ## 9. Conversation document forks
 
@@ -121,34 +136,47 @@ of task- and Session-scoped documents.
 
 ## 10. Chord structural array operations
 
-Make ordinary positional mutations encode scattered removals without carrying
-retained payloads. Callers must not write operations manually.
+**Chord-owned prerequisite/integration:** the canonical Delta revision differ
+must be fixed in `packages/chord`; Pico only verifies and consumes it.
+
+Improve the canonical Chord Delta revision differ so ordinary positional
+mutations encode scattered removals without carrying retained payloads. Callers
+must not write operations manually.
 
 Test front/tail/middle/scattered/all/no removal, retained 256 KiB and 1 MiB
 payloads, append plus removal, later nested/index writes, exact replay, and
-unchanged previous immutable snapshots. Internal flushes must remain one commit.
+unchanged previous immutable snapshots. One prepared document change remains one
+Session commit; no intermediate candidate is adopted or published.
 
 ## 11. Chord document source
 
-Add the thin opaque-source adapter to `ReplicatedState`. It must use committed
-value/ops directly, with no tracker or re-diff.
+**Prerequisite:** Chord exposes the normative atomic `ReplicatedStateSource`
+attachment and `replicatedState(source)` adoption contract.
+
+Make Chord replicated state adopt Pico's opaque committed document source through
+a supported race-free source contract. It must atomically attach to the source's
+current immutable value and later committed operations without another tracker
+or re-diff. Pico remains the sole document mutator.
 
-Test contiguous Chord adapter delivery sequences, atomic hydrate/subscribe,
-attachment races, retirement ending one incarnation, recreation requiring
+Test contiguous Chord delivery sequences, atomic hydrate/subscribe, a snapshot
+that already covers a queued publication without duplicate application,
+retirement between source acquisition and attachment hydrating `null` rather than
+a replacement, retirement ending one incarnation, recreation requiring
 reacquisition, and listener isolation. Reuse the transaction core's immutable
 published value; do not materialize another document copy.
 
 ## 12. Document watches
 
-Implement get-or-create `watchDoc` as an incarnation-bound `WatchHandle` that
-atomically captures one fixed immutable value and registers for later committed
+Implement non-creating `watchDoc` as an incarnation-bound `WatchHandle` that
+returns `undefined` when absent and atomically captures one fixed immutable value
+while registering for later committed
 operation batches. `start()` installs one serialized asynchronous listener.
 Bound the pending queue only by the total number of operations in its undelivered
 batches. Never estimate serialized bytes or call `JSON.stringify()` for delta
 queue accounting. When the operation-count limit is exceeded, compact the entire
 undelivered suffix into one root replacement using the matching latest immutable
-published value from package 6; never retain mutable tracker or borrowed storage
-candidates.
+published value from package 6; never retain a transaction draft or borrowed
+storage candidate.
 
 Test updates between acquisition/return/start; asynchronous consumer
 initialization; no callback overlap; listener-initiated commits; compaction
@@ -214,15 +242,20 @@ retirement of task-scoped documents, default non-inheritance, inheritance from
 the current committed tail, an empty source conversation, document fork
 policies, and explicit model/section seed overrides.
 
-## 18. Inputs and positional inbox
+## 18. Submissions and positional inbox
 
-Define the initial inbox and turn-control documents, then implement request-ID
-deduplication, awaitable input handles, busy admission, withdrawal, queue modes,
-and `postTools`/`final` boundaries. Use a fake successor task.
+Define the initial inbox and turn-control documents, then implement strict input/
+write `SubmissionRecord` variants, `Conversation.submit()`, request-ID
+deduplication, awaitable/reacquirable submissions, busy admission, withdrawal, queue modes,
+and `postTools`/`final` boundaries. Successful input settlement requires an
+answer; write settlement means entry placement and never starts a turn. Use a fake successor
+task.
 
-Table-test every input transition, interleaved steer/follow-up/write selection,
-self-head cuts, stale targets, successor triggers, reopen waits, compact
-large-payload removals, and orphan/fault cleanup of active turn control.
+Table-test every submission transition, cross-type request-ID conflicts,
+interleaved steer/follow-up/write selection, self-head cuts, stale targets,
+successor triggers, reopen waits, writes pending without a later boundary,
+compact large-payload removals, abort results for queued/placed/terminal
+submissions, and orphan/fault cleanup of active turn control.
 
 ## 19. Remaining built-in documents and view
 
@@ -280,7 +313,7 @@ cancellation through pi-ai's exported `Models` interface. Do not add a Pico
 model adapter. The faux test double implements that same interface.
 
 Test every phase before and after reopen, aborted partial conversion, overflow
-through a fake collapse kind, input settlement, and no visible-undurable update.
+through a fake collapse kind, input-submission settlement, and no visible-undurable update.
 Replace the fake tool successor and rerun the package 21 integration tests.
 
 ## 23. Collapse task
@@ -294,18 +327,19 @@ overflow integration test.
 
 ## 24. Harness integration
 
-Implement the exact Pico3-shaped public surface in specification §2.2:
+Implement the exact public surface in specification §2.2:
 `Harness.open/resume/suspend/close`, lifecycle gates, root/create/lookup
-`Conversation` objects, ordered `write` handles, send/input handles,
+`Conversation` objects, typed input/write `submit()` and `Submission` objects,
 conversation-bound commits and history pagination, fork/collapse/reset/abort/idle,
-typed task wait/abort, generic document access, task/tool/section registries, and structural conversation watches. Do not restore Pico3's
+typed task wait/abort, generic document access, task/tool/section registries, and
+structural conversation watches. Do not restore Pico3's
 namespace router, fixed document accessors, semantic view events, or manual Chord
 view bridge.
 
 Expose service withdrawal/client detach and product wiring. Implement the §9.4
 agent-mode notification adapter directly from uncoalesced committed publication,
 without another tracker or persistence authority. Migrate TUI hydration to the
-structural conversation watch, make print await its own `InputHandle`, and expose
+structural conversation watch, make print await its own input `Submission`, and expose
 JSON/RPC correlated commands plus ordered committed notifications. Test that
 watch reset compaction cannot erase a subscribed notification lifecycle, late
 clients use structural hydration rather than event replay, progress notifications
@@ -315,15 +349,15 @@ backpressure/disconnect policy stays in the mode adapter.
 Implement the v1 host-extension reload path as stop admission, close/join, dispose,
 rebuild with new document tokens and registered task/tool/section definitions, reopen/migrate live tasks, and resume. Ordinary documents migrate
 on later typed access. Test that closing seals commit and
-get-or-create admission, lets storage settlement for already-flushed admitted
+mutation admission, lets storage settlement for already-prepared admitted
 commits finish despite caller cancellation, stops watches, joins in-flight watch
 callbacks and task/tool/hook invocations outside the Session line, writes no abort
 or terminal outcome, starts no fresh abort invocation, and does not run old and
 new generations concurrently. Include cancellation during watch acquisition and
 a non-cooperative watch callback in shutdown/extension-reload quiescence tests.
 
-Test stable persisted root identity; atomic conversation/config/section/input
-creation; default `"off"` thinking; every configuration getter/setter; explicit
+Test stable persisted root identity; atomic conversation/config/section/input-
+submission creation; default `"off"` thinking; every configuration getter/setter; explicit
 active-tool seed duplicate/unregistered rejection; default active registry
 snapshot; as-of fork inheritance including unavailable historical names; durable
 `missing_active_tool` settlement; fork seed overrides; concrete-entry forks;
@@ -334,8 +368,9 @@ quiescence with eligible work; listener initial/future delivery and isolation;
 and runtime registration between open and resume without resurrection of a task
 settled during open.
 
-Compile-test every §2.2 signature and the usage sequences in the normative
-specification and Chord guide. The erased registry test must include a concrete task with narrowed
+Compile-test every §2.2 and §3 owner/key/seed overload plus the usage sequences
+in the normative specification and Chord guide. Verify that a Chord root
+replacement delta remains distinct from a Session-selected storage checkpoint. The erased registry test must include a concrete task with narrowed
 input, multiple checkpoint phases, and custom hooks. Run all package-specific
 tests and the repository check. Verify a local
 coding-agent turn and a reopened interrupted turn, then stop for final review.