@astrosheep/square 0.3.69 → 0.3.71

package/dist/artifact.js

@@ -4,196 +4,351 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { isDeepStrictEqual } from 'node:util';
 import { observeFileVersion } from './file-changes.js';
+import { canonicalPath } from './canonical-path.js';
 import { InternalSquareError, SquareError } from './model.js';
-import { validateSquareState } from './square-state.js';
-const APPLICATION_ID = 0x53515245;
-const USER_VERSION = 1;
-const SNAPSHOT_TABLE = 'square_snapshot';
-const SNAPSHOT_DDL = `CREATE TABLE ${SNAPSHOT_TABLE} (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL CHECK(revision>=0), state TEXT NOT NULL)`;
-const SNAPSHOT_COLUMNS = [
-    { cid: 0, name: 'id', type: 'INTEGER', notnull: 0, dflt_value: null, pk: 1, hidden: 0 },
-    { cid: 1, name: 'revision', type: 'INTEGER', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
-    { cid: 2, name: 'state', type: 'TEXT', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
-];
-export { createSquareState, emptyRuntimeState } from './square-state.js';
-function invalidArtifact(detail) {
-    return new SquareError('invalid_args', `Invalid square artifact: ${detail}`);
-}
-function requireSquareExtension(squarePath) {
-    if (!squarePath.endsWith('.square'))
-        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${squarePath}`);
+import { wrapSquareWrite } from './square-domain.js';
+import { APPLICATION_ID, createSqliteDriver, initializeSqlite, exportSqliteState, inspectSqlite, invalidArtifact, validateSqliteHeader, emptyRuntimeState } from './square-sqlite.js';
+const guideContents = new Map();
+function readGuide(name) {
+    if (!['participant', 'architect', 'brainstorm'].includes(name))
+        throw new SquareError('invalid_args', `Unknown square guide: ${name}`);
+    let content = guideContents.get(name);
+    if (content === undefined) {
+        content = fs.readFileSync(new URL(`../guides/${name}.md`, import.meta.url), 'utf8').trim();
+        guideContents.set(name, content);
+    }
+    return content;
+}
+function normalizedLines(value) {
+    const normalized = value.replace(/\r\n/g, '\n').trim();
+    return normalized === '' ? [] : normalized.split('\n');
+}
+/** All build paths share configuration validation and lazy guide preparation. */
+export function prepareSquareBuild(options, snippet) {
+    if (options.hardCap !== undefined && options.hardCap !== null
+        && (!Number.isSafeInteger(options.hardCap) || options.hardCap < 1))
+        throw new SquareError('invalid_args', 'hardCap must be a positive integer or null');
+    if (options.throttlePerMinute !== undefined
+        && (!Number.isSafeInteger(options.throttlePerMinute) || options.throttlePerMinute < 1))
+        throw new SquareError('invalid_args', 'throttlePerMinute must be a positive integer');
+    const guides = [readGuide('participant')];
+    if (options.template !== undefined)
+        guides.push(readGuide(options.template));
+    return {
+        hardCap: options.hardCap ?? null,
+        ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
+        preamble: normalizedLines(snippet), warmup: normalizedLines(guides.join('\n\n')),
+        acts: [], routes: [], runtime: emptyRuntimeState(),
+    };
+}
+/** File build owns publication and CLI conflict semantics, not host resources. */
+export async function createSquare(location, options, snippet, signal) {
+    const state = prepareSquareBuild(options, snippet);
+    if (options.force) {
+        await writeSquareFile(location, state, signal);
+    }
+    else if (!await createSquareFile(location, state, signal)) {
+        throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${location}\nPass -f to overwrite.`);
+    }
+    return { hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }) };
 }
