@astrosheep/square 0.3.86 → 0.3.87

package/guides/migration.md

@@ -1,75 +1,115 @@
 # Migrating an existing square
 
-Square stores authority in one versioned SQLite artifact. Version 1 kept the
-whole history as one JSON snapshot. Version 2 introduced typed rows. Current
-format 3 adds the `unlisten` history event without changing the other tables.
+Square stores its authority in one versioned SQLite artifact. Format 1 kept the
+history as one JSON snapshot; format 2 introduced typed rows; format 3 added the
+`unlisten` activity; format 4 adds artifact-owned participant seats and delivery
+evidence. Existing artifacts are never converted implicitly.
 
-Existing artifacts are **not** converted automatically. Ordinary reads and
-writes refuse versions 1 and 2 with an offline-migration requirement. The CLI
-adds the concrete recovery command; native tools retain the description:
+Use the explicit command while all processes using the artifact are stopped:
 
 ```sh
 square --location /path/to/SQUARE.square migrate
 ```
 
-This is the only artifact migration command. There is no `--check`, `--backup`,
-`--force`, bulk mode, sidecar, daemon or dual reader. The host ledger is a
-separate resource; unlisten does not change its format.
-
-## What the command does
-
-Both supported conversions happen **in place**, in **one transaction**:
-
-1. Read the owned framing before any persistent pragma or DDL: application id,
-   source format, `DELETE` journal mode, and exact known schema.
-2. Take `BEGIN IMMEDIATE` and re-check that framing under the lock.
-3. Convert the source using its explicit path:
-   - **Version 1:** decode and validate the complete snapshot, create current
-     rows, and preserve activity indices/gaps, optional fields, raw receipt and
-     lease owners, ordered routes, strings and finite fractional timestamps.
-     Rebuild derived participant, hold, attention and landed-audience facts
-     with the runtime's shared landing transition, then drop the snapshot.
-   - **Version 2:** rebuild only `activities` and its indexes to accept
-     `unlisten`, copying every existing activity row unchanged. All other
-     tables, including attention, landed audience, receipts, leases, routes
-     and configuration, remain untouched. No history is reinterpreted.
-4. Set format 3 and commit once.
-
-Revision and assigned activity indices are preserved. Migration adds no domain
-activity. Nothing is published piecemeal, and path, inode and registry identity
-remain unchanged. A format-3 artifact is reported as already current without
-writing, including when another migrator finished while this one waited.
-
-## What it refuses
-
-Missing files, unrelated databases, unsupported versions, different journal
-modes, unknown schemas and malformed headers are refused without a write.
-Version-1 snapshot JSON and activity vocabulary must be valid for that source
-format. Non-finite numbers anywhere in a legacy route, including nested extra
-properties, are refused with the offending property named; they are not
-silently coerced to null. Journal mode is never rewritten to make conversion
-possible, and migration is not a corruption-repair command.
-
-## Before you migrate
-
-Stop every session and service using that artifact. Make an offline backup, or
-use SQLite's backup facilities rather than copying a live database. The command
-does not manage backups, stop processes, revoke in-flight remote deliveries,
-or update installed runtimes.
-
-Upgrade all attached runtimes before reopening the migrated artifact. Both
-version-1 and version-2 runtimes refuse format 3; do not mix old and new
-processes against the converted file. An older writer either commits before
-conversion or meets the new version gate afterwards.
-
-## Crash safety and checking
-
-Before `COMMIT`, SQLite's journal recovers the complete source version; after
-it, complete format-3 rows are present. A failure or process death cannot leave
-a partial conversion. A busy `COMMIT` retries the same transaction, never the
-copy or domain callback.
-
-`square --location <path> doctor` is read-only. On versions 1 and 2 it prints
-the migration requirement without calling the artifact damaged. On current
-format 3 it validates rows and recomputes derived indices for comparison.
-Run it after migration and before restarting upgraded clients.
+The command handles the supported older formats in place. It does not create a
+backup, stop processes, install a runtime, or update another artifact. A legacy
+HostLedger that needs its own format conversion must be prepared separately with
+the old runtime's offline tooling.
+
+## Format 3 preflight and conversion
+
+Before writing, migration validates the exact format-3 schema, header, and legacy
+rows read-only. The configured legacy HostLedger must be frozen along with the
+artifact. Its latest owner row for each participant at this artifact is selected
+by source `(effectiveAt, seq)` only: no wall clock, retention, expiry, or ownership
+history reconstruction is involved.
+
+- A standing seat requires an agreeing owner Body (`channel`, `session`, optional
+  `agent`), route Body, and verified establishing last join. Routes alone never
+  establish ownership. An absent agent means the top-level body; a known agent is
+  preserved and compared exactly. Repeated matching route registrations are
+  acceptable; a wake address is carried forward only when they agree on it.
+- Missing owners or routes, conflicting or shared body mappings, and unverifiable
+  joins refuse before publication. Resolve these in the old runtime before
+  retrying; migration does not guess or synthesize authority.
+- Standing wake/presentation evidence maps only to that verified current join
+  generation and an existing directed say after the join. Evidence older than the
+  current generation, conflicting owner/session mappings, duplicate claim tokens,
+  or ambiguous attempt numbers refuse. A single record without an attempt number
+  receives attempt 0; missing numbers among multiple attempts are ambiguous.
+- Done participants get **no seat or completed coordinate**. Only native wake
+  correlation directly attributable to their verified latest join and a directed
+  activity between that join and done is retained for retired-token recognition.
+  It does not authorize admission, completion, or presentation. Ambiguous critical
+  native mappings refuse rather than disappear. Migrated Claude native addresses
+  include `sessionId` on both seats and evidence routes.
+
+This is deliberately a narrow, lossy conversion, not a general history importer.
+Conversation facts (activity IDs, bodies and audience), receipts and source revision
+meaning survive. Replay-critical delivery coordinates, outcomes and native
+correlation survive direct mappings. Completed non-native evidence and noncritical
+metadata—including old presence history, epochs, diagnostic messages, native
+observation histories and arbitrary legacy fields—are not imported. The legacy
+ledger is read-only and remains untouched, so it is still available for offline
+diagnostics. An absent ledger cannot establish standing ownership; an unreadable
+or unsupported ledger refuses before changing the square.
+
+After successful preflight, one SQLite transaction creates format-4 ownership and
+evidence rows and publishes the format marker. Activity history and indices,
+receipts, lease contents, and the artifact revision are preserved. Legacy routes
+are decoded only during migration and their table is removed. Existing lease
+generations are resolved only for exact owner spellings that match a standing
+participant; other lease rows retain their legacy, unbound generation.
+The new delivery revision starts at zero. There is no intermediate published
+format, and any failure before commit rolls back the conversion.
+
+Format 2 first rebuilds only the activity table and its indexes to accept
+`unlisten`, then follows the same row-format preflight and conversion. Snapshot
+format 1 is not accepted by this format-4 migration.
+
+## What migration refuses
+
+Migration validates the exact old row schema, including the legacy routes table,
+using migration-local codecs. Current format 4 has no routes table or runtime route
+reader; migration consumes the old rows only to resolve seats, then drops the legacy
+table as part of the format change.
+
+Unrelated databases, unsupported formats, non-`DELETE` journal modes, unknown
+schemas, malformed headers or rows, unresolved standing ownership, and ambiguous
+standing or native delivery evidence are refused. The source artifact is preserved on every
+refusal. Migration is not a repair command and never rewrites journal mode to make
+conversion possible. A HostLedger that itself requires migration must be migrated
+separately before Square migration can import its delivery evidence.
+
+## Conservative retired-token restriction
+
+For an old artifact conversion, **any nonempty legacy `host_native_tokens` table
+makes preflight refuse**, including tokens for other sessions. Those token-only
+Claude tombstones are replay protection, not diagnostics: they contain only a
+session and token, with no artifact, participant or activity coordinate. The
+converter cannot safely assign them a join generation. This is deliberately a
+ledger-wide ambiguity refusal, not a claim that each token belongs to the square
+being converted. Even a tombstone duplicated by retained evidence is refused by
+this conservative implementation; no deduplication or history inference is done.
+
+Keep the original ledger and artifact intact. Resolve the ambiguity offline with
+replay protection preserved; **do not delete tombstones just to bypass preflight**.
+An already-current artifact returns without consulting the legacy ledger and
+remains a byte-preserving no-op.
+
+## Before and after migration
+
+Stop every session or service using the square and any process writing its
+HostLedger. Make an offline backup, or use SQLite's backup facilities rather than
+copying a live database. Migration does not revoke an in-flight remote delivery or
+modify HostLedger evidence. Square writes use ordinary SQLite `DELETE` journals:
+the artifact must be writable and its containing directory must permit journal
+creation and removal. The legacy ledger needs read access only. After conversion,
+participation and delivery authority live in the artifact, not writable HOME;
+loss of the rebuildable HOME discovery index may limit automatic discovery but
+does not transfer custody or erase durable delivery evidence.
+
+Upgrade attached runtimes before reopening the format-4 artifact; older runtimes
+must not be mixed with it. Run the read-only `doctor` command after migration and
+before restarting clients. Repeating migration on a current artifact is a
+byte-preserving no-op.

