@astrosheep/square 0.3.73 → 0.3.75

package/dist/attention-presentation.d.ts

@@ -12,4 +12,6 @@ export declare function previewAttentionBody(body: string): string;
 export declare function attentionBodyIsClipped(body: string): boolean;
 export declare function displayAttentionPath(squarePath: string): string;
 export declare function renderAttentionDescription({ actor, recipient, route }: Pick<AttentionPreview, 'actor' | 'recipient' | 'route'>): string;
+/** Full notification text for human-facing expansion, never the bounded model preview. */
+export declare function renderAttentionFull(attention: AttentionPreview): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -24,14 +24,23 @@ export function renderAttentionDescription({ actor, recipient, route }) {
         case 'bell': return `${actor} rang the bell · everyone’s attention`;
     }
 }
-export function renderAttentionPreview(attention) {
+/** Full notification text for human-facing expansion, never the bounded model preview. */
+export function renderAttentionFull(attention) {
+    return renderAttentionBlock(attention, attention.body);
+}
+function renderAttentionBlock(attention, body) {
     return [
         '<square-activity>',
         `· ${displayAttentionPath(attention.squarePath)} · ${formatActivityId(attention.actIndex)}`,
         `● ${renderAttentionDescription(attention)}`,
         '',
-        previewAttentionBody(attention.body),
+        body,
         '</square-activity>',
+    ].join('\n');
+}
+export function renderAttentionPreview(attention) {
+    return [
+        renderAttentionBlock(attention, previewAttentionBody(attention.body)),
         // A clipped body ends with the full command to read it all: a labeled caption, then the
         // command bare on its own line so it can be copied and run as it is.
         ...(attentionBodyIsClipped(attention.body)

package/dist/boundary-presentation.d.ts

@@ -1,5 +1,12 @@
 import type { InboxMembership } from './model.js';
 export { pendingAtBoundary } from './square-projections.js';
 export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
-/** Serialize a boundary across hook processes so one stale inbox cannot render twice. */
+/**
+ * Serialize a boundary across hook processes so one stale inbox cannot render twice.
+ *
+ * `lookup` returns the session's memberships for this boundary. It may reuse an observation it has
+ * verified against the current presence binding and artifact revision; the boundary still projects
+ * presentation evidence live, and `presentPending` still re-checks the pending head, join, ownership
+ * claim and seen CAS. A source that cannot verify its reuse must read the inbox again.
+ */
 export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -140,7 +140,14 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
     }
     return result;
 }
-/** Serialize a boundary across hook processes so one stale inbox cannot render twice. */
+/**
+ * Serialize a boundary across hook processes so one stale inbox cannot render twice.
+ *
+ * `lookup` returns the session's memberships for this boundary. It may reuse an observation it has
+ * verified against the current presence binding and artifact revision; the boundary still projects
+ * presentation evidence live, and `presentPending` still re-checks the pending head, join, ownership
+ * claim and seen CAS. A source that cannot verify its reuse must read the inbox again.
+ */
 export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
     const ledgerRoot = hostLedgerRoot(env);
     const ownerKey = createHash('sha256').update(sessionId).digest('hex');

package/dist/cli/context.d.ts

@@ -33,5 +33,5 @@ export interface ParsedGlobalArgs {
 export declare function parseGlobalArgs(rawArgs: string[]): Promise<ParsedGlobalArgs>;
 export declare function locationIsRequired(command: string): boolean;
 export declare function defaultContext(command: string, squarePath?: string, name?: string): CommandContext;
-export declare function applicationFor(context: CommandContext): import("../square-facade.js").SquareApplication;
+export declare function applicationFor(context: CommandContext): import("../square-facade.js").SquareApplication<true>;
 export declare function requireSquarePath(context: CommandContext): string;

package/dist/cli/express-presentation.js

@@ -156,8 +156,7 @@ export async function executeExpression(application, squarePath, requestedName,
         const lines = [message, `· draft kept: ${draftPath}`];
         const recipientFailure = detail?.subject === 'recipient';
         const repair = reason === 'bell_mention_conflict' ? { bell: true, fromBody: true }
-            : reason === 'unmatched_mention' ? { bell: false, fromBody: true }
-                : reason === 'not_standing' && recipientFailure ? { bell: false, fromBody: false } : undefined;
+            : reason === 'not_standing' && recipientFailure ? { bell: false, fromBody: false } : undefined;
         if (isSquareError(error)) {
             if ((reason === 'never_joined' && detail?.subject === 'caller') || error.code === 'unknown_participant' || error.code === 'not_joined') {
                 lines.push(joinRecoveryCommand(squarePath, name));

package/dist/cli/ledger-command.js

@@ -4,6 +4,7 @@ import { usage } from './context.js';
 function renderReport(report) {
     const lines = [
         `host ledger: ${report.status}`,
+        `root: ${report.rootPath}`,
         `presence: ${report.presence} · evidence: ${report.evidence}`,
     ];
     if (report.presenceRevision !== undefined) {
@@ -21,9 +22,12 @@ function renderReport(report) {
     }
     if (report.status === 'legacy') {
         if (report.ready)
-            lines.push('Stop all Square hosts before conversion.', 'square ledger migrate');
+            lines.push('Stop agent sessions and MCP services using Square with this ledger before conversion.', 'Keep them stopped until migration and verification succeed; then start them with the updated Square version.', 'Next: migrate, then verify.', 'square ledger migrate', 'square ledger verify');
         else
-            lines.push('Unsafe legacy records; conversion refused.');
+            lines.push('Unsafe legacy records; conversion refused. Preserve the sources and resolve the rejected records before retrying verification.');
+    }
+    if (report.status === 'migrated' || report.status === 'upgraded') {
+        lines.push('Keep affected sessions and MCP services stopped until verification succeeds.', 'After verification, start them with the updated Square version.', 'square ledger verify');
     }
     return lines.join('\n') + '\n';
 }

package/dist/cli/meta-commands.js

@@ -12,7 +12,7 @@ export const helpCommand = {
             return renderGlobalHelp();
         const rendered = renderSubcommandHelp(intent.command);
         if (rendered === undefined)
-            fail(`unknown command: ${intent.command}\nrun 'square help' to list available commands`);
+            fail(`unknown command: ${intent.command}\nrun 'square --help' to list available commands`);
         return rendered;
     },
     present: (result) => process.stdout.write(result),

package/dist/decisions.js

@@ -107,30 +107,15 @@ export function decideAct(facts, input) {
             throw activityRefusal('invalid_args', `${participantIdentity(requested)} is not standing in this square`, { reason: 'not_standing', targets: [requested] });
         addMention(resolved);
     }
-    if (input.noMention !== true) {
-        const unmatched = [];
-        for (const candidate of scanMentionCandidates(body)) {
-            const resolved = resolveNameAt(body, candidate, joinedNames);
-            if (resolved === undefined)
-                unmatched.push(candidate);
-            else
-                addMention(resolved);
-        }
-        if (reach !== 'bell' && unmatched.length > 0) {
-            const names = roster.map((participant) => participant.name);
-            const notStanding = unmatched.filter((candidate) => resolveNameAt(body, candidate, names) !== undefined);
-            const unknown = unmatched.filter((candidate) => !notStanding.includes(candidate));
-            const lines = [];
-            if (unknown.length > 0)
-                lines.push(`${unknown.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${unknown.length === 1 ? 'does' : 'do'} not match anyone in this square`);
-            if (notStanding.length > 0)
-                lines.push(`${notStanding.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${notStanding.length === 1 ? 'is' : 'are'} not standing in this square`);
-            throw activityRefusal('invalid_args', lines.join('\n'), { reason: 'unmatched_mention', targets: unmatched.map((candidate) => candidate.token) });
-        }
+    const bodyMentions = input.noMention === true ? [] : scanMentionCandidates(body);
+    for (const candidate of bodyMentions) {
+        const resolved = resolveNameAt(body, candidate, joinedNames);
+        if (resolved !== undefined)
+            addMention(resolved);
     }
     if (reach === 'bell' && mentionNames.length > 0)
         throw activityRefusal('invalid_args', 'A bell cannot be combined with a mention', { reason: 'bell_mention_conflict', targets: mentionNames });
-    if (input.requireExplicitReach && reach !== 'bell' && mentionNames.length === 0 && reply === undefined && input.noMention !== true) {
+    if (input.requireExplicitReach && reach !== 'bell' && mentionNames.length === 0 && bodyMentions.length === 0 && reply === undefined && input.noMention !== true) {
         throw activityRefusal('invalid_args', 'Express needs a recipient, reply, bell, or explicit bare reach', { reason: 'explicit_reach_required' });
     }
     const header = facts.header();

package/dist/help.js

@@ -77,12 +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: ['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.'],
+        details: ['For the selected .square artifact only. Global identity and delivery records use square ledger migrate instead.', 'Stop sessions and services using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'A version 2 square is left untouched; an unrelated or unsupported artifact is refused without a write. There is no --check, --backup or --force.'],
     },
     {
         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.'],
+        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 supported SQLite format requires explicit migration. Unsupported versions or invalid databases need diagnosis; migration is not a repair command.', 'migrate: stop agent sessions and MCP services using Square with this ledger first, then convert legacy NDJSON or upgrade supported SQLite version 1 in place. Keep them stopped, run square ledger verify afterward, then start them with the updated Square version. 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) {
@@ -131,7 +131,7 @@ export function renderSubcommandHelp(command) {
         'Help:',
         '  -h, --help  Show this command help.',
         '',
-        "Run 'square help' to list available commands.",
+        "Run 'square --help' to list available commands.",
         '',
     ].join('\n');
 }
@@ -164,5 +164,5 @@ export function helpRequest(rawArgs) {
 export function commandUsageHint(command) {
     return command !== undefined && definitionFor(command) !== undefined
         ? `Run 'square ${command} --help' for usage.\n`
-        : "Run 'square help' to list commands.\n";
+        : "Run 'square --help' to list commands.\n";
 }

package/dist/host-ledger-migration.d.ts

@@ -7,6 +7,7 @@ export interface LedgerSourceReport {
 }
 export interface HostLedgerReport {
     status: 'empty' | 'legacy' | 'sqlite' | 'migrated' | 'upgraded';
+    rootPath: string;
     presence: number;
     evidence: number;
     presenceRevision?: number;

package/dist/host-ledger-migration.js

@@ -5,7 +5,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { canonicalPathSync } from './canonical-path.js';
 import { withFileLock } from './file-lock.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
-import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, } from './host-ledger-sqlite.js';
+import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, } from './host-ledger-sqlite.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
 function rootFor(options) {
     return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
@@ -25,21 +25,45 @@ async function exists(file) {
         throw error;
     }
 }
-/** Generic and payload-free: the only supported remedy is offline conversion under stopped hosts. */
-function verificationFailure() {
-    return new Error('Host ledger database verification failed; destination left untouched.\nStop all Square hosts, then run: square ledger migrate');
+function migrationGuidance(root, file) {
+    const name = file ?? path.join(root, LEDGER_FILENAME);
+    return `Host ledger at ${root} has a supported older format (${name}).\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nsquare ledger migrate\nsquare ledger verify`;
 }
-async function verifyDatabase(file, signal) {
+function verificationFailure(root, file, format) {
+    const name = file ?? path.join(root, LEDGER_FILENAME);
+    const detail = format === 'unsupported'
+        ? 'It has an unsupported format version.'
+        : format === 'unrelated'
+            ? 'It is unrelated to a Square host ledger.'
+            : format === undefined
+                ? 'It could not be read.'
+                : 'Its identity is current but its contents failed verification.';
+    return new Error(`Host ledger verification failed at ${name}; ${detail}\nDestination left untouched. Migration is not a repair command. Keep the affected sessions and MCP services stopped, preserve the ledger, and diagnose the underlying file before retrying.`);
+}
+async function verifyDatabase(file, root, signal) {
     abort(signal);
     let db;
     try {
         db = new DatabaseSync(file, { readOnly: true });
         const counts = await inSqliteTransaction(db, false, () => validateLedger(db), () => verifyLedger(db), signal);
-        return { status: 'sqlite', ...counts };
+        return { status: 'sqlite', rootPath: root, ...counts };
     }
     catch {
         abort(signal);
-        throw verificationFailure();
+        let format;
+        try {
+            db = new DatabaseSync(file, { readOnly: true });
+            format = inspectLedgerIdentity(db);
+            db.close();
+            db = undefined;
+        }
+        catch {
+            db?.close();
+            db = undefined;
+        }
+        if (format === 'old-sqlite')
+            throw new Error(migrationGuidance(root, file));
+        throw verificationFailure(root, file, format);
     }
     finally {
         db?.close();
@@ -94,9 +118,10 @@ async function readLegacy(root, kind, signal) {
 async function readSources(root, signal) {
     return { presence: await readLegacy(root, 'presence', signal), evidence: await readLegacy(root, 'evidence', signal) };
 }
-function sourceReport(sources) {
+function sourceReport(root, sources) {
     return {
         status: sources.presence.report.sha256 === null && sources.evidence.report.sha256 === null ? 'empty' : 'legacy',
+        rootPath: root,
         presence: sources.presence.rows.length, evidence: sources.evidence.rows.length,
         sources: { presence: sources.presence.report, evidence: sources.evidence.report },
         ready: sources.presence.report.rejected === 0 && sources.evidence.report.rejected === 0,
@@ -108,8 +133,8 @@ export async function verifyHostLedger(options = {}) {
     abort(options.signal);
     const destination = path.join(root, LEDGER_FILENAME);
     if (await exists(destination))
-        return verifyDatabase(destination, options.signal);
-    return sourceReport(await readSources(root, options.signal));
+        return verifyDatabase(destination, root, options.signal);
+    return sourceReport(root, await readSources(root, options.signal));
 }
 /** The fixed offline fence: ownership claim, then both legacy source locks, in that order. */
 function withOfflineLocks(root, signal, body) {
@@ -124,24 +149,24 @@ function withOfflineLocks(root, signal, body) {
 async function currentFormat(root, signal) {
     const destination = path.join(root, LEDGER_FILENAME);
     try {
-        return await verifyDatabase(destination, signal);
+        return await verifyDatabase(destination, root, signal);
     }
     catch {
         abort(signal);
     }
     if (!await exists(destination))
-        throw verificationFailure();
+        throw verificationFailure(root);
     let db;
     try {
         db = new DatabaseSync(destination);
         const upgraded = await inSqliteTransaction(db, true, () => { }, () => upgradeLedger(db), signal);
         db.close();
         db = undefined;
-        return { ...await verifyDatabase(destination, signal), status: upgraded ? 'upgraded' : 'sqlite' };
+        return { ...await verifyDatabase(destination, root, signal), status: upgraded ? 'upgraded' : 'sqlite' };
     }
     catch {
         abort(signal);
-        throw verificationFailure();
+        throw verificationFailure(root, destination);
     }
     finally {
         db?.close();
@@ -154,16 +179,32 @@ export async function migrateHostLedger(options = {}) {
     const destination = path.join(root, LEDGER_FILENAME);
     if (await exists(destination)) {
         try {
-            return await verifyDatabase(destination, signal);
+            return await verifyDatabase(destination, root, signal);
         }
         catch {
             abort(signal);
         }
-        // An older SQLite format is upgraded offline; a current ledger stays a read-only no-op.
-        return withOfflineLocks(root, signal, () => currentFormat(root, signal));
+        // Inspect only the database identity; record/schema verification remains the migration fence.
+        let format;
+        let probe;
+        try {
+            probe = new DatabaseSync(destination, { readOnly: true });
+            format = inspectLedgerIdentity(probe);
+        }
+        catch {
+            format = undefined;
+        }
+        finally {
+            probe?.close();
+        }
+        if (format === 'old-sqlite') {
+            // Only the supported prior format enters the existing offline upgrade fence.
+            return withOfflineLocks(root, signal, () => currentFormat(root, signal));
+        }
+        throw verificationFailure(root, destination, format);
     }
     if (!await exists(path.join(root, 'presence.ndjsonl')) && !await exists(path.join(root, 'evidence.ndjsonl'))) {
-        return { status: 'empty', presence: 0, evidence: 0 };
+        return { status: 'empty', rootPath: root, presence: 0, evidence: 0 };
     }
     return withOfflineLocks(root, signal, () => convertLegacy(root, destination, signal));
 }
@@ -172,7 +213,7 @@ async function convertLegacy(root, destination, signal) {
     if (await exists(destination))
         return currentFormat(root, signal);
     const sources = await readSources(root, signal);
-    const report = sourceReport(sources);
+    const report = sourceReport(root, sources);
     if (!report.ready) {
         const rejected = ['presence', 'evidence'].filter((kind) => sources[kind].report.rejected > 0)
             .map((kind) => `${kind}: ${sources[kind].report.rejected} rejected (first line ${sources[kind].firstRejectedLine})`);
@@ -198,7 +239,7 @@ async function convertLegacy(root, destination, signal) {
         }, signal);
         db.close();
         db = undefined;
-        const verified = await verifyDatabase(file, signal);
+        const verified = await verifyDatabase(file, root, signal);
         if (verified.presence !== report.presence || verified.evidence !== report.evidence) {
             throw new Error('Host ledger import counts do not match; conversion refused.');
         }
@@ -208,7 +249,7 @@ async function convertLegacy(root, destination, signal) {
         }
         catch (error) {
             if (error.code === 'EEXIST')
-                return await verifyDatabase(destination, signal);
+                return await verifyDatabase(destination, root, signal);
             throw error;
         }
         const directory = await fs.open(root, 'r');

package/dist/host-ledger-sqlite.d.ts

@@ -9,6 +9,7 @@ export interface Stored<T> {
     readonly seq: number;
     readonly record: T;
 }
+export type HostLedgerFormat = 'current' | 'old-sqlite' | 'unrelated' | 'unsupported';
 /** The complete record remains authority; these are only reproducible lookup projections. */
 export declare function ledgerRecordColumns(kind: Kind, input: object): Record<string, SQLInputValue>;
 export declare function initializeLedger(db: DatabaseSync): void;
@@ -28,9 +29,11 @@ export declare function verifyLedger(db: DatabaseSync): {
     presenceRevision: number;
     evidenceRevision: number;
 };
+/** Read the file-type stamp and format version without making the runtime authority. */
+export declare function inspectLedgerIdentity(db: DatabaseSync): HostLedgerFormat;
 /** Explicit offline migration only; the caller owns the write transaction. Preserve all records and revisions. */
 export declare function upgradeLedger(db: DatabaseSync): boolean;
-export declare function migrationRequired(): Error;
+export declare function migrationRequired(root: string): Error;
 /** Transaction-local storage rows; sequence coordinates never cross HostLedgerPort. */
 export declare class LedgerTransaction {
     private readonly db;

package/dist/host-ledger-sqlite.js

@@ -137,6 +137,21 @@ function verifyLedgerAtVersion(db, version) {
         throw invalid('records without revision');
     return { ...counts, presenceRevision: revision.presence, evidenceRevision: revision.evidence };
 }
+function inspectLegacyRoot(root) {
+    return fs.existsSync(path.join(root, 'presence.ndjsonl')) || fs.existsSync(path.join(root, 'evidence.ndjsonl'));
+}
+/** Read the file-type stamp and format version without making the runtime authority. */
+export function inspectLedgerIdentity(db) {
+    const application = db.prepare('PRAGMA application_id').get().application_id;
+    const version = db.prepare('PRAGMA user_version').get().user_version;
+    if (application !== LEDGER_APPLICATION_ID)
+        return 'unrelated';
+    if (version === LEDGER_VERSION)
+        return 'current';
+    if (version === 1)
+        return 'old-sqlite';
+    return 'unsupported';
+}
 /** Explicit offline migration only; the caller owns the write transaction. Preserve all records and revisions. */
 export function upgradeLedger(db) {
     if (db.prepare('PRAGMA user_version').get()?.user_version === LEDGER_VERSION) {
@@ -159,14 +174,26 @@ catch (error) {
         return false;
     throw error;
 } }
-export function migrationRequired() {
-    return new Error('Host ledger conversion required. Stop all ledger users before running:\nsquare ledger migrate');
+export function migrationRequired(root) {
+    return new Error(`Host ledger legacy format needs offline migration at ${root}.\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nRun square ledger migrate from the same environment, then square ledger verify.`);
 }
 /** Compact runtime framing. Full schema, projections and integrity belong to explicit verify. */
 function validateLedgerHeader(db, version = LEDGER_VERSION) {
-    if (db.prepare('PRAGMA application_id').get()?.application_id !== LEDGER_APPLICATION_ID
-        || db.prepare('PRAGMA user_version').get()?.user_version !== version)
-        throw invalid('unsupported identity or version. Stop all ledger users before running:\nsquare ledger migrate');
+    if (db.prepare('PRAGMA application_id').get()?.application_id !== LEDGER_APPLICATION_ID)
+        throw invalid('unrelated identity.');
+    if (db.prepare('PRAGMA user_version').get()?.user_version !== version)
+        throw invalid('unsupported format version.');
+}
+/** The runtime's only upgrade door: a supported old ledger is pointed at explicit migration. */
+function runtimeLedgerHeader(db, root) {
+    try {
+        validateLedgerHeader(db);
+    }
+    catch (error) {
+        if (inspectLedgerIdentity(db) === 'old-sqlite')
+            throw migrationRequired(root);
+        throw error;
+    }
 }
 /** Publish new empty authority only. Never initialize or replace an existing destination. */
 function createEmptyLedger(root) {
@@ -203,8 +230,8 @@ function createEmptyLedger(root) {
 async function openLedger(root, write, signal) {
     const file = path.join(root, LEDGER_FILENAME);
     if (!exists(file)) {
-        if (exists(path.join(root, 'presence.ndjsonl')) || exists(path.join(root, 'evidence.ndjsonl')))
-            throw migrationRequired();
+        if (inspectLegacyRoot(root))
+            throw migrationRequired(root);
         if (!write)
             return undefined;
         if (signal?.aborted)
@@ -318,7 +345,7 @@ export async function withLedger(root, write, select, absent, signal) {
     if (!db)
         return absent;
     try {
-        return await inSqliteTransaction(db, write, () => validateLedgerHeader(db), () => {
+        return await inSqliteTransaction(db, write, () => runtimeLedgerHeader(db, root), () => {
             const rows = new LedgerTransaction(db), result = select(rows);
             rows.commitRevisions();
             return result;
@@ -333,7 +360,7 @@ export async function readLedgerRevisions(root, signal) {
     if (!db)
         return undefined;
     try {
-        return await inSqliteTransaction(db, false, () => validateLedgerHeader(db), () => ledgerRevisions(db), signal);
+        return await inSqliteTransaction(db, false, () => runtimeLedgerHeader(db, root), () => ledgerRevisions(db), signal);
     }
     finally {
         db.close();

package/dist/inbox.d.ts

@@ -36,6 +36,8 @@ export type NativePendingPreviewInput = {
 export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
 export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
 export interface SessionPendingObserver {
+    /** Read committed revisions before reusing content; filesystem hints are only for waiting. */
+    read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<InboxMembership[]>;
     wait(timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;
     close(): void;
 }

package/dist/inbox.js

@@ -109,7 +109,66 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
     const ledger = await hostLedger.observeChanges();
     const artifacts = new Map();
     const lifetime = new AbortController();
+    const bindingsNow = async () => Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
+    async function membershipAt(binding, version, signal) {
+        const cache = artifacts.get(binding.location)?.inbox;
+        const name = nameKey(binding.participant);
+        const coordinate = bindingCoordinate(binding);
+        let cached = cache?.get(name);
+        if (cached === undefined || cached.version !== version || cached.binding !== coordinate) {
+            cached = { ...await readInboxMembership(binding, signal), binding: coordinate };
+            cache?.set(name, cached);
+        }
+        const membership = cached.value;
+        if (membership === undefined)
+            return undefined;
+        const { catchLease, ...rest } = membership;
+        const now = Date.now();
+        return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
+            ? membership : rest;
+    }
+    async function eligibleInbox(inbox, excludeKeys) {
+        const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
+        return excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
+            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex)));
+            return notifications.length === 0 ? [] : [{ ...membership, notifications }];
+        });
+    }
     return {
+        async read(options = {}) {
+            const signal = AbortSignal.any([lifetime.signal, ...(options.signal === undefined ? [] : [options.signal])]);
+            signal.throwIfAborted();
+            const bindings = await bindingsNow();
+            const revisions = new Map();
+            const inbox = [];
+            for (const binding of bindings) {
+                signal.throwIfAborted();
+                try {
+                    let version = revisions.get(binding.location);
+                    if (version === undefined) {
+                        const artifact = createArtifactPort(binding.location);
+                        try {
+                            version = await artifact.revision(signal);
+                        }
+                        finally {
+                            await artifact.close();
+                        }
+                        revisions.set(binding.location, version);
+                    }
+                    const membership = await membershipAt(binding, version, signal);
+                    if (membership !== undefined)
+                        inbox.push(membership);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw signal.reason ?? error;
+                    // An unreadable current revision must never authorize cached content.
+                }
+            }
+            const pending = await eligibleInbox(inbox, options.excludeKeys);
+            signal.throwIfAborted();
+            return pending;
+        },
         async wait(timeoutMs, options = {}) {
             const deadline = Date.now() + Math.max(0, timeoutMs);
             const expired = new AbortController();
@@ -123,7 +182,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                 while (!signal.aborted) {
                     // Subscribe/capture the ledger BEFORE discovering bindings; a concurrent join cannot fall in a gap.
                     const sources = await Promise.all([capture(ledger.presence, 'presence', signal), capture(ledger.evidence, 'evidence', signal)]);
-                    const bindings = await Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
+                    const bindings = await bindingsNow();
                     const paths = new Set(bindings.map((binding) => binding.location));
                     for (const [file, entry] of artifacts) {
                         if (!paths.has(file)) {
@@ -155,22 +214,10 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                     for (const binding of bindings) {
                         if (signal.aborted)
                             return [];
-                        const entry = artifacts.get(binding.location);
-                        const name = nameKey(binding.participant);
                         try {
-                            const coordinate = bindingCoordinate(binding);
-                            const cached = entry.inbox.get(name);
-                            if (cached?.version !== revisions.get(binding.location) || cached?.binding !== coordinate) {
-                                const projection = await readInboxMembership(binding, signal);
-                                entry.inbox.set(name, { ...projection, binding: coordinate });
-                            }
-                            const membership = entry.inbox.get(name)?.value;
-                            if (membership === undefined)
-                                continue;
-                            const { catchLease, ...rest } = membership;
-                            const now = Date.now();
-                            inbox.push(catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
-                                ? membership : rest);
+                            const membership = await membershipAt(binding, revisions.get(binding.location), signal);
+                            if (membership !== undefined)
+                                inbox.push(membership);
                         }
                         catch (error) {
                             if (signal.aborted)
@@ -178,12 +225,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                             // Unreadable projections are retried, never cached as current.
                         }
                     }
-                    const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
-                    const excludeKeys = options.excludeKeys;
-                    const pending = excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
-                        const notifications = membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex)));
-                        return notifications.length === 0 ? [] : [{ ...membership, notifications }];
-                    });
+                    const pending = await eligibleInbox(inbox, options.excludeKeys);
                     const eligibleKeys = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => notificationKey(membership, note.actIndex))).sort());
                     if (previousEligible !== undefined && previousEligible !== eligibleKeys)
                         canReturn = true;

package/dist/mcp.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { SquareApplicationContext } from './square-facade.js';
-export interface SquareMcpOptions extends SquareApplicationContext {
+/** The server owns its artifact connection lifetime, so callers cannot lend one. */
+export interface SquareMcpOptions extends Omit<SquareApplicationContext, 'resources'> {
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;