@astrosheep/square 0.3.70 → 0.3.72

package/dist/runtime.d.ts

@@ -1,48 +1,21 @@
-import { type ActivityId, type LandedAudienceReplay, type Reach } from './square-core.js';
-import { type StoredAct, type SquareState, type HoldState, type ObservationState, type WatchLease } from './model.js';
+import { type ActivityId } from './square-core.js';
+import { type StoredAct, type WatchLease } from './model.js';
+import type { SquareRead } from './ports.js';
 export declare const WATCH_HEARTBEAT_MS: number;
 export declare const SLEEP_MS: number;
 export declare const STALE_MS: number;
 export declare const WATCH_STALE_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 const FACT_PAGE_SIZE = 100;
 export declare function nowMs(): number;
-/** Pure directed-activity filter. Bell matches every viewer; mentions match by audience. */
-export declare function matchesMentionTarget(act: {
-    body: string;
-    mentions?: readonly string[];
-    reach?: Reach;
-}, mention: string | true): boolean;
-export declare function foldedState(squareState: SquareState): import("./square-core.js").FoldedSquareState;
-export declare function rosterNames(squareState: SquareState): string[];
-export declare function inSquareCount(squareState: SquareState): number;
-export declare function resolveRosterName(squareState: SquareState, name: string): string | undefined;
-export declare function countSays(acts: StoredAct[], name: string): number;
-export declare function sayNumberFor(acts: StoredAct[], target: StoredAct): number;
-/** Shared terminal condition for a participant's watch lifecycle. */
-export declare function watchTerminalStatus(squareState: SquareState, name: string): 'capped' | 'quorum' | undefined;
-export declare function joinedNames(acts: StoredAct[]): Set<string>;
-export declare function isCurrentlyJoined(acts: StoredAct[], name: string): boolean;
-/** Stable index of the recipient's most recent join act, if any. */
-export declare function lastJoinIndex(acts: StoredAct[], name: string): number | undefined;
-export declare function actStableIndex(act: StoredAct): number;
+export declare function rosterNames(facts: SquareRead): string[];
+export declare function inSquareCount(facts: SquareRead): number;
 export declare function actId(actOrIndex: StoredAct | number): ActivityId;
-export declare function currentHold(acts: StoredAct[]): HoldState;
-export declare function publicActs(acts: StoredAct[]): Array<Extract<StoredAct, {
-    kind: 'say' | 'done';
-}>>;
-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;
-/**
- * The last public act the participant was verifiably present for, or -1 when there is no evidence.
- *
- * "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 presenceAnchor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
-export declare function freshWatchLease(squareState: SquareState, name: string, at?: number): WatchLease | undefined;
-export declare function writeWatchLease(squareState: SquareState, name: string, lease: WatchLease): void;
-export declare function removeWatchLease(squareState: SquareState, name: string, leaseId: string): boolean;
+export declare function watchTerminalStatus(facts: SquareRead, name: string): 'capped' | 'quorum' | undefined;
+/** A continuous prefix stops at the first unseen historical audience edge after join. */
+export declare function readCursor(facts: SquareRead, name: string): number;
+/** Presence rides on own activity or exact receipts, not nonaddressed cursor progress. */
+export declare function presenceAnchor(facts: SquareRead, name: string): number;
+export declare function freshWatchLease(facts: SquareRead, name: string, at?: number): WatchLease | undefined;

package/dist/runtime.js

@@ -1,13 +1,12 @@
-import { audienceIncludes, audienceOf, fold, formatActivityId, replayLandedAudiences } from './square-core.js';
-import { SquareError, findParticipantName, nameKey, sameName, } from './model.js';
+import { formatActivityId } from './square-core.js';
+import { SquareError, sameName } from './model.js';
 function parseIntegerEnv(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined)
         return fallback;
     const value = parseInt(raw, 10);
-    if (!Number.isFinite(value) || value <= 0) {
+    if (!Number.isFinite(value) || value <= 0)
         throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
-    }
     return value;
 }
 export const WATCH_HEARTBEAT_MS = parseIntegerEnv('SQUARE_WATCH_HEARTBEAT_MS', 60000);
@@ -16,177 +15,47 @@ export const STALE_MS = parseIntegerEnv('SQUARE_WATCH_QUIET_MS', 300000);
 export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', 180000);
 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 const FACT_PAGE_SIZE = 100;
 export function nowMs() {
     const override = process.env.SQUARE_NOW_MS;
     if (override === undefined)
         return Date.now();
     const value = parseInt(override, 10);
-    if (!Number.isFinite(value)) {
+    if (!Number.isFinite(value))
         throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
-    }
     return value;
 }