package/guides/row-storage-design.md

@@ -427,7 +427,7 @@ No production structure below carries `.state`, all `.activities`, or a deferred
 | history / participantHistory / historyPresentation | relational head filter + contextIndexes; hydrate filtered candidate bodies for JS search, otherwise page only; count before final limit; selected ordinals + detached presence anchors/perceptions. Retain CLI lifecycle archive/raw coordinate windows and facade non-read inclusion. See algorithm below. |
 | watchPresentation/watch.ts/renderWatchOutput | pass caught activity ids into projection; hydrate ONLY those rows, selected lifetime ordinals, caller-supplied caught perceptions, participant statuses/clock, count/cap/terminal. Finish/terminal-only call omits ids. No all-history lookup of caught ids. |
 | streamProjection/streamTailProjection | ordinary stream pages raw activity heads BEFORE recipient filtering (100 existing rows), advances cursor to last examined raw row even on empty recipient output. Recipient stream filters historical audience, not pending/seen/latest-join. Tail selects last N matching rows but cursor is artifact's last actual index. Includes raw lifecycle/read exactly where current stream does. |
-| sessionInbox/projectPresentation/boundary | participant joined/latestJoin + recipient directed unseen pages + lease; complete result using §6. Boundary's stale-activity fallback uses activity(index) existence, not `.acts.every`. |
+| sessionInbox/located seats/boundary | exact-body seats + establishing join time, recipient directed unseen pages + live lease; complete result using §6. Boundary's stale-activity fallback uses activity(index) existence, not `.acts.every`. |
 | deliverPending/sweep/delivery-health/notifications | pendingAudience groups or audience(activity)+joined/latestJoin+receipt checks for exact activity, ordered routes and detached host ledger evidence. Eligibility projection takes these typed facts instead of state. Sweep scans past suppressed candidates. Health can explicitly collect its complete pending summaries without bodies; renderer's existing detail cap stays. |
 | Claude cancellation/resume/route discovery | cancellation=max existing activity index with at<=cutoff (not assumed chronological time); use newest activity-head pages in one read txn, testing timestamps from greatest index downward and stopping at the first match. If none matches, cutoff is -1. Resume last join/done by EXACT actor spelling; no full snapshot. Routes keep first-match order. |
 | nativePendingPreview (Claude/OpenCode), WakeCurrentness | exact directedAt + joined/latestJoin/unseen receipt, routes first-match/exact epoch/address, fresh lease, captured cancellation cutoff. Generic currentness still joins selected owned routes with host evidence; does not newly consult lease. Pre-effect projection does not persist eligibility. |

