docs: publish reviewed CHAT-01 draft contracts and fixtures (#1507)

docs/plans/chat-01/README.md

@@ -0,0 +1,386 @@
+# CHAT-01 draft conversation and control contracts
+
+Issue #1507, authorized charter 26103. Darkwing authors; Filbert independently
+reviews; Dewey reviews UI semantics; Rocko reviews architecture. Research baseline
+is `370823b354400a73425b4180e07747d97ff87e7a`.
+
+R3 draft, superseding rejected R1 request 26105 and R2 request 26117. R2
+findings are Filbert 26119, Dewey 26120 and Rocko's adversarial re-review via
+agent-send. All three accept the named companion gates below. Approval must name
+all four current file hashes; prior reviews do not approve changed bytes.
+
+These are proposed contracts and synthetic reference models. They implement no
+endpoint, engine adapter, permission grant or live migration. Version 2 is a draft
+revision, not a migration of an existing Mosaic record. Q21 publication does not
+authorize deploying it. Only this directory's four files and scoped tracking are
+in scope. Strict foundation isolation remains; no host-seat exception is approved.
+
+## Record and trust boundary
+
+The local-only draft 2020-12 schema has 24 closed record variants and 20 commands.
+Every declared property is required. Null means absent or unknown, not permission.
+IDs are opaque references, never filesystem paths, bearer credentials or proof.
+UTC dates receive calendar validation. Integers fit JavaScript's safe range.
+The example.invalid schema ID requires no network access.
+
+Only `clientRequest` is untrusted client input. Its actor, authenticated channel,
+grant, policy and supervisor facts come from authoritative server state, never
+from a request header, posted record or tmux preamble. Other variants describe
+server records or authorized projections. Shape validity authenticates nothing.
+Never expose binding, grant, proof records or private blob storage wholesale.
+Text, filenames, Markdown, arguments and labels remain untrusted render data.
+
+| Records | Meaning |
+|---|---|
+| binding, grant, connection | Approved exact scope, source/config/engine pins, execution/cohort, current generation and fence; independent actor authority; authenticated connection incarnation |
+| clientRequest, request, receipt | Expected target and command; immutable causal admission; monotonically revised actual or uncertain outcome |
+| catalogueItem, clientView | Authorized catalogue plus safe current target, connection, view revision, observer/controller mode, supported operations/reasons and attachment limits |
+| entry, event, cursor, page | Stable history/message/block fragments, ordered stream, actor-bound opaque cursor, exact snapshot and stream watermark |
+| draft, upload, draftListing | Actor-private composer revision, private staged bytes and bounded private listing; no native delivery before Send |
+| frozenPayload, queueItem | Immutable accepted text/upload revisions and digest; queue revision, admission lineage, original actor and dispatch disposition |
+| nativeDecision, approval | Stable native decision identity and generation-specific UI projection with exact intent display, native choices and causal decider |
+| confirmation | Short-lived single-use actor/connection-incarnation/target/operation/intent confirmation |
+| stop, cohortProof, effectReport, turnProof | Recorded stop transitions, selected-cohort observations, explicit effect dispositions and native-turn reconciliation |
+
+Capabilities in this proposal are names for future reviewed grants, not changes
+to `roles/`. Missing grants, mappings, evidence, supported operations or required
+recording capacity refuse effects. Do not turn a fail-closed refusal into a
+fallback tmux paste, CLI launch or guessed source path.
+
+## Safe bootstrap, history and rendering
+
+An authorized catalogue response includes `currentView`. It supplies the target
+needed for a first observe/takeover request without exposing the private binding.
+View revisions increase on refresh. Transfer, revocation and reconciliation require
+a fresh view. Availability intersects current grants, verified adapter support and
+control/fence state; request-specific prerequisites still apply. Disabled controls
+carry reasons. A stale view never authorizes a command. Recheck authoritative state
+at admission and dispatch, including stricter verified byte limits.
+
+All connections start as observers. Catalogue creation time, engine launch time
+and last activity are separate nullable values. Relative Age uses last activity.
+Earlier conversations and branches are read-only. Opening them never resumes,
+forks or launches. Each conversation needs an approved project/workspace mapping;
+OS readability, cwd and seat labels do not establish membership.
+
+Cursors bind actor, purpose, conversation, branch, snapshot, source epoch and
+expiry. Refuse unknown, foreign, expired or source-replaced cursors and retain the
+old view with a reconciliation indicator. Never silently switch to a newer file.
+History pages contain at most 100 parts and must also fit 8 MiB serialized UTF-8.
+Each part has at most 64 blocks; strings cap at 262144 Unicode characters.
+Split into continuation parts instead of clipping. Byte enforcement and renderer
+safety need separate implementation tests; schema character limits are insufficient.
+
+Render Markdown/code/tool details and permitted reasoning without active HTML,
+unsafe URLs or terminal escape execution. Unavailable reasoning has empty text;
+unavailable events have empty content. The schema rejects hidden payloads under
+an unavailable label. This does not prove renderer safety or source redaction.
+
+### History and stream identity
+
+Every content event carries an explicit bounded role, including message-start
+and final parts. Role comes from authorized native message metadata, never a
+request ID or guessed text. Entry and stream roles must agree for the same stable
+message; conflicting role or persisted-entry attribution requires reconciliation.
+A final event is self-describing even when no history row preceded it. Empty-history
+NEW user then assistant output, null causal request and reconnect overlap are tested.
+
+`entry.message` and `event.message` are stable within the execution. A broker may
+allocate a transient message key before native persistence, but must preserve it
+when attaching a persisted entry ID. Unknown causal requests stay null. A content
+event cannot omit its message key merely because request and entry are unknown.
+
+Every block carries `block`, `fragment`, `lastFragment`. Block ordinals start at
+zero per message; fragments start at zero per block and stay contiguous across
+entry parts. Continuations retain type and tool-call identity. Do not render a
+split tool invocation as several independent calls.
+
+Final message events use `updateMode:replace`, exact entry/message, `part` and
+`lastPart`. They replace only that addressed part, not the entire message. Text
+and reasoning deltas append to the addressed block fragment. Tool updates replace
+the addressed fragment. Once authoritative final parts arrive, replace provisional
+content rather than appending it again. Missing parts/fragments are incomplete,
+never silently dropped. Preserve branch and subagent separation.
+
+A page's `streamEpoch` and `throughSequence` describe an atomic snapshot cut.
+Subscribe/replay after that watermark. Deduplicate overlap; repeated event IDs
+must have identical bytes. A final-part overlap conflicting with the snapshot,
+sequence gap, unavailable replay or new epoch requires reconciliation. Do not
+concatenate across a gap. The source adapter must produce this atomic cut or
+advertise streaming as unavailable. R3 checks multipart finals, two blocks, null
+request correlation, duplicate delivery, page overlap and reconnect gap/epoch
+refusal. It does not prove a native stream producer or every delta subtype.
+
+Keep loaded history, selection/caret/scroll and private drafts when paused or
+offline. Show stale/paused state and reconcile on reconnect. Native acknowledgment
+is not an assistant answer. Actual return-flow acceptance still requires sending
+and receiving NEW assistant/tool text in the selected UI without manual refresh.
+
+## Admission, dispatch and deduplication
+
+Resolve authenticated connection and actor, current grant revision/expiry/scope,
+approved mapping, verified command support, configuration/trust/policy and evidence
+capacity. Browser Origin/Host/CSRF and private peer authentication remain required
+runtime gates. Nothing in these files implements authentication.
+
+Commands assert conversation/branch/execution/generation; those assertions never
+choose a host process or storage path. Private drafts/uploads need their own
+actor-scoped grants, not existing input control. Observe can read an authorized
+history branch without acquiring control. Native work needs current control,
+except independent takeover and recovery-control acquisition described below.
+
+Commit intent, frozen bytes and queue transition before reporting admission.
+The future broker must serialize dispatch, transfer, edits and cancellation.
+Several file renames are not a proven multi-record transaction.
+
+Canonical fixture hashing uses UTF-8 JSON, lexically sorted object keys, preserved
+array order and no whitespace. Production decoding must reject duplicate keys,
+unpaired surrogates, non-finite numbers and unsafe integers. No text normalization
+or claim of full RFC 8785 conformance is made.
+
+The client fingerprint covers target and validated command, excluding transport
+connection and client request ID. The durable prompt/edit `operationDigest` also
+covers the frozen payload digest, including text and complete upload revisions.
+Dedup keys are authenticated actor, approved conversation and client request ID.
+An exact reconnect retry returns the existing receipt, without requiring that the
+new connection is controller and without redispatch. Conflicting content refuses.
+Resolve referenced revisions against the original immutable admission on retry,
+not the latest mutable draft. Delivery-unknown is never permission to replay.
+The checker models a single receipt lookup and derives its current queue outcome
+when available, including recovery after takeover. It does not implement a durable
+multi-request index or monotonically persisted receipt revisions.
+
+Dispatch resolves queueItem and its stored admission, then rechecks CURRENT
+grant/policy/target/controller/fence and the frozen digest/revision. New client
+commands require a connected authenticated channel. The scheduler instead uses
+the authenticated durable admission and retained execution/controller claim;
+ordinary browser disconnect alone does not pause already broker-acknowledged
+queued work. Broker acknowledgment means durable admission, not native acceptance.
+Native acknowledgment occurs later and never grants replay. Revocation, grant
+expiry, generation change or fences still refuse dispatch.
+
+A pre-dispatch refusal moves a still-queued item to `dispatch-refused`, stores
+failureReason and emits queue-changed. It is not eligible for another scheduler
+attempt. Existing recovered/terminal dispositions are retained. Reconciliation
+returns that actual state, not a stale queued receipt. Frozen content remains
+preserved; no automatic re-admission or native replay is inferred.
+Missing or altered frozen content refuses. A later mutable source-draft revision
+is orthogonal and does not invalidate an unchanged admitted snapshot. An edit
+creates a new immutable admission and queue revision; original admission and
+payload stay unchanged. Per-item cancel affects only that item. Bulk recovery
+classifies all selected snapshots before committing dispositions. Valid content
+becomes recovered drafts; missing/corrupt content becomes `recovery-failed` with
+failureReason and queue-changed evidence. No text is invented from damaged bytes.
+Control transfer and cancellation must still succeed. Stop records list successful
+queueDrafts separately from queueFailures. These failed items preserve their
+references for authorized repair/readback, never automatic resend.
+
+## Commands and private composer lifecycle
+
+All twenty commands are closed unions; no raw RPC/shell/session/provider/permission
+command is accepted. Leading slash text, including leading whitespace, receives
+`text-policy` refusal in the model. Complete slash/resource suppression and native
+command interpretation still block CHAT-03 under B3.
+
+| Commands | Required authority and transition |
+|---|---|
+| observe | observe plus authorized source/cursor; no launch/control |
+| create-draft, update-draft, discard-draft, list-drafts | draft grant; actor/conversation/branch ownership; unsent state and revision CAS for mutations |
+| begin-upload, append-upload, complete-upload, discard-upload | upload grant; private recipient scope, revision and committed offset CAS; verify staged bytes/digest before completion |
+| issue-confirmation, answer-confirmation | confirm grant; issuance also needs the selected destructive-operation grant; actor, connection incarnation, target, expiry and pending-state checks |
+| prompt | send/current controller; own exact unsent draft and valid uploads; freeze and queue, no blind interrupt |
+| edit-queued, cancel-queued | send/current controller; owned queued item and exact revision; refuse dispatch races |
+| takeover | independent take-control plus observe, active/open binding, expected generation; refuse self-takeover |
+| acquire-recovery-control | independent recover-control plus observe, closed admission, absent/disconnected/revoked prior controller and exact confirmation |
+| approval | approve/current controller, pending stable native decision, current projection/intent and enabled exact supported choice |
+| interrupt | interrupt/current controller; fence, recover undispatched input, request native cancellation and reconcile |
+| force-stop | force-stop/current controller and exact confirmation; allowed from active/stopping/uncertain even when work admission is closed |
+| recover | recover/current controller, exact confirmation and stopped prior cohort/effects proof; eligibility only, no launch |
+
+Draft creation/editing and upload staging emit no native input. Reload retrieves
+only the authenticated actor's drafts. Private cursor/large-list support is held
+by the companion below; the model refuses rather than silently truncating. Failed
+upload or prompt admission must retain the original text and bytes. The fixture
+uses synthetic in-memory bytes, not tested durable storage or disk-full recovery.
+
+At most 10 attachments, 20 MiB/file, 100 MiB/message, narrowed by verified harness
+limits. `limits.verified:false` disables attachment acceptance in a real consumer;
+ceiling values alone are not evidence of native support. The miniature upload
+model tests ownership, byte count, digest, offset, storage capacity and refusal
+under unknown/stricter synthetic limits, not MIME sniffing or actual native limits. Chunks cap at 256 KiB. A filename is display
+text only. Never extract/execute uploads or put private staging in an agent's
+workspace before Send. No implicit TTL removes unsent drafts or uploads.
+
+Uploads progress receiving -> staged, then transferring/delivered/sent where a
+verified adapter requires that path. Transfer acknowledgment must bind recipient,
+incarnation and bytes. A posted acknowledgment ID proves nothing. Frozen uploads
+cannot be discarded out from under an admitted payload. Preview/download access
+is NOT authorized by a privateBlobRef.
+
+### Explicit companion dependencies, not hidden endpoints
+
+R3 is not a complete deployable UI API. The following are named prerequisite
+contracts, not authorized implementation tasks or additional queue starts:
+
+* **CHAT-01C private readback/content companion** must define authenticated
+  attachment preview/download ranges, safe public upload projections, durable
+  queue/receipt/confirmation restoration, and actor-bound paginated private-state
+  snapshots/cursors. Until reviewed, these controls remain unavailable. A small
+  own-draft listing fixture does not claim complete browser/server restart recovery.
+  The UI must not invent a side API or enable durable Send acceptance before this
+  dependency is disposed.
+* **CHAT-03I ingress/handoff companion** must resolve board Reply, agent-send/tmux,
+  native terminal/internal queued input and launcher/supervisor restart. R3's
+  disposition for unmediated input is `unmediated-ingress` refusal, not successful
+  message delivery. There is no deliver-message operation or authenticated peer
+  sender mapping here. Jason's ruling and a bounded reviewed charter are still
+  required before changing fleet communications. All-seat control acceptance is
+  blocked until this conflict is resolved. Existing live seats are untouched.
+* **CHAT-03D native dialog companion** must map native confirm/select/input/editor
+  forms without pretending that every extension dialog is a tool permission.
+  They are explicitly unsupported in this draft. No generic yes/no substitution or hidden
+  text-entry endpoint is allowed.
+
+These dependencies belong on subsequent CHAT task charters before implementation.
+Their names do not authorize CHAT-02/03, other queue rows, live work or policy grants.
+
+## Control loss, approvals and stopping
+
+Takeover atomically increments generation, makes the old controller an observer,
+recovers only undispatched work and reprojects pending decisions. It does not
+interrupt active work. Recovered drafts retain original actor, attachments and
+lineage. A different actor cannot read/adopt them by taking control. Same-actor
+interfaces may explicitly resend after reconciliation; never resend automatically.
+
+Disconnect does not release execution ownership, cancel work, allow a pending
+decision or infer denial. Revocation closes affected ingress, clears the revoked
+controller reference, increments generation and publishes control transfer.
+Grant revocation/expiry must trigger the same ingress reconciliation in production;
+the server fixture explicitly exercises connection revocation. Missing that event
+producer is a runtime blocker, not permission to retain unsafe control.
+
+Ordinary takeover is unavailable while fenced. Separately authorized recovery-control
+acquisition can bind an observer when the previous controller is gone. It increments
+generation without reopening admission, releasing the execution claim or launching.
+After reconnection, destructive confirmation must be issued and answered again;
+confirmation binds connection generation, target, operation and stop context and
+is single-use. The digest includes the selected recovery stop or current predecessor
+stop for force-stop. Changing that context requires a new confirmation.
+Self-takeover is refused rather than becoming a queue-cancel shortcut.
+
+An active/open controller revocation creates a revocation-mode fence record with
+the revoked connection and no fabricated client request. A replacement controller
+may acquire recovery-control, then request server-origin reconciliation. A trusted
+turnProof must establish cleared native input, no revoked pending input, valid
+current control and re-projected pending approvals or evidenced terminal decisions.
+Use `turnState:input-reconciled` and `approvalDisposition:pending-reprojected` for
+this path; the active turn need not be interrupted. The server records
+control-reconciled and reopens admission without killing/restarting the engine.
+Already fenced Interrupt/Force-stop paths retain their existing stop and proof
+requirements. Grant revocation/expiry producers must use the equivalent protocol.
+
+`nativeDecision` retains nativeRequest/toolCall/intent/policy identity across control
+transfer. Each takeover creates a NEW approval projection ID with the same decision
+reference and unchanged intent display. Old projections become superseded. Dedupe
+native responses by stable native decision/request identity, not projection ID.
+`resolvedBy` links to a causal request/actor even after takeover. Once a decision is
+terminal, an old projection cannot resolve it again.
+
+The approval includes bounded safe intent text before the tool transcript exists.
+If the full authorized intent cannot be displayed, do not enable approval. Render
+exact native labels. Permission-widening choices remain disabled with a reason.
+Non-permission forms are explicitly blocked by CHAT-03D. A cancel choice is enabled
+only with an independently verified adapter mapping proving non-allow semantics;
+Pi select cancellation cannot inherit confirm cancellation's semantics. Claude's
+permission callback has no invented cancel response.
+
+A local deadline makes an unresolved decision uncertain until native evidence
+establishes timeout/cancellation/resolution. Interrupt/Force stop likewise mark
+pending approvals uncertain, not automatically denied or cancelled. Reconcile
+native outcomes before reopening. Native denial remains authoritative. No tool
+callback substitutes for strict tool isolation. A turnProof that settles an uncertain
+decision must include decisionOutcomes with nativeEvidence. Native resolution with
+no representable client choice uses `resolved-natively`, not an unexplained resolved
+state. chosen may then be null, but native evidence may not. This does not invent a
+human resolvedBy actor for a native timeout or decision.
+
+Interrupt creates a stop record, closes dispatch and recovers queued drafts. It
+may advance fenced -> cancelling -> uncertain. A trusted `turnProof` tied to that
+stop/cohort must establish interrupted turn, cleared native queue with no remaining
+IDs, native approval disposition and recorded effects. Then publish `reconciled`
+with the stop reference, mark turn-interrupted and reopen only under current valid
+control/trust/policy. Before this transition, prompt and ordinary takeover refuse.
+If cancellation hangs, separately confirmed Force stop remains available.
+
+For Pi, documented clear_queue precedes abort; returned text cannot reconstruct
+attachments. Claude cancel_queued is capability-gated; SDK interrupt() alone is
+insufficient. Neither adapter is proven by these fixtures.
+
+Force stop creates a new stop record referencing its predecessor, fences input,
+then records fenced -> cancelling/stopping -> uncertain/stopped. A successor marks
+its unfinished predecessor superseded, a terminal presentation state. Immediate
+trusted death/effect evidence may move fenced directly to stopped; intermediate
+signal observations are not mandatory invented events. Only trusted
+cohort/effects observations may promote stopped, and the binding cannot lead its
+stop record. SIGTERM, EOF, abort acknowledgment or idle does not prove death.
+
+`cohortProof` binds stop, authority, conversation/execution/cohort and membership
+epoch; it includes complete membership, boot/pid/start identity, per-member death
+time, observation time and verification digest. `effectReport` lists invocation
+dispositions with evidence. Recovery derives no-live-members and reconciled effects
+from these records, not world booleans. The fixture's trusted digest registry stands
+in for an authenticated supervisor evidence store. Matching a self-posted hash is
+NOT trust; a real producer/verifier and complete cohort containment remain B3/B4.
+External effects can remain explicitly uncertain; killing never proves rollback.
+
+At most one non-stopped binding may hold a conversation or approved native-session
+identity. Active/reserved duplicates refuse `already-active`; uncertain/stopping
+or unproven stopped replacements refuse `unsafe-replacement`. Recovery needs the
+same conversation/branch/config pins, retained/reacquired exclusive claim, current
+authority and confirmation. It only reports eligibility for separately authorized
+Resume. Browser/server crash, lost acknowledgment or selecting history cannot start
+another engine. The actual execution/writer-claim record is deferred to CHAT-02;
+the single-binding fixture models its assumed retained identity, not a claim store.
+No private-host command is admitted before Q22/CHAT-04R.
+
+## Verification and retained gates
+
+```sh
+node --check docs/plans/chat-01/check.mjs
+node docs/plans/chat-01/check.mjs
+node docs/plans/chat-00/check.mjs
+```
+
+Node plus installed Python jsonschema 4.26.0, no install/network. Missing validator
+or invalid schema fails closed. R3 currently tests 98 shapes, 322 required-field
+omissions, 76 reference cases and seventeen named lifecycle sequences, plus per-item
+recovery, immutable queue-edit, bootstrap and multipart-stream regressions. These
+are finite synthetic examples, not comprehensive model checking or runtime proof.
+
+Explicit model limits accepted for bounded review:
+
+* Unmediated-ingress refusal is an asserted CHAT-03I disposition, not a modelled
+  ingress path. It is excluded from lifecycle counts. Refusal names are bounded
+  but unregistered draft IDs; no closed public reason-code registry is claimed.
+* Control transfer rechecks grants/mapping/recording and verified operation support,
+  but intentionally does not require native preflight. It is bookkeeping only;
+  reprojecting an approval never sends a native response. Native actions still gate.
+* Leading slash text is refused. Other prefixes such as `!` and `@`, and slash
+  commands on later lines, remain admitted unchecked by the miniature text model.
+  Their native interpretation is unverified and held under B3, not declared safe.
+* publicView uses a separate illustrative predicate which can drift from admission,
+  including native preflight details. It is advisory, never authority. A production
+  view must derive availability from shared authoritative eligibility rules; these
+  fixtures do not prove complete UI refusal-reason coverage.
+
+Admission fixtures assume authenticated channels and verified operation registries.
+They do not produce those facts. Native byte limits, permissions, trusted signing,
+durable transactions, full cursor/readback protocols, all delta/dialog forms,
+process observation and actual UI behavior remain unverified. Never report a
+passing synthetic fixture as security enforcement or all-seat acceptance.
+
+B1/B2 retain exact Pi/Claude branch/image/protocol, trust/settings and tool-isolation
+proof. B3/B4 retain every-ingress fencing, crash recovery, approved access mappings
+and supervisor evidence. B5/Q22 retain piece-5/#1508/fleet ordering. B6 requires a
+separately approved cutover/rollback envelope for each live target. #1507 remains
+open for the all-seat demonstration and Jason's workday ruling.