@astrosheep/square 0.3.45 → 0.3.46

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.45",
+  "version": "0.3.46",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.45",
+  "version": "0.3.46",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/artifact.d.ts

@@ -1,4 +1,5 @@
-import { type BuildOptions, type HardCap, type SquareState, type SquareRuntimeState } from './model.js';
+import { type SquareState } from './model.js';
+export { createSquareState, emptyRuntimeState } from './square-state.js';
 export interface DoctorProblem {
     kind: string;
     message: string;
@@ -8,12 +9,32 @@ export interface DiagnoseResult {
     problems: DoctorProblem[];
     state?: SquareState;
 }
-export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
-export declare function createSquareState(options: BuildOptions & {
-    hardCap: HardCap;
-}, snippet: string): SquareState;
-export declare function encodeSquare(squareState: SquareState): Buffer;
-export declare function decodeSquare(bytes: Buffer): SquareState;
+export interface SquareSnapshot {
+    readonly state: SquareState;
+    readonly revision: number;
+}
+/** Creates a new SQLite artifact only when its pathname did not already exist. */
+export declare function createSquareFile(squarePath: string, state: SquareState): Promise<boolean>;
+/**
+ * Reads a complete validated snapshot, yielding between transient SQLite lock
+ * conflicts. The URI remains create-disabled throughout the retry loop.
+ */
+export declare function readSquareSnapshot(squarePath: string, signal?: AbortSignal): Promise<SquareSnapshot>;
+export type SquareTransition<R> = (state: SquareState, revision: number) => {
+    state?: SquareState;
+    result: R;
+};
+/**
+ * Executes one synchronous SquareState transition under SQLite's write lock.
+ * A busy COMMIT retries on this same transaction, so fn is never replayed.
+ */
+export declare function transactSquareSnapshot<R>(squarePath: string, fn: SquareTransition<R>, signal?: AbortSignal, forceCommit?: boolean): Promise<{
+    result: R;
+    revision: number;
+    changed: boolean;
+}>;
+/** Replaces an existing validated snapshot in place and always advances its revision. */
+export declare function replaceSquareSnapshot(squarePath: string, state: SquareState): Promise<SquareSnapshot>;
 export declare function writeSquareFile(squarePath: string, squareState: SquareState): Promise<void>;
 export declare function loadSquare(squarePath: string): Promise<SquareState>;
 export declare function probeSquare(squarePath: string): Promise<SquareState | undefined>;

package/dist/artifact.js

@@ -1,317 +1,360 @@
-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) {
+    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 +365,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/help.js

@@ -70,7 +70,7 @@ const COMMANDS = [
     },
     {
         names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
-        summary: 'Validate binary artifact integrity.',
+        summary: 'Validate artifact integrity.',
     },
 ];
 function definitionFor(command) {

package/dist/ports.d.ts

@@ -11,10 +11,7 @@ export interface SquareArtifactPort {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    } | Promise<{
-        state?: SquareState;
-        result: R;
-    }>): Promise<R>;
+    }): Promise<R>;
     changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
     close(): Promise<void>;
 }

package/dist/square-file-adapter.js

@@ -1,17 +1,18 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { createSquareState, probeSquareFile, writeSquareSnapshot, withSquareFileLock, openSquareCell, createMemoryCell, } from './square-storage.js';
+import { createSquareState, createSquareSnapshot, probeSquareFile, writeSquareSnapshot, openSquareCell, createMemoryCell, } from './square-storage.js';
 import { InternalSquareError, SquareError, } from './model.js';
 import { closeOpenSquare } from './open-square.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export async function createSquare(squarePath, options, snippet) {
