@astrosheep/square 0.3.70 → 0.3.71

package/dist/square-application.js

@@ -1,185 +1,681 @@
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { SquareError } from './model.js';
+import { SquareError, isSquareError, nameKey, validateName } from './model.js';
 import { validateDoneBody } from './decisions.js';
-import { currentHold, HELD_WAIT_BUDGET_MS } from './runtime.js';
-import { Square } from './square-wiring.js';
-import { openSquare } from './square-file-adapter.js';
-import { closeOpenSquare } from './open-square.js';
-import { catchUp, express, ignore, listen, listening } from './square-actions.js';
-import { participantHistory, resolveParticipant, statusPresentation, participantsPresentation } from './views.js';
-import { hostLedgerForEnv, localParticipantName, localSessionIdentities, presenceEpoch, readParticipantOwner } from './registry.js';
-function requireLocation(context) {
-    const selected = context.squarePath ?? context.env.SQUARE_LOCATION;
-    if (selected === undefined || selected.trim() === '')
-        throw new SquareError('invalid_args', 'Square application context needs a square location');
-    return path.resolve(context.cwd, selected);
-}
-async function requireParticipant(context, squarePath, hostLedger, env = context.env) {
-    const selected = context.participant ?? env.SQUARE_PARTICIPANT_NAME;
-    if (selected?.trim())
-        return selected;
-    const discovered = await localParticipantName(squarePath, hostLedger, env).catch(() => undefined);
-    if (discovered !== undefined)
-        return discovered;
-    throw new SquareError('invalid_args', 'Square application context needs one unambiguous participant name');
-}
+import { HELD_WAIT_BUDGET_MS, WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
+import { catchLimit, observeCatchSelection } from './catch-decisions.js';
+import { directedSuffix } from './activity-feed.js';
+import { assertLiveOwner } from './participant-host.js';
+import { buildMemorySquare, buildSquare, openSquare, closeOpenSquare } from './open-square.js';
+import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, retireEndedSessionRoutes } from './square-actions.js';
+import { recoveryObservation, currentParticipant, entryPresentation, eventPresentation, history, participants, resolveParticipant, snapshot, queryStatus, queryParticipants, catchPresence, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, } from './views.js';
+import { hasAutomaticDeliveryIdentity, hostLedgerForEnv, localParticipantName, localSessionIdentities, presenceEpoch, readParticipantOwner } from './registry.js';
+import { projectSessionBindings } from './square-projections.js';
+import { sessionIdsFromEnvironment } from './participant-identity.js';
+import { createDefaultWakeTransport, wakeGraceMs } from './notifications.js';
+import { sweepPending } from './delivery-operations.js';
+import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
+import { createSquare, diagnoseSquareFile } from './artifact.js';
+import { migrateSquareFile } from './square-migration.js';
+import { discoverSquares, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT } from './list.js';
+import { streamSquare } from './stream.js';
+export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
+export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
+export { HELD_WAIT_BUDGET_MS } from './runtime.js';
+export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
 function checkControl(control) {
     if (control?.signal?.aborted)
-        throw new SquareError('invalid_args', 'Square operation was cancelled');
+        throw control.signal.reason ?? new Error('Square operation was cancelled');
+}
+function clockFor(env, clock) {
+    if (clock !== undefined)
+        return clock;
+    if (env.SQUARE_NOW_MS === undefined)
+        return Date.now;
+    return () => {
+        const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
+        if (!Number.isFinite(value))
+            throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
+        return value;
+    };
+}
+function failure(error, detail) {
+    const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
+    Object.assign(normalized, { operation: detail });
+    return normalized;
+}
+function defaultTransport(square, inMemory = false) {
+    let transport;
+    return () => transport ??= square.wakeTransport !== undefined ? Promise.resolve(square.wakeTransport)
+        : inMemory || square.hostLedger === undefined ? Promise.resolve(undefined)
+            : createDefaultWakeTransport(square.hostLedger, square.clock, square.env).catch(() => undefined);
+}
+function observedContext(square, standingCount, held, participant, now = square.clock()) {
+    return {
+        location: square.location, standingCount, held, now,
+        ...(participant === undefined ? {} : { participant }),
+        automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
+    };
+}
+async function contextProjection(square, participant, control) {
+    const observation = (await square.artifact.read((facts) => ({
+        standingCount: inSquareCount(facts), held: facts.hold().active,
+    }), control?.signal)).value;
+    return observedContext(square, observation.standingCount, observation.held, participant);
+}
+async function joinOwned(square, requested, options = {}, control) {
+    checkControl(control);
+    if (options.takeover && await currentParticipant(square, requested, control) !== undefined) {
+        const result = await takeover(square, requested, [], control);
+        return {
+            participant: result.name, activity: result.activities.at(-1) ?? null,
+            kind: 'taken-over', participantCount: result.participantCount,
+        };
+    }
+    const result = await join(square, requested, control);
+    return {
+        participant: result.name, activity: result.activity,
+        kind: result.reconnected ? 'reconnected' : 'joined', participantCount: result.participantCount,
+    };
+}
+async function prepareExpression(square, requested, control) {
+    try {
+        checkControl(control);
+        const name = (await resolveParticipant(square, requested, control)).name;
+        return await joinOwned(square, name, {}, control);
+    }
+    catch (error) {
+        throw failure(error, { operation: 'express', subject: 'caller', participant: requested, expressEffect: 'unsent' });
+    }
+}
+/** The one retry/commit owner, shared by application and SDK without projections. */
+async function landExpression(square, name, body, options, transport, control) {
+    let effect = 'unsent';
+    let waited = false;
+    let heldWaitedMs = 0;
+    try {
+        const wakeTransport = await transport();
+        while (true) {
+            checkControl(control);
+            try {
+                effect = 'unknown';
+                const result = await express({ ...square, wakeTransport }, name, body, options, control);
+                return { ...result, waited };
+            }
+            catch (error) {
+                if (isSquareError(error) && error.facts?.activityUnsent === true)
+                    effect = 'unsent';
+                if (!isSquareError(error) || options.noWait || (error.code !== 'held' && error.code !== 'throttled'))
+                    throw error;
+                if (error.code === 'held' && heldWaitedMs >= HELD_WAIT_BUDGET_MS)
+                    throw error;
+                waited = true;
+                control?.onProgress?.({
+                    kind: 'waiting', reason: error.code,
+                    ...(error.code === 'throttled' ? { delayMs: error.facts?.retryAfterMs ?? 1 } : {}),
+                    ...(error.facts?.holder === undefined ? {} : { holder: error.facts.holder }),
+                    ...(error.facts?.holdReason === undefined ? {} : { holdReason: error.facts.holdReason }),
+                });
+                if (error.code === 'throttled') {
+                    await sleep(error.facts?.retryAfterMs ?? 1, undefined, { signal: control?.signal });
+                }
+                else {
+                    const started = Date.now();
+                    const observation = await square.artifact.read((facts) => facts.hold().active, control?.signal);
+                    if (observation.value) {
+                        await square.artifact.changed(observation.version, Math.max(1, HELD_WAIT_BUDGET_MS - heldWaitedMs), control?.signal);
+                    }
+                    heldWaitedMs += Date.now() - started;
+                }
+            }
+        }
+    }
+    catch (error) {
+        const recipient = isSquareError(error)
+            && ['not_standing', 'unmatched_mention', 'bell_mention_conflict'].includes(error.facts?.reason ?? '');
+        throw failure(error, {
+            operation: 'express', participant: name, subject: recipient ? 'recipient' : 'caller', expressEffect: effect,
+        });
+    }
+}
+async function expressOwned(square, requested, body, options, transport, control) {
+    const entry = await prepareExpression(square, requested, control);
+    const name = entry.participant;
+    let result;
+    try {
+        const feed = (await square.artifact.read((facts) => {
+            const pendingPublic = directedSuffix(facts, name);
+            return {
+                pendingPublic,
+                sayNumbers: facts.sayOrdinals(pendingPublic.map((item) => item.index)),
+                perceptions: Object.fromEntries(pendingPublic.map((item) => [item.index, 'full'])),
+            };
+        }, control?.signal)).value;
+        result = await landExpression(square, name, body, options, transport, control);
+        // Minimal count/header facts come from the authoritative commit, not a later
+        // read that could erase success or a second feed that would be discarded.
+        const fresh = result.observation;
+        return {
+            data: {
+                activity: result.activity, waited: result.waited,
+                ...(result.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: result.replyAuthorNotHere }),
+            },
+            projection: {
+                ...fresh, ...feed, participant: name,
+                location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
+                ...(entry.activity === null ? {} : { reentry: entry.activity }),
+                ...(result.delivery === undefined ? {} : { delivery: result.delivery }),
+            },
+        };
+    }
+    catch (error) {
+        if (result === undefined && error instanceof Error && 'operation' in error)
+            throw error;
+        throw failure(error, {
+            operation: 'express', participant: name, subject: 'caller',
+            expressEffect: result === undefined ? 'unsent' : 'landed',
+            ...(result === undefined ? {} : { landedId: result.activity.id }),
+        });
+    }
+}
+/** Directed selection guarantees full visibility; only the API exits expose activities. */
+function caughtResult({ selection, stop }) {
+    return {
+        activities: selection.activities.map((activity) => ({ ...toPublicActivity(activity), perception: 'full' })),
+        consumedThrough: selection.consumedThrough, remaining: selection.remaining, idleExpired: stop === 'stale',
+    };
+}
+/** Leases, quiet waiting, selection and sweep form one lifecycle for both APIs. */
+async function catchOwned(square, requested, options = {}, control) {
+    let name = requested, subject = 'caller';
+    let leaseId;
+    let waitStarted = false, replaced = false;
+    let selection = options;
+    const idle = options.idle ?? 0;
+    async function complete(caught, stop) {
+        const selected = caught ?? (await square.artifact.read((facts) => observeCatchSelection(facts, name, [], {
+            unseenOnly: true, senders: selection.from,
+            ...(selection.mention === true ? { attentionOnly: true } : {}),
+        }, square.clock()))).value;
+        const terminal = stop === 'empty-now' || stop === undefined ? selected.terminalStatus ?? stop : stop;
+        if (leaseId !== undefined) {
+            await releaseWatchLease(square, name, leaseId).catch(() => undefined);
+            leaseId = undefined;
+        }
+        if (!control?.signal?.aborted && stop !== 'replaced' && stop !== 'already-active'
+            && (waitStarted || selected.activities.length > 0) && square.location !== 'memory'
+            && square.hostLedger !== undefined && square.env?.SQUARE_DISABLE_PASEO_WAKE !== '1') {
+            try {
+                await sweepPending({
+                    artifact: square.artifact, hostLedger: square.hostLedger, location: square.location,
+                    now: square.clock(), graceMs: wakeGraceMs(square.env), limit: 8,
+                });
+            }
+            catch { /* a completed receipt is not conditional on notification enrichment */ }
+        }
+        return { selection: selected, stop: terminal, waitStarted, replaced };
+    }
+    const empty = (stop) => complete(undefined, stop);
+    try {
+        checkControl(control);
+        if (!Number.isFinite(idle) || idle < 0)
+            throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
+        if (options.id !== undefined
+            && ['idle', 'from', 'mention', 'limit', 'replace'].some((key) => Object.hasOwn(options, key))) {
+            throw new SquareError('invalid_args', 'Catch id cannot be combined with idle, from, mention, limit or replace');
+        }
+        if (Object.hasOwn(options, 'replace') && idle === 0)
+            throw new SquareError('invalid_args', 'Catch replacement requires a positive idle duration');
+        catchLimit(options.limit);
+        name = (await resolveParticipant(square, requested, control)).name;
+        subject = 'filter';
+        const from = options.from === undefined ? undefined : await Promise.all(options.from.map(async (target) => (await resolveParticipant(square, target, control)).name));
+        selection = { ...options, ...(from === undefined ? {} : { from }) };
+        subject = 'caller';
+        if (idle === 0) {
+            const data = await catchUp(square, name, selection, control);
+            return await complete(data, data.activities.length === 0 ? 'empty-now' : undefined);
+        }
+        if (!await assertLiveOwner(square, name)) {
+            throw new SquareError('already_joined', `${name} already stands here — another session holds the name`);
+        }
+        const watch = {
+            ...(from === undefined ? {} : { participants: [...from] }),
+            ...(options.mention ? { mention: name } : {}),
+            ...(options.replace === undefined ? {} : { replace: options.replace }),
+        };
+        const start = await acquireWatchLease(square, name, crypto.randomUUID(), watch, control?.signal);
+        if (start.type === 'active')
+            return await empty('already-active');
+        leaseId = start.leaseId;
+        waitStarted = true;
+        replaced = start.replaced;
+        control?.onProgress?.({
+            kind: 'catch-started', participant: name, idleMs: idle,
+            replacementRequested: options.replace ?? false, replaced,
+        });
+        let quietSince = square.clock();
+        let wasHeld = false;
+        let nextHeartbeat = start.heartbeatAt + WATCH_HEARTBEAT_MS;
+        while (true) {
+            checkControl(control);
+            // Capture before evaluation: commits during selection cannot be missed.
+            const baseline = await square.artifact.revision(control?.signal);
+            const pulse = await pulseWatchLease(square, name, leaseId, watch, square.clock() >= nextHeartbeat, control?.signal);
+            if (pulse.type === 'replaced')
+                return await empty('replaced');
+            if (pulse.type === 'terminal')
+                return await empty(pulse.status);
+            if (pulse.heartbeatAt !== undefined)
+                nextHeartbeat = pulse.heartbeatAt + WATCH_HEARTBEAT_MS;
+            if (pulse.type === 'sleep') {
+                const caught = await catchUp(square, name, selection, control, leaseId);
+                if (caught === null)
+                    return await empty('replaced');
+                if (caught.activities.length > 0)
+                    return await complete(caught);
+            }
+            if (pulse.type === 'held' || wasHeld)
+                quietSince = square.clock();
+            wasHeld = pulse.type === 'held';
+            if (!wasHeld && square.clock() - quietSince >= idle) {
+                const owns = await ownsWatchLease(square, name, leaseId, control?.signal);
+                return await empty(owns ? 'stale' : 'replaced');
+            }
+            const deadline = Math.min(nextHeartbeat, wasHeld ? Infinity : quietSince + idle);
+            await square.artifact.changed(baseline, Math.max(0, deadline - square.clock()), control?.signal);
+        }
+    }
+    catch (error) {
+        throw failure(error, { operation: 'catch', subject, participant: name });
+    }
+    finally {
+        // Cleanup deliberately does not reuse the aborted request signal, and the ID
+        // fence never releases a replacement lease.
+        if (leaseId !== undefined)
+            await releaseWatchLease(square, name, leaseId).catch(() => undefined);
+    }
+}
+class ParticipantHandle {
+    name;
+    square;
+    transport;
+    constructor(name, square, transport) {
+        this.name = name;
+        this.square = square;
+        this.transport = transport;
+    }
+    async express(body, options, control) {
+        const entry = await prepareExpression(this.square, this.name, control);
+        const { waited: _waited, observation: _observation, ...result } = await landExpression(this.square, entry.participant, body, { ...options, noWait: true }, this.transport, control);
+        return result;
+    }
+    listen(target, control) { return listen(this.square, this.name, target, control); }
+    ignore(target, control) { return ignore(this.square, this.name, target, control); }
+    listening(control) { return listening(this.square, this.name, control); }
+    async catch(options, control) {
+        return caughtResult(await catchOwned(this.square, this.name, options, control));
+    }
+    history(query = {}, control) {
+        return history(this.square, query.limit === undefined ? { ...query, limit: HISTORY_DEFAULT_LIMIT } : query, control);
+    }
+    hold(reason, control) { return hold(this.square, this.name, reason, control); }
+    resume(control) { return resume(this.square, this.name, control); }
+    done(body, control) { return done(this.square, this.name, body, {}, control); }
+}
+/** Supported SDK resource. It owns one open artifact; application operations use
+ * the same owner functions directly, not an application -> SDK -> application chain. */
+export class Square {
+    location;
+    square;
+    transport;
+    constructor(location, square) {
+        this.location = location;
+        this.square = square;
+        this.transport = defaultTransport(square, location === 'memory');
+    }
+    static async at(input, control) {
+        const env = { ...(input.env ?? process.env) };
+        return new Square(input.path, await openSquare(input.path, { ...input, env, clock: clockFor(env, input.clock) }, control));
+    }
+    static async build(input) {
+        const env = { ...(input.env ?? process.env) };
+        return new Square(input.path, await buildSquare(input.path, { ...input, env, clock: clockFor(env, input.clock) }));
+    }
+    static inMemory(input) { return new Square('memory', buildMemorySquare(input)); }
+    handle(name) { return new ParticipantHandle(name, this.square, this.transport); }
+    async join(name, control) { return this.handle((await join(this.square, name, control)).name); }
+    async takeover(name, control) {
+        const result = await takeover(this.square, name, [], control);
+        return this.handle(result.name);
+    }
+    doneOwnedSession(name, body, expectedEpoch, control) { return done(this.square, name, body, { expectedEpoch }, control); }
+    async implicitJoin(name, control) {
+        const result = await implicitJoin(this.square, name, control);
+        return { state: result.state, ...(result.state === 'done' ? {} : { participant: this.handle(result.name) }) };
+    }
+    participants() { return participants(this.square); }
+    snapshot(control) { return snapshot(this.square, control); }
+    history(query, control) { return history(this.square, query, control); }
+    async recognize(env) {
+        if (this.square.hostLedger === undefined)
+            return null;
+        const candidates = (await Promise.all(sessionIdsFromEnvironment(env).map((sessionId) => projectSessionBindings({ hostLedger: this.square.hostLedger, location: this.location, sessionId })))).flat();
+        if (candidates.length !== 1)
+            return null;
+        const name = await currentParticipant(this.square, candidates[0].participant);
+        return name === undefined ? null : this.handle(name);
+    }
+    close() { return closeOpenSquare(this.square); }
+    endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.square, name, sessionId, expectedEpoch); }
+    retireEndedSessionRoutes(sessionId) { return retireEndedSessionRoutes(this.square, sessionId); }
 }
 export function createSquareApplication(context) {
     const env = { ...context.env };
-    const location = () => requireLocation({ ...context, env });
+    const clock = clockFor(env, context.clock);
     const hostLedger = context.hostLedger ?? hostLedgerForEnv(env);
-    const open = (control) => Square.at({ path: location(), clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport }, control);
-    async function existing(operation, control) {
+    const openOptions = { env, clock, hostLedger, wakeTransport: context.wakeTransport };
+    const getTransport = defaultTransport(openOptions);
+    function location() {
+        const selected = context.squarePath ?? env.SQUARE_LOCATION;
+        if (selected === undefined || selected.trim() === '')
+            throw new SquareError('invalid_args', 'Square application context needs a square location');
+        return path.resolve(context.cwd, selected);
+    }
+    async function actor() {
+        const selected = context.participant ?? env.SQUARE_PARTICIPANT_NAME;
+        if (context.participant !== undefined || selected?.trim()) {
+            validateName(selected);
+            return selected;
+        }
+        const discovered = await localParticipantName(location(), hostLedger, env);
+        if (discovered !== undefined)
+            return discovered;
+        throw new SquareError('invalid_args', 'Square application context needs one unambiguous participant name');
+    }
+    async function scoped(operation, control) {
         checkControl(control);
-        const squarePath = location();
-        const participantName = await requireParticipant(context, squarePath, hostLedger, env);
-        const square = await openSquare(squarePath, { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport }, control);
+        const square = await openSquare(location(), openOptions, control);
         try {
-            const { name } = await resolveParticipant(square, participantName, control);
-            checkControl(control);
-            return await operation(square, name);
+            return await operation(square);
         }
         finally {
-            await closeOpenSquare(square);
+            await closeOpenSquare(square).catch(() => undefined);
         }
     }
-    async function joined(operation, control) {
-        checkControl(control);
-        const square = await open(control);
+    async function selected(operation, run, control) {
+        let name = context.participant ?? env.SQUARE_PARTICIPANT_NAME;
         try {
-            return await operation(await square.join(await requireParticipant(context, square.location, hostLedger, env), control));
+            checkControl(control);
+            name = await actor();
+            return await scoped((square) => run(square, name), control);
         }
-        finally {
-            await square.close();
+        catch (error) {
+            const detail = error?.operation;
+            if (detail?.operation === operation)
+                throw error;
+            throw failure(error, {
+                operation, participant: detail?.participant ?? name, subject: 'caller',
+                ...(operation === 'express' ? { expressEffect: 'unsent' } : {}),
+            });
         }
     }
+    async function listener(verb, target, control) {
+        return selected('other', async (square, requested) => {
+            const name = (await resolveParticipant(square, requested, control)).name;
+            const result = await (verb === 'listen' ? listen : ignore)(square, name, target, control);
+            return {
+                data: result,
+                projection: {
+                    ...await contextProjection(square, name), participant: name,
+                    requestedTarget: target, target: result.activity?.target ?? target,
+                },
+            };
+        }, control);
+    }
+    async function lifecycle(verb, body, control) {
+        if (verb === 'done')
+            validateDoneBody(body);
+        return selected('other', async (square, requested) => {
+            const identity = localSessionIdentities(env)[0];
+            const owner = verb !== 'done' || identity === undefined ? undefined : await readParticipantOwner(square.location, requested, hostLedger);
+            const fenced = identity !== undefined && owner?.session === identity.sessionId && presenceEpoch(owner) > 0;
+            const name = fenced ? requested : (await join(square, requested, control)).name;
+            let result;
+            if (verb === 'done') {
+                const fence = fenced ? { expectedEpoch: presenceEpoch(owner) } : {};
+                result = await done(square, name, body ?? '', fence, control);
+            }
+            else if (verb === 'hold') {
+                result = await hold(square, name, body, control);
+            }
+            else {
+                result = await resume(square, name, control);
+            }
+            const view = await eventPresentation(square, result.activity.id);
+            return {
+                data: { activity: result.activity },
+                projection: { ...observedContext(square, view.participantCount, view.held, name), ...view },
+            };
+        }, control);
+    }
     return {
-        async join(options = {}, control = {}) {
+        now: clock,
+        async build(input, control) {
             checkControl(control);
             const squarePath = location();
-            const square = await open(control);
-            try {
-                const participantName = await requireParticipant(context, squarePath, hostLedger, env);
-                const before = await square.snapshot(control);
-                const standing = before.participants.some((item) => item.name.toLocaleLowerCase() === participantName.toLocaleLowerCase() && item.state === 'joined');
-                const identity = localSessionIdentities(env)[0];
-                const owner = standing ? await readParticipantOwner(squarePath, participantName, hostLedger).catch(() => undefined) : undefined;
-                const reconnect = standing && identity !== undefined && owner?.session === identity.sessionId;
-                if (standing && owner !== undefined && identity !== undefined && !options.takeover && !reconnect) {
-                    throw new SquareError('already_joined', `✕ ${participantName} already stands here — another session holds the name`, { pending: before.participants.length });
-                }
-                if (options.takeover && standing) {
-                    const replaced = await square.takeoverWithActivity(participantName, control);
-                    const activity = replaced.activities.at(-1) ?? null;
-                    return { participant: replaced.participant.name, activity, kind: 'taken-over', participantCount: (await square.snapshot()).participants.length };
-                }
-                const joined = await square.joinWithActivity(participantName, control);
-                return { participant: joined.participant.name, activity: joined.activity, kind: reconnect ? 'reconnected' : 'joined', participantCount: (await square.snapshot()).participants.length };
-            }
-            finally {
-                await square.close();
-            }
+            const now = clock();
+            const configuration = await createSquare(squarePath, {
+                hardCap: input.hardCap, throttlePerMinute: input.throttlePerMinute,
+                template: input.template, force: input.force ?? false,
+            }, input.markdown, control?.signal);
+            return {
+                data: { location: squarePath, ...configuration },
+                projection: { location: squarePath, standingCount: 0, held: false, now,
+                    automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(env) },
+            };
         },
-        async express(body, options = {}, control = {}) {
-            let waited = false;
-            let heldWaitedMs = 0;
-            while (true) {
-                checkControl(control);
+        join(options = {}, control) {
+            return selected('join', async (square, name) => {
+                const last = options.last ?? 10;
+                if (!Number.isSafeInteger(last) || last < 1 || last > 100) {
+                    throw new SquareError('invalid_args', 'Join history limit must be between 1 and 100');
+                }
+                const data = await joinOwned(square, name, options, control);
                 try {
-                    const result = await existing((square, name) => express(square, name, body, options, control), control);
-                    return { ...result, waited };
+                    const view = await entryPresentation(square, data.participant, last);
+                    return {
+                        data,
+                        projection: { ...observedContext(square, view.participantCount, view.held, data.participant), ...view },
+                    };
                 }
                 catch (error) {
-                    if (!(error instanceof SquareError) || options.noWait || (error.code !== 'held' && error.code !== 'throttled'))
-                        throw error;
-                    // A held wait is a convenience, not a trap: past the budget the error
-                    // surfaces exactly like --no-wait (the CLI saves a draft and prints a retry).
-                    if (error.code === 'held' && heldWaitedMs >= HELD_WAIT_BUDGET_MS)
-                        throw error;
-                    waited = true;
-                    control?.onProgress?.({
-                        kind: 'waiting',
-                        reason: error.code,
-                        ...(error.code === 'throttled' ? { delayMs: error.facts?.retryAfterMs ?? 1 } : {}),
-                        ...(error.facts?.holder === undefined ? {} : { holder: error.facts.holder }),
-                        ...(error.facts?.holdReason === undefined ? {} : { holdReason: error.facts.holdReason }),
-                    });
-                    if (error.code === 'throttled') {
-                        await sleep(error.facts?.retryAfterMs ?? 1, undefined, { signal: control.signal });
+                    throw failure(error, { operation: 'join', participant: data.participant, subject: 'caller' });
+                }
+            }, control);
+        },
+        express(body, options = {}, control) {
+            return selected('express', (square, name) => expressOwned(square, name, body, options, getTransport, control), control);
+        },
+        catch(options, control) {
+            return selected('catch', async (square, name) => {
+                const result = await catchOwned(square, name, options, control);
+                const presence = await catchPresence(square, control).catch(() => undefined);
+                const view = result.selection;
+                const stop = result.stop;
+                const status = stop === 'already-active' || stop === 'replaced' || stop === 'capped' || stop === 'quorum'
+                    ? stop : undefined;
+                return {
+                    data: { ...caughtResult(result), ...(status === undefined ? {} : { status }) },
+                    projection: {
+                        ...observedContext(square, view.standingCount, view.held, view.participant, view.now),
+                        participant: view.participant, sayNumbers: view.sayNumbers,
+                        ownActivityCount: view.ownActivityCount, hardCap: view.hardCap, stop,
+                        ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }),
+                        waitStarted: result.waitStarted, replaced: result.replaced,
+                    },
+                };
+            }, control);
+        },
+        history(query = {}, control) {
+            return scoped(async (square) => {
+                if (query.limit !== undefined && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT)) {
+                    throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);
+                }
+                if (query.grep !== undefined && query.fixed !== undefined)
+                    throw new SquareError('invalid_args', 'History cannot combine regular-expression and literal search');
+                if (query.grep === '' || query.fixed === '')
+                    throw new SquareError('invalid_args', 'History search requires non-empty text');
+                if (query.since !== undefined && !Number.isFinite(query.since))
+                    throw new SquareError('invalid_args', 'History timestamp must be finite');
+                for (const count of [query.contextBefore, query.contextAfter]) {
+                    if (count !== undefined && (!Number.isSafeInteger(count) || count < 0))
+                        throw new SquareError('invalid_args', 'History context must be a non-negative safe integer');
+                }
+                const limit = query.limit ?? (query.at?.length ? null : HISTORY_DEFAULT_LIMIT);
+                const kinds = query.at?.length || query.contextBefore !== undefined || query.contextAfter !== undefined || query.since !== undefined ? undefined : NON_READ;
+                return (await square.artifact.read((facts) => {
+                    const selected = selectHistory(facts, query, limit, kinds);
+                    if (limit === null && selected.totalMatches > HISTORY_MAX_LIMIT) {
+                        throw failure(new SquareError('invalid_args', `History context exceeds ${HISTORY_MAX_LIMIT} activities`), {
+                            operation: 'history', historyBounds: { maxLimit: HISTORY_MAX_LIMIT, totalMatches: selected.totalMatches },
+                        });
                     }
-                    else {
-                        const waitStarted = Date.now();
-                        const square = await openSquare(location(), { clock: context.clock, env, hostLedger }, control);
-                        try {
-                            const snapshot = await square.artifact.read(control.signal);
-                            if (currentHold(snapshot.state.acts).active)
-                                await square.artifact.changed(snapshot.version, Math.max(1, HELD_WAIT_BUDGET_MS - heldWaitedMs), control.signal);
-                        }
-                        finally {
-                            await closeOpenSquare(square);
-                        }
-                        heldWaitedMs += Date.now() - waitStarted;
+                    const indexes = selected.activities.map((activity) => activity.index);
+                    const presenceAnchors = {};
+                    for (const participant of facts.roster()) {
+                        const anchor = presenceAnchor(facts, participant.name);
+                        if (indexes.includes(anchor))
+                            (presenceAnchors[anchor] ??= []).push(participant.name);
                     }
-                }
-            }
+                    return {
+                        data: { activities: publicActivities(selected.activities) },
+                        projection: {
+                            ...observedContext(square, inSquareCount(facts), facts.hold().active), ...selected,
+                            sayNumbers: facts.sayOrdinals(indexes), presenceAnchors,
+                        },
+                    };
+                }, control?.signal)).value;
+            }, control);
+        },
+        listen: (target, control) => listener('listen', target, control),
+        ignore: (target, control) => listener('ignore', target, control),
+        listening(control) {
+            return selected('other', async (square, requested) => {
+                const name = (await resolveParticipant(square, requested, control)).name;
+                const targets = await listening(square, name, control);
+                return { data: { listening: targets }, projection: await contextProjection(square, name, control) };
+            }, control);
         },
-        catch(options, control) { return existing((square, name) => catchUp(square, name, options, undefined, control), control); },
-        async history(query, control) {
+        hold: (reason, control) => lifecycle('hold', reason, control),
+        resume: (control) => lifecycle('resume', undefined, control),
+        done: (body, control) => lifecycle('done', body, control),
+        async status(viewer, control) {
             checkControl(control);
-            if (context.participant !== undefined || env.SQUARE_PARTICIPANT_NAME !== undefined)
-                return existing((square, name) => participantHistory(square, name, query, control), control);
-            const square = await open(control);
-            try {
-                checkControl(control);
-                return await square.history(query, control);
-            }
-            finally {
-                await square.close();
-            }
+            const selectedViewer = viewer ?? await actor().catch(() => '');
+            return scoped(async (square) => (await square.artifact.read((facts) => queryStatus(facts, {
+                location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
+            }, selectedViewer), control?.signal)).value, control);
         },
-        listen(target, control) { return existing((square, name) => listen(square, name, target, control), control); },
-        ignore(target, control) { return existing((square, name) => ignore(square, name, target, control), control); },
-        listening(control) { return existing((square, name) => listening(square, name, control), control); },
-        hold(reason, control) { return joined((participant) => participant.hold(reason, control), control); },
-        resume(control) { return joined((participant) => participant.resume(control), control); },
-        async done(body, control) {
-            validateDoneBody(body);
+        participants(control) {
+            return scoped(async (square) => (await square.artifact.read((facts) => queryParticipants(facts, {
+                location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
+            }), control?.signal)).value, control);
+        },
+        async diagnose(control) {
+            checkControl(control);
             const squarePath = location();
-            const participantName = await requireParticipant(context, squarePath, hostLedger, env);
-            const identity = localSessionIdentities(env)[0];
-            const owner = identity === undefined ? undefined : await readParticipantOwner(squarePath, participantName, hostLedger).catch(() => undefined);
-            if (identity !== undefined && owner?.session === identity.sessionId && presenceEpoch(owner) > 0) {
-                const square = await open(control);
+            const data = await diagnoseSquareFile(squarePath);
+            return {
+                data,
+                projection: { location: squarePath, now: clock(),
+                    ...(data.standingCount === undefined ? {} : { standingCount: data.standingCount }) },
+            };
+        },
+        async migrate(control) {
+            checkControl(control);
+            const squarePath = location();
+            const data = await migrateSquareFile(squarePath, control?.signal);
+            return { data, projection: { location: squarePath, now: clock(), standingCount: data.standing } };
+        },
+        async discover(options, control) {
+            checkControl(control);
+            const data = await discoverSquares(context.cwd, options, control, openOptions);
+            return {
+                data,
+                projection: { cwd: context.cwd, now: clock(),
+                    depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT },
+            };
+        },
+        async inbox(sessionId, options = {}, control) {
+            checkControl(control);
+            const limit = options.limit ?? 20;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new SquareError('invalid_args', 'Inbox limit must be between 1 and 100');
+            const rows = [];
+            for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
+                checkControl(control);
+                let square;
                 try {
-                    return await square.doneOwnedSession(participantName, body ?? '', presenceEpoch(owner), control);
+                    square = await openSquare(binding.location, openOptions, control);
+                    const row = (await square.artifact.read((facts) => {
+                        const participant = facts.participant(binding.participant);
+                        if (!participant?.joined)
+                            return undefined;
+                        return {
+                            name: participant.name, squarePath: binding.location,
+                            pending: facts.directedCount(participant.name, { unseenOnly: true }),
+                        };
+                    }, control?.signal)).value;
+                    if (row !== undefined)
+                        rows.push(row);
+                }
+                catch (error) {
+                    if (control?.signal?.aborted)
+                        throw error;
                 }
                 finally {
-                    await square.close();
+                    if (square !== undefined)
+                        await closeOpenSquare(square);
                 }
             }
-            return joined((participant) => participant.done(body, control), control);
+            rows.sort((a, b) => {
+                const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+                return compare(a.squarePath, b.squarePath) || compare(nameKey(a.name), nameKey(b.name)) || compare(a.name, b.name);
+            });
+            return { data: { rows: rows.slice(0, limit), total: rows.length }, projection: { sessionId, now: clock(), limit } };
         },
-        async status() {
-            const square = await openSquare(location(), { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+        async recovery(control) {
+            let projection = { now: clock() };
             try {
-                return await statusPresentation(square);
-            }
-            finally {
-                await closeOpenSquare(square);
+                projection = { ...projection, location: location() };
+                const name = await actor().catch(() => undefined);
+                if (name !== undefined)
+                    projection = { ...projection, participant: name };
+                await scoped(async (square) => {
+                    if (name === undefined) {
+                        projection = { ...projection, ...await contextProjection(square, undefined, control) };
+                    }
+                    else {
+                        const facts = await recoveryObservation(square, name, control).catch(() => undefined);
+                        projection = facts === undefined
+                            ? { ...projection, ...await contextProjection(square, name, control) }
+                            : {
+                                ...projection, ...observedContext(square, facts.participantCount, facts.held, facts.name),
+                                holdReason: facts.holdReason, ownActivityCount: facts.ownActivityCount,
+                                hardCap: facts.hardCap, roster: facts.roster, activitySummaries: facts.activitySummaries,
+                            };
+                    }
+                }, control);
             }
+            catch { /* unavailable recovery observations never replace the original error */ }
+            return { data: projection, projection };
         },
-        async participants() {
-            const square = await openSquare(location(), { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
-            try {
-                return await participantsPresentation(square);
-            }
-            finally {
-                await closeOpenSquare(square);
-            }
+        stream(options, control) {
+            checkControl(control);
+            return streamSquare(location(), options, control, openOptions);
         },
     };
 }