@astrosheep/square 0.3.93 → 0.3.95

package/guides/square-api.md

@@ -1,26 +1,36 @@
 # Square and Participant API
 
-`Square` is the actual resource handle shared by SDK, CLI, MCP and Pi. `square-api.ts` selects a
-structural backend resource: `sqlite-square.ts` owns existing local semantics, and `square-stdio.ts`
-adapts that same API over a process connection. `square.ts` remains the executable CLI entrypoint.
+`Square` opens the concrete local SQLite resource shared by SDK, CLI, MCP and Pi. `square-api.ts`
+exports the public `{at, build, inMemory}` entrypoints and `type Square`; `square.ts` remains the
+executable CLI entrypoint.
+For audience computation without opening a square, see the [attention primitive](attention-primitive.md).
+For transaction-scoped attempt custody and the storage-independent dispatch/prepared presentation
+lifecycles used by Square's actual adapters, see the [delivery primitives](delivery-primitives.md).
+Full presentation settlement atomically completes its captured attempt and full-consumption receipts;
+clipped previews record no full receipt. Cancellation/deferral is pre-effect policy, never a veto of a
+successful sink. The public primitive distinguishes sink observations from refused/failed persistence;
+Square retains its existing result shapes and explicit failed classification for rejected sinks.
+For caller-owned item admission and sparse consumption, see the [receive primitive](receive-primitive.md).
 `square-facade.ts` contains only public types. There is no separate operation factory, policy
-dispatcher or `{data, projection}` envelope. See [backends.md](backends.md) for runnable configuration,
-URI encoding, the versioned protocol and explicit remote limitations.
+dispatcher or `{data, projection}` envelope.
 
 ## Open, select, join, close
 
 Membership is explicit: no harness joins a square based on its filename or working directory.
-`PUBLIC.square` has exactly the same behavior as any other square file.
+`PUBLIC.square` has exactly the same behavior as any other square file. Membership (join/done,
+read horizon and listens) is separate from host attachment (whether an exact owner is currently
+executing for that participant). Host shutdown detaches; it does not make the participant leave.
+An owner is an opaque, non-secret string compared only for equality. It is not a participant name
+or authentication credential: one owner may control several names. The SDK requires it explicitly;
+`localUserOwner()` supplies `user:<OS username>@<hostname>` when that is the intended actor.
 
 ```ts
 import { Square } from '@astrosheep/square';
 
-const square = await Square.at({
-  path: './discussion.square',
-  body: { channel: 'example', session: 'alice-process' },
-});
+const owner = 'example:alice-process';
+const square = await Square.at({ path: './discussion.square' });
 try {
-  const joined = await square.join('Alice');
+  const joined = await square.join('Alice', { owner });
   const alice = joined.participant;
   const sent = await alice.express('Hello @Bob', { force: true });
   const page = await square.history();
@@ -31,92 +41,239 @@ try {
 ```
 
 - `Square.build({path, markdown, hardCap?, throttlePerMinute?, template?, force?, ...})` returns
-  the same open resource. `Square.inMemory({markdown, ...})` is synchronous and creates no default
-  native wake transport.
-- `Square.at` accepts `path`, optional `cwd`, `body`, `wakeAddress`, `clock`, `wakeTransport`,
-  `backends`, default `participant`, and a caller-owned connection via `resources`. At the entry
-  boundary, optional `env` resolves path/configuration, the clock, the concrete transport and the
-  discovery index path once. The opened local resource and participant operations do not carry an
-  environment object or derive identity from it. Supply an explicit Body (`channel`, `session`,
-  optional `agent`) for writes; read-only operations need none. `wakeTransport` injection is retained
+  the same open resource. Public `Square.at` and `Square.build` resolve an omitted `wakeTransport`
+  once from `env ?? process.env` to the product's Claude/Codex/Paseo/HTTP defaults; if creation fails,
+  opening still succeeds without proactive wake. A supplied port is used unchanged; `false`
+  disables proactive wake. Activities still land normally without a transport.
+- Synchronous `Square.inMemory` uses only an explicitly supplied port; omitted or `false` means
+  no wake. An injected transport runs the same claim, deferral and final currentness checks as
+  file delivery. Each memory resource has a unique `memory://` identity; this is not a remotely
+  openable address, is not indexed, and does not enable file-based hooks.
+- `Square.at` accepts `path`, optional `cwd`, `env`, `clock`, `wakeTransport` and a caller-owned
+  connection via `resources`. At entry, `env` resolves the path, clock and discovery index path
+  once. `Square.at`, `Square.build` and `Square.inMemory` do not capture a
+  `owner`, `wakeAddress` or default `participant`. The same resource can serve multiple owners;
+  identity is supplied at each join or participant selection. `wakeTransport` injection is retained
   for both file-backed build/open and memory resources.
