@astrosheep/square 0.3.41 → 0.3.43

package/dist/square-actions.js

@@ -1,10 +1,11 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin, resolveKnownName } from './decisions.js';
-import { nameKey, SquareError } from './model.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 { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
+import { claimSessionParticipant, claimSessionTakeover, readParticipantOwner, sessionOwnsParticipant, withOwnershipClaimLock } from './registry.js';
+import { applyWakeRouteToState, defaultWakeRouteCapabilities, dropParticipantWakeRoutesFromState, dropSessionWakeRoutesFromState, publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, sessionCanEndParticipant, ROUTE_FRESH_MS } from './routes.js';
 function processIdentity(env) {
     const choices = [
         [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
@@ -13,33 +14,76 @@ function processIdentity(env) {
     const found = choices.find(([session]) => session?.trim());
     return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
 }
-async function publishIdentityRoute(context, participant) {
+async function identityRouteDraft(context, participant) {
     if (context.location === undefined || context.location === 'memory')
-        return;
+        return undefined;
     const identity = processIdentity(context.env ?? process.env);
-    if (context.hostLedger === undefined)
+    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
+    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
+    return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+}
+async function currentOwnerEpoch(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return undefined;
+    const owner = await readParticipantOwner(context.location, participant, context.env ?? process.env);
+    return owner?.epoch;
+}
+async function publishIdentityRoute(context, participant, epoch) {
+    if (context.location === undefined || context.location === 'memory')
         return;
+    const identity = processIdentity(context.env ?? process.env);
     const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
-    const capabilities = await defaultWakeRouteCapabilities(context.hostLedger);
-    const route = await resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
+    const route = resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
     if (route === undefined)
         return;
-    await publishWakeRoute(context.artifact, route, { at: context.clock() }).catch(() => undefined);
+    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
+    await publishWakeRoute(context.artifact, { ...route, ...(ownerEpoch === undefined ? {} : { epoch: ownerEpoch }) }, { at: context.clock(), requireCurrentSession: true }).catch(() => undefined);
 }
-async function retireIdentityRoute(context, participant) {
+async function retireIdentityRoute(context, participant, expectedEpoch) {
     if (context.location === undefined || context.location === 'memory')
         return;
     const identity = processIdentity(context.env ?? process.env);
-    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }).catch(() => undefined);
+    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }, expectedEpoch === undefined ? {} : { expectedEpoch }).catch(() => undefined);
+}
+async function assertLiveOwner(context, participant, expectedEpoch) {
+    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+        return true;
+    const identity = processIdentity(context.env ?? process.env);
+    // Library callers without a harness session are not ownership-fenced unless an epoch was supplied.
+    if (identity.channel === 'unknown' && expectedEpoch === undefined)
+        return true;
+    return sessionOwnsParticipant(context.location, participant, identity.session, context.env ?? process.env, expectedEpoch);
 }
 /** Presence is best effort and runs only after the artifact mutation commits. */
-async function ensureLocalPresence(context, participant) {
+async function ensureLocalPresence(context, participant, epoch) {
     if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
         return;
     const identity = processIdentity(context.env ?? process.env);
+    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
+    const now = context.clock();
+    // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
+    try {
+        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, scopes: ['local'], now });
+        if (existing.some((row) => row.channel === identity.channel
+            && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
+            && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
+            return;
+    }
+    catch { /* fall through to the best-effort ensure below */ }
     const result = await context.hostLedger.ensurePresence({
-        location: context.location, participant, session: identity.session, channel: identity.channel, updatedAt: context.clock(),
-    }, 'local').catch((error) => ({ status: 'degraded', record: { location: context.location, participant, session: identity.session, channel: identity.channel }, error }));
+        location: context.location,
+        participant,
+        session: identity.session,
+        channel: identity.channel,
+        // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
+        updatedAt: Date.now(),
+        ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
+    }, 'local').catch((error) => ({
+        status: 'degraded',
+        record: { location: context.location, participant, session: identity.session, channel: identity.channel },
+        error,
+    }));
     if (result.status === 'degraded')
         process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
 }
@@ -79,7 +123,17 @@ export async function catchUp(square, name, options = {}, project) {
             };
         }
         const remaining = deadline - Date.now();
