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

package/dist/ground-coordination.js

@@ -5,9 +5,95 @@
  * cones it touches. Two effects conflict only when one cone contains the
  * other; unrelated cones proceed concurrently. Conflicting effects are served
  * in request order, so a stream of small effects can never starve an earlier
- * large one, and a timed-out waiter leaves the queue instead of poisoning it.
+ * large one, and a cancelled waiter leaves the queue instead of poisoning it.
+ *
+ * Detect collects without holding cones. A lease opens only when no
+ * conflicting effect is held: the check and the open are one step, and a
+ * collection that finds ground held waits, holding nothing, for its release.
+ * The lease then records whether any conflicting effect was granted before
+ * admission; admission accepts only an uncrossed lease, checked synchronously
+ * inside the admitting transaction. Every grant follows an await, so no
+ * effect can begin between that check and commit.
+ *
+ * A collection that learns it read ground outside its cones (Git storage a
+ * checkout keeps elsewhere) fails its lease and retries; the coordinator
+ * remembers that extent for the cones that needed it, so the next lease of
+ * them names it from the start.
+ *
+ * A file changed in place (Git appends to a reflog, and may chmod it) is
+ * reachable through every other link to it, and those links lie outside the
+ * effect's cones. Such an effect declares the physical keys it may change;
+ * a collection records the physical key of every regular file it read, since
+ * a link to it may appear while it reads. A lease is crossed when an effect
+ * held at any time since it opened declared a key it read.
+ * Holds order cone conflicts only: this class is detected, not queued.
+ *
+ * A lease also keeps every effect held at any time while it is open, so one
+ * collection can admit in independent units. An effect at cone C may change
+ * anything at or under C and the entry list of C's parent, nothing else
+ * except its declared in-place keys. A unit is crossed only when one of those
+ * meets what the unit read; sibling churn does not cross a route through
+ * their shared parent.
  */