-- Paths resolve against `cwd`; an omitted path uses `SQUARE_LOCATION` at entry.
-  `stdio://name/key` stays a canonical URI and routes before filesystem access. The `backends`
-  configuration selects named stdio aliases.
-- `await square.participant(name?)` selects a handle **without joining, claiming or reentering**.
-  A supplied name or explicit resource `participant` selects that voice; without either, the artifact
-  must recognize exactly one current seat for the captured Body. Zero or multiple matches refuse.
-  `await square.recognize()` returns all current handles held by that exact Body; the discovery index
-  never establishes ownership, and a name alone never authorizes writes.
-- Join with an explicit name: `square.join('Alice', options?, control?)` returns one `JoinResult`:
-  `{participant, activity, kind, participantCount, observation?}`. The name is required at every
-  boundary: an omitted or blank name refuses, even when the resource has a default `participant` or
-  the captured Body holds exactly one current seat. Only `participant()` performs that unambiguous
-  current-body selection. `participant` is a handle, not a
-  string. `takeover: true` atomically replaces a standing seat; a rejoin after done establishes a new
-  join generation. Same-body reconnection retains its generation. Old handles remain fenced after
-  takeover or rejoin, including when the same Body reacquires the name. There is no separate
-  `Participant.join()` or public `takeover()` API. `participantCount` counts known joined-or-done names.
-- A Square owns its connection unless `resources: createSquareResourceOwner()` lends it one.
-  Closing a borrowing handle leaves that owner open. Request signals never become the borrowed
-  connection's lifetime. The MCP server drains cancelled/in-flight work before closing its owner;
-  explicit location overrides get independent request-owned connections. Stdio opens always own
-  their process connection (SQLite resource lending does not pool remote processes).
+- Local artifact paths resolve against `cwd`; an omitted path uses `SQUARE_LOCATION` at entry.
+- `await square.participant(name, {owner})` selects an **attached, standing** seat held by that exact
+  owner without joining, claiming or reentering. It never manufactures a ghost handle: a never-joined,
+  done, foreign or detached seat is refused with `already_joined`, `reason: 'needs_seat'` and a `join`
+  recovery fact.
+  Foreign custody still requires explicit takeover. The returned handle captures the current owner
+  and generation; subsequent mutations recheck custody. A name alone never authorizes writes.
+- `await square.seatsOf(owner)` returns the owner's standing seats as
+  `[{name, generation, attachment}]`, including attached and detached seats but not done participants.
+  It is read-only and neither joins nor restores a seat. `selectOwnSeat(square, owner, name?)` is the
+  adapter helper: an explicit name is checked through `participant`; otherwise exactly one attached
+  seat is required. For an overview-capable call,
+  `selectOwnSeat(square, owner, undefined, {optional: true})` instead returns `undefined` for a missing
+  owner or zero/multiple attached seats. Selection does not change membership.
+- Join with an explicit name and owner: `square.join('Alice', {owner, wakeAddress?, ...options}, control?)`
+  returns one `JoinResult`: `{participant, kind, activity, observation?}`. The name is required even
+  when the owner holds exactly one seat. `participant` is a handle, not a string. `takeover: true`
+  atomically replaces a standing seat; a rejoin after done establishes a new join generation.
+  Same-owner reconnection retains its generation. A detached seat reattaches with kind `reconnected`,
+  no activity and no change to its read horizon or listens; the operation supplies any wake address.
+  A foreign owner still needs explicit takeover, including for an away participant. Old handles remain
+  fenced after takeover or rejoin, including when the same owner reacquires the name. There is no
+  separate `Participant.join()` or public `takeover()` API.
+- Owner selection prevents accidental custody reuse, not malicious impersonation; never let untrusted
+  input choose another caller's owner. A Square owns its connection unless
+  `resources: createSquareResourceOwner()` lends it one. Closing a borrowing resource leaves that
+  owner open. Request signals never become the borrowed connection's lifetime. The MCP server drains
+  cancelled/in-flight work before closing its owner; explicit location overrides get independent
+  request-owned connections.
+
+The rebuildable HOME discovery index is only a source of candidate paths, never custody authority.
+File-backed successful joins and non-null reattachments attempt best-effort publication of their
+owner and path; opening, building, selecting a participant or expressing does not publish. Memory
+resources are not indexed. Losing the index may delay discovery, but cannot transfer a seat.
+
+## Adapter owner resolution
+
+Owners are nonempty strings without control characters, at most 512 UTF-8 bytes. The core stores
+and compares them without interpreting harnesses. One adapter codec, `harnessOwner`, escapes each
+coordinate segment with `encodeURIComponent`: `<channel>:<session>[:agent:<agent>]`.
+`decodeHarnessOwner` is for adapters only; custom owner strings need no harness spelling.
+
+CLI uses `--owner` or `SQUARE_OWNER` exactly when supplied, then one complete native harness
+coordinate (Paseo is auxiliary), otherwise `localUserOwner()`. Multiple native identities or an
+incomplete Claude-child identity refuse rather than using the human's owner. Plain terminal owners
+have no automatic host lifecycle or wake address: join explicitly and use `catch --idle`.
+MCP uses the call-local harness coordinate, else its configured owner, never tool arguments. Pi and
+native adapters encode their own coordinate; the Slack bridge uses its local configured owner.
+`inbox(input, owner)` and `square inbox --for-owner <owner>` select exact opaque equality.
+
+## Host attachment lifecycle
+
+`square.detach(name, {owner, generation})` checks the exact owner and generation inside the artifact
+transaction. It returns `true` when it detaches, or `null` for stale, replaced, foreign, done or
+already-detached custody. It lands no activity, preserves membership/read horizon/listens, and
+clears wake readiness, catch ownership and delivery deferrals. Detached handles cannot write,
+including an empty catch; reattachment or same-owner rejoin restores access. Proactive claims,
+observers and final send/presentation checks exclude detached seats. Existing receipts and delivery
+evidence survive. A detached participant stays away indefinitely; no timer manufactures a departure.
+
+`square.reattach(name, {owner, wakeAddress?}, control?)` restores a standing seat of that exact owner
+and returns a `Participant`, or `null` if the seat is absent, foreign or done; it never creates
+membership. It preserves the generation, read horizon and listens. On an already attached seat it
+returns a handle and can refresh the supplied wake address, subject to native-route preference.
+Host start/resume restores detached seats found with `seatsOf(owner)` before arming delivery,
+independently across seats and locations. Concurrent departure or takeover remains fenced; a foreign
+takeover between the initial seat read and transaction can refuse instead of returning `null`.
+New/forked owners restore nothing, and hosts do not recover from historical done coordinates.
+
+There are three endings: participant `done` ends membership; Pi shutdown, Codex SessionEnd and
+Claude session end detach only; host-confirmed permanent deletion uses
+`square.endHeld(name, {owner, generation})` to land a fenced `done` on an attached or detached seat,
+returning its lifecycle result or `null` when custody no longer matches. OpenCode `session.deleted`
+is permanent deletion. Takeover replaces either attachment state with `done -> join`; late cleanup
+or restoration by the old owner cannot reclaim it.
+
+`square.cancelDeliveries(name, {owner, generation})` is also generation-fenced: for an attached
+current seat it advances the suppression boundary through the current activity head, returning
+whether it changed. A mismatched seat returns `false`; a detached or concurrently replaced seat may
+be refused. It does not consume activity or recall an external send already past its final check.
+
+## HTTP(S) wake notifications
+
+File-backed public opens include a built-in `http` wake transport for both HTTP and HTTPS.
+Register its address through SDK join or same-owner `reattach`:
+
+```ts
+const { participant: bob } = await square.join('Bob', {
+  owner: 'example:bob-process',
+  wakeAddress: { kind: 'http', address: {
+    url: 'https://example.com/square/wake',
+    tokenEnv: 'BOB_WAKE_TOKEN', // optional; sender process environment variable
+  } },
+});
+```
+
+The URL must have an HTTP(S) scheme and hostname, with no embedded username/password or fragment.
+Local/private endpoints are allowed. HTTPS uses normal certificate validation. The sender POSTs
+`Content-Type: application/json` to that URL without following redirects. When `tokenEnv` is
+configured, the sender resolves it in its own environment (`env` at open, otherwise `process.env`),
+not the receiver's. A missing, blank or invalid bearer token refuses locally without HTTP I/O.
+Keep the secret in that environment variable, never in the stored address. Diagnostics do not echo
+URLs or raw network errors; URL query strings may themselves be sensitive and remain stored config.
+
+The JSON body contains only:
+
+```json
+{
+  "location": "/sender/path/discussion.square",
+  "participant": "Bob",
+  "activity": "act/12",
+  "actor": "Alice",
+  "attemptN": 0,
+  "preview": "<existing rendered Square wake reminder>"
+}
+```
+
+`attemptN` is omitted when unavailable. The preview is the existing rendered awareness reminder,
+not a new payload template or full artifact. Owner, route and claim token are never included. `location` is the
+**sender's artifact locator**, not a downloadable URL. HTTP adds wake notification, not a remote
+Square backend: the receiver owns how it queues/wakes its agent and gives it access to Square.
+
+Return 2xx promptly only after accepting wake custody. A 2xx records an accepted wake, **not** catch
+or presentation; activity remains unread until normal consumption. Redirects and 4xx are rejected,
+5xx are transient failures, and other non-2xx statuses are rejected. A network error or timeout
+after sending starts is **unknown**: the receiver may already have accepted. Unknown/accepted wakes
+are not automatically replayed. There is no retry loop in the HTTP adapter; existing delivery policy
+owns future dispatch. Local configuration, absent preview, expired pre-send budget or a refused final
+gate sends nothing. One deadline covers preparation, the final gate and waiting for response headers;
+response bodies are cancelled rather than read. Claims, per-owner ordering, deferral, attachment and
+cancellation checks are shared with every transport. `wakeTransport: false` still disables wakes,
+and an injected transport remains authoritative.
+
+The enclosing dispatcher's safety deadline is transport-neutral: if an attempt is still unsettled,
+it records conservative **unknown**, even when HTTP has not started (for example, while the final
+send gate is stalled). A local pre-send expiry is known no-send only when the adapter's result arrives
+before that outer fallback. HTTP still must not start I/O after a stalled gate resumes past its
+deadline; the persisted unknown remains and prevents automatic replay. This does not change the
+shared dispatcher's timeout or retry policy.
 
 ## One set of operations and defaults
 
 Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
 A file-backed `stream` follows the path with a fresh artifact read for each page, so atomic file
 replacement is visible even while the resource holds its original connection. Its iterator owns
