@astrosheep/square 0.3.58 → 0.3.62

package/dist/registry.js

@@ -1,11 +1,11 @@
 /** Machine-local participant discovery cache. */
 import path from 'node:path';
-import { homedir } from 'node:os';
 import { withFileLock } from './file-lock.js';
 import { sameName, SquareError } from './model.js';
 import { isCurrentlyJoined } from './runtime.js';
 import { squareAssignedParticipantName as computeSquareAssignedParticipantName } from './participant-identity.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+import { hostLedgerRoot } from './host-ledger-root.js';
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const PRESENCE_CLAIM_LOCK = { retryMs: 10 };
 const LOCAL_SESSION_SOURCES = [
@@ -14,23 +14,15 @@ const LOCAL_SESSION_SOURCES = [
     { variable: 'OPENCODE_SESSION_ID', channel: 'opencode' },
     { variable: 'PI_SESSION_ID', channel: 'pi' },
 ];
-export function registryPath(env = process.env) { return env.SQUARE_REGISTRY || path.join(homedir(), '.square', 'sessions.ndjsonl'); }
+export function registryPath(env = process.env) { return env.SQUARE_REGISTRY || path.join(hostLedgerRoot(env), '..', 'sessions.ndjsonl'); }
 export async function canonicalSquarePath(squarePath) { const absolute = path.resolve(squarePath); try {
     return await (await import('node:fs/promises')).realpath(absolute);
 }
 catch {
     return absolute;
 } }
-function ledgerRoot(env) {
-    const root = path.dirname(registryPath(env));
-    return {
-        userPath: env.SQUARE_HOST_LEDGER_USER ?? (env.SQUARE_REGISTRY ? root : path.join(homedir(), '.square', 'host-ledger')),
-        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? (env.SQUARE_REGISTRY ? root : path.join(process.cwd(), '.square', 'host-ledger')),
-    };
-}
-function ledger(env, writableScope = 'local') {
-    return createHostLedgerPort({ ...ledgerRoot(env), writableScope });
-}
+function ledgerRoot(env) { return hostLedgerRoot(env); }
+function ledger(env) { return createHostLedgerPort({ rootPath: ledgerRoot(env) }); }
 export function presenceEpoch(record) {
     return typeof record?.epoch === 'number' && Number.isSafeInteger(record.epoch) && record.epoch > 0 ? record.epoch : 0;
 }
@@ -47,22 +39,21 @@ function toBinding(record) {
     };
 }
 function presenceClaimLockPath(env) {
-    return path.join(ledgerRoot(env).userPath, 'presence-claim.lock');
+    return path.join(ledgerRoot(env), 'presence-claim.lock');
 }
 /** Runs `fn` inside the ownership claim critical section, under the same lock as claims and finalize. */
