@astrosheep/square 0.3.70 → 0.3.72

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

@@ -0,0 +1,200 @@
+# Shared application boundary: delivery evidence
+
+Deliverer evidence, **not independent review or acceptance**. Design and the complete caller/deletion map are in [application-facade-design](application-facade-design.md).
+
+## Candidate coordinates
+
+- Fixed baseline and observed target `main`: `52b58eb9f901f0458302e6120cd83b1079f8ba1c`.
+- Production/test implementation commit: `69b0320031b112f220a80180f607c0deb1beeccd` — `Keep raw drafts independent of a failing application clock` (on top of the owner consolidation `8ecf99cd1e7f4eeb5399f1e9de12f5d901250e9c`).
+- Measured on 2026-10-15 at 09:23 CST (Beijing time). This evidence is a documentation-only descendant of that implementation. The tender receipt identifies the final candidate; rerun the recipe on that candidate. Documentation does not enter this count.
+- No unrelated target changes are included. The seven narrowly amended paths implement captured wake environment, build cancellation propagation, and retired-interface test migration only; no schema/framing/native-protocol changes.
+
+The application factory now returns explicit `{data, projection}` outcomes (except the pull-based stream). This intentionally replaces its old return contract, not the supported SDK resource shapes or MCP wire envelopes. MCP serializes `data`, never the outcome envelope or private projection. SDK handles call shared semantic owners directly, without building application projections.
+
+## Exact committed production count
+
+The Contract recipe was run against the committed implementation, including both new CLI files. Result: **110 production files, 13,934 physical lines, 733,438 bytes; line delta −7**. Bytes increased by 16,488; bytes are reported, not a separate gate. The negative margin is small; no larger reduction is claimed.
+
+Exact recipe (git objects, no checkout edits):
+
+```python
+import subprocess
+from pathlib import PurePosixPath
+
+BASE = '52b58eb9f901f0458302e6120cd83b1079f8ba1c'
+CANDIDATE = 'HEAD'  # Run on the committed integration candidate being reviewed.
+EXCLUDED_DIRS = {
+    'test', 'tests', '__tests__', 'fixture', 'fixtures', '__fixtures__',
+    'script', 'scripts', 'dist', 'build', 'out', 'coverage',
+    'vendor', 'vendors', 'node_modules', 'generated',
+    'docs', 'doc', 'guides', 'skills', '.agents', '.keiyaku', '.git',
+}
+EXCLUDED_NAME_PARTS = ('.test.', '.spec.', '.generated.', '.gen.')
+
+def production(name):
+    path = PurePosixPath(name)
+    return (
+        path.suffix in {'.ts', '.js', '.mjs'}
+        and not any(part in EXCLUDED_DIRS for part in path.parts[:-1])
+        and not any(part in path.name for part in EXCLUDED_NAME_PARTS)
+    )
+
+def snapshot(revision):
+    names = subprocess.check_output([
+        'git', 'ls-tree', '-r', '-z', '--name-only', revision,
+    ]).decode().split('\0')
+    result = {}
+    for name in names:
+        if name and production(name):
+            body = subprocess.check_output(['git', 'show', f'{revision}:{name}'])
+            lines = body.count(b'\n') + int(bool(body) and not body.endswith(b'\n'))
+            result[name] = (lines, len(body))
+    return result
+
+before = snapshot(BASE)
+after = snapshot(CANDIDATE)
+for label, data in [('baseline', before), ('candidate', after)]:
+    print(label, 'files', len(data), 'lines', sum(v[0] for v in data.values()),
+          'bytes', sum(v[1] for v in data.values()))
+for name in sorted(before.keys() | after.keys()):
+    left = before.get(name, (0, 0))
+    right = after.get(name, (0, 0))
+    if left != right:
+        print(f'{right[0] - left[0]:+7d} lines {right[1] - left[1]:+9d} bytes {name}')
+delta = sum(v[0] for v in after.values()) - sum(v[0] for v in before.values())
+print('production line delta', delta)
+if delta >= 0:
+    raise SystemExit('FAIL: production source is not net-negative against the fixed baseline')
+```
+
+Exact stdout (including every changed production path):
+
+```text
+baseline files 111 lines 13941 bytes 716950
+candidate files 110 lines 13934 bytes 733438
+   -271 lines    -13402 bytes activity.ts
+     +3 lines      +167 bytes artifact.ts
+     +0 lines        +5 bytes automatic-session.ts
+     +0 lines        +7 bytes catch-decisions.ts
+     +0 lines        +5 bytes claude-mod.ts
+    +68 lines     +3581 bytes cli/catch-presentation.ts
+    -17 lines      -726 bytes cli/context.ts
+   +206 lines    +12163 bytes cli/express-presentation.ts
+     -1 lines      +114 bytes cli/maintenance-commands.ts
+    +10 lines     +1405 bytes cli/observation-commands.ts
+     -7 lines       -32 bytes cli/program.ts
+   -150 lines     -6582 bytes cli/square-commands.ts
+     +3 lines      +181 bytes codex-queue.ts
+    -22 lines      -273 bytes decisions.ts
+    -21 lines      -511 bytes index.ts
+   -103 lines     -3235 bytes list.ts
+    -29 lines     -1998 bytes mcp.ts
+     +3 lines      +243 bytes model.ts
+     +0 lines       +46 bytes notifications.ts
+     +0 lines        +5 bytes plugins/opencode/index.ts
+    -11 lines      -280 bytes presentation.ts
+    +43 lines     +1940 bytes square-actions.ts
+   +478 lines    +24632 bytes square-application.ts
+   +233 lines    +15186 bytes square-facade.ts
+     +1 lines       +83 bytes square-file-adapter.ts
+     +0 lines       +60 bytes square-storage.ts
+   -136 lines     -6338 bytes square-wiring.ts
+    +23 lines     +1407 bytes stream.ts
+    +18 lines     +2606 bytes views.ts
+     +0 lines       +90 bytes wakes.ts
+   -328 lines    -14061 bytes watch.ts
+production line delta -7
+```
+
+### What actually disappeared
+
+- `square-wiring.ts` (136 lines) is deleted, not a forwarding shim. `Square` and participant resources live with the application owner.
+- 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.
+- 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.
+
+No minification, packed orchestration, bulk whitespace/comment deletion, excluded-path offloading, extension changes, vendor/symlink indirection or unrelated production deletion was used. Explicit DTOs, receipt observations, iterator disposal and cancellation propagation account for additions; the semantic removals above must be judged as well as the small negative total.
+
+## Reference and dependency evidence
+
+Reference searches ran over every tracked production path selected by the recipe's `production` predicate. For each pattern, invocation was `subprocess.run(['rg', '-n', '--', pattern, *paths], text=True, capture_output=True)`. Adapter search restricted paths to `cli/**` and `mcp.ts`; contract search used `square-facade.ts`. Exit 1 below means no matches, not a hidden error.
+
+```text
+## deleted module imports
+pattern: (?:from\s*|import\s*\(\s*)['"][^'"]*(?:square-wiring|/activity|/watch)\.js['"]
+(no matches)
+rg exit: 1
+
+## retired names
+pattern: \b(?:joinWithActivity|takeoverWithActivity|joinFacts|activityPresentation|watchPresentation|renderWatchOutput|cmdListSquares|cmdStreamSquare|publicResult|publicActivity)\b
+(no matches)
+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';
+rg exit: 0
+
+## adapter direct private execution
+pattern: (?:from\s*|import\s*\(\s*)['"][^'"]*(?:square-storage|square-file-adapter|square-actions|views|wakes|notifications|delivery-operations|registry|list|stream)\.js['"]
+cli/program.ts:9:import { executeRegisteredCommand, findCommand } from './registry.js';
+rg exit: 0
+
+## facade derived contracts
+pattern: (?:ReturnType|Awaited)\s*<
+(no matches)
+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.
+
+## Closure map for pre-delivery findings
+
+These are deliverer closures, not a reviewer verdict. Rows distinguish behavior tests from source inspection; passing a nearby test is not claimed to prove a different edge.
+
+| Finding | Implementation and evidence |
+| --- | --- |
+| Status loses configured/discovered viewer | Application `status` resolves optional viewer without joining/claiming; `statusPresentation` settles perception. `application-boundary`: configured/discovered status viewer fixture compares directed bodies and unchanged ownership/artifact; `projections`: viewer perception and exact-spelling rejoin annotations. CLI uses that perception, not audience-law fallback. |
+| Idle completion fabricates null cursor/zero remaining | `catchOwned.complete` uses committed selection data, or reads authoritative cursor/count only when no selection result exists. `application-boundary`: quiet expiry asserts the existing consumed cursor, including after an actual delivered say; `catch-id`: exact acknowledgement is repeatable and incompatible options do not consume. |
+| Stream return hangs behind quiet next | Per-iterator disposal aborts before generator return; observer closes in finally. `application-boundary`: an outstanding quiet pull and `return()` both finish without activity or caller abort. `stream.ts` is pull-based and contains no stdout/drain. |
+| Captured clock became loose Number conversion | `clockFor` retains parseInt + finite coded validation; injected clock wins. `application-boundary`: malformed and blank env clock refusal plus injected override. CLI relative-time decoding uses `app.now`. |
+| Blank participant env stops discovery | Explicit context still validates; blank env falls through to the injected ledger. `application-boundary`: discovery fixture deliberately supplies `SQUARE_PARTICIPANT_NAME: ''` with a ledger outside the env root. History does not select an actor to choose its limit. |
+| Selected/discovered actor lost in errors; generic operation masks express/catch | Named `selected` keeps this attempt's actor and preserves only matching operation detail; inner join enrichment retains canonical committed actor. `application-boundary`: real open failure after explicit/discovered selection proves `express/unsent/Alice`, no mutation. Catch filter/caller distinction has structured refusal assertions. Join actor propagation is also inspected in `selected`/`join`. |
+| 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. |
+| 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 / missing reach / 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 and other recipients; missing reach offers executable `--no-mention`; done ends scoped help. Unknown/landed effects offer reconciliation, never replay. |
+| Failing application clock prevents draft creation | `executeExpression` uses `saveActivityDraft`'s transport-local `Date.now` default, never the failed owner clock. Focused `express-recovery` fixture supplies a throwing clock and landed error plus throwing recovery; exact CRLF raw is already saved at recovery invocation, landed ID remains in history reconciliation, and no replay is offered. |
+| Captured default wake stops at adapter or executable selection | Amended `defaultWakeAdapters(env)` builds `CodexQueueAdapter({env})`; queue executable comes from explicit bin, else supplied env, never later ambient env. Boundary test uses a real isolated fake executable and captured child environment/queue destination after global mutation; injected port wins. No real native delivery. |
+| Force-build ignores cancellation under lock | Amended build/create signal reaches existing lock retries and transaction boundaries; abort checked before public link, cleanup signal-free, no postcommit rejection. Real exclusive-lock fixture cancels, unlocks, and proves unchanged snapshot/no delayed rebuild/no temporary artifact. Separate published-link fixture aborts after commit and still gets the build result. |
+| Removed helper tests / package contract | Obsolete consumers moved to actual application/renderer boundaries, not production stubs. Full suite includes packed ESM root import + TypeScript consumer + unsupported deep-import denial, native import migration, ownership/storage/migration and receipts. |
+
+## Verification on the implemented source
+
+Both declared suites were run serially using repository scripts (sandbox preload), with no live native-session notification or new capacity probe.
+
+| Command | Result | Local raw log |
+| --- | --- | --- |
+| `npm run test:cli-process` | 48 tests, 48 pass, 0 fail, 0 skip; 33,887.057125 ms | `/tmp/facade-process4.log` |
+| `npm test` | 603 tests, 602 pass, 0 fail, 1 skip; 69,523.713167 ms | `/tmp/facade-full5.log` |
+
+The only skipped test is `shipped Claude mod real runtime scheduling and lifecycle`, the existing opt-in real-runtime test. No cancellation, facade, storage or package coverage was skipped. The formal `verified` audit/delivery gate must run or attest both declarations on the final candidate; the journal receipt, not this document, records that attestation.
+
+During integration, stale deleted-helper consumers were migrated to real owner/presentation paths. A captured-env failure and the locked build cancellation gap were fixed under explicit journal amendments. The last failed full run exposed one old core error-text assertion demanding a terminal glyph in domain output; it was updated to the neutral message while keeping requested-name/reason/no-other-name assertions. The full suite passed after that correction. Frozen-source inspection then found the draft timestamp's dependency on a failing owner clock; that dependency was removed and a focused raw-before-recovery/landed-ID regression added. Both suites were rerun successfully as reported above. No failure was hidden by narrowing the final commands.
+
+## Non-claims
+
+- This document does not record independent review or acceptance. The holder/reviewer owns those acts; the deliverer does not self-review.
+- Production line reduction does not imply byte reduction or establish architectural quality by itself.
+- No artifact replacement support, native protocol redesign, schema change, capacity re-probe or live harness validation is claimed.

package/guides/application-facade-design.md

@@ -0,0 +1,95 @@
+# One Square application boundary
+
+**Status: implemented; deliverer verification and measurement are recorded in the delivery evidence. Independent review remains separate.**
+Baseline: `52b58eb9f901f0458302e6120cd83b1079f8ba1c`. Delivery evidence and the exact size recipe live in [application-facade-delivery-evidence](application-facade-delivery-evidence.md).
+
+## Decision in brief
+
+- `square-application.ts` is the sole runtime application owner. It captures the operation context, resolves location/participant, opens and closes resources, applies common defaults (reentry, quiet-wait, default wake transport, history page size), coordinates private actions, and composes projections.
+- `square-facade.ts` stays type-only: it declares the operation contracts, the `{data, projection}` outcome, projection contracts and the SDK resource types. It is the source of every public contract name; the owner re-exports its types.
+- CLI and MCP are transport adapters. Neither opens storage, reads private projections, executes admission/wait policy nor derives domain states from display text.
+- SDK resource handles and the application share the same semantic owners (`prepareExpression`, `landExpression`, `catchOwned`); the handles do not round-trip through the application outcome/projection contract.
+- `square-wiring.ts`, root `activity.ts` and root `watch.ts` are deleted. No forwarding stub, legacy factory or return-shape mode remains.
+- The SDK resource API and its documented defaults are preserved, but they are a resource surface over the same owner functions, not a second implementation.
+
+## The application contract
+
+Root factory (named, single):
+
+```ts
+export function createSquareApplication(context: SquareApplicationContext): SquareApplication;
+```
+
+Context (`cwd`, captured `env`, optional `squarePath`, `participant`, `clock`, `hostLedger`, `wakeTransport`) is snapshotted at creation. Location resolution uses the context and its `SQUARE_LOCATION`; participant selection is explicit context, then captured `SQUARE_PARTICIPANT_NAME`, then one unambiguous current-session binding from the selected/injected ledger. Explicit values win. A history read never discovers, joins or claims a participant just to select a default limit.
+
+Every operation returns one composed outcome:
+
+```ts
+export interface ApplicationOutcome<Data, Projection> {
+  readonly data: Data;       // canonical structured result (the MCP wire fields are a subset)
+  readonly projection: Projection; // extra domain/presentation facts, never terminal copy
+}
+```
+
+`SquareApplication` exposes `now()`, `build`, `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, `participants`, `diagnose`, `migrate`, `discover`, `inbox`, `recovery` and `stream(options, control?)` (an abortable `AsyncIterable`, not a process writer). Read-only operations accept the same `OperationControl` (`signal` + typed progress).
+
+This outcome contract **replaces** the previous factory return values; it is not source-compatible with them, and it does not select semantics or shapes by transport. In-repo consumers migrate together. There is no second factory, no overload that chooses a return shape, and no compatibility shim. The application result contract is recorded in the delivery evidence so it cannot be mistaken for the earlier factory contract.
+
+Array-bearing results use object envelopes (`{activities}`, `{participants}`, `{listening}`), never arrays carrying hidden metadata. `data` never contains an artifact, transaction callback, SQL, lock or lease capability.
+
+`ApplicationFailureDetail` supplements, never contradicts, authoritative `facts.activityUnsent`; the owner classifies express effects as before-attempt, proven-unsent (authoritative admission refusal), landed (committed activity + ID) or unknown (execution failure without refusal/result evidence).
+
+## Committed facts and projection sources
+
+- Express takes its minimal count/header facts from the authoritative commit's own observation. It does not issue a later context read that could erase a successful say, and it does not build a second pending feed that would be discarded. The outcome `data` is the committed activity, `waited` and optional `replyAuthorNotHere`; the projection adds the pre-attempt directed feed, the reentry fact and delivery.
+- Catch settles raw records, say ordinals and count/terminal facts inside the same receipt transaction as selection and marking seen. There is no duplicate post-receipt raw re-read: the application outcome adds the optional focused `catchPresence` read instead, and its unavailability is an explicit fact (`enrichmentUnavailable`).
+
+## SDK resources and preserved defaults
+
+- `Square` and its participant handles live in `square-application.ts`; `index.ts` exports `Square` from there, not from a forwarding shim.
+- SDK handles call the shared semantic owners directly, not through an application outcome/projection roundtrip:
+  - `Participant.express` = `prepareExpression` (reentry/caller resolution) + the shared `landExpression` retry/commit owner. It returns the established `ExpressResult` (including `delivery`) and drops the projection.
+  - `Participant.catch` = the shared `catchOwned` lease/wait/selection/sweep owner. It unwraps the receipt data into `CatchResult` (`activities`, `consumedThrough`, `idleExpired`, `remaining`).
+  - Listener, lifecycle and history methods call their shared owners directly; `snapshot().delivered` stays a detached receipt predicate.
+- Retained supported `Square` methods: `at`, `build`, `inMemory`, `join`, `takeover`, `doneOwnedSession`, `implicitJoin`, `participants`, `snapshot`, `history`, `recognize`, `close`, `endOwnedSession`, `retireEndedSessionRoutes`. The unused `joinWithActivity`, `takeoverWithActivity`, `joinFacts` and `standingCount` glue is deleted.
+- Preserved defaults are explicit at the SDK/application boundary, not a difference in transport defaults:
+  - `Square.history()` keeps its current **unbounded** archive default.
+  - `Participant.history()` keeps its current **recent-ten** default.
+  - Application, CLI and MCP ordinary history default to **ten**, independent of participant selection.
+- In-memory resources stay in-memory: they do not invent file/native wake routes or build a default transport merely to express.
+
+## Module deletion map
+
+| Path | New ownership | Disposition |
+| --- | --- | --- |
+| `square-wiring.ts` | `square-application.ts` | **Deleted.** `Square`/participant handles flattened into the owner; no re-export stub. |
+| `activity.ts` | `app.express` + `cli/express-presentation.ts` | **Deleted.** Caller resolution, implicit join, attempt/uncertainty policy and default-transport construction moved to the owner; only draft/retry/render helpers survive in the CLI. |
+| `watch.ts` | `app.catch` + `cli/catch-presentation.ts` | **Deleted.** Lease/heartbeat/revision loop and terminal policy moved to the owner; one renderer of returned classifications remains. |
+| `square-application.ts` | — | **Owner.** Shared `prepareExpression`/`landExpression`/`catchOwned` semantic owners are the single implementation for application and SDK. No application -> SDK -> application chain; unused SDK glue (`joinWithActivity`, `takeoverWithActivity`, `joinFacts`, `standingCount`) deleted, supported methods retained. |
+| `square-facade.ts` | — | Type-only contracts, `ApplicationOutcome`, projection/SDK contracts, explicit legacy name aliases. |
+| `square-actions.ts` | `square-actions.ts` | Private mutation/ownership fences/delivery integration; called only by the owner. |
+| `decisions.ts`, `catch-decisions.ts`, `wakes.ts` | unchanged files | Private implementations used by the owner. |
+| `views.ts` | unchanged file | Private selected-row reads. `activityPresentation`, `standingCount`, `joinFacts` and `watchPresentation` retired; focused `recoveryObservation` and `catchPresence` added. Public projection types live in the facade. |
+| `list.ts`, `stream.ts` | unchanged files | Internal data-returning discovery/observation; no process writers or argv recovery. |
+| CLI operation paths (build, join, express, catch, history, listen/ignore/listening, hold/resume/done, status, participants, inbox, discover, doctor, migrate) | corresponding `app.*` | Direct storage opens, private projection imports, admission policy and duplicated wait loops removed. |
+| `mcp.ts` | `app.*` | `publicResult`/stored-activity conversion deleted; serialize `outcome.data` only. |
+| `index.ts` | owner + facade | Root `Square` from the owner; all facade contracts via one type-only star plus the supported legacy aliases. |
+| `automatic-session.ts`, `claude-mod.ts`, `plugins/opencode/index.ts` | owner | Mechanical import migration only; native lifecycle protocols unchanged. |
+
+## Architecture edges
+
+- **Adapter boundary.** CLI/MCP reach storage, actions, decisions, views, wakes, list, stream, diagnosis/migration, inbox and notification execution only through `square-application.ts`. Private concern helpers retain their existing typed ports and internal dependencies; they are not callable from adapter execution paths.
+- **Facade.** `square-facade.ts` defines contracts; it must not derive contracts from `ReturnType`/`Awaited<ReturnType>` of private functions, and public activity IDs are formatted/parsed only by the existing core implementation.
+- **CLI (`cli/**`).** Owns argv/stdin, scoped help, shell quoting, sensory rendering/recovery, drafts, stdout/stderr, exit codes, SIGINT -> `AbortSignal` and stream backpressure. It maps returned classifications to copy/exit status, and preserves query argv in continuation commands; it cannot derive admission, commit certainty, terminal states or pagination eligibility from display text. File path display and draft-file I/O are allowed; opening an artifact or resolving ownership is not path formatting.
+- **MCP (`mcp.ts`).** Owns Zod schemas, registration, request-local `as`/`_meta.threadId`/session mapping, signal forwarding, JSON-RPC envelopes and stdio lifecycle. Request environment derivation stays immutable; no shared `process.env` writes and no invented session identity. Its method-name dispatch is a thin argument-to-method mapping, not a second policy dispatcher.
+- **Closed exceptions.** Harness install/uninstall/doctor, scoped help/version, meta commands and native hook input/output keep their existing protocol owners; that exception does not cover join, expression, catch, history, status, participants, build, stream, discovery, inbox, artifact doctor or migrate. Native changes stay limited to the required owner import migration.
+- **Storage/native scope.** SQLite schema/framing, artifact version, migration protocol, receipt model, ownership CAS, notification cancellation suppression and delivery eligibility rules are unchanged. Transactions stay synchronous and typed. The journaled amendment permits only build/create signal propagation through the existing adapter/storage/artifact retries and transactions, and captured-env propagation through default Codex wake construction/executable selection. A committed build is returned despite later cancellation; temporary-file cleanup does not reuse the aborted signal.
+
+## Shared behavior (all four land together)
+
+1. Application express reenters a roster-known departed participant through the same join/ownership path; a never-joined caller is refused. Takeover is never implicit.
+2. Application idle catch is one shared leased quiet wait (hold/heartbeat/replacement/terminal); omitted/zero idle is immediate; exact `id` stays immediate/idempotent and conflicts with idle/filter/limit/replace; a non-replaced current lease returns `already-active`.
+3. The default wake transport resolves lazily from the captured env, selected/injected ledger and clock, cached only for that application's lifetime; an injected transport prevents default construction.
+4. Application, CLI and MCP history default to ten; SDK `Square`/`Participant` defaults above are preserved.
+
+Only these four deliberate common behavior changes, plus the additive explicit idle terminal statuses, alter existing behavior. All other SDK/CLI/MCP contracts, error codes and wire meanings are preserved.

