@astrosheep/square 0.3.86 → 0.3.88

package/dist/host-ledger-migration.js

@@ -1,264 +0,0 @@
-import { createHash } from 'node:crypto';
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { DatabaseSync } from 'node:sqlite';
-import { canonicalPathSync } from './canonical-path.js';
-import { withFileLock } from './file-lock.js';
-import { hostLedgerRoot } from './host-ledger-root.js';
-import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, migrationRequired, } from './host-ledger-sqlite.js';
-import { inSqliteTransaction } from './sqlite-transaction.js';
-function rootFor(options) {
-    return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
-}
-function abort(signal) {
-    if (signal?.aborted)
-        throw signal.reason ?? new Error('Host ledger migration aborted');
-}
-async function exists(file) {
-    try {
-        await fs.lstat(file);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
-}
-function verificationFailure(root, file, format) {
-    const name = file ?? path.join(root, LEDGER_FILENAME);
-    const detail = format === 'unsupported'
-        ? 'It has an unsupported format version.'
-        : format === 'unrelated'
-            ? 'It is unrelated to a Square host ledger.'
-            : format === undefined
-                ? 'It could not be read.'
-                : 'Its identity is current but its contents failed verification.';
-    return new Error(`Host ledger verification failed at ${name}; ${detail}\nDestination left untouched. Migration is not a repair command. Keep the affected sessions and MCP services stopped, preserve the ledger, and diagnose the underlying file before retrying.`);
-}
-async function verifyDatabase(file, root, signal) {
-    abort(signal);
-    let db;
-    try {
-        db = new DatabaseSync(file, { readOnly: true });
-        const counts = await inSqliteTransaction(db, false, () => validateLedger(db), () => verifyLedger(db), signal);
-        return { status: 'sqlite', rootPath: root, ...counts };
-    }
-    catch {
-        abort(signal);
-        let format;
-        try {
-            db = new DatabaseSync(file, { readOnly: true });
-            format = inspectLedgerIdentity(db);
-            db.close();
-            db = undefined;
-        }
-        catch {
-            db?.close();
-            db = undefined;
-        }
-        if (format === 'old-sqlite')
-            throw migrationRequired(root);
-        throw verificationFailure(root, file, format);
-    }
-    finally {
-        db?.close();
-    }
-}
-async function readLegacy(root, kind, signal) {
-    let bytes;
-    try {
-        bytes = await fs.readFile(path.join(root, `${kind}.ndjsonl`));
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return { rows: [], report: { records: 0, ignored: 0, rejected: 0, sha256: null } };
-        throw new Error(`Cannot read legacy ${kind} source.`);
-    }
-    const rows = [];
-    let ignored = 0, rejected = 0;
-    let firstRejectedLine;
-    const lines = bytes.toString('utf8').split('\n');
-    for (let index = 0; index < lines.length; index++) {
-        abort(signal);
-        if (lines[index].trim() === '')
-            continue;
-        let row;
-        try {
-            row = JSON.parse(lines[index]);
-        }
-        catch {
-            ignored++;
-            continue;
-        }
-        if (row === null || typeof row !== 'object' || row.v !== 1 || typeof (row.at ?? row.updatedAt) !== 'number') {
-            ignored++;
-            continue;
-        }
-        // This compatibility normalization belongs only to the explicit importer.
-        if (row.kind === 'wake' && row.outcome === 'unknown' && row.unknownSource === undefined) {
-            row = { ...row, unknownSource: row.signature === 'worker_interrupted_during_dispatch' ? 'interrupted' : 'transport' };
-        }
-        try {
-            ledgerRecordColumns(kind, row);
-        }
-        catch {
-            rejected++;
-            firstRejectedLine ??= index + 1;
-            continue;
-        }
-        rows.push(row);
-    }
-    return { rows, firstRejectedLine, report: { records: rows.length, ignored, rejected, sha256: createHash('sha256').update(bytes).digest('hex') } };
-}
-async function readSources(root, signal) {
-    return { presence: await readLegacy(root, 'presence', signal), evidence: await readLegacy(root, 'evidence', signal) };
-}
-function sourceReport(root, sources) {
-    return {
-        status: sources.presence.report.sha256 === null && sources.evidence.report.sha256 === null ? 'empty' : 'legacy',
-        rootPath: root,
-        presence: sources.presence.rows.length, evidence: sources.evidence.rows.length,
-        sources: { presence: sources.presence.report, evidence: sources.evidence.report },
-        ready: sources.presence.report.rejected === 0 && sources.evidence.report.rejected === 0,
-    };
-}
-/** Read-only readiness/integrity check. Never creates a root, lock, or database. */
-export async function verifyHostLedger(options = {}) {
-    const root = rootFor(options);
-    abort(options.signal);
-    const destination = path.join(root, LEDGER_FILENAME);
-    if (await exists(destination))
-        return verifyDatabase(destination, root, options.signal);
-    return sourceReport(root, await readSources(root, options.signal));
-}
-/** The fixed offline fence: ownership claim, then both legacy source locks, in that order. */
-function withOfflineLocks(root, signal, body) {
-    const lockOptions = { retryMs: 10, signal };
-    return withFileLock(path.join(root, 'presence-claim.lock'), lockOptions, () => withFileLock(path.join(root, 'presence.ndjsonl.lock'), lockOptions, () => withFileLock(path.join(root, 'evidence.ndjsonl.lock'), lockOptions, body)))
-        .catch((error) => { abort(signal); throw error; });
-}
-/**
- * Under the offline fence: a current ledger verifies read-only, an older SQLite format is upgraded in
- * place through the explicit transaction owner, and anything else is refused without repair.
- */
-async function currentFormat(root, signal) {
-    const destination = path.join(root, LEDGER_FILENAME);
-    try {
-        return await verifyDatabase(destination, root, signal);
-    }
-    catch {
-        abort(signal);
-    }
-    if (!await exists(destination))
-        throw verificationFailure(root);
-    let db;
-    try {
-        db = new DatabaseSync(destination);
-        const upgraded = await inSqliteTransaction(db, true, () => { }, () => upgradeLedger(db), signal);
-        db.close();
-        db = undefined;
-        return { ...await verifyDatabase(destination, root, signal), status: upgraded ? 'upgraded' : 'sqlite' };
-    }
-    catch {
-        abort(signal);
-        throw verificationFailure(root, destination);
-    }
-    finally {
-        db?.close();
-    }
-}
-/** Offline only: locks fence compatible writers, but do not prove hosts have stopped. */
-export async function migrateHostLedger(options = {}) {
-    const root = rootFor(options), signal = options.signal;
-    abort(signal);
-    const destination = path.join(root, LEDGER_FILENAME);
-    if (await exists(destination)) {
-        try {
-            return await verifyDatabase(destination, root, signal);
-        }
-        catch {
-            abort(signal);
-        }
-        // Inspect only the database identity; record/schema verification remains the migration fence.
-        let format;
-        let probe;
-        try {
-            probe = new DatabaseSync(destination, { readOnly: true });
-            format = inspectLedgerIdentity(probe);
-        }
-        catch {
-            format = undefined;
-        }
-        finally {
-            probe?.close();
-        }
-        if (format === 'old-sqlite') {
-            // Only the supported prior format enters the existing offline upgrade fence.
-            return withOfflineLocks(root, signal, () => currentFormat(root, signal));
-        }
-        throw verificationFailure(root, destination, format);
-    }
-    if (!await exists(path.join(root, 'presence.ndjsonl')) && !await exists(path.join(root, 'evidence.ndjsonl'))) {
-        return { status: 'empty', rootPath: root, presence: 0, evidence: 0 };
-    }
-    return withOfflineLocks(root, signal, () => convertLegacy(root, destination, signal));
-}
-/** The offline NDJSON import: build, verify and publish a new database without touching sources. */
-async function convertLegacy(root, destination, signal) {
-    if (await exists(destination))
-        return currentFormat(root, signal);
-    const sources = await readSources(root, signal);
-    const report = sourceReport(root, sources);
-    if (!report.ready) {
-        const rejected = ['presence', 'evidence'].filter((kind) => sources[kind].report.rejected > 0)
-            .map((kind) => `${kind}: ${sources[kind].report.rejected} rejected (first line ${sources[kind].firstRejectedLine})`);
-        throw new Error(`Unsafe legacy records; conversion refused. ${rejected.join('; ')}.`);
-    }
-    const temporary = await fs.mkdtemp(path.join(root, '.host-ledger-migrate-'));
-    const file = path.join(temporary, LEDGER_FILENAME);
-    let db;
-    try {
-        abort(signal);
-        // The temporary connection remains under the ledger root, including journals.
-        await fs.writeFile(file, '', { flag: 'wx', mode: 0o600 });
-        db = new DatabaseSync(file);
-        initializeLedger(db);
-        await inSqliteTransaction(db, true, () => { }, () => {
-            for (const kind of ['presence', 'evidence']) {
-                for (const row of sources[kind].rows) {
-                    abort(signal);
-                    insertLedgerRecord(db, kind, row);
-                }
-            }
-            setLedgerRevisions(db, { presence: report.presence ? 1 : 0, evidence: report.evidence ? 1 : 0 });
-        }, signal);
-        db.close();
-        db = undefined;
-        const verified = await verifyDatabase(file, root, signal);
-        if (verified.presence !== report.presence || verified.evidence !== report.evidence) {
-            throw new Error('Host ledger import counts do not match; conversion refused.');
-        }
-        abort(signal);
-        try {
-            await fs.link(file, destination);
-        }
-        catch (error) {
-            if (error.code === 'EEXIST')
-                return await verifyDatabase(destination, root, signal);
-            throw error;
-        }
-        const directory = await fs.open(root, 'r');
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
-        }
-        return { ...verified, status: 'migrated', sources: report.sources };
-    }
-    finally {
-        db?.close();
-        await fs.rm(temporary, { recursive: true, force: true });
-    }
-}

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