package/guides/square-api.md

@@ -15,7 +15,10 @@ Membership is explicit: no harness joins a square based on its filename or worki
 ```ts
 import { Square } from '@astrosheep/square';
 
-const square = await Square.at({ path: './discussion.square', env: { ...process.env } });
+const square = await Square.at({
+  path: './discussion.square',
+  body: { channel: 'example', session: 'alice-process' },
+});
 try {
   const joined = await square.join('Alice');
   const alice = joined.participant;
@@ -30,18 +33,30 @@ try {
 - `Square.build({path, markdown, hardCap?, throttlePerMinute?, template?, force?, ...})` returns
   the same open resource. `Square.inMemory({markdown, ...})` is synchronous and creates no default
   native wake transport.
-- `Square.at` accepts `path`, optional `cwd`, captured `env`, `clock`, `hostLedger`, `wakeTransport`,
-  `backends`, and default `participant`. The `backends` configuration selects explicit named stdio
-  aliases. Paths resolve against `cwd`;
-  `stdio://name/key` stays a canonical URI and routes before filesystem access. An omitted path uses
-  captured `SQUARE_LOCATION`. Explicit participant, configured default, nonblank captured `SQUARE_PARTICIPANT_NAME`,
-  then an unambiguous current-session ledger binding determine a name, in that order.
+- `Square.at` accepts `path`, optional `cwd`, `body`, `wakeAddress`, `clock`, `wakeTransport`,
+  `backends`, default `participant`, and a caller-owned connection via `resources`. At the entry
+  boundary, optional `env` resolves path/configuration, the clock, the concrete transport and the
+  discovery index path once. The opened local resource and participant operations do not carry an
+  environment object or derive identity from it. Supply an explicit Body (`channel`, `session`,
+  optional `agent`) for writes; read-only operations need none. `wakeTransport` injection is retained
+  for both file-backed build/open and memory resources.
+- Paths resolve against `cwd`; an omitted path uses `SQUARE_LOCATION` at entry.
+  `stdio://name/key` stays a canonical URI and routes before filesystem access. The `backends`
+  configuration selects named stdio aliases.
 - `await square.participant(name?)` selects a handle **without joining, claiming or reentering**.
