@astrosheep/square 0.3.94 → 0.3.96

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

package/guides/primitive-catch-consolidation.md

@@ -20,7 +20,7 @@ Deliverer evidence only, **not independent review or acceptance**.
 
 | Removed | Canonical owner / retained boundary |
 | --- | --- |
-| `CatchDecision`, its unused `changed`, and its all-full perception map | `CatchSelection` contains raw selected activities, participant, cursor/remaining, say ordinals, clock, count/hold/cap/terminal facts. Pure `decideCatch` selects and writes receipts through `SquareWrite`, then captures these facts in that transaction. |
+| `CatchDecision`, its unused `changed`, and its all-full perception map | `CatchSelection` contains raw selected activities, participant, cursor/remaining, say ordinals, clock, count/cap/terminal facts. Pure `decideCatch` selects and writes receipts through `SquareWrite`, then captures these facts in that transaction. |
 | `CatchSelectionResult` combining public activities with a second raw observation | `catchUp` admits the owner, checks the lease ID and invokes `decideCatch` in one receipt transaction, publishes presence best effort, and returns that exact selection. It no longer performs public conversion. |
 | `CatchSelectionObservation` and `WatchPresentation` | `catchOwned` carries the same selection through completion, alongside actual lifecycle stop, waitStarted and replaced facts. No second selected-record wrapper or public page is built inside the lifecycle. |
 | Completion's separate empty-result construction | `observeCatchSelection` captures the same concrete contract using `SquareRead` without marking seen. Only a completion without a committed selection calls it; it does not reopen or rehydrate a committed page. Empty ordinals are `{}` without an unnecessary selector call. |
@@ -34,7 +34,7 @@ Necessary abstractions remain: typed transaction capabilities, pure selection, o
 ## Preserved lifecycle and observation timing
 
 - Lease acquisition retains its own transaction. Lease-ID validation, selection, markSeen, cursor, remaining and selected-page facts share the `catchUp` receipt transaction. A replaced waiter cannot insert a receipt in the gap after its heartbeat.
-- Revision is still captured before evaluation. Heartbeats, hold-paused quiet expiry, replacement and ID-fenced signal-free cleanup remain unchanged. Already-active/replaced/capped/quorum remain distinct from empty-now/stale.
+- Revision is still captured before evaluation. Heartbeats, lease-paused quiet expiry, replacement and ID-fenced signal-free cleanup remain unchanged. Already-active/replaced/capped/quorum remain distinct from empty-now/stale.
 - Successful selection never falls back to a postcommit page/context read. Presence publication, lease release and notification enrichment remain best effort after authoritative consumption. Optional nearby presence can be unavailable without erasing the selected page.
 - Empty terminal/quiet completion reads authoritative cursor and filtered remaining without markSeen. It never invents a null cursor after consumption. Seen holes, continuous cursor, historical catch and notification latest-join semantics remain unchanged.
 - Public conversion now occurs later, at each API exit, rather than in the action/lifecycle. Selection facts still reflect the receipt transaction, not optional presence time. Empty completion's clock is captured when constructing that read-only selection; no selected body is hydrated. No SDK default or wire result changes are intended.
@@ -80,9 +80,9 @@ The first full run exposed an unnecessary `sayOrdinals([])` read on empty SDK co
 
 Boundary evidence:
 