package/guides/change-waits.md

@@ -4,7 +4,7 @@ Square's artifact and host-ledger adapters own change detection. Notifications a
 
 - A process shares a revision reader per canonical artifact and a filesystem watcher per containing directory. Subscribers have independent baselines, deadlines, and cancellation. The final release closes the watcher, reconciliation timer, and any outstanding read.
 - Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions/ledger metadata even when notifications are missing. Missing directories, unsupported watches, and watcher failures retain that fallback; directory replacement is detected during reconciliation. Normal notification latency is not a hard guarantee: a missed hint may wait for reconciliation, plus scheduling and lock contention.
-- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. A missing artifact is a stable observation, not a repeated change: reconciliation remains quiet while it stays absent and detects its return without deleting its session bindings. Strict artifact reads still report absence as an error. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
+- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Changed projections read typed recipient facts and selected bodies, not the whole historical state. A missing artifact is a stable observation, not a repeated change: reconciliation remains quiet while it stays absent and detects its return without deleting its session bindings. Strict artifact reads still report absence as an error. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
 - Each Pi session owns a long-lived pending observer, including when it has no bindings yet. Presence and evidence changes update its subscriptions. There is no repeated thirty-second restart and no per-second binding scan. A failed injection waits for a substantive change; its own failed evidence write does not trigger a retry loop.
 - Blocking CLI catch waits for a revision or its next heartbeat/quiet deadline. A held catch keeps its lease alive and pauses quiet expiry. Core catch, NDJSON stream, and delivery-receipt waits use the same change detector. Held express also waits for changes; throttling still waits for its eligibility time.
 - Catch lease expiry, ledger retention/claim expiry, and cancellation are independent wake conditions. No filesystem write is required for a time-based eligibility change.