-  Discovery happens on each selection, not through a cached session-to-name decision.
-- `square.join(name?, options?, control?)` returns one `JoinResult`: `{participant, activity, kind,
-  participantCount, observation?}`. `participant` is a handle, not a string. `takeover: true` reclaims
-  a standing name; fresh/departed names join normally. There is no separate `Participant.join()`
-  or public `takeover()` API. `participantCount` counts known joined-or-done names.
+  A supplied name or explicit resource `participant` selects that voice; without either, the artifact
+  must recognize exactly one current seat for the captured Body. Zero or multiple matches refuse.
+  `await square.recognize()` returns all current handles held by that exact Body; the discovery index
+  never establishes ownership, and a name alone never authorizes writes.
+- Join with an explicit name: `square.join('Alice', options?, control?)` returns one `JoinResult`:
+  `{participant, activity, kind, participantCount, observation?}`. The name is required at every
+  boundary: an omitted or blank name refuses, even when the resource has a default `participant` or
+  the captured Body holds exactly one current seat. Only `participant()` performs that unambiguous
+  current-body selection. `participant` is a handle, not a
+  string. `takeover: true` atomically replaces a standing seat; a rejoin after done establishes a new
+  join generation. Same-body reconnection retains its generation. Old handles remain fenced after
+  takeover or rejoin, including when the same Body reacquires the name. There is no separate
+  `Participant.join()` or public `takeover()` API. `participantCount` counts known joined-or-done names.
 - A Square owns its connection unless `resources: createSquareResourceOwner()` lends it one.
   Closing a borrowing handle leaves that owner open. Request signals never become the borrowed
   connection's lifetime. The MCP server drains cancelled/in-flight work before closing its owner;