-- `performance`: real raw selection hydrates only its bounded page; remaining uses directedCount; presence/rendering never rehydrates it. A new postcommit mutation fixture changes own count, hold and pending rows after selection and rejects any action-level read: returned ordinals/cursor/remaining/count/hold/clock still match the receipt transaction. A mismatched lease ID returns null without revision/receipt change.
-- `application-boundary`: a real delivered receipt triggers failing host publication and a failing postcommit clock/presence read; catch still returns the consumed public page and its original projection facts, with enrichmentUnavailable and no raw activities projection. A later catch is empty. Existing real leased replacement, cancellation cleanup, hold/resume and quiet expiry fixtures pass, including the preserved consumed cursor after an actual say.
-- `presentation`: public/raw rendering parity checks multiline body, activity ID, reply ID, mention metadata, done and listen; presence omits bodies. Raw read remains empty and actorless hold remains renderable.
+- `performance`: real raw selection hydrates only its bounded page; remaining uses directedCount; presence/rendering never rehydrates it. A new postcommit mutation fixture changes own count and pending rows after selection and rejects any action-level read: returned ordinals/cursor/remaining/count/clock still match the receipt transaction. A mismatched lease ID returns null without revision/receipt change.
+- `application-boundary`: a real delivered receipt triggers failing host publication and a failing postcommit clock/presence read; catch still returns the consumed public page and its original projection facts, with enrichmentUnavailable and no raw activities projection. A later catch is empty. Existing real leased replacement, cancellation cleanup and quiet expiry fixtures pass, including the preserved consumed cursor after an actual say.
+- `presentation`: public/raw rendering parity checks multiline body, activity ID, reply ID, mention metadata, done and listen; presence omits bodies. Raw read remains empty.
 - `row-domain`, `core`, `delivery`, `perception-projection`: filter-before-limit, exact repeat, original receipt timestamp, gap/cursor and latest-join differences remain tested. Obsolete changed assertions were replaced by actual receipts, or removed only where the immediately adjacent unchanged receiptAssignments equality already proves no write. No boundary assertion was weakened to preserve a retired mechanism.
 - `operation-cancellation`, `square-facade`: commit survives response abort; SDK returns only its established CatchResult, no application body projections. CLI process coverage retains filtered continuation, mention/body visibility, stable IDs and lifecycle feedback. MCP continues serializing data only.
 - Production reference search for `CatchDecision|CatchSelectionResult|CatchSelectionObservation|WatchPresentation|exposeCaught` returned no matches (excluding dist/node_modules); `git diff --check` passed. CLI has no `projection.activities.find` or raw reconstruction.

package/guides/primitive-history-consolidation.md

@@ -57,9 +57,9 @@ Entry still uses the actual selector with explicit `['say', 'done']` kinds and i
 ## Necessary distinctions retained
 
 - **Defaults:** SDK `Square.history` is unbounded. SDK `Participant.history` defaults to ten. Application/CLI/MCP default to ten, cap explicit limits at 100, and reject an implicit merged context larger than 100 with the original `operation.historyBounds` detail. Supplying a limit bounds that context. Application's stricter grep/fixed, non-empty search, finite since and safe nonnegative context validation is unchanged; SDK search remains intentionally looser.
-- **Three subsets:** raw selected records can contain reads and historical actorless lifecycle records; public `Activity` omits read/actorless records but retains listen/ignore; ordinary terminal visibility contains join/say/done/hold/resume. Hidden listener events still occupy page positions. Since/context windows still select raw bookkeeping; ordinary history excludes reads. Field formatting uses raw records; CLI JSON now serializes the public SDK result and omits bookkeeping records. No third event model was introduced.
+- **Three subsets:** raw selected records can contain reads and historical actorless lifecycle records; public `Activity` omits read/actorless records but retains listen/ignore; ordinary terminal visibility contains join/say/done. Hidden listener events still occupy page positions. Since/context windows still select raw bookkeeping; ordinary history excludes reads. Field formatting uses raw records; CLI JSON now serializes the public SDK result and omits bookkeeping records. No third event model was introduced.
 - **Paging:** cursor bounds remain exclusive stable IDs, sparse context counts existing positions, and from/mention/search intersect before applying the limit. An after cursor selects the oldest eligible page; otherwise the newest eligible page is selected. `order` only reverses the selected page. Continuation uses the terminal-visible subset and the same filtered candidate universe; a listener-only page has no invented terminal anchor. Audience paging continues through empty intersections.
