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

package/dist/ground-install-saves.js

@@ -0,0 +1,139 @@
+/**
+ * Installation's writes, run only by the ground file's saver thread
+ * (ground-saver.ts): rows a login install, direct persist or Add reveal
+ * projects, the references Add renders and their parents' membership, the
+ * revealed root's refreshed fingerprint, a root's retired rows, and the Add
+ * intent that journals one Add. The main thread derives every row and closes
+ * every physical witness before it posts.
+ */
+import { createHash } from "node:crypto";
+import { canonicalVersion, membershipHash } from "@amalgm/live";
+import { installRepositorySeal } from "./detection/seal-law.js";
+import { groundStore } from "./ground-store.js";
+import { cachedStatement } from "./sqlite.js";
+const sha256Hex = (input) => createHash("sha256").update(input).digest("hex");
+function writeOwner(database, owner) {
+    cachedStatement(database, `
+    INSERT INTO ground_identity(singleton, user_id, user_email, device_id)
+    VALUES(1, ?, ?, ?)
+    ON CONFLICT(singleton) DO UPDATE SET
+      user_id = excluded.user_id,
+      user_email = excluded.user_email,
+      device_id = excluded.device_id
+  `).run(owner.userId, owner.userEmail, owner.deviceId);
+}
+/** `install.rows`. */
+export function installRows(database, input) {
+    groundStore(database).write(writer => {
+        writeOwner(database, input.owner);
+        for (const pair of input.repositoryObservations)
+            writer.observeRepository(pair);
+        const replace = (inventory, rows) => {
+            const current = new Set(rows.map(row => row.uuid));
+            for (const old of input.previous) {
+                if (current.has(old.uuid))
+                    continue;
+                const held = writer.get(inventory, old.uuid);
+                if (held?.resourceId === input.resourceId && held.rootUUID === old.rootUUID)
+                    writer.remove(inventory, old.uuid);
+            }
+            if (inventory === "entities")
+                writer.replace(inventory, rows);
+            else
+                writer.replace(inventory, rows, [], "replace");
+        };
+        replace("entities", input.rows.observed);
+        if (input.rows.shared)
+            replace("detection_notebook", input.rows.shared);
+        for (const seal of input.seals)
+            installRepositorySeal(database, seal);
+    });
+}
+/** `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 function installReferences(database, input) {
+    groundStore(database).write(writer => {
+        writeOwner(database, input.owner);
+        writer.replace("entities", input.rows);
+        writer.replace("detection_notebook", input.rows, [], "replace");
+        for (const parentId of new Set(input.rows.map(row => row.parentUUID))) {
+            for (const inventory of ["entities", "detection_notebook"]) {
+                const parent = writer.get(inventory, parentId);
+                if (!parent)
+                    throw new Error(`reference parent ${parentId} left ${inventory} during Add`);
+                const membership = membershipHash(cachedStatement(database, `SELECT uuid, name FROM ${inventory} WHERE parent_uuid = ? AND status = 'active'`)
+                    .all(parentId), sha256Hex);
+                writer.update(inventory, parentId, {
+                    version: canonicalVersion({
+                        type: parent.type,
+                        parentUUID: parent.parentUUID,
+                        name: parent.name,
+                        status: parent.status,
+                        payloadVersion: membership,
+                    }, sha256Hex),
+                }, inventory === "detection_notebook" ? "replace" : undefined);
+            }
+        }
+    });
+}
+/** `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 function refreshRoot(database, input) {
+    const { workspaceId, absolutePath, fingerprint } = input;
+    groundStore(database).write(writer => {
+        const current = writer.get("entities", workspaceId);
+        if (!current || current.absolutePath !== absolutePath) {
+            throw new Error(`revealed workspace ${workspaceId} has no committed root row`);
+        }
+        writer.update("entities", workspaceId, fingerprint);
+        const notebook = writer.get("detection_notebook", workspaceId);
+        if (notebook?.absolutePath === absolutePath)
+            writer.update("detection_notebook", workspaceId, fingerprint, "retain-equivalent");
+    });
+}
+/** `install.clearRoot`: every row one root holds, in both inventories. */
+export function clearRoot(database, input) {
+    groundStore(database).write(writer => {
+        for (const inventory of ["entities", "detection_notebook"]) {
+            const uuids = cachedStatement(database, `SELECT uuid FROM ${inventory} WHERE resource_id = ? AND root_uuid = ?`)
+                .pluck().all(input.resourceId, input.rootUUID);
+            for (const uuid of uuids)
+                writer.remove(inventory, uuid);
+        }
+    });
+}
+/** `add.beginIntent`: the proposed intent, or the one already journaled for
+ * that workspace. A destination another pending Add owns refuses. */
+export function beginAddIntent(database, proposed) {
+    let inserted;
+    try {
+        inserted = cachedStatement(database, `
+      INSERT INTO workspace_add_intents(workspace_uuid, destination_path, intent_json)
+      VALUES (?, ?, ?)
+      ON CONFLICT(workspace_uuid) DO NOTHING
+    `).run(proposed.workspaceId, proposed.destinationPath, proposed.intentJson);
+    }
+    catch (error) {
+        const destinationOwner = cachedStatement(database, "SELECT workspace_uuid AS workspaceId FROM workspace_add_intents WHERE destination_path = ?")
+            .get(proposed.destinationPath);
+        if (destinationOwner) {
+            throw new Error(`workspace Add destination belongs to pending workspace ${destinationOwner.workspaceId}`);
+        }
+        throw error;
+    }
+    if (inserted.changes === 1)
+        return { intentJson: proposed.intentJson, created: true };
+    const existing = cachedStatement(database, "SELECT intent_json AS intentJson FROM workspace_add_intents WHERE workspace_uuid = ?")
+        .get(proposed.workspaceId);
+    if (!existing)
+        throw new Error(`workspace Add intent ${proposed.workspaceId} was not persisted`);
+    return { intentJson: existing.intentJson, created: false };
+}
+/** `add.clearIntent`. */
+export function clearAddIntent(database, workspaceId) {
+    cachedStatement(database, "DELETE FROM workspace_add_intents WHERE workspace_uuid = ?").run(workspaceId);
+}
+//# sourceMappingURL=ground-install-saves.js.map