-        if (remaining <= 0 || !await square.artifact.changed(attempt.version, remaining)) {
+        if (remaining <= 0) {
+            return { activities: [], consumedThrough: attempt.decision.consumedThrough, idleExpired: true, remaining: 0 };
+        }
+        // Publication above is a semantic no-op while the route and presence stay unchanged and
+        // 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;
+        if (baseline !== attempt.version)
+            continue;
+        if (!await square.artifact.changed(baseline, remaining)) {
             return { activities: [], consumedThrough: attempt.decision.consumedThrough, idleExpired: true, remaining: 0 };
         }
     }
@@ -118,49 +172,140 @@ function parseRequiredActivityId(id) {
     return index;
 }
 export async function join(square, name) {
+    // Rejected validation must not perform an ownership claim.
+    validateName(name);
+    const preview = await square.artifact.read();
+    const previewDecision = decideJoin(preview.state, name, square.clock());
+    if (previewDecision.joinAct === undefined) {
+        // An active artifact participant is idempotent only for its current session.
+        // A different owner must still pass through the registry CAS so it is refused
+        // instead of silently reconnecting as a foreign session.
+        if (square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
+            const identity = processIdentity(square.env ?? process.env);
+            const owner = await readParticipantOwner(square.location, previewDecision.joinedName, square.env ?? process.env);
+            if (owner === undefined) {
+                // Keep the claim path for an active artifact whose ledger owner is not
+                // 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.
+            }
+            else {
+                return { name: previewDecision.joinedName, activity: null };
+            }
+        }
+        else {
+            return { name: previewDecision.joinedName, activity: null };
+        }
+    }
+    let epoch;
+    if (square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
+        const claim = await claimSessionParticipant(square.location, name, square.env ?? process.env);
+        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)
+        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') } };
     });
-    await ensureLocalPresence(square, committed.name);
-    await publishIdentityRoute(square, committed.name);
+    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) {
-    const now = square.clock();
-    const committed = await square.artifact.transact((state) => {
-        const joinedName = resolveKnownName(state, name);
-        const done = coreDone(state, joinedName, '', now);
-        const storedDone = committedActivity(storeActs(state, [done]), 'kick');
-        const decision = decideJoin(state, joinedName, now);
-        if (decision.joinAct === undefined)
-            throw new SquareError('already_joined', `${participantIdentity(joinedName)} could not be reclaimed`);
-        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] } };
-    });
+export async function takeover(square, name, _oldSessionIds = []) {
+    // Rejected validation must not perform an ownership claim.
+    validateName(name);
+    const commitLifecycle = async () => {
+        const now = square.clock();
+        const committed = await square.artifact.transact((state) => {
+            const joinedName = resolveKnownName(state, name);
+            const done = coreDone(state, joinedName, '', now);
+            const storedDone = committedActivity(storeActs(state, [done]), 'kick');
+            const decision = decideJoin(state, joinedName, now);
+            if (decision.joinAct === undefined)
+                throw new SquareError('already_joined', `${participantIdentity(joinedName)} could not be reclaimed`);
+            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] } };
+        });
+        return committed;
+    };
+    if (square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
+        const env = square.env ?? process.env;
+        // 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 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);
+        // 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) => {
+            const committed = await commitLifecycle();
+            await ensureLocalPresence(square, committed.name, claim.epoch);
+            await publishIdentityRoute(square, committed.name, claim.epoch);
+            return committed;
+        });
+        if (outcome.status === 'busy')
+            throw new SquareError('already_joined', `${participantIdentity(name)} is already bound to another session`);
+        return { name: outcome.result.name, activities: outcome.result.stored.map(exposeActivity), epoch: outcome.epoch };
+    }
+    const committed = await commitLifecycle();
+    await ensureLocalPresence(square, committed.name);
+    await publishIdentityRoute(square, committed.name);
     return { name: committed.name, activities: committed.stored.map(exposeActivity) };
 }
 export async function implicitJoin(square, name) {
     const now = square.clock();
+    const route = await identityRouteDraft(square, name);
     const committed = await square.artifact.transact((state) => {
         const decision = decideImplicitJoin(state, name, now);
+        if (decision.state === 'done') {
+            if (square.location !== undefined && square.location !== 'memory')
+                dropSessionWakeRoutesFromState(state, square.location, processIdentity(square.env ?? process.env).session);
+            return { state, result: { name: decision.joinedName, state: decision.state, stored: null } };
+        }
         if (decision.joinAct === undefined)
             return { result: { name: decision.joinedName, state: decision.state, stored: null } };
+        if (square.location !== undefined && square.location !== 'memory')
+            dropParticipantWakeRoutesFromState(state, square.location, decision.joinedName);
+        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') } };
     });
     await ensureLocalPresence(square, committed.name);
     if (committed.state === 'done')
         await retireIdentityRoute(square, committed.name);
-    else
+    else if (committed.stored !== null)
         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 = {}) {
+    if (!await assertLiveOwner(square, name)) {
+        throw new SquareError('already_joined', `${participantIdentity(name)} is already bound to another session`);
+    }
     const now = square.clock();
     const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
     const committed = await square.artifact.transact((state) => {
@@ -206,16 +351,71 @@ async function landListenerChange(square, verb, actor, target) {
 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 = '') {
-    const now = square.clock();
-    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) };
-    });
+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 () => {
+        if (verb === 'done' && !await assertLiveOwner(square, actor, fence.expectedEpoch)) {
+            throw new SquareError('already_done', `${participantIdentity(actor)} is already bound to another session`);
+        }
+        const now = square.clock();
+        return 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 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);
+        await retireIdentityRoute(square, actor, fence.expectedEpoch);
     return { activity: exposeActivity(stored) };
 }
