stack/docs/plans/chat-01/README.md

# 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.