-export async function withOwnershipClaimLock(env, fn) {
-    return withFileLock(presenceClaimLockPath(env), PRESENCE_CLAIM_LOCK, fn);
+export async function withOwnershipClaimLock(env, fn, signal) {
+    return withFileLock(presenceClaimLockPath(env), { ...PRESENCE_CLAIM_LOCK, signal }, fn);
 }
-async function activeBindings(now, env) { return (await ledger(env).listPresence({ now, scopes: ['user', 'local'] })).map(toBinding).sort((a, b) => b.updatedAt - a.updatedAt); }
-async function writePresence(sessionId, name, squarePath, options, done, scope = 'local') { if (!sessionId || !name || !squarePath)
-    return; const env = options.env ?? process.env; const channel = options.channel ?? 'unknown'; const port = ledger(env, scope); const location = await canonicalSquarePath(squarePath); if (done)
+async function activeBindings(now, env) { return (await ledger(env).listPresence({ now })).map(toBinding).sort((a, b) => b.updatedAt - a.updatedAt); }
+async function writePresence(sessionId, name, squarePath, options, done) { if (!sessionId || !name || !squarePath)
+    return; const env = options.env ?? process.env; const channel = options.channel ?? 'unknown'; const port = ledger(env); const location = await canonicalSquarePath(squarePath); if (done)
     await port.removePresence({ location, participant: name, session: sessionId, channel });
 else
     await port.ensurePresence({ location, participant: name, session: sessionId, channel, updatedAt: options.at ?? Date.now() }); }
 export function recordJoin(sessionId, name, squarePath, options = {}) { return writePresence(sessionId, name, squarePath, options, false); }
 export async function recordDone(sessionId, name, squarePath, options = {}) {
     await writePresence(sessionId, name, squarePath, options, true);
-    await writePresence(sessionId, name, squarePath, options, true, 'user');
 }
 export async function readActiveBindings(now = Date.now(), env = process.env) { try {
     return await activeBindings(now, env);
@@ -87,10 +78,18 @@ export async function sessionOwnsParticipant(squarePath, name, sessionId, env =
         return false;
     return expectedEpoch === undefined || owner.epoch === expectedEpoch;
 }
-export async function claimSessionParticipant(squarePath, name, env = process.env) {
+export async function releaseSessionParticipantClaim(squarePath, name, env, claim) {
+    if (claim?.status !== 'acquired')
+        return;
+    const port = ledger(env);
+    await port.removePresenceIfUnchanged(claim.record);
+}
+export async function claimSessionParticipant(squarePath, name, env = process.env, signal) {
     const identity = localSessionIdentities(env)[0];
     if (identity === undefined)
         return undefined;
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Operation aborted');
     const location = await canonicalSquarePath(squarePath);
     const result = await ledger(env).claimPresence({
         location,
@@ -99,13 +98,13 @@ export async function claimSessionParticipant(squarePath, name, env = process.en
         channel: identity.channel,
         updatedAt: Date.now(),
         epoch: 1,
-    }, 'local');
+    }, signal);
     if (result.status === 'busy')
-        throw new SquareError('already_joined', `${name} is already bound to another session`);
+        throw new SquareError('already_joined', `✕ ${name} already stands here — another session holds the name`);
     if (result.status === 'degraded')
         throw result.error;
-    const epoch = presenceEpoch(result.record) || (result.status === 'acquired' ? 1 : 0);
-    return { status: result.status, sessionId: identity.sessionId, epoch };
+    const record = result.record;
+    return { status: result.status, record, sessionId: record.session, epoch: presenceEpoch(record) };
 }
 /**
  * Fenced takeover: the ownership claim and the lifecycle run as one critical section under the
@@ -116,18 +115,15 @@ export async function claimSessionParticipant(squarePath, name, env = process.en
  * carrying the claim token (session + channel + claim epoch) are withdrawn and the captured
  * standing rows are restored exactly.
  */
-export async function claimSessionTakeover(squarePath, name, env = process.env, opts = {}, lifecycle) {
+export async function claimSessionTakeover(squarePath, name, env = process.env, opts = {}, lifecycle, signal) {
     const identity = localSessionIdentities(env)[0];
     if (identity === undefined)
         throw new SquareError('invalid_args', 'No local session identity for takeover');
     const location = await canonicalSquarePath(squarePath);
-    return withFileLock(presenceClaimLockPath(env), PRESENCE_CLAIM_LOCK, async () => {
+    return withFileLock(presenceClaimLockPath(env), { ...PRESENCE_CLAIM_LOCK, signal }, async () => {
         const port = ledger(env);
-        const standing = {
-            user: await port.listPresence({ location, participant: name, scopes: ['user'] }),
-            local: await port.listPresence({ location, participant: name, scopes: ['local'] }),
-        };
-        const owner = [...standing.user, ...standing.local]
+        const standing = await port.listPresence({ location, participant: name });
+        const owner = standing
             .map((row) => toBinding(row))
             .sort((left, right) => right.epoch - left.epoch || right.updatedAt - left.updatedAt)[0];
         const currentEpoch = owner?.epoch ?? 0;
@@ -147,50 +143,21 @@ export async function claimSessionTakeover(squarePath, name, env = process.env,
             // token (session + channel + epoch) — whatever the lifecycle itself ensured — then restore
             // the captured standing rows so the old owner survives byte-consistently. Foreign rows and
             // later owners are never touched.
-            for (const scope of ['user', 'local']) {
-                const tokenRows = await ledger(env, scope).listPresence({
-                    location,
-                    participant: name,
-                    session: identity.sessionId,
-                    scopes: [scope],
-                });
-                for (const row of tokenRows) {
-                    if (row.channel !== identity.channel || presenceEpoch(row) !== epoch)
-                        continue;
-                    await ledger(env, scope).removePresence({
-                        location: row.location,
-                        participant: row.participant,
-                        session: row.session,
-                        channel: row.channel,
-                    });
-                }
-                for (const row of standing[scope]) {
-                    await ledger(env, scope).ensurePresence(row, scope);
-                }
+            const tokenRows = await ledger(env).listPresence({ location, participant: name, session: identity.sessionId });
+            for (const row of tokenRows) {
+                if (row.channel === identity.channel && presenceEpoch(row) === epoch)
+                    await ledger(env).removePresence({ location: row.location, participant: row.participant, session: row.session, channel: row.channel });
             }
+            for (const row of standing)
+                await ledger(env).ensurePresence(row);
             throw error;
         }
         // Finalize: the lifecycle committed. Replace the standing owner with the new owner's row at
-        // the claim epoch in every scope where the owner was visible, so exactly one current owner
+        // the claim epoch where the owner was visible, so exactly one current owner
         // remains — also when the takeover is a self-takeover (same session as the standing owner).
-        for (const scope of ['user', 'local']) {
-            for (const row of standing[scope]) {
-                await ledger(env, scope).removePresence({
-                    location: row.location,
-                    participant: row.participant,
-                    session: row.session,
-                    channel: row.channel,
-                });
-            }
-            await ledger(env, scope).ensurePresence({
-                location,
-                participant: name,
-                session: identity.sessionId,
-                channel: identity.channel,
-                updatedAt: Date.now(),
-                epoch,
-            }, scope);
-        }
+        for (const row of standing)
+            await ledger(env).removePresence({ location: row.location, participant: row.participant, session: row.session, channel: row.channel });
+        await ledger(env).ensurePresence({ location, participant: name, session: identity.sessionId, channel: identity.channel, updatedAt: Date.now(), epoch });
         return { status: 'acquired', sessionId: identity.sessionId, epoch, result };
     });
 }
@@ -203,7 +170,7 @@ export async function releaseSessionParticipant(squarePath, name, env = process.
 export async function bindCurrentParticipant(squarePath, name, env = process.env) { if (squareAssignedParticipantName(env) !== name)
     throw new SquareError('invalid_args', `The current session is not assigned ${name}`); const sessionId = await localParticipantOwner(squarePath, name, env); if (sessionId !== undefined)
     return { created: false, sessionId }; if ((await lookupParticipant(squarePath, name, Date.now(), env)).at(0) !== undefined)
-    throw new SquareError('already_joined', `${name} is already bound to another session`); await recordLocalJoin(name, squarePath, env); const currentSessionId = await localParticipantOwner(squarePath, name, env); if (currentSessionId === undefined)
+    throw new SquareError('already_joined', `✕ ${name} already stands here — another session holds the name`); await recordLocalJoin(name, squarePath, env); const currentSessionId = await localParticipantOwner(squarePath, name, env); if (currentSessionId === undefined)
     throw new Error(`Current participant binding did not commit for ${name}`); return { created: true, sessionId: currentSessionId }; }
 export async function unbindCurrentParticipant(squarePath, name, env = process.env) { const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); const current = (await lookupParticipant(squarePath, name, Date.now(), env)).filter((binding) => identities.has(binding.sessionId)); for (const binding of current)
     await recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel, env); return current.length > 0; }
@@ -226,9 +193,9 @@ export async function recordLocalJoin(name, squarePath, env = process.env) { con
 } }
 export async function recordLocalDone(name, squarePath, env = process.env) { const at = Date.now(); const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => identities.has(binding.sessionId)); for (const binding of current)
     await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); }
-export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => binding.sessionId === sessionId); for (const binding of current) {
-    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env });
-    await writePresence(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }, true, 'user');
-} await recordJoin(sessionId, name, squarePath, { channel, at, env }); await writePresence(sessionId, name, squarePath, { channel, at, env }, false, 'user'); return sessionId; }
+export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => binding.sessionId === sessionId); for (const binding of current)
+    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); await recordJoin(sessionId, name, squarePath, { channel, at, env }); return sessionId; }
 export async function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const binding = (await lookupSessionBindings(sessionId, Date.now(), env)).find((item) => item.squarePath === canonicalPath && sameName(item.name, name) && item.channel === channel); if (binding === undefined)