-export function done(square, name, body = '') { return landCore(square, 'done', name, body); }
+export function done(square, name, body = '', fence = {}) {
+    return landCore(square, 'done', name, body, fence);
+}
+/** SessionEnd retires the ended session's routes even when its presence row is gone. */
+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;
+        if (location !== undefined && location !== 'memory' && square.hostLedger !== undefined) {
+            try {
+                const bindings = await square.hostLedger.listPresence({ location, participant: name, scopes: ['user', 'local'], now });
+                currentSessionId = bindings.find((binding) => binding.session !== sessionId)?.session
+                    ?? bindings.toSorted((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0))[0]?.session;
+                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 */ }
+        }
+        return square.artifact.transact((state) => {
+            let committed = null;
+            if (location !== undefined && location !== 'memory' && ownerMatches && sessionCanEndParticipant(state, location, name, sessionId, currentSessionId)) {
+                try {
+                    committed = committedActivity(storeActs(state, [coreDone(state, name, '', now)]), 'done');
+                }
+                catch (error) {
+                    if (!isSquareError(error) || (error.code !== 'already_done' && error.code !== 'not_joined'))
+                        throw error;
+                }
+            }
+            if (location !== undefined && location !== 'memory')
+                dropSessionWakeRoutesFromState(state, location, sessionId);
+            return { state, result: committed };
+        });
+    };
+    const fenced = location !== undefined && location !== 'memory' && square.hostLedger !== undefined;
+    const stored = fenced
+        ? await withOwnershipClaimLock(square.env ?? process.env, run)
+        : 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); }

package/dist/square-facade.d.ts

@@ -86,6 +86,10 @@ export interface SquareBuildInput extends SquareSource {
     wakeTransport?: WakeTransportPort;
     env?: NodeJS.ProcessEnv;
 }