-function isNotFound(error) {
-    return error instanceof Error && /unable to open database file|no such file|SQLITE_CANTOPEN/i.test(error.message);
+function requireSquareExtension(location) {
+    if (!location.endsWith('.square'))
+        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${location}`);
 }
-function isNotADatabase(error) {
-    return error instanceof Error && /not a database|file is not a database|SQLITE_NOTADB/i.test(error.message);
+function isBusy(error) {
+    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
 }
-function openExistingDatabase(squarePath) {
-    const uri = pathToFileURL(path.resolve(squarePath));
+function storageError(error, location) {
+    if (!(error instanceof Error) || error instanceof SquareError || error instanceof InternalSquareError)
+        return error;
+    if (/unable to open database file|no such file|SQLITE_CANTOPEN/i.test(error.message))
+        return new InternalSquareError('not_found', `square file not found: ${location}`);
+    if (/not a database|SQLITE_NOTADB/i.test(error.message))
+        return invalidArtifact('not a SQLite database.');
+    return error;
+}
+/** Private artifact-boundary connection shared with explicit migration. Never creates a path. */
+export function openExistingSquareDatabase(location) {
+    requireSquareExtension(location);
+    const uri = pathToFileURL(path.resolve(location));
     uri.searchParams.set('mode', 'rw');
     try {
         return new DatabaseSync(uri.href);
     }
     catch (error) {
-        if (isNotFound(error))
-            throw new InternalSquareError('not_found', `square file not found: ${squarePath}`);
-        if (isNotADatabase(error))
-            throw invalidArtifact('not a SQLite database.');
-        throw error;
+        throw storageError(error, location);
     }
 }
-function closeQuietly(database) {
-    try {
-        database?.close();
-    }
-    catch { /* closing does not alter the primary failure */ }
+function abort(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Square artifact operation aborted');
 }
-function parseState(state) {
-    if (typeof state !== 'string')
-        throw invalidArtifact('snapshot state is malformed.');
-    try {
-        return validateSquareState(JSON.parse(state));
-    }
-    catch (error) {
-        if (error instanceof SquareError)
-            throw error;
-        throw invalidArtifact('snapshot state is not valid JSON.');
+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 normalizedSql(sql) {
-    return sql.trim().replace(/\s+/g, ' ').replace(/\s*(>=|[(),=])\s*/g, '$1');
-}
-function isOwnedSnapshotSchema(database) {
-    const objects = database.prepare("SELECT type, name, tbl_name, sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' ORDER BY type, name")
-        .all();
-    if (objects.length !== 1)
-        return false;
-    const [object] = objects;
-    if (object.type !== 'table' || object.name !== SNAPSHOT_TABLE || object.tbl_name !== SNAPSHOT_TABLE
-        || typeof object.sql !== 'string' || normalizedSql(object.sql) !== normalizedSql(SNAPSHOT_DDL))
-        return false;
-    const columns = database.prepare('SELECT cid, name, type, "notnull", dflt_value, pk, hidden FROM pragma_table_xinfo(?) ORDER BY cid')
-        .all(SNAPSHOT_TABLE);
-    return columns.length === SNAPSHOT_COLUMNS.length && columns.every((column, index) => {
-        const expected = SNAPSHOT_COLUMNS[index];
-        return column.cid === expected.cid && column.name === expected.name && column.type === expected.type
-            && column.notnull === expected.notnull && column.dflt_value === expected.dflt_value
-            && column.pk === expected.pk && column.hidden === expected.hidden;
-    });
-}
-function validateDatabaseHeader(database) {
-    const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
-    if (identity.application_id !== APPLICATION_ID)
-        throw invalidArtifact('unrelated SQLite database.');
-    if (identity.user_version !== USER_VERSION)
-        throw invalidArtifact('unsupported SQLite format version.');
-    if (!isOwnedSnapshotSchema(database))
-        throw invalidArtifact('unsupported snapshot schema.');
-}
-function validateSnapshotRevision(rows) {
-    if (rows.length !== 1 || rows[0].id !== 1 || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
-        throw invalidArtifact('snapshot row is malformed.');
-    return rows[0].revision;
+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.');
+    }
 }
-function validateDatabase(database) {
+/** 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 {
-        validateDatabaseHeader(database);
-        const rows = database.prepare(`SELECT id, revision, state FROM ${SNAPSHOT_TABLE}`).all();
-        const revision = validateSnapshotRevision(rows);
-        return { state: parseState(rows[0].state), revision };
+        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 (error instanceof SquareError)
-            throw error;
-        if (isNotADatabase(error))
-            throw invalidArtifact('not a SQLite database.');
+        if (begun) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* retain the original failure */ }
+        }
         throw error;
     }
 }
-/** Opens an existing artifact without permitting SQLite to create a missing path. */
-function readExistingArtifact(squarePath, read) {
-    requireSquareExtension(squarePath);
+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',
+];
+const writeMethods = ['applyLanding', 'markSeen', 'putLease', 'removeLease', 'replaceRoutes'];
+/** One connection, ordered operations, guarded synchronous transaction capabilities. */
+export function createArtifactPort(location, initial, externalSignal) {
     let database;
-    try {
-        database = openExistingDatabase(squarePath);
-        return read(database);
-    }
-    catch (error) {
-        if (error instanceof SquareError)
+    let closed = false, inCallback = false;
+    let tail = Promise.resolve();
+    const cancel = new AbortController();
+    const canonical = initial === undefined ? canonicalPath(location) : Promise.resolve(location);
+    if (initial !== undefined) {
+        database = new DatabaseSync(':memory:');
+        try {
+            initializeSqlite(database, initial);
+            database.exec(`PRAGMA application_id=${APPLICATION_ID}; PRAGMA user_version=2`);
+        }
+        catch (error) {
+            database.close();
             throw error;
-        if (isNotFound(error))
-            throw new InternalSquareError('not_found', `square file not found: ${squarePath}`);
-        if (isNotADatabase(error))
-            throw invalidArtifact('not a SQLite database.');
-        throw error;
-    }
-    finally {
-        closeQuietly(database);
+        }
     }
-}
-function readSquareSnapshotOnce(squarePath) {
-    return readExistingArtifact(squarePath, validateDatabase);
-}
-async function createTemporaryArtifact(squarePath) {
-    const directory = path.dirname(squarePath);
-    await fs.promises.mkdir(directory, { recursive: true });
-    while (true) {
-        const temporary = path.join(directory, `.${path.basename(squarePath)}.${process.pid}.${randomUUID()}.tmp`);
+    const combined = (signal) => AbortSignal.any([cancel.signal, ...(externalSignal ? [externalSignal] : []), ...(signal ? [signal] : [])]);
+    const validate = (db) => validateSqliteHeader(db, initial === undefined ? location : ':memory:');
+    async function connection(signal) {
+        if (database)
+            return database;
+        location = await canonical;
+        abort(signal);
+        database = openExistingSquareDatabase(location);
         try {
-            const handle = await fs.promises.open(temporary, 'wx');
-            await handle.close();
-            return temporary;
+            await retrySqliteBusy(() => validate(database), signal);
+            database.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL');
         }
         catch (error) {
-            if (error.code === 'EEXIST')
-                continue;
-            throw error;
+            database.close();
+            database = undefined;
+            throw storageError(error, location);
         }
+        return database;
     }
-}
-async function syncTemporaryArtifact(temporary) {
-    // Windows FlushFileBuffers requires a writable handle; r+ never creates a missing file.
-    const handle = await fs.promises.open(temporary, 'r+');
+    function queue(operation, signal) {
+        if (inCallback)
+            throw new TypeError('Square artifact operations cannot nest inside a callback.');
+        if (closed)
+            return Promise.reject(new Error('Square artifact is closed'));
+        const operationSignal = combined(signal);
+        const result = tail.then(() => {
+            abort(operationSignal);
+            return operation(operationSignal);
+        });
+        tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    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;
+            let active = true, failed = false, failure;
+            function guard(fn) {
+                return ((...args) => {
+                    if (!active)
+                        throw new Error('Square artifact transaction capability expired');
+                    abort(signal);
+                    if (failed)
+                        throw failure;
+                    try {
+                        return fn(...args);
+                    }
+                    catch (error) {
+                        failed = true;
+                        failure = storageError(error, location);
+                        throw failure;
+                    }
+                });
+            }
+            const reads = Object.fromEntries(readMethods.map(name => [name, guard(driver[name])]));
+            const writes = Object.fromEntries(writeMethods.map(name => [name, guard(driver[name])]));
+            const facts = write ? wrapSquareWrite(reads, writes) : reads;
+            let value;
+            inCallback = true;
+            try {
+                value = callback(facts);
+                synchronous(value);
+            }
+            finally {
+                inCallback = false;
+                active = false;
+            }
+            if (failed)
+                throw failure;
+            const changed = write && driver.changed;
+            if (changed) {
+                if (version === Number.MAX_SAFE_INTEGER)
+                    throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
+                db.prepare('UPDATE square_meta SET revision=? WHERE id=1').run(version + 1);
+            }
+            return {
+                value, version: version + Number(changed), changed
+            };
+        }, signal);
+    }
+    const revision = signal => queue(async (s) => {
+        const db = await connection(s);
+        return inSqliteTransaction(db, false, () => validate(db), () => createSqliteDriver(db).header().revision, s);
+    }, signal);
+    return {
+        read: (select, signal) => queue(async (s) => {
+            const { value, version } = await transaction(select, false, s);
+            return { value, version };
+        }, signal),
+        transact: (change, signal) => queue(s => transaction(change, true, s), signal),
+        revision,
+        async changed(since, timeout, signal) {
+            if (inCallback)
+                throw new TypeError('Square artifact operations cannot nest inside a callback.');
+            if (closed)
+                return false;
+            const s = combined(signal), deadline = Date.now() + Math.max(0, timeout);
+            if (initial !== undefined) {
+                try {
+                    do {
+                        if (await revision(s) > since)
+                            return true;
+                        if (Date.now() >= deadline)
+                            return false;
+                        await sleep(Math.min(25, deadline - Date.now()), undefined, { signal: s });
+                    } while (!closed);
+                }
+                catch (error) {
+                    if (closed)
+                        return false;
+                    abort(s);
+                    throw error;
+                }
+                return false;
+            }
+            const observer = await observeSquareRevision(await canonical);
+            try {
+                return await observer.changed(since, Math.max(0, deadline - Date.now()), s);
+            }
+            catch (error) {
+                if (closed)
+                    return false;
+                throw error;
+            }
+            finally {
+                observer.close();
+            }
+        },
+        async close() {
+            if (inCallback)
+                throw new TypeError('Square artifact cannot close inside a callback.');
+            if (closed) {
+                await tail;
+                return;
+            }
+            closed = true;
+            cancel.abort(new Error('Square artifact is closed'));
+            await tail;
+            database?.close();
+            database = undefined;
+        },
+    };
+}
+async function temporaryArtifact(location) {
+    await fs.promises.mkdir(path.dirname(location), { recursive: true });
+    const temporary = path.join(path.dirname(location), `.${path.basename(location)}.${process.pid}.${randomUUID()}.tmp`);
+    const handle = await fs.promises.open(temporary, 'wx');
+    await handle.close();
+    return temporary;
+}
+async function initializeFile(location, state, signal) {
+    const db = new DatabaseSync(location);
     try {
-        await handle.sync();
+        db.exec('PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL');
+        await inSqliteTransaction(db, true, () => { }, () => {
+            initializeSqlite(db, state);
+            db.exec(`PRAGMA application_id=${APPLICATION_ID}; PRAGMA user_version=2`);
+        }, signal);
     }
     finally {
-        await handle.close();
+        db.close();
     }
-}
-function initializeDatabase(squarePath, state) {
-    const encoded = JSON.stringify(state);
-    let database;
+    const handle = await fs.promises.open(location, 'r+');
     try {
-        database = openExistingDatabase(squarePath);
-        database.exec(`PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; BEGIN IMMEDIATE; PRAGMA application_id = ${APPLICATION_ID}; PRAGMA user_version = ${USER_VERSION}; ${SNAPSHOT_DDL};`);
-        database.prepare(`INSERT INTO ${SNAPSHOT_TABLE} (id, revision, state) VALUES (1, 0, ?)`).run(encoded);
-        database.exec('COMMIT;');
-    }
-    catch (error) {
-        try {
-            database?.exec('ROLLBACK;');
-        }
-        catch { /* retain initialization failure */ }
-        throw error;
+        await handle.sync();
     }
     finally {
-        closeQuietly(database);
+        await handle.close();
     }
 }
-/** Creates a new SQLite artifact only when its pathname did not already exist. */
-export async function createSquareFile(squarePath, state) {
-    requireSquareExtension(squarePath);
-    const validated = validateSquareState(state);
-    const temporary = await createTemporaryArtifact(squarePath);
+/** New-format creation; initial authority is accepted only at this explicit boundary. */
+export async function createSquareFile(location, state, signal) {
+    abort(signal);
+    location = await canonicalPath(location);
+    requireSquareExtension(location);
+    const temporary = await temporaryArtifact(location);
     try {
-        initializeDatabase(temporary, validated);
-        await syncTemporaryArtifact(temporary);
+        await initializeFile(temporary, state, signal);
+        abort(signal);
         try {
-            await fs.promises.link(temporary, squarePath);
+            await fs.promises.link(temporary, location);
             return true;
         }
         catch (error) {
@@ -203,197 +358,71 @@ export async function createSquareFile(squarePath, state) {
         }
     }
     finally {
-        try {
-            await fs.promises.unlink(temporary);
-        }
-        catch { /* cleanup cannot invalidate a published artifact */ }
+        await fs.promises.unlink(temporary).catch(() => undefined);
     }
 }
-function isBusy(error) {
-    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
-}
-function isThenable(value) {
-    return (typeof value === 'object' || typeof value === 'function') && value !== null
-        && typeof value.then === 'function';
-}
-function discardThenable(value) {
-    void Promise.resolve(value).catch(() => undefined);
-}
-function closedError() {
-    return new Error('Square artifact is closed');
+/** Explicit build --force / fixture import, never a runtime state-replacement callback. */
+export async function writeSquareFile(location, state, signal) {
+    location = await canonicalPath(location);
+    if (await createSquareFile(location, state, signal))
+        return;
+    abort(signal);
+    const db = openExistingSquareDatabase(location);
+    try {
+        await retrySqliteBusy(() => validateSqliteHeader(db, location), signal);
+        db.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL');
+        await inSqliteTransaction(db, true, () => validateSqliteHeader(db, location), () => {
+            const revision = createSqliteDriver(db).header().revision;
+            if (revision === Number.MAX_SAFE_INTEGER)
+                throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
+            for (const table of ['landed_audience', 'attention', 'participants', 'routes', 'catch_leases', 'receipts', 'activities', 'square_meta'])
+                db.exec(`DROP TABLE ${table}`);
+            initializeSqlite(db, state, revision + 1);
+        }, signal);
+    }
+    finally {
+        db.close();
+    }
 }
-async function pauseForBusy(signal) {
-    if (signal?.aborted)
-        throw signal.reason ?? closedError();
+async function inspectFile(location, select, signal) {
+    const db = openExistingSquareDatabase(location);
     try {
-        await sleep(25, undefined, { signal });
+        return await inSqliteTransaction(db, false, () => validateSqliteHeader(db, location), () => select(db), signal);
     }
     catch (error) {
-        if (signal?.aborted)
-            throw signal.reason ?? closedError();
-        throw error;
+        throw storageError(error, location);
+    }
+    finally {
+        db.close();
     }
 }
-/**
- * Reads a complete validated snapshot, yielding between transient SQLite lock
- * conflicts. The URI remains create-disabled throughout the retry loop.
- */
-export function readSquareSnapshot(squarePath, signal) {
-    return readWithBusyRetry(() => readSquareSnapshotOnce(squarePath), signal);
+/** Explicit test/export projection. Hot callers must use the typed port. */
+export function readSquareSnapshot(location, signal) {
+    return inspectFile(location, db => ({ state: exportSqliteState(db), revision: createSqliteDriver(db).header().revision }), signal);
 }
-/** Check the artifact revision without loading or parsing the historical state. */
-export function readSquareRevision(squarePath, signal) {
-    return readWithBusyRetry(() => readExistingArtifact(squarePath, (database) => {
-        validateDatabaseHeader(database);
-        const rows = database.prepare(`SELECT id, revision FROM ${SNAPSHOT_TABLE}`).all();
-        return validateSnapshotRevision(rows);
-    }), signal);
+export function readSquareRevision(location, signal) {
+    return inspectFile(location, db => createSqliteDriver(db).header().revision, signal);
 }
-/** One reference-counted revision detector per canonical artifact in this process. */
-export function observeSquareRevision(squarePath) {
-    return observeFileVersion(squarePath, 'square-revision', async (file, signal) => {
+export function observeSquareRevision(location) {
+    return observeFileVersion(location, 'square-revision', async (file, signal) => {
         try {
             return await readSquareRevision(file, signal);
         }
         catch (error) {
-            if (signal?.aborted)
-                throw signal.reason ?? error;
+            abort(signal);
             if (error instanceof InternalSquareError && error.code === 'not_found')
                 return null;
             throw error;
         }
     });
 }
-async function readWithBusyRetry(read, signal) {
-    while (true) {
-        if (signal?.aborted)
-            throw signal.reason ?? closedError();
-        try {
-            return read();
-        }
-        catch (error) {
-            if (!isBusy(error))
-                throw error;
-            await pauseForBusy(signal);
-        }
-    }
-}
-/**
- * Executes one synchronous SquareState transition under SQLite's write lock.
- * A busy COMMIT retries on this same transaction, so fn is never replayed.
- */
-export async function transactSquareSnapshot(squarePath, fn, signal, forceCommit = false) {
-    requireSquareExtension(squarePath);
-    let database;
-    let begun = false;
-    try {
-        database = openExistingDatabase(squarePath);
-        // Validate before any persistent pragma can touch an unsupported artifact.
-        while (true) {
-            try {
-                validateDatabase(database);
-                break;
-            }
-            catch (error) {
-                if (!isBusy(error))
-                    throw error;
-                await pauseForBusy(signal);
-            }
-        }
-        while (true) {
-            if (signal?.aborted)
-                throw signal.reason ?? closedError();
-            try {
-                database.exec('PRAGMA busy_timeout = 0; PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL;');
-                database.exec('BEGIN IMMEDIATE;');
-                begun = true;
-                break;
-            }
-            catch (error) {
-                if (!isBusy(error))
-                    throw error;
-                await pauseForBusy(signal);
-            }
-        }
-        const current = validateDatabase(database);
-        const outcome = fn(structuredClone(current.state), current.revision);
-        if (isThenable(outcome)) {
-            discardThenable(outcome);
-            throw new TypeError('Square artifact transitions must be synchronous.');
-        }
-        if (typeof outcome !== 'object' || outcome === null || !Object.hasOwn(outcome, 'result')) {
-            throw new TypeError('Square artifact transition must return { state?, result }.');
-        }
-        if (outcome.state === undefined || (!forceCommit && isDeepStrictEqual(outcome.state, current.state))) {
-            database.exec('ROLLBACK;');
-            begun = false;
-            return { result: outcome.result, revision: current.revision, changed: false };
-        }
-        const state = validateSquareState(outcome.state);
-        if (current.revision === Number.MAX_SAFE_INTEGER) {
-            throw invalidArtifact('snapshot revision cannot advance beyond the safe integer limit.');
-        }
-        const revision = current.revision + 1;
-        database.prepare(`UPDATE ${SNAPSHOT_TABLE} SET revision = ?, state = ? WHERE id = 1`)
-            .run(revision, JSON.stringify(state));
-        while (true) {
-            if (signal?.aborted)
-                throw signal.reason ?? closedError();
-            try {
-                database.exec('COMMIT;');
-                begun = false;
-                return { result: outcome.result, revision, changed: true };
-            }
-            catch (error) {
-                if (!isBusy(error))
-                    throw error;
-                await pauseForBusy(signal);
-            }
-        }
-    }
-    catch (error) {
-        if (begun) {
-            try {
-                database?.exec('ROLLBACK;');
-            }
-            catch { /* retain callback and SQLite failures */ }
-        }
-        throw error;
-    }
-    finally {
-        closeQuietly(database);
-    }
-}
-/** Replaces an existing validated snapshot in place and always advances its revision. */
-export async function replaceSquareSnapshot(squarePath, state) {
-    const replacement = structuredClone(validateSquareState(state));
-    const committed = await transactSquareSnapshot(squarePath, () => ({ state: replacement, result: undefined }), undefined, true);
-    return { state: replacement, revision: committed.revision };
-}
-export async function writeSquareFile(squarePath, squareState) {
-    requireSquareExtension(squarePath);
-    if (await createSquareFile(squarePath, squareState))
-        return;
-    await replaceSquareSnapshot(squarePath, squareState);
-}
-export async function loadSquare(squarePath) {
-    return structuredClone((await readSquareSnapshot(squarePath)).state);
-}
-export async function probeSquare(squarePath) {
-    if (!squarePath.endsWith('.square'))
-        return undefined;
-    try {
-        return structuredClone(readSquareSnapshotOnce(squarePath).state);
-    }
-    catch {
-        return undefined;
-    }
-}
-export async function diagnoseSquareFile(squarePath) {
+export async function diagnoseSquareFile(location) {
     try {
-        return { problems: [], state: await loadSquare(squarePath) };
+        return { problems: [], ...await inspectFile(await canonicalPath(location), inspectSqlite) };
     }
     catch (error) {
+        if (error instanceof SquareError && error.facts?.reason === 'migration_required')
+            return { migrationRequired: error.message, problems: [] };
         return { unfixable: error instanceof Error ? error.message : String(error), problems: [] };
     }
 }