@astrosheep/square 0.3.45 → 0.3.47

package/dist/artifact.js

@@ -1,317 +1,361 @@
-import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { TextDecoder } from 'node:util';
-import zlib from 'node:zlib';
-import { isWakeRouteKind, InternalSquareError, SquareError, } from './model.js';
-import { parseActivityId } from './square-core.js';
-const SQUARE_MAGIC = Buffer.from('SQUARE01', 'ascii');
-const LENGTH_BYTES = 4;
-const DIGEST_BYTES = 32;
-const HEADER_BYTES = SQUARE_MAGIC.length + LENGTH_BYTES + DIGEST_BYTES;
-const utf8 = new TextDecoder('utf-8', { fatal: true });
-const guideNames = ['participant', 'architect', 'brainstorm'];
-const guideContents = new Map(await Promise.all(guideNames.map(async (name) => [name, (await fs.promises.readFile(new URL(`../guides/${name}.md`, import.meta.url), 'utf8')).trim()])));
+import { pathToFileURL } from 'node:url';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
+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 isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function hasExactKeys(value, required, optional = []) {
-    const allowed = new Set([...required, ...optional]);
-    return required.every((key) => Object.hasOwn(value, key))
-        && Object.keys(value).every((key) => allowed.has(key));
-}
-function isFiniteNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value);
-}
-function isNonNegativeInteger(value) {
-    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
-}
-function isNonblankString(value) {
-    return typeof value === 'string' && value.length > 0;
+function requireSquareExtension(squarePath) {
+    if (!squarePath.endsWith('.square'))
+        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${squarePath}`);
 }
-function isStringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+function isNotFound(error) {
+    return error instanceof Error && /unable to open database file|no such file|SQLITE_CANTOPEN/i.test(error.message);
 }
-function validateObservation(value) {
-    return isObject(value)
-        && hasExactKeys(value, ['state', 'at'])
-        && value.state === 'seen'
-        && isFiniteNumber(value.at);
+function isNotADatabase(error) {
+    return error instanceof Error && /not a database|file is not a database|SQLITE_NOTADB/i.test(error.message);
 }
-function validateWatchLease(value) {
-    if (!isObject(value)
-        || !hasExactKeys(value, ['leaseId', 'heartbeatAt', 'expiresAt'], ['filter'])
-        || !isNonblankString(value.leaseId)
-        || !isFiniteNumber(value.heartbeatAt)
-        || !isFiniteNumber(value.expiresAt)
-        || value.expiresAt < value.heartbeatAt)
-        return false;
-    if (value.filter === undefined)
-        return true;
-    return isObject(value.filter)
-        && hasExactKeys(value.filter, [], ['participants', 'mention'])
-        && (value.filter.participants === undefined || isStringArray(value.filter.participants))
-        && (value.filter.mention === undefined || typeof value.filter.mention === 'string');
+function existingDatabaseUri(squarePath) {
+    const uri = pathToFileURL(path.resolve(squarePath));
+    uri.searchParams.set('mode', 'rw');
+    return uri.href;
 }
-function validateRecord(value, item) {
-    return isObject(value)
-        && Object.entries(value).every(([key, candidate]) => key.length > 0 && item(candidate));
+function openExistingDatabase(squarePath) {
+    try {
+        return new DatabaseSync(existingDatabaseUri(squarePath));
+    }
+    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;
+    }
 }
-function validateRuntime(value) {
-    if (!isObject(value)
-        || !hasExactKeys(value, ['nextActIndex', 'observations', 'leases'])
-        || !isNonNegativeInteger(value.nextActIndex)
-        || !validateRecord(value.observations, (candidate) => isObject(candidate) && Object.entries(candidate).every(([id, observation]) => parseActivityId(id) !== undefined && validateObservation(observation)))
-        || !validateRecord(value.leases, validateWatchLease))
-        return false;
-    return true;
+function closeQuietly(database) {
+    try {
+        database?.close();
+    }
+    catch { /* closing does not alter the primary failure */ }
 }
-function validateAssignedRuntimeReferences(runtime) {
-    const bound = runtime.nextActIndex;
-    for (const observations of Object.values(runtime.observations)) {
-        for (const id of Object.keys(observations)) {
-            const index = parseActivityId(id);
-            if (index === undefined)
-                return 'malformed';
-            if (index >= bound)
-                return 'future';
-        }
+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.');
     }
-    return 'ok';
 }
-function validateActor(value, required) {
-    return required ? isNonblankString(value) : value === undefined || isNonblankString(value);
+function normalizedSql(sql) {
+    return sql.trim().replace(/\s+/g, ' ').replace(/\s*(>=|[(),=])\s*/g, '$1');
 }
-function validateStoredAct(value) {
-    if (!isObject(value)
-        || typeof value.kind !== 'string'
-        || !isNonNegativeInteger(value.index)
-        || !isFiniteNumber(value.at))
+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;
-    switch (value.kind) {
-        case 'join':
-            return hasExactKeys(value, ['kind', 'actor', 'at', 'index']) && validateActor(value.actor, true);
-        case 'done':
-            return hasExactKeys(value, ['kind', 'actor', 'at', 'index'], ['body'])
-                && validateActor(value.actor, true)
-                && (value.body === undefined || typeof value.body === 'string');
-        case 'say':
-            return hasExactKeys(value, ['kind', 'actor', 'at', 'body', 'index'], ['mentions', 'reach', 'reply'])
-                && validateActor(value.actor, true)
-                && typeof value.body === 'string'
-                && (value.mentions === undefined || isStringArray(value.mentions))
-                && (value.reach === undefined || value.reach === 'bell')
-                && (value.reply === undefined || isNonNegativeInteger(value.reply));
-        case 'hold':
-            return hasExactKeys(value, ['kind', 'at', 'index'], ['actor', 'body'])
-                && validateActor(value.actor, false)
-                && (value.body === undefined || typeof value.body === 'string');
-        case 'resume':
-            return hasExactKeys(value, ['kind', 'at', 'index'], ['actor']) && validateActor(value.actor, false);
-        case 'read':
-            return hasExactKeys(value, ['kind', 'actor', 'at', 'through', 'index'])
-                && validateActor(value.actor, true)
-                && isNonNegativeInteger(value.through);
-        case 'listen':
-        case 'ignore':
-            return hasExactKeys(value, ['kind', 'actor', 'target', 'at', 'index'])
-                && validateActor(value.actor, true)
-                && validateActor(value.target, true);
-        default:
-            return false;
-    }
-}
-function validateActs(value) {
-    if (!Array.isArray(value) || !value.every(validateStoredAct))
+    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;
-    let previous = -1;
-    for (const act of value) {
-        if (act.index <= previous)
-            return false;
-        if (act.kind === 'say' && act.reply !== undefined && act.reply >= act.index)
-            return false;
-        previous = act.index;
-    }
-    return true;
+    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 validateSquareState(value) {
-    if (!isObject(value)
-        || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute', 'routes'])
-        || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
-        || (value.throttlePerMinute !== undefined
-            && (!Number.isSafeInteger(value.throttlePerMinute) || value.throttlePerMinute <= 0))
-        || !isStringArray(value.preamble)
-        || !isStringArray(value.warmup)
-        || !validateActs(value.acts)
-        || (value.routes !== undefined && (!Array.isArray(value.routes) || !value.routes.every((route) => isObject(route) && isWakeRouteKind(route.kind) && typeof route.location === 'string' && typeof route.participant === 'string' && typeof route.sessionId === 'string' && typeof route.channel === 'string' && isObject(route.address) && Object.values(route.address).every((item) => typeof item === 'string') && typeof route.updatedAt === 'number')))
-        || !validateRuntime(value.runtime)) {
-        throw invalidArtifact('snapshot schema is malformed.');
+function validateDatabase(database) {
+    try {
+        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.');
+        const rows = database.prepare(`SELECT id, revision, state FROM ${SNAPSHOT_TABLE}`).all();
+        if (rows.length !== 1 || rows[0].id !== 1 || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
+            throw invalidArtifact('snapshot row is malformed.');
+        return { state: parseState(rows[0].state), revision: rows[0].revision };
     }
-    const acts = value.acts;
-    const runtime = value.runtime;
-    const historyBoundary = acts.at(-1)?.index ?? -1;
-    if (runtime.nextActIndex <= historyBoundary) {
-        throw invalidArtifact('nextActIndex is behind the activity history.');
+    catch (error) {
+        if (error instanceof SquareError)
+            throw error;
+        if (isNotADatabase(error))
+            throw invalidArtifact('not a SQLite database.');
+        throw error;
     }
-    const references = validateAssignedRuntimeReferences(runtime);
-    if (references === 'malformed')
-        throw invalidArtifact('snapshot schema is malformed.');
-    if (references === 'future')
-        throw invalidArtifact('runtime references an unassigned activity index.');
-    return value;
 }
-function encodeEnvelope(magic, value) {
-    const json = Buffer.from(JSON.stringify(value), 'utf8');
-    const payload = zlib.gzipSync(json, { level: 9 });
-    if (payload.length > 0xffff_ffff)
-        throw invalidArtifact('compressed payload is too large.');
-    const header = Buffer.alloc(HEADER_BYTES);
-    magic.copy(header, 0);
-    header.writeUInt32BE(payload.length, magic.length);
-    crypto.createHash('sha256').update(payload).digest().copy(header, magic.length + LENGTH_BYTES);
-    return Buffer.concat([header, payload]);
+function configureDatabase(database) {
+    database.exec('PRAGMA busy_timeout = 0; PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL;');
 }
-function decodeEnvelope(bytes, magic) {
-    if (bytes.length < HEADER_BYTES)
-        throw invalidArtifact('truncated header.');
-    if (!bytes.subarray(0, magic.length).equals(magic))
-        throw invalidArtifact('bad magic or unsupported format version.');
-    const length = bytes.readUInt32BE(magic.length);
-    if (bytes.length !== HEADER_BYTES + length)
-        throw invalidArtifact('payload length does not match the file.');
-    const expected = bytes.subarray(magic.length + LENGTH_BYTES, HEADER_BYTES);
-    const payload = bytes.subarray(HEADER_BYTES);
-    const actual = crypto.createHash('sha256').update(payload).digest();
-    if (!crypto.timingSafeEqual(expected, actual))
-        throw invalidArtifact('payload digest mismatch.');
-    let inflated;
+/** Opens an existing artifact without permitting SQLite to create a missing path. */
+function readSquareSnapshotOnce(squarePath) {
+    requireSquareExtension(squarePath);
+    let database;
     try {
-        inflated = zlib.gunzipSync(payload);
+        database = openExistingDatabase(squarePath);
+        return validateDatabase(database);
     }
-    catch {
-        throw invalidArtifact('payload is not valid gzip data.');
+    catch (error) {
+        if (error instanceof SquareError)
+            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;
     }
-    let text;
-    try {
-        text = utf8.decode(inflated);
+    finally {
+        closeQuietly(database);
     }
-    catch {
-        throw invalidArtifact('payload is not valid UTF-8.');
+}
+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`);
+        try {
+            const handle = await fs.promises.open(temporary, 'wx');
+            await handle.close();
+            return temporary;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                continue;
+            throw error;
+        }
     }
