@amalgm/shell 0.1.164-preview.36072132286 → 0.1.164-preview.36809057014

package/dist/ground-database.js

@@ -0,0 +1,290 @@
+import { dirname } from "node:path";
+import { ensurePrivateDir } from "./filesystem.js";
+import { beginGroundEpoch, groundIncarnation, retireGroundViews } from "./ground-basis.js";
+import { startGroundCheckpoints, stopGroundCheckpoints } from "./ground-checkpoints.js";
+import { ensureGroundDifferences } from "./ground-differences.js";
+import { releaseHeldGroundFile } from "./ground-holders.js";
+import { assertGroundInitialized, objectAt } from "./ground-initialization.js";
+import { ensureInventorySchema } from "./ground-inventory-schema.js";
+import { startGroundSaver, stopGroundSaver } from "./ground-saver.js";
+import { databaseFileName, openFileDatabase } from "./sqlite.js";
+/** A publication row holds only what the authority must be told: the small
+ * meta facts and the head-commit operation naming this graph's pages. The
+ * pages themselves are write-once rows in their own table, because a status
+ * transition rewrites its whole row — overflow pages included — through the
+ * WAL at synchronous=FULL, and page bytes must never ride that rewrite.
+ *
+ * Every row owns exactly one Register declaration, named by its root. While
+ * a row names a declaration, that root's ground is held from ordinary Detect;
+ * the row is the machine's only pending responsibility for it. */
+const SNAPSHOT_PUBLICATIONS_SCHEMA = `
+    CREATE TABLE IF NOT EXISTS snapshot_publications (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+      mutation_id TEXT NOT NULL UNIQUE,
+      resource_id TEXT NOT NULL,
+      declaration_root TEXT NOT NULL,
+      meta_json TEXT NOT NULL,
+      operation_blob BLOB NOT NULL,
+      created_at INTEGER NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected')),
+      submitted_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS snapshot_publications_by_declaration
+      ON snapshot_publications(declaration_root);
+    CREATE TABLE IF NOT EXISTS snapshot_publication_pages (
+      mutation_id TEXT NOT NULL,
+      page_index INTEGER NOT NULL,
+      sha256 TEXT NOT NULL,
+      bytes BLOB NOT NULL,
+      PRIMARY KEY (mutation_id, page_index)
+    );`;
+/** A publication journal in any other shape names no declaration, so no
+ * current reader may interpret it. An empty one carries no responsibility
+ * and is recreated; a non-empty one may hold a submitted mutation whose
+ * outcome exists only at the authority, so the open refuses rather than
+ * guess — the file stays exactly as it was. */
+function requireCurrentJournal(database, columns) {
+    if (columns.size === 0 || columns.has("declaration_root"))
+        return;
+    const rows = database.prepare("SELECT COUNT(*) AS count FROM snapshot_publications").get().count;
+    if (rows > 0) {
+        throw new Error(`snapshot publication journal is in an unsupported shape with ${rows} row(s); `
+            + "it names no declaration and cannot be replayed");
+    }
+    database.transaction(() => {
+        database.exec("DROP TABLE snapshot_publications");
+        database.exec("DROP TABLE IF EXISTS snapshot_publication_blobs");
+        database.exec("DROP TABLE IF EXISTS snapshot_publication_pages");
+    })();
+}
+/** The durability policy of the file's two writers, the migration and the
+ * saver thread, applied before their first write.
+ * A commit pays only for its own frames. No commit checkpoints: moving the
+ * log into the database flushes the drive, and the committing thread would
+ * wait for it. The file's checkpoint thread does that work
+ * (ground-checkpoints.ts). No commit resizes the log either: cutting the file
+ * back frees everything earlier commits wrote, which one commit would wait
+ * for. A restarted log reuses the space it grew to until the checkpoint
+ * thread finds it quiet and cuts it back, or a writer closes with no other
+ * connection open. */
+export function configureGroundConnection(database) {
+    database.pragma("busy_timeout = 5000");
+    database.pragma("journal_mode = WAL");
+    database.pragma("synchronous = FULL");
+    database.pragma("wal_autocheckpoint = 0");
+    database.pragma("journal_size_limit = -1");
+    return database;
+}
+const columnsOf = (database, table) => new Set(database.prepare(`PRAGMA table_info(${table})`).all().map(({ name }) => name));
+/** The one migration, and the process's ground epoch after it, on the
+ * migrating thread's own connection. Only the initialization owner calls it,
+ * once per file per process, while no other connection is open. */
+export function migrateGroundDatabase(file) {
+    const started = performance.now();
+    ensurePrivateDir(dirname(file));
+    const database = configureGroundConnection(openFileDatabase(file));
+    try {
+        requireCurrentJournal(database, columnsOf(database, "snapshot_publications"));
+        // A seal is disposable reuse evidence: another shape is dropped, never read.
+        const sealColumns = columnsOf(database, "repository_git_evidence");
+        if (sealColumns.size > 0 && !sealColumns.has("selection_key"))
+            database.exec("DROP TABLE repository_git_evidence");
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS ground_identity (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        user_id TEXT NOT NULL,
+        user_email TEXT NOT NULL,
+        device_id TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS record_outbox (
+        local_sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        mutation_id TEXT NOT NULL UNIQUE,
+        authority_id TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        record_json TEXT NOT NULL,
+        status TEXT NOT NULL CHECK(status IN ('pending', 'accepted')),
+        global_sequence INTEGER,
+        created_at INTEGER NOT NULL,
+        accepted_at INTEGER,
+        CHECK((status = 'pending' AND global_sequence IS NULL AND accepted_at IS NULL)
+           OR (status = 'accepted' AND global_sequence > 0 AND accepted_at IS NOT NULL))
+      );
+      CREATE TABLE IF NOT EXISTS record_inbox (
+        authority_id TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        global_sequence INTEGER NOT NULL CHECK(global_sequence > 0),
+        delivery_sequence INTEGER NOT NULL CHECK(delivery_sequence > 0),
+        mutation_id TEXT NOT NULL,
+        record_json TEXT NOT NULL,
+        received_at INTEGER NOT NULL,
+        resolved_at INTEGER,
+        PRIMARY KEY(entity_id, global_sequence),
+        UNIQUE(entity_id, mutation_id),
+        UNIQUE(authority_id, delivery_sequence)
+      );
+      CREATE TABLE IF NOT EXISTS entity_receive_cursors (
+        entity_id TEXT PRIMARY KEY,
+        authority_id TEXT NOT NULL,
+        received_through INTEGER NOT NULL CHECK(received_through >= 0)
+      );
+      CREATE TABLE IF NOT EXISTS authority_delivery_cursors (
+        authority_id TEXT PRIMARY KEY,
+        received_through INTEGER NOT NULL CHECK(received_through >= 0),
+        history_floor INTEGER NOT NULL DEFAULT 0 CHECK(history_floor >= 0)
+      );
+      CREATE TABLE IF NOT EXISTS authority_snapshot_baselines (
+        authority_id TEXT PRIMARY KEY,
+        delivery_sequence INTEGER NOT NULL CHECK(delivery_sequence >= 0)
+      );
+      ${SNAPSHOT_PUBLICATIONS_SCHEMA}
+      CREATE TABLE IF NOT EXISTS constructs (
+        uuid TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        name TEXT NOT NULL,
+        status TEXT NOT NULL,
+        version TEXT NOT NULL,
+        payload_version TEXT,
+        updated_at_ms INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS entity_apply_state (
+        entity_id TEXT PRIMARY KEY,
+        authority_id TEXT NOT NULL,
+        resolved_through INTEGER NOT NULL CHECK(resolved_through >= 0),
+        materialized_sequence INTEGER,
+        materialized_record_json TEXT,
+        CHECK((materialized_sequence IS NULL AND materialized_record_json IS NULL)
+           OR (materialized_sequence > 0 AND materialized_record_json IS NOT NULL))
+      );
+      CREATE TABLE IF NOT EXISTS entity_apply_intents (
+        entity_id TEXT PRIMARY KEY,
+        authority_id TEXT NOT NULL,
+        intent_json TEXT NOT NULL,
+        recovery_location TEXT,
+        retirement_json TEXT
+      );
+      CREATE TABLE IF NOT EXISTS workspace_add_intents (
+        workspace_uuid TEXT PRIMARY KEY,
+        destination_path TEXT NOT NULL UNIQUE,
+        intent_json TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS repository_git_evidence (
+        uuid TEXT PRIMARY KEY,
+        fingerprint TEXT NOT NULL,
+        observed_payload TEXT NOT NULL,
+        identity_hash TEXT NOT NULL,
+        selection_key TEXT,
+        selected_payload TEXT,
+        selected_transport TEXT,
+        CHECK((selection_key IS NULL) = (selected_payload IS NULL)
+          AND (selection_key IS NULL) = (selected_transport IS NULL))
+      );
+      CREATE TABLE IF NOT EXISTS detect_dispositions (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_id TEXT NOT NULL UNIQUE,
+        incarnation TEXT NOT NULL,
+        fact TEXT NOT NULL CHECK(fact IN ('ready', 'outcome', 'observation')),
+        collection_id TEXT,
+        recorded_at INTEGER NOT NULL,
+        event_json TEXT NOT NULL,
+        CHECK(fact = 'observation' OR collection_id IS NOT NULL)
+      );
+      CREATE INDEX IF NOT EXISTS detect_dispositions_by_collection
+        ON detect_dispositions(collection_id, fact) WHERE collection_id IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS record_inbox_apply
+        ON record_inbox(authority_id, entity_id, global_sequence);
+      CREATE INDEX IF NOT EXISTS record_inbox_entity_apply
+        ON record_inbox(entity_id, global_sequence DESC);
+      CREATE INDEX IF NOT EXISTS record_outbox_pending
+        ON record_outbox(status, local_sequence);
+      CREATE INDEX IF NOT EXISTS record_outbox_pending_entity
+        ON record_outbox(status, entity_id, local_sequence);
+      CREATE INDEX IF NOT EXISTS record_outbox_local_work
+        ON record_outbox(authority_id, entity_id, global_sequence);
+    `);
+        if (!columnsOf(database, "record_inbox").has("resolved_at")) {
+            database.exec("ALTER TABLE record_inbox ADD COLUMN resolved_at INTEGER");
+        }
+        // A cursor that predates its floor may have jumped at any adopted
+        // snapshot, so the largest adopted baseline is its only honest floor.
+        if (!columnsOf(database, "authority_delivery_cursors").has("history_floor")) {
+            database.exec(`ALTER TABLE authority_delivery_cursors
+        ADD COLUMN history_floor INTEGER NOT NULL DEFAULT 0 CHECK(history_floor >= 0)`);
+            database.exec(`UPDATE authority_delivery_cursors SET history_floor = MIN(received_through, COALESCE(
+        (SELECT delivery_sequence FROM authority_snapshot_baselines AS baseline
+          WHERE baseline.authority_id = authority_delivery_cursors.authority_id), 0))`);
+        }
+        database.exec("DROP INDEX IF EXISTS record_inbox_delivery");
+        // Resolved history is retained; readers of unresolved work pay only for it.
+        database.exec(`CREATE INDEX IF NOT EXISTS record_inbox_unresolved
+      ON record_inbox(authority_id, entity_id, global_sequence) WHERE resolved_at IS NULL`);
+        const inventories = ensureInventorySchema(database);
+        ensureGroundDifferences(database);
+        database.exec("DROP TABLE IF EXISTS mutation_journal");
+        // Once per file per process, like the migration: every connection this
+        // process opens later reads the same epoch.
+        beginGroundEpoch(database);
+        const count = (table) => database.prepare(`SELECT COUNT(*) FROM ${table}`).pluck().get();
+        return {
+            incarnation: groundIncarnation(database),
+            ...inventories,
+            entities: count("entity_rows"),
+            notebook: count("notebook_rows"),
+            roots: count("ground_roots"),
+            migrationMs: performance.now() - started,
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+/** Every ordinary connection to an initialized ground file, named as every
+ * connection names it (databaseFileName). Each one only reads: the file's
+ * saver thread (ground-saver.ts) makes every write, so no read ever waits
+ * behind a commit on its own thread. None checkpoints, so the first one starts the file's
+ * checkpoint thread and its saver thread. */
+export function openGroundConnection(file) {
+    const name = databaseFileName(file);
+    assertGroundInitialized(name);
+    const database = openFileDatabase(name, { readonly: true, fileMustExist: true });
+    database.pragma("busy_timeout = 5000");
+    startGroundCheckpoints(name, objectAt(name));
+    startGroundSaver(name, objectAt(name));
+    return database;
+}
+const held = new Map();
+function bound(file) {
+    const name = databaseFileName(file);
+    const current = held.get(name);
+    if (!current) {
+        const database = openGroundConnection(name);
+        const entry = { key: objectAt(name), database };
+        held.set(name, entry);
+        return entry;
+    }
+    if (objectAt(name) !== current.key) {
+        throw new Error(`the ground database ${JSON.stringify(file)} was replaced beneath its open binding`);
+    }
+    return current;
+}
+export function groundDatabase(file) {
+    const { database } = bound(file);
+    if (database.inTransaction)
+        throw new Error("the ground connection was acquired inside an open transaction");
+    return database;
+}
+/** Every other owner has closed by now: each content thread lets its read
+ * connection go after the job it is running, the saver finishes its queue,
+ * and the checkpoint thread's own connection closes last and makes the final
+ * checkpoint there. Released means no thread of this process holds the file:
+ * the final checkpoint is part of closing, and Windows refuses to remove a
+ * file any handle still has open. */
+export async function releaseGroundDatabase(file) {
+    const name = databaseFileName(file);
+    const current = held.get(name);
+    held.delete(name);
+    current?.database.close();
+    retireGroundViews(name);
+    await Promise.all([releaseHeldGroundFile(name), stopGroundSaver(name)]);
+    await stopGroundCheckpoints(name);
+}
+//# sourceMappingURL=ground-database.js.map

package/dist/ground-database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-database.js","sourceRoot":"","sources":["../src/ground-database.ts"],"names":[],"mappings":"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"}

package/dist/ground-differences.d.ts

@@ -0,0 +1,23 @@
+/** Where the two ground inventories disagree, kept exact by their one writer,
+ * so a reader finds it in time proportional to the disagreement, never to
+ * the ground.
+ *
+ * O (entities) and B (detection_notebook) agree on an identity in a root when
+ * both place it there at one type, parent, name, lifecycle and address and,
+ * for all but a folder or workspace, whose result is its membership, at one
+ * version. Every other placement disagrees: an identity one inventory places
+ * in a root the other does not, or both place there differently. The
+ * relation is defined once, as the view ground_disagreements, and
+ * ground_differences is that view stored: created complete, then restated by
+ * each ground write batch, in its own transaction, for every identity whose
+ * compared fields it changed. */
+import type Database from "better-sqlite3";
+import type { GroundTransition } from "./ground-basis.js";
+/** Created with the relation it stores, complete, in one transaction. */
+export declare function ensureGroundDifferences(database: Database.Database): void;
+/** Inside the batch that wrote these transitions, after its last row write:
+ * each identity whose compared fields changed is stated again from the view,
+ * whose per-identity read is a few key lookups. */
+export declare function restateGroundDifferences(database: Database.Database, transitions: Iterable<GroundTransition>): void;
+/** Every identity O and B hold differently in this root. */
+export declare const groundDifferences: (database: Database.Database, rootUUID: string) => string[];

package/dist/ground-differences.js

@@ -0,0 +1,47 @@
+import { cachedStatement } from "./sqlite.js";
+/** The fields agreement reads, beside presence. A write that changes none of
+ * them leaves every agreement as it was. */
+const COMPARED = ["rootUUID", "type", "parentUUID", "name", "status", "relativePath", "version"];
+/** A visible identity lies once in each inventory, so the two arms never
+ * name one pair. */
+const DISAGREEMENTS = `
+  CREATE VIEW ground_disagreements(root_uuid, uuid) AS
+    SELECT o.root_uuid, o.uuid FROM entities o WHERE NOT EXISTS (
+      SELECT 1 FROM detection_notebook b WHERE b.uuid = o.uuid AND b.root_uuid = o.root_uuid
+        AND b.type = o.type AND b.parent_uuid IS o.parent_uuid AND b.name = o.name AND b.status = o.status
+        AND b.relative_path = o.relative_path AND (b.version = o.version OR o.type IN ('workspace', 'folder')))
+    UNION ALL
+    SELECT b.root_uuid, b.uuid FROM detection_notebook b WHERE NOT EXISTS (
+      SELECT 1 FROM entities o WHERE o.uuid = b.uuid AND o.root_uuid = b.root_uuid)`;
+/** Created with the relation it stores, complete, in one transaction. */
+export function ensureGroundDifferences(database) {
+    if (database.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'ground_differences'").get())
+        return;
+    database.transaction(() => database.exec(`${DISAGREEMENTS};
+    CREATE TABLE ground_differences (
+      root_uuid TEXT NOT NULL, uuid TEXT NOT NULL, PRIMARY KEY(root_uuid, uuid)
+    ) WITHOUT ROWID;
+    CREATE INDEX ground_differences_by_uuid ON ground_differences(uuid);
+    INSERT INTO ground_differences(root_uuid, uuid) SELECT root_uuid, uuid FROM ground_disagreements;`))();
+}
+/** Inside the batch that wrote these transitions, after its last row write:
+ * each identity whose compared fields changed is stated again from the view,
+ * whose per-identity read is a few key lookups. */
+export function restateGroundDifferences(database, transitions) {
+    const touched = new Set();
+    for (const { before, after } of transitions) {
+        if (!before || !after || COMPARED.some(field => before[field] !== after[field]))
+            touched.add((after ?? before).uuid);
+    }
+    if (!touched.size)
+        return;
+    const forget = cachedStatement(database, "DELETE FROM ground_differences WHERE uuid = ?");
+    const state = cachedStatement(database, "INSERT INTO ground_differences(root_uuid, uuid) SELECT root_uuid, uuid FROM ground_disagreements WHERE uuid = ?");
+    for (const uuid of touched) {
+        forget.run(uuid);
+        state.run(uuid);
+    }
+}
+/** Every identity O and B hold differently in this root. */
+export const groundDifferences = (database, rootUUID) => cachedStatement(database, "SELECT uuid FROM ground_differences WHERE root_uuid = ?").pluck().all(rootUUID);
+//# sourceMappingURL=ground-differences.js.map

package/dist/ground-differences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-differences.js","sourceRoot":"","sources":["../src/ground-differences.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;4CAC4C;AAC5C,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,CACjE,CAAC;AAE/B;oBACoB;AACpB,MAAM,aAAa,GAAG;;;;;;;;oFAQ8D,CAAC;AAErF,yEAAyE;AACzE,MAAM,UAAU,uBAAuB,CAAC,QAA2B;IACjE,IAAI,QAAQ,CAAC,OAAO,CAAC,kFAAkF,CAAC,CAAC,GAAG,EAAE;QAAE,OAAO;IACvH,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa;;;;;sGAK2C,CAAC,CAAC,EAAE,CAAC;AAC3G,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,wBAAwB,CAAC,QAA2B,EAAE,WAAuC;IAC3G,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,WAAW,EAAE,CAAC;QAC5C,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,MAAM,CAAE,CAAC,IAAI,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI;QAAE,OAAO;IAC1B,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,+CAA+C,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EACpC,iHAAiH,CAAC,CAAC;IACrH,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;AACpE,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAA2B,EAAE,QAAgB,EAAY,EAAE,CAC3F,eAAe,CAAC,QAAQ,EAAE,yDAAyD,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAa,CAAC"}

package/dist/ground-holders.d.ts

@@ -0,0 +1,4 @@
+export declare function holdGroundFiles(release: (file: string) => Promise<void>): void;
+/** Resolves once no registered thread holds `file`, named as every
+ * connection names it (databaseFileName). */
+export declare function releaseHeldGroundFile(file: string): Promise<void>;

package/dist/ground-holders.js

@@ -0,0 +1,15 @@
+/** Threads that keep their own connections to ground files (the content
+ * threads, content-capture-pool.ts) register how they let one file go, and
+ * releasing a ground file (ground-database.ts) waits for every one of them.
+ * Registering inverts the import, so the saver, checkpoint and
+ * initialization threads never load the content threads' modules. */
+const holders = new Set();
+export function holdGroundFiles(release) {
+    holders.add(release);
+}
+/** Resolves once no registered thread holds `file`, named as every
+ * connection names it (databaseFileName). */
+export async function releaseHeldGroundFile(file) {
+    await Promise.all([...holders].map(release => release(file)));
+}
+//# sourceMappingURL=ground-holders.js.map

package/dist/ground-holders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-holders.js","sourceRoot":"","sources":["../src/ground-holders.ts"],"names":[],"mappings":"AAAA;;;;qEAIqE;AACrE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmC,CAAC;AAE3D,MAAM,UAAU,eAAe,CAAC,OAAwC;IACtE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC;AAED;6CAC6C;AAC7C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAY;IACtD,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/ground-initialization-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ground-initialization-worker.js

@@ -0,0 +1,20 @@
+/**
+ * The bootstrap thread: it migrates one ground database, begins its epoch,
+ * reports what it committed and exits. While it runs it holds the file's
+ * only connection (ground-initialization.ts).
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { migrateGroundDatabase } from "./ground-database.js";
+const port = parentPort;
+if (!port)
+    throw new Error("ground initialization must run on a worker thread");
+try {
+    // Absolute high-resolution times: each thread's own clock has its own origin.
+    const startedAt = performance.timeOrigin + performance.now();
+    const migration = migrateGroundDatabase(workerData.file);
+    port.postMessage({ ok: true, migration, startedAt, reportedAt: performance.timeOrigin + performance.now() });
+}
+catch (error) {
+    port.postMessage({ ok: false, error });
+}
+//# sourceMappingURL=ground-initialization-worker.js.map

package/dist/ground-initialization-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-initialization-worker.js","sourceRoot":"","sources":["../src/ground-initialization-worker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,IAAI,GAAG,UAAU,CAAC;AACxB,IAAI,CAAC,IAAI;IAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;AAEhF,IAAI,CAAC;IACH,8EAA8E;IAC9E,MAAM,SAAS,GAAG,WAAW,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC7D,MAAM,SAAS,GAAG,qBAAqB,CAAE,UAA+B,CAAC,IAAI,CAAC,CAAC;IAC/E,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC/G,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/ground-initialization.d.ts

@@ -0,0 +1,35 @@
+/** What the bootstrap thread committed, in counts, never rows. */
+export interface GroundMigration {
+    /** The epoch this initialization began. */
+    readonly incarnation: string;
+    /** The inventory storage it found. */
+    readonly from: "fresh" | "flat" | "generations";
+    readonly entities: number;
+    readonly notebook: number;
+    readonly roots: number;
+    /** Open, migration body, commits and epoch, on the bootstrap thread. */
+    readonly migrationMs: number;
+    /** The conversion's exact-contents check, inside its transaction. */
+    readonly validationMs: number;
+    /** Secondary keys this open built because their stored form differed. */
+    readonly keysBuilt: number;
+}
+export interface GroundInitialization extends GroundMigration {
+    /** From the request to the thread starting the migration: spawn and module loading. */
+    readonly startupMs: number;
+    /** From the thread's report to its exit, when the outcome becomes known. */
+    readonly exitMs: number;
+    /** From the request to a validated result. */
+    readonly readinessMs: number;
+    /** The main thread's two synchronous sections: starting the thread, and
+     * confirming its committed result, including that thread's first SQLite use. */
+    readonly spawnMs: number;
+    readonly confirmMs: number;
+}
+export declare const objectAt: (file: string) => string | null;
+/** Awaited before a file's first handle; later calls share the outcome. The
+ * host never replaces an initialized file, so another object at its name
+ * fails every later opener rather than initializing beside a held one. */
+export declare function initializeGroundDatabase(file: string): Promise<GroundInitialization>;
+/** Every opener of a ground file, read-only or not, on any connection. */
+export declare function assertGroundInitialized(file: string): void;

package/dist/ground-initialization.js

@@ -0,0 +1,102 @@
+/**
+ * The one owner of a ground database's initialization in this process.
+ *
+ * Migration and the process's ground epoch run once per file per process,
+ * before any ordinary handle exists. They run on a bootstrap thread, never
+ * the main one: atomicity belongs to the migration's transactions, not to
+ * the thread that runs them. The outcome is known only once that thread has
+ * exited, and no opener may read or write the file until its committed
+ * result is validated here. A failed initialization leaves nothing
+ * recorded, so the next attempt validates the file afresh.
+ */
+import { statSync } from "node:fs";
+import { moduleThread } from "./module-thread.js";
+import { physicalKey } from "./source-signature.js";
+import { databaseFileName, openFileDatabase } from "./sqlite.js";
+const at = () => performance.timeOrigin + performance.now();
+const WORKER = new URL("./ground-initialization-worker.js", import.meta.url);
+const initializing = new Map();
+/** Each initialized file, by the object it initialized. */
+const initialized = new Map();
+export const objectAt = (file) => {
+    try {
+        return physicalKey(statSync(file, { bigint: true }));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+};
+/** Awaited before a file's first handle; later calls share the outcome. The
+ * host never replaces an initialized file, so another object at its name
+ * fails every later opener rather than initializing beside a held one. */
+export function initializeGroundDatabase(file) {
+    const name = databaseFileName(file);
+    let pending = initializing.get(name);
+    if (!pending) {
+        pending = bootstrap(name);
+        initializing.set(name, pending);
+        pending.catch(() => { if (initializing.get(name) === pending)
+            initializing.delete(name); });
+    }
+    return pending;
+}
+/** Every opener of a ground file, read-only or not, on any connection. */
+export function assertGroundInitialized(file) {
+    const name = databaseFileName(file);
+    const key = initialized.get(name);
+    if (key === undefined)
+        throw new Error(`the ground database ${JSON.stringify(file)} is opened before its initialization completed`);
+    if (objectAt(name) !== key)
+        throw new Error(`the ground database ${JSON.stringify(file)} was replaced after its initialization`);
+}
+function bootstrap(name) {
+    const requested = at();
+    return new Promise((resolveInitialization, reject) => {
+        const worker = moduleThread(WORKER, { workerData: { file: name } });
+        const spawnMs = at() - requested;
+        let report = null;
+        worker.once("message", (message) => { report = message; });
+        worker.once("error", error => { report ??= { ok: false, error }; });
+        // Only an exited thread has released the file: a reply alone is not an outcome.
+        worker.once("exit", code => {
+            const outcome = report;
+            if (!outcome?.ok) {
+                reject(outcome?.error ?? new Error(`ground initialization thread exited with code ${code} before reporting`));
+                return;
+            }
+            const validating = at();
+            try {
+                validate(name, outcome.migration);
+                const now = at();
+                resolveInitialization(Object.freeze({ ...outcome.migration,
+                    startupMs: outcome.startedAt - requested,
+                    exitMs: validating - outcome.reportedAt,
+                    readinessMs: now - requested,
+                    spawnMs,
+                    confirmMs: now - validating }));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+/** The committed file must carry the reported epoch and the generation form. */
+function validate(name, migration) {
+    const database = openFileDatabase(name, { readonly: true, fileMustExist: true });
+    try {
+        const incarnation = database.prepare("SELECT identity FROM ground_incarnation WHERE singleton = 1").pluck().get();
+        const views = database.prepare(`SELECT COUNT(*) FROM sqlite_master
+      WHERE type = 'view' AND name IN ('entities', 'detection_notebook')`).pluck().get();
+        if (incarnation !== migration.incarnation || views !== 2) {
+            throw new Error("the ground database does not hold the initialization its thread reported");
+        }
+    }
+    finally {
+        database.close();
+    }
+    initialized.set(name, objectAt(name));
+}
+//# sourceMappingURL=ground-initialization.js.map

package/dist/ground-initialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-initialization.js","sourceRoot":"","sources":["../src/ground-initialization.ts"],"names":[],"mappings":"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"}

package/dist/ground-install-saves.d.ts

@@ -0,0 +1,63 @@
+import type Database from "better-sqlite3";
+import { type RepositorySealCandidate } from "./detection/seal-law.js";
+import type { RepositoryObservationPair } from "./git-repository-host.js";
+import type { GroundRow } from "./ground-row.js";
+import type { SourceFingerprint } from "./source-signature.js";
+/** Who this ground file belongs to. */
+export interface GroundOwner {
+    readonly userId: string;
+    readonly userEmail: string;
+    readonly deviceId: string;
+}
+export interface InstalledRows {
+    readonly owner: GroundOwner;
+    readonly resourceId: string;
+    /** One root's rows: all it observed, and what it selected for sharing,
+     * absent when selection could not complete and sharing stands as it was. */
+    readonly rows: {
+        readonly observed: readonly GroundRow[];
+        readonly shared: readonly GroundRow[] | null;
+    };
+    readonly repositoryObservations: readonly Omit<RepositoryObservationPair, "proof">[];
+    /** Rows this root held before; each one an inventory's new rows no longer
+     * name leaves that inventory. */
+    readonly previous: readonly Pick<GroundRow, "uuid" | "rootUUID">[];
+    readonly seals: readonly RepositorySealCandidate[];
+}
+/** `install.rows`. */
+export declare function installRows(database: Database.Database, input: InstalledRows): void;
+/** `install.references`: new references and their parents' derived
+ * membership. Each inventory re-derives its own parent version from its own
+ * active children, so a notebook never inherits observation-only state. */
+export declare function installReferences(database: Database.Database, input: {
+    readonly owner: GroundOwner;
+    readonly rows: readonly GroundRow[];
+}): void;
+/** `install.refreshRoot`: a same-filesystem rename preserves identity and
+ * bytes but may advance the root directory's ctime, so the revealed root's
+ * one derived fingerprint is refreshed before its binding makes the committed
+ * graph observable. */
+export declare function refreshRoot(database: Database.Database, input: {
+    readonly workspaceId: string;
+    readonly absolutePath: string;
+    readonly fingerprint: SourceFingerprint;
+}): void;
+/** `install.clearRoot`: every row one root holds, in both inventories. */
+export declare function clearRoot(database: Database.Database, input: {
+    readonly resourceId: string;
+    readonly rootUUID: string;
+}): void;
+/** One Add's journaled intent: its workspace, destination and exact JSON. */
+export interface AddIntentRow {
+    readonly workspaceId: string;
+    readonly destinationPath: string;
+    readonly intentJson: string;
+}
+/** `add.beginIntent`: the proposed intent, or the one already journaled for
+ * that workspace. A destination another pending Add owns refuses. */
+export declare function beginAddIntent(database: Database.Database, proposed: AddIntentRow): {
+    readonly intentJson: string;
+    readonly created: boolean;
+};
+/** `add.clearIntent`. */
+export declare function clearAddIntent(database: Database.Database, workspaceId: string): void;