-- **Projection:** ordinals, presence anchors, standing/held facts and final data come from the same read callback. The projection clock is now sampled within that callback instead of after the intermediate async presentation completed. It is still an observation-only operation with no receipt, presence or lease writes. Overflow is rejected before unnecessary anchor/ordinal enrichment.
+- **Projection:** ordinals, presence anchors, roster facts and final data come from the same read callback. The projection clock is now sampled within that callback instead of after the intermediate async presentation completed. It is still an observation-only operation with no receipt, presence or lease writes. Overflow is rejected before unnecessary anchor/ordinal enrichment.
 - CLI and MCP require no policy changes: CLI continues formatting raw/terminal records and owner-produced continuation; MCP serializes public data only. Catch's renderer-accessor changes are owned by its separate lane.
 
 ## Verification

package/guides/primitive-status-consolidation.md

@@ -63,14 +63,14 @@ For completeness, **whole integrated source** against fixed `501ddc2` is 110 fil
 
 Full versus filtered roster is a real distinction: status data omits never-joined historical actor names, while participants data retains them. `knownParticipantCount` separately preserves the complete-roster continuation count; it is not `status.data.participants.length` or the standing count.
 
-The amended guidance's reachable-latest clause is applied: the selector remains newest `say`/`done`. Both require an actor in valid storage, whereas actorless `hold`/`resume` and `read` are not selected. Therefore status has no reachable raw/public latest distinction. The conversion guard remains conservative, but no hypothetical duplicate projection is retained. History and other operations' genuine raw/public distinctions are untouched by this lane.
+The amended guidance's reachable-latest clause is applied: the selector remains newest `say`/`done`. Both require an actor in valid storage, whereas `read` is not selected. Therefore status has no reachable raw/public latest distinction. The conversion guard remains conservative, but no hypothetical duplicate projection is retained. History and other operations' genuine raw/public distinctions are untouched by this lane.
 
 ## Behavior and timing evidence
 
-- `test/projections.test.js`: exact canonical status data, full versus filtered roster, absent duplicate projections, hold/cap/throttle fields, and read/actorless-hold exclusion from latest selection. Existing viewer perception, exact-spelling rejoin and bounded hydration assertions remain. Shared watching/recent/lingering policy remains read-only.
+- `test/projections.test.js`: exact canonical status data, full versus filtered roster, absent duplicate projections, cap/throttle fields, and read exclusion from latest selection. Existing viewer perception, exact-spelling rejoin and bounded hydration assertions remain. Shared watching/recent/lingering policy remains read-only.
 - `test/application-boundary.test.js`: configured named, discovered (including blank environment name), explicit blank, explicit override and ambient viewer; body perception and attention names; unchanged artifact state and ownership/presence ledger after status.
 - `test/core.test.js`: status and participants continue sharing actual authored and receipt times, including a fresh rejoin and watcher.
-- `test/process/square-cli-render.test.js`: the compact ten-person preview now includes a valid historical never-joined actor in the artifact. Status still hides that actor but its executable continuation uses the full count 14 rather than filtered count 13; participants prints the complete roster. Existing hold duration, exact rejoin, attention, clipping/public-id continuation and presence feedback remain covered.
+- `test/process/square-cli-render.test.js`: the compact ten-person preview now includes a valid historical never-joined actor in the artifact. Status still hides that actor but its executable continuation uses the full count 14 rather than filtered count 13; participants prints the complete roster. Existing exact rejoin, attention, clipping/public-id continuation and presence feedback remain covered.
 
 No observation timing change is intended: optional viewer discovery still precedes status's resource read; the clock is sampled once inside the transaction, and all domain data, classification, perception and rendering annotations are assembled in that read. Queries perform no I/O or mutations themselves. SDK participant/snapshot shapes and MCP serialization of data remain unchanged. No join/claim is introduced.
 

package/guides/primitive-storage-consolidation.md

@@ -25,7 +25,7 @@ Deliverer evidence, not independent review or acceptance.
 | `square-state.ts` legacy SQLite framing | `square-sqlite.ts`: read-only owned-v1 recognition beside row framing/codecs |
 | `square-state.ts` legacy payload validation | `square-migration.ts`: explicit legacy envelope, order/gap and assigned-reference checks, permissive finite route data and path-specific nonfinite rejection |
 | General-model snapshot/runtime DTOs | `square-sqlite.ts`: explicit import/export DTOs, not runtime transaction state |
