@astrosheep/square 0.3.61 → 0.3.63

package/dist/square-actions.js

@@ -1,18 +1,21 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin, resolveKnownName } from './decisions.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { isSquareError, nameKey, SquareError, validateName } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { deliverPending } from './delivery-operations.js';
 import { decideCatch } from './catch-decisions.js';
-import { claimSessionParticipant, claimSessionTakeover, readParticipantOwner, withOwnershipClaimLock } from './registry.js';
+import { claimSessionParticipant, claimSessionTakeover, releaseSessionParticipantClaim, readParticipantOwner, withOwnershipClaimLock } from './registry.js';
 import { assertLiveOwner, ensureLocalPresence, identityRouteDraft, processIdentity, publishIdentityRoute, retireIdentityRoute } from './participant-host.js';
-import { applyWakeRouteToState, dropParticipantWakeRoutesFromState, dropSessionWakeRoutesFromState, sessionCanEndParticipant } from './routes.js';
+import { applyWakeRouteToState, dropEndedSessionWakeRoutesFromState, dropParticipantWakeRoutesFromState, dropSessionWakeRoutesFromState, sessionCanEndParticipant } from './routes.js';
+function throwIfAborted(control) { if (control?.signal?.aborted)
+    throw control.signal.reason ?? new Error('Operation aborted'); }
 function exposeCaught(activity, perception) {
     if (activity.kind === 'read' || activity.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(activity.index)}`);
     const result = {
         id: formatActivityId(activity.index), at: activity.at, kind: activity.kind, actor: activity.actor,
         mentions: activity.kind === 'say' ? activity.mentions ?? [] : [],
+        ...(activity.kind === 'say' && activity.reach !== undefined ? { reach: activity.reach } : {}),
         ...('body' in activity && activity.body !== undefined ? { body: activity.body } : {}),
         ...('target' in activity ? { target: activity.target } : {}),
         ...(activity.kind === 'say' && activity.reply !== undefined ? { reply: formatActivityId(activity.reply) } : {}),
@@ -22,11 +25,13 @@ function exposeCaught(activity, perception) {
     const { body: _body, ...withoutBody } = result;
     return { ...withoutBody, perception };
 }
-export async function catchUp(square, name, options = {}, project) {
+export async function catchUp(square, name, options = {}, project, control) {
     const idle = options.idle ?? 0;
     if (!Number.isFinite(idle) || idle < 0)
         throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
     const deadline = Date.now() + idle;
+    if (control?.signal?.aborted)
+        throw control.signal.reason ?? new Error('Operation aborted');
     while (true) {
         if (!await assertLiveOwner(square, name)) {
             throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
@@ -34,7 +39,7 @@ export async function catchUp(square, name, options = {}, project) {
         const attempt = await square.artifact.transact((state, version) => {
             const decision = decideCatch(state, name, options, square.clock(), project);
             return { ...(decision.changed ? { state } : {}), result: { version, decision } };
-        });
+        }, control?.signal);
         await ensureLocalPresence(square, name);
         await publishIdentityRoute(square, name);
         if (attempt.decision.delivered.length > 0 || idle === 0) {
@@ -53,10 +58,10 @@ export async function catchUp(square, name, options = {}, project) {
         // unexpired, so only a real external change can move the artifact version. Establish the
         // wait baseline after those self-side effects; if the version moved anyway (own refresh or
         // a racing external commit), re-snapshot instead of waiting on a stale baseline.
-        const baseline = (await square.artifact.read()).version;
+        const baseline = (await square.artifact.read(control?.signal)).version;
         if (baseline !== attempt.version)
             continue;
-        if (!await square.artifact.changed(baseline, remaining)) {
+        if (!await square.artifact.changed(baseline, remaining, control?.signal)) {
             return { activities: [], consumedThrough: attempt.decision.consumedThrough, idleExpired: true, remaining: 0 };
         }
     }
@@ -84,6 +89,7 @@ function exposeActivity(stored) {
         id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [],
+        ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
         ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}),
     };
@@ -94,10 +100,11 @@ function parseRequiredActivityId(id) {
         throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
     return index;
 }
-export async function join(square, name) {
+export async function join(square, name, control) {
     // Rejected validation must not perform an ownership claim.
+    throwIfAborted(control);
     validateName(name);
-    const preview = await square.artifact.read();
+    const preview = await square.artifact.read(control?.signal);
     const previewDecision = decideJoin(preview.state, name, square.clock());
     if (previewDecision.joinAct === undefined) {
         // An active artifact participant is idempotent only for its current session.
@@ -111,14 +118,6 @@ export async function join(square, name) {
                 // visible yet; concurrent callers must still serialize through CAS.
             }
             else if (owner.sessionId !== identity.session) {
-                const userPresence = await square.hostLedger.listPresence({
-                    location: square.location,
-                    participant: previewDecision.joinedName,
-                    scopes: ['user'],
-                });
-                if (userPresence.some((binding) => binding.session === owner.sessionId)) {
-                    return { name: previewDecision.joinedName, activity: null };
-                }
                 // Continue into the ownership claim below; it will produce the stable
                 // already_joined error without mutating the artifact.
             }
@@ -131,32 +130,44 @@ export async function join(square, name) {
         }
     }
     let epoch;
+    let ownershipClaim;
     if (square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
-        const claim = await claimSessionParticipant(square.location, name, square.env ?? process.env);
+        const claim = await claimSessionParticipant(square.location, name, square.env ?? process.env, control?.signal);
+        ownershipClaim = claim;
         epoch = claim?.epoch;
     }
-    const now = square.clock();
-    const route = await identityRouteDraft(square, name);
-    const committed = await square.artifact.transact((state) => {
-        const decision = decideJoin(state, name, now);
-        if (decision.joinAct === undefined) {
-            return { result: { name: decision.joinedName, stored: null } };
-        }
-        if (square.location !== undefined && square.location !== 'memory')
-            dropParticipantWakeRoutesFromState(state, square.location, decision.joinedName);
-        if (route !== undefined)
-            applyWakeRouteToState(state, route, now);
-        return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
-    });
+    let committed;
+    try {
+        const now = square.clock();
+        const route = await identityRouteDraft(square, name);
+        throwIfAborted(control);
+        committed = await square.artifact.transact((state) => {
+            const decision = decideJoin(state, name, now);
+            if (decision.joinAct === undefined) {
+                return { result: { name: decision.joinedName, stored: null } };
+            }
+            if (square.location !== undefined && square.location !== 'memory')
+                dropParticipantWakeRoutesFromState(state, square.location, decision.joinedName);
+            if (route !== undefined)
+                applyWakeRouteToState(state, route, now);
+            return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
+        }, control?.signal);
+    }
+    catch (error) {
+        await releaseSessionParticipantClaim(square.location, name, square.env ?? process.env, ownershipClaim).catch(() => undefined);
+        throw error;
+    }
     await ensureLocalPresence(square, committed.name, epoch);
     await publishIdentityRoute(square, committed.name, epoch);
     return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
 /** End the standing participant and immediately let the caller reclaim the name. */
-export async function takeover(square, name, _oldSessionIds = []) {
+export async function takeover(square, name, _oldSessionIds = [], control) {
     // Rejected validation must not perform an ownership claim.
+    throwIfAborted(control);
     validateName(name);
     const commitLifecycle = async () => {
+        throwIfAborted(control);
         const now = square.clock();
         const committed = await square.artifact.transact((state) => {
             const joinedName = resolveKnownName(state, name);
@@ -168,7 +179,7 @@ export async function takeover(square, name, _oldSessionIds = []) {
             const storedJoin = committedActivity(storeActs(state, [decision.joinAct]), 'join');
             state.routes = (state.routes ?? []).filter((route) => nameKey(route.participant) !== nameKey(joinedName));
             return { state, result: { name: joinedName, stored: [storedDone, storedJoin] } };
-        });
+        }, control?.signal);
         return committed;
     };
     if (square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
@@ -176,21 +187,23 @@ export async function takeover(square, name, _oldSessionIds = []) {
         // Gate the ownership claim on the artifact's authoritative state: a takeover that cannot
         // commit its lifecycle (a name that never joined, or a standing participant that is no
         // longer joined) must not claim or remove presence. The refusals mirror the transaction.
-        const { state } = await square.artifact.read();
+        const { state } = await square.artifact.read(control?.signal);
         const joinedName = resolveKnownName(state, name); // invalid_args when the name never joined
         coreDone(state, joinedName, '', square.clock()); // already_done/not_joined when not standing
         const owner = await readParticipantOwner(square.location, name, env);
+        throwIfAborted(control);
         // The claim and the artifact lifecycle are one fenced critical section: a losing or refused
         // takeover never mutates the winner, and no second takeover can interleave mid-commit.
         const outcome = await claimSessionTakeover(square.location, name, env, {
             expectedEpoch: owner?.epoch ?? 0,
             expectedSession: owner?.sessionId ?? '',
         }, async (claim) => {
+            throwIfAborted(control);
             const committed = await commitLifecycle();
             await ensureLocalPresence(square, committed.name, claim.epoch);
             await publishIdentityRoute(square, committed.name, claim.epoch);
             return committed;
-        });
+        }, control?.signal);
         if (outcome.status === 'busy')
             throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
         return { name: outcome.result.name, activities: outcome.result.stored.map(exposeActivity), epoch: outcome.epoch };
@@ -200,9 +213,11 @@ export async function takeover(square, name, _oldSessionIds = []) {
     await publishIdentityRoute(square, committed.name);
     return { name: committed.name, activities: committed.stored.map(exposeActivity) };
 }
-export async function implicitJoin(square, name) {
+export async function implicitJoin(square, name, control) {
+    throwIfAborted(control);
     const now = square.clock();
     const route = await identityRouteDraft(square, name);
+    throwIfAborted(control);
     const committed = await square.artifact.transact((state) => {
         const decision = decideImplicitJoin(state, name, now);
         if (decision.state === 'done') {
@@ -217,7 +232,7 @@ export async function implicitJoin(square, name) {
         if (route !== undefined)
             applyWakeRouteToState(state, { ...route, participant: decision.joinedName }, now);
         return { state, result: { name: decision.joinedName, state: decision.state, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
-    });
+    }, control?.signal);
     await ensureLocalPresence(square, committed.name);
     if (committed.state === 'done')
         await retireIdentityRoute(square, committed.name);
@@ -225,31 +240,52 @@ export async function implicitJoin(square, name) {
         await publishIdentityRoute(square, committed.name);
     return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
-export async function express(square, name, body, options = {}) {
+/** Only admission failures can advertise a safe retry; storage and post-commit
+ * failures must not be mistaken for a rejected send merely by their error code. */
+function rejectUnsentActivity(operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (isSquareError(error))
+            error.facts = { ...error.facts, activityUnsent: true };
+        throw error;
+    }
+}
+export async function express(square, name, body, options = {}, control) {
+    if (control?.signal?.aborted)
+        throw control.signal.reason ?? new Error('Operation aborted');
     if (!await assertLiveOwner(square, name)) {
-        throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
+        throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`, { activityUnsent: true });
     }
