@astrosheep/square 0.3.61 → 0.3.62

package/dist/square-application.js

@@ -0,0 +1,183 @@
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { SquareError } from './model.js';
+import { validateDoneBody } from './decisions.js';
+import { currentHold, HELD_WAIT_BUDGET_MS } from './runtime.js';
+import { Square, openParticipant } from './square-wiring.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { statusPresentation, participantsPresentation } from './views.js';
+import { hostLedgerForEnv, localParticipantName, localSessionIdentities, 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, env = context.env) {
+    const selected = context.participant ?? env.SQUARE_PARTICIPANT_NAME;
+    if (selected?.trim())
+        return selected;
+    const discovered = await localParticipantName(squarePath, env).catch(() => undefined);
+    if (discovered !== undefined)
+        return discovered;
+    throw new SquareError('invalid_args', 'Square application context needs one unambiguous participant name');
+}
+function checkControl(control) {
+    if (control?.signal?.aborted)
+        throw new SquareError('invalid_args', 'Square operation was cancelled');
+}
+export function createSquareApplication(context) {
+    const env = { ...context.env };
+    const location = () => requireLocation({ ...context, env });
+    const hostLedger = context.hostLedger ?? hostLedgerForEnv(env);
+    const open = () => Square.at({ path: location(), clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+    async function existing(operation, control) {
+        checkControl(control);
+        const squarePath = location();
+        const participantName = await requireParticipant(context, squarePath, env);
+        const facade = await openParticipant({ path: squarePath, clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport }, participantName);
+        try {
+            checkControl(control);
+            return await operation(facade.participant);
+        }
+        finally {
+            await facade.close();
+        }
+    }
+    async function joined(operation, control) {
+        checkControl(control);
+        const square = await open();
+        try {
+            return await operation(await square.join(await requireParticipant(context, square.location, env), control));
+        }
+        finally {
+            await square.close();
+        }
+    }
+    return {
+        async join(options = {}, control = {}) {
+            checkControl(control);
+            const squarePath = location();
+            const square = await open();
+            try {
+                const participantName = await requireParticipant(context, squarePath, env);
+                const before = await square.snapshot();
+                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, env).catch(() => undefined) : undefined;
+                const reconnect = standing && identity !== undefined && owner?.sessionId === 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();
+            }
+        },
+        async express(body, options = {}, control = {}) {
+            let waited = false;
+            let heldWaitedMs = 0;
+            while (true) {
+                checkControl(control);
+                try {
+                    const result = await existing((participant) => participant.express(body, options, control), control);
+                    return { ...result, waited };
+                }
+                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 });
+                    }
+                    else {
+                        const waitStarted = Date.now();
+                        const square = await openSquare(location(), { clock: context.clock, env, hostLedger, signal: control.signal });
+                        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;
+                    }
+                }
+            }
+        },
+        catch(options, control) { return existing((participant) => participant.catch(options, control), control); },
+        async history(query, control) {
+            checkControl(control);
+            if (context.participant !== undefined || env.SQUARE_PARTICIPANT_NAME !== undefined)
+                return existing((participant) => participant.history(query, control), control);
+            const square = await open();
+            try {
+                checkControl(control);
+                return await square.history(query, control);
+            }
+            finally {
+                await square.close();
+            }
+        },
+        listen(target, control) { return existing((participant) => participant.listen(target, control), control); },
+        ignore(target, control) { return existing((participant) => participant.ignore(target, control), control); },
+        listening(control) { return existing((participant) => participant.listening(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);
+            const squarePath = location();
+            const participantName = await requireParticipant(context, squarePath, env);
+            const identity = localSessionIdentities(env)[0];
+            const owner = identity === undefined ? undefined : await readParticipantOwner(squarePath, participantName, env).catch(() => undefined);
+            if (identity !== undefined && owner?.sessionId === identity.sessionId && owner.epoch > 0) {
+                const square = await open();
+                try {
+                    return await square.doneOwnedSession(participantName, body ?? '', owner.epoch, control);
+                }
+                finally {
+                    await square.close();
+                }
+            }
+            return joined((participant) => participant.done(body, control), control);
+        },
+        async status() {
+            const square = await openSquare(location(), { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+            try {
+                return await statusPresentation(square);
+            }
+            finally {
+                await closeOpenSquare(square);
+            }
+        },
+        async participants() {
+            const square = await openSquare(location(), { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+            try {
+                return await participantsPresentation(square);
+            }
+            finally {
+                await closeOpenSquare(square);
+            }
+        },
+    };
+}

package/dist/square-facade.d.ts

@@ -7,6 +7,7 @@ export interface Activity {
     readonly actor: string;
     readonly body?: string;
     readonly mentions: readonly string[];
+    readonly reach?: Reach;
     readonly target?: string;
     readonly reply?: ActivityId;
 }
@@ -18,6 +19,7 @@ export interface ExpressOptions {
     readonly mentions?: readonly string[];
     readonly reach?: Reach;
     readonly reply?: ActivityId;
+    readonly noMention?: boolean;
 }
 export interface ExpressResult {
     readonly activity: Activity;
@@ -39,12 +41,24 @@ export interface CatchResult {
     readonly idleExpired: boolean;
     readonly remaining: number;
 }
+export interface OperationProgress {
+    readonly kind: 'waiting';
+    readonly reason: 'held' | 'throttled';
+    readonly delayMs?: number;
+    readonly holder?: string;
+    readonly holdReason?: string;
+}
+export interface OperationControl {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: OperationProgress) => void;
+}
 export interface HistoryQuery {
     readonly limit?: number;
     readonly order?: 'asc' | 'desc';
     readonly before?: ActivityId;
     readonly after?: ActivityId;
     readonly grep?: string;
+    readonly fixed?: string;
     readonly from?: readonly string[];
     readonly mention?: string;
 }
@@ -93,13 +107,14 @@ export interface OwnershipFenceOptions {
 }
 export interface Participant {
     readonly name: string;
-    express(body: string, options?: ExpressOptions): Promise<ExpressResult>;
-    listen(target: string): Promise<ListenerChangeResult>;
-    ignore(target: string): Promise<ListenerChangeResult>;
-    listening(): Promise<readonly string[]>;
-    catch(options?: CatchOptions): Promise<CatchResult>;
-    history(query?: HistoryQuery): Promise<Activity[]>;
-    hold(reason?: string): Promise<ExpressResult>;
-    resume(): Promise<ExpressResult>;
-    done(body?: string): Promise<ExpressResult>;
+    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
+    listen(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+    ignore(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+    listening(control?: OperationControl): Promise<readonly string[]>;
+    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
+    hold(reason?: string, control?: OperationControl): Promise<ExpressResult>;
+    resume(control?: OperationControl): Promise<ExpressResult>;
+    /** Leave without a message. Only an omitted or empty body is accepted. */
+    done(body?: string, control?: OperationControl): Promise<ExpressResult>;
 }

package/dist/square-file-adapter.d.ts

@@ -1,6 +1,7 @@
+export { observeSquareRevision as observeSquareChanges } from './artifact.js';
 import { type BuildOptions, type HardCap } from './model.js';
-import { type OpenSquare } from './open-square.js';
-import type { HostLedgerPort } from './ports.js';
+import type { OpenSquare } from './open-square.js';
+import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export declare function createSquare(squarePath: string, options: BuildOptions & {
     hardCap: HardCap;
@@ -20,13 +21,5 @@ export declare function openSquare(squarePath: string, options?: Pick<SquareBuil
 export declare function probeSquare(squarePath: string): Promise<OpenSquare | undefined>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;
-/** Wait for any bound artifact to change; delivery callers re-project after the edge. */
-export type SquareChangeWaitResult<T> = {
-    status: 'ready';
-    value: T;
-} | {
-    status: 'changed';
-} | {
-    status: 'expired';
-};
-export declare function waitForSquareChanges<T>(squarePaths: readonly string[], timeoutMs: number, signal?: AbortSignal, afterReady?: () => Promise<T | undefined>, onArmed?: (armed: boolean) => void): Promise<SquareChangeWaitResult<T>>;
+/** A projection reads and validates its snapshot once; no preliminary duplicate read. */
+export declare function openSquareArtifact(squarePath: string, signal?: AbortSignal): SquareArtifactPort;

package/dist/square-file-adapter.js

@@ -1,7 +1,7 @@
-import path from 'node:path';
+export { observeSquareRevision as observeSquareChanges } from './artifact.js';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import { createSquareState, createSquareSnapshot, probeSquareFile, writeSquareSnapshot, openSquareCell, createMemoryCell, } from './square-storage.js';
 import { InternalSquareError, SquareError, } from './model.js';
-import { closeOpenSquare } from './open-square.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export async function createSquare(squarePath, options, snippet) {
@@ -26,25 +26,23 @@ function validateBuildOptions(options) {
 }
 export async function openSquare(squarePath, options = {}) {
     const env = options.env ?? process.env;
-    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const cell = openSquareCell(squarePath, options.signal);
+    const ledgerRoot = hostLedgerRoot(env);
+    const artifact = openSquareArtifact(squarePath, options.signal);
     try {
-        await cell.read();
-        const artifact = { read: (signal) => cell.read(signal), transact: (fn, signal) => cell.transact(fn, signal), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
+        await artifact.read();
         return {
             artifact,
             clock: options.clock ?? Date.now,
             location: squarePath,
             env,
             hostLedger: options.hostLedger ?? createHostLedgerPort({
-                userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
-                localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
+                rootPath: ledgerRoot,
             }),
             wakeTransport: options.wakeTransport,
         };
     }
     catch (error) {
-        await cell.close();
+        await artifact.close();
         if (error instanceof InternalSquareError && error.code === 'not_found') {
             throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
         }
@@ -81,60 +79,10 @@ export function buildMemorySquare(options) {
     }, options.markdown);
     return { artifact: memoryArtifact(createMemoryCell(squareState)), clock: options.clock ?? Date.now, location: 'memory', hostLedger: options.hostLedger, wakeTransport: options.wakeTransport };
 }
-function memoryArtifact(cell) {
-    return { read: (signal) => cell.read(signal), transact: (fn, signal) => cell.transact(fn, signal), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
+/** A projection reads and validates its snapshot once; no preliminary duplicate read. */
+export function openSquareArtifact(squarePath, signal) {
+    return memoryArtifact(openSquareCell(squarePath, signal));
 }
-export async function waitForSquareChanges(squarePaths, timeoutMs, signal, afterReady, onArmed) {
-    if (timeoutMs <= 0 || signal?.aborted || squarePaths.length === 0) {
-        onArmed?.(false);
-        return { status: 'expired' };
-    }
-    const squares = [];
-    try {
-        for (const squarePath of [...new Set(squarePaths)]) {
-            try {
-                squares.push(await openSquare(squarePath));
-            }
-            catch { /* stale binding */ }
-        }
-        if (squares.length === 0) {
-            onArmed?.(false);
-            return { status: 'expired' };
-        }
-        const baselines = await Promise.all(squares.map(async (square) => ({
-            square,
-            version: (await square.artifact.read()).version,
-        })));
-        const ready = await afterReady?.();
-        if (ready !== undefined) {
-            onArmed?.(false);
-            return { status: 'ready', value: ready };
-        }
-        const waits = baselines.map(async ({ square, version }) => {
-            const changed = await square.artifact.changed(version, timeoutMs).catch(() => false);
-            if (changed)
-                return true;
-            throw new Error('square wait expired');
-        });
-        onArmed?.(true);
-        let abortWait;
-        const abort = new Promise((resolve) => {
-            abortWait = () => resolve(false);
-            if (signal?.aborted)
-                abortWait();
-            else
-                signal?.addEventListener('abort', abortWait, { once: true });
-        });
-        try {
-            const changed = await Promise.race([Promise.any(waits).catch(() => false), abort]);
-            return changed ? { status: 'changed' } : { status: 'expired' };
-        }
-        finally {
-            if (abortWait)
-                signal?.removeEventListener('abort', abortWait);
-        }
-    }
-    finally {
-        await Promise.all(squares.map((square) => closeOpenSquare(square)));
-    }
+function memoryArtifact(cell) {
+    return { read: (signal) => cell.read(signal), transact: (fn, signal) => cell.transact(fn, signal), changed: (since, timeout, signal) => cell.changed(since, timeout, signal), close: () => cell.close() };
 }

package/dist/square-projections.d.ts

@@ -1,12 +1,13 @@
-import { type SquareState } from './model.js';
+import { type InboxMembership, type SquareState } from './model.js';
 import type { HostLedgerPort, SquareArtifactPort, PresentationEvidenceProjection, PresentationProjection, SessionBindingProjection } from './ports.js';
 import { deriveDeliveryModel } from './delivery.js';
 import type { WakeRoute, WakeRouteKind } from './model.js';
+/** A fresh blocking catch owns only the notifications admitted by its filter. */
+export declare function pendingAtBoundary(inbox: InboxMembership[]): InboxMembership[];
 export declare function projectSessionBindings(input: {
     readonly hostLedger: HostLedgerPort;
     readonly sessionId: string;
     readonly location?: string;
-    readonly scopes?: readonly import('./host-ledger.js').HostLedgerScope[];
     readonly now?: number;
 }): Promise<readonly SessionBindingProjection[]>;
 export declare function sessionIdsFromEnvironment(env?: NodeJS.ProcessEnv): readonly string[];

package/dist/square-projections.js

@@ -1,8 +1,17 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { nameKey } from './model.js';
-import { deriveDeliveryModel } from './delivery.js';
+import { deriveDeliveryModel, leaseOwnsNotification } from './delivery.js';
 import { freshWatchLease } from './runtime.js';
 import { canonicalRouteLocation } from './routes.js';
+/** A fresh blocking catch owns only the notifications admitted by its filter. */
+export function pendingAtBoundary(inbox) {
+    return inbox.map((membership) => {
+        const lease = membership.catchLease;
+        if (lease === undefined)
+            return membership;
+        return { ...membership, notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, { ...notification, recipient: membership.name })) };
+    }).filter((membership) => membership.notifications.length > 0);
+}
 function bindingProjection(record) {
     return {
         location: record.location,
@@ -24,7 +33,7 @@ function bindingProjection(record) {
     };
 }
 export async function projectSessionBindings(input) {
-    const rows = await input.hostLedger.listPresence({ location: input.location, session: input.sessionId, scopes: input.scopes ?? ['user', 'local'], now: input.now });
+    const rows = await input.hostLedger.listPresence({ location: input.location, session: input.sessionId, now: input.now });
     return rows.map(bindingProjection);
 }
 export function sessionIdsFromEnvironment(env = process.env) {
@@ -32,7 +41,7 @@ export function sessionIdsFromEnvironment(env = process.env) {
         .map((value) => value?.trim()).filter((value) => Boolean(value));
 }
 export async function projectLocalParticipantBinding(input) {
-    const bindings = (await Promise.all(input.sessionIds.map((sessionId) => projectSessionBindings({ hostLedger: input.hostLedger, location: input.location, sessionId, scopes: ['user', 'local'], now: input.now })))).flat();
+    const bindings = (await Promise.all(input.sessionIds.map((sessionId) => projectSessionBindings({ hostLedger: input.hostLedger, location: input.location, sessionId, now: input.now })))).flat();
     return bindings.find((binding) => binding.participant.toLocaleLowerCase() === input.participant.toLocaleLowerCase());
 }
 export async function projectPresentation(input) {

package/dist/square-storage.js

@@ -1,8 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { setTimeout as sleep } from 'node:timers/promises';
 import { isDeepStrictEqual } from 'node:util';
-import { createSquareFile, createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, readSquareSnapshot, transactSquareSnapshot, writeSquareFile, } from './artifact.js';
+import { createSquareFile, createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, observeSquareRevision, readSquareSnapshot, transactSquareSnapshot, writeSquareFile, } from './artifact.js';
 export { createSquareState };
 async function canonicalPath(squarePath) {
     const absolute = path.resolve(squarePath);
@@ -49,9 +48,6 @@ function isThenable(value) {
 function discardThenable(value) {
     void Promise.resolve(value).catch(() => undefined);
 }
-function isBusy(error) {
-    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
-}
 /** In-process cell for fast behavior tests and embedded consumers. */
 export function createMemoryCell(initial) {
     let state = cloneState(initial);
@@ -65,6 +61,7 @@ export function createMemoryCell(initial) {
                 continue;
             clearTimeout(waiter.timer);
             waiters.delete(waiter);
+            waiter.signal?.removeEventListener("abort", waiter.onAbort);
             waiter.resolve(true);
         }
     }
@@ -106,19 +103,29 @@ export function createMemoryCell(initial) {
                 throw signal.reason ?? new Error('StateCell operation aborted');
             return { state: cloneState(state), version };
         },
-        changed(sinceVersion, timeoutMs) {
+        changed(sinceVersion, timeoutMs, signal) {
             assertCellOpen(closed);
+            if (signal?.aborted)
+                return Promise.reject(signal.reason ?? new Error("StateCell operation aborted"));
             if (version > sinceVersion)
                 return Promise.resolve(true);
             if (timeoutMs <= 0)
                 return Promise.resolve(false);
-            return new Promise((resolve) => {
+            return new Promise((resolve, reject) => {
+                if (signal?.aborted) {
+                    reject(signal.reason ?? new Error("StateCell operation aborted"));
+                    return;
+                }
+                const abort = () => { waiters.delete(waiter); clearTimeout(waiter.timer); signal?.removeEventListener("abort", abort); reject(signal?.reason ?? new Error("StateCell operation aborted")); };
                 const waiter = {
                     since: sinceVersion,
                     resolve,
-                    timer: setTimeout(() => { waiters.delete(waiter); resolve(false); }, timeoutMs),
+                    timer: setTimeout(() => { waiters.delete(waiter); signal?.removeEventListener("abort", abort); resolve(false); }, timeoutMs),
+                    onAbort: abort,
+                    signal,
                 };
                 waiters.add(waiter);
+                signal?.addEventListener("abort", abort, { once: true });
             });
         },
         async close() {
@@ -129,6 +136,7 @@ export function createMemoryCell(initial) {
             for (const waiter of [...waiters]) {
                 clearTimeout(waiter.timer);
                 waiters.delete(waiter);
+                waiter.signal?.removeEventListener("abort", waiter.onAbort);
                 waiter.resolve(false);
             }
         },
@@ -172,36 +180,21 @@ export function createFileCell(squarePath, externalSignal) {
             const snapshot = await readSquareSnapshot(await storagePath(), operationSignal(signal));
             return { state: cloneState(snapshot.state), version: snapshot.revision };
         },
-        async changed(sinceVersion, timeoutMs) {
+        async changed(sinceVersion, timeoutMs, signal) {
             assertCellOpen(closed);
             const deadline = Date.now() + Math.max(0, timeoutMs);
-            while (!closed) {
-                const remaining = deadline - Date.now();
-                const timeout = AbortSignal.timeout(Math.max(1, remaining));
-                const readSignal = AbortSignal.any([cancel.signal, timeout]);
-                try {
-                    if ((await readSquareSnapshot(await storagePath(), readSignal)).revision > sinceVersion)
-                        return true;
-                }
-                catch (error) {
-                    if (closed || cancel.signal.aborted || timeout.aborted)
-                        return false;
-                    if (!isBusy(error))
-                        throw error;
-                }
-                const nextRemaining = deadline - Date.now();
-                if (nextRemaining <= 0)
+            const observer = await observeSquareRevision(await storagePath());
+            try {
+                return await observer.changed(sinceVersion, Math.max(0, deadline - Date.now()), operationSignal(signal));
+            }
+            catch (error) {
+                if (closed || cancel.signal.aborted)
                     return false;
-                try {
-                    await sleep(Math.min(25, nextRemaining), undefined, { signal: cancel.signal });
-                }
-                catch (error) {
-                    if (closed || cancel.signal.aborted)
-                        return false;
-                    throw error;
-                }
+                throw error;
+            }
+            finally {
+                observer.close();
             }
-            return false;
         },
         async close() {
             if (closed)

package/dist/square-wiring.d.ts

@@ -1,5 +1,5 @@
 import type { Activity, ExpressResult, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
-import type { Participant, SquareAtInput, SquareBuildInput } from './square-facade.js';
+import type { Participant, OperationControl, SquareAtInput, SquareBuildInput } from './square-facade.js';
 export declare class Square {
     readonly location: string;
     private readonly square;
@@ -8,23 +8,28 @@ export declare class Square {
     static at(input: SquareAtInput): Promise<Square>;
     static build(input: SquareBuildInput): Promise<Square>;
     static inMemory(input: Omit<SquareBuildInput, 'path'>): Square;
-    join(name: string): Promise<Participant>;
-    joinWithActivity(name: string): Promise<{
+    join(name: string, control?: OperationControl): Promise<Participant>;
+    joinWithActivity(name: string, control?: OperationControl): Promise<{
         readonly participant: Participant;
         readonly activity: Activity | null;
     }>;
-    takeover(name: string): Promise<Participant>;
-    implicitJoin(name: string): Promise<{
+    takeoverWithActivity(name: string, control?: OperationControl): Promise<{
+        readonly participant: Participant;
+        readonly activities: readonly Activity[];
+    }>;
+    takeover(name: string, control?: OperationControl): Promise<Participant>;
+    doneOwnedSession(name: string, body: string, expectedEpoch: number, control?: OperationControl): Promise<ExpressResult>;
+    implicitJoin(name: string, control?: OperationControl): Promise<{
         readonly state: 'joined' | 'active' | 'done';
         readonly participant?: Participant;
     }>;
     participants(): Promise<ParticipantStatus[]>;
     snapshot(): Promise<SquareSnapshot>;
-    history(query?: HistoryQuery): Promise<Activity[]>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
     recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
     close(): Promise<void>;
-    reconcileBinding(): Promise<import("./host-ledger.js").ReconcileBindingResult>;
     endOwnedSession(name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
+    retireEndedSessionRoutes(sessionId: string): Promise<void>;
 }
 export declare function markBoundarySeen(squarePath: string, name: string, actIndexes: readonly number[], at?: number): Promise<void>;
 export declare function openParticipant(input: SquareAtInput, name: string): Promise<{