@astrosheep/square 0.3.94 → 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,8 +174,8 @@ 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. |
+| 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. |

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/codex-delivery.md

@@ -40,7 +40,7 @@ an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare se
 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 format-7 artifact remains authoritative for membership, attachment 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.

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.

package/guides/mcp.md

@@ -4,7 +4,7 @@ Square provides a stdio MCP server through `square mcp-server`.
 
 Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact opaque owner; zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
 
-The server exposes `join`, `express`, `catch`, `history`, `attention`, `hold`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `hold` lowers the hand with `release: true`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All eight tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
+The server exposes `join`, `express`, `catch`, `history`, `attention`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All seven tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
 
 Claude's bundled plugin configures this server automatically. Its mod supplies live session/cwd/subagent attribution through an out-of-band tool-use-ID association, not AI-visible arguments; see [Claude call identity](claude-native.md#mcp-tools-and-call-identity). The bundled endpoint requires that association rather than falling back to its startup environment.
 

package/guides/migration.md

@@ -4,7 +4,8 @@ Square stores its authority in one versioned SQLite artifact. Format 1 kept a sn
 format 2 introduced typed facts; format 3 added `unlisten`; format 4 moved participant custody
 and delivery evidence into the artifact; format 5 added independent delivery deferrals.
 **Format 6 separates participant membership from host attachment; format 7 replaces harness Body
-coordinates with opaque owners.** Existing artifacts are never converted implicitly.
+coordinates with opaque owners; format 8 removes Square hold/resume activities and held state.**
+Existing artifacts are never converted implicitly.
 
 Stop all processes using the artifact, make an offline backup, then run:
 
@@ -13,12 +14,16 @@ square --location /path/to/SQUARE.square migrate
 square --location /path/to/SQUARE.square doctor
 ```
 
-The command handles supported formats 2–6 in place and publishes only final format 7, in one
+The command handles supported formats 2–7 in place and publishes only final format 8, in one
 transaction. It does not make a backup, stop processes, install a runtime or update another
 artifact. For formats 2/3, also freeze and back up the legacy HostLedger used for owner/evidence
 import. A legacy ledger needing its own conversion must be prepared separately with its old
 runtime's offline tooling. Snapshot format 1 is not accepted by this conversion.
 
+Format 7 to 8 deletes hold/resume activities and rows keyed to them, clears replies that point to
+deleted activities, and preserves every surviving activity index. Gaps remain legal; `lastActIndex`
+is the greatest surviving index and `nextActIndex` never reuses a deleted index.
+
 ## Membership and attachment after conversion
 
 Membership owns a participant's join/done history, read horizon and outgoing listens. Attachment
@@ -101,9 +106,10 @@ not import. Evidence without current or verified completed ownership is skipped
 read-only legacy ledger remains available for offline diagnosis; an absent ledger permits route-
 derived custody, but an unreadable or unsupported ledger refuses before changing the square.
 
-One transaction imports verified authority/evidence, adds deferral and attachment support and
-publishes format 7. Existing conversation and membership facts are preserved; no intermediate
-format is published. Legacy catch ownership is generation-bound only for exact standing owner
+One transaction imports verified authority/evidence, adds deferral and attachment support, applies
+the format-7-to-8 deletion, and publishes format 8. Existing conversation and membership facts are
+preserved apart from the deleted hold/resume rows and cleared replies; no intermediate format is
+published. Legacy catch ownership is generation-bound only for exact standing owner
 spellings; otherwise it stays unbound. Legacy routes are consumed only during migration and are
 not a live authority source. The new delivery revision starts at zero. Format 2 first adds support
 for `unlisten`, then follows the same conversion.
@@ -142,7 +148,7 @@ rows are ignored. Rejoin with the exact migrated owner to republish discovery (o
 harness reconnect). This preserves generation, listens and unread activity; do not use takeover
 merely to rebuild the index.
 
-Upgrade all attached runtimes before reopening format 7; older runtimes must not be mixed with it.
+Upgrade all attached runtimes before reopening format 8; older runtimes must not be mixed with it.
 Updating a package does not migrate an artifact, and migration does not install upgraded runtimes.
 After conversion, run read-only `doctor` before restarting clients. To roll back a committed
 conversion, stop all clients and restore the offline backup with its compatible older runtime;

package/guides/participant-ownership.md

@@ -53,7 +53,7 @@ for resource lifetimes and adapter selection.
   failed reattachment does not block the others. A new or forked session has a different owner and
   restores nothing. Hosts never infer restoration from a historical departure.
 - Participant mutations require both the captured generation and an attached current seat.
-  Detach suspends existing handles; they cannot express, catch, listen, hold, leave or change
+  Detach suspends existing handles; they cannot express, catch, listen, leave or change
   deferrals until reattachment. Rejoin/takeover fences old handles permanently, even if the same
   owner later reacquires the name. Host cleanup checks owner and generation inside its transaction;
   stale, foreign, done or already-detached detach changes nothing. Host `cancelDeliveries` also

package/guides/pi-tools.md

@@ -1,6 +1,6 @@
 # Pi native tools
 
-The existing Square Pi extension registers `square_join`, `square_express`, `square_catch`, `square_history`, `square_attention`, `square_hold`, `square_done`, and `square_status`. `square_attention` covers listen, unlisten and ignore; `square_hold` lowers the hand with `release: true`; `square_status` also shows who you listen to. No additional MCP server or subprocess is needed.
+The existing Square Pi extension registers `square_join`, `square_express`, `square_catch`, `square_history`, `square_attention`, `square_done`, and `square_status`. `square_attention` covers listen, unlisten and ignore; `square_status` also shows who you listen to. No additional MCP server or subprocess is needed.
 
 Tools use the `square` namespace with codemode exposure. Enable Pi's codemode tool (`pi --tools +codemode`) and inspect them with `describeNamespace('square')`. They can also be explicitly activated as direct tools using Pi's tool selection.
 
@@ -22,7 +22,7 @@ overview if there are zero or multiple. The extension encodes the live Pi sessio
 `harnessOwner({channel: 'pi', session})`, never a model-provided session id, without mutating
 the process environment.
 
-All eight tools return the CLI's human-readable text, without an `outputSchema` or
+All seven tools return the CLI's human-readable text, without an `outputSchema` or
 `structuredContent`. In Pi codemode, a successful call resolves to a `string`:
 use `text(result)`, not `text(result.text)`. Failures are marked as failed tool results;
 codemode rejects with the readable error and recovery commands rather than returning