+    throwIfAborted(control);
     const now = square.clock();
-    const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
+    const reply = rejectUnsentActivity(() => options.reply === undefined ? undefined : parseRequiredActivityId(options.reply));
     const committed = await square.artifact.transact((state) => {
-        const decision = decideAct(state, { name, body, force: options.force ?? false, now, mentions: options.mentions, ...(options.reach === undefined ? {} : { reach: options.reach }), ...(reply === undefined ? {} : { reply }) });
-        if (decision.type === 'blocked') {
-            const pending = decision.activitySummaries.reduce((count, summary) => count + summary.count, 0) + decision.unreadRoomChanges.length;
-            throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending });
-        }
-        if (decision.type === 'held') {
-            const holder = state.acts.filter((activity) => activity.kind === 'hold').at(-1)?.actor;
-            throw new SquareError('held', 'The square is held', holder === undefined ? undefined : { holder });
-        }
-        if (decision.type === 'capped')
-            throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
-        if (decision.type === 'throttled')
-            throw new SquareError('throttled', `${name} is throttled`, { retryAfterMs: decision.delayMs });
-        if (decision.type === 'bell_quota')
-            throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, decision.nextAt - now) });
+        const decision = rejectUnsentActivity(() => {
+            const decision = decideAct(state, { name, body, force: options.force ?? false, now, mentions: options.mentions, ...(options.reach === undefined ? {} : { reach: options.reach }), ...(options.noMention === undefined ? {} : { noMention: options.noMention }), ...(reply === undefined ? {} : { reply }) });
+            if (decision.type === 'blocked') {
+                const pending = decision.activitySummaries.reduce((count, summary) => count + summary.count, 0) + decision.unreadRoomChanges.length;
+                throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending });
+            }
+            if (decision.type === 'held') {
+                const holder = state.acts.filter((activity) => activity.kind === 'hold').at(-1)?.actor;
+                throw new SquareError('held', 'The square is held', {
+                    ...(holder === undefined ? {} : { holder }),
+                    ...(decision.reason === undefined ? {} : { holdReason: decision.reason }),
+                });
+            }
+            if (decision.type === 'capped')
+                throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
+            if (decision.type === 'throttled')
+                throw new SquareError('throttled', `${name} is throttled`, { retryAfterMs: decision.delayMs });
+            if (decision.type === 'bell_quota')
+                throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, decision.nextAt - now) });
+            return decision;
+        });
         const stored = committedActivity(storeActs(state, [decision.act]), 'express');
         return { state, result: { stored } };