-    return false; const options = { channel, at: Date.now(), env }; await recordDone(sessionId, binding.name, binding.squarePath, options); await writePresence(sessionId, binding.name, binding.squarePath, options, true, 'user'); return true; }
+    return false; const options = { channel, at: Date.now(), env }; await recordDone(sessionId, binding.name, binding.squarePath, options); return true; }
+/** Bind the host ledger to the caller's captured environment. */
+export function hostLedgerForEnv(env = process.env) { return ledger(env); }

package/dist/routes.d.ts

@@ -36,7 +36,22 @@ export type RouteEpoch = {
     readonly epoch?: number;
 };
 export declare function applyWakeRouteToState(state: import('./model.js').SquareState, route: Omit<WakeRoute, 'updatedAt'> & RouteEpoch, at?: number): void;
-export declare function dropSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string): void;
+export declare function dropSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string, expectedEpoch?: number): void;
+/**
+ * Drop one ended session's routes at a location, atomically with the lifecycle decide.
+ *
+ * A route survives when the ending transaction did not commit `done` and this session
+ * still holds the sole live presence for its participant — an in-flight same-session
+ * rejoin. `liveParticipants === undefined` means the ledger could not be read, so
+ * nothing is dropped on suspicion. An explicit epoch fence additionally keeps routes
+ * published by a later generation.
+ */
+export declare function dropEndedSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string, opts: {
+    readonly expectedEpoch?: number;
+    readonly liveParticipants?: ReadonlySet<string>;
+    readonly force: boolean;
+    readonly participant?: string;
+}): void;
 export declare function dropParticipantWakeRoutesFromState(state: import('./model.js').SquareState, location: string, participant: string): void;
 export declare function sessionOwnsParticipantRoutes(state: import('./model.js').SquareState, location: string, participant: string, sessionId: string): boolean;
 export declare function sessionCanEndParticipant(state: import('./model.js').SquareState, location: string, participant: string, sessionId: string, currentSessionId?: string): boolean;