@@ -19,10 +19,10 @@ npm test
 npm run test:cli-process
 node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode poll200
 node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode events
-node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode session
-node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode session --active
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
 ```
 
-The benchmark creates disposable synthetic history. poll200 reconstructs the preceding lightweight 200ms polling strategy; events measures revision waits. session includes binding and notification projection, but excludes initial setup. Active runs inject one bell and report committed-write-to-projection latency, not native Pi message landing. They allow up to twenty seconds so saturation is distinguishable from a lost wake. One hundred processes still have one hundred monitors: sharing is process-local, not a claim of cross-process deduplication.
+The benchmark creates disposable synthetic history. poll200 measures 200ms revision polling; events measures revision waits. session includes binding and notification projection, but excludes initial setup. Active session runs compare 1,800 and 18,000 unrelated history rows, inject one bell without push, then catch concurrently. `--no-hints` disables filesystem hints only inside benchmark workers. Runs report committed-write-to-projection latency, not native Pi message landing, and retain the twenty-second discovery deadline as a probe bound rather than an SLA. Three hundred processes still have three hundred monitors: sharing is process-local, not cross-process deduplication. See [row runtime delivery evidence](row-runtime-delivery-evidence.md) for actual completion, hydration, CPU, lock contention and host-ledger costs.
 
 A long-running Pi process must reload/restart its Square extension to use rebuilt code.

package/guides/migration.md

@@ -0,0 +1,77 @@
+# Migrating an existing square to row storage
+
+Square stores authority in one versioned SQLite artifact. Version 1 kept the
+whole history as one JSON snapshot; version 2 keeps typed rows — activities,
+sparse receipts, catch leases, ordered routes and the small configuration
+facts — in one in-place database.
+
+Existing artifacts are **not** converted automatically. A normal read of a
+version 1 artifact refuses with the exact command to run:
+
+```sh
+square --location /path/to/SQUARE.square migrate
+```
+
+That is the only migration command. There is no `--check`, `--backup`,
+`--force`, bulk mode, sidecar, daemon or dual reader, and no operator
+configuration to set.
+
+## What the command does
+
+It converts the artifact **in place**, in **one transaction**:
+
+1. Reads the owned legacy framing before touching anything (application id,
+   format version, `DELETE` journal mode, the exact snapshot schema) and
+   refuses anything that is not an owned version 1 square.
+2. Takes `BEGIN IMMEDIATE`, re-checks that framing under the lock, and decodes
+   and validates the complete snapshot inside the lock.
+3. Creates the row schema and writes the preserved authority: activity indices
+   and their gaps, optional-field presence, raw receipt and lease owner keys,
+   route order and duplicates, string content and finite fractional timestamps.
+4. Rebuilds the derived participant, hold, attention and landed-audience facts
+   through the same single landing transition the runtime uses.
+5. Drops the snapshot table, sets the format version, and commits once.
+
+The revision is preserved; migration never invents or advances it. Nothing is
+published piecemeal, and the file keeps its path, inode and registry identity.
+
+Two shapes are already fine and change nothing:
+
+- an artifact that is already version 2 (reported as already format 2);
+- an artifact converted by another process while this one waited for the lock.
+
+## What it refuses
+
+Nothing is written when the input is not a normally persisted version 1 square:
+a missing file, an unrelated SQLite database, an unsupported format version, a
+different journal mode, an unknown snapshot schema, unreadable snapshot JSON, or
+a route carrying a non-finite number (an exponent-overflow value such as
+`1e999`, which the previous permissive check accepted and an ordinary JSON round
+trip cannot carry) are all refused before any write. The refusal names the
+offending route property.
+
+Journal mode is never rewritten to make a migration possible.
+
+## Before you migrate
+
+- Stop attached runtimes, or upgrade them together with the migration. An
+  in-flight remote delivery is not revoked by migration, and a version 1 writer
+  either commits before the conversion or is refused afterwards — it can never
+  overwrite converted rows.
+- An offline backup is optional and, if you want one, ordinary: copy the file
+  while no writer is attached. The command does not manage backups.
+
+## Crash safety
+
+Before `COMMIT`, SQLite's own journal recovers the complete version 1 artifact;
+after it, the complete version 2 rows are there. A process killed mid-migration
+therefore leaves one or the other, never a partial artifact, and re-running the
+command finishes the job. A busy `COMMIT` retries the same transaction and never
+re-runs the conversion.
+
+## Checking an artifact
+
+`square --location <path> doctor` is read-only. On a legacy artifact it
+recognizes version 1 and prints the migration command; it does not call the
+artifact damaged. On version 2 it validates the rows and recomputes the derived
+indices to compare them against the stored ones.

package/guides/postcommit-simplification-performance.md

@@ -0,0 +1,36 @@
+# Postcommit simplification: 300-process comparison
+
+Measured on the same local host with Node v26.10.0. Baseline runtime: release 0.3.71 (`90478f8`). Candidate runtime: `03237aa`. The benchmark entrypoint repair in `2bfb68e` was used for both; it replaces imports of removed modules with current artifact/open-square exports, without changing the scenario or deadlines.
+
+```sh
+npm run build
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
+```
+
+The command exercises both 1,800 and 18,000 unrelated historical activities. Each of 300 processes observes one bell, recognizes its participant, performs one consuming catch and one empty repeat. These are synthetic Pi bindings without callable native routes. Counts below aggregate all 300 processes; catch latency describes that entire per-process catch phase, not one standalone API call. MB means decimal bytes. Ledger bytes measure instrumented file reads/writes, not physical disk traffic.
+
+| Measurement | Baseline, 1,800 | Candidate, 1,800 | Baseline, 18,000 | Candidate, 18,000 |
+| --- | ---: | ---: | ---: | ---: |
+| Ready / complete | 300 / 300 | 300 / 300 | 300 / 300 | 300 / 300 |
+| Caught per process | 1 | 1 | 1 | 1 |
+| Reconsumed total | 0 | 0 | 0 | 0 |
+| Catch ledger MB | 229.248 | 95.520 | 229.248 | 95.520 |
+| Catch ledger operations | 4,200 | 1,500 | 4,200 | 1,500 |
+| Catch p50 seconds | 18.65 | 5.80 | 22.76 | 5.36 |
+| Catch p95 seconds | 22.57 | 7.11 | 26.62 | 6.85 |
+| Catch SQLite busy errors/retries | 174,082 | 45,555 | 221,701 | 45,028 |
+| Catch CPU seconds, aggregate | 65.01 | 23.31 | 73.50 | 21.65 |
+| Discovery p95 seconds | 1.870 | 1.877 | 1.877 | 1.897 |
+| Five-second idle CPU seconds, aggregate | 3.181 | 3.241 | 3.594 | 3.088 |
+
+These historical SQL/busy counts combined artifact SQL with host-ledger file-lock SQL; “busy errors/retries” counted thrown busy errors, not independently observed retries. They cannot be compared directly with the origin-separated counters now in the benchmark. Rerun both runtimes with the same new script. Its `ledgerSql` reports host-root SQL (including lock databases), separately from artifact SQL. Returned SQL string/blob bytes are not physical I/O or full JSON decode measurements; SQLite's zero instrumented filesystem bytes is a transport change, not a performance gain.
+
+Idle body hydration and ledger bytes remained zero. Each discovery and catch phase hydrated 300 activity bodies. The original 20-second discovery deadline and derived phase guard were unchanged.
+
+The candidate removes a discarded catch-completion sweep and combines postcommit identity publication around one fresh presence observation. Admission remains a separate ownership check. Source changes also consolidate duplicate native connection-option declarations; those type changes do not account for the performance result. Production TypeScript across the three changes is net -57 lines without formatting compression. The benchmark repair is separately net -1 tooling line.
+
+Ledger bytes fell 58.3%, and ledger operation count fell 64.3%. The observed latency improvement is a single before/after local comparison, not an SLA or an isolated causal attribution: other agent work and verification occurred during the broader run, and host load was not controlled. The deterministic operation reduction supports the intended deletion of duplicate work. Idle discovery was not redesigned, and this does not measure callable-route publication or long-lived leased catch optimization.
+
+Each change passed independent review and its declared verification before integration. Root CLI process checks passed all 48 cases; the native adapter package passed 42 cases with its existing Windows-only skip. Full root verification retained its existing skipped case.
+
+Local raw reports: `/tmp/square-round2-baseline-300.json` and `/tmp/square-round2-final-300.json`. These temporary reports are diagnostic artifacts, not repository dependencies. No ledger storage migration or evidence GC change is included.

package/guides/primitive-catch-consolidation.md

@@ -0,0 +1,85 @@
+# Canonical catch selection — delivery evidence
+
+Deliverer evidence only, **not independent review or acceptance**.
+
+## Coordinates and lane attribution
+
+- Contract: `kei/one-canonical-catch-selection-36b2`.
+- Fixed baseline: `501ddc27d5520717f7a9e4d9a5b97406ea72022f`.
+- Implementation: `a2647054f45024ace2562001344285959fbecede`, following `d4df16e0db10d50c01b7ca6646b3c2bdb2871184`.
+- Appointed worktree: `/Users/astrosheep/Developer/square/.keiyaku/wt/revolvingdoor`.
+- Target checked and `git merge main` run at 2026-10-15 10:24 CST: already up to date, main still the fixed baseline. No storage/history/status lane changes are included in this implementation or its reduction claim. Later integration must preserve those lanes and rerun the declared scripts if production changes.
+- This document is a documentation-only descendant of the implementation. The journal tender identifies the final candidate SHA.
+
+## Removed responsibilities and their owners
+
+| 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. |
+| `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. |
+| SDK public-result strip/rebuild and application raw page duplication | `caughtResult` maps to the established `CatchResult` at SDK/application exits. The application alone adds its existing terminal status and necessary projection metadata. `CatchProjection` has no raw `activities` array and no repeated terminalStatus. Optional nearby presence remains separate. |
+| CLI reverse lookup from public ID into raw projection | CLI renders each public activity directly. Existing event rendering accepts `Activity` or `StoredAct` using small ID/reply accessors; no reconstruction of StoredAct or third display-event model. Raw archive/read/actorless inputs still work. |
+
+Directed selection guarantees full visibility: `facts.directed` selects the landed audience relation; its heads require a say with an actor. Exact-ID catch checks both say kind and `directedAt` before selection. `perceiveActivity` settles any directed say to `full`, including listening/reply/bell routes. Therefore the deleted map carried no information and public conversion can attach `perception: 'full'` directly. The case/rejoin audience fixture now verifies the actual perception predicate for selected records, rather than checking the deleted map.
+
+Necessary abstractions remain: typed transaction capabilities, pure selection, owner admission, leased waiting, application outcome and CLI/MCP adapters are distinct. No schema, native protocol, build/resource construction, generic operation receipt, generic dispatcher or optional-field selection bag was added.
+
+## 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.
+- 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.
+
+## Lane-local source reduction
+
+Classification is exactly the production predicate in `guides/application-facade-delivery-evidence.md`: handwritten `.ts/.js/.mjs`, excluding its listed test/generated/script/documentation/vendor directories and test/spec/generated filename markers. All new production files would count; this lane adds none.
+
+Measured from git objects, fixed baseline to the implementation above:
+
+| Snapshot | Production files | Physical lines | Bytes |
+| --- | ---: | ---: | ---: |
+| `501ddc2` | 110 | 13,926 | 732,940 |
+| `a264705` (catch lane only) | 110 | 13,903 | 731,909 |
+| Delta | 0 | **−23** | **−1,031** |
+
+Exact production patch counts:
+
+| Path | Added | Deleted | Net lines | Net bytes |
+| --- | ---: | ---: | ---: | ---: |
+| catch-decisions.ts | 30 | 17 | +13 | +820 |
+| cli/catch-presentation.ts | 4 | 8 | −4 | −160 |
+| presentation.ts | 22 | 13 | +9 | +369 |
+| square-actions.ts | 9 | 33 | −24 | −1,274 |
+| square-application.ts | 30 | 41 | −11 | −497 |
+| square-facade.ts | 4 | 10 | −6 | −289 |
+| **Total** | **99** | **122** | **−23** | **−1,031** |
+
+Reproduce patch counts with `git diff --numstat 501ddc2 a264705 --` followed by those six production paths; reproduce snapshot totals with the referenced evidence document's Python recipe, setting BASE to `501ddc2` and CANDIDATE to `a2647054f45024ace2562001344285959fbecede`. Counts include every production change in this lane, not another lane's removals. This is real responsibility deletion, not a claim based on relocation, packed statements, comment/whitespace removal, excluded-path offloading or unrelated deletion.
+
+## Verification and concrete evidence
+
+All test invocations use repository scripts or the `--import ./test/sandbox-env.js` preload. No live session notification or external runtime probe was used.
+
+| Command / subject | Result | Raw local log |
+| --- | --- | --- |
+| Initial focused eight-file selection/lifecycle/renderer checks | 107 passed, 0 failed | `/tmp/catch-focused-1.log` |
+| Focused page/fence/postcommit/public-render regressions | 39 passed, 0 failed | `/tmp/catch-focused-2.log` |
+| `npm test` on `a264705` | 606 tests, 605 passed, 0 failed, 1 existing opt-in Claude runtime skip; 31,629.839875 ms | `/tmp/catch-full-2.log` |
+| `npm run test:cli-process` on `a264705` | 48 tests, 48 passed, 0 failed, 0 skipped; 22,602.035709 ms | `/tmp/catch-cli-1.log` |
+
+The first full run exposed an unnecessary `sayOrdinals([])` read on empty SDK completion. The existing SDK no-body-projection assertion was left intact; the observer now omits that empty selector call. The full scripts above passed after the fix. No failing test was hidden by narrowing the final commands.
+
+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.
+- `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.
+
+Formal audit and tender are journal acts; their receipts, not this deliverer document, establish Verification and waiting review. No self-review was performed.