@astrosheep/square 0.3.86 → 0.3.87

package/dist/square-stdio.js

@@ -3,9 +3,10 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { SquareError } from './model.js';
 import { harnessSessionSources } from './participant-identity.js';
+import { requireJoinName } from './seats.js';
 export const STDIO_PROTOCOL_VERSION = 1;
 export const STDIO_MAX_FRAME_BYTES = 8 * 1024 * 1024;
-export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])]), 'SQUARE_PARTICIPANT_NAME'];
+export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])])];
 export function wireIdentity(env) {
     return Object.fromEntries(identityVariables.map(key => [key, env[key] ?? '']));
 }
@@ -162,7 +163,11 @@ class StdioSquare {
     participantHandle(name) {
         return {
             name,
-            express: (body, options, control) => this.call('express', [body, options], control, name),
+            express: ((bodyOrInput, optionsOrControl, control) => {
+                if (typeof bodyOrInput === 'object' && bodyOrInput !== null)
+                    return this.call('express', [bodyOrInput, undefined], optionsOrControl, name);
+                return this.call('express', [bodyOrInput, optionsOrControl], control, name);
+            }),
             catch: (options, control) => this.call('catch', [options], control, name),
             listen: (target, options, control) => this.call('listen', [target, options], control, name),
             ignore: (target, options, control) => this.call('ignore', [target, options], control, name),
@@ -176,6 +181,7 @@ class StdioSquare {
     }
     async participant(name) { return this.participantHandle(await this.call('participant', [name])); }
     async join(...[name, options, control]) {
+        requireJoinName(name);
         const result = await this.call('join', [name, options], control);
         return { ...result, participant: this.participantHandle(result.participant) };
     }
@@ -187,14 +193,13 @@ class StdioSquare {
     stream() { unsupported('stream'); }
     recognize() { return Promise.reject(new SquareError('invalid_args', 'stdio does not support host recognition; select a participant explicitly')); }
     implicitJoin() { unsupported('host implicit join'); }
-    doneOwnedSession() { unsupported('host session cleanup'); }
     endOwnedSession() { unsupported('host session cleanup'); }
-    retireEndedSessionRoutes() { unsupported('host wake routes'); }
+    cancelDeliveries() { unsupported('host delivery cancellation'); }
     close() { return this.connection.close(); }
 }
 export async function openStdioSquare(location, selected, input, backends, build, control) {
-    if (input.clock || input.hostLedger || input.wakeTransport)
-        unsupported('client clock, hostLedger or wakeTransport injection');
+    if (input.clock || input.wakeTransport)
+        unsupported('client clock or wakeTransport injection');
     if (control?.signal?.aborted)
         throw control.signal.reason ?? new Error('Operation cancelled');
     const backend = Object.hasOwn(backends, selected.backend) ? backends[selected.backend] : undefined;
@@ -205,7 +210,7 @@ export async function openStdioSquare(location, selected, input, backends, build
     const connection = new Connection(command, backend.args ?? [], path.resolve(cwd, backend.cwd ?? '.'), { ...(input.env ?? process.env), ...backend.env });
     try {
         const result = await connection.request('square/open', { version: STDIO_PROTOCOL_VERSION, key: selected.key, location,
-            identity: wireIdentity(input.env ?? process.env), participant: input.participant, build }, control);
+            identity: wireIdentity(input.env ?? process.env), body: input.body, participant: input.participant, build }, control);
         if (result.version !== STDIO_PROTOCOL_VERSION || typeof result.handle !== 'string')
             throw new SquareError('unavailable', 'Backend protocol version mismatch');
         return new StdioSquare(location, connection, result.handle);

package/dist/square-tools.js

@@ -14,11 +14,38 @@ function observation(control) {
 function rendering(render) {
     return (result, args) => render(result, args);
 }
+/**
+ * Tool receipts are the one machine surface without activity metadata: a receipt copy drops every
+ * property named `metadata` while domain activities keep theirs for SDK, CLI, stdio and stream readers.
+ */
+function withoutActivityMetadata(value) {
+    if (Array.isArray(value))
+        return value.map(withoutActivityMetadata);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'metadata')
+        .map(([key, item]) => [key, withoutActivityMetadata(item)]));
+}
+/**
+ * Human text renders from the unfiltered receipt, so metadata-only says keep the placeholder the
+ * CLI prints and every other sentence stays identical. Machines only ever receive the filtered copy.
+ */
+const renderingReceipts = new WeakMap();
+function renderingReceipt(receipt) {
+    return (renderingReceipts.get(receipt) ?? receipt);
+}
 function tool(name, description, shape, run, render) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, render, run: (square, args, control) => {
+    return { name, description, inputSchema, render: (receipt, args) => render(renderingReceipt(receipt), args),
+        run: async (square, args, control) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            return run(square, operationArgs, control);
+            const receipt = await run(square, operationArgs, control);
+            const filtered = withoutActivityMetadata(receipt);
+            renderingReceipts.set(filtered, receipt);
+            return filtered;
         } };
 }
 export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';

package/dist/stdio-server.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
 import { SqliteSquare } from './sqlite-square.js';
-import { SquareError } from './model.js';
+import { SquareError, validateBody } from './model.js';
 import { canonicalPath } from './canonical-path.js';
 import { STDIO_PROTOCOL_VERSION, STDIO_MAX_FRAME_BYTES, encodeError, identityVariables } from './square-stdio.js';
 import { parseSquareLocation } from './square-location.js';
@@ -71,7 +71,9 @@ export async function runSquareStdioServer(root) {
                         throw new SquareError('invalid_args', 'Invalid operation identity');
                     env[key] = value ?? '';
                 }
-                const input = { path: target, env, participant: params.participant };
+                const input = { path: target, env, body: params.body, participant: params.participant };
+                if (params.body !== undefined)
+                    validateBody(params.body);
                 square = params.build === undefined ? await SqliteSquare.at(input, control, false)
                     : await SqliteSquare.build({ ...params.build, ...input }, control, false);
                 location = parsed.uri;

package/dist/stream.d.ts

@@ -1,3 +1,4 @@
-import type { OpenOptions, OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
+import type { SquareArtifactPort } from './ports.js';
+import type { OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamRecord>;
+export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, borrowed?: SquareArtifactPort): AsyncIterable<StreamRecord>;

package/dist/stream.js

@@ -1,15 +1,13 @@
 import fs from 'node:fs/promises';
 import { SquareError } from './model.js';
-import { observeSquareRevision } from './artifact.js';
-import { openSquare, closeOpenSquare } from './open-square.js';
+import { createArtifactPort, observeSquareRevision } from './artifact.js';
 import { streamProjection, streamTailProjection } from './views.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export function streamSquare(squarePath, options = {}, control, openOptions = {}) {
+export function streamSquare(squarePath, options = {}, control, borrowed) {
     return {
         [Symbol.asyncIterator]() {
             const disposal = new AbortController();
             const signal = control?.signal === undefined ? disposal.signal : AbortSignal.any([control.signal, disposal.signal]);
-            const iterationControl = { ...control, signal };
             const records = observe();
             return {
                 next: () => records.next(),
@@ -43,19 +41,20 @@ export function streamSquare(squarePath, options = {}, control, openOptions = {}
                             let projection;
                             try {
                                 baseline = await observer.read(signal);
-                                const square = await openSquare(squarePath, { ...openOptions, env: openOptions.env ?? {}, signal }, iterationControl);
+                                const artifact = borrowed ?? createArtifactPort(squarePath, undefined, signal);
                                 try {
-                                    projection = initial === undefined
-                                        ? await streamProjection(square, cursor, options.recipient, iterationControl)
-                                        : await streamTailProjection(square, initial.last, options.recipient, iterationControl);
+                                    projection = (await artifact.read(facts => initial === undefined
+                                        ? streamProjection(facts, cursor, options.recipient)
+                                        : streamTailProjection(facts, initial.last, options.recipient), signal)).value;
                                 }
                                 finally {
-                                    await closeOpenSquare(square);
+                                    if (borrowed === undefined)
+                                        await artifact.close();
                                 }
                             }
                             catch (error) {
                                 signal.throwIfAborted();
-                                if (error instanceof SquareError && error.code === 'invalid_args')
+                                if (borrowed !== undefined || error instanceof SquareError && error.code === 'invalid_args')
                                     throw error;
                                 // Repair/replacement is a hint, not a reason to scan history on a timer.
                                 await observer.hinted(generation, Infinity, signal);

package/dist/views.d.ts

@@ -1,8 +1,7 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
-import type { OpenSquare } from './open-square.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, OperationControl, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
+import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
 export type { EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
@@ -18,12 +17,8 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function resolveParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<{
-    name: string;
-}>;
-export declare function currentParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<string | undefined>;
-export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
-export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<{
+export declare function snapshot(facts: SquareRead, now: number): SquareSnapshot;
+export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     ownActivityCount: number;
     hardCap: import("./model.js").HardCap;
     holdReason?: string | undefined;
@@ -32,12 +27,12 @@ export declare function recoveryObservation(square: OpenSquare, name: string, co
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
     standingCount: number;
     held: boolean;
-}>;
-export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
+};
+export declare function entryPresentation(facts: SquareRead, name: string, lastN?: number | null): EntryPresentation;
 type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now' | 'automaticDeliveryAvailable'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, observe?: boolean): ParticipantsResult;
-export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
+export declare function listPresentation(facts: SquareRead): ListPresentation;
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string, observe?: boolean): StatusResult;
-export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
-export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
-export declare function streamTailProjection(square: OpenSquare, last?: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
+export declare function catchPresence(facts: SquareRead, now: number): CatchPresence;
+export declare function streamProjection(facts: SquareRead, cursor: number, recipient?: string): StreamProjection;
+export declare function streamTailProjection(facts: SquareRead, last?: number, recipient?: string): StreamProjection;

package/dist/views.js

@@ -18,6 +18,7 @@ export function toPublicActivity(stored) {
     return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
+        ...(stored.kind === 'say' && stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
@@ -104,46 +105,34 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
 }
-export async function resolveParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
-}
-export async function currentParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => { const p = facts.participant(name); return p?.joined ? p.name : undefined; }, control?.signal)).value;
-}
 function statuses(facts, now) {
     return coreParticipants(facts, now).filter((p) => p.state !== 'not joined').map((p) => {
         const cursor = readCursor(facts, p.name);
         return { name: p.name, state: p.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: p.presence === 'watching', listening: p.listening };
     });
 }
-export async function snapshot(square, control) {
-    return (await square.artifact.read((facts) => {
-        const header = facts.header(), hold = facts.hold();
-        const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
-        const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
-        return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
-            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-            held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
-            participants: statuses(facts, square.clock()), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
-    }, control?.signal)).value;
-}
-export async function recoveryObservation(square, name, control) {
-    return (await square.artifact.read((facts) => {
-        const known = resolveKnownName(facts, name), hold = facts.hold();
-        return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), standingCount: inSquareCount(facts), held: hold.active,
-            ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
-    }, control?.signal)).value;
-}
-export async function entryPresentation(square, name, lastN = HISTORY_DEFAULT_LIMIT, control) {
-    return (await square.artifact.read((facts) => {
-        const header = facts.header();
-        const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
-        return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
-            scene: header.warmup.join('\n').trim(),
-            joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
-            perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
-            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
-    }, control?.signal)).value;
+export function snapshot(facts, now) {
+    const header = facts.header(), hold = facts.hold();
+    const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
+    const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
+    return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
+        ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
+        held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
+        participants: statuses(facts, now), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
+}
+export function recoveryObservation(facts, name, now) {
+    const known = resolveKnownName(facts, name), hold = facts.hold();
+    return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
+        ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
+}
+export function entryPresentation(facts, name, lastN = HISTORY_DEFAULT_LIMIT) {
+    const header = facts.header();
+    const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
+    return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
+        scene: header.warmup.join('\n').trim(),
+        joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
+        perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
+        sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
 }
 function classifyPresence(participants, now) {
     const here = participants.filter((participant) => participant.state === 'active' && (participant.presence === 'watching'
@@ -159,14 +148,12 @@ export function queryParticipants(facts, context, observe = false) {
     return { participants, ...(!observe ? {} : { observation: { ...context, ...classifyPresence(participants, context.now),
                 standingCount: inSquareCount(facts), held: facts.hold().active } }) };
 }
-export async function listPresentation(square, control) {
-    return (await square.artifact.read((facts) => {
-        const participants = facts.roster().filter((p) => p.joined).map((p) => {
-            const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
-            return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
-        }).sort(compareParticipantActivity).map((p) => p.name);
-        return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
-    }, control?.signal)).value;
+export function listPresentation(facts) {
+    const participants = facts.roster().filter((p) => p.joined).map((p) => {
+        const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
+        return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
+    }).sort(compareParticipantActivity).map((p) => p.name);
+    return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
 }
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
@@ -204,33 +191,26 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
         },
     };
 }
-export async function catchPresence(square, control) {
-    return (await square.artifact.read((facts) => {
-        const now = square.clock();
-        const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
-            || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
-        return { participants, now };
-    }, control?.signal)).value;
-}
-export async function streamProjection(square, cursor, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
-        const heads = page.items.flatMap((head) => {
-            const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
-            return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
-        });
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
-                const route = heads.find((h) => h.index === activity.index).route;
-                return { activity, ...(route === undefined ? {} : { route }) };
-            }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
-    }, control?.signal)).value;
+export function catchPresence(facts, now) {
+    const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
+        || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
+    return { participants, now };
 }
-export async function streamTailProjection(square, last = HISTORY_DEFAULT_LIMIT, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
-            throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
-        const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
-                ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
-    }, control?.signal)).value;
+export function streamProjection(facts, cursor, recipient) {
+    const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
+    const heads = page.items.flatMap((head) => {
+        const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
+        return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
+    });
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
+            const route = heads.find((h) => h.index === activity.index).route;
+            return { activity, ...(route === undefined ? {} : { route }) };
+        }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
+}
+export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipient) {
+    if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
+        throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
+    const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
+            ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
 }

package/dist/wakes.d.ts

@@ -1,5 +1,6 @@
 import { type WatchLease, type WatchOptions } from './model.js';
-import type { OpenSquare } from './open-square.js';
+import type { SquareArtifactPort } from './ports.js';
+import type { Seat } from './model.js';
 export type WatchLeaseStart = {
     readonly type: 'started';
     readonly leaseId: string;
@@ -21,7 +22,7 @@ export type WatchLeasePulse = {
     readonly type: 'sleep';
     readonly heartbeatAt?: number;
 };
-export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
-export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
-export declare function releaseWatchLease(square: OpenSquare, name: string, leaseId: string | undefined): Promise<void>;
-export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string, signal?: AbortSignal): Promise<boolean>;
+export declare function acquireWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
+export declare function pulseWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
+export declare function releaseWatchLease(artifact: SquareArtifactPort, seat: Seat, leaseId: string): Promise<void>;
+export declare function ownsWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, signal?: AbortSignal): Promise<boolean>;