@@ -52,5 +67,7 @@ export declare function retireWakeRoute(route: WakeRoute, opts?: {
 export declare function retireWakeRouteFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>, opts?: {
     readonly expectedEpoch?: number;
 }): Promise<void>;
-export declare function retireWakeRoutesForSessionFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'sessionId'>): Promise<void>;
+export declare function retireWakeRoutesForSessionFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'sessionId'>, opts?: {
+    readonly expectedEpoch?: number;
+}): Promise<void>;
 export declare function canonicalRouteLocation(location: string): Promise<string>;

package/dist/routes.js

@@ -10,7 +10,7 @@ export async function defaultWakeRouteCapabilities(hostLedger) {
     let userCapable = hostLedger !== undefined;
     if (hostLedger !== undefined) {
         try {
-            await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+            await hostLedger.listPresence({ now: Date.now() });
         }
         catch {
             userCapable = false;
@@ -109,9 +109,44 @@ export function applyWakeRouteToState(state, route, at = Date.now()) {
             return !(itemLocation === location && routeIdentityKey(item, itemLocation) === routeIdentityKey(route, location));
         }), { ...route, location, updatedAt: at }];
 }
-export function dropSessionWakeRoutesFromState(state, location, sessionId) {
+export function dropSessionWakeRoutesFromState(state, location, sessionId, expectedEpoch) {
     const canonical = canonicalRouteLocationSync(location);
-    state.routes = (state.routes ?? []).filter((item) => !(item.sessionId === sessionId && canonicalRouteLocationSync(item.location) === canonical));
+    state.routes = (state.routes ?? []).filter((item) => {
+        if (item.sessionId !== sessionId || canonicalRouteLocationSync(item.location) !== canonical)
+            return true;
+        if (expectedEpoch === undefined)
+            return false;
+        return item.epoch !== expectedEpoch;
+    });
+}
+/**
+ * Drop one ended session's routes at a location, atomically with the lifecycle decide.
+ *
+ * A route survives when the ending transaction did not commit `done` and this session
+ * still holds the sole live presence for its participant — an in-flight same-session
+ * rejoin. `liveParticipants === undefined` means the ledger could not be read, so
+ * nothing is dropped on suspicion. An explicit epoch fence additionally keeps routes
+ * published by a later generation.
+ */
+export function dropEndedSessionWakeRoutesFromState(state, location, sessionId, opts) {
+    const canonical = canonicalRouteLocationSync(location);
+    state.routes = (state.routes ?? []).filter((item) => {
+        if (item.sessionId !== sessionId || canonicalRouteLocationSync(item.location) !== canonical)
+            return true;
+        if (opts.participant !== undefined && nameKey(item.participant) !== nameKey(opts.participant))
+            return true;
+        if (!opts.force) {
+            // Keep only a route whose participant is still joined and whose ended session still
+            // holds the sole live presence — an in-flight same-session rejoin. A no-longer-joined
+            // participant is retired even when a stale presence row survives.
+            if (isCurrentlyJoined(state.acts, item.participant)
+                && (opts.liveParticipants === undefined || opts.liveParticipants.has(nameKey(item.participant))))
+                return true;
+        }
+        if (opts.expectedEpoch !== undefined && item.epoch !== opts.expectedEpoch)
+            return true;
+        return false;
+    });
 }
 export function dropParticipantWakeRoutesFromState(state, location, participant) {
     const canonical = canonicalRouteLocationSync(location);
@@ -163,8 +198,16 @@ export async function retireWakeRouteFromArtifact(artifact, route, opts = {}) {
                 return opts.expectedEpoch !== undefined && itemEpoch !== opts.expectedEpoch;
             }) }, result: undefined }));
 }