-its observation lifetime: `return()` interrupts a pending pull; closing the Square does not close
-that independent path observation. Internal readers that explicitly borrow an artifact port leave
-its lifetime with the lender and propagate port failures rather than waiting for path repair.
-Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `hold`, `resume`, `done`,
-`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`;
-its `history` delegates to the same Square history operation.
-
-- Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
-  includes the committed `activity`, `waited`, optional `delivery`, and landing-time warnings
-  (`unmatchedMentions`, `replyAuthorNotHere`). Warnings are not stored on the activity.
+its observation lifetime: `return()` interrupts a pending pull; closing a local Square does not close
+that independent path observation.
+Internal readers that explicitly borrow an artifact port leave its lifetime with the lender and
+propagate port failures rather than waiting for path repair.
+
+`Activity` is `{id, at, kind, actor, body?, metadata?, mentions, reach?, target?, reply?}` throughout
+the SDK. Stream without a recipient yields these activities; with a recipient it selects
+their landed directed activities and adds `perception` and the landing route `via`
+(`mention`, `reply`, `attention`, or `bell`). Perception follows the viewer's actual landed audience;
+`via` is absent when no directed route exists. Stream starts at a bounded tail or after an `ActivityId`
+like `act/12`; it never consumes activity.
+Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `done`,
+`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`. History belongs only to
+Square; there is no `Participant.history`.
+
+- Express waits when throttled unless `noWait: true`, for **every** caller. `ExpressResult`
+  includes the committed `activity`, optional landing-time warnings (`unmatchedMentions`,
+  `replyAuthorNotHere`), `hint` and `observation`. Warnings are not stored on the activity.
 - A say may carry `metadata`, an immutable JSON object with nested JSON values and a maximum serialized
   UTF-8 size of 16 KiB (`ACTIVITY_METADATA_MAX_BYTES`). `alice.express({body?, metadata?, ...options}, control?)`
   is the object form; the existing `express(body, options?, control?)` form remains valid. A non-empty
   body may carry `{}`; an omitted, empty or whitespace-only body requires non-empty metadata. Metadata-only
   says omit `body` from public activity records. Invalid objects, cycles, unsupported values and oversized
   metadata refuse before landing with `activityUnsent`. Metadata is carried unchanged by express, history,
