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

package/dist/construct-ledger.js

@@ -10,6 +10,8 @@
  * The product owns what it runs; this ledger owns what the rails said. They
  * are different questions, and Apply asks the product, never this table.
  */
+import { save } from "./ground-saver.js";
+import { cachedStatement } from "./sqlite.js";
 const record = (row) => Object.freeze({
     uuid: row.uuid,
     type: row.type,
@@ -23,37 +25,31 @@ const record = (row) => Object.freeze({
     fileMode: null,
     transportVersion: null,
 });
+/** The ledger's one write, run only by the ground file's saver thread. */
+export function rememberConstruct(database, input) {
+    const { entity } = input;
+    cachedStatement(database, `
+    INSERT INTO constructs(uuid, type, name, status, version, payload_version, updated_at_ms)
+    VALUES(?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(uuid) DO UPDATE SET
+      type = excluded.type,
+      name = excluded.name,
+      status = excluded.status,
+      version = excluded.version,
+      payload_version = excluded.payload_version,
+      updated_at_ms = excluded.updated_at_ms
+  `).run(entity.uuid, entity.type, entity.name, entity.status, entity.version, entity.payloadVersion, input.updatedAtMs);
+}
 export class ConstructLedger {
+    #file;
     #read;
-    #write;
     #now;
     constructor(database, now = Date.now) {
-        database.exec(`
-      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
-      )
-    `);
+        this.#file = database.name;
         this.#read = database.prepare(`
       SELECT uuid, type, name, status, version, payload_version
         FROM constructs
        WHERE uuid = ?
-    `);
-        this.#write = database.prepare(`
-      INSERT INTO constructs(uuid, type, name, status, version, payload_version, updated_at_ms)
-      VALUES(@uuid, @type, @name, @status, @version, @payloadVersion, @updatedAtMs)
-      ON CONFLICT(uuid) DO UPDATE SET
-        type = excluded.type,
-        name = excluded.name,
-        status = excluded.status,
-        version = excluded.version,
-        payload_version = excluded.payload_version,
-        updated_at_ms = excluded.updated_at_ms
     `);
         this.#now = now;
     }
@@ -71,16 +67,8 @@ export class ConstructLedger {
         return this.record(uuid)?.status === "active";
     }
     /** Remember one record, whether this computer recorded it or received it. */
-    remember(entity) {
-        this.#write.run({
-            uuid: entity.uuid,
-            type: entity.type,
-            name: entity.name,
-            status: entity.status,
-            version: entity.version,
-            payloadVersion: entity.payloadVersion,
-            updatedAtMs: this.#now(),
-        });
+    async remember(entity) {
+        await save(this.#file, "constructs.remember", { entity, updatedAtMs: this.#now() });
     }
 }
 //# sourceMappingURL=construct-ledger.js.map

package/dist/construct-ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"construct-ledger.js","sourceRoot":"","sources":["../src/construct-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,MAAM,GAAG,CAAC,GAAiB,EAAqB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,IAAI,EAAE,GAAG,CAAC,IAAiC;IAC3C,0EAA0E;IAC1E,+CAA+C;IAC/C,UAAU,EAAE,IAAI;IAChB,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,MAAM,EAAE,GAAG,CAAC,MAAqC;IACjD,OAAO,EAAE,GAAG,CAAC,OAAO;IACpB,cAAc,EAAE,GAAG,CAAC,eAAe;IACnC,QAAQ,EAAE,IAAI;IACd,gBAAgB,EAAE,IAAI;CACvB,CAAC,CAAC;AAEH,MAAM,OAAO,eAAe;IACjB,KAAK,CAAqB;IAC1B,MAAM,CAAqB;IAC3B,IAAI,CAAe;IAE5B,YAAY,QAA2B,EAAE,MAAoB,IAAI,CAAC,GAAG;QACnE,QAAQ,CAAC,IAAI,CAAC;;;;;;;;;;KAUb,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;KAI7B,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;;;;;;;KAU9B,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,MAAM,CAAC,IAAY;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAA6B,CAAC;QAC7D,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,IAAY;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC;IAChD,CAAC;IAED,6EAA6E;IAC7E,QAAQ,CAAC,MAAyB;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;YACd,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE;SACzB,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"construct-ledger.js","sourceRoot":"","sources":["../src/construct-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAW9C,MAAM,MAAM,GAAG,CAAC,GAAiB,EAAqB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,IAAI,EAAE,GAAG,CAAC,IAAiC;IAC3C,0EAA0E;IAC1E,+CAA+C;IAC/C,UAAU,EAAE,IAAI;IAChB,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,MAAM,EAAE,GAAG,CAAC,MAAqC;IACjD,OAAO,EAAE,GAAG,CAAC,OAAO;IACpB,cAAc,EAAE,GAAG,CAAC,eAAe;IACnC,QAAQ,EAAE,IAAI;IACd,gBAAgB,EAAE,IAAI;CACvB,CAAC,CAAC;AAEH,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,QAA2B,EAAE,KAG9D;IACC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,eAAe,CAAC,QAAQ,EAAE;;;;;;;;;;GAUzB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AACzH,CAAC;AAED,MAAM,OAAO,eAAe;IACjB,KAAK,CAAS;IACd,KAAK,CAAqB;IAC1B,IAAI,CAAe;IAE5B,YAAY,QAA2B,EAAE,MAAoB,IAAI,CAAC,GAAG;QACnE,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;KAI7B,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,MAAM,CAAC,IAAY;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAA6B,CAAC;QAC7D,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,IAAY;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC;IAChD,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,QAAQ,CAAC,MAAyB;QACtC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,qBAAqB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtF,CAAC;CACF"}

package/dist/content-cache-collection.d.ts

@@ -0,0 +1,18 @@
+export interface CollectionReport {
+    readonly outcome: "committed" | "deferred" | "invalidated" | "failed";
+    readonly examined: number;
+    readonly deleted: number;
+    readonly ms: number;
+    readonly error?: string;
+}
+export interface CollectionOptions {
+    readonly cacheDir: string;
+    /** Which cached objects no durable owner retains; null defers. */
+    readonly unowned: (current: () => boolean) => Promise<{
+        readonly examined: number;
+        readonly unowned: readonly string[];
+    } | null>;
+    readonly report: (report: CollectionReport) => void;
+}
+/** Start collecting one cache; the returned stop waits out a running attempt. */
+export declare function collectContentCache({ cacheDir, unowned, report }: CollectionOptions): () => Promise<void>;

package/dist/content-cache-collection.js

@@ -0,0 +1,99 @@
+/**
+ * When the content cache collects what no durable owner retains.
+ *
+ * Prior art is `git gc --auto`: collection is due once enough new objects
+ * have arrived, or once a period has passed; nothing collects per commit, so
+ * an acknowledgment never starts one. A cache whose objects are all retained
+ * stays quiet until more arrive, however large it is. A proof that a recovery
+ * owner defers, or that a new cache user invalidates, retries after a
+ * doubling delay, never on every idle edge. Collection waits for a quiet
+ * cache and yields between its bounded chunks and deletion steps.
+ */
+import { performance } from "node:perf_hooks";
+import { pruneUnownedContentCache } from "./content-cache-host.js";
+import { cacheNamespace } from "./content-cache-namespace.js";
+import { contentCacheOwnership } from "./content-cache-ownership.js";
+/** Names created since the last attempt that make collection due. */
+const PRESSURE = 1024;
+const PERIOD_MS = 60 * 60 * 1000;
+/** Cache uses arrive in bursts; a quiet quarter second lets one finish. */
+const QUIET_MS = 250;
+const FIRST_RETRY_MS = 1000;
+/** Hashes whose evidence one synchronous deletion step removes. */
+const STEP = 64;
+/** Start collecting one cache; the returned stop waits out a running attempt. */
+export function collectContentCache({ cacheDir, unowned, report }) {
+    const owner = contentCacheOwnership(cacheDir);
+    const namespace = cacheNamespace(cacheDir);
+    let due = true;
+    let createdAtAttempt = namespace.created;
+    let retryMs = FIRST_RETRY_MS;
+    let retryAt = 0;
+    let timer = null;
+    let running = null;
+    let stopped = false;
+    const consider = () => {
+        if (stopped || timer || running)
+            return;
+        if (!due && namespace.created - createdAtAttempt >= PRESSURE)
+            due = true;
+        if (!due || !owner.unused)
+            return;
+        timer = setTimeout(attempt, Math.max(QUIET_MS, retryAt - performance.now()));
+        timer.unref();
+    };
+    const attempt = () => {
+        timer = null;
+        if (stopped || !owner.unused)
+            return; // the next idle edge reconsiders
+        createdAtAttempt = namespace.created;
+        const started = performance.now();
+        let examined = 0;
+        let deleted = 0;
+        running = owner.maintain(async (current) => {
+            const proof = await unowned(current);
+            if (proof === null)
+                return null;
+            examined = proof.examined;
+            const steps = [];
+            for (let start = 0; start === 0 || start < proof.unowned.length; start += STEP) {
+                const batch = proof.unowned.slice(start, start + STEP);
+                steps.push(() => { pruneUnownedContentCache(cacheDir, batch); deleted += batch.length; });
+            }
+            return steps;
+        }).then(outcome => {
+            if (outcome === "committed") {
+                due = false;
+                retryMs = FIRST_RETRY_MS;
+                retryAt = 0;
+            }
+            else {
+                retryAt = performance.now() + retryMs;
+                retryMs = Math.min(retryMs * 2, PERIOD_MS);
+            }
+            if (outcome !== "busy")
+                report({ outcome, examined, deleted, ms: performance.now() - started });
+        }, error => {
+            due = false;
+            report({ outcome: "failed", examined, deleted, ms: performance.now() - started,
+                error: error instanceof Error ? error.message : String(error) });
+        }).finally(() => { running = null; consider(); });
+    };
+    const period = setInterval(() => { due = true; consider(); }, PERIOD_MS);
+    period.unref();
+    owner.onIdle(consider);
+    consider();
+    return async () => {
+        stopped = true;
+        owner.onIdle(null);
+        clearInterval(period);
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        // A new use invalidates any proof or deletion step still to run.
+        const release = owner.use();
+        release();
+        await running;
+    };
+}
+//# sourceMappingURL=content-cache-collection.js.map

package/dist/content-cache-collection.js.map

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

package/dist/content-cache-host.d.ts

@@ -7,9 +7,9 @@
  * files. The portable transfer law remains in @amalgm/live; this module owns
  * only Node filesystem effects.
  */
-import { type Stats } from "node:fs";
 import { type ContentChunk, type ContentManifest, type TransferArtifact } from "@amalgm/live";
 import { ContentCacheIndex } from "./content-cache-index.js";
+import { type SourceStat } from "./source-signature.js";
 export interface SealedContentFile {
     readonly file: string;
     readonly bytes: number;
@@ -21,6 +21,20 @@ export interface CapturedFileContent {
     readonly manifest: ContentManifest;
     readonly binary: boolean;
 }
+/** What a content-thread cargo writer leaves the main thread to publish: a
+ * qualified name it found standing, or bytes it staged written through,
+ * which receive their name only after a barrier makes them durable. */
+export type CacheStage = {
+    readonly kind: "reused";
+} | {
+    readonly kind: "staged";
+    readonly temporary: string;
+};
+/** A content-thread capture also says what it left for the cache name, so
+ * the main thread publishes it and accounts for its directory durability. */
+export interface CacheCapture extends CapturedFileContent {
+    readonly cache: CacheStage | null;
+}
 export interface ContentBlockSource {
     readonly bytes: number;
     read(offset: number, bytes: number): Promise<Uint8Array>;
@@ -34,38 +48,90 @@ export interface ContentBlockSink {
 export declare class CaptureSourceChangedError extends Error {
     readonly code = "CAPTURE_SOURCE_CHANGED";
 }
+/** Where the cache keeps one artifact's sealed bytes. */
+export declare const contentFile: (cacheDir: string, contentHash: string) => string;
+/** Every content hash the cache holds any sealed evidence for. */
+export declare function listCachedContent(cacheDir: string): Promise<ReadonlySet<string>>;
 /**
- * Remove sealed cache evidence that no durable retry or current replay base
- * retains. The caller owns that reference set; this filesystem effect owns
- * only the disposable bytes. Downloads and captures currently in progress live
- * in their dedicated partial/capture directories and are never inspected here.
+ * Remove the sealed cache evidence of exactly these hashes, which the caller
+ * proved no durable owner retains. A name the proof never examined is never
+ * removed. Callers must hold the cache's final maintenance fence: a capture can
+ * already occupy its final filename before Record owns it. Every staging
+ * temporary goes too: each writer holds a cache use until its attempt settles,
+ * so under the fence none belongs to a live attempt. Resumable download
+ * partials remain outside this deletion surface.
  */
-export declare function pruneSettledContentCache(cacheDir: string, retainedContentHashes: ReadonlySet<string>): void;
+export declare function pruneUnownedContentCache(cacheDir: string, unowned: readonly string[]): void;
+/** Remove a cached artifact whose bytes no longer prove its hash, with its
+ * hint. The name is forgotten, so if it reappears it is a new publication. */
+export declare function discardCachedArtifact(cacheDir: string, contentHash: string): void;
 /** True when the machine cache already holds this artifact sealed whole.
  * Cold Add routes such artifacts through the cache rail so a warm re-Add
  * stays a local clone instead of a fresh download. */
 export declare function hasSealedContent(cacheDir: string, contentHash: string, bytes: number): boolean;
-/** Seal bytes once in the machine content cache. Capture paths share this
- * effect so file and repository Detect cannot invent different cache laws. */
-export declare function sealCapturedArtifact(cacheDir: string, artifact: TransferArtifact, bytes: Uint8Array): void;
+/**
+ * Publish what a content thread left for one cargo name, on the main thread:
+ * a staged file receives its name once content-cache-namespace's group
+ * barrier made it durable; a reused name is adopted. Either way the namespace
+ * learns the name, so a Record requiring it knows whether its directory entry
+ * still needs a flush. A staged file that cannot be named is removed.
+ */
+export declare function publishCargo(cacheDir: string, contentHash: string, stage: CacheStage): Promise<void>;
+/**
+ * A hint is reconstructible evidence, not cargo: no record commits to it, and
+ * its exact bytes follow from retained immutable content. So a hint is written
+ * without any flush and may be lost or torn by a crash; every reader validates
+ * it and otherwise derives it again. A failure to write one loses only the
+ * hint. Manifests and repository identity frontiers are hints.
+ */
+export declare function writeCacheHint(cacheDir: string, file: string, text: Uint8Array): Promise<void>;
+/** A cached manifest hint, or null unless it is exactly the manifest this
+ * artifact's current contract and layout commit to. The read never runs on
+ * the main thread: a slow page-in stalls only this reader. */
+export declare function readManifestHint(cacheDir: string, artifact: TransferArtifact): Promise<ContentManifest | null>;
+/** Every valid hint this cache holds for one set, keyed by content hash. A
+ * missing or invalid hint is simply absent; its reader re-derives or fetches
+ * the manifest exactly as before. */
+export declare function readManifestHints(cacheDir: string, artifacts: readonly TransferArtifact[]): Promise<ReadonlyMap<string, ContentManifest>>;
+/** Derive a manifest again from the retained immutable bytes, never from the
+ * user's filesystem, in the layout the artifact commits to, and restore the
+ * hint. Only a content thread runs this; callers reach it through
+ * content-capture-pool's `contentManifest`. */
+export declare function deriveCachedManifest(cacheDir: string, artifact: TransferArtifact): Promise<ContentManifest>;
+/** Seal bytes once in the machine content cache: verify them against the
+ * artifact, derive the manifest, stage the bytes for publication under the
+ * one law and leave the manifest as a hint. Only a content thread runs this;
+ * the main thread reaches it through content-capture-pool's `sealContent`,
+ * which publishes what it staged. */
+export declare function sealCapturedArtifact(cacheDir: string, artifact: TransferArtifact, bytes: Uint8Array): Promise<CacheStage>;
+/** Every cargo name appears only over durable bytes. Before Record promises
+ * cached content, its names' directory entries must be durable too; the
+ * namespace flushes the cache directory only when some required name is not
+ * yet known durable. The flush runs off the event loop, before admission. */
+export declare function makeRecordContentDurable(cacheDir: string, artifacts: readonly TransferArtifact[]): Promise<void>;
 /**
  * Capture an ordinary file in bounded blocks. The same bytes feed whole-file
  * identity, block identity, text/binary evidence, and the optional immutable
  * cache sink. No caller may need a complete-file Buffer.
  */
 export declare function captureContentBlocks(source: ContentBlockSource, sink: ContentBlockSink | null): Promise<CapturedFileContent>;
-export declare const sameCaptureFingerprint: (left: Stats, right: Stats) => boolean;
+/** One capture is pinned to one unchanged regular file. The expected stat is
+ * plain data, so a capture thread receives exactly what its caller observed. */
+export declare const sameCaptureSource: (left: SourceStat, right: SourceStat) => boolean;
 /**
- * Stream one stable filesystem file. Non-repository files are sealed directly
- * into the immutable cache during that read; repository-owned leaves use the
- * same capture primitive without a redundant second cache artifact. An
+ * Stream one stable filesystem file, optionally staging it for the immutable
+ * cache during that read; the main thread publishes what it staged. Only a
+ * capture thread runs this; every caller goes through content-capture-pool
+ * so no read or hash occupies the main thread. An
  * optional collect sink receives the same blocks during the one read, valid
  * only when capture succeeds — a churned capture throws and its blocks are
- * discarded with it.
+ * discarded with it. Observation can omit the sink; a later selected content
+ * promise must seal and prove its bytes before Record.
  */
-export declare function captureContentFile(sourceFile: string, expected: Stats, cacheDir: string | null, collect?: ContentBlockSink | null): Promise<CapturedFileContent>;
+export declare function captureContentFile(sourceFile: string, expected: SourceStat, cacheDir: string | null, collect?: ContentBlockSink | null): Promise<CacheCapture>;
 /** Collect a capture's blocks into one contiguous Buffer, so a fused caller
- * owns the exact bytes the capture read without reading the file again. */
+ * owns the exact bytes the capture read without reading the file again. The
+ * Buffer owns its whole ArrayBuffer, so a capture thread can transfer it. */
 export declare function contentBlockCollector(bytes: number): ContentBlockSink & {
     readonly collected: Buffer;
 };
@@ -83,7 +149,7 @@ export interface CaptureStreamTransport {
  * the authority, never a sealed identity, and surfaces as the walk's
  * ordinary CaptureSourceChangedError.
  */
-export declare function captureContentFileStream(sourceFile: string, expected: Stats, transport: CaptureStreamTransport): Promise<CapturedFileContent>;
+export declare function captureContentFileStream(sourceFile: string, expected: SourceStat, transport: CaptureStreamTransport): Promise<CapturedFileContent>;
 /** One artifact download. Calls may write different block indexes in
  * parallel; sealing is legal only after the portable download operation has
  * awaited them all. Targets retain metadata, never OS handles or chunk bytes. */