@astrosheep/square 0.3.61 → 0.3.62

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: {

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)

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>;