-  catch, status/latest, unread projections and stream records through the SDK, stdio, CLI and stream.
+  catch, status/latest, unread projections and stream records through the SDK, CLI and stream.
   MCP and Pi tools are not a metadata surface: their `express` requires a body and its schema rejects a
-  `metadata` argument, and every shared tool receipt omits metadata, so tool history/catch results carry
-  the same activities without it. Metadata does not affect mentions, replies, listening, audience,
+  `metadata` argument. Tool history/catch return rendered text with a structured-activity placeholder,
+  not metadata JSON or activity objects. Metadata does not affect mentions, replies, listening, audience,
   ordering, consumption or permissions. A current participant may temporarily defer proactive delivery
-  by exact metadata match through the SDK/stdio lease API below. Metadata may nest up to 256 levels; the bound is enforced before
+  by exact metadata match through the SDK lease API below. Metadata may nest up to 256 levels; the bound is enforced before
   persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
   metadata JSON. There is no archive metadata filter, query language or index; CLI `--metadata <json>` is the only
   metadata input flag.
-- Catch returns `{activities, consumedThrough, remaining, idleExpired, status?, observation?}`.
-  Omitted/zero idle is immediate; positive idle uses the single leased quiet wait. Receipt selection,
-  ordinals, counts and terminal facts settle in the receipt transaction. Cancellation/replacement
-  releases only that waiter's lease and never consumes future activity.
+- Catch returns `{activities, remaining, reason, hint?, observation?}`. Each activity includes
+  viewer-relative `perception` and `via`. Reasons are `drained`, `idle`, `capped`, `quorum`,
+  `replaced`, or `already-active`. Omitted/zero idle is immediate; positive idle uses the single
+  leased quiet wait. Receipt selection, perception, routes, counts and terminal facts settle
+  in the receipt transaction. Cancellation/replacement releases only that waiter's lease and never
+  consumes future activity.
 - All history callers return a `HistoryResult` object with `activities`. Default page size is ten;
   `limit: null` explicitly requests an unbounded archive. Numeric limits must be 1–100. Contextual
   queries still reject an implicit merged window over 100 activities; an explicit numeric limit
