@astrosheep/square 0.3.72 → 0.3.73

package/dist/artifact.d.ts

@@ -22,9 +22,6 @@ export interface SquareSnapshot {
 }
 /** Private artifact-boundary connection shared with explicit migration. Never creates a path. */
 export declare function openExistingSquareDatabase(location: string): DatabaseSync;
-export declare function retrySqliteBusy<T>(operation: () => T, signal?: AbortSignal): Promise<T>;
-/** Acquisition may retry; after change starts, only COMMIT retries, retaining its result. */
-export declare function inSqliteTransaction<T>(db: DatabaseSync, write: boolean, validate: () => void, change: () => T, signal?: AbortSignal): Promise<T>;
 /** One connection, ordered operations, guarded synchronous transaction capabilities. */
 export declare function createArtifactPort(location: string, initial?: SquareState, externalSignal?: AbortSignal): SquareArtifactPort;
 /** New-format creation; initial authority is accepted only at this explicit boundary. */

package/dist/artifact.js

@@ -1,4 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
+import { retrySqliteBusy, inSqliteTransaction } from './sqlite-transaction.js';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -57,9 +58,6 @@ function requireSquareExtension(location) {
     if (!location.endsWith('.square'))
         throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${location}`);
 }
-function isBusy(error) {
-    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
-}
 function storageError(error, location) {
     if (!(error instanceof Error) || error instanceof SquareError || error instanceof InternalSquareError)
         return error;
@@ -85,69 +83,17 @@ function abort(signal) {
     if (signal?.aborted)
         throw signal.reason ?? new Error('Square artifact operation aborted');
 }
-export async function retrySqliteBusy(operation, signal) {
-    while (true) {
-        abort(signal);
-        try {
-            return operation();
-        }
-        catch (error) {
-            if (!isBusy(error))
-                throw error;
-            try {
-                await sleep(25, undefined, { signal });
-            }
-            catch (error) {
-                abort(signal);
-                throw error;
-            }
-        }
-    }
-}
 function synchronous(value) {
     if (value !== null && (typeof value === 'object' || typeof value === 'function') && typeof value.then === 'function') {
         void Promise.resolve(value).catch(() => undefined);
         throw new TypeError('Square artifact callbacks must be synchronous.');
     }
 }
-/** Acquisition may retry; after change starts, only COMMIT retries, retaining its result. */
-export async function inSqliteTransaction(db, write, validate, change, signal) {
-    let begun = false;
-    try {
-        await retrySqliteBusy(() => {
-            db.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN');
-            begun = true;
-            try {
-                validate();
-            }
-            catch (error) {
-                db.exec('ROLLBACK');
-                begun = false;
-                throw error;
-            }
-        }, signal);
-        abort(signal);
-        const result = change();
-        synchronous(result);
-        await retrySqliteBusy(() => db.exec('COMMIT'), signal);
-        begun = false;
-        return result;
-    }
-    catch (error) {
-        if (begun) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* retain the original failure */ }
-        }
-        throw error;
-    }
-}
 const readMethods = [
     'header', 'participant', 'roster', 'attention', 'incomingAttention', 'hold',
     'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount', 'pendingAudience',
-    'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'routes',
+    'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'routes', 'participantCounts',
 ];
 const writeMethods = ['applyLanding', 'markSeen', 'putLease', 'removeLease', 'replaceRoutes'];
 /** One connection, ordered operations, guarded synchronous transaction capabilities. */
@@ -202,8 +148,8 @@ export function createArtifactPort(location, initial, externalSignal) {
     }
     async function transaction(callback, write, signal) {
         const db = await connection(signal);
-        return inSqliteTransaction(db, write, () => validate(db), () => {
-            const driver = createSqliteDriver(db), version = driver.header().revision;
+        return inSqliteTransaction(db, write, () => validate(db), (header) => {
+            const driver = createSqliteDriver(db), version = header.revision;
             let active = true, failed = false, failure;
             function guard(fn) {
                 return ((...args) => {
@@ -250,7 +196,7 @@ export function createArtifactPort(location, initial, externalSignal) {
     }
     const revision = signal => queue(async (s) => {
         const db = await connection(s);
-        return inSqliteTransaction(db, false, () => validate(db), () => createSqliteDriver(db).header().revision, s);
+        return inSqliteTransaction(db, false, () => validate(db), (header) => header.revision, s);
     }, signal);
     return {
         read: (select, signal) => queue(async (s) => {

package/dist/catch-decisions.d.ts

@@ -1,6 +1,6 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
-import type { DirectedFilter, SquareRead, SquareWrite } from './ports.js';
+import type { ActivityIndex, DirectedFilter, SquareRead, SquareWrite } from './ports.js';
 import type { CatchOptions } from './square-facade.js';
 export interface CatchSelection {
     readonly participant: string;
@@ -20,5 +20,11 @@ export declare function observeCatchSelection(facts: SquareRead, participant: st
 export declare const CATCH_DEFAULT_LIMIT = 10;
 export declare const CATCH_MAX_LIMIT = 100;
 export declare function catchLimit(value: number | undefined): number;
+/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
+export declare function selectCatchPage(facts: SquareRead, requestedName: string, options: CatchOptions): {
+    readonly participant: string;
+    readonly indexes: readonly ActivityIndex[];
+    readonly filter: DirectedFilter;
+};
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
 export declare function decideCatch(facts: SquareWrite, requestedName: string, options: CatchOptions, at: number): CatchSelection;

package/dist/catch-decisions.js

@@ -1,17 +1,20 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { inSquareCount, readCursor, watchTerminalStatus } from './runtime.js';
+import { readCursor, terminalStatusFor } from './runtime.js';
 import { SquareError } from './model.js';
 import { resolveKnownName } from './decisions.js';
 /** Capture a selected page (or an empty completion) without opening another resource. */
 export function observeCatchSelection(facts, participant, activities, filter, at) {
+    if (typeof at !== 'number' || !Number.isFinite(at))
+        throw new SquareError('invalid_args', 'Catch time must be a finite number.');
     const cursor = readCursor(facts, participant);
+    const counts = facts.participantCounts(), header = facts.header(), current = facts.participant(participant);
     return {
         participant, activities, consumedThrough: cursor < 0 ? null : formatActivityId(cursor),
         remaining: facts.directedCount(participant, filter),
         sayNumbers: activities.length === 0 ? {} : facts.sayOrdinals(activities.map((item) => item.index)),
-        standingCount: inSquareCount(facts), held: facts.hold().active, now: at,
-        ownActivityCount: facts.participant(participant).sayCount, hardCap: facts.header().hardCap,
-        terminalStatus: watchTerminalStatus(facts, participant),
+        standingCount: counts.joined, held: facts.hold().active, now: at,
+        ownActivityCount: current.sayCount, hardCap: header.hardCap,
+        terminalStatus: terminalStatusFor(current, header.hardCap, counts),
     };
 }
 export const CATCH_DEFAULT_LIMIT = 10;
@@ -23,13 +26,21 @@ export function catchLimit(value) {
     }
     return limit;
 }
+/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
+export function selectCatchPage(facts, requestedName, options) {
+    const participant = resolveKnownName(facts, requestedName);
+    const limit = catchLimit(options.limit);
+    const filter = { unseenOnly: true, ...(options.from === undefined ? {} : { senders: options.from }), ...(options.mention === true ? { attentionOnly: true } : {}) };
+    return { participant, indexes: facts.directed(participant, filter, { edge: 'oldest', limit }).items.map((item) => item.index), filter };
+}
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
 export function decideCatch(facts, requestedName, options, at) {
-    const viewer = resolveKnownName(facts, requestedName);
-    const limit = catchLimit(options.limit);
+    let viewer;
     let delivered;
     let filter = { unseenOnly: true };
     if (options.id !== undefined) {
+        viewer = resolveKnownName(facts, requestedName);
+        catchLimit(options.limit);
         if (['idle', 'from', 'mention', 'limit'].some((key) => Object.hasOwn(options, key)))
             throw new SquareError('invalid_args', 'Catch id cannot be combined with idle, from, mention or limit.');
         const index = parseActivityId(options.id);
@@ -44,8 +55,10 @@ export function decideCatch(facts, requestedName, options, at) {
         delivered = [activity];
     }
     else {
-        filter = { unseenOnly: true, ...(options.from === undefined ? {} : { senders: options.from }), ...(options.mention === true ? { attentionOnly: true } : {}) };
-        delivered = facts.activities(facts.directed(viewer, filter, { edge: 'oldest', limit }).items.map((item) => item.index));
+        const page = selectCatchPage(facts, requestedName, options);
+        viewer = page.participant;
+        filter = page.filter;
+        delivered = facts.activities(page.indexes);
     }
     facts.markSeen(viewer, delivered.map((item) => item.index), at);
     return observeCatchSelection(facts, viewer, delivered, filter, at);

package/dist/claude-delivery.d.ts

@@ -3,7 +3,7 @@ import type { WakeTransportPort } from './ports.js';
 export declare function nativeTokens(text: string): string[];
 export declare function nativePayload(token: string, preview: string): string;
 export declare function createClaudeWakeTransport(hostLedger: HostLedgerPort, env?: NodeJS.ProcessEnv): WakeTransportPort;
-/** Authority comes only from bound memberships and the existing attempt ledger. */
+/** Retired tokens veto a frame; only live correlations and bound memberships confer authority. */
 export declare function observeClaudeDelivery(sessionId: string, text: string, operation: 'guard' | 'admitted' | 'stored', env?: NodeJS.ProcessEnv): Promise<{
     recognized: boolean;
     current: boolean;

package/dist/claude-delivery.js

@@ -101,15 +101,19 @@ async function dispatchClaude(request, hostLedger, timeoutMs, beforeSend, env =
         return writeClaudeWake(row.session, native.endpoint, payload, timeoutMs, signal);
     }, signal);
 }
-/** Authority comes only from bound memberships and the existing attempt ledger. */
+/** Retired tokens veto a frame; only live correlations and bound memberships confer authority. */
 export async function observeClaudeDelivery(sessionId, text, operation, env = process.env) {
     const ledger = hostLedgerForEnv(env);
     return ledger.withClaimLock(async () => {
         const tokens = nativeTokens(text);
-        const rows = (await ledger.listEvidence({ kind: 'wake', session: sessionId })).filter((row) => row.nativeDelivery?.harness === 'claude' && row.claimToken && tokens.includes(row.claimToken) && ['dispatching', 'unknown', 'accepted'].includes(row.outcome));
+        const { deliveries: rows, retired } = await ledger.lookupNativeTokens({ harness: 'claude', session: sessionId, tokens });
+        // A stale token vetoes the entire frame, including a mixed current/stale frame,
+        // before admission, artifact reads or presentation can confer any authority.
+        if (retired.length)
+            return { recognized: true, current: false };
         let current = false;
         for (const row of rows) {
-            if (row.nativeDelivery?.harness !== 'claude')
+            if (row.nativeDelivery?.harness !== 'claude' || !['dispatching', 'unknown', 'accepted'].includes(row.outcome))
                 continue;
             const native = row.nativeDelivery;
             const pending = await currentDelivery(row, ledger).catch(() => undefined);

package/dist/cli/ledger-command.d.ts

@@ -0,0 +1,12 @@
+import { type LedgerMaintenanceReport } from '../ledger-maintenance.js';
+import { type HostLedgerReport } from '../host-ledger-migration.js';
+import { type CommandSpec } from './context.js';
+type LedgerIntent = {
+    readonly action: 'verify' | 'migrate';
+} | {
+    readonly action: 'gc';
+    readonly dryRun: boolean;
+};
+type LedgerResult = HostLedgerReport | LedgerMaintenanceReport;
+export declare const ledgerCommand: CommandSpec<LedgerIntent, LedgerResult>;
+export {};

package/dist/cli/ledger-command.js

@@ -0,0 +1,68 @@
+import { gcHostLedger } from '../ledger-maintenance.js';
+import { migrateHostLedger, verifyHostLedger } from '../host-ledger-migration.js';
+import { usage } from './context.js';
+function renderReport(report) {
+    const lines = [
+        `host ledger: ${report.status}`,
+        `presence: ${report.presence} · evidence: ${report.evidence}`,
+    ];
+    if (report.presenceRevision !== undefined) {
+        lines.push(`revisions: presence ${report.presenceRevision} · evidence ${report.evidenceRevision}`);
+    }
+    if (report.status === 'upgraded')
+        lines.push('SQLite schema upgraded in place; records, order and revisions preserved.');
+    if (report.ready !== undefined)
+        lines.push(`readiness: ${report.ready ? 'ready' : 'not ready'}`);
+    if (report.sources !== undefined) {
+        for (const kind of ['presence', 'evidence']) {
+            const source = report.sources[kind];
+            lines.push(`${kind}.ndjsonl: ${source.records} accepted · ${source.ignored} ignored · ${source.rejected} rejected · sha256 ${source.sha256 ?? 'absent'}`);
+        }
+    }
+    if (report.status === 'legacy') {
+        if (report.ready)
+            lines.push('Stop all Square hosts before conversion.', 'square ledger migrate');
+        else
+            lines.push('Unsafe legacy records; conversion refused.');
+    }
+    return lines.join('\n') + '\n';
+}
+/** Counts only: unreadable locations are summarized, never printed, so no payload or credential can leak. */
+function renderMaintenance(report) {
+    return [
+        `host ledger: gc${report.dryRun ? ' (dry run)' : ''}`,
+        `eligible: ${report.eligible} · retired: ${report.retired} · cas misses: ${report.casMisses}`,
+        `unreadable artifacts: ${report.unavailableArtifacts.length}`,
+        ...(report.dryRun ? ['Dry run: nothing retired; ledger and artifacts unchanged.'] : []),
+        '',
+    ].join('\n');
+}
+export const ledgerCommand = {
+    parse(argv, context) {
+        if (argv[0] === 'gc') {
+            if (argv.length === 1)
+                return { action: 'gc', dryRun: false };
+            if (argv.length === 2 && argv[1] === '--dry-run')
+                return { action: 'gc', dryRun: true };
+            return usage(context.command);
+        }
+        if (argv.length !== 1 || (argv[0] !== 'verify' && argv[0] !== 'migrate'))
+            usage(context.command);
+        return { action: argv[0] };
+    },
+    execute(intent, context) {
+        if (intent.action === 'gc')
+            return gcHostLedger({ env: context.env, dryRun: intent.dryRun });
+        const options = { env: context.env };
+        return intent.action === 'verify' ? verifyHostLedger(options) : migrateHostLedger(options);
+    },
+    present(result) {
+        if ('dryRun' in result) {
+            process.stdout.write(renderMaintenance(result));
+            return;
+        }
+        process.stdout.write(renderReport(result));
+        if (result.ready === false)
+            process.exitCode = 2;
+    },
+};

package/dist/cli/registry.js

@@ -1,5 +1,6 @@
 import { buildCommand, doneCommand, expressCommand, holdCommand, ignoreCommand, joinCommand, listenCommand, listeningCommand, resumeCommand } from './square-commands.js';
 import { doctorCommand, migrateCommand } from './maintenance-commands.js';
+import { ledgerCommand } from './ledger-command.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
 import { mcpServerCommand } from './mcp-server-command.js';
@@ -26,6 +27,7 @@ export const commandRegistry = [
     { names: ['harness'], spec: harnessCommand },
     { names: ['doctor'], spec: doctorCommand },
     { names: ['migrate'], spec: migrateCommand },
+    { names: ['ledger'], spec: ledgerCommand },
     { names: ['history'], spec: historyCommand },
     { names: ['status'], spec: statusCommand },
     { names: ['participants'], spec: participantsCommand },

package/dist/help.js

@@ -77,7 +77,12 @@ const COMMANDS = [
     {
         names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
         summary: 'Convert an existing version 1 square to row storage in place.',
-        details: ['It is the only migration command: there is no --check, --backup or --force.', 'A version 2 square is left untouched; an unrelated or unsupported artifact is refused without a write.'],
+        details: ['For the selected square artifact only; there is no --check, --backup or --force.', 'A version 2 square is left untouched; an unrelated or unsupported artifact is refused without a write.'],
+    },
+    {
+        names: ['ledger'], usage: 'ledger <verify|migrate|gc>', usesSquare: false, group: 'maintenance',
+        summary: 'Verify, convert, or reclaim the machine-local host ledger.',
+        details: ['verify: read-only SQLite integrity or full legacy readiness with accepted/ignored/rejected counts and source hashes; not-ready exits 2, an empty root stays empty. An older or unsupported database is refused with the migrate command and is never upgraded by verify.', 'migrate: stop every Square host first, then convert legacy NDJSON, or upgrade an older SQLite ledger in place. Sources, records, order and observer revisions are preserved; an existing current ledger is an untouched no-op.', 'gc [--dry-run]: reclaim old wake/presentation evidence only where the square artifact proves the recipient is closed — the activity reached them and catch receipted it or they later rejoined. Dispatching, lifecycle and unprovable rows are retained. Deleted rows free reusable pages, not file size (no VACUUM); retired Claude recognition tokens keep growing in total.', 'Run gc with --dry-run first: it reports eligible, retired, cas-miss and unreadable-artifact counts without writing. Eligible rows are candidates only: a changed record or an unusable Claude correlation is retained.', 'No participant or square location is required. Uses SQUARE_HOST_LEDGER_ROOT, then SQUARE_REGISTRY’s directory, then ~/.square/host-ledger.', 'These commands never stop, restart, install into or schedule hosts; conversion and schema upgrade are never automatic. No --force or repair.'],
     },
 ];
 function definitionFor(command) {
@@ -90,7 +95,7 @@ export function renderGlobalHelp() {
     const groups = [
         { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'ignore', 'listening', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
-        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate'] },
+        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate', 'ledger'] },
     ];
     const commandLines = groups.flatMap(({ key, title, order }) => [
         title,

package/dist/host-ledger-file-adapter.d.ts

@@ -1,33 +1,27 @@
 import { type VersionObserver } from './file-changes.js';
-import type { HostLedgerPort, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, PresenceClaimResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, WakeAttemptClaim, WakeAttemptClaimInput, WakeAttemptLookup } from './host-ledger.js';
+import type { HostLedgerPort, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, PresenceClaimResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, NativeTokenLookup, NativeTokenResult, ClaimResult, WakeAttemptClaim, WakeAttemptClaimInput, WakeAttemptLookup } from './host-ledger.js';
 export interface HostLedgerFileAdapterOptions {
     rootPath?: string;
     now?: () => number;
 }
+/** Existing port surface; each operation owns a short-lived SQLite connection. */
 export declare class FileHostLedgerPort implements HostLedgerPort {
     private readonly root;
     private readonly clock;
     constructor(o?: HostLedgerFileAdapterOptions);
-    private file;
-    /** Invalidation only: callers still use the ledger projections as their authority. */
     observeChanges(): Promise<{
         presence: VersionObserver<string>;
         evidence: VersionObserver<string>;
     }>;
-    /** Time can expire bindings/evidence even when their files do not change. */
     nextExpiry(session: string): Promise<number>;
-    /** The ownership claim critical section: the same lock as claimPresence and finalize. */
     withClaimLock<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
     claimPresence(i: PresenceRecord, signal?: AbortSignal): Promise<PresenceClaimResult>;
     ensurePresence(i: PresenceRecord): Promise<PresenceResult>;
-    /** Local batch suppression is monotonic only for the captured host generation. */
     suppressPresence(i: PresenceRecord, through: number): Promise<boolean>;
     removePresence(i: PresenceKey): Promise<void>;
     removePresenceIfUnchanged(i: PresenceRecord): Promise<boolean>;
     listPresence(i?: PresenceLookup): Promise<readonly PresenceRecord[]>;
-    /** One attempt row owns attention-wide exclusion and session-scoped history for a wake. */
     claimWakeAttempt(i: WakeAttemptClaimInput): Promise<WakeAttemptClaim>;
-    /** One locked, token-fenced replacement; each operation owns its state condition. */
     private updateWake;
     listWakeAttempts(i?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
     prepareNativeWake(i: EvidenceRecord & {
@@ -40,11 +34,11 @@ export declare class FileHostLedgerPort implements HostLedgerPort {
     }): Promise<boolean>;
     claimEvidence(i: EvidenceClaim): Promise<ClaimResult>;
     releaseEvidence(i: EvidenceRelease): Promise<void>;
-    /** Token-fenced terminal write. A token may only finish the attempt it claimed. */
     appendEvidence(i: EvidenceRecord & {
         readonly claimToken: string;
     }): Promise<void>;
     listEvidence(i?: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
-    gcEvidence(i: EvidenceGc): Promise<void>;
+    retireEvidenceIfUnchanged(expected: EvidenceRecord): Promise<boolean>;
+    lookupNativeTokens(input: NativeTokenLookup): Promise<NativeTokenResult>;
 }
 export declare function createHostLedgerPort(o?: HostLedgerFileAdapterOptions): FileHostLedgerPort;