-/** Pure directed-activity filter. Bell matches every viewer; mentions match by audience. */
-export function matchesMentionTarget(act, mention) {
-    const audience = audienceOf(act);
-    if (mention === true)
-        return audience.kind === 'bell' || audience.names.length > 0;
-    return audienceIncludes(audience, mention);
-}
-export function foldedState(squareState) {
-    return fold(squareState.acts);
-}
-export function rosterNames(squareState) {
-    return foldedState(squareState).participants.map((participant) => participant.name);
-}
-export function inSquareCount(squareState) {
-    return foldedState(squareState).joined.length;
-}
-export function resolveRosterName(squareState, name) {
-    return findParticipantName(rosterNames(squareState), name);
-}
-export function countSays(acts, name) {
-    return acts.filter((act) => act.kind === 'say' && sameName(act.actor, name)).length;
-}
-export function sayNumberFor(acts, target) {
-    if (target.kind !== 'say')
-        throw new Error('sayNumberFor only applies to say acts');
-    let number = 0;
-    for (const act of acts) {
-        if (act.kind === 'say' && sameName(act.actor, target.actor))
-            number++;
-        if (act === target)
-            return number;
-        if (target.index !== undefined && act.index === target.index)
-            return number;
-    }
-    throw new Error('target say act is not present in act history');
-}
-/** Shared terminal condition for a participant's watch lifecycle. */
-export function watchTerminalStatus(squareState, name) {
-    if (squareState.hardCap !== null && countSays(squareState.acts, name) >= squareState.hardCap)
+export function rosterNames(facts) { return facts.roster().map((participant) => participant.name); }
+export function inSquareCount(facts) { return facts.roster().filter((participant) => participant.joined).length; }
+export function actId(actOrIndex) { return formatActivityId(typeof actOrIndex === 'number' ? actOrIndex : actOrIndex.index); }
+export function watchTerminalStatus(facts, name) {
+    const cap = facts.header().hardCap;
+    if (cap !== null && (facts.participant(name)?.sayCount ?? 0) >= cap)
         return 'capped';
-    const done = new Set(fold(squareState.acts).done.map((participant) => nameKey(participant)));
-    done.delete(nameKey(name));
-    const peers = rosterNames(squareState).filter((participant) => !sameName(participant, name));
-    return peers.length > 0 && peers.every((peer) => done.has(nameKey(peer))) ? 'quorum' : undefined;
-}
-export function joinedNames(acts) {
-    return new Set(acts.filter((act) => act.kind === 'join').map((act) => nameKey(act.actor)));
-}
-export function isCurrentlyJoined(acts, name) {
-    return fold(acts).participants.some((participant) => sameName(participant.name, name) && participant.joined);
-}
-/** Stable index of the recipient's most recent join act, if any. */
-export function lastJoinIndex(acts, name) {
-    let last;
-    for (const act of acts) {
-        if (act.kind === 'join' && sameName(act.actor, name))
-            last = actStableIndex(act);
-    }
-    return last;
-}
-export function actStableIndex(act) {
-    if (act.index === undefined)
-        throw new Error(`act ${act.kind} is missing a stable index`);
-    return act.index;
-}
-export function actId(actOrIndex) {
-    const index = typeof actOrIndex === 'number' ? actOrIndex : actStableIndex(actOrIndex);
-    return formatActivityId(index);
-}
-function canonicalRuntimeName(squareState, name) {
-    return resolveRosterName(squareState, name) ?? name;
-}
-export function currentHold(acts) {
-    const hold = fold(acts).hold;
-    return hold.active ? { active: true, at: hold.at, reason: hold.reason } : { active: false };
-}
-export function publicActs(acts) {
-    return acts.filter((act) => act.kind === 'say' || act.kind === 'done');
-}
-export function recordObservation(squareState, name, index, state, at = Date.now()) {
-    if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(at))
-        return false;
-    const key = canonicalRuntimeName(squareState, name);
-    const id = formatActivityId(index);
-    const current = squareState.runtime.observations[key]?.[id];
-    if (current?.state === 'seen' || (current?.state === state && current.at >= at))
-        return false;
-    const next = {
-        state: 'seen',
-        at: Math.max(current?.at ?? -Infinity, at),
-    };
-    ((squareState.runtime.observations ??= {})[key] ??= {})[id] = next;
-    return true;
-}
-export function readCursor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
-    const recipient = landed.resolveParticipant(name) ?? name;
-    const boundary = landed.lastJoinIndex(recipient) ?? -1;
-    let cursor = boundary;
-    for (const act of squareState.acts) {
-        if (act.index <= boundary || act.kind === 'read' || act.actor === undefined)
-            continue;
-        if (sameName(act.actor, recipient)) {
-            cursor = act.index;
-            continue;
-        }
-        if (!landed.includes(act, recipient)) {
-            cursor = act.index;
-            continue;
-        }
-        if (squareState.runtime.observations?.[recipient]?.[formatActivityId(act.index)]?.state !== 'seen')
-            break;
-        cursor = act.index;
-    }
-    return cursor;
-}
-/**
- * The last public act the participant was verifiably present for, or -1 when there is no evidence.
- *
- * "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 presenceAnchor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
-    const recipient = landed.resolveParticipant(name) ?? name;
-    const boundary = landed.lastJoinIndex(recipient) ?? -1;
+    const peers = facts.roster().filter((participant) => !sameName(participant.name, name));
+    return peers.length > 0 && peers.every((peer) => peer.done) ? 'quorum' : undefined;
+}
+/** A continuous prefix stops at the first unseen historical audience edge after join. */
+export function readCursor(facts, name) {
+    const boundary = facts.participant(name)?.lastJoinIndex ?? -1;
+    const block = facts.directed(name, { afterIndex: boundary, unseenOnly: true }, { edge: 'oldest', limit: 1 }).items[0]?.index;
+    const last = facts.activityHeads({
+        afterIndex: boundary, ...(block === undefined ? {} : { beforeIndex: block }), actorRequired: true,
+        kinds: ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore'],
+    }, { edge: 'newest', limit: 1 }).items[0]?.index;
+    return Math.max(boundary, last ?? boundary);
+}
+/** Presence rides on own activity or exact receipts, not nonaddressed cursor progress. */
+export function presenceAnchor(facts, name) {
+    const boundary = facts.participant(name)?.lastJoinIndex ?? -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;
-        }
-    }
-    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 = squareState.runtime.leases[key];
-    if (lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS)
-        return undefined;
-    return lease;
-}
-export function writeWatchLease(squareState, name, lease) {
-    squareState.runtime.leases[canonicalRuntimeName(squareState, name)] = lease;
+    const own = facts.activityHeads({ afterIndex: boundary, actors: [name] }, { edge: 'newest', limit: 1 }).items[0]?.index;
+    const evidence = Math.max(boundary, own ?? boundary, facts.receiptFacts(name, boundary).latestActorActivityIndex ?? boundary);
+    return facts.activityHeads({ afterIndex: boundary, throughIndex: evidence, kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0]?.index ?? -1;
 }
-export function removeWatchLease(squareState, name, leaseId) {
-    const key = canonicalRuntimeName(squareState, name);
-    if (squareState.runtime.leases[key]?.leaseId !== leaseId)
-        return false;
-    delete squareState.runtime.leases[key];
-    return true;
+export function freshWatchLease(facts, name, at = Date.now()) {
+    const lease = facts.lease(name);
+    return lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS ? undefined : lease;
 }

package/dist/square-actions.d.ts

@@ -1,21 +1,24 @@
-import { type SquareState } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, OperationControl, OwnershipFenceOptions } from './square-facade.js';
-import { type CatchProjection } from './catch-decisions.js';
+import type { Activity, CatchOptions, ExpressOptions, ExpressResult, ExpressionObservation, ListenerChangeResult, OperationControl, OwnershipFenceOptions } from './square-facade.js';
+import { type CatchSelection } 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, control?: OperationControl): Promise<CatchResult>;
+export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, control?: OperationControl): Promise<CatchSelection>;
+export declare function catchUp(square: OperationContext, name: string, options: CatchOptions, control: OperationControl | undefined, leaseId: string): Promise<CatchSelection | null>;
 export declare function join(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
+    readonly participantCount: number;
+    readonly reconnected: boolean;
 }>;
-/** End the standing participant and immediately let the caller reclaim the name. */
+/** Takeover holds the host CAS fence across the single done+join artifact transaction. */
 export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[], control?: OperationControl): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
+    readonly participantCount: number;
     readonly epoch?: number;
 }>;
 export declare function implicitJoin(square: OperationContext, name: string, control?: OperationControl): Promise<{
@@ -23,28 +26,15 @@ export declare function implicitJoin(square: OperationContext, name: string, con
     readonly state: 'joined' | 'active' | 'done';
     readonly activity: Activity | null;
 }>;
-export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
-export interface ListenerChangeResult {
-    readonly activity: Activity | null;
+export interface ExpressCommittedResult extends ExpressResult {
+    readonly observation: ExpressionObservation;
 }
+export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressCommittedResult>;
 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>;
-/**
- * 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>;