-import { resolve, sep } from "node:path";
+import { channel } from "node:diagnostics_channel";
+import { dirname, resolve, sep } from "node:path";
+import { DetectionBasisAdvancedError } from "./detection/basis-advanced.js";
+/** Examiners hear each wait on held ground, once as it begins and once as it
+ * ends, labelled with the waiting lane: a Detect lane or an effect's owner.
+ * Opening at once is no wait. */
+const groundWaits = channel("amalgm:ground-wait");
+let waitIds = 0;
+const waiting = (lane) => {
+    if (!groundWaits.hasSubscribers)
+        return () => { };
+    const id = ++waitIds;
+    groundWaits.publish({ id, lane, waiting: true, at: performance.now() });
+    return () => { groundWaits.publish({ id, lane, waiting: false, at: performance.now() }); };
+};
+/** Settles with `wait`, or rejects when the signal aborts first. */
+const abortable = (wait, signal) => new Promise((resolveWait, rejectAborted) => {
+    const aborted = () => rejectAborted(signal.reason);
+    signal.addEventListener("abort", aborted, { once: true });
+    void wait.then(() => {
+        signal.removeEventListener("abort", aborted);
+        resolveWait();
+    });
+});
+/** Keys read on this thread. */
+export class PhysicalKeySet {
+    #keys;
+    constructor(keys) { this.#keys = new Set(keys); }
+    has(key) { return this.#keys.has(key); }
+}
+/** One key's exact (device, inode) as the 64-bit patterns a BigInt64Array
+ * stores, whichever sign the key was written with. */
+const physicalPair = (key) => {
+    const separator = key.indexOf(":");
+    return [BigInt.asIntN(64, BigInt(key.slice(0, separator))), BigInt.asIntN(64, BigInt(key.slice(separator + 1)))];
+};
+/** Appends a key's exact (device, inode) pair. */
+export function pushPhysicalPair(pairs, key) {
+    pairs.push(...physicalPair(key));
+}
+/** A content thread's reads cross back as one buffer of exact (device,
+ * inode) pairs, never as a key per file. Asked only for a declared key. */
+export class PhysicalKeyPairs {
+    pairs;
+    constructor(pairs) {
+        this.pairs = pairs;
+    }
+    has(key) {
+        if (this.pairs.length === 0)
+            return false;
+        const [device, inode] = physicalPair(key);
+        for (let index = 0; index < this.pairs.length; index += 2) {
+            if (this.pairs[index] === device && this.pairs[index + 1] === inode)
+                return true;
+        }
+        return false;
+    }
+}
+const nothingInPlace = new Set();
 const normalizeCone = (cone) => {
     const normalized = resolve(cone);
     return normalized.endsWith(sep) ? normalized : `${normalized}${sep}`;
@@ -18,8 +104,160 @@ export function conesConflict(left, right) {
     const b = normalizeCone(right);
     return a === b || a.startsWith(b) || b.startsWith(a);
 }
+/** The effect interval belongs to the admission basis. */
+export class GroundEffectCrossedError extends DetectionBasisAdvancedError {
+    constructor() { super("a ground effect crossed this Detect collection; retrying fresh truth"); }
+}
+/** The collection read ground its lease never covered; retry under a lease
+ * that names it. */
+export class GroundFootprintExceededError extends DetectionBasisAdvancedError {
+    addresses;
+    constructor(addresses) {
+        super(`Detect read ground outside its lease (${addresses.join(", ")}); retrying under the wider footprint`);
+        this.addresses = addresses;
+    }
+}
+const leaseState = (cones) => ({ cones, crossed: false, read: [], changed: new Set(), effects: [] });
+/** Normalized addresses end in the separator, so containment is a prefix. */
+const under = (address, cone) => address.startsWith(cone);
+function crossesReads(effects, reads) {
+    if (effects.length === 0)
+        return false;
+    const entries = [...reads.entries ?? []].map(normalizeCone);
+    const routes = [...reads.routes ?? []].map(normalizeCone);
+    const markers = routes.map((route) => `${route}.git${sep}`);
+    const namespaces = new Set([...reads.namespaces ?? []].map(normalizeCone));
+    const physical = reads.physical;
+    const declaredRead = (effect) => {
+        if (physical)
+            for (const key of effect.inPlace)
+                if (physical.has(key))
+                    return true;
+        return false;
+    };
+    return effects.some((effect) => declaredRead(effect)
+        || effect.cones.some((cone) => {
+            if (entries.some((entry) => under(entry, cone) || under(cone, entry)))
+                return true;
+            if (routes.some((route) => under(route, cone)))
+                return true;
+            if (markers.some((marker) => under(marker, cone) || under(cone, marker)))
+                return true;
+            if (namespaces.has(normalizeCone(dirname(cone))))
+                return true;
+            for (const namespace of namespaces)
+                if (under(namespace, cone))
+                    return true;
+            return false;
+        }));
+}
+const crosses = (lease, ticket) => ticket.cones.some((held) => lease.cones.some((read) => conesConflict(held, read)));
+const ticketsConflict = (left, right) => left.cones.some((held) => right.cones.some((wanted) => conesConflict(held, wanted)));
 export class GroundCoordinator {
     #queue = [];
+    #held = new Set();
+    #leases = new Set();
+    /** Requested cone -> ground collections of it were found to read. Only
+     * widens later leases; a stale extent costs concurrency, never truth. */
+    #extents = new Map();
+    #footprint(cones) {
+        const requested = cones.map(normalizeCone);
+        return [...new Set([...requested, ...requested.flatMap((cone) => [...this.#extents.get(cone) ?? []])])];
+    }
+    /** Open a lease now when no conflicting effect is held; otherwise null.
+     * The check and the open are one step. */
+    tryLease(cones) {
+        const state = leaseState(this.#footprint(cones));
+        if ([...this.#held].some((ticket) => crosses(state, ticket)))
+            return null;
+        return this.#open(cones, state);
+    }
+    #open(cones, state) {
+        this.#leases.add(state);
+        for (const ticket of this.#held) {
+            state.effects.push(ticket);
+            for (const key of ticket.inPlace)
+                state.changed.add(key);
+        }
+        return {
+            assertUncrossed: () => { if (state.crossed)
+                throw new GroundEffectCrossedError(); },
+            crosses: (reads) => crossesReads(state.effects, reads),
+            require: (addresses) => {
+                const outside = addresses.map(normalizeCone).filter((address) => !state.cones.some((cone) => address.startsWith(cone)));
+                if (outside.length === 0)
+                    return;
+                for (const cone of cones.map(normalizeCone)) {
+                    const extent = this.#extents.get(cone) ?? new Set();
+                    for (const address of outside)
+                        extent.add(address);
+                    this.#extents.set(cone, extent);
+                }
+                throw new GroundFootprintExceededError(outside);
+            },
+            physical: (reads) => {
+                state.read.push(reads);
+                for (const key of state.changed)
+                    if (reads.has(key))
+                        state.crossed = true;
+            },
+            close: () => { this.#leases.delete(state); },
+        };
+    }
+    /** The conflicting effects held now. */
+    #holding(cones) {
+        const state = leaseState(this.#footprint(cones));
+        return [...this.#held].filter((ticket) => crosses(state, ticket));
+    }
+    /** Whether an effect conflicting with these cones is held now. */
+    holds(cones) {
+        return this.#holding(cones).length > 0;
+    }
+    /** Settles once every conflicting effect held now has released. Waiting
+     * holds nothing. */
+    released(cones, lane) {
+        const holding = this.#holding(cones);
+        if (holding.length === 0)
+            return Promise.resolve();
+        const done = waiting(lane);
+        return Promise.all(holding.map((ticket) => ticket.settled)).then(done);
+    }
+    /** Open a lease once no conflicting effect is held. */
+    async lease(cones, lane, signal) {
+        signal.throwIfAborted();
+        const opened = this.tryLease(cones);
+        if (opened)
+            return opened;
+        const done = waiting(lane);
+        try {
+            for (;;) {
+                await abortable(Promise.all(this.#holding(cones).map((ticket) => ticket.settled)), signal);
+                signal.throwIfAborted();
+                const next = this.tryLease(cones);
+                if (next)
+                    return next;
+            }
+        }
+        finally {
+            done();
+        }
+    }
+    #grant(ticket, release, inPlace) {
+        if (inPlace)
+            ticket.inPlace = new Set(inPlace());
+        this.#held.add(ticket);
+        for (const lease of this.#leases) {
+            lease.effects.push(ticket);
+            if (crosses(lease, ticket))
+                lease.crossed = true;
+            for (const key of ticket.inPlace) {
+                lease.changed.add(key);
+                if (lease.read.some((reads) => reads.has(key)))
+                    lease.crossed = true;
+            }
+        }
+        return () => { this.#held.delete(ticket); release(); };
+    }
     /** Cones currently held or awaited, oldest first. Diagnostics only. */
     get pending() {
         return this.#queue.map((ticket) => ticket.cones);
@@ -32,16 +270,13 @@ export class GroundCoordinator {
     async acquire(cones, options = {}) {
         if (cones.length === 0)
             return () => { };
-        const timeoutMs = options.timeoutMs;
-        if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)) {
-            throw new Error("ground-effect wait timeout must be a positive integer");
-        }
+        options.signal?.throwIfAborted();
         let release;
         const settled = new Promise((resolveSettled) => {
             release = resolveSettled;
         });
-        const ticket = { cones: cones.map(normalizeCone), settled, release };
-        const predecessors = this.#queue.filter((earlier) => earlier.cones.some((held) => ticket.cones.some((wanted) => conesConflict(held, wanted))));
+        const ticket = { cones: cones.map(normalizeCone), settled, release, inPlace: nothingInPlace };
+        const predecessors = this.#queue.filter((earlier) => ticketsConflict(earlier, ticket));
         this.#queue.push(ticket);
         let released = false;
         const releaseOnce = () => {
@@ -53,30 +288,20 @@ export class GroundCoordinator {
                 this.#queue.splice(index, 1);
             ticket.release();
         };
-        const wait = Promise.all(predecessors.map((earlier) => earlier.settled)).then(() => { });
-        if (timeoutMs === undefined) {
-            await wait;
-            return releaseOnce;
-        }
-        let timer = null;
+        const turn = Promise.all(predecessors.map((earlier) => earlier.settled));
+        const done = predecessors.length > 0 ? waiting(options.lane ?? "effect") : () => { };
         try {
-            await Promise.race([
-                wait,
-                new Promise((_resolve, reject) => {
-                    timer = setTimeout(() => reject(new Error(`ground-effect wait exceeded ${timeoutMs}ms`)), timeoutMs);
-                }),
-            ]);
-            return releaseOnce;
+            await (options.signal ? abortable(turn, options.signal) : turn);
+            return this.#grant(ticket, releaseOnce, options.inPlace);
         }
         catch (error) {
-            // A timed-out waiter never held the cones. Leave the queue now so no
+            // A cancelled waiter never held the cones. Leave the queue now so no
             // later effect waits on a slot that will never be used.
             releaseOnce();
             throw error;
         }
         finally {
-            if (timer)
-                clearTimeout(timer);
+            done();
         }
     }
 }

package/dist/ground-coordination.js.map

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

package/dist/ground-database.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The user ground database: its schema and migration, its opener, and the
+ * one read-only main-thread connection every Detect, Record and ground read
+ * shares for the life of its binding. Migration runs only on the bootstrap thread
+ * (ground-initialization.ts); every opener requires its completed result.
+ *
+ * The qualified performance profile gathers no planner statistics: nothing
+ * here runs ANALYZE or an optimizing maintenance call. That is a performance
+ * policy, not a data law: statistics already present are kept and read the
+ * same visible rows, and gathering them needs its own qualification.
+ */
+import type Database from "better-sqlite3";
+import { type GroundMigration } from "./ground-initialization.js";
+/** 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 declare function configureGroundConnection(database: Database.Database): Database.Database;
+/** 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 declare function migrateGroundDatabase(file: string): GroundMigration;
+/** 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 declare function openGroundConnection(file: string): Database.Database;
+export declare function groundDatabase(file: string): Database.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 declare function releaseGroundDatabase(file: string): Promise<void>;