@@ -1,2 +0,0 @@
-/** Resolve the single user-level host ledger root. */
-export declare function hostLedgerRoot(env?: NodeJS.ProcessEnv): string;

package/dist/host-ledger-root.js

@@ -1,9 +0,0 @@
-import path from 'node:path';
-import { homedir } from 'node:os';
-/** Resolve the single user-level host ledger root. */
-export function hostLedgerRoot(env = process.env) {
-    return env.SQUARE_HOST_LEDGER_ROOT
-        ?? (env.SQUARE_REGISTRY === undefined
-            ? path.join(homedir(), '.square', 'host-ledger')
-            : path.dirname(env.SQUARE_REGISTRY));
-}

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

@@ -1,65 +0,0 @@
-import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
-import type { PresenceRecord, PresenceLookup, EvidenceRecord, EvidenceLookup, NativeTokenLookup, NativeTokenResult } from './host-ledger.js';
-export declare const LEDGER_FILENAME = "host-ledger.sqlite";
-export declare const LEDGER_APPLICATION_ID = 1397835852;
-export declare const LEDGER_VERSION = 2;
-export declare const LEDGER_RETENTION: number;
-type Kind = 'presence' | 'evidence';
-export interface Stored<T> {
-    readonly seq: number;
-    readonly record: T;
-}
-export type HostLedgerFormat = 'current' | 'old-sqlite' | 'unrelated' | 'unsupported';
-/** The complete record remains authority; these are only reproducible lookup projections. */
-export declare function ledgerRecordColumns(kind: Kind, input: object): Record<string, SQLInputValue>;
-export declare function initializeLedger(db: DatabaseSync): void;
-export declare function setLedgerRevisions(db: DatabaseSync, revisions: {
-    presence: number;
-    evidence: number;
-}): void;
-export declare function insertLedgerRecord(db: DatabaseSync, kind: Kind, row: object): void;
-export declare function ledgerRevisions(db: DatabaseSync): {
-    presence: number;
-    evidence: number;
-};
-export declare function validateLedger(db: DatabaseSync): void;
-export declare function verifyLedger(db: DatabaseSync): {
-    presence: number;
-    evidence: number;
-    presenceRevision: number;
-    evidenceRevision: number;
-};
-/** Read the file-type stamp and format version without making the runtime authority. */
-export declare function inspectLedgerIdentity(db: DatabaseSync): HostLedgerFormat;
-/** Explicit offline migration only; the caller owns the write transaction. Preserve all records and revisions. */
-export declare function upgradeLedger(db: DatabaseSync): boolean;
-export declare function migrationRequired(root: string): Error;
-/** Transaction-local storage rows; sequence coordinates never cross HostLedgerPort. */
-export declare class LedgerTransaction {
-    private readonly db;
-    private readonly changed;
-    constructor(db: DatabaseSync);
-    presence(input: PresenceLookup & {
-        channel?: string;
-    }, now: number, includeFuture?: boolean): Stored<PresenceRecord>[];
-    evidence(input: EvidenceLookup & {
-        claimToken?: string;
-    }, now: number, includeFuture?: boolean): Stored<EvidenceRecord>[];
-    private select;
-    /** Both halves of recognition are read in the enclosing SQLite snapshot, with indexed session/token predicates. */
-    nativeTokens(input: NativeTokenLookup): NativeTokenResult;
-    /** Called only after exact-record CAS. No housekeeping of unrelated rows belongs here. */
-    retireEvidence(row: Stored<EvidenceRecord>): boolean;
-    insert(kind: Kind, row: object): void;
-    replace(kind: Kind, seq: number, row: object): void;
-    remove(kind: Kind, rows: readonly Stored<unknown>[]): void;
-    /** Only invoke at the point where the former implementation published a mutation. */
-    publish(kind: Kind, now: number): void;
-    commitRevisions(): void;
-}
-export declare function withLedger<T>(root: string, write: boolean, select: (rows: LedgerTransaction) => T, absent: T, signal?: AbortSignal): Promise<T>;
-export declare function readLedgerRevisions(root: string, signal?: AbortSignal): Promise<{
-    presence: number;
-    evidence: number;
-} | undefined>;
-export {};