@amalgm/shell 0.1.133 → 0.1.135

package/dist/register-upload-fusion.js

@@ -0,0 +1,169 @@
+/**
+ * Register's fused upload — the walk's one read is also the upload.
+ *
+ * A cold Register used to read every source byte twice: once for identity,
+ * once for transport. This rail rides the capture instead. Small files hand
+ * their already-read bytes to a bounded cargo stream; each segment asks the
+ * authority's seal inventory first, so a retried or crashed register ships
+ * only what is not yet sealed. Large files stream verified blocks during
+ * the single capture read and seal their manifest last, behind the same
+ * fingerprint law as the classic capture.
+ *
+ * Fusion is an opportunity, never a dependency. The upload stage still
+ * plans afterwards from the authority's seal inventory and remains the
+ * guarantor: anything this rail could not fuse — a churned file, a refused
+ * wave, a dead wire — uploads there exactly as before. Any transport
+ * failure disables fusion for the rest of the walk and is never a walk
+ * failure; ground failures keep the walk's own churn law. Git repositories
+ * stay on their Git-native rail and never enter this module.
+ */
+import { lstat } from "node:fs/promises";
+import { openCargoStream, } from "@amalgm/live";
+import { captureContentFileStream, sameCaptureFingerprint, } from "./content-cache-host.js";
+/** A wire refusal inside a fused capture. Distinguished from ground errors
+ * so the caller can disable fusion without disturbing the walk's churn law. */
+class FusionTransportError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+    }
+}
+export class RegisterUploadFusion {
+    ports;
+    stream;
+    admitted = new Set();
+    shipped = [];
+    disabledBy = null;
+    smallArtifacts = 0;
+    smallBytes = 0;
+    cargoSegments = 0;
+    sealedSkipped = 0;
+    largeArtifacts = 0;
+    largeBytes = 0;
+    constructor(ports) {
+        this.ports = ports;
+        this.stream = openCargoStream({
+            send: async (segment) => {
+                // Ask before shipping: a re-walked or previously crashed register
+                // recaptures files whose artifacts may already be sealed whole.
+                const sealed = await ports.sealedContentHashes(segment.items.map((item) => item.contentHash));
+                const fresh = segment.items.filter((item) => !sealed.has(item.contentHash));
+                this.sealedSkipped += segment.items.length - fresh.length;
+                if (fresh.length === 0)
+                    return [...sealed];
+                const answered = await ports.sendCargo(fresh.map((item) => ({
+                    content_hash: item.contentHash,
+                    bytes: item.bytes,
+                    chunks: item.manifest.chunks,
+                })), Buffer.concat(fresh.map((item) => item.payload)));
+                this.cargoSegments += 1;
+                this.smallArtifacts += fresh.length;
+                for (const item of fresh)
+                    this.smallBytes += item.bytes;
+                return [...answered, ...sealed];
+            },
+        });
+    }
+    get enabled() {
+        return this.disabledBy === null;
+    }
+    /** Hand one already-captured small artifact's bytes to the cargo rail.
+     * Waits only for window room — backpressure, never durability — and a
+     * failed stream disables fusion instead of failing the capture. */
+    async addSmall(absolutePath, fingerprint, captured, payload) {
+        if (this.disabledBy !== null)
+            return;
+        if (this.admitted.has(captured.contentHash)) {
+            // Equal bytes share one upload identity, but every physical path still
+            // owns its own capture fingerprint. A duplicate path moving after the
+            // read must invalidate the attempt just like the path that supplied the
+            // shared cargo.
+            this.shipped.push({ absolutePath, fingerprint });
+            return;
+        }
+        this.admitted.add(captured.contentHash);
+        try {
+            await this.stream.add({
+                contentHash: captured.contentHash,
+                bytes: captured.bytes,
+                manifest: captured.manifest,
+                payload,
+            });
+            this.shipped.push({ absolutePath, fingerprint });
+        }
+        catch (error) {
+            this.disable(error);
+        }
+    }
+    /** Capture one large file by streaming its single read to the authority.
+     * Ground churn propagates unchanged into the walk's retry law; a wire
+     * failure disables fusion and answers null so the caller captures the
+     * classic way and the upload stage ships it. */
+    async captureLarge(sourceFile, expected) {
+        if (this.disabledBy !== null)
+            return null;
+        const guard = (work) => work.catch((error) => {
+            throw new FusionTransportError(error);
+        });
+        try {
+            const captured = await captureContentFileStream(sourceFile, expected, {
+                putBlocks: (chunks, bytes) => guard(this.ports.putBlocks(chunks, bytes)),
+                sealManifest: (manifest) => guard(this.ports.sealManifest(manifest)),
+            });
+            this.largeArtifacts += 1;
+            this.largeBytes += captured.bytes;
+            this.shipped.push({ absolutePath: sourceFile, fingerprint: expected });
+            return captured;
+        }
+        catch (error) {
+            if (!(error instanceof FusionTransportError))
+                throw error;
+            this.disable(error.cause);
+            return null;
+        }
+    }
+    /** Prove every fused source still stands exactly as it was captured — the
+     * proof the classic upload's re-read gave for free, at stat cost only.
+     * Answers the first moved path, or null while the fused ground stands.
+     * The caller turns a moved path into its ordinary stale-capture re-walk;
+     * sealed content stays harmlessly unreferenced until the re-walk names
+     * what stands there now. */
+    async movedGround() {
+        for (const { absolutePath, fingerprint } of this.shipped) {
+            let current;
+            try {
+                current = await lstat(absolutePath);
+            }
+            catch {
+                return absolutePath;
+            }
+            if (!sameCaptureFingerprint(fingerprint, current))
+                return absolutePath;
+        }
+        return null;
+    }
+    /** Settle the fused rail: every admitted segment ships or the failure is
+     * recorded as this fusion's disabling reason. Never throws — the upload
+     * stage re-plans from the seal inventory, so an incomplete fusion only
+     * means it uploads more. */
+    async flush() {
+        try {
+            await this.stream.flush();
+        }
+        catch (error) {
+            this.disable(error);
+        }
+        return {
+            smallArtifacts: this.smallArtifacts,
+            smallBytes: this.smallBytes,
+            cargoSegments: this.cargoSegments,
+            sealedSkipped: this.sealedSkipped,
+            largeArtifacts: this.largeArtifacts,
+            largeBytes: this.largeBytes,
+            disabledReason: this.disabledBy,
+        };
+    }
+    disable(error) {
+        this.disabledBy ??= error instanceof Error ? error.message : String(error);
+    }
+}
+//# sourceMappingURL=register-upload-fusion.js.map