package/dist/ground-install-saves.js.map

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

package/dist/ground-inventory-schema.d.ts

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+declare const SHAPES: {
+    readonly fresh: "-,-,-,-,-";
+    readonly flat: "table,table,-,-,-";
+    readonly generations: "view,view,table,table,table";
+};
+/** What the migration found, how long converting it took to prove, and how
+ * many keys it built. */
+export interface InventoryMigration {
+    readonly from: keyof typeof SHAPES;
+    readonly validationMs: number;
+    readonly keysBuilt: number;
+}
+/** Recognizes one of three coherent states and leaves the generation form
+ * with exactly the declared keys. Any other mixture of these objects fails
+ * the open unchanged. */
+export declare function ensureInventorySchema(database: Database.Database): InventoryMigration;
+export {};

package/dist/ground-inventory-schema.js

@@ -0,0 +1,168 @@
+/** The storage of the two ground inventories: base tables holding stored
+ * generations, one visible generation per root, and read-only views that
+ * every reader uses.
+ *
+ * `ground_roots` names which stored generation supplies a root's ordinary
+ * O/B view. It is storage bookkeeping, never declaration, binding or
+ * materialization truth. Generations are opaque identities, never ordered. */
+import { randomUUID } from "node:crypto";
+import { INVENTORY_ROWS, inventoryColumns } from "./ground-row.js";
+const INVENTORIES = ["entities", "detection_notebook"];
+const ROW_COLUMNS = `
+      resource_id TEXT NOT NULL,
+      root_uuid TEXT NOT NULL,
+      type TEXT NOT NULL,
+      parent_uuid TEXT,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL,
+      version TEXT NOT NULL,
+      payload_version TEXT,
+      transport_version TEXT,
+      relative_path TEXT NOT NULL,
+      absolute_path TEXT NOT NULL,
+      physical_key TEXT NOT NULL,
+      source_signature TEXT,
+      filesystem_mode INTEGER,
+      content_verified_ns TEXT`;
+const TABLES = `
+    CREATE TABLE ground_roots (
+      root_uuid TEXT PRIMARY KEY,
+      generation TEXT NOT NULL
+    ) WITHOUT ROWID;
+    CREATE TABLE entity_rows (
+      uuid TEXT NOT NULL,
+      generation TEXT NOT NULL,${ROW_COLUMNS},
+      git_configuration_observation TEXT,
+      PRIMARY KEY(uuid, generation),
+      UNIQUE(resource_id, root_uuid, relative_path, generation)
+    );
+    CREATE TABLE notebook_rows (
+      uuid TEXT NOT NULL,
+      generation TEXT NOT NULL,${ROW_COLUMNS},
+      local_admission_mutation_id TEXT,
+      PRIMARY KEY(uuid, generation)
+    );`;
+const VIEWS = INVENTORIES.map(inventory => `CREATE VIEW ${inventory}(${inventoryColumns(inventory).join(", ")}) AS
+      SELECT ${inventoryColumns(inventory).map(column => `b.${column}`).join(", ")} FROM ${INVENTORY_ROWS[inventory]} b
+      JOIN ground_roots r ON r.root_uuid = b.root_uuid AND r.generation = b.generation;`).join("\n");
+/** The stored rows' secondary keys, by name. Every key is the flat
+ * inventory's, except the root/path key: led by the root's generation, a
+ * root-scoped read visits only the visible generation however many others
+ * are stored, and each inventory's slot key: who holds a portable
+ * (parent, name) slot is one probe, never a pass over the parent's children.
+ * A key also yields its reader's order, since the planner otherwise prefers
+ * the key that does: a slot key without UUID loses to the child key. */
+const KEYS = {
+    entity_rows_by_root_path: "entity_rows(root_uuid, generation, relative_path)",
+    entity_rows_by_absolute_path: "entity_rows(absolute_path)",
+    entity_rows_repository_bindings: "entity_rows(uuid) WHERE type = 'repo.git' AND status = 'active'",
+    entity_rows_by_physical_identity: "entity_rows(physical_key)",
+    entity_rows_by_parent_uuid: "entity_rows(parent_uuid, uuid)",
+    entity_rows_by_slot: "entity_rows(parent_uuid, name, uuid)",
+    notebook_rows_by_root_path: "notebook_rows(root_uuid, generation, relative_path)",
+    notebook_rows_by_absolute_path: "notebook_rows(absolute_path)",
+    notebook_rows_by_parent_uuid: "notebook_rows(parent_uuid, uuid)",
+    notebook_rows_by_slot: "notebook_rows(parent_uuid, name, uuid)",
+    notebook_rows_by_physical_identity: "notebook_rows(physical_key)",
+    notebook_rows_by_payload: "notebook_rows(payload_version) WHERE payload_version IS NOT NULL",
+    notebook_rows_by_transport: "notebook_rows(transport_version) WHERE transport_version IS NOT NULL",
+};
+/** Keys are derived storage, so every open leaves exactly the declared ones:
+ * a key stored under another definition is rebuilt, an undeclared one
+ * dropped, a missing one built. Returns how many it built. */
+function ensureInventoryKeys(database) {
+    const stored = new Map(database.prepare(`SELECT name, sql FROM sqlite_master
+    WHERE type = 'index' AND sql IS NOT NULL AND tbl_name IN ('entity_rows', 'notebook_rows')`)
+        .all().map(({ name, sql }) => [name, sql]));
+    const declared = new Map(Object.entries(KEYS).map(([name, key]) => [name, `CREATE INDEX ${name} ON ${key}`]));
+    const built = [...declared].filter(([name, sql]) => stored.get(name) !== sql);
+    const dropped = [...stored].filter(([name, sql]) => declared.get(name) !== sql);
+    if (built.length || dropped.length) {
+        database.transaction(() => {
+            for (const [name] of dropped)
+                database.exec(`DROP INDEX ${name}`);
+            for (const [, sql] of built)
+                database.exec(sql);
+        })();
+    }
+    return built.length;
+}
+const OBJECTS = ["entities", "detection_notebook", "entity_rows", "notebook_rows", "ground_roots"];
+const SHAPES = {
+    fresh: "-,-,-,-,-",
+    flat: "table,table,-,-,-",
+    generations: "view,view,table,table,table",
+};
+/** Recognizes one of three coherent states and leaves the generation form
+ * with exactly the declared keys. Any other mixture of these objects fails
+ * the open unchanged. */
+export function ensureInventorySchema(database) {
+    const found = new Map(database.prepare(`SELECT name, type FROM sqlite_master WHERE name IN (${OBJECTS.map(() => "?").join(", ")})`)
+        .all(...OBJECTS).map(({ name, type }) => [name, type]));
+    const shape = OBJECTS.map(name => found.get(name) ?? "-").join(",");
+    if (shape === SHAPES.generations)
+        return { from: "generations", validationMs: 0, keysBuilt: ensureInventoryKeys(database) };
+    if (shape === SHAPES.fresh) {
+        database.transaction(() => database.exec(TABLES + VIEWS))();
+        return { from: "fresh", validationMs: 0, keysBuilt: ensureInventoryKeys(database) };
+    }
+    if (shape !== SHAPES.flat) {
+        throw new Error(`the ground inventories are in an unrecognized schema state (${OBJECTS.join(",")} = ${shape})`);
+    }
+    const validationMs = convertFlatInventories(database);
+    return { from: "flat", validationMs, keysBuilt: ensureInventoryKeys(database) };
+}
+/** One transaction: the flat tables step aside, their rows are copied under
+ * one generation per root shared by both inventories, the views must then
+ * reproduce both inventories exactly, and only then are the flat tables
+ * dropped. A failure rolls everything back. Rows move as storage; no ground
+ * write, stamp, history or Record is produced. */
+function convertFlatInventories(database) {
+    return database.transaction(() => {
+        const flat = { entities: "flat_entities", detection_notebook: "flat_notebook" };
+        for (const inventory of INVENTORIES)
+            database.exec(`ALTER TABLE ${inventory} RENAME TO ${flat[inventory]}`);
+        database.exec(TABLES);
+        const place = database.prepare("INSERT INTO ground_roots(root_uuid, generation) VALUES (?, ?)");
+        for (const root of database.prepare(`SELECT root_uuid FROM ${flat.entities}
+      UNION SELECT root_uuid FROM ${flat.detection_notebook}`).pluck().all())
+            place.run(root, randomUUID());
+        const stored = {};
+        for (const inventory of INVENTORIES) {
+            const columns = inventoryColumns(inventory);
+            const table = database.prepare(`PRAGMA table_info(${flat[inventory]})`).all();
+            const present = table.map(({ name }) => name);
+            const unknown = present.filter(column => !columns.includes(column));
+            if (unknown.length)
+                throw new Error(`the flat ${inventory} inventory has unknown columns: ${unknown.join(", ")}`);
+            if (table.filter(({ pk }) => pk > 0).map(({ name }) => name).join() !== "uuid") {
+                throw new Error(`the flat ${inventory} inventory is not keyed by its UUID alone`);
+            }
+            stored[inventory] = present;
+            // A column the flat table never gained holds no value in any row.
+            database.exec(`INSERT INTO ${INVENTORY_ROWS[inventory]}(generation, ${columns.join(", ")})
+        SELECT r.generation, ${columns.map(column => present.includes(column) ? `f.${column}` : "NULL").join(", ")}
+        FROM ${flat[inventory]} f JOIN ground_roots r ON r.root_uuid = f.root_uuid`);
+        }
+        database.exec(VIEWS);
+        const validating = performance.now();
+        // A flat row is keyed by its UUID, and a visible row is fixed by its UUID
+        // and root, so an equal pair matches each side at most once. Every flat
+        // row having an equal visible row, with equal counts, makes the visible
+        // rows exactly the flat rows, each UUID once.
+        for (const inventory of INVENTORIES) {
+            const equal = stored[inventory].map(column => `f.${column} IS v.${column}`).join(" AND ");
+            const differs = database.prepare(`SELECT
+          (SELECT COUNT(*) FROM ${flat[inventory]}) <> (SELECT COUNT(*) FROM ${inventory})
+          OR (SELECT COUNT(*) FROM ${flat[inventory]} f JOIN ${inventory} v ON v.uuid = f.uuid WHERE ${equal})
+            <> (SELECT COUNT(*) FROM ${flat[inventory]})`).pluck().get();
+            if (differs)
+                throw new Error(`the converted ${inventory} view does not reproduce its flat inventory`);
+        }
+        const validationMs = performance.now() - validating;
+        for (const inventory of INVENTORIES)
+            database.exec(`DROP TABLE ${flat[inventory]}`);
+        return validationMs;
+    })();
+}
+//# sourceMappingURL=ground-inventory-schema.js.map