@@ -51,12 +66,31 @@ try {
 ## One set of operations and defaults
 
 Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
+A file-backed `stream` follows the path with a fresh artifact read for each page, so atomic file
+replacement is visible even while the resource holds its original connection. Its iterator owns
+its observation lifetime: `return()` interrupts a pending pull; closing the Square does not close
+that independent path observation. Internal readers that explicitly borrow an artifact port leave
+its lifetime with the lender and propagate port failures rather than waiting for path repair.
 Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `hold`, `resume`, `done`;
 its `history` delegates to the same Square history operation.
 
 - Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
   includes the committed `activity`, `waited`, optional `delivery`, and landing-time warnings
   (`unmatchedMentions`, `replyAuthorNotHere`). Warnings are not stored on the activity.
+- A say may carry `metadata`, an immutable JSON object with nested JSON values and a maximum serialized
+  UTF-8 size of 16 KiB (`ACTIVITY_METADATA_MAX_BYTES`). `alice.express({body?, metadata?, ...options}, control?)`
+  is the object form; the existing `express(body, options?, control?)` form remains valid. A non-empty
+  body may carry `{}`; an omitted, empty or whitespace-only body requires non-empty metadata. Metadata-only
+  says omit `body` from public activity records. Invalid objects, cycles, unsupported values and oversized
+  metadata refuse before landing with `activityUnsent`. Metadata is carried unchanged by express, history,
+  catch, status/latest, unread projections and stream records through the SDK, stdio, CLI and stream.
+  MCP and Pi tools are not a metadata surface: their `express` requires a body and its schema rejects a
+  `metadata` argument, and every shared tool receipt omits metadata, so tool history/catch results carry
+  the same activities without it. Metadata does not affect mentions, replies, listening, audience, delivery,
+  ordering, consumption or permissions. Metadata may nest up to 256 levels; the bound is enforced before
+  persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
+  metadata JSON. There is no metadata filter, query language or index; CLI `--metadata <json>` is the only
+  metadata input flag.
 - Catch returns `{activities, consumedThrough, remaining, idleExpired, status?, observation?}`.
   Omitted/zero idle is immediate; positive idle uses the single leased quiet wait. Receipt selection,
   ordinals, counts and terminal facts settle in the receipt transaction. Cancellation/replacement
@@ -71,8 +105,9 @@ its `history` delegates to the same Square history operation.
   leaving or blocking future mentions/replies. It returns the same `ListenerChangeResult` as listen
   and ignore, with `activity: null` when no listen exists. Existing ignores are unchanged. Earlier
   landed audiences and receipts are never rewritten; listening again remains available.
-- Lifecycle operations keep contextual reentry/ownership policy. In particular, done retains its
-  native owner epoch fence instead of blindly joining first. Done accepts no message.
+- Lifecycle operations use the same artifact custody gate. Done accepts no message and retires
+  only its captured Body/join generation; it never implicitly rejoins or grants a completed seat
+  write authority.
 
 Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
 Listener/lifecycle operations take optional observation options before that control argument.
@@ -110,20 +145,18 @@ opening a valid current-format Square first.
 
 ## Artifact format and explicit migration
 
-The current artifact format is 3. It records `unlisten` as a real history activity; the derived
-attention table still contains only listen or ignore edges. New artifacts use format 3. Ordinary
-opens refuse older formats with migration guidance, and never migrate implicitly.
-
-Stop all sessions and services using a particular artifact, back it up offline (or use SQLite's
-backup API), then run `square --location <path.square> migrate` and `doctor` before reopening it
-with upgraded runtimes. Older runtimes refuse format 3; do not mix versions against a migrated
-artifact. Updating a package does not migrate any file.
-
-Format 2 migration changes only the activities table's accepted event kinds and the format marker,
-inside one transaction. Existing rows, revision, assigned indices, attention, landed audiences,
-receipts, leases, and routes remain unchanged. Format 1 snapshots import directly into the current
-format. Repeated migration of a current artifact is a byte-preserving no-op. This is separate from
-host-ledger migration, whose format does not change for unlisten.
+The current artifact format is 4. It owns participant seats, delivery evidence and cancellation,
+separate from conversation activities; `unlisten` remains a real history activity. Ordinary opens
+refuse older formats with migration guidance and never convert them implicitly.
+
+Stop all sessions and services using the artifact and freeze its legacy HostLedger, back them up
+offline, then run `square --location <path.square> migrate` and `doctor` before reopening with upgraded
+runtimes. Supported row formats 2/3 convert transactionally only when owner/route/join mappings are
+directly verifiable; no seat is manufactured for done participants. Replay-critical native ambiguity
+refuses rather than disappears, including the conservative refusal of any nonempty legacy token-only
+tombstone table. Current-format migration is a byte-preserving no-op. See [migration.md](migration.md)
+for the deliberately lossy metadata policy, source-preserving refusal and filesystem requirements.
+Updating a package does not migrate files or install a new runtime.
 
 ## Deliberate migration breaks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.86",
+  "version": "0.3.87",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.86",
+  "version": "0.3.87",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/claude/hooks/register.js

@@ -84,7 +84,7 @@ export function register(on) {
     return next(e);
   });
   on('session.end', async ($, e, next) => {
-    // Pinned old ID and captured ownership epochs, never a later current coordinate.
+    // Pinned old ID and captured seat generations, never a later current coordinate.
     const endedAt = await $.clock.now().catch(() => undefined);
     const held = await $.state.get({ plugin: 'square', key: 'inbox', id: e.sessionId }).catch(() => undefined);
     const old = held?.value;

package/plugins/claude/skills/square/SKILL.md

@@ -10,7 +10,7 @@ Bring a thought, a question, an objection, or a gesture. Leave private tool chat
 
 This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The operations are the same either way.
 
-A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and a participant name. Tools take them from your session; the CLI takes `--location` and `--as`, or `SQUARE_LOCATION` and `SQUARE_PARTICIPANT_NAME`.
+A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `--location` (or `SQUARE_LOCATION`) and an explicit `--as <name>` when joining. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
 
 ## The rhythm
 

package/plugins/claude/types.d.ts

@@ -1,4 +1,4 @@
-export type SquareInboxBinding = { location: string; participant: string; session: string; epoch?: number };
+export type SquareInboxBinding = { location: string; participant: string; session: string; generation?: `act/${number}` };
 export type SquareInboxCoordinate = { sessionId: string; cwd: string; version: string; endpoint?: string };
 export type SquareInboxCancellation = { at: number; bindings?: SquareInboxBinding[] };
 export type SquareInboxState = { coordinate: SquareInboxCoordinate; bindings?: SquareInboxBinding[] };

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.86",
+  "version": "0.3.87",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"