-| Dead `StoredActHead`, `HoldState`, `findParticipantName`, empty `ReceiverRoute` alias | Deleted; interchange routes use the existing `WakeRoute` type |
+| Dead `StoredActHead`, `findParticipantName`, empty `ReceiverRoute` alias | Deleted; interchange routes use the existing `WakeRoute` type |
 
 There are no forwarding stubs. The renamed build preparation is the actual implementation, not an alias. File SDK build, synchronous memory build and application build share it. Application build returns the normalized configuration from canonical creation rather than reconstructing it. Ordinary storage/resource imports perform no guide reads; the first build reads only its selected guides and caches them.
 

package/guides/receive-primitive.md

@@ -0,0 +1,90 @@
+# Transaction-local receive and consumption
+
+`@astrosheep/square/receive` admits items and their settled audience, selects
+received heads without consumption, and records sparse first-write-wins receipts.
+It has no runtime dependencies, Square membership, SQLite or transport requirement.
+For computing an audience before admission, see [attention](attention-primitive.md).
+
+```ts
+import { receive, consumeReceived } from '@astrosheep/square/receive';
+
+// Both callbacks belong to your storage implementation, not this package.
+store.transaction(tx => receive(tx, {
+  item: { key: 'opaque:west/7?hello', data: { text: 'Hello' } },
+  audience: [{ recipient: 'east:bob', via: 'link' }],
+}));
+const page = store.transaction(tx => consumeReceived(tx, 'east:bob', {
+  kind: 'page', query: { sender: 'west:alice' }, limit: 10,
+}, Date.now()));
+// { items: [{ key, data, via }], newlyConsumed, remaining }
+```
+
+`store` and `tx` above are caller-owned storage, not exports. Implement
+`ReceiveRead<K,D,V,Q>` / `ReceiveWrite<K,D,V,Q>` structurally; each function only
+requires the `Pick` of methods it uses. `K extends string | number` is an opaque
+equality identity: no ordering, parsing, numeric sequence, or `act/N` convention
+is imposed. The storage defines head order and query semantics. `D`, route `V`,
+and query `Q` are caller data. Recipients are strings; the caller owns canonical
+identity and eligibility. Item and address keys must be unique in storage.
+
+## Capabilities and ownership
+
+- `insertItem({key,data})` and `insertAddress(key,{recipient,via},order)` admit an
+  item and its audience in supplied order. `receive` permits an empty audience.
+  Supply unique recipient keys; duplicate items/addresses must throw, never
+  overwrite or silently deduplicate. Roll back the whole admission on failure.
+- `heads(recipient,query,{unconsumed,limit})` applies the query and consumption
+  predicate **before** limiting, returning ordered `{key,via}` heads.
+  `addressed(recipient,key)` ignores receipt state, but checks addressedness.
+- `load(keys)` hydrates the selected keys once as a `ReadonlyMap<K,D>`.
+  Missing keys are errors; an explicitly stored `undefined` value is not missing.
+  `count(recipient,query,unconsumed)` counts the same selection without a limit.
+- `receipt({recipient,item})` reads `{at}` or `undefined`.
+  `insertReceipt(ref,at)` returns true only for a new coordinate and preserves the
+  first timestamp. The identity is `(recipient,item)`, not a cursor or generation.
+
+All functions are synchronous. Supply capabilities from **one isolated,
+caller-owned transaction**, with storage uniqueness constraints and rollback on
+any thrown error, including failures during hydration, receipt insertion or the
+final count. No capability or selected page should escape that transaction for
+later consumption. The leaf does not start, commit, retry or emulate transactions.
+Its atomicity depends on this caller obligation.
+
+## Selection and receipts
+
+`selectReceivedHeads(tx,recipient,selection)` never hydrates or writes. A page is
+`{kind:'page',query,limit}` and always selects unconsumed heads; `limit` must be a
+positive safe integer, with no policy maximum. An exact selection is
+`{kind:'exact',key,remainingQuery}` and remains repeatable after consumption.
+
+`consumeReceived` selects inside the supplied transaction, hydrates all selected
+keys before any receipt insertion, preserves head order, records the captured
+coordinates and counts matching unconsumed items. Exact remaining uses
+`remainingQuery`; page remaining uses `query`. Repeating exact consumption returns
+the same item with `newlyConsumed: 0`, not a second receipt.
+
+`recordConsumed(tx,refs,at)` only needs `insertReceipt`. It records captured
+coordinates without reselecting, loading or checking eligibility. Duplicate refs
+are idempotent through storage and cannot change the first timestamp. Timestamps
+must be finite numbers (negative/fractional timestamps are allowed). Nonnumber
+limits/timestamps throw `TypeError`; out-of-range numbers throw `RangeError`.
+`ReceiveError` exposes `code: 'not_addressed' | 'missing_item'` and the opaque `key`.
+Storage errors propagate unchanged; they still require caller rollback.
+
+This is not a remote message protocol, replay envelope, permission system,
+ordering service, billing ledger or exactly-once external effect guarantee.
+Delivery attempts and presentation are separate from consumption. The
+[symmetric domains example](symmetric-domains.md) composes all three public
+primitive entrypoints without constructing Square.
+
+## Square composition
+
+Square uses these functions for production landing, catch and `markSeen` against
+its existing activity, audience and receipt tables. Numeric activity indexes stay
+internal keys; the primitive does not know Square IDs. Square retains validation,
+limits, filtering, perception, ownership, leases, hints and error mapping. The
+empty-catch read probe does not hydrate or acquire a writer; a nonempty probe is
+reselected inside the writer. Ordinary catch sees historical receipt holes,
+including before rejoin; proactive pending still starts after the latest join.
+The artifact schema/format and receipt identity are unchanged. See the
+[Square API](square-api.md) for product operations.

