@astrosheep/square 0.3.72 → 0.3.74

package/dist/sqlite-transaction.js

@@ -0,0 +1,72 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+function abort(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('SQLite operation aborted');
+}
+function isBusy(error) {
+    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
+}
+/** Yield rather than blocking the process while another connection owns SQLite. */
+export async function retrySqliteBusy(operation, signal, retryMs = 25) {
+    for (;;) {
+        abort(signal);
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!isBusy(error))
+                throw error;
+            try {
+                await sleep(typeof retryMs === 'function' ? retryMs() : retryMs, undefined, { signal });
+            }
+            catch (error) {
+                abort(signal);
+                throw error;
+            }
+        }
+    }
+}
+/** Acquisition may retry; COMMIT retries retain the callback's result and transaction. */
+export async function inSqliteTransaction(db, write, validate, change, signal) {
+    let begun = false, backoffMs = 25;
+    // Spread writer contenders out without delaying a writer that already owns the lock.
+    const writerDelay = () => {
+        const delay = 1 + Math.floor(Math.random() * backoffMs);
+        backoffMs = Math.min(100, backoffMs * 2);
+        return delay;
+    };
+    try {
+        const validated = await retrySqliteBusy(() => {
+            db.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN');
+            begun = true;
+            try {
+                return validate();
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                begun = false;
+                throw error;
+            }
+        }, signal, write ? writerDelay : 25);
+        abort(signal);
+        const result = change(validated);
+        if (result !== null && (typeof result === 'object' || typeof result === 'function') && typeof result.then === 'function') {
+            void Promise.resolve(result).catch(() => undefined);
+            throw new TypeError('SQLite transaction callbacks must be synchronous.');
+        }
+        // A busy commit still owns the writer lock. Retry promptly once readers leave;
+        // acquisition contenders keep the longer backoff above.
+        await retrySqliteBusy(() => db.exec('COMMIT'), signal, 1);
+        begun = false;
+        return result;
+    }
+    catch (error) {
+        if (begun) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* retain original failure */ }
+        }
+        throw error;
+    }
+}

package/dist/square-actions.d.ts