+}
+async function syncTemporaryArtifact(temporary) {
+    // Windows FlushFileBuffers requires a writable handle; r+ never creates a missing file.
+    const handle = await fs.promises.open(temporary, 'r+');
     try {
-        return JSON.parse(text);
+        await handle.sync();
     }
-    catch {
-        throw invalidArtifact('payload is not valid JSON.');
+    finally {
+        await handle.close();
     }
 }
-export function emptyRuntimeState(nextActIndex = 0) {
-    return {
-        nextActIndex,
-        observations: {},
-        leases: {},
-    };
-}
-function normalizedLines(value) {
-    const normalized = value.replace(/\r\n/g, '\n').trim();
-    return normalized === '' ? [] : normalized.split('\n');
+async function removeTemporaryArtifact(temporary) {
+    try {
+        await fs.promises.unlink(temporary);
+    }
+    catch { /* cleanup cannot invalidate a published artifact */ }
 }
-function readGuide(name) {
+function initializeDatabase(squarePath, state) {
+    const encoded = JSON.stringify(state);
+    let database;
     try {
-        const guide = guideContents.get(name);
-        if (guide === undefined)
-            throw Object.assign(new Error('missing guide'), { code: 'ENOENT' });
-        return guide;
+        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) {
-        if (error.code === 'ENOENT') {
-            throw new SquareError('invalid_args', `Unknown square guide: ${name}`);
+        try {
+            database?.exec('ROLLBACK;');
         }
+        catch { /* retain initialization failure */ }
         throw error;
     }
+    finally {
+        closeQuietly(database);
+    }
+}
+/** 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);
+    try {
+        initializeDatabase(temporary, validated);
+        await syncTemporaryArtifact(temporary);
+        try {
+            await fs.promises.link(temporary, squarePath);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        await removeTemporaryArtifact(temporary);
+    }
 }
-export function createSquareState(options, snippet) {
-    const guides = [readGuide('participant')];
-    if (options.template !== undefined)
-        guides.push(readGuide(options.template));
-    return {
-        hardCap: options.hardCap,
-        ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
-        preamble: normalizedLines(snippet),
-        warmup: normalizedLines(guides.join('\n\n')),
-        acts: [],
-        routes: [],
-        runtime: emptyRuntimeState(),
-    };
+function isBusy(error) {
+    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
 }
-export function encodeSquare(squareState) {
-    return encodeEnvelope(SQUARE_MAGIC, validateSquareState(squareState));
+function isThenable(value) {
+    return (typeof value === 'object' || typeof value === 'function') && value !== null
+        && typeof value.then === 'function';
 }
-export function decodeSquare(bytes) {
-    return validateSquareState(decodeEnvelope(bytes, SQUARE_MAGIC));
+function discardThenable(value) {
+    void Promise.resolve(value).catch(() => undefined);
 }
-async function readArtifact(squarePath) {
+function closedError() {
+    return new Error('Square artifact is closed');
+}
+async function pauseForBusy(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? closedError();
     try {
-        return await fs.promises.readFile(squarePath);
+        await sleep(25, undefined, { signal });
     }
     catch (error) {
-        if (error.code === 'ENOENT') {
-            throw new InternalSquareError('not_found', `square file not found: ${squarePath}`);
-        }
+        if (signal?.aborted)
+            throw signal.reason ?? closedError();
         throw error;
     }
 }
-function requireSquareExtension(squarePath) {
-    if (!squarePath.endsWith('.square')) {
-        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${squarePath}`);
+/**
+ * Reads a complete validated snapshot, yielding between transient SQLite lock
+ * conflicts. The URI remains create-disabled throughout the retry loop.
+ */
+export async function readSquareSnapshot(squarePath, signal) {
+    while (true) {
+        if (signal?.aborted)
+            throw signal.reason ?? closedError();
+        try {
+            return readSquareSnapshotOnce(squarePath);
+        }
+        catch (error) {
+            if (!isBusy(error))
+                throw error;
+            await pauseForBusy(signal);
+        }
     }
 }
-async function atomicWrite(target, bytes) {
-    const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-    await fs.promises.mkdir(path.dirname(target), { recursive: true });
+/**
+ * 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 {
-        await fs.promises.writeFile(temporary, bytes);
-        await fs.promises.rename(temporary, target);
+        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 {
+                configureDatabase(database);
+                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) {
-        try {
-            await fs.promises.unlink(temporary);
+        if (begun) {
+            try {
+                database?.exec('ROLLBACK;');
+            }
+            catch { /* retain callback and SQLite failures */ }
         }
-        catch { }
         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);
-    await atomicWrite(squarePath, encodeSquare(squareState));
+    if (await createSquareFile(squarePath, squareState))
+        return;
+    await replaceSquareSnapshot(squarePath, squareState);
 }
 export async function loadSquare(squarePath) {
-    requireSquareExtension(squarePath);
-    return decodeSquare(await readArtifact(squarePath));
+    return structuredClone((await readSquareSnapshot(squarePath)).state);
 }
 export async function probeSquare(squarePath) {
     if (!squarePath.endsWith('.square'))
         return undefined;
-    let descriptor;
-    try {
-        descriptor = await fs.promises.open(squarePath, 'r');
-        const magic = Buffer.alloc(SQUARE_MAGIC.length);
-        if ((await descriptor.read(magic, 0, magic.length, 0)).bytesRead !== magic.length || !magic.equals(SQUARE_MAGIC)) {
-            return undefined;
-        }
-    }
-    catch {
-        return undefined;
-    }
-    finally {
-        if (descriptor !== undefined)
-            await descriptor.close();
-    }
     try {
-        return await loadSquare(squarePath);
+        return structuredClone(readSquareSnapshotOnce(squarePath).state);
     }
     catch {
         return undefined;
@@ -322,9 +366,6 @@ export async function diagnoseSquareFile(squarePath) {
         return { problems: [], state: await loadSquare(squarePath) };
     }
     catch (error) {
-        return {
-            unfixable: error instanceof Error ? error.message : String(error),
-            problems: [],
-        };
+        return { unfixable: error instanceof Error ? error.message : String(error), problems: [] };
     }
 }

package/dist/catch-decisions.d.ts

@@ -1,4 +1,5 @@
 import { type Perception } from './square-core.js';
+import { type PerceptionProjection } from './perception-projection.js';
 import { type SquareState, type StoredAct } from './model.js';
 import type { CatchOptions } from './square-facade.js';
 export interface CatchDecision {
@@ -11,11 +12,6 @@ export interface CatchDecision {
 }
 export declare const CATCH_DEFAULT_LIMIT = 10;
 export declare const CATCH_MAX_LIMIT = 100;
-export interface CatchProjection {
-    cursorFor(name: string): number;
-    directedTo(activity: StoredAct, name: string): boolean;
-    perceive(activity: StoredAct, name: string): Perception;
-    isSeen(name: string, index: number): boolean;
-}
+export type CatchProjection = Pick<PerceptionProjection, 'cursorFor' | 'directedTo' | 'perceive' | 'isSeen'>;
 /** Pure catch selection and acknowledgement over one SquareState snapshot. */
 export declare function decideCatch(state: SquareState, requestedName: string, options: CatchOptions, at: number, project?: (state: SquareState) => CatchProjection): CatchDecision;