-    await withSquareFileLock(squarePath, async () => {
-        if (await fs.promises.access(squarePath).then(() => true, () => false) && !options.force) {
-            throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
-        }
-        await writeSquareSnapshot(squarePath, await createSquareState(options, snippet));
-    });
+    const state = createSquareState(options, snippet);
+    if (options.force) {
+        await writeSquareSnapshot(squarePath, state);
+        return;
+    }
+    if (!await createSquareSnapshot(squarePath, state)) {
+        throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
+    }
 }
 function validateBuildOptions(options) {
     if (options.hardCap !== undefined && options.hardCap !== null

package/dist/square-state.d.ts

@@ -0,0 +1,6 @@
+import { type BuildOptions, type HardCap, type SquareRuntimeState, type SquareState } from './model.js';
+export declare function validateSquareState(value: unknown): SquareState;
+export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
+export declare function createSquareState(options: BuildOptions & {
+    hardCap: HardCap;
+}, snippet: string): SquareState;

package/dist/square-state.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import { isWakeRouteKind, SquareError, } from './model.js';
+import { parseActivityId } from './square-core.js';
+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()])));
+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 isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validateObservation(value) {
+    return isObject(value) && hasExactKeys(value, ['state', 'at']) && value.state === 'seen' && isFiniteNumber(value.at);
+}
+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 validateRecord(value, item) {
+    return isObject(value) && Object.entries(value).every(([key, candidate]) => key.length > 0 && item(candidate));
+}
+function validateRuntime(value) {
+    return 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);
+}
+function validateAssignedRuntimeReferences(runtime) {
+    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 >= runtime.nextActIndex)
+                return 'future';
+        }
+    }
+    return 'ok';
+}
+function validateActor(value, required) {
+    return required ? isNonblankString(value) : value === undefined || isNonblankString(value);
+}
+function validateStoredAct(value) {
+    if (!isObject(value) || typeof value.kind !== 'string' || !isNonNegativeInteger(value.index) || !isFiniteNumber(value.at))
+        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))
+        return false;
+    let previous = -1;
+    for (const act of value) {
+        if (act.index <= previous || (act.kind === 'say' && act.reply !== undefined && act.reply >= act.index))
+            return false;
+        previous = act.index;
+    }
+    return true;
+}
+export 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.');
+    const historyBoundary = value.acts.at(-1)?.index ?? -1;
+    if (value.runtime.nextActIndex <= historyBoundary)
+        throw invalidArtifact('nextActIndex is behind the activity history.');
+    const references = validateAssignedRuntimeReferences(value.runtime);
+    if (references === 'malformed')
+        throw invalidArtifact('snapshot schema is malformed.');
+    if (references === 'future')
+        throw invalidArtifact('runtime references an unassigned activity index.');
+    return value;
+}
+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');
+}
+function readGuide(name) {
+    const guide = guideContents.get(name);
+    if (guide === undefined)
+        throw new SquareError('invalid_args', `Unknown square guide: ${name}`);
+    return guide;
+}
+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(),
+    };
+}

package/dist/square-storage.d.ts

@@ -1,20 +1,17 @@
 import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile } from './artifact.js';
+import type { SquareState } from './model.js';
 import type { StateCell } from './state-cell.js';
-import { type SquareState } from './model.js';
-/**
- * The only production module allowed to cross the .square byte boundary.
- * Consumers receive a SquareState and never need to know which codec or lock
- * protects it.
- */
-export { createSquareState, };
+export { createSquareState };
 export declare function readSquareFile(squarePath: string): Promise<SquareState>;
 export declare function probeSquareFile(squarePath: string): Promise<SquareState | undefined>;
 export declare function diagnoseSquareFile(squarePath: string): ReturnType<typeof diagnoseArtifactFile>;
+/** Test-helper snapshot replacement backed by one SQLite artifact. */
 export declare function writeSquareSnapshot(squarePath: string, squareState: SquareState): Promise<void>;
-export declare function withSquareFileLock<T>(squarePath: string, fn: () => T | Promise<T>): Promise<T>;
+/** Race-safe non-force creation for the file adapter. */
+export declare function createSquareSnapshot(squarePath: string, squareState: SquareState): Promise<boolean>;
 /** In-process cell for fast behavior tests and embedded consumers. */
 export declare function createMemoryCell(initial: SquareState): StateCell;
-/** File-backed cell retaining the existing .square codec and lock boundary. */
+/** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
 export declare function createFileCell(squarePath: string): StateCell;
-/** Consumer-facing file cell factory; keeps storage choice behind this module. */
+/** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
 export declare function openSquareCell(squarePath: string): StateCell;

package/dist/square-storage.js

@@ -1,15 +1,9 @@
-import { setTimeout as sleep } from 'node:timers/promises';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, writeSquareFile, } from './artifact.js';
-import { withFileLock } from './file-lock.js';
-import { LOCK_RETRY_MS } from './runtime.js';
-/**
- * The only production module allowed to cross the .square byte boundary.
- * Consumers receive a SquareState and never need to know which codec or lock
- * protects it.
- */
-export { createSquareState, };
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { createSquareFile, createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, readSquareSnapshot, transactSquareSnapshot, writeSquareFile, } from './artifact.js';
+export { createSquareState };
 async function canonicalPath(squarePath) {
     const absolute = path.resolve(squarePath);
     try {
@@ -22,49 +16,24 @@ async function canonicalPath(squarePath) {
         return path.join(parent, path.basename(absolute));
     }
 }
-async function squareFileExists(squarePath) {
-    try {
-        await fs.promises.access(squarePath);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
-}
-async function withSquareFileReadLock(squarePath, fn) {
-    if (!await squareFileExists(squarePath))
-        return fn();
-    try {
-        return await withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, createParent: false }, fn);
-    }
-    catch (error) {
-        if (!await squareFileExists(squarePath))
-            return fn();
-        throw error;
-    }
-}
 export async function readSquareFile(squarePath) {
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => loadSquare(canonical));
+    return loadSquare(await canonicalPath(squarePath));
 }
 export async function probeSquareFile(squarePath) {
     if (!squarePath.endsWith('.square'))
         return undefined;
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => probeSquare(canonical));
+    return probeSquare(await canonicalPath(squarePath));
 }
 export async function diagnoseSquareFile(squarePath) {
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => diagnoseArtifactFile(canonical));
+    return diagnoseArtifactFile(await canonicalPath(squarePath));
 }