-  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts.
+  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts; history
+  observations retain lifetime say ordinals for CLI `history --format number`.
 - `participants()` returns `{participants, observation?}` and `listening()` returns
-  `{listening, observation?}`, not arrays carrying metadata.
+  `{listening, observation?}`, not arrays carrying metadata. Participant summaries use `presence`
+  (`never-joined`, `active`, `watching`, `away`, or `done`). Away participants remain members,
+  count toward in-square totals and keep receiving normal bell, mention and listened audience. Its roster
+  supplies the participant counts. Core `square.status({viewer})` uses only the explicitly supplied viewer; with
+  no viewer it returns an unfiltered overview without viewer-specific `listening`. Core status does
+  not select or authorize a seat. CLI and tools check an explicit `--as`/`as` with `selectOwnSeat`;
+  otherwise exactly one attached seat of the caller's owner becomes the viewer, while zero or multiple
+  seats (or no owner) produce the overview. Snapshot participants use the same `name`, `presence` and
+  `listening` facts, excluding never-joined people; its detached `delivered(name, id)` predicate
+  remains available.
 - `unlisten(target)` removes only that participant's current listen edge to the target, without
   leaving or blocking future mentions/replies. It returns the same `ListenerChangeResult` as listen
   and ignore, with `activity: null` when no listen exists. Existing ignores are unchanged. Earlier
   landed audiences and receipts are never rewritten; listening again remains available.
-- Lifecycle operations use the same artifact custody gate. Done accepts no message and retires
-  only its captured Body/join generation; it never implicitly rejoins or grants a completed seat
-  write authority.
+- Lifecycle operations return `{activity, observation?}` and use the same artifact custody gate;
+  observations do not repeat the activity. Join entry uses public activities with settled perception,
+  and status observations use public join activities. Done accepts no message and retires only its
+  attached, captured owner/join generation; it never implicitly rejoins. A done participant is not
+  recoverable authority for any host path.
+- Recovery summarizes unread directed activity with per-sender count, latest age and the single
+  greatest-index preview. Age uses the greatest timestamp, which may belong to another activity.
 
-Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
-Listener/lifecycle operations take optional observation options before that control argument.
+Operations that accept an `OperationControl` use a final argument with `signal` and optional typed
+`onProgress`. Listener/lifecycle operations take optional observation options before that argument;
+participant selection, seat discovery and host cleanup methods do not take an `OperationControl`.
 
 ## Temporary proactive delivery deferral
 
-SDK and stdio Participants expose the same three operations. There are no CLI/MCP/Pi authoring
+SDK Participants expose three operations. There are no CLI/MCP/Pi authoring
 commands or listing operation in this delivery. Existing proactive adapters still obey deferrals.
 
 ```ts
@@ -147,7 +304,7 @@ try {
   24 hours. Invalid matches, durations and IDs refuse with `invalid_args` before mutation.
 - Renewal extends that same live lease from the renewal operation's clock; expired/missing IDs
   return `null`, and release returns `false`. Independent overlapping leases are never merged;
-  releasing one cannot end another. A captured current Body/join generation is required for every
+  releasing one cannot end another. A captured current owner/join generation is required for every
   mutation. Stale handles retain the ownership refusal; done/takeover/rejoin retire old leases.
 - Lease writes change delivery revision, not conversation history. They do not create a receipt,
   change audience or unread counts, hide an archive record, or prohibit explicit catch. Catch alone
@@ -163,7 +320,7 @@ try {
   with acquisition and remain dispatched; a sink effect already written cannot be withdrawn.
   Presentation eligibility is checked before the effect, not again as a veto after success. A batch
   claims and filters its items before its one sink call, then records exactly the successfully rendered
-  set under each captured Body/join generation. A lease acquired while the sink returns or before a
+  set under each captured owner/join generation. A lease acquired while the sink returns or before a
   later item's evidence commit does not erase success or allow replay after release. Cancellation
   likewise stops pre-effect work, not truthful completion after a successful sink: evidence settles
   on the original connection with an independent bounded storage lifetime and the same seat fences.
@@ -179,13 +336,23 @@ has a concrete optional observation type, without conditional generics or a gene
 Data-only calls do not hydrate join history, the pre-expression feed, catch presence enrichment,
 or history/status presentation annotations.
 
-Express captures its optional directed feed before the attempt and returns count/held/time facts
+Express captures optional unread context before the attempt: the latest five directed,
+unseen activities after the current join, each preview capped at 400 Unicode characters,
+plus the count outside that preview. It hydrates only that page, not the entire cursor suffix.
+This is a nonconsuming preview even when a short body fits in full; only `catch` or the
+normal full-notification presentation path consumes it. Count and time facts come
 from the committed transaction. Listener and lifecycle observations likewise use their mutation's
 facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
 entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the
 successful receipt survives. Catch preserves its committed page even if optional nearby presence
 fails. A cancellation or failed clock after commit cannot turn these receipts into an unsent retry.
 
+Delivery readiness is participant-specific, not a property of the Square resource.
+`ParticipantSummary.deliveryAvailable`, `JoinObservation.deliveryAvailable` and
+`CatchObservation.deliveryAvailable` reflect whether the participant's seat has a stored wake
+address. Catch captures this fact with its selection. Join and catch observations require
+`observe: true`. These flags do not prove that a receiver is live or that delivery succeeded.
+
 `OperationError.operation` supplements authoritative error facts with caller/filter/recipient and
 express certainty. Selected-row/execution failures remain unknown unless admission proved the
 expression unsent. CLI saves raw drafts even when opening the resource fails; its initial open
@@ -194,39 +361,95 @@ receives the express abort signal, while recovery reopening is deliberately unca
 ## Adapters and standalone functions
 
 CLI and tools only adapt input, identity, resource lifetime and output. They do not import private
-actions, storage, admission, scanners or query execution. MCP/Pi use the shared `square-tools.ts`
-definitions. Join JSON contains `participant.name` and the receipt fields, never the handle or its
-resources. Express wire output omits the internal delivery diagnostic as before.
+actions, storage, admission, scanners or query execution. CLI `--json` for join, express, catch,
+history, listen, ignore, unlisten, listening, done, status, participants and inbox
+serializes the same SDK result without requesting `observe: true`. Only `observation` is omitted and
+a live Participant handle becomes `{name}`. History returns one JSON document, including an empty
+`activities` array; `history --format` remains human-oriented. `participants --limit` limits only
+human text, not the SDK result. Stream `--ndjson` remains one SDK stream record per line.
 
-`discover(input, options?, control?)`, `inbox(input, sessionId, options?, control?)`,
+MCP/Pi use the shared `square-tools.ts` definitions. All seven tools return only the CLI's rendered text, with no `outputSchema`
+or `structuredContent`. Join text includes its context and recent activity; express text
+includes landing ID/reach, warnings and bounded unread previews, never the sent body echo
+or internal observation tables. Failures remain failed tool results with readable recovery
+text. The SDK and CLI JSON keep their full domain receipts. The optional express observation
+contains `context: {activities: [{id, actor, preview, truncated}], remaining}`, not the old
+unbounded `pendingPublic`/ordinal/perception tables.
+
+Express still finishes attempted notification delivery before releasing its resource.
+It overlaps at most four receiving sessions per dispatch, preserving order within each
+session and draining started work even on failure. Claims, final freshness checks and
+uncertain-delivery suppression remain unchanged. Paseo inventory discovery is asynchronous;
+overlapping attempts share only the in-flight inventory read, never a cached idle status.
+The standalone `discoverPaseoAgents` export now returns a promise.
+
+`discover(input, options?, control?)`, `inbox(input, owner, options?, control?)`,
 `diagnoseSquare(input, control?)`, and `migrateSquare(input, control?)` are ordinary public exports.
 They are not methods on a synthetic cross-square object. Diagnose/migrate resolve a path without
 opening a valid current-format Square first.
 
 ## Artifact format and explicit migration
 
-The current artifact format is 5. It owns participant seats, delivery evidence, cancellation and
-independent delivery deferrals, separate from conversation activities and catch leases; `unlisten` remains a real history activity. Ordinary opens
-refuse older formats with migration guidance and never convert them implicitly.
+The current artifact format is 7. It stores opaque owners rather than harness coordinates and
+preserves format 6's attached/detached distinction. Seats, delivery evidence, cancellation and
+independent delivery deferrals remain separate from conversation activities and catch ownership.
+Ordinary opens refuse older formats with migration guidance and never convert them implicitly.
 
 Stop all sessions and services using the artifact, make an offline backup, then run
 `square --location <path.square> migrate` and `doctor` before reopening with upgraded runtimes.
-For formats 2/3, also freeze and back up the legacy HostLedger used for owner/evidence import.
-Format 4 adds only an empty deferral table and its owner/generation/expiry index, preserving
-all existing facts and revisions without consulting HostLedger. Supported row formats 2/3 convert
-directly into format 5 in one transaction, only when owner/route/join mappings are
-directly verifiable; no seat is manufactured for done participants. Replay-critical native ambiguity
-refuses rather than disappears, including the conservative refusal of any nonempty legacy token-only
-tombstone table. Current-format migration is a byte-preserving no-op. See [migration.md](migration.md)
-for the deliberately lossy metadata policy, source-preserving refusal and filesystem requirements.
-Updating a package does not migrate files or install a new runtime.
-
-## Deliberate migration breaks
+Supported formats 2–6 convert to 7 in one transaction. Format 6's Body coordinates become encoded
+owners while attachment, generations, wakes, evidence and revisions survive. Formats 4/5 first gain
+attached seats; format 4 also gains empty deferral support. Formats 4–6 never consult HostLedger.
+Historic host-cleanup departures cannot be distinguished from voluntary `done` and stay done.
+For formats 2/3, also freeze and back up the legacy HostLedger used for verified owner/evidence
+import; no authority is manufactured for done participants. Replay-critical native ambiguity
+refuses rather than disappears, including any nonempty legacy token-only tombstones.
+Current-format migration is a byte-preserving no-op. See [migration.md](migration.md) for the
+narrow metadata policy, source-preserving refusal and filesystem requirements. Updating a package
+does not migrate files or install a new runtime.
+
+## SDK breaking migration: opaque owners
+
+Artifact format 7 introduced opaque owners; format-6 artifacts required explicit migration before
+opening with that format. Current artifacts use format 8 and require explicit migration from format 7.
+`Body`, `sameBody` and `validateBody` are removed from the core and public API. Replace identity
+objects with an explicit owner at each identity-bearing operation; do not put identity on a resource:
+
+```ts
+import { Square } from '@astrosheep/square';
+
+const aliceOwner = 'example:alice-process';
+const bobOwner = 'example:bob-process';
+const square = await Square.at({ path: './discussion.square' });
+try {
+  // Previously: pass body/wakeAddress/participant to Square.at and join(name).
+  const { participant: alice } = await square.join('Alice', { owner: aliceOwner }); // wakeAddress is optional
+  const { participant: bob } = await square.join('Bob', { owner: bobOwner }); // same resource, another owner
+  // For an already attached seat, select it without joining:
+  const selected = await square.participant('Alice', { owner: aliceOwner });
+  const seats = await square.seatsOf(aliceOwner);
+  const { activities } = await square.history(); // not alice.history()
+  const status = await square.status({ viewer: selected.name });
+  console.log(alice.name, bob.name, seats, activities, status);
+} finally {
+  await square.close();
+}
+```
+
+Replace `recognize()`/`bodySeats()` with `seatsOf(owner)`, followed by explicit attached-seat
+selection as needed; replace `implicitJoin` with `reattach(name, {owner, wakeAddress?})`. Replace
+`detachOwnedSession`/`endOwnedSession` with the generation-fenced `detach`/`endHeld` methods above.
+`forBody` is removed: use the same Square with operation-local owners. Read readiness from
+participant summaries or join/catch observations, not the removed resource-level
+`automaticDeliveryAvailable`. Core status no longer infers a viewer. Participant selection no longer
+returns a handle for a missing, done, foreign or detached seat.
+
+## Other deliberate migration breaks
 
 The independent `createSquareApplication` API, its options/results/aliases, and `square-application.ts`
-are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins must use
-`(await square.join(name)).participant`; history callers must use `.activities` and opt into full
-archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
+are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins return
+`(await square.join(name, {owner})).participant`; history callers must use `.activities` and opt into
+full archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
 uses `path`, consistent with `Square.at`, rather than `squarePath`.
 
 External consumers must migrate before taking this source version. Editing source does not update

package/guides/symmetric-domains.md

@@ -0,0 +1,92 @@
+# Two equal domains, using the public primitives
+
+[`examples/symmetric-domains.mjs`](../examples/symmetric-domains.mjs) is a plain
+ESM installed-package consumer. It imports only Node builtins and
+`@astrosheep/square/attention`, `/receive`, and `/delivery`; it never constructs
+`Square`. Two instances of the **same `Domain` implementation** independently
+originate, receive, present and consume work. Neither is a master or a relay.
+
+## Run from an installed package
+
+In a consumer project with `@astrosheep/square` installed:
+
+```sh
+cp node_modules/@astrosheep/square/examples/symmetric-domains.mjs ./symmetric-domains.mjs
+node ./symmetric-domains.mjs
+```
+
+The script prints a JSON summary. It also exports
+`demonstrateSymmetricDomains()` for programmatic use. The repository's
+`test/package-consumer.test.js` packs the package, copies the shipped example
+into an isolated consumer, runs it there, and asserts the summary. It does not
+substitute repository-relative imports, a second implementation, or path aliases.
+
+## What the demonstration does
+
+1. East originates a message for one local reader and two selected west readers.
+   West independently originates a message for one local reader and two east
+   readers. The static application directory supplies eligibility and destination
+   routing; no primitive parses the recipient spelling.
+2. Each origin commits its local item/audience before any link effect. East uses
+   opaque random string keys; west uses decreasing negative numbers. Every
+   destination assigns its own key. `data.origin` is just application data, not
+   a global cursor, admission key or identity codec.
+3. `resolveAudience` selects recipients; the application maps `{recipient, route}`
+   once to receive's `{recipient, via}` addresses, preserving them locally and
+   across the handoff. Application routing groups that result by destination.
+   One `dispatchEffect` passes **one payload with both selected
+   remote recipients**, not one payload per recipient. Its attempt series is
+   bound to source item + destination + purpose in the source's private store.
+4. East's link returns `accepted` after west admits. West's link deliberately
+   returns `unknown` after east admits. Admission leaves both destination
+   recipients pending. In both directions a second dispatch acquires no claim:
+   the actual stored `accepted`/`unknown` attempt stops replay through
+   `claimAttempt`, not a callback counter or link-level duplicate filter.
+5. Each destination uses `preparePresentation` / `presentPrepared` to present the
+   full payload to its first recipient. Settlement completes that recipient's
+   presentation attempt and calls `recordConsumed` for the captured receipt in
+   **one synchronous transaction**. The other recipient remains pending until
+   separately consumed. Origin receipts are unchanged by destination consumption.
+6. With the link disabled, both domains still admit and consume three local-only
+   messages. Exact consumption of the middle item is repeatable; subsequent
+   one-item pages find the older and newer receipt holes in local insertion order.
+   No remote sink is invoked for this local work.
+
+## Primitive responsibilities and caller obligations
+
+| Primitive | Owns | Example caller supplies |
+|---|---|---|
+| `resolveAudience` | Deterministic attention selection | Eligible directory and explicit routing |
+| `receive` | Item and address insertion | Local IDs, uniqueness, isolation and rollback |
+| `consumeReceived` / `recordConsumed` | Selection/full receipts, first-write-wins coordinates | Ordered reads and recipient + local item receipt storage |
+| `claimAttempt` / `settleAttempt` | Scoped attempt transitions, terminal uncertainty | One transaction-bound series, tokens, lease times and persistence |
+| `dispatchEffect` | Claim/currentness/effect/timeout/settlement lifecycle | Bound port, link callback, pre-send policy and actual deadline enforcement |
+| `preparePresentation` / `presentPrepared` | One-shot custody, sink outcome and settlement | Captured payload, receipt coordinates and atomic completion + receipts |
+
+The memory adapter clones a draft and commits only when its synchronous callback
+returns. A throw discards all changes, including an attempt completion if receipt
+recording fails. It never holds a transaction across an `await`. Each effect claim
+commits before external work; settlement opens a new transaction. Returned rows
+are copied, and the two stores share no mutable state. A real application must
+provide equivalent isolation, fencing, uniqueness and atomic rollback in its own
+storage, plus durability if required. The primitives do not supply a database.
+
+The link obeys `beforeSend()` and checks cancellation/deadline **after** awaiting
+that gate, immediately before admission. A late policy answer is not permission
+to send after timeout. Settlement does not re-check policy after a successful
+sink: it records captured facts without erasing success or selecting new items.
+Public effect reports distinguish callback observation from persistence results.
+
+## Deliberately bounded claims
+
+The adapter is nondurable illustrative memory, and the link is an in-process
+function. `accepted` means destination admission only. Presentation success means
+this example's callback captured the supplied full payload, **not** that a human
+or model read it. Unknown suppresses automatic replay but does not reconcile it;
+this example has no crash recovery, cross-domain transaction, exactly-once effect,
+network protocol, federation, authentication or discovery implementation.
+
+One handoff per destination is a boundary an application **could choose** for
+billing. No charges, billing ledger or payment semantics are implemented here.
+For the underlying contracts, see [attention](attention-primitive.md),
+[receive](receive-primitive.md), and [delivery](delivery-primitives.md).