-export async function retireWakeRoutesForSessionFromArtifact(artifact, route) {
-    await artifact.transact((state) => { dropSessionWakeRoutesFromState(state, route.location, route.sessionId); return { state, result: undefined }; });
+export async function retireWakeRoutesForSessionFromArtifact(artifact, route, opts = {}) {
+    const location = canonicalRouteLocationSync(route.location);
+    await artifact.transact((state) => ({ state: { ...state, routes: (state.routes ?? []).filter((item) => {
+                if (canonicalRouteLocationSync(item.location) !== location || item.sessionId !== route.sessionId)
+                    return true;
+                if (opts.expectedEpoch === undefined)
+                    return false;
+                const itemEpoch = item.epoch;
+                return itemEpoch !== undefined && itemEpoch !== opts.expectedEpoch;
+            }) }, result: undefined }));
 }
 export async function canonicalRouteLocation(location) {
     return canonicalRouteLocationSync(location);

package/dist/runtime.d.ts

@@ -7,6 +7,8 @@ export declare const WATCH_STALE_MS: number;
 export declare const LOCK_RETRY_MS: number;
 export declare const THROTTLE_WINDOW_MS: number;
 export declare const UNREAD_BLOCK_GRACE_MS: number;
+/** A held express waits for the hand to lower, but not forever: past this budget it gives up exactly like --no-wait (draft saved, retry printed). 0 disables waiting. */
+export declare const HELD_WAIT_BUDGET_MS: number;
 export declare function nowMs(): number;
 /** Pure directed-activity filter. Bell matches every viewer; mentions match by audience. */
 export declare function matchesMentionTarget(act: {
@@ -38,6 +40,14 @@ export declare function observationFor(squareState: SquareState, name: string, i
 export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number): boolean;
 export declare function readCursor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
 export declare function latestActIndex(acts: StoredAct[]): number;
+/**
+ * "Was here" is a claim of presence, so it rides on evidence: the participant's own acts
+ * and seen receipts after their latest join. Anything else — in particular acts merely
+ * not addressed to them — says nothing about where they actually were.
+ */
+export declare function presenceEvidenceCursor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
+/** The last public act the participant was verifiably present for, or -1 when there is no evidence. */
+export declare function presenceAnchor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
 export declare function freshWatchLease(squareState: SquareState, name: string, at?: number): WatchLease | undefined;
 export declare function watchLease(squareState: SquareState, name: string): WatchLease | undefined;
 export declare function writeWatchLease(squareState: SquareState, name: string, lease: WatchLease): void;

package/dist/runtime.js

@@ -40,6 +40,8 @@ export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', scaledMs(
 export const LOCK_RETRY_MS = parseIntegerEnv('SQUARE_LOCK_RETRY_MS', 25);
 export const THROTTLE_WINDOW_MS = parseIntegerEnv('SQUARE_THROTTLE_WINDOW_MS', 60000);
 export const UNREAD_BLOCK_GRACE_MS = parseIntegerEnv('SQUARE_UNREAD_BLOCK_GRACE_MS', 90000);
+/** A held express waits for the hand to lower, but not forever: past this budget it gives up exactly like --no-wait (draft saved, retry printed). 0 disables waiting. */
+export const HELD_WAIT_BUDGET_MS = parseIntegerEnv('SQUARE_HELD_WAIT_BUDGET_MS', 10 * 60 * 1000);
 export function nowMs() {
     const override = process.env.SQUARE_NOW_MS;
     if (override === undefined)
@@ -184,6 +186,43 @@ export function readCursor(squareState, name, landed = replayLandedAudiences(squ
 export function latestActIndex(acts) {
     return acts.reduce((max, act) => Math.max(max, act.index), -1);
 }
+/**
+ * "Was here" is a claim of presence, so it rides on evidence: the participant's own acts
+ * and seen receipts after their latest join. Anything else — in particular acts merely
+ * not addressed to them — says nothing about where they actually were.
+ */
+export function presenceEvidenceCursor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
+    const recipient = landed.resolveParticipant(name) ?? name;
+    const boundary = landed.lastJoinIndex(recipient) ?? -1;
+    if (boundary < 0)
+        return -1;
+    let evidence = boundary;
+    for (const act of squareState.acts) {
+        if (act.index <= boundary || act.index <= evidence || act.actor === undefined)
+            continue;
+        if (sameName(act.actor, recipient)
+            || squareState.runtime.observations?.[recipient]?.[formatActivityId(act.index)]?.state === 'seen') {
+            evidence = act.index;
+        }
+    }
+    return evidence;
+}
+/** The last public act the participant was verifiably present for, or -1 when there is no evidence. */
+export function presenceAnchor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
+    const recipient = landed.resolveParticipant(name) ?? name;
+    const boundary = landed.lastJoinIndex(recipient) ?? -1;
+    if (boundary < 0)
+        return -1;
+    const evidence = presenceEvidenceCursor(squareState, recipient, landed);
+    for (let i = squareState.acts.length - 1; i >= 0; i--) {
+        const event = squareState.acts[i];
+        if (event.index <= boundary || event.index > evidence)
+            continue;
+        if (event.kind === 'say' || event.kind === 'done')
+            return event.index;
+    }
+    return -1;
+}
 export function freshWatchLease(squareState, name, at = Date.now()) {
     const key = canonicalRuntimeName(squareState, name);
     const lease = watchLease(squareState, key);

package/dist/square-actions.d.ts

@@ -1,37 +1,50 @@
 import { type SquareState } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, OwnershipFenceOptions } from './square-facade.js';
+import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, OperationControl, OwnershipFenceOptions } from './square-facade.js';
 import { type CatchProjection } from './catch-decisions.js';
 import { type HostContext } from './participant-host.js';
 export interface OperationContext extends HostContext {
     readonly wakeTransport?: WakeTransportPort;
 }
 export type { OwnershipFenceOptions };
-export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;
-export declare function join(square: OperationContext, name: string): Promise<{
+export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection, control?: OperationControl): Promise<CatchResult>;
+export declare function join(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
 }>;
 /** End the standing participant and immediately let the caller reclaim the name. */
-export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[]): Promise<{
+export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[], control?: OperationControl): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
     readonly epoch?: number;
 }>;
-export declare function implicitJoin(square: OperationContext, name: string): Promise<{
+export declare function implicitJoin(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly state: 'joined' | 'active' | 'done';
     readonly activity: Activity | null;
 }>;
-export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
 export interface ListenerChangeResult {
     readonly activity: Activity | null;
 }
-export declare function listen(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function ignore(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function listening(square: OperationContext, actor: string): Promise<readonly string[]>;
-export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions): Promise<ExpressResult>;
-/** SessionEnd retires the ended session's routes even when its presence row is gone. */
+export declare function listen(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+export declare function ignore(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+export declare function listening(square: OperationContext, actor: string, control?: OperationControl): Promise<readonly string[]>;
+export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions, control?: OperationControl): Promise<ExpressResult>;
+/**
+ * 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 declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
-export declare function hold(square: OperationContext, name: string, reason?: string): Promise<ExpressResult>;
-export declare function resume(square: OperationContext, name: string): Promise<ExpressResult>;
+/**
+ * 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 declare function retireEndedSessionRoutes(square: OperationContext, sessionId: string): Promise<void>;
+export declare function hold(square: OperationContext, name: string, reason?: string, control?: OperationControl): Promise<ExpressResult>;
+export declare function resume(square: OperationContext, name: string, control?: OperationControl): Promise<ExpressResult>;