+/** Optional fence for owner-scoped lifecycle actions. */
+export interface OwnershipFenceOptions {
+    readonly expectedEpoch?: number;
+}
 export interface Participant {
     readonly name: string;
     express(body: string, options?: ExpressOptions): Promise<ExpressResult>;

package/dist/square-projections.d.ts

@@ -30,6 +30,13 @@ export declare function projectPresentationEvidence(input: {
     readonly activity?: string;
     readonly now?: number;
 }): Promise<readonly PresentationEvidenceProjection[]>;
+/** Successful boundary output, including a clipped preview, suppresses awareness wake. */
+export declare function presentationSuppressesWake(evidence: readonly Pick<PresentationEvidenceProjection, 'outcome'>[]): boolean;
+/** The most recently published session owns wake eligibility for its participant. */
+export declare function currentSessionBindings<T extends {
+    readonly participant: string;
+    readonly updatedAt?: number;
+}>(bindings: readonly T[]): T[];
 export interface WakeAttempt {
     readonly at: number;
     readonly attention: {

package/dist/square-projections.js

@@ -50,6 +50,19 @@ export async function projectPresentationEvidence(input) {
     const rows = await input.hostLedger.listEvidence({ kind: 'presentation', location: input.location, participant: input.participant, session: input.sessionId, activity: input.activity, now: input.now });
     return rows.map((row) => ({ location: row.location, participant: row.participant, sessionId: row.session, activity: row.activity, outcome: row.outcome, ...(row.at === undefined ? {} : { at: row.at }) }));
 }
+/** Successful boundary output, including a clipped preview, suppresses awareness wake. */
+export function presentationSuppressesWake(evidence) {
+    return evidence.some((row) => row.outcome === 'clipped' || row.outcome === 'presented');
+}
+/** The most recently published session owns wake eligibility for its participant. */
+export function currentSessionBindings(bindings) {
+    const latest = new Map();
+    for (const binding of bindings) {
+        const participant = nameKey(binding.participant);
+        latest.set(participant, Math.max(latest.get(participant) ?? Number.NEGATIVE_INFINITY, binding.updatedAt ?? 0));
+    }
+    return bindings.filter((binding) => (binding.updatedAt ?? 0) === latest.get(nameKey(binding.participant)));
+}
 export function terminalWakeEvidence(attempts) { return attempts.findLast((attempt) => attempt.outcome === 'accepted'); }
 export function isWakeRouteAttemptable(route, attempts) {
     if (terminalWakeEvidence(attempts) !== undefined)
@@ -80,13 +93,13 @@ export async function projectWakeEvidenceFromState(input) {
     const presentedRows = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: canonicalLocation, now: input.now });
     return {
         evidence(recipient, actIndex) {
-            const recipientBindings = bindings.filter((binding) => nameKey(binding.participant) === nameKey(recipient));
+            const recipientBindings = currentSessionBindings(bindings.filter((binding) => nameKey(binding.participant) === nameKey(recipient)));
             const routes = recipientBindings.flatMap((binding) => binding.route === undefined ? [] : [binding.route]);
             const attempts = recipientBindings.flatMap((binding) => attemptsByBinding.get(JSON.stringify([nameKey(recipient), actIndex, binding.sessionId])) ?? []);
             const terminal = terminalWakeEvidence(attempts);
-            const presented = presentedRows.some((row) => row.activity === formatActivityId(actIndex) && row.participant.toLocaleLowerCase() === recipient.toLocaleLowerCase() && recipientBindings.some((binding) => binding.sessionId === row.sessionId));
+            const presented = presentedRows.some((row) => row.activity === formatActivityId(actIndex) && row.participant.toLocaleLowerCase() === recipient.toLocaleLowerCase() && recipientBindings.some((binding) => binding.sessionId === row.sessionId) && presentationSuppressesWake([row]));
             return { delivered: delivery.isSeen(recipient, actIndex), presented, attempts, ...(terminal === undefined ? {} : { terminal }), attemptableRoutes: terminal === undefined ? routes.filter((route) => isWakeRouteAttemptable(route, attempts)) : [] };
         },
     };
 }
-export function wakeIsEligible(evidence) { return !evidence.delivered && evidence.terminal === undefined && evidence.attemptableRoutes.length > 0; }
+export function wakeIsEligible(evidence) { return !evidence.delivered && !evidence.presented && evidence.terminal === undefined && evidence.attemptableRoutes.length > 0; }

package/dist/square-storage.js

@@ -1,30 +1,70 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import fs from 'node:fs';
+import path from 'node:path';
 import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, writeSquareFile, } from './artifact.js';
 import { withFileLock } from './file-lock.js';
-import { LOCK_RETRY_MS, LOCK_STALE_MS } from './runtime.js';
+import { LOCK_RETRY_MS } from './runtime.js';
 /**
  * The only production module allowed to cross the .square byte boundary.
  * Consumers receive a SquareState and never need to know which codec or lock
  * protects it.
  */
 export { createSquareState, };
+async function canonicalPath(squarePath) {
+    const absolute = path.resolve(squarePath);
+    try {
+        return await fs.promises.realpath(absolute);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        const parent = await fs.promises.realpath(path.dirname(absolute)).catch(() => path.dirname(absolute));
+        return path.join(parent, path.basename(absolute));
+    }
+}
+async function squareFileExists(squarePath) {
+    try {
+        await fs.promises.access(squarePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function withSquareFileReadLock(squarePath, fn) {
+    if (!await squareFileExists(squarePath))
+        return fn();
+    try {
+        return await withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, createParent: false }, fn);
+    }
+    catch (error) {
+        if (!await squareFileExists(squarePath))
+            return fn();
+        throw error;
+    }
+}
 export async function readSquareFile(squarePath) {
-    return withSquareFileLock(squarePath, () => loadSquare(squarePath));
+    const canonical = await canonicalPath(squarePath);
+    return withSquareFileReadLock(canonical, () => loadSquare(canonical));
 }
 export async function probeSquareFile(squarePath) {
     if (!squarePath.endsWith('.square'))
         return undefined;
-    return withSquareFileLock(squarePath, () => probeSquare(squarePath));
+    const canonical = await canonicalPath(squarePath);
+    return withSquareFileReadLock(canonical, () => probeSquare(canonical));
 }
 export async function diagnoseSquareFile(squarePath) {
-    return withSquareFileLock(squarePath, () => diagnoseArtifactFile(squarePath));
+    const canonical = await canonicalPath(squarePath);
+    return withSquareFileReadLock(canonical, () => diagnoseArtifactFile(canonical));
 }
 export async function writeSquareSnapshot(squarePath, squareState) {
-    await writeSquareFile(squarePath, squareState);
+    await writeSquareFile(await canonicalPath(squarePath), squareState);
 }
-export function withSquareFileLock(squarePath, fn) {
-    return withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, fn);
+export async function withSquareFileLock(squarePath, fn) {
+    const canonical = await canonicalPath(squarePath);
+    return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, fn);
 }
 function cloneState(squareState) {
     return structuredClone(squareState);
@@ -119,8 +159,13 @@ export function createFileCell(squarePath) {
     let version = 0;
     let fingerprint;
     let cached;
+    let canonicalSquarePath;
+    async function storagePath() {
+        canonicalSquarePath ??= await canonicalPath(squarePath);
+        return canonicalSquarePath;
+    }
     async function observe() {
-        const next = await fileFingerprint(squarePath);
+        const next = await fileFingerprint(await storagePath());
         if (fingerprint === undefined) {
             fingerprint = next;
         }
@@ -135,21 +180,22 @@ export function createFileCell(squarePath) {
         const observed = await observe();
         if (cached?.fingerprint === observed)
             return cloneState(cached.state);
-        const decoded = await loadSquare(squarePath);
+        const decoded = await loadSquare(await storagePath());
         cached = { fingerprint: observed, state: cloneState(decoded) };
         return cloneState(cached.state);
     }
     return {
         async transact(fn) {
             assertCellOpen(closed);
-            return withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, async () => {
+            const canonical = await storagePath();
+            return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, async () => {
                 assertCellOpen(closed);
                 const current = await currentStateUnderLock();
                 const working = cloneState(current);
                 const outcome = fn(working, version);
                 if (outcome.state !== undefined) {
-                    await writeSquareSnapshot(squarePath, outcome.state);
-                    fingerprint = await fileFingerprint(squarePath);
+                    await writeSquareFile(canonical, outcome.state);
+                    fingerprint = await fileFingerprint(canonical);
                     cached = { fingerprint, state: cloneState(outcome.state) };
                     version += 1;
                 }
@@ -158,7 +204,7 @@ export function createFileCell(squarePath) {
         },
         async read() {
             assertCellOpen(closed);
-            return withSquareFileLock(squarePath, async () => {
+            return withSquareFileReadLock(await storagePath(), async () => {
                 assertCellOpen(closed);
                 return { state: await currentStateUnderLock(), version };
             });

package/dist/square-wiring.d.ts

@@ -1,4 +1,4 @@
-import type { Activity, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
+import type { Activity, ExpressResult, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
 import type { Participant, SquareAtInput, SquareBuildInput } from './square-facade.js';
 export declare class Square {
     readonly location: string;
@@ -24,6 +24,7 @@ export declare class Square {
     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>;
 }
 export declare function markBoundarySeen(squarePath: string, name: string, actIndexes: readonly number[], at?: number): Promise<void>;
 export declare function openParticipant(input: SquareAtInput, name: string): Promise<{

package/dist/square-wiring.js

@@ -1,6 +1,6 @@
 import { closeOpenSquare } from './open-square.js';
 import { buildMemorySquare, buildSquare, openSquare } from './square-file-adapter.js';
-import { catchUp, done, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, } from './square-actions.js';
+import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, } from './square-actions.js';
 import { markBoundarySeen as recordBoundarySeen } from './presence.js';
 import { history, participantHistory, participants, resolveParticipant, snapshot } from './views.js';
 import { currentParticipant } from './views.js';
@@ -102,6 +102,7 @@ export class Square {
     }
     close() { return closeOpenSquare(this.square); }
     reconcileBinding() { return reconcileBindingOperation({ artifact: this.square.artifact, hostLedger: this.square.hostLedger, location: this.location }); }
+    endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.context, name, sessionId, expectedEpoch); }
 }
 export function markBoundarySeen(squarePath, name, actIndexes, at) {
     return recordBoundarySeen(squarePath, name, actIndexes, at);

package/dist/state-cell.d.ts

@@ -4,7 +4,10 @@ export interface StateCell {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    }): Promise<R>;
+    } | Promise<{
+        state?: SquareState;
+        result: R;
+    }>): Promise<R>;
     read(): Promise<{
         state: SquareState;
         version: number;

package/dist/wake-attempts.js

@@ -64,7 +64,10 @@ export async function recordWakeAttempt(attempt, env = process.env) {
         throw new Error(`${value.outcome} wake attempts require a transport signature.`);
     }
     const safe = redact(value, env.PASEO_PASSWORD);
-    await ledger(env).appendWakeAttempt({ location: safe.attention.squarePath, participant: safe.attention.recipient, session: safe.session ?? safe.signature ?? `route:${safe.routeKind}`, activity: formatActivityId(safe.attention.actIndex), kind: 'wake', outcome: safe.outcome, routeKind: safe.routeKind, signature: safe.signature, attemptN: safe.attemptN, message: safe.message, diagnostic: safe.diagnostic, at: safe.at });
+    const session = safe.session ?? safe.signature ?? `route:${safe.routeKind}`;
+    const claim = await ledger(env).claimEvidence({ location: safe.attention.squarePath, participant: safe.attention.recipient, session, activity: formatActivityId(safe.attention.actIndex), kind: 'wake', leaseMs: 5000 });
+    if (claim.status === 'acquired')
+        await ledger(env).appendWakeAttempt({ location: safe.attention.squarePath, participant: safe.attention.recipient, session, activity: formatActivityId(safe.attention.actIndex), kind: 'wake', outcome: safe.outcome, routeKind: safe.routeKind, signature: safe.signature, attemptN: safe.attemptN, message: safe.message, diagnostic: safe.diagnostic, at: safe.at, claimToken: claim.claimToken });
     return value;
 }
 export async function recordRecoveredUnknown(attention, lease, env = process.env, at = Date.now()) {
@@ -94,7 +97,10 @@ export async function recordRecoveredUnknown(attention, lease, env = process.env
             attemptN: lease.attemptN,
             message: 'The notification worker ended after dispatch began; transport acceptance is unknown.',
         };
-        await ledger(env).appendWakeAttempt({ location: attention.squarePath, participant: attention.recipient, session: lease.session ?? value.signature, activity: formatActivityId(attention.actIndex), kind: 'wake', outcome: 'unknown', routeKind, signature: value.signature, attemptN: value.attemptN, message: value.message, at });
+        const session = lease.session ?? value.signature;
+        const claim = await ledger(env).claimEvidence({ location: attention.squarePath, participant: attention.recipient, session, activity: formatActivityId(attention.actIndex), kind: 'wake', leaseMs: 5000 });
+        if (claim.status === 'acquired')
+            await ledger(env).appendWakeAttempt({ location: attention.squarePath, participant: attention.recipient, session, activity: formatActivityId(attention.actIndex), kind: 'wake', outcome: 'unknown', routeKind, signature: value.signature, attemptN: value.attemptN, message: value.message, at, claimToken: claim.claimToken });
         return value;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {