@astrosheep/square 0.3.93 → 0.3.95

package/examples/symmetric-domains.mjs

@@ -0,0 +1,250 @@
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { resolveAudience } from '@astrosheep/square/attention';
+import { receive, consumeReceived, recordConsumed } from '@astrosheep/square/receive';
+import { claimAttempt, settleAttempt, dispatchEffect, preparePresentation, presentPrepared } from '@astrosheep/square/delivery';
+
+// Application routing fixture, not discovery or a core identity format.
+const directory = new Map([
+  ['e/author', 'east'], ['e/reader', 'east'], ['e/other', 'east'],
+  ['w/author', 'west'], ['w/reader', 'west'], ['w/other', 'west'],
+]);
+
+// One structural ReceiveWrite adapter. Array insertion order is local order;
+// opaque item keys are only compared for equality, never parsed or sorted.
+function receiveStore(state) {
+  const tx = {
+    insertItem({ key, data }) {
+      if (state.items.has(key)) throw new Error('duplicate item');
+      state.items.set(key, structuredClone(data));
+    },
+    insertAddress(key, address) {
+      if (tx.addressed(address.recipient, key)) throw new Error('duplicate address');
+      state.addresses.push({ key, ...address });
+    },
+    heads(recipient, query, { unconsumed, limit }) {
+      return state.addresses.filter(row => row.recipient === recipient
+        && (!query.via || row.via === query.via)
+        && (!unconsumed || !tx.receipt({ recipient, item: row.key }))).slice(0, limit);
+    },
+    addressed: (recipient, key) => state.addresses.find(row => row.recipient === recipient && row.key === key),
+    load: keys => new Map(keys.filter(key => state.items.has(key)).map(key => [key, state.items.get(key)])),
+    count: (recipient, query, unconsumed) => tx.heads(recipient, query, { unconsumed, limit: Infinity }).length,
+    receipt: ({ recipient, item }) => state.receipts.get(recipient)?.get(item),
+    insertReceipt({ recipient, item }, at) {
+      if (!state.receipts.has(recipient)) state.receipts.set(recipient, new Map());
+      const receipts = state.receipts.get(recipient);
+      if (receipts.has(item)) return false;
+      receipts.set(item, { at });
+      return true;
+    },
+  };
+  return tx;
+}
+
+// A tiny illustrative consumer, NOT a storage backend or durable runtime.
+class Domain {
+  #state = { items: new Map(), addresses: [], receipts: new Map(), series: [] };
+
+  constructor(name, nextKey) {
+    this.name = name;
+    this.nextKey = nextKey;
+  }
+
+  transaction(change) {
+    const draft = structuredClone(this.#state);
+    const result = change(draft, receiveStore(draft));
+    if (result instanceof Promise) throw new Error('no awaits inside memory transactions');
+    // A throw above discards the draft. No capability or mutable row escapes.
+    const captured = structuredClone(result);
+    this.#state = draft;
+    return captured;
+  }
+
+  originate(actor, mentions, text) {
+    // Attention names its route; receive stores that application route as via.
+    const audience = resolveAudience({ actor, recipients: [...directory.keys()], mentions })
+      .map(({ recipient, route }) => ({ recipient, via: route }));
+    const key = this.nextKey();
+    const data = { text, origin: { domain: this.name, key } };
+    this.transaction((_state, tx) => receive(tx, {
+      item: { key, data }, audience: audience.filter(a => directory.get(a.recipient) === this.name),
+    }));
+    const outgoing = new Map();
+    for (const address of audience) {
+      const destination = directory.get(address.recipient);
+      if (destination === this.name) continue;
+      if (!outgoing.has(destination)) outgoing.set(destination, []);
+      outgoing.get(destination).push(address);
+    }
+    return { key, data, outgoing };
+  }
+
+  admit(data, audience) {
+    const key = this.nextKey(); // Destination owns this identity, not origin.key.
+    this.transaction((_state, tx) => receive(tx, {
+      item: { key, data }, audience,
+    }));
+    return key;
+  }
+
+  // Captured item/target/purpose are application coordinates, not an encoded key.
+  // For dispatch target is a destination; for presentation it is one recipient.
+  effectPort(purpose, item, target, fullReceipts = []) {
+    const rows = state => {
+      let series = state.series.find(s => s.purpose === purpose && s.item === item && s.target === target);
+      if (!series) {
+        series = { purpose, item, target, attempts: new Map() };
+        state.series.push(series);
+      }
+      return {
+        list: () => structuredClone([...series.attempts.values()].sort((a, b) => b.ordinal - a.ordinal)),
+        byToken: token => structuredClone(series.attempts.get(token)),
+        insert: row => { series.attempts.set(row.token, structuredClone(row)); },
+        replace: row => { series.attempts.set(row.token, structuredClone(row)); },
+      };
+    };
+    const current = (state, tx) => state.items.has(item) && (purpose === 'dispatch'
+      || Boolean(tx.addressed(target, item)) && !tx.receipt({ recipient: target, item }));
+    return {
+      claim: async () => this.transaction((state, tx) => {
+        if (!current(state, tx)) return undefined;
+        const claim = claimAttempt(rows(state), {
+          purpose, token: randomUUID(), at: Date.now(), leaseMs: 30_000, data: {},
+        });
+        return claim.status === 'acquired' ? { token: claim.token, ordinal: claim.ordinal } : undefined;
+      }),
+      current: async () => this.transaction(current),
+      settle: async (claim, completion) => this.transaction((state, tx) => {
+        const recorded = settleAttempt(rows(state), {
+          token: claim.token, outcome: completion.outcome, at: Date.now(), data: completion,
+        });
+        // ONE commit: attempt completion plus captured full-consumption receipts.
+        // No post-effect cancellation/currentness veto and no re-selection.
+        if (recorded && completion.outcome === 'presented') recordConsumed(tx, fullReceipts, Date.now());
+        return recorded;
+      }),
+    };
+  }
+
+  consume(recipient, selection) {
+    return this.transaction((_state, tx) => consumeReceived(tx, recipient, selection, Date.now()));
+  }
+
+  pending(recipient) {
+    return this.transaction((_state, tx) => tx.heads(recipient, {}, { unconsumed: true, limit: Infinity }).map(h => h.key));
+  }
+
+  receipts() {
+    return this.transaction(state => [...state.receipts].flatMap(([recipient, items]) =>
+      [...items].map(([item, { at }]) => ({ recipient, item, at }))));
+  }
+
+  attempts() {
+    return this.transaction(state => state.series.map(({ purpose, item, target, attempts }) =>
+      ({ purpose, item, target, outcomes: [...attempts.values()].map(a => a.outcome) })));
+  }
+
+  async present(recipient, item, sink) {
+    const payload = this.transaction((_state, tx) => {
+      if (!tx.addressed(recipient, item)) throw new Error('not addressed');
+      return tx.load([item]).get(item);
+    });
+    const prepared = await preparePresentation({
+      payload, coverage: 'full',
+      port: this.effectPort('presentation', item, recipient, [{ recipient, item }]),
+    });
+    return prepared ? presentPrepared(prepared, sink) : undefined;
+  }
+}
+
+export async function demonstrateSymmetricDomains() {
+  // Same implementation, truly separate stores and unrelated key spaces.
+  let westKey = -700;
+  const east = new Domain('east', () => `opaque?${randomUUID()}`);
+  const west = new Domain('west', () => westKey--);
+  const domains = new Map([['east', east], ['west', west]]);
+  const handoffs = [];
+  let online = true;
+
+  async function sendAll(source, message, mode = 'accepted') {
+    const reports = [];
+    for (const [destination, audience] of message.outgoing) {
+      const report = await dispatchEffect(source.effectPort('dispatch', message.key, destination), async context => {
+        if (!await context.beforeSend()) return { outcome: 'not-capable' };
+        // A final policy gate may finish after the runner's timeout. Never mutate
+        // the destination after our deadline or cancellation, even if it said yes.
+        if (context.signal?.aborted || Date.now() >= context.deadline) return { outcome: 'not-capable' };
+        if (!online) return { outcome: 'failed' }; // Known no-send in this in-process fixture.
+        const key = domains.get(destination).admit(message.data, audience);
+        handoffs.push({ from: source.name, to: destination, key, audience: structuredClone(audience) });
+        // Unknown deliberately happens AFTER admission. This is not a dedup protocol.
+        return { outcome: mode, data: { destinationKey: key } };
+      }, { timeoutMs: 1000 });
+      reports.push(report);
+    }
+    return reports;
+  }
+
+  const eastMessage = east.originate('e/author', ['e/reader', 'w/reader', 'w/other'], 'East says hello');
+  const westMessage = west.originate('w/author', ['w/reader', 'e/reader', 'e/other'], 'West says hello');
+  // Establish origin receipts before destination presentation: neither can overwrite the other.
+  east.consume('e/reader', { kind: 'exact', key: eastMessage.key, remainingQuery: {} });
+  west.consume('w/reader', { kind: 'exact', key: westMessage.key, remainingQuery: {} });
+
+  const exchanges = [];
+  for (const [source, destination, message, mode, first, second] of [
+    [east, west, eastMessage, 'accepted', 'w/reader', 'w/other'],
+    [west, east, westMessage, 'unknown', 'e/reader', 'e/other'],
+  ]) {
+    const [report] = await sendAll(source, message, mode);
+    const destinationKey = report.settlement.completion.data.destinationKey;
+    const admission = [destination.pending(first), destination.pending(second)];
+    const originReceiptsBefore = source.receipts();
+    const output = [];
+    // The sink proves only that this example callback captured the full payload.
+    const presentation = await destination.present(first, destinationKey, payload => { output.push(payload); });
+    const afterPresentation = [destination.pending(first), destination.pending(second)];
+    const presentationReceipts = destination.receipts().filter(ref => ref.item === destinationKey);
+    const originReceiptsAfter = source.receipts();
+    const exact = { kind: 'exact', key: destinationKey, remainingQuery: {} };
+    const unmatched = destination.consume(second, { kind: 'page', query: { via: 'bell' }, limit: 1 });
+    const consumed = destination.consume(second, { kind: 'page', query: { via: 'mention' }, limit: 1 });
+    const repeated = destination.consume(second, exact);
+    const handoffsBeforeReplay = handoffs.length;
+    const [replay] = await sendAll(source, message, mode);
+    exchanges.push({
+      from: source.name, to: destination.name, sourceKey: message.key, destinationKey,
+      dispatch: report, admission, presentation, output, afterPresentation, presentationReceipts,
+      originReceiptsBefore, originReceiptsAfter, unmatched, consumed, repeated, replay,
+      handoffsBeforeReplay, handoffsAfterReplay: handoffs.length,
+    });
+  }
+
+  online = false;
+  const handoffsBeforeOffline = handoffs.length;
+  const offline = [];
+  for (const [domain, author, recipient] of [[east, 'e/author', 'e/reader'], [west, 'w/author', 'w/reader']]) {
+    const messages = [];
+    for (const text of ['oldest', 'middle', 'newest']) {
+      const message = domain.originate(author, [recipient], text);
+      messages.push(message);
+      await sendAll(domain, message); // Local work has no remote destination at all.
+    }
+    const exact = { kind: 'exact', key: messages[1].key, remainingQuery: {} };
+    const middle = domain.consume(recipient, exact);
+    const repeated = domain.consume(recipient, exact);
+    const page = () => domain.consume(recipient, { kind: 'page', query: { via: 'mention' }, limit: 1 });
+    offline.push({ domain: domain.name, keys: messages.map(m => m.key), middle, repeated, pages: [page(), page()] });
+  }
+  return {
+    exchanges, handoffs, offline, handoffsBeforeOffline, handoffsAfterOffline: handoffs.length,
+    attempts: { east: east.attempts(), west: west.attempts() },
+    receipts: { east: east.receipts(), west: west.receipts() },
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  console.log(JSON.stringify(await demonstrateSymmetricDomains(), null, 2));
+}

package/guides/application-facade-delivery-evidence.md

@@ -117,7 +117,7 @@ production line delta -7
 - Root `activity.ts` (271 lines) and `watch.ts` (328 lines) are deleted. Their surviving draft/retry/rendering code is counted in the new CLI helpers (206 + 68 lines); moving renderers is not claimed as semantic deletion.
 - CLI build/join/listener/lifecycle/history/status/catch no longer open storage for admission, before/after facts, projections or sweep coordination. `cli/context.ts` no longer constructs a ledger or discovers bindings during parsing. Application `selected` captures an actor per operation, not a mutable-binding cache.
 - Catch has one leased quiet-wait owner; the old action absolute-idle loop and CLI heartbeat/revision/finish wrappers are removed. Selection carries records/ordinals/header facts in its receipt transaction. Optional nearby presence does not rehydrate the selected page.
-- Express has one preparation/reentry and retry/commit owner. It selects the pending directed feed once, and uses commit-observed count/hold/cap facts rather than rebuilding that feed or issuing a duplicate post-success header query.
+- Express has one preparation/reentry and retry/commit owner. It selects the pending directed feed once, and uses commit-observed count/cap facts rather than rebuilding that feed or issuing a duplicate post-success header query.
 - MCP `publicResult`, stored-activity conversion and status-result policy are deleted. Private producers reuse the facade DTOs instead of maintaining parallel status/unread declarations.
 - Deleted unused `Square.joinWithActivity`, `takeoverWithActivity`, `joinFacts`, `standingCount`; deleted `views.activityPresentation`, `standingCount`, `joinFacts`, `watchPresentation`, and `presentation.renderWatchOutput`. Focused `recoveryObservation` and optional `catchPresence` replace the displaced mixed queries. Supported SDK/session methods remain.
 - `list.ts` no longer parses argv or writes process output; `stream.ts` no longer owns stdout/drain. The CLI owns those adaptations.
@@ -141,7 +141,7 @@ rg exit: 1
 
 ## private action imports
 pattern: from\s*['"][^'"]*square-actions\.js['"]
-square-application.ts:14:import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, retireEndedSessionRoutes, type ExpressCommittedResult } from './square-actions.js';
+square-application.ts:14:import { catchUp, done, endOwnedSession, express, ignore, implicitJoin, join, takeover, listen, listening, retireEndedSessionRoutes, type ExpressCommittedResult } from './square-actions.js';
 rg exit: 0
 
 ## adapter direct private execution
@@ -157,7 +157,7 @@ rg exit: 1
 
 The adapter grep's sole match resolves to **`cli/registry.ts`**, the argv registry, not the root host-binding `registry.ts`. The AST dependency test resolves paths instead of mistaking equal basenames for equal ownership.
 
-`test/architecture-boundary.test.js` passed the transitive adapter/helper traversal and its deliberate hidden-bypass fixtures. It checks all CLI roots, MCP and presentation helpers; permits only named pure bindings (core IDs, immutable held limit, model syntax/errors, identity formatting, search formatting) and closed protocol edges (harness, native hook I/O, MCP immutable `operationEnv`). It rejects private execution hidden through nested helpers, namespace/extra mixed-module bindings, an exceeded native exception and unbounded imports. These are not blanket directory exemptions. Existing storage-boundary/synchronous-capability tests also pass.
+`test/architecture-boundary.test.js` passed the transitive adapter/helper traversal and its deliberate hidden-bypass fixtures. It checks all CLI roots, MCP and presentation helpers; permits only named pure bindings (core IDs, model syntax/errors, identity formatting, search formatting) and closed protocol edges (harness, native hook I/O, MCP immutable `operationEnv`). It rejects private execution hidden through nested helpers, namespace/extra mixed-module bindings, an exceeded native exception and unbounded imports. These are not blanket directory exemptions. Existing storage-boundary/synchronous-capability tests also pass.
 
 ## Closure map for pre-delivery findings
 
@@ -174,9 +174,9 @@ These are deliverer closures, not a reviewer verdict. Rows distinguish behavior
 | Actor discovery cached across binding changes | No actor cache. Reused-app fixture joins Alice, leaves, binds Bob, then expresses as current Bob without reentering Alice or claiming a second name. |
 | Join count derived by racy pre-read arithmetic | `square-actions.join` returns known joined-or-done count from its authoritative join transaction; takeover returns the same fact from its atomic done+join transaction. `joinOwned` uses returned count, never adds to a pre-read. Verified by transaction/source inspection; existing concurrent-owner/join tests remain passing. Standing headers remain distinct. |
 | Express cleanup/enrichment erases commit or calls it unsent | Resource close cannot replace a completed result. Action route/host publication is best effort after commit. Commit observation replaces duplicate post-read. Boundary fixtures prove postcommit host-publication failure returns the activity, projection-clock failure retains landed ID without replay, and selected-row corruption is unknown rather than proven unsent. Operation-cancellation has before-return commit abort coverage. |
-| Catch completion/enrichment erases a committed page | Raw page, ordinals/count/cap/hold/terminal facts travel with receipt selection; completion never rereads them. Only optional `catchPresence` can be unavailable. `performance`: real selection hydrates exactly its page; presence/rendering adds no hydration/reads. Operation-cancellation preserves committed consumption after abort. |
-| Replaced/cancelled waiter consumes later activity or releases new lease | Catch selection transaction checks lease ID. Finally cleanup is non-aborted and ID-fenced. Boundary fixtures prove replacement owns consumption, old waiter returns replaced, cancelled waiter releases lease, later attention stays pending. Hold/expiry and CLI watch-wait heartbeat fixtures pass. |
-| SDK projection roundtrip / leaked observations | SDK express uses `prepareExpression` + `landExpression`, strips observation/waited and retains delivery; SDK catch uses `catchOwned` and returns only established CatchResult. SDK test asserts established fields and avoids application body projections. SDK Square history stays unbounded, Participant recent-ten; parity history fixture proves both, and projection test preserves detached delivered predicate. |
+| Catch completion/enrichment erases a committed page | Raw page, ordinals/count/cap/terminal facts travel with receipt selection; completion never rereads them. Only optional `catchPresence` can be unavailable. `performance`: real selection hydrates exactly its page; presence/rendering adds no hydration/reads. Operation-cancellation preserves committed consumption after abort. |
+| Replaced/cancelled waiter consumes later activity or releases new lease | Catch selection transaction checks lease ID. Finally cleanup is non-aborted and ID-fenced. Boundary fixtures prove replacement owns consumption, old waiter returns replaced, cancelled waiter releases lease, later attention stays pending. Lease expiry and CLI watch-wait heartbeat fixtures pass. |
+| SDK projection roundtrip / leaked observations | The current SDK result shapes are documented in [Square/Participant API](square-api.md); parity tests exercise the real resource and projection tests preserve the detached delivered predicate. |
 | Duplicate contracts, aliases and dead mixed views | Private status/unread producers import/re-export facade contracts; catch observation extends shared expression facts and enriched projection reuses it; required express participant replaces name alias. Retired helper search is empty. Recovery selects only gates/bounded unread summaries, not discarded feed/ordinals/perceptions. |
 | Packed owner orchestration hides effects/count integrity | History, lifecycle branches, maintenance/discovery/recovery, catch conflict and SDK recognize are expanded into readable steps. Remaining one-line SDK delegates are supported simple resource calls, not packed async policy. Inspect implementation diff; all new source is included in count. |
 | Invalid reply / done repair regressions | Typed `invalid_reply` covers malformed and valid-but-absent IDs; typed reach/done reasons stay domain facts, CLI owns glyphs/flags. Express-recovery tests execute printed repaired commands, preserving raw drafts, body candidates and other recipients. Unknown/landed effects offer reconciliation, never replay. |

package/guides/attention-primitive.md

@@ -0,0 +1,32 @@
+# Attention audience resolution
+
+The standalone `@astrosheep/square/attention` subpath computes an audience from
+caller data. It does not open a square, send or consume anything, or grant permission.
+
+```ts
+import { resolveAudience } from '@astrosheep/square/attention';
+
+const audience = resolveAudience({
+  actor: 'east:alice',
+  recipients: ['east:bob', 'west:carol'],
+  mentions: ['west:carol'],
+  incoming: [{ listener: 'east:bob', kind: 'listen' }],
+});
+// [{ recipient: 'west:carol', route: 'mention' },
+//  { recipient: 'east:bob', route: 'attention' }]
+```
+
+The caller supplies eligible recipients in canonical spelling and order, and owns
+their validation and persistence. Identity is exact by default; `sameIdentity` may
+provide a deterministic equivalence relation. The first equivalent recipient gives
+the output spelling. Mentions precede the reply author, followed by listeners in
+recipient order; ignores exclude all three. A `reach: 'bell'` reaches all eligible
+recipients except the actor, bypassing ignores. Equivalent recipients appear once.
+
+The caller decides whether a bell's recipient snapshot is local or global, and when
+that snapshot is authoritative. Square supplies its standing participants and
+incoming relationships at landing, inside its persistence transaction. The result
+is computed attention, separate from delivery and consumption.
+
+For an installed consumer composing this with receive and delivery in two equal,
+independent domains, see the [symmetric domains example](symmetric-domains.md).

package/guides/change-waits.md

@@ -28,9 +28,9 @@ notifications are hints, not activity delivery or consumption receipts.
   returns promptly. An existing active delivery observer will reconsider release/expiry; absent an
   observer, pending work waits for the next normal delivery opportunity. A lease does not create a
   process that was not already running.
-- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. A held catch keeps
+- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. An active catch keeps
   its single lease alive and pauses quiet expiry. Core catch and streams use the same storage change
-  detector. Held express also waits for changes; throttling waits for its eligibility time.
+  detector. Throttling waits for its eligibility time.
 - Deferrals are independent of catch filters, presentation claims, full-delivery seen receipts,
   clipped previews and session-local cancellation. Sharing storage detection does not share session
   delivery state. Cancellation never creates a receipt or removes archive history. A deferral cannot

package/guides/claude-native.md

@@ -5,6 +5,10 @@ contains only `{"modules":["./register.js"]}`. Install with `square install clau
 and load/approve it in a trusted interactive Claude terminal. Installation is
 not evidence of a live receiver.
 
+Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
+`wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
+synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
+
 ## Validated capability
 
 The supported baseline is **macOS Claude Code with the mod actually loaded**;
@@ -24,7 +28,7 @@ An absent/broken endpoint is unavailable; it does not consume Square activity.
 Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
 joins register the native queue for their thread. Claude and OpenCode receivers
 register their native wake addresses only through their loaded integrations. An
-ordinary reconnect or implicit join cannot replace a current native address with a
+ordinary reconnect or reattachment cannot replace a current native address with a
 generic Paseo proposal. Addresses belong to the artifact seat generation, not an
 expiring routes table: explicit receiver withdrawal permits fallback, and a new
 seat generation cannot inherit the previous generation's native registration.
@@ -95,15 +99,20 @@ Initial activation and hot reload use `session.start`. New conversations use
 `classic.SessionStart`: clear reads the new API coordinate; **resume's event
 `session_id` is already the resumed coordinate while `$.session.id()` still reads
 the ending one (observed in 2.1.295)**. The event coordinate is used at that boundary, with
-API cwd/version/socket. Modern `session.end` retires only its pinned `e.sessionId`
-and captured ownership epochs, within the event budget. Late committed joins
+API cwd/version/socket. Modern `session.end` detaches only its pinned `e.sessionId`
+and captured owner/join generations, within the event budget. Late committed joins
 are discovered at the pinned end timestamp. A process crash can omit end.
 
-A resumed conversation restores only memberships whose last lifecycle activity
-is exactly the `done` recorded by its previous confirmed end in the existing
-host ledger. It never takes another owner's participant or re-enters a later
-explicit user `done`. Restoration advances the binding epoch, so callbacks and
-old ends cannot retire that replacement. Unchanged reload preserves epochs.
+Host end is not a participant departure: no `done` lands, and membership, listens,
+read horizon and generation remain intact. Catch ownership, deferrals and wake readiness
+are cleared; the participant appears away and keeps accumulating unread audience without
+proactive delivery. Before arming a receiver, start/resume discovers the exact owner's
+standing seats through `seatsOf(owner)` and restores only detached ones with
+`reattach(name, {owner, wakeAddress?})`. The adapter obtains that owner with
+`harnessOwner({channel: 'claude-code', session, agent?})`. One failed seat or location does not block the
+others. New/forked harness owners restore nothing. Neither a voluntary `done` nor a takeover is
+revived; there is no completed-seat recovery path or timeout that turns away into done.
+See [participant-ownership.md](participant-ownership.md).
 
 ## Body, admission, and presentation
 
@@ -143,7 +152,7 @@ Explicit plugin `turn.abort` and terminal `turn.complete(reason:'aborted')`
 suppress the outstanding local batch without recording seen. Ordinary answer,
 refusal, and error completion are not user cancellation. Separate engine-owned
 family state survives hot reload, containing the abort timestamp and frozen
-membership epochs. Same-epoch host-ledger presence stores a monotonic activity
+membership generations. The artifact stores a generation-scoped monotonic activity
 cutoff; replacement generations cannot inherit the old abort.
 
 Engine state reads are snapshots of one dispatch. Confirmation therefore uses

package/guides/codex-delivery.md

@@ -5,14 +5,22 @@ maintaining a second hook protocol, boundary store or CLI sender. The standalone
 package's [README](../packages/agent-delivery/README.md) describes both its native
 app-server capability and its host-owned hook integration.
 
+Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
+`wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
+synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
+
 ## Square's hook path
 
 `plugins/codex/hooks/hooks.json` invokes `square codex-hook`:
 
 - `SessionStart`, `SessionResume` and `UserPromptSubmit` invalidate the previous
-  Stop observation. `SessionEnd` marks the session ended and ends Square's owned
-  memberships. Later Stop/tool callbacks cannot re-enable queue until a new
-  `SessionStart` or `SessionResume`.
+  Stop observation. `SessionEnd` marks the host session ended and detaches its exact
+  owner's seats without landing `done`, ending membership, dropping listens or resetting
+  the read horizon. Later Stop/tool callbacks cannot re-enable queue until a new
+  `SessionStart` or `SessionResume`. Before enabling delivery, those start paths use
+  `seatsOf(owner)` and `reattach(name, {owner, wakeAddress?})` to restore only detached
+  standing seats of that exact owner; voluntary departures and takeovers are never revived.
+  A new/forked session restores nothing.
 - `PostToolUse` asks Square for current pending activity and returns the existing
   bounded `additionalContext` presentation.
 - `Stop` records queue eligibility and sweeps pending work, but does not itself
@@ -20,7 +28,7 @@ app-server capability and its host-owned hook integration.
 
 The shared handler owns hook framing, lifecycle sequencing, its cancellation
 budget and bounded sweeps. Square supplies activity selection, formatting,
-artifact-owned presentation claims, cancellation, membership cleanup and
+artifact-owned presentation claims, cancellation, attachment cleanup and
 pending-work sweeps. The handler cooperatively awaits Square's pull: the signal
 cancels work before presentation, but a successful presentation's `settleAs`
 finishes independently of request cancellation. Even when that settlement crosses
@@ -28,11 +36,14 @@ the internal budget, the hook waits for it and returns the associated context;
 it never abandons settlement that can mark activity seen without returning text.
 After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
 output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
-an exact Body (`{ channel: 'codex', session }`), not a bare session id. The shared
+an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare session id. The shared
 boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
 defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
 conversation storage and are not proof of current native execution or consumption.
-Square's format5 artifact remains authoritative for seats and delivery evidence.
+Square's format-8 artifact remains authoritative for membership, attachment and delivery evidence.
+Detached members appear away indefinitely and keep accumulating unread audience, but have no
+write or proactive delivery eligibility until same-owner reattachment. Only a host-confirmed
+permanent deletion uses fenced membership-ending cleanup; Codex SessionEnd is not that proof.
 
 `CodexQueueTransport` implements the existing `WakeTransportPort` and uses the public
 `connect({ harness: 'codex', transport: 'cli', sessionId, boundaries, ... })`

package/guides/delivery-primitives.md

@@ -0,0 +1,180 @@
+# Delivery custody primitives
+
+`@astrosheep/square/delivery` provides storage-independent attempt transitions, suppression predicates,
+and four bound effect functions: `dispatchEffect`, `preparePresentation`, `presentPrepared`, and
+`presentPreparedBatch`. It does not open a square, interpret identities, own transactions, or schedule
+retries. Square's actual dispatch, single presentation and boundary batch adapters compose these same
+lifecycles; its SQLite adapter uses the attempt transitions with existing tables. Ownership, membership,
+cancellation and delivery-deferral policy remain in the bound application capability.
+
+## Bind a series inside a transaction
+
+`AttemptRows<D>` is a capability for **one logical item / recipient / authority / purpose series**.
+The caller chooses those coordinates, including arbitrary opaque strings, and binds the store to them.
+No Square name, seat, generation, activity-id codec or composite-key format is required.
+
+- `list()` returns that series newest ordinal first.
+- `byToken(token)` returns only a matching attempt in that series.
+- `insert(attempt)` and `replace(attempt)` write within the caller's current transaction.
+- Replacements preserve purpose, token, ordinal and the caller's external series coordinates.
+
+The caller guarantees isolation against competing claims, token uniqueness within its token lookup
+scope, atomic commit/rollback, and durable storage where needed. Run each operation and its reads and
+writes inside that boundary; an asynchronous read followed later by an unguarded write is not custody.
+Stores must not retain mutable references that allow a caller to change durable rows without a write.
+`D` belongs entirely to the caller. The primitive does not merge, serialize or interpret it.
+
+```ts
+import { claimAttempt, prepareAttempt, settleAttempt, type AttemptRows } from '@astrosheep/square/delivery';
+
+type Payload = { route?: string; nativeToken?: string; ack?: string };
+// Supplied by the application, already scoped and transaction-bound:
+declare const rows: AttemptRows<Payload>;
+
+const claim = claimAttempt(rows, {
+  purpose: 'dispatch', token: 'application-generated-unique-token',
+  at: 1000, leaseMs: 30_000, data: { route: 'opaque endpoint' },
+});
+if (claim.status === 'acquired') {
+  prepareAttempt(rows, { token: claim.token, data: { route: 'opaque endpoint', nativeToken: 'correlation' } });
+}
+// In a later transaction, only after external proof of acceptance:
+settleAttempt(rows, {
+  token: 'application-generated-unique-token', outcome: 'accepted', at: 1100,
+  data: { route: 'opaque endpoint', nativeToken: 'correlation', ack: 'external proof' },
+});
+```
+
+The example shows only transaction-scoped transitions. Commit a successful claim before external I/O;
+settle its exact token in a new transaction after observing the result. The bound effect capability
+below connects those operations without introducing a generic transaction runtime. Authority fencing,
+currentness policy and the meaning of external proof remain the application's responsibility.
+An `accepted` dispatch is not proof of presentation or consumption. Only the responsible presentation
+boundary may assert `presented`; consuming an item is a separate application operation.
+
+## Transitions
+
+An `Attempt<D>` has `purpose: 'dispatch' | 'presentation'`, `token`, zero-based `ordinal`, `outcome`,
+finite `at`, optional `expiresAt`, and `data`.
+
+- `claimAttempt` first returns terminal evidence: dispatch `accepted`/`unknown`, presentation
+  `presented`/`unknown`. Otherwise a live `dispatching` attempt is `busy`; missing expiry is live.
+- At exact expiry or later, an interrupted `dispatching` attempt becomes `unknown`, keeps its original
+  payload, loses expiry, and returns `terminal` with `interrupted: true`. There is no new attempt and
+  **no automatic replay of uncertainty**. Square maps that flag to its interruption diagnostic.
+- With neither terminal nor dispatching evidence, claim inserts `dispatching` at the next ordinal.
+  Failed/released attempts can therefore be retried. Purpose-specific terminal meanings are not
+  inferred from other completion labels.
+- `prepareAttempt` replaces only the data of the exact `dispatching` token. Pass the complete merged
+  payload. It returns false for an absent or no-longer-dispatching token. Callers that already know
+  the payload is unchanged may skip the replacement; core performs no JSON equality checks.
+- `settleAttempt` allows `dispatching` to any defined completion, and late `unknown` to `accepted`.
+  It clears expiry and sets time/outcome/data. `accepted` to `accepted` returns true **without any
+  write or payload/time mutation**. All other transitions return false, including `unknown` to
+  `presented`. Missing or foreign tokens cannot settle another series.
+
+Invalid purpose/completion/token/time, non-positive or unsafe lease durations, non-finite expiry, and
+unsafe next ordinals reject before mutation with `TypeError` or `RangeError`, not `SquareError`.
+The caller supplies valid stored attempts and consistently scoped, ordered rows.
+
+## Suppression without payloads
+
+`presentationBlocksDispatch(attempts, now)` and `automaticDispatchEligible(attempts, now)` accept only
+`purpose`, `outcome`, and optional `expiresAt`; no dummy payload or identity is needed. These predicates
+may see both purposes for the same logical delivery.
+
+Presentation `presented`, `clipped`, `unknown`, or live `dispatching` blocks dispatch. Expired
+presentation dispatching alone does not. Automatic dispatch additionally requires no dispatch
+`accepted`, `unknown`, or `dispatching`; even expired dispatch custody blocks automatic replay.
+These are preselection predicates, not substitutes for a transactional claim or application gates.
+
+
+## Bound effects: one captured capability, four functions
+
+`EffectPort<C>` is bound by the caller to **one captured work item / recipient / authority / purpose**.
+It exposes only:
+
+- `claim(signal?)`: the application's existing atomic claim, returning `{ token, ordinal }` or
+  `undefined` when busy, terminal, stale or deferred. The runner does not claim the attempt twice.
+- `current(signal?)`: pre-effect policy; a rejected check is unverifiable and treated as false.
+- `settle(claim, completion)`: one captured settlement operation, with no request signal. Return true
+  only when it commits, false when not recorded (not necessarily stale), or throw on persistence error.
+
+The application owns tokens, leases, semantic timestamps, authority, proof/diagnostic payloads and
+resource lifetimes. There is no public transaction type, series-key codec or extra persisted lifecycle.
+`Settlement<C>` keeps the selected completion separate from persistence: `recorded`, `not-recorded`,
+or `error` with the original error. Observations are never erased by persistence refusal/error.
+
+### Dispatch
+
+```ts
+import { dispatchEffect, type EffectPort, type DispatchCompletion } from '@astrosheep/square/delivery';
+
+declare const port: EffectPort<DispatchCompletion>; // bound claim/current/settle
+// A sender must check its absolute deadline/cancellation immediately before external mutation.
+const report = await dispatchEffect(port, async context => {
+  if (!await context.beforeSend()) return { outcome: 'not-capable' };
+  if (context.signal?.aborted || Date.now() >= context.deadline) return { outcome: 'unknown' };
+  // Call the application's transport here, passing the remaining budget and captured claim.
+  return { outcome: 'accepted', data: { proof: 'application acknowledgement' } };
+}, { timeoutMs: 5000 });
+```
+
+`dispatchEffect` owns claim → initial currentness → send → settlement. Cancellation suppresses
+pre-effect work. It starts its timer immediately before invoking the sender, not during claim,
+initial policy reads or persistence. Exactly one returned/thrown/timeout decision is frozen before
+settlement. A sender exception defaults to `unknown`, not failed; returned `not-capable` releases
+custody. A denied final gate releases with `not-current / final` under the sender's obligation to
+obey it. No automatic retry occurs.
+
+`beforeSend()` is **policy currentness, not an elapsed-budget gate**. A stalled policy check may
+return true after the outer timeout. The sender must recheck `deadline` and `signal` after that await
+and immediately before I/O; true does not authorize a late send. Outer timeout stays unknown even
+when no I/O is known to have started. Late gates and late promise results cannot rewrite the frozen
+settlement. Separately correlated native proof may still use the attempt transition's permitted late
+unknown → accepted path; the timed-out runner does not reconcile itself.
+
+### Prepared presentation
+
+`preparePresentation({ payload, coverage, port }, { signal? })` acquires custody without running a
+sink. A returned `PreparedPresentation<P>` exposes `payload`, pre-effect `eligible(signal?)`, and
+promise-cached `release()` for abandonment. It is a local one-shot capability, not a durable row and
+not a public success writer.
+
+`presentPrepared(handle, sink, control?)` specializes the batch lifecycle to one item.
+`presentPreparedBatch(handles, render, sink, control?)` takes all supplied custody before its first
+await. It rejects duplicate, foreign or used handles before any effect, checks eligibility, then calls
+synchronous side-effect-free `render(eligible)` returning `{ payload, included }`. Included handles
+must be a unique exact subset of those eligible handles; invalid rendering releases custody and
+rejects without presentation evidence. No included items means no sink call.
+
+Cancellation is checked immediately before the one sink invocation. There is **no presentation timer**
+and no post-effect cancellation, deferral or currentness veto. The runner awaits the sink and marks
+**all included handles** effect-observed before starting asynchronous settlements. Full coverage
+settles `presented`; clipped coverage settles `clipped`. A thrown sink defaults to `unknown`;
+`classifyError` may explicitly return `failed` (classifier failure stays unknown). Unused handles are
+released, all sibling settlements and cleanup drain even on persistence failure, and later cleanup
+cannot overwrite success or uncertainty.
+
+### Mandatory atomic full-consumption settlement
+
+The presentation binding's single `settle` operation must enforce:
+
+| Completion | Atomic persistence |
+| --- | --- |
+| `presented` | Complete the captured attempt **and all captured full-consumption receipts in the same transaction**. Return true only when the combined operation commits. |
+| `clipped` | Complete the attempt; no full-consumption receipt. |
+| `failed`, `unknown`, `released` | Complete the attempt; no success consumption receipt. |
+
+If receipt writing throws, both receipt writes and attempt completion must roll back. Do not reselect
+items or split `complete` and `recordConsumed` into separately awaited callbacks. Captured ownership
+still fences settlement; request cancellation and new delivery deferrals do not. TypeScript cannot
+supply isolation for a caller, so this is a mandatory port contract, tested in Square's real transaction.
+
+Presentation reports distinguish observed sink behavior from durable persistence. A returned sink
+with `not-recorded` or `error` still returned successfully; that alone proves only the supplied sink's
+documented effect, not model consumption or human display. Square explicitly classifies its existing
+rejected sinks as failed and rethrows the original exception after draining. Its single result stays
+`{ presented: true, activity }` only on recorded success, false on ownership refusal; unexpected
+success-settlement errors propagate. Batch returns its original sink value after all settlements,
+with the same error propagation. No schema, storage format or public Square result changes are needed.