@@ -8,7 +8,9 @@ export interface OperationContext extends HostContext {
 export type { OwnershipFenceOptions };
 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<{
+export declare function join(square: OperationContext, name: string, control?: OperationControl, admission?: {
+    readonly requireKnown?: boolean;
+}): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
     readonly participantCount: number;

package/dist/square-actions.js

@@ -2,7 +2,7 @@ import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume,
 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 { decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
 import { inSquareCount } from './runtime.js';
 import { claimSessionParticipant, claimSessionTakeover, presenceEpoch, releaseSessionParticipantClaim, readParticipantOwner } from './registry.js';
 import { assertLiveOwner, ensureLocalPresence, identityRouteDraft, processIdentity, publishCommittedIdentity, retireIdentityRoute } from './participant-host.js';
@@ -14,25 +14,38 @@ export async function catchUp(square, name, options = {}, control, leaseId) {
     throwIfAborted(control);
     if (!await assertLiveOwner(square, name))
         throw new SquareError('already_joined', `${participantIdentity(name)} already stands here — another session holds the name`);
-    const selected = (await square.artifact.transact((facts) => {
-        // Replacement and selection share the receipt transaction: an old waiter cannot
-        // consume a later activity between its heartbeat and its selection.
-        if (leaseId !== undefined && facts.lease(name)?.leaseId !== leaseId)
-            return null;
-        return decideCatch(facts, name, options, square.clock());
-    }, control?.signal)).value;
+    let selected;
+    if (leaseId === undefined && options.id === undefined) {
+        selected = (await square.artifact.read((facts) => {
+            const page = selectCatchPage(facts, name, options);
+            return page.indexes.length === 0 ? observeCatchSelection(facts, page.participant, [], page.filter, square.clock()) : undefined;
+        }, control?.signal)).value;
+    }
+    if (selected === undefined)
+        selected = (await square.artifact.transact((facts) => {
+            // Replacement and selection share the receipt transaction: an old waiter cannot
+            // consume a later activity between its heartbeat and its selection.
+            if (leaseId !== undefined && facts.lease(name)?.leaseId !== leaseId)
+                return null;
+            return decideCatch(facts, name, options, square.clock());
+        }, control?.signal)).value;
     if (selected !== null)
         await publishCommittedIdentity(square, selected.participant);
     return selected;
 }
-export async function join(square, name, control) {
+export async function join(square, name, control, admission = {}) {
     throwIfAborted(control);
     validateName(name);
     const hostLedger = square.hostLedger;
-    const preview = (await square.artifact.read((facts) => ({
-        ...decideJoin(facts, name, square.clock()),
-        participantCount: facts.roster().filter((p) => p.joined || p.done).length,
-    }), control?.signal)).value;
+    const preview = (await square.artifact.read((facts) => {
+        // Express may reenter a known participant, but must never create a new name.
+        const selected = admission.requireKnown ? resolveKnownName(facts, name) : name;
+        return {
+            ...decideJoin(facts, selected, square.clock()),
+            participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+        };
+    }, control?.signal)).value;
+    name = preview.joinedName;
     if (preview.joinAct === undefined) {
         if (hostLedger === undefined)
             return { name: preview.joinedName, activity: null, participantCount: preview.participantCount, reconnected: false };

package/dist/square-application.d.ts

@@ -1,5 +1,6 @@
 import type { Activity, ExpressResult, HistoryQuery, OperationControl, Participant, ParticipantStatus, SquareApplication, SquareApplicationContext, SquareAtInput, SquareBuildInput, SquareSnapshot } from './square-facade.js';
 export type * from './square-facade.js';
+export { createSquareResourceOwner } from './open-square.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
 export { HELD_WAIT_BUDGET_MS } from './runtime.js';
@@ -32,3 +33,6 @@ export declare class Square {
     retireEndedSessionRoutes(sessionId: string): Promise<void>;
 }
 export declare function createSquareApplication(context: SquareApplicationContext): SquareApplication;
+export declare function createSquareApplication(context: SquareApplicationContext, demand: {
+    readonly presentation: false;
+}): SquareApplication<false>;

package/dist/square-application.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { SquareError, isSquareError, nameKey, validateName } from './model.js';
-import { validateDoneBody } from './decisions.js';
+import { resolveKnownName, validateDoneBody } from './decisions.js';
 import { HELD_WAIT_BUDGET_MS, WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, observeCatchSelection } from './catch-decisions.js';
 import { directedSuffix } from './activity-feed.js';
@@ -19,6 +19,7 @@ import { createSquare, diagnoseSquareFile } from './artifact.js';
 import { migrateSquareFile } from './square-migration.js';
 import { discoverSquares, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT } from './list.js';
 import { streamSquare } from './stream.js';
+export { createSquareResourceOwner } from './open-square.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
 export { HELD_WAIT_BUDGET_MS } from './runtime.js';
@@ -82,8 +83,8 @@ async function joinOwned(square, requested, options = {}, control) {
 async function prepareExpression(square, requested, control) {
     try {
         checkControl(control);
-        const name = (await resolveParticipant(square, requested, control)).name;
-        return await joinOwned(square, name, {}, control);
+        const result = await join(square, requested, control, { requireKnown: true });
+        return { participant: result.name, activity: result.activity };
     }
     catch (error) {
         throw failure(error, { operation: 'express', subject: 'caller', participant: requested, expressEffect: 'unsent' });
@@ -139,12 +140,12 @@ async function landExpression(square, name, body, options, transport, control) {
         });
     }
 }
-async function expressOwned(square, requested, body, options, transport, control) {
+async function expressOwned(square, requested, body, options, transport, presentation, control) {
     const entry = await prepareExpression(square, requested, control);
     const name = entry.participant;
     let result;
     try {
-        const feed = (await square.artifact.read((facts) => {
+        const feed = !presentation ? undefined : (await square.artifact.read((facts) => {
             const pendingPublic = directedSuffix(facts, name);
             return {
                 pendingPublic,
@@ -161,7 +162,7 @@ async function expressOwned(square, requested, body, options, transport, control
                 activity: result.activity, waited: result.waited,
                 ...(result.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: result.replyAuthorNotHere }),
             },
-            projection: {
+            projection: feed === undefined ? undefined : {
                 ...fresh, ...feed, participant: name,
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
                 ...(entry.activity === null ? {} : { reentry: entry.activity }),
@@ -217,9 +218,11 @@ async function catchOwned(square, requested, options = {}, control) {
         if (Object.hasOwn(options, 'replace') && idle === 0)
             throw new SquareError('invalid_args', 'Catch replacement requires a positive idle duration');
         catchLimit(options.limit);
-        name = (await resolveParticipant(square, requested, control)).name;
-        subject = 'filter';
-        const from = options.from === undefined ? undefined : await Promise.all(options.from.map(async (target) => (await resolveParticipant(square, target, control)).name));
+        const from = (await square.artifact.read((facts) => {
+            name = resolveKnownName(facts, requested);
+            subject = 'filter';
+            return options.from?.map((target) => resolveKnownName(facts, target));
+        }, control?.signal)).value;
         selection = { ...options, ...(from === undefined ? {} : { from }) };
         subject = 'caller';
         if (idle === 0) {
@@ -360,12 +363,14 @@ export class Square {
     endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.square, name, sessionId, expectedEpoch); }
     retireEndedSessionRoutes(sessionId) { return retireEndedSessionRoutes(this.square, sessionId); }
 }
-export function createSquareApplication(context) {
+export function createSquareApplication(context, demand = { presentation: true }) {
+    const presentation = demand.presentation;
     const env = { ...context.env };
     const clock = clockFor(env, context.clock);
     const hostLedger = context.hostLedger ?? hostLedgerForEnv(env);
     const openOptions = { env, clock, hostLedger, wakeTransport: context.wakeTransport };
     const getTransport = defaultTransport(openOptions);
+    const resources = context.resources;
     function location() {
         const selected = context.squarePath ?? env.SQUARE_LOCATION;
         if (selected === undefined || selected.trim() === '')
@@ -385,7 +390,9 @@ export function createSquareApplication(context) {
     }
     async function scoped(operation, control) {
         checkControl(control);
-        const square = await openSquare(location(), openOptions, control);
+        const selected = location();
+        const artifact = resources?.artifact(selected);
+        const square = await openSquare(selected, { ...openOptions, artifact }, control);
         try {
             return await operation(square);
         }
@@ -416,7 +423,7 @@ export function createSquareApplication(context) {
             const result = await (verb === 'listen' ? listen : ignore)(square, name, target, control);
             return {
                 data: result,
-                projection: {
+                projection: !presentation ? undefined : {
                     ...await contextProjection(square, name), participant: name,
                     requestedTarget: target, target: result.activity?.target ?? target,
                 },
@@ -442,6 +449,8 @@ export function createSquareApplication(context) {
             else {
                 result = await resume(square, name, control);
             }
+            if (!presentation)
+                return { data: { activity: result.activity }, projection: undefined };
             const view = await eventPresentation(square, result.activity.id);
             return {
                 data: { activity: result.activity },
@@ -461,7 +470,7 @@ export function createSquareApplication(context) {
             }, input.markdown, control?.signal);
             return {
                 data: { location: squarePath, ...configuration },
-                projection: { location: squarePath, standingCount: 0, held: false, now,
+                projection: !presentation ? undefined : { location: squarePath, standingCount: 0, held: false, now,
                     automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(env) },
             };
         },
@@ -472,6 +481,8 @@ export function createSquareApplication(context) {
                     throw new SquareError('invalid_args', 'Join history limit must be between 1 and 100');
                 }
                 const data = await joinOwned(square, name, options, control);
+                if (!presentation)
+                    return { data, projection: undefined };
                 try {
                     const view = await entryPresentation(square, data.participant, last);
                     return {
@@ -485,19 +496,19 @@ export function createSquareApplication(context) {
             }, control);
         },
         express(body, options = {}, control) {
-            return selected('express', (square, name) => expressOwned(square, name, body, options, getTransport, control), control);
+            return selected('express', (square, name) => expressOwned(square, name, body, options, getTransport, presentation, control), control);
         },
         catch(options, control) {
             return selected('catch', async (square, name) => {
                 const result = await catchOwned(square, name, options, control);
-                const presence = await catchPresence(square, control).catch(() => undefined);
+                const presence = !presentation ? undefined : await catchPresence(square, control).catch(() => undefined);
                 const view = result.selection;
                 const stop = result.stop;
                 const status = stop === 'already-active' || stop === 'replaced' || stop === 'capped' || stop === 'quorum'
                     ? stop : undefined;
                 return {
                     data: { ...caughtResult(result), ...(status === undefined ? {} : { status }) },
-                    projection: {
+                    projection: !presentation ? undefined : {
                         ...observedContext(square, view.standingCount, view.held, view.participant, view.now),
                         participant: view.participant, sayNumbers: view.sayNumbers,
                         ownActivityCount: view.ownActivityCount, hardCap: view.hardCap, stop,
@@ -525,12 +536,15 @@ export function createSquareApplication(context) {
                 const limit = query.limit ?? (query.at?.length ? null : HISTORY_DEFAULT_LIMIT);
                 const kinds = query.at?.length || query.contextBefore !== undefined || query.contextAfter !== undefined || query.since !== undefined ? undefined : NON_READ;
                 return (await square.artifact.read((facts) => {
-                    const selected = selectHistory(facts, query, limit, kinds);
+                    const selected = selectHistory(facts, query, limit, kinds, presentation);
                     if (limit === null && selected.totalMatches > HISTORY_MAX_LIMIT) {
                         throw failure(new SquareError('invalid_args', `History context exceeds ${HISTORY_MAX_LIMIT} activities`), {
                             operation: 'history', historyBounds: { maxLimit: HISTORY_MAX_LIMIT, totalMatches: selected.totalMatches },
                         });
                     }
+                    const data = { activities: publicActivities(selected.activities) };
+                    if (!presentation)
+                        return { data, projection: undefined };
                     const indexes = selected.activities.map((activity) => activity.index);
                     const presenceAnchors = {};
                     for (const participant of facts.roster()) {
@@ -539,7 +553,7 @@ export function createSquareApplication(context) {
                             (presenceAnchors[anchor] ??= []).push(participant.name);
                     }
                     return {
-                        data: { activities: publicActivities(selected.activities) },
+                        data,
                         projection: {
                             ...observedContext(square, inSquareCount(facts), facts.hold().active), ...selected,
                             sayNumbers: facts.sayOrdinals(indexes), presenceAnchors,
@@ -554,7 +568,7 @@ export function createSquareApplication(context) {
             return selected('other', async (square, requested) => {
                 const name = (await resolveParticipant(square, requested, control)).name;
                 const targets = await listening(square, name, control);
-                return { data: { listening: targets }, projection: await contextProjection(square, name, control) };
+                return { data: { listening: targets }, projection: !presentation ? undefined : await contextProjection(square, name, control) };
             }, control);
         },
         hold: (reason, control) => lifecycle('hold', reason, control),
@@ -562,15 +576,15 @@ export function createSquareApplication(context) {
         done: (body, control) => lifecycle('done', body, control),
         async status(viewer, control) {
             checkControl(control);
-            const selectedViewer = viewer ?? await actor().catch(() => '');
+            const selectedViewer = !presentation ? '' : viewer ?? await actor().catch(() => '');
             return scoped(async (square) => (await square.artifact.read((facts) => queryStatus(facts, {
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
-            }, selectedViewer), control?.signal)).value, control);
+            }, selectedViewer, presentation), control?.signal)).value, control);
         },
         participants(control) {
             return scoped(async (square) => (await square.artifact.read((facts) => queryParticipants(facts, {
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
-            }), control?.signal)).value, control);
+            }, presentation), control?.signal)).value, control);
         },
         async diagnose(control) {
             checkControl(control);
@@ -578,7 +592,7 @@ export function createSquareApplication(context) {
             const data = await diagnoseSquareFile(squarePath);
             return {
                 data,
-                projection: { location: squarePath, now: clock(),
+                projection: !presentation ? undefined : { location: squarePath, now: clock(),
                     ...(data.standingCount === undefined ? {} : { standingCount: data.standingCount }) },
             };
         },
@@ -586,14 +600,14 @@ export function createSquareApplication(context) {
             checkControl(control);
             const squarePath = location();
             const data = await migrateSquareFile(squarePath, control?.signal);
-            return { data, projection: { location: squarePath, now: clock(), standingCount: data.standing } };
+            return { data, projection: !presentation ? undefined : { location: squarePath, now: clock(), standingCount: data.standing } };
         },
         async discover(options, control) {
             checkControl(control);
             const data = await discoverSquares(context.cwd, options, control, openOptions);
             return {
                 data,
-                projection: { cwd: context.cwd, now: clock(),
+                projection: !presentation ? undefined : { cwd: context.cwd, now: clock(),
                     depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT },
             };
         },
@@ -633,7 +647,7 @@ export function createSquareApplication(context) {
                 const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
                 return compare(a.squarePath, b.squarePath) || compare(nameKey(a.name), nameKey(b.name)) || compare(a.name, b.name);
             });
-            return { data: { rows: rows.slice(0, limit), total: rows.length }, projection: { sessionId, now: clock(), limit } };
+            return { data: { rows: rows.slice(0, limit), total: rows.length }, projection: !presentation ? undefined : { sessionId, now: clock(), limit } };
         },
         async recovery(control) {
             let projection = { now: clock() };
@@ -659,7 +673,7 @@ export function createSquareApplication(context) {
                 }, control);
             }
             catch { /* unavailable recovery observations never replace the original error */ }
-            return { data: projection, projection };
+            return { data: projection, projection: presentation ? projection : undefined };
         },
         stream(options, control) {
             checkControl(control);

package/dist/square-facade.d.ts

@@ -1,6 +1,6 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { StoredAct } from './model.js';
-import type { HostLedgerPort, WakeTransportPort, DeliveryResult } from './ports.js';
+import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
 import type { DiagnoseResult } from './artifact.js';
 import type { MigrationOutcome } from './square-migration.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
@@ -136,10 +136,14 @@ export interface SquareApplicationContext extends Readonly<OpenOptions> {
     readonly env: NodeJS.ProcessEnv;
     readonly squarePath?: string;
     readonly participant?: string;
+    /** Borrow the owner's connection for the configured square. The caller owns its lifetime;
+     *  without an owner, each operation opens and closes its own connection. */
+    readonly resources?: SquareResourceOwner;
 }
-export interface ApplicationOutcome<Data, Projection> {
+/** Data-only callers do not request or pay for presentation work. */
+export interface ApplicationOutcome<Data, Projection, Presentation extends boolean = true> {
     readonly data: Data;
-    readonly projection: Projection;
+    readonly projection: Presentation extends true ? Projection : undefined;
 }
 export interface ApplicationFailureDetail {
     readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
@@ -444,26 +448,26 @@ export interface StatusProjection extends SquareContextProjection, PresenceClass
 }
 export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
 }
-export interface SquareApplication {
+export interface SquareApplication<Presentation extends boolean = true> {
     now(): number;
-    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection>>;
-    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection>>;
-    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection>>;
-    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection>>;
-    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection>>;
-    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection>>;
-    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection>>;
-    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>>;
-    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>>>;
-    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>>>;
-    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection>>;
-    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection>>;
-    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection>>;
+    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection, Presentation>>;
+    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection, Presentation>>;
+    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection, Presentation>>;
+    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection, Presentation>>;
+    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection, Presentation>>;
+    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection, Presentation>>;
+    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection, Presentation>>;
+    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, Presentation>>;
+    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection, Presentation>>;
+    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection, Presentation>>;
+    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection, Presentation>>;
     stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
 }
 export type JoinApplicationResult = JoinApplicationData;

package/dist/square-migration.js

@@ -1,4 +1,5 @@
-import { inSqliteTransaction, openExistingSquareDatabase } from './artifact.js';
+import { openExistingSquareDatabase } from './artifact.js';
+import { inSqliteTransaction } from './sqlite-transaction.js';
 import { canonicalPath } from './canonical-path.js';
 import { isWakeRouteKind } from './model.js';
 import { parseActivityId } from './square-core.js';

package/dist/square-sqlite.d.ts

@@ -1,6 +1,6 @@
 import { type DatabaseSync } from 'node:sqlite';
 import { SquareError, type ActivityObservation, type HardCap, type StoredAct, type WakeRoute, type WatchLease } from './model.js';
-import type { SquareRead, RouteFact } from './ports.js';
+import type { SquareHeader, SquareRead, RouteFact } from './ports.js';
 import { type LandingWriter } from './square-domain.js';
 /** Explicit import/export DTOs, not a runtime transaction model. */
 export interface SquareRuntimeState {
@@ -43,7 +43,7 @@ export declare function invalidArtifact(detail: string): SquareError;
 export declare function validateStoredActivity(value: unknown): StoredAct;
 export declare function validateWatchLease(value: unknown): WatchLease;
 export declare function validateRoute(value: unknown): RouteFact;
-export declare function validateSqliteHeader(db: DatabaseSync, location?: string): void;
+export declare function validateSqliteHeader(db: DatabaseSync, location?: string): SquareHeader;
 export interface SqliteDriver extends SquareRead, LandingWriter {
     readonly changed: boolean;
 }

package/dist/square-sqlite.js

@@ -141,6 +141,7 @@ CREATE TABLE landed_audience (
   UNIQUE (act_index, recipient_order)
 ) WITHOUT ROWID;
 CREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);`;
+const EXPECTED_SCHEMA_SQL = SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const encode = JSON.stringify;
 const key = (name) => encode(nameKey(name));
 export function invalidArtifact(detail) {
@@ -330,11 +331,10 @@ export function validateSqliteHeader(db, location = '') {
         throw new SquareError('invalid_args', `Square artifact needs migration.\n${migrationRecoveryCommand(location)}`, { reason: 'migration_required' });
     }
     requireFact(identity.user_version === 2, 'unsupported SQLite format version.');
-    const expected = SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
     const actual = db.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all().map(r => normalizedSql(string(r.sql))).sort();
-    requireFact(actual.length === expected.length && actual.every((sql, i) => sql === expected[i]), 'unsupported row schema.');
+    requireFact(actual.length === EXPECTED_SCHEMA_SQL.length && actual.every((sql, i) => sql === EXPECTED_SCHEMA_SQL[i]), 'unsupported row schema.');
     requireFact(db.prepare('PRAGMA journal_mode').get().journal_mode === (location === ':memory:' ? 'memory' : 'delete'), 'unsupported journal mode.');
-    createSqliteDriver(db).header();
+    return createSqliteDriver(db).header();
 }
 function activitySelection(filter, alias = 'a') {
     const terms = [], args = [];
@@ -418,6 +418,10 @@ export function createSqliteDriver(db) {
             const r = one('SELECT * FROM participants WHERE name_key_json=?', [key(name)]);
             return r ? participant(r) : undefined;
         },
+        participantCounts() {
+            const r = one('SELECT COUNT(*) AS known, COALESCE(SUM(joined),0) AS joined, COALESCE(SUM(done),0) AS done FROM participants');
+            return immutable({ known: integer(r.known), joined: integer(r.joined), done: integer(r.done) });
+        },
         roster: () => immutable(all('SELECT * FROM participants ORDER BY first_index').map(participant)),
         attention: name => immutable(attentionRows('t.listener_key_json=?', [key(name)])),
         incomingAttention: name => immutable(attentionRows('t.target_key_json=?', [key(name)])),
@@ -468,7 +472,14 @@ export function createSqliteDriver(db) {
         sayOrdinals(indexes) {
             indexes.forEach(v => integer(v));
             const result = {};
-            for (const r of all("SELECT a.act_index,(SELECT COUNT(*) FROM activities s WHERE s.kind='say' AND s.actor_key_json=a.actor_key_json AND s.act_index<=a.act_index) AS n FROM activities a WHERE a.kind='say' AND a.act_index IN (SELECT value FROM json_each(?))", [encode(indexes)]))
+            // Only an actor's latest say can use its authoritative lifetime count.
+            for (const r of all(`SELECT a.act_index, CASE
+                WHEN p.say_count IS NOT NULL AND a.act_index=(SELECT MAX(s.act_index) FROM activities s WHERE s.kind='say' AND s.actor_key_json=a.actor_key_json)
+                THEN p.say_count
+                ELSE (SELECT COUNT(*) FROM activities s WHERE s.kind='say' AND s.actor_key_json=a.actor_key_json AND s.act_index<=a.act_index)
+                END AS n
+                FROM activities a LEFT JOIN participants p ON p.name_key_json=a.actor_key_json
+                WHERE a.kind='say' AND a.act_index IN (SELECT value FROM json_each(?))`, [encode(indexes)]))
                 result[integer(r.act_index)] = integer(r.n, 1);
             return immutable(result);
         },

package/dist/views.d.ts

@@ -11,7 +11,7 @@ export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume"
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds']): {
+export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
     visibleActivities: StoredAct[];
@@ -29,8 +29,10 @@ export declare function recoveryObservation(square: OpenSquare, name: string, co
 export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
 type ParticipantQueryContext = Pick<SquareContextProjection, 'location' | 'now' | 'automaticDeliveryAvailable'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>;
+export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, presentation: boolean): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, boolean>;
 export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string): ApplicationOutcome<StatusApplicationData, StatusProjection>;
+export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer: string, presentation: boolean): ApplicationOutcome<StatusApplicationData, StatusProjection, boolean>;
 export declare function eventPresentation(square: OpenSquare, id: ActivityId, control?: OperationControl): Promise<EventPresentation>;
 export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
 export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;