package/dist/ground-inventory-schema.js.map

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

package/dist/ground-profile.d.ts

@@ -0,0 +1,7 @@
+export interface GroundProfile {
+    readonly id: string;
+    /** How far below the stamp a time must lie; null when untrusted. */
+    readonly marginNs: bigint | null;
+}
+/** The profile of the filesystem holding path, read now. */
+export declare function groundProfile(path: string): GroundProfile;

package/dist/ground-profile.js

@@ -0,0 +1,52 @@
+/** The filesystems whose own times Detect trusts. Two shortcuts rest on them:
+ * an unchanged signature standing for unchanged content, and directory
+ * signatures that held still closing a namespace. Both need every change to
+ * an object to move its times forward from the kernel's one timestamp source,
+ * the same source that writes the root's content-clock stamp. A later change
+ * then carries a time at or after the stamp, and a time strictly before it
+ * names ground that has held since. Only a filesystem named here is trusted;
+ * any other keeps neither shortcut and still reaches every conclusion: its
+ * leaves are reread, and its listings close only by being listed again after
+ * the walk (see detection/ground-proof.ts). Mounting over an entry moves no
+ * time and is outside every profile.
+ *
+ * A time is kept at its inode's own resolution. Ext inodes without extra
+ * time fields hold whole seconds beside inodes that hold nanoseconds, so
+ * source-signature.ts reads any time without a subsecond part as covering its
+ * whole second. The margin is kept below the stamp as defense against one
+ * kernel handing out times from two sources that disagree within a scheduler
+ * tick; the proof is the single source, not the margin.
+ *
+ * statfs names a filesystem by number. On Linux that is the superblock magic,
+ * kernel ABI. On macOS it is the number APFS registered in this boot, so it
+ * is resolved from the boot volume, which every macOS this runtime supports
+ * requires to be APFS. The profile id names the law's version, and the
+ * content clock records the id it stamped under, so a changed qualification
+ * retires every proof minted under the old one. */
+import { statfsSync } from "node:fs";
+/** Bumped whenever what a trusted profile qualifies changes. */
+const LAW = 2;
+const MARGIN_NS = 10000000n;
+let darwinApfs;
+function trustedName(type) {
+    if (process.platform === "darwin")
+        return type === (darwinApfs ??= statfsSync("/").type) ? "apfs" : undefined;
+    if (process.platform !== "linux")
+        return undefined;
+    switch (type) {
+        // ext2, ext3 and ext4 share one magic.
+        case 0xef53: return "ext";
+        case 0x58465342: return "xfs";
+        case 0x9123683e: return "btrfs";
+        case 0x01021994: return "tmpfs";
+        default: return undefined;
+    }
+}
+/** The profile of the filesystem holding path, read now. */
+export function groundProfile(path) {
+    const type = statfsSync(path).type;
+    const name = trustedName(type);
+    return name === undefined ? { id: `${process.platform}:${type}`, marginNs: null }
+        : { id: `${name}@${LAW}`, marginNs: MARGIN_NS };
+}
+//# sourceMappingURL=ground-profile.js.map