-    });
+    }, control?.signal);
     await ensureLocalPresence(square, name);
     await publishIdentityRoute(square, name);
     let delivery;
@@ -261,64 +297,118 @@ export async function express(square, name, body, options = {}) {
     }
     return { activity: exposeActivity(committed.stored), delivery };
 }
-async function landListenerChange(square, verb, actor, target) {
+async function landListenerChange(square, verb, actor, target, control) {
+    throwIfAborted(control);
     const now = square.clock();
     const stored = await square.artifact.transact((state) => {
         const act = verb === 'listen' ? coreListen(state, actor, target, now) : coreIgnore(state, actor, target, now);
         if (act === undefined)
             return { result: null };
         return { state, result: committedActivity(storeActs(state, [act]), verb) };
-    });
+    }, control?.signal);
     return { activity: stored === null ? null : exposeActivity(stored) };
 }
-export function listen(square, actor, target) { return landListenerChange(square, 'listen', actor, target); }
-export function ignore(square, actor, target) { return landListenerChange(square, 'ignore', actor, target); }
-export async function listening(square, actor) { const { state } = await square.artifact.read(); return coreListening(state, actor); }
-async function landCore(square, verb, actor, body = '', fence = {}) {
-    // Done completes ownership: the live-owner validation and the artifact commit share one
-    // ownership critical section, so a takeover finalizing between validation and commit can never
-    // be completed by a stale done — an old expected epoch refuses instead of appending.
-    const commit = async () => {
+export function listen(square, actor, target, control) { return landListenerChange(square, 'listen', actor, target, control); }
+export function ignore(square, actor, target, control) { return landListenerChange(square, 'ignore', actor, target, control); }
+export async function listening(square, actor, control) { const { state } = await square.artifact.read(control?.signal); return coreListening(state, actor); }
+async function landCore(square, verb, actor, body = '', fence = {}, control) {
+    if (verb === 'done')
+        validateDoneBody(body);
+    // Done completes ownership: the live-owner validation, the artifact commit, the ended
+    // session's route retirement, and presence cleanup share one ownership critical section.
+    // A takeover finalizing between validation and commit can never be completed by a stale
+    // done, and no post-lock cleanup can remove a replacement owner's fresh rows.
+    const fenced = verb === 'done' && square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory';
+    const session = fenced ? processIdentity(square.env ?? process.env).session : undefined;
+    const commitAndCleanup = async () => {
         if (verb === 'done' && !await assertLiveOwner(square, actor, fence.expectedEpoch)) {
             throw new SquareError('already_done', `✕ ${participantIdentity(actor)} already stands here — another session holds the name`);
         }
+        let ownerRecords = [];
+        if (fenced && session !== undefined) {
+            ownerRecords = (await square.hostLedger.listPresence({ location: square.location, participant: actor }))
+                .filter((row) => row.session === session);
+        }
         const now = square.clock();
-        return square.artifact.transact((state) => {
+        const stored = await square.artifact.transact((state) => {
             const act = verb === 'done' ? coreDone(state, actor, body, now) : verb === 'hold' ? coreHold(state, actor, body, now) : coreResume(state, actor, now);
-            return { state, result: committedActivity(storeActs(state, [act]), verb) };
-        });
+            const result = committedActivity(storeActs(state, [act]), verb);
+            if (fenced && session !== undefined) {
+                dropEndedSessionWakeRoutesFromState(state, square.location, session, { expectedEpoch: fence.expectedEpoch, force: true, participant: actor });
+            }
+            return { state, result };
+        }, control?.signal);
+        for (const ownerRecord of ownerRecords) {
+            await square.hostLedger.removePresenceIfUnchanged(ownerRecord).catch((error) => {
+                process.stderr.write(`! host presence cleanup degraded: ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+        }
+        return stored;
     };
-    const fenced = verb === 'done' && square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory';
     const stored = fenced
-        ? await withOwnershipClaimLock(square.env ?? process.env, commit)
-        : await commit();
-    if (verb === 'done')
-        await retireIdentityRoute(square, actor, fence.expectedEpoch);
+        ? await withOwnershipClaimLock(square.env ?? process.env, commitAndCleanup, control?.signal)
+        : await commitAndCleanup();
     return { activity: exposeActivity(stored) };
 }
-export function done(square, name, body = '', fence = {}) {
-    return landCore(square, 'done', name, body, fence);
+export function done(square, name, body = '', fence = {}, control) { return landCore(square, 'done', name, body, fence, control); }
+function liveClaimedParticipants(rows, sessionId) {
+    const claimed = new Set();
+    const foreign = new Set();
+    for (const row of rows) {
+        const key = nameKey(row.participant);
+        if (row.session === sessionId)
+            claimed.add(key);
+        else
+            foreign.add(key);
+    }
+    for (const key of foreign)
+        claimed.delete(key);
+    return claimed;
 }
-/** SessionEnd retires the ended session's routes even when its presence row is gone. */
+async function readLiveClaimedParticipants(square, location, sessionId) {
+    if (square.hostLedger === undefined)
+        return new Set();
+    try {
+        return liveClaimedParticipants(await square.hostLedger.listPresence({ location, now: square.clock() }), sessionId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * End one session's ownership of a participant inside the ownership claim critical
+ * section. The artifact `done` (when this session is still the owner) and retirement of
+ * this session's routes share one transaction, and the exact captured presence row is
+ * removed only while the lock is still held. A rejoin or takeover therefore lands either
+ * before the whole cleanup — and is part of the state being ended — or after it, with
+ * fresh presence and route rows that this cleanup can never touch.
+ */
 export async function endOwnedSession(square, name, sessionId, expectedEpoch) {
     const location = square.location;
     const run = async () => {
         const now = square.clock();
         let currentSessionId;
         let ownerMatches = expectedEpoch === undefined;
+        let ownerRecords = [];
+        let liveParticipants = new Set();
         if (location !== undefined && location !== 'memory' && square.hostLedger !== undefined) {
             try {
-                const bindings = await square.hostLedger.listPresence({ location, participant: name, scopes: ['user', 'local'], now });
+                const rows = await square.hostLedger.listPresence({ location, now });
+                const bindings = rows.filter((row) => nameKey(row.participant) === nameKey(name));
                 currentSessionId = bindings.find((binding) => binding.session !== sessionId)?.session
                     ?? bindings.toSorted((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0))[0]?.session;
+                ownerRecords = rows.filter((row) => row.session === sessionId);
+                liveParticipants = liveClaimedParticipants(rows, sessionId);
                 if (expectedEpoch !== undefined) {
                     const owner = await readParticipantOwner(location, name, square.env ?? process.env);
                     ownerMatches = owner?.sessionId === sessionId && owner.epoch === expectedEpoch;
                 }
             }
-            catch { /* stale evidence leaves ownership fenced by artifact routes */ }
+            catch {
+                liveParticipants = undefined; /* unknown evidence preserves routes; artifact routes still fence ownership */
+            }
         }
-        return square.artifact.transact((state) => {
+        const stored = await square.artifact.transact((state) => {
             let committed = null;
             if (location !== undefined && location !== 'memory' && ownerMatches && sessionCanEndParticipant(state, location, name, sessionId, currentSessionId)) {
                 try {
@@ -329,10 +419,19 @@ export async function endOwnedSession(square, name, sessionId, expectedEpoch) {
                         throw error;
                 }
             }
-            if (location !== undefined && location !== 'memory')
-                dropSessionWakeRoutesFromState(state, location, sessionId);
+            if (location !== undefined && location !== 'memory') {
+                dropEndedSessionWakeRoutesFromState(state, location, sessionId, { expectedEpoch, liveParticipants, force: committed !== null });
+            }
             return { state, result: committed };
         });
+        if (stored !== null) {
+            for (const ownerRecord of ownerRecords) {
+                await square.hostLedger.removePresenceIfUnchanged(ownerRecord).catch((error) => {
+                    process.stderr.write(`! host presence cleanup degraded: ${error instanceof Error ? error.message : String(error)}\n`);
+                });
+            }
+        }
+        return stored;
     };
     const fenced = location !== undefined && location !== 'memory' && square.hostLedger !== undefined;
     const stored = fenced
@@ -340,5 +439,22 @@ export async function endOwnedSession(square, name, sessionId, expectedEpoch) {
         : await run();
     return stored === null ? null : { activity: exposeActivity(stored) };
 }
-export function hold(square, name, reason = '') { return landCore(square, 'hold', name, reason); }
-export function resume(square, name) { return landCore(square, 'resume', name); }
+/**
+ * Retire an ended session's orphan routes when no participant name is known. The
+ * ownership claim lock is held across the ledger read and the artifact transaction, so a
+ * rejoin that claims first is seen as a live participant and its route survives.
+ */
+export async function retireEndedSessionRoutes(square, sessionId) {
+    const location = square.location;
+    if (location === undefined || location === 'memory' || square.hostLedger === undefined)
+        return;
+    await withOwnershipClaimLock(square.env ?? process.env, async () => {
+        const liveParticipants = await readLiveClaimedParticipants(square, location, sessionId);
+        await square.artifact.transact((state) => {
+            dropEndedSessionWakeRoutesFromState(state, location, sessionId, { liveParticipants, force: false });
+            return { state, result: undefined };
+        });
+    });
+}
+export function hold(square, name, reason = '', control) { return landCore(square, 'hold', name, reason, {}, control); }
+export function resume(square, name, control) { return landCore(square, 'resume', name, '', {}, control); }

package/dist/square-application.d.ts

@@ -0,0 +1,58 @@
+import type { HostLedgerPort, WakeTransportPort } from './ports.js';
+import { statusPresentation, participantsPresentation } from './views.js';
+import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, ParticipantStatus, PerceivedActivity, OperationControl } from './square-facade.js';
+/** Final control coordinate shared by facade, actions, and application adapters. */
+export interface SquareApplicationContext {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly squarePath?: string;
+    readonly participant?: string;
+    readonly clock?: () => number;
+    readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: WakeTransportPort;
+}
+export interface JoinApplicationOptions {
+    readonly takeover?: boolean;
+}
+export interface JoinApplicationResult {
+    readonly participant: string;
+    readonly activity: Activity | null;
+    readonly kind: 'joined' | 'reconnected' | 'taken-over';
+    readonly participantCount: number;
+}
+export interface ExpressApplicationOptions extends ExpressOptions {
+    readonly noWait?: boolean;
+}
+export interface ExpressApplicationResult extends ExpressResult {
+    readonly waited: boolean;
+}
+export interface ApplicationStatus {
+    readonly context: string;
+    readonly actCount: number;
+    readonly hardCap: number | null;
+    readonly throttlePerMinute?: number;
+    readonly held: {
+        readonly by: string;
+        readonly reason?: string;
+    } | null;
+    readonly participants: readonly ParticipantStatus[];
+}
+export type ApplicationParticipants = Awaited<ReturnType<typeof participantsPresentation>>;
+export type ApplicationStatusProjection = Awaited<ReturnType<typeof statusPresentation>>;
+export interface SquareApplication {
+    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<JoinApplicationResult>;
+    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ExpressApplicationResult>;
+    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
+    listen(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+    ignore(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+    listening(control?: OperationControl): Promise<readonly string[]>;
+    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>;
+    status(): Promise<ApplicationStatusProjection>;
+    participants(): Promise<ApplicationParticipants>;
+}
+export declare function createSquareApplication(context: SquareApplicationContext): SquareApplication;
+export type { CatchResult, PerceivedActivity };