+/** Test-helper snapshot replacement backed by one SQLite artifact. */
 export async function writeSquareSnapshot(squarePath, squareState) {
     await writeSquareFile(await canonicalPath(squarePath), squareState);
 }
-export async function withSquareFileLock(squarePath, fn) {
-    const canonical = await canonicalPath(squarePath);
-    return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, fn);
+/** Race-safe non-force creation for the file adapter. */
+export async function createSquareSnapshot(squarePath, squareState) {
+    return createSquareFile(await canonicalPath(squarePath), squareState);
 }
 function cloneState(squareState) {
     return structuredClone(squareState);
@@ -73,6 +42,16 @@ function assertCellOpen(closed) {
     if (closed)
         throw new Error('StateCell is closed');
 }
+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 isBusy(error) {
+    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
+}
 /** In-process cell for fast behavior tests and embedded consumers. */
 export function createMemoryCell(initial) {
     let state = cloneState(initial);
@@ -89,15 +68,21 @@ export function createMemoryCell(initial) {
             waiter.resolve(true);
         }
     }
-    const cell = {
+    return {
         transact(fn) {
             assertCellOpen(closed);
-            let operation;
-            operation = tail.then(() => {
+            const operation = tail.then(() => {
                 assertCellOpen(closed);
-                const working = cloneState(state);
-                const outcome = fn(working, version);
-                if (outcome.state !== undefined) {
+                const current = cloneState(state);
+                const outcome = fn(current, version);
+                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 && !isDeepStrictEqual(outcome.state, state)) {
                     state = cloneState(outcome.state);
                     version += 1;
                     publish();
@@ -110,6 +95,7 @@ export function createMemoryCell(initial) {
         async read() {
             assertCellOpen(closed);
             await tail;
+            assertCellOpen(closed);
             return { state: cloneState(state), version };
         },
         changed(sinceVersion, timeoutMs) {
@@ -122,10 +108,7 @@ export function createMemoryCell(initial) {
                 const waiter = {
                     since: sinceVersion,
                     resolve,
-                    timer: setTimeout(() => {
-                        waiters.delete(waiter);
-                        resolve(false);
-                    }, timeoutMs),
+                    timer: setTimeout(() => { waiters.delete(waiter); resolve(false); }, timeoutMs),
                 };
                 waiters.add(waiter);
             });
@@ -142,93 +125,79 @@ export function createMemoryCell(initial) {
             }
         },
     };
-    return cell;
-}
-async function fileFingerprint(squarePath) {
-    try {
-        const stat = await fs.promises.stat(squarePath);
-        return `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
-    }
-    catch {
-        return 'missing';
-    }
 }
-/** File-backed cell retaining the existing .square codec and lock boundary. */
+/** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
 export function createFileCell(squarePath) {
     let closed = false;
-    let version = 0;
-    let fingerprint;
-    let cached;
-    let canonicalSquarePath;
-    async function storagePath() {
-        canonicalSquarePath ??= await canonicalPath(squarePath);
-        return canonicalSquarePath;
-    }
-    async function observe() {
-        const next = await fileFingerprint(await storagePath());
-        if (fingerprint === undefined) {
-            fingerprint = next;
-        }
-        else if (next !== fingerprint) {
-            fingerprint = next;
-            cached = undefined;
-            version += 1;
-        }
-        return fingerprint;
+    let storage;
+    let tail = Promise.resolve();
+    const cancel = new AbortController();
+    function storagePath() {
+        storage ??= canonicalPath(squarePath);
+        return storage;
     }
-    async function currentStateUnderLock() {
-        const observed = await observe();
-        if (cached?.fingerprint === observed)
-            return cloneState(cached.state);
-        const decoded = await loadSquare(await storagePath());
-        cached = { fingerprint: observed, state: cloneState(decoded) };
-        return cloneState(cached.state);
+    function abortError() {
+        return new Error('StateCell is closed');
     }
     return {
-        async transact(fn) {
+        transact(fn) {
             assertCellOpen(closed);
-            const canonical = await storagePath();
-            return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, async () => {
+            const operation = tail.then(async () => {
                 assertCellOpen(closed);
-                const current = await currentStateUnderLock();
-                const working = cloneState(current);
-                const outcome = fn(working, version);
-                if (outcome.state !== undefined) {
-                    await writeSquareFile(canonical, outcome.state);
-                    fingerprint = await fileFingerprint(canonical);
-                    cached = { fingerprint, state: cloneState(outcome.state) };
-                    version += 1;
-                }
-                return outcome.result;
+                const result = await transactSquareSnapshot(await storagePath(), fn, cancel.signal);
+                return result.result;
             });
+            tail = operation.then(() => undefined, () => undefined);
+            return operation;
         },
         async read() {
             assertCellOpen(closed);
-            return withSquareFileReadLock(await storagePath(), async () => {
-                assertCellOpen(closed);
-                return { state: await currentStateUnderLock(), version };
-            });
+            await tail;
+            assertCellOpen(closed);
+            const snapshot = await readSquareSnapshot(await storagePath(), cancel.signal);
+            return { state: cloneState(snapshot.state), version: snapshot.revision };
         },
         async changed(sinceVersion, timeoutMs) {
             assertCellOpen(closed);
             const deadline = Date.now() + Math.max(0, timeoutMs);
-            while (true) {
-                await observe();
-                if (version > sinceVersion)
-                    return true;
+            while (!closed) {
                 const remaining = deadline - Date.now();
-                if (remaining <= 0)
+                const timeout = AbortSignal.timeout(Math.max(1, remaining));
+                const readSignal = AbortSignal.any([cancel.signal, timeout]);
+                try {
+                    if ((await readSquareSnapshot(await storagePath(), readSignal)).revision > sinceVersion)
+                        return true;
+                }
+                catch (error) {
+                    if (closed || cancel.signal.aborted || timeout.aborted)
+                        return false;
+                    if (!isBusy(error))
+                        throw error;
+                }
+                const nextRemaining = deadline - Date.now();
+                if (nextRemaining <= 0)
                     return false;
-                await sleep(Math.min(25, remaining));
-                assertCellOpen(closed);
+                try {
+                    await sleep(Math.min(25, nextRemaining), undefined, { signal: cancel.signal });
+                }
+                catch (error) {
+                    if (closed || cancel.signal.aborted)
+                        return false;
+                    throw error;
+                }
             }
+            return false;
         },
         async close() {
+            if (closed)
+                return;
             closed = true;
+            cancel.abort(abortError());
+            await tail;
         },
     };
 }
-/** Consumer-facing file cell factory; keeps storage choice behind this module. */
+/** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
 export function openSquareCell(squarePath) {
     return createFileCell(squarePath);
 }

package/dist/state-cell.d.ts

@@ -4,10 +4,7 @@ export interface StateCell {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    } | Promise<{
-        state?: SquareState;
-        result: R;
-    }>): Promise<R>;
+    }): Promise<R>;
     read(): Promise<{
         state: SquareState;
         version: number;

package/guides/participant-ownership.md

@@ -110,7 +110,7 @@ row.
 1. Resolve the requested name and collect the currently active bindings for
    that name. The current session is excluded from the old-owner set only when
    it is already the owner and this is a reconnect, not a kick.
-2. Under the artifact lock, commit two lifecycle activities as one transaction:
+2. In one artifact transaction, commit two lifecycle activities:
    `done` for the standing participant, followed immediately by `join` for the
    reclaimed name. If this transaction cannot commit, nothing is kicked.
 3. In the same artifact transaction, remove every route for the kicked
@@ -152,8 +152,8 @@ owner. It must not append a second `done` for the new owner.
 ## Concurrency and Recovery
 
 The artifact transaction serializes participant lifecycle activities. The host
-ledger lock serializes binding rows. These locks protect different facts and
-must not be replaced with a copied sidecar or a display-level mutex.
+ledger lock serializes binding rows. They protect different facts and must not
+be replaced with a copied sidecar or a display-level mutex.
 
 The safe ordering is:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.45",
+  "version": "0.3.46",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "author": "astrosheep",
   "license": "MIT",
   "engines": {
-    "node": ">=22.5.0"
+    "node": "^22.16.0 || >=24.0.0"
   },
   "devDependencies": {
     "@getpaseo/client": "^0.3.1",