package/dist/ground-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-profile.js","sourceRoot":"","sources":["../src/ground-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;mDAwBmD;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,gEAAgE;AAChE,MAAM,GAAG,GAAG,CAAC,CAAC;AAQd,MAAM,SAAS,GAAG,SAAW,CAAC;AAE9B,IAAI,UAA8B,CAAC;AAEnC,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9G,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACnD,QAAQ,IAAI,EAAE,CAAC;QACb,uCAAuC;QACvC,KAAK,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC;QAC1B,KAAK,UAAU,CAAC,CAAC,OAAO,KAAK,CAAC;QAC9B,KAAK,UAAU,CAAC,CAAC,OAAO,OAAO,CAAC;QAChC,KAAK,UAAU,CAAC,CAAC,OAAO,OAAO,CAAC;QAChC,OAAO,CAAC,CAAC,OAAO,SAAS,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC/E,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC"}

package/dist/ground-root-index.d.ts

@@ -5,7 +5,8 @@ export interface OutermostGroundRoot {
 /**
  * Assign materialized rows to disjoint outermost roots in one pass. Walking a
  * row's ancestors is bounded by path depth; comparing every row with every
- * registered root makes restart work grow with roots × entities.
+ * registered root makes restart work grow with roots × entities. Each
+ * directory's answer is remembered, so siblings share one ancestor walk.
  */
 export declare function indexRowsByOutermostRoot<T extends {
     readonly absolutePath: string;

package/dist/ground-root-index.js

@@ -2,24 +2,26 @@ import { dirname, resolve } from "node:path";
 /**
  * Assign materialized rows to disjoint outermost roots in one pass. Walking a
  * row's ancestors is bounded by path depth; comparing every row with every
- * registered root makes restart work grow with roots × entities.
+ * registered root makes restart work grow with roots × entities. Each
+ * directory's answer is remembered, so siblings share one ancestor walk.
  */
 export function indexRowsByOutermostRoot(roots, rows) {
-    const rootAtDirectory = new Map(roots.map(({ rootId, directory }) => [resolve(directory), rootId]));
+    const owner = new Map(roots.map(({ rootId, directory }) => [resolve(directory), rootId]));
     const rowsByRoot = new Map(roots.map(({ rootId }) => [rootId, []]));
+    const ownerOf = (directory) => {
+        const known = owner.get(directory);
+        if (known !== undefined)
+            return known;
+        const parent = dirname(directory);
+        const found = parent === directory ? null : ownerOf(parent);
+        owner.set(directory, found);
+        return found;
+    };
     for (const row of rows) {
-        let cursor = resolve(row.absolutePath);
-        while (true) {
-            const rootId = rootAtDirectory.get(cursor);
-            if (rootId) {
-                rowsByRoot.get(rootId)?.push(row);
-                break;
-            }
-            const parent = dirname(cursor);
-            if (parent === cursor)
-                break;
-            cursor = parent;
-        }
+        const path = resolve(row.absolutePath);
+        const rootId = owner.get(path) ?? ownerOf(dirname(path));
+        if (rootId)
+            rowsByRoot.get(rootId)?.push(row);
     }
     return rowsByRoot;
 }

package/dist/ground-root-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"ground-root-index.js","sourceRoot":"","sources":["../src/ground-root-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAO7C;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAqC,EACrC,IAAkB;IAElB,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACpG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAS,CAAC,CAAC,CAAC,CAAC;IAC3E,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACvC,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,MAAM,EAAE,CAAC;gBACX,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;gBAClC,MAAM;YACR,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,MAAM;gBAAE,MAAM;YAC7B,MAAM,GAAG,MAAM,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"ground-root-index.js","sourceRoot":"","sources":["../src/ground-root-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAO7C;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAqC,EACrC,IAAkB;IAElB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAwB,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACjH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAS,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAiB,EAAE;QACnD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5D,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,IAAI,MAAM;YAAE,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/ground-row.d.ts

@@ -0,0 +1,62 @@
+import { type CloudEntityRecord, type EntityType } from "@amalgm/live";
+export interface GroundRow {
+    readonly resourceId: string;
+    readonly rootUUID: string;
+    readonly uuid: string;
+    readonly type: EntityType;
+    readonly parentUUID: string | null;
+    readonly name: string;
+    readonly status: CloudEntityRecord["status"];
+    readonly version: string;
+    readonly payloadVersion: string | null;
+    readonly transportVersion: string | null;
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    /** Exact `device:inode` decimal (source-signature.ts). */
+    readonly physicalKey: string;
+    /** The exact stat this row was observed at; null is never unchanged. */
+    readonly sourceSignature: string | null;
+    /** The observed mode: kind and executable posture. */
+    readonly filesystemMode: number | null;
+    /** Exact nanosecond boundary of the last real content read, in decimal. */
+    readonly contentVerifiedNs: string | null;
+    /** Machine-local O only. Absence means no qualified repository observation;
+     * neither a B row nor imported cargo can establish this source fact. */
+    readonly gitConfigurationObservation?: string | null;
+}
+/** Local Record provenance belongs only to the admitted sharing baseline. */
+/** Stored addresses are resolved absolute paths, so one lies at or beneath
+ * another exactly when it extends it at a separator; nothing is resolved. */
+export declare const storedWithin: (top: string, address: string) => boolean;
+export interface SharingGroundRow extends GroundRow {
+    readonly localAdmissionMutationId: string | null;
+}
+export declare const GROUND_ROW_PROJECTION: string;
+export declare const SHARING_ROW_PROJECTION: string;
+export declare const groundRowProjection: (inventory: "entities" | "detection_notebook") => string;
+/** Every stored column of one inventory row, in its view's order; the order
+ * of `groundRowValues(row, inventory)`. */
+export declare const inventoryColumns: (inventory: "entities" | "detection_notebook") => readonly string[];
+/** Each inventory is a read-only view of its base table: a stored row is
+ * visible exactly when its generation is its root's visible generation. Only
+ * the schema owner and the ground writer name a base table. */
+export declare const INVENTORY_ROWS: {
+    readonly entities: "entity_rows";
+    readonly detection_notebook: "notebook_rows";
+};
+/** Caller-only convenience fields are not part of the persisted row. */
+export declare function groundRowSnapshot(row: GroundRow, inventory?: "entities" | "detection_notebook"): GroundRow;
+/** Local ground ends at its materialization root: the root's portable parent
+ * may lie in a workspace this machine never materialized. */
+export declare const localParentOf: (row: Pick<GroundRow, "uuid" | "rootUUID" | "parentUUID">) => string | null;
+export declare function portableGroundRecord(row: GroundRow): CloudEntityRecord;
+/** Active with no trashed or deleted ancestor up to its materialization root,
+ * each ancestor read from the row's own inventory through `lookup`. */
+export declare const effectivelyActive: (row: GroundRow, lookup: (uuid: string) => GroundRow | undefined) => boolean;
+/** The same answer by induction down a proved chain: beneath an effectively
+ * active parent, a row is effectively active exactly when it is itself active
+ * and that parent is its own. */
+export declare const activeUnder: (row: GroundRow, parent: Pick<GroundRow, "uuid">) => boolean;
+/** O and B read sets include their distinct local facts. An omitted inventory
+ * requests only common columns, used when writing B through its admission owner. */
+export declare function groundRowValues(row: GroundRow, inventory?: "entities" | "detection_notebook"): readonly unknown[];

package/dist/ground-row.js

@@ -0,0 +1,70 @@
+/** SQLite row codec shared by observation, sharing admission and verified Apply.
+ * Sharing rows and physical rows use the same identity vocabulary; using this
+ * codec never grants one inventory the meaning or ownership of the other. */
+import { sep } from "node:path";
+import { effectiveStatusOf, portableFileMode } from "@amalgm/live";
+/** Local Record provenance belongs only to the admitted sharing baseline. */
+/** Stored addresses are resolved absolute paths, so one lies at or beneath
+ * another exactly when it extends it at a separator; nothing is resolved. */
+export const storedWithin = (top, address) => address.startsWith(top)
+    && (address.length === top.length || top.endsWith(sep) || address[top.length] === sep);
+/** One field-to-column map owns SQL values, reads and detached row evidence. */
+const fields = {
+    uuid: "uuid", resourceId: "resource_id", rootUUID: "root_uuid", type: "type",
+    parentUUID: "parent_uuid", name: "name", status: "status", version: "version",
+    payloadVersion: "payload_version", transportVersion: "transport_version",
+    relativePath: "relative_path", absolutePath: "absolute_path", physicalKey: "physical_key",
+    sourceSignature: "source_signature", filesystemMode: "filesystem_mode",
+    contentVerifiedNs: "content_verified_ns",
+};
+const keys = Object.keys(fields);
+export const GROUND_ROW_PROJECTION = keys.map(key => `${fields[key]} AS ${key}`).join(", ");
+export const SHARING_ROW_PROJECTION = `${GROUND_ROW_PROJECTION}, local_admission_mutation_id AS localAdmissionMutationId`;
+export const groundRowProjection = (inventory) => inventory === "entities" ? `${GROUND_ROW_PROJECTION}, git_configuration_observation AS gitConfigurationObservation` : SHARING_ROW_PROJECTION;
+/** Every stored column of one inventory row, in its view's order; the order
+ * of `groundRowValues(row, inventory)`. */
+export const inventoryColumns = (inventory) => [...Object.values(fields), inventory === "entities" ? "git_configuration_observation" : "local_admission_mutation_id"];
+/** Each inventory is a read-only view of its base table: a stored row is
+ * visible exactly when its generation is its root's visible generation. Only
+ * the schema owner and the ground writer name a base table. */
+export const INVENTORY_ROWS = { entities: "entity_rows", detection_notebook: "notebook_rows" };
+/** Caller-only convenience fields are not part of the persisted row. */
+export function groundRowSnapshot(row, inventory = "entities") {
+    return Object.freeze({ ...Object.fromEntries(keys.map(key => [key, row[key]])),
+        ...(inventory === "entities" ? { gitConfigurationObservation: row.gitConfigurationObservation ?? null } : {
+            localAdmissionMutationId: row.localAdmissionMutationId ?? null,
+        }) });
+}
+/** Local ground ends at its materialization root: the root's portable parent
+ * may lie in a workspace this machine never materialized. */
+export const localParentOf = (row) => row.uuid === row.rootUUID ? null : row.parentUUID;
+export function portableGroundRecord(row) {
+    return {
+        uuid: row.uuid,
+        type: row.type,
+        parentUUID: row.parentUUID,
+        name: row.name,
+        status: row.status,
+        version: row.version,
+        payloadVersion: row.payloadVersion,
+        fileMode: portableFileMode(row.type, row.filesystemMode),
+        transportVersion: row.transportVersion,
+    };
+}
+/** Active with no trashed or deleted ancestor up to its materialization root,
+ * each ancestor read from the row's own inventory through `lookup`. */
+export const effectivelyActive = (row, lookup) => effectiveStatusOf({ status: row.status, parentUuid: localParentOf(row) }, uuid => {
+    const parent = lookup(uuid);
+    return parent && { ...portableGroundRecord(parent), parentUuid: localParentOf(parent) };
+}) === "active";
+/** The same answer by induction down a proved chain: beneath an effectively
+ * active parent, a row is effectively active exactly when it is itself active
+ * and that parent is its own. */
+export const activeUnder = (row, parent) => row.status === "active" && localParentOf(row) === parent.uuid;
+/** O and B read sets include their distinct local facts. An omitted inventory
+ * requests only common columns, used when writing B through its admission owner. */
+export function groundRowValues(row, inventory) {
+    return [...keys.map(key => row[key]), ...(inventory === "entities" ? [row.gitConfigurationObservation ?? null]
+            : inventory === "detection_notebook" ? [row.localAdmissionMutationId ?? null] : [])];
+}
+//# sourceMappingURL=ground-row.js.map

package/dist/ground-row.js.map

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