package/guides/row-runtime-delivery-evidence.md

@@ -10,7 +10,7 @@ Candidate implementation: `833d6f15c9071767eb49a9562a4c42a93c6f4000` plus post-r
 | Whole-history fold on normal operations; replay delivery/perception closures | `square-domain.ts::deriveLanding` maintains participant, attention and ordered audience indices once at landing; `runtime.ts` computes cursor/presence/terminal from narrow domain facts. |
 | `FromState`/delta bridges and old core append/observation update helpers | Removed. `SquareWrite.land/markSeen/putLease/removeLease/replaceRoutes` are the finite domain mutations. Memory uses the same SQLite driver in `:memory:`, not a second selector/policy implementation. |
 | Renderer `.state` inputs and replay-based ordinal/perception lookup | `views.ts`, `perception-projection.ts` and presentation operations settle selected bodies, ordinals, counts and perceptions inside the transaction; renderers receive detached values. |
-| Join/status/hold/resume/done snapshot loads for counts | `joinFacts`, standing counts, roster/status aggregates and header reads. Public SDK snapshot is no longer used by these production callers. |
+| Join/status/done snapshot loads for counts | `joinFacts`, standing counts, roster/status aggregates and header reads. Public SDK snapshot is no longer used by these production callers. |
 | Global whole-history notification/wake enumeration | Bodyless `pendingAudience` groups with a captured activity upper bound and recipient join coordinates; receivers use their own `directed` relation. Scans advance past withheld groups and do not restart on unrelated writes. |
 | Whole-history native/Claude currentness and cancellation | Exact pending facts, ordered routes, lease and captured host fences; cancellation selects activity heads by descending coordinate and tests timestamp. Host/network work stays outside artifact transactions. |
 | Preliminary full load before file-backed open/probe/wait | Validated header/schema boundary, revision-only observer; selected row validation on access. Full doctor is explicit. |