package/dist/wakes.js

@@ -4,23 +4,21 @@ function newLease(leaseId, at, options) {
     const filter = { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
     return { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter).length === 0 ? {} : { filter }) };
 }
-export async function acquireWatchLease(square, name, leaseId, options, signal) {
-    const at = square.clock();
-    const { value } = await square.artifact.transact((facts) => {
-        const known = resolveKnownName(facts, name);
-        const existing = freshWatchLease(facts, known, at);
+export async function acquireWatchLease(artifact, seat, at, leaseId, options, signal) {
+    const name = seat.participant;
+    const { value } = await artifact.transactAs({ kind: 'participant', seat }, facts => {
+        const known = resolveKnownName(facts, name), existing = freshWatchLease(facts, known, at);
         if (existing !== undefined && !options.replace)
             return { type: 'active', lease: existing };
-        facts.putLease(known, newLease(leaseId, at, options));
+        facts.putLease(known, newLease(leaseId, at, options), seat.generation);
         return { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at };
     }, signal);
     return value;
 }
-export async function pulseWatchLease(square, name, leaseId, options, heartbeatDue, signal) {
-    const at = square.clock();
-    const { value } = await square.artifact.transact((facts) => {
-        const known = resolveKnownName(facts, name);
-        const lease = freshWatchLease(facts, known, at);
+export async function pulseWatchLease(artifact, seat, at, leaseId, options, heartbeatDue, signal) {
+    const name = seat.participant;
+    const { value } = await artifact.transactAs({ kind: 'participant', seat }, facts => {
+        const known = resolveKnownName(facts, name), lease = freshWatchLease(facts, known, at);
         if (lease?.leaseId !== leaseId)
             return { type: 'replaced' };
         const held = facts.hold().active;
@@ -30,15 +28,20 @@ export async function pulseWatchLease(square, name, leaseId, options, heartbeatD
         const type = held ? 'held' : 'sleep';
         if (!heartbeatDue)
             return { type };
-        facts.putLease(known, newLease(leaseId, at, options));
+        facts.putLease(known, newLease(leaseId, at, options), seat.generation);
         return { type, heartbeatAt: at };
     }, signal);
     return value;
 }
-export async function releaseWatchLease(square, name, leaseId) {
-    if (leaseId !== undefined)
-        await square.artifact.transact((facts) => facts.removeLease(resolveKnownName(facts, name), leaseId));
+export async function releaseWatchLease(artifact, seat, leaseId) {
+    await artifact.transactAs({ kind: 'participant', seat }, facts => facts.removeLease(seat.participant, leaseId, seat.generation));
 }
-export async function ownsWatchLease(square, name, leaseId, signal) {
-    return (await square.artifact.read((facts) => freshWatchLease(facts, resolveKnownName(facts, name), square.clock())?.leaseId === leaseId, signal)).value;
+export async function ownsWatchLease(artifact, seat, at, leaseId, signal) {
+    const name = seat.participant;
+    return (await artifact.read(facts => {
+        const current = facts.seat(name);
+        if (current === undefined || current.generation !== seat.generation)
+            return false;
+        return freshWatchLease(facts, resolveKnownName(facts, name), at)?.leaseId === leaseId;
+    }, signal)).value;
 }

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

@@ -181,7 +181,7 @@ These are deliverer closures, not a reviewer verdict. Rows distinguish behavior
 | Packed owner orchestration hides effects/count integrity | History, lifecycle branches, maintenance/discovery/recovery, catch conflict and SDK recognize are expanded into readable steps. Remaining one-line SDK delegates are supported simple resource calls, not packed async policy. Inspect implementation diff; all new source is included in count. |
 | Invalid reply / done repair regressions | Typed `invalid_reply` covers malformed and valid-but-absent IDs; typed reach/done reasons stay domain facts, CLI owns glyphs/flags. Express-recovery tests execute printed repaired commands, preserving raw drafts, body candidates and other recipients. Unknown/landed effects offer reconciliation, never replay. |
 | 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. |
+| Captured default wake stops at adapter or executable selection | Amended `createDefaultWakeTransport(env)` builds `CodexQueueTransport({env})`; semantic state time belongs to Square operations and never controls external I/O deadlines; 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. |
 

package/guides/claude-native.md

@@ -21,14 +21,14 @@ An absent/broken endpoint is unavailable; it does not consume Square activity.
 
 ## Native-first routing and policy holds
 
-Native delivery is preferred, including under Paseo. Codex proposes its capable
-native queue before Paseo. Claude and OpenCode receivers register their native
-routes only through their loaded integrations. The common publication transaction
-keeps a fresh native registration ahead of a Paseo proposal for the same
-participant, session, channel and ownership epoch. Tool operations cannot flip it
-back to Paseo between receiver reconciliations. An absent, expired or explicitly
-retired native registration does not block a Paseo fallback; a replacement epoch
-cannot inherit an older native registration.
+Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
+joins register the native queue for their thread. Claude and OpenCode receivers
+register their native wake addresses only through their loaded integrations. An
+ordinary reconnect or implicit join cannot replace a current native address with a
+generic Paseo proposal. Addresses belong to the artifact seat generation, not an
+expiring routes table: explicit receiver withdrawal permits fallback, and a new
+seat generation cannot inherit the previous generation's native registration.
+Participant expressions do not publish replacement addresses.
 
 This is route preference, not permission to bypass receiver policy. Claude can
 legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
@@ -47,7 +47,7 @@ Neither a release nor a drop is a queue receipt, proof of consumption or retry
 authorization.
 
 `square harness doctor delivery` shows native custody separately from pending
-attention, including after the activity is seen or the participant leaves. Paseo
+attention for current seat generations, including after the activity is seen. Paseo
 presents the `peer_message_hold` state in its own timeline. Acceptance means normal
 delivery when the receiver allows it, or a visible reason without bypass/replay when
 policy holds it.

package/guides/mcp.md

@@ -2,7 +2,7 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-Set `SQUARE_LOCATION` to the default `.square` artifact path and optionally `SQUARE_PARTICIPANT_NAME` to the default participant. Calls may override these with `location` and `as`; relative paths use the server's startup working directory. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) identity when present, otherwise the startup environment is used. Participant names are not session identities.
+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 Body (`channel`, `session`, optional `agent`); 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; otherwise a reliable startup coordinate is required for participant writes. Read-only calls do not need a Body.
 
 The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, and `participants`. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.