package/dist/register-upload-fusion.js.map

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

package/dist/user-ground-host.d.ts

@@ -225,12 +225,21 @@ export declare class UserGroundHost {
      * timings — verification, storage, sealing — which fold into the ledger
      * as a decomposition of this round trip's `wireMs`. */
     private putCargo;
+    /** Store one wave of provisional content blocks, addressed by their own
+     * digests and bound to no artifact. Resolving means every block is
+     * durable at the authority. Answers the wire bytes actually sent. */
+    private putContentBlocks;
+    /** Seal one artifact's manifest. The authority re-proves every named
+     * block durable before anything becomes visible, so this frame is only
+     * lawful after the complete file went over the wire. */
+    private putContentManifest;
     private uploadSnapshotContent;
     /** Download a set of immutable artifacts straight from content storage.
-     * The set is the primitive: every storage object the set still needs —
-     * manifests and blocks alike — shares one wide lane bound, so no artifact
-     * serializes behind another's plan or seal. Each object is still its own
-     * storage request. A lone artifact is a set of one. */
+     * The set is the primitive and the plan is physical: the engine resolves
+     * the whole want-list in two planned waves — manifests grouped by the
+     * pack that holds them, then blocks the same way — so all members of one
+     * pack collapse into a few broad ranged reads while standalone objects
+     * stay one read each. A lone artifact is a set of one. */
     private downloadContentSet;
     private downloadContent;
     private ensureWatchers;
@@ -251,9 +260,13 @@ export declare class UserGroundHost {
      * preparation names the slow part instead of one opaque number. */
     private finishPreparation;
     /** Which of these heads does the authority hold sealed under the current
-     * content contract? Batched so a whole workspace costs a handful of
-     * frames; the answer is the only permission to skip an upload. */
-    private sealedContentHashes;
+     * content contract — and which of the sealed ones are packed, their whole
+     * closure inside immutable packs? Batched so a whole workspace costs a
+     * handful of frames. `sealed` is the only permission to skip an upload
+     * for correctness; `packed` is placement knowledge only. The packed
+     * answer is a protocol 16 capability and is required: a missing field
+     * means an older gateway, and this machine refuses to guess placement. */
+    private sealInventory;
     private publishPendingSnapshots;
     /** Seal this publication's graph pages. Pages are immutable, content
      * addressed, and already in memory, so the authority's seal inventory alone