@astrosheep/square 0.3.105 → 0.4.0

package/dist/activity-feed.js

@@ -3,7 +3,7 @@ const CONTEXT_LIMIT = 5;
 const PREVIEW_CHARS = 400;
 /** A bounded, nonconsuming glimpse; seen rows beyond a cursor hole must not reappear. */
 export function expressionContext(facts, name) {
-    const filter = { afterIndex: facts.participant(name)?.lastJoinIndex ?? -1, unseenOnly: true };
+    const filter = { kinds: ['say'], afterIndex: facts.participant(name)?.lastJoinIndex ?? -1, unseenOnly: true };
     const page = facts.directed(name, filter, { edge: 'newest', limit: CONTEXT_LIMIT });
     const activities = facts.activities(page.items.map(head => head.index)).filter(act => act.kind === 'say')
         .sort((a, b) => a.index - b.index).map(act => {

package/dist/artifact-store.d.ts

@@ -0,0 +1,41 @@
+import { DatabaseSync } from 'node:sqlite';
+export interface StoreFormat {
+    readonly applicationId: number;
+    readonly userVersion: number;
+    readonly validate: (db: DatabaseSync, location: string) => void;
+    readonly reset: (db: DatabaseSync) => void;
+    readonly observerKey: string;
+}
+export type StoreInitializer = (db: DatabaseSync) => void;
+export type StoreChanges = {
+    readonly changed: boolean;
+    readonly deliveryChanged: boolean;
+};
+export interface StoreTransaction {
+    readonly db: DatabaseSync;
+    guard<F extends (...args: never[]) => unknown>(fn: F): F;
+    track(changes: StoreChanges): void;
+}
+export declare function requireSquareExtension(location: string): void;
+export declare function storageError(error: unknown, location: string): unknown;
+/** Private storage opening; never creates a missing file. */
+export declare function openExistingSquareDatabase(location: string): DatabaseSync;
+export declare function abort(signal?: AbortSignal): void;
+/** One ordered connection and transaction lifetime, shared by Channel and Agora compositions. */
+export declare function createArtifactStore(location: string, format: StoreFormat, initialize?: StoreInitializer, externalSignal?: AbortSignal): {
+    run<R>(write: boolean, callback: (tx: StoreTransaction) => R, signal?: AbortSignal, settlement?: boolean): Promise<{
+        value: R;
+        version: number;
+        changed: boolean;
+        deliveryChanged: boolean;
+    }>;
+    revision: (signal?: AbortSignal, delivery?: boolean) => Promise<number>;
+    deliveryRevision: (signal?: AbortSignal) => Promise<number>;
+    changed(since: number, timeout: number, signal?: AbortSignal): Promise<boolean>;
+    close(): Promise<void>;
+};
+export declare function inspectStore<R>(location: string, format: StoreFormat, select: (db: DatabaseSync) => R, signal?: AbortSignal): Promise<R>;
+export declare function observeStoreRevision(location: string, format: StoreFormat, delivery?: boolean): Promise<import("./file-changes.js").VersionObserver<number | null>>;
+/** Atomic publication and explicit replacement share the same closed physical schema. */
+export declare function createStoreFile(location: string, format: StoreFormat, initialize: StoreInitializer, signal?: AbortSignal): Promise<boolean>;
+export declare function replaceStoreFile(location: string, format: StoreFormat, initialize: (db: DatabaseSync, revision: number) => void, signal?: AbortSignal): Promise<void>;

package/dist/artifact-store.js

@@ -0,0 +1,272 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { canonicalPath } from './canonical-path.js';
+import { observeFileVersion } from './file-changes.js';
+import { retrySqliteBusy, inSqliteTransaction } from './sqlite-transaction.js';
+import { InternalSquareError, SquareError } from './neutral.js';
+import { readStorageRevision } from './sqlite-framing.js';
+import { invalidArtifact } from './sqlite-values.js';
+export function requireSquareExtension(location) {
+    if (!location.endsWith('.square'))
+        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${location}`);
+}
+export 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 storage opening; never creates a missing file. */
+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) {
+        throw storageError(error, location);
+    }
+}
+export function abort(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Square artifact operation aborted');
+}
+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.');
+    }
+}
+/** One ordered connection and transaction lifetime, shared by Channel and Agora compositions. */
+export function createArtifactStore(location, format, initialize, externalSignal) {
+    let database, closed = false, inCallback = false;
+    let tail = Promise.resolve();
+    const cancel = new AbortController();
+    const canonical = initialize === undefined ? canonicalPath(location) : Promise.resolve(location);
+    if (initialize) {
+        database = new DatabaseSync(':memory:');
+        try {
+            initialize(database);
+            database.exec(`PRAGMA application_id=${format.applicationId}; PRAGMA user_version=${format.userVersion}`);
+        }
+        catch (error) {
+            database.close();
+            throw error;
+        }
+    }
+    const combined = (signal) => AbortSignal.any([cancel.signal, ...(externalSignal ? [externalSignal] : []), ...(signal ? [signal] : [])]);
+    const validate = (db) => { format.validate(db, initialize ? ':memory:' : location); return readStorageRevision(db); };
+    async function connection(signal) {
+        if (database)
+            return database;
+        location = await canonical;
+        abort(signal);
+        database = openExistingSquareDatabase(location);
+        try {
+            await retrySqliteBusy(() => validate(database), signal);
+            database.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL');
+        }
+        catch (error) {
+            database.close();
+            database = undefined;
+            throw storageError(error, location);
+        }
+        return database;
+    }
+    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 result = tail.then(() => { abort(signal); return operation(signal); });
+        tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function transaction(write, callback, signal) {
+        return connection(signal).then(db => inSqliteTransaction(db, write, () => validate(db), version => {
+            const changes = [];
+            let active = true, failed = false, failure;
+            const guard = fn => ((...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;
+                }
+            });
+            let value;
+            inCallback = true;
+            try {
+                value = callback({ db, guard, track: item => changes.push(item) });
+                synchronous(value);
+            }
+            finally {
+                inCallback = false;
+                active = false;
+            }
+            if (failed)
+                throw failure;
+            const changed = write && changes.some(item => item.changed), deliveryChanged = write && changes.some(item => item.deliveryChanged);
+            if (changed || deliveryChanged) {
+                if ((changed && version === Number.MAX_SAFE_INTEGER) || (deliveryChanged && readStorageRevision(db, true) === Number.MAX_SAFE_INTEGER))
+                    throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
+                db.prepare('UPDATE storage_meta SET revision=revision+?, delivery_revision=delivery_revision+? WHERE id=1').run(Number(changed), Number(deliveryChanged));
+            }
+            return { value, version: version + Number(changed), changed, deliveryChanged };
+        }, signal));
+    }
+    const revision = (signal, delivery = false) => queue(async (s) => {
+        const db = await connection(s);
+        return inSqliteTransaction(db, false, () => validate(db), () => readStorageRevision(db, delivery), s);
+    }, combined(signal));
+    return {
+        run(write, callback, signal, settlement = false) {
+            return queue(s => transaction(write, callback, s), settlement
+                ? AbortSignal.any([cancel.signal, AbortSignal.timeout(5000)]) : combined(signal));
+        },
+        revision,
+        deliveryRevision: (signal) => revision(signal, true),
+        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 (initialize) {
+                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 observeStoreRevision(await canonical, format);
+            try {
+                return await observer.changed(since, Math.max(0, deadline - Date.now()), s);
+            }
+            catch (error) {
+                if (closed)
+                    return false;
+                abort(s);
+                throw error;
+            }
+            finally {
+                observer.close();
+            }
+        },
+        async close() {
+            if (inCallback)
+                throw new TypeError('Square artifact cannot close inside a callback.');
+            if (!closed) {
+                closed = true;
+                cancel.abort(new Error('Square artifact is closed'));
+            }
+            await tail;
+            database?.close();
+            database = undefined;
+        },
+    };
+}
+export async function inspectStore(location, format, select, signal) {
+    const db = openExistingSquareDatabase(location);
+    return inSqliteTransaction(db, false, () => format.validate(db, location), () => select(db), signal)
+        .catch(error => { throw storageError(error, location); }).finally(() => db.close());
+}
+export function observeStoreRevision(location, format, delivery = false) {
+    return observeFileVersion(location, `${format.observerKey}-${delivery ? 'delivery-revision' : 'revision'}`, async (file, signal) => {
+        try {
+            return await inspectStore(file, format, db => readStorageRevision(db, delivery), signal);
+        }
+        catch (error) {
+            abort(signal);
+            if (error instanceof InternalSquareError && error.code === 'not_found')
+                return null;
+            throw error;
+        }
+    });
+}
+/** Atomic publication and explicit replacement share the same closed physical schema. */
+export async function createStoreFile(location, format, initialize, signal) {
+    abort(signal);
+    location = await canonicalPath(location);
+    requireSquareExtension(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();
+    try {
+        const db = new DatabaseSync(temporary);
+        try {
+            db.exec('PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL');
+            await inSqliteTransaction(db, true, () => { }, () => { initialize(db); db.exec(`PRAGMA application_id=${format.applicationId}; PRAGMA user_version=${format.userVersion}`); }, signal);
+        }
+        finally {
+            db.close();
+        }
+        const flush = await fs.promises.open(temporary, 'r+');
+        try {
+            await flush.sync();
+        }
+        finally {
+            await flush.close();
+        }
+        abort(signal);
+        try {
+            await fs.promises.link(temporary, location);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        await fs.promises.unlink(temporary).catch(() => undefined);
+    }
+}
+export async function replaceStoreFile(location, format, initialize, signal) {
+    if (await createStoreFile(location, format, db => initialize(db, 0), signal))
+        return;
+    abort(signal);
+    const db = openExistingSquareDatabase(await canonicalPath(location));
+    try {
+        await retrySqliteBusy(() => format.validate(db, location), signal);
+        db.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL');
+        await inSqliteTransaction(db, true, () => format.validate(db, location), () => {
+            const revision = readStorageRevision(db);
+            if (revision === Number.MAX_SAFE_INTEGER)
+                throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
+            format.reset(db);
+            initialize(db, revision + 1);
+        }, signal);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/artifact.d.ts

@@ -1,21 +1,22 @@
-import { DatabaseSync } from 'node:sqlite';
 import { type BuildOptions } from './model.js';
 import type { SquareResourceOwner, SquareArtifactPort } from './ports.js';
 import { type SquareState } from './square-sqlite.js';
+import type { ChannelArtifact } from './channel-ports.js';
+export { openExistingSquareDatabase } from './artifact-store.js';
+export declare function channelArtifact(port: SquareArtifactPort): ChannelArtifact;
 /** Explicit-lifetime holder of one reused artifact connection. Request cancellation
  * never becomes the shared connection's lifetime; close drains the owner once. */
 export declare function createSquareResourceOwner(): SquareResourceOwner;
 /** All build paths share configuration validation and lazy guide preparation. */
-export declare function prepareSquareBuild(options: Omit<BuildOptions, 'force'>, snippet: string): SquareState;
+export declare function prepareSquareBuild(options: Omit<BuildOptions, 'force'>, snippet: string, includeGuides?: boolean): SquareState;
 /** File build owns publication and CLI conflict semantics, not host resources. */
-export declare function createSquare(location: string, options: BuildOptions, snippet: string, signal?: AbortSignal): Promise<Pick<SquareState, 'hardCap' | 'throttlePerMinute'>>;
+export declare function createSquare(location: string, options: BuildOptions, snippet: string, signal?: AbortSignal, includeGuides?: boolean): Promise<Pick<SquareState, 'hardCap' | 'throttlePerMinute'>>;
 export interface DoctorProblem {
     kind: string;
     message: string;
 }
 export interface DiagnoseResult {
     unfixable?: string;
-    migrationRequired?: string;
     problems: DoctorProblem[];
     standingCount?: number;
 }
@@ -23,18 +24,13 @@ export interface SquareSnapshot {
     readonly state: SquareState;
     readonly revision: number;
 }
-/** Private artifact-boundary connection shared with explicit migration. Never creates a path. */
-export declare function openExistingSquareDatabase(location: string): DatabaseSync;
-/** One connection, ordered operations, guarded synchronous transaction capabilities. */
+/** Agora composition over the same lower SQL and ordered store used by standalone Channel. */
 export declare function createArtifactPort(location: string, initial?: SquareState, externalSignal?: AbortSignal): SquareArtifactPort;
-/** New-format creation; initial authority is accepted only at this explicit boundary. */
 export declare function createSquareFile(location: string, state: SquareState, signal?: AbortSignal): Promise<boolean>;
-/** Explicit build --force / fixture import, never a runtime state-replacement callback. */
 export declare function writeSquareFile(location: string, state: SquareState, signal?: AbortSignal): Promise<void>;
-/** Explicit test/export projection. Hot callers must use the typed port. */
 export declare function readSquareSnapshot(location: string, signal?: AbortSignal): Promise<SquareSnapshot>;
 export declare function readSquareRevision(location: string, signal?: AbortSignal): Promise<number>;
 export declare function readSquareDeliveryRevision(location: string, signal?: AbortSignal): Promise<number>;
-export declare function observeSquareRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
-export declare function observeSquareDeliveryRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
+export declare const observeSquareRevision: (location: string) => Promise<import("./file-changes.js").VersionObserver<number | null>>;
+export declare const observeSquareDeliveryRevision: (location: string) => Promise<import("./file-changes.js").VersionObserver<number | null>>;
 export declare function diagnoseSquareFile(location: string): Promise<DiagnoseResult>;