@amalgm/shell 0.1.133 → 0.1.135

package/dist/user-ground-host.js

@@ -11,7 +11,8 @@ import { EntityApplyHost, } from "./entity-apply-host.js";
 import { EntityRecordSqliteStore } from "./entity-record-store.js";
 import { observeEntityRecordPorts } from "./entity-record-observability.js";
 import { indexRowsByOutermostRoot } from "./ground-root-index.js";
-import { ContentCacheDownloadSet, captureContentFile, hasSealedContent, hashContentFile, pruneSettledContentCache, sealCapturedArtifact, } from "./content-cache-host.js";
+import { ContentCacheDownloadSet, captureContentFile, contentBlockCollector, hasSealedContent, hashContentFile, pruneSettledContentCache, sealCapturedArtifact, } from "./content-cache-host.js";
+import { RegisterUploadFusion } from "./register-upload-fusion.js";
 import { StagedContentSet, addStagingEvidenceDir, clearAddStagingEvidence, } from "./workspace-add-staging.js";
 import { DirectContentPlane } from "./content-direct.js";
 import { encodeContentWireBytes } from "./content-wire-codec.js";
@@ -37,8 +38,8 @@ const CARGO_SEGMENT_LOAD_CONCURRENCY = 8;
 /** Storage-object lanes for one download set. Tiny objects use the wide
  * request window, while the separate byte budget narrows large chunks so
  * request concurrency can never silently become an unbounded memory claim. */
-/** Admission is sized to the refs batch law so one same-turn wave coalesces
- * into one refs frame and the span fetcher merges each pack's members into a
+/** Admission is sized to the refs batch law so one planned wave resolves in
+ * one refs frame and the span planner merges each pack's members into a
  * few broad ranged reads. Memory is bounded by the byte laws below, never by
  * this count. */
 const DIRECT_OBJECT_DOWNLOAD_CONCURRENCY = CONTENT_REFS_BATCH_OBJECTS;
@@ -676,20 +677,82 @@ export class UserGroundHost {
                     this.stage({
                         primitive: "register", stage: "entity-registration", status: "started", workspaceId,
                     });
-                    const scanned = await reconcileGround({
-                        identity,
-                        userRoot: this.userRoot(identity),
-                        database: this.databasePath(identity),
-                        cacheDir: this.cacheDir(identity),
-                        onScan: (evidence) => this.reportDetectScan(evidence),
-                        measuring: this.measuring(),
-                        registrationWorkspaceId: workspaceId,
-                        suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
+                    // The walk's own read is also the upload: smalls ride cargo
+                    // segments, larges stream blocks and seal last. The flush settles
+                    // every fused effect before publication plans, so the upload
+                    // stage's seal inventory — the guarantor for anything fusion
+                    // could not ship — already sees these seals.
+                    const fusionResourceId = this.cloudState.resourceId;
+                    const fusionLegs = new TransferLegs();
+                    const fusion = new RegisterUploadFusion({
+                        // Fusion ships whole small artifacts into packs; skipping one
+                        // requires it to be both sealed and packed, so sealed-but-
+                        // standalone smalls re-ship here and placement converges on
+                        // packs without a separate migration.
+                        sealedContentHashes: async (hashes) => {
+                            const inventory = await this.sealInventory(fusionResourceId, hashes);
+                            return new Set([...inventory.sealed].filter((hash) => inventory.packed.has(hash)));
+                        },
+                        sendCargo: async (artifacts, payload) => {
+                            const { sealed } = await this.putCargo(fusionResourceId, artifacts, payload, fusionLegs);
+                            return sealed;
+                        },
+                        putBlocks: async (chunks, bytes) => {
+                            await this.putContentBlocks(fusionResourceId, chunks, bytes, fusionLegs);
+                        },
+                        sealManifest: async (manifest) => {
+                            await this.putContentManifest(fusionResourceId, manifest, fusionLegs);
+                        },
                     });
+                    const scanned = await (async () => {
+                        try {
+                            return await reconcileGround({
+                                identity,
+                                userRoot: this.userRoot(identity),
+                                database: this.databasePath(identity),
+                                cacheDir: this.cacheDir(identity),
+                                onScan: (evidence) => this.reportDetectScan(evidence),
+                                measuring: this.measuring(),
+                                registrationWorkspaceId: workspaceId,
+                                suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
+                                fusion,
+                            });
+                        }
+                        finally {
+                            // Even an abandoned walk settles its in-flight cargo, and a
+                            // stale-capture re-walk then skips whatever already sealed.
+                            const fused = await fusion.flush();
+                            this.stage({
+                                primitive: "register",
+                                stage: "fused-upload",
+                                status: "completed",
+                                workspaceId,
+                                measurements: {
+                                    smallArtifacts: fused.smallArtifacts,
+                                    smallBytes: fused.smallBytes,
+                                    cargoSegments: fused.cargoSegments,
+                                    sealedSkipped: fused.sealedSkipped,
+                                    largeArtifacts: fused.largeArtifacts,
+                                    largeBytes: fused.largeBytes,
+                                    ...(fused.disabledReason !== null ? { disabled: fused.disabledReason } : {}),
+                                    ...fusionLegs.report(),
+                                },
+                            });
+                        }
+                    })();
                     const retry = scanned.detection.find((plan) => plan.kind === "retry");
                     if (retry?.kind === "retry") {
                         throw new Error(retry.reasons.join("; "));
                     }
+                    // The classic upload re-proved every source byte against its
+                    // captured hash when it read it. The fused rail already shipped
+                    // those bytes, so the equivalent proof is the fingerprint law at
+                    // stat cost: any fused source that moved after capture makes this
+                    // attempt stale, and the re-walk publishes what stands there now.
+                    const movedGround = await fusion.movedGround();
+                    if (movedGround !== null) {
+                        throw new StaleCaptureError(`${movedGround} changed after its fused upload`);
+                    }
                     const registrationDuration = performance.now() - registrationStarted;
                     const commitStarted = performance.now();
                     this.stage({
@@ -867,10 +930,11 @@ export class UserGroundHost {
             throw new Error("entity Record rail already started");
         await this.wire.open();
         // One floor, no per-feature gates: this shell and its gateway release
-        // together, and the gateway ships first. 14 = immutable content packs
-        // with a refs frame answering locations; an older gateway still speaks
-        // presign and cannot resolve a packed object at all.
-        if (this.wire.protocolVersion < 14) {
+        // together, and the gateway ships first. 16 = placement answers on the
+        // seal inventory; an older gateway cannot say which sealed artifacts are
+        // packed, and this shell plans pack-span downloads and repacks against
+        // exactly that answer.
+        if (this.wire.protocolVersion < 16) {
             throw new Error("gateway speaks an older wire protocol than this shell");
         }
         this.adoptCloudDeliveryBaseline(identity, this.cloudState.deliveryWatermark);
@@ -1413,6 +1477,40 @@ export class UserGroundHost {
             wireBytes: encoded.bytes.byteLength,
         };
     }
+    /** 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. */
+    async putContentBlocks(resourceId, blocks, payload, legs) {
+        const encoded = await legs.time("encodeMs", () => encodeContentWireBytes(payload));
+        const frame = await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
+            type: "private.entity-content.put-blocks",
+            resource_id: resourceId,
+            blocks,
+            bytes: payload.byteLength,
+            wire_bytes: encoded.bytes.byteLength,
+            ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
+        }, encoded.bytes, ["private.entity-content.stored-blocks"])));
+        legs.add("gatewayVerifyMs", Number(frame.verify_ms));
+        legs.add("gatewayStoreMs", Number(frame.store_ms));
+        return encoded.bytes.byteLength;
+    }
+    /** 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. */
+    async putContentManifest(resourceId, manifest, legs) {
+        const bytes = Buffer.from(stableJson(manifest), "utf8");
+        const frame = await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
+            type: "private.entity-content.put",
+            resource_id: resourceId,
+            content_hash: manifest.contentHash,
+            sha256: sha256Hex(bytes),
+            bytes: bytes.length,
+        }, bytes, ["private.entity-content.stored"])));
+        legs.add("gatewayVerifyMs", Number(frame.verify_ms));
+        legs.add("gatewayStoreMs", Number(frame.store_ms));
+        legs.add("gatewaySealMs", Number(frame.seal_ms));
+        return bytes.length;
+    }
     async uploadSnapshotContent(identity, resourceId, records, trace, manifestHints) {
         const cache = this.cacheDir(identity);
         const byHash = new Map();
@@ -1448,11 +1546,16 @@ export class UserGroundHost {
         // The authority's seal inventory is the only permission to skip an
         // upload — asked before any source is touched, so sealed artifacts cost
         // zero local reads and a retried publication whose upload already sealed
-        // completely never needs its captured ground to still exist.
-        const alreadySealed = await legs.time("planMs", () => this.sealedContentHashes(resourceId, [...byHash.keys()]));
+        // completely never needs its captured ground to still exist. Placement
+        // rides the same answer: a sealed-but-unpacked small artifact is
+        // correctness-complete but stored inefficiently, so this guarantor also
+        // re-ships it into a pack when its source is still at hand (axiom 44).
+        const inventory = await legs.time("planMs", () => this.sealInventory(resourceId, [...byHash.keys()]));
         const unsealed = [...byHash.values()]
-            .filter(({ artifact }) => !alreadySealed.has(artifact.contentHash));
-        const rows = legs.timeSync("planMs", () => readGroundRowsByUuid(this.databasePath(identity), unsealed.map(({ uuid }) => uuid)));
+            .filter(({ artifact }) => !inventory.sealed.has(artifact.contentHash));
+        const unpacked = [...byHash.values()].filter(({ artifact }) => inventory.sealed.has(artifact.contentHash)
+            && !inventory.packed.has(artifact.contentHash));
+        const rows = legs.timeSync("planMs", () => readGroundRowsByUuid(this.databasePath(identity), [...unsealed, ...unpacked].map(({ uuid }) => uuid)));
         // Each artifact uploads from the strongest evidence available: a cache
         // copy when another journey pinned one, otherwise the ground entity
         // itself. Register stages nothing, so the ground path is the common
@@ -1499,6 +1602,42 @@ export class UserGroundHost {
                 bytes,
             };
         }));
+        // Repack candidates are sealed already, so their sources are optional:
+        // anything missing, oversized, or unreadable skips silently — a frozen
+        // workspace simply keeps standalone placement until its next actual
+        // publication. What readers see never changes either way.
+        const repackSources = legs.timeSync("planMs", () => unpacked.flatMap(({ artifact, uuid }) => {
+            const cached = contentCacheFile(cache, artifact.contentHash);
+            const fromCache = existsSync(cached);
+            const row = rows.get(uuid);
+            if (!fromCache && (artifact.kind === "git" || !row))
+                return [];
+            const file = fromCache ? cached : row.absolutePath;
+            let linkTarget;
+            let bytes;
+            try {
+                if (!fromCache && artifact.kind === "link") {
+                    linkTarget = Buffer.from(readlinkSync(file), "utf8");
+                    bytes = linkTarget.byteLength;
+                }
+                else {
+                    bytes = statSync(file).size;
+                }
+            }
+            catch {
+                return [];
+            }
+            if (bytes > CHUNK_BYTES)
+                return [];
+            return [{
+                    artifact,
+                    file,
+                    fromCache,
+                    ...(linkTarget ? { linkTarget } : {}),
+                    bytes,
+                    repack: true,
+                }];
+        }));
         const stale = (source, error) => {
             if (source.fromCache) {
                 // A cache copy that no longer proves its hash is torn evidence:
@@ -1518,8 +1657,11 @@ export class UserGroundHost {
         const small = sources.filter((source) => source.bytes <= CHUNK_BYTES);
         const large = sources.filter((source) => source.bytes > CHUNK_BYTES);
         let cargoSegments = 0;
+        let repackedArtifacts = 0;
+        let repackedBytes = 0;
         const sendCargoSegment = async (segment) => {
-            const loaded = new Array(segment.items.length);
+            const loaded = new Array(segment.items.length).fill(null);
+            const dropped = [];
             await boundedForEach(segment.items.map((item, index) => ({ source: item.source, index })), CARGO_SEGMENT_LOAD_CONCURRENCY, async ({ source, index }) => {
                 try {
                     const bytes = source.linkTarget ?? await legs.time("loadMs", () => readFile(source.file));
@@ -1530,42 +1672,50 @@ export class UserGroundHost {
                     };
                 }
                 catch (error) {
+                    // A repack source that churned or vanished under this read is
+                    // dropped, never stale: the artifact stays sealed standalone,
+                    // and it is answered as sealed because it truthfully is.
+                    if (source.repack) {
+                        dropped.push(source.artifact.contentHash);
+                        return;
+                    }
                     if (sourceMismatch(error))
                         stale(source, error);
                     throw error;
                 }
             });
-            const { sealed, wireBytes } = await this.putCargo(resourceId, loaded.map((item, index) => ({
-                content_hash: segment.items[index].contentHash,
-                bytes: item.manifest.bytes,
-                chunks: item.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
-            })), Buffer.concat(loaded.map((item) => item.bytes)), legs);
-            for (const item of loaded)
-                uploadedChunks += item.manifest.chunks.length;
+            const shipping = segment.items.flatMap((item, index) => {
+                const load = loaded[index];
+                return load === null ? [] : [{ item, load }];
+            });
+            if (shipping.length === 0)
+                return dropped;
+            const { sealed, wireBytes } = await this.putCargo(resourceId, shipping.map(({ item, load }) => ({
+                content_hash: item.contentHash,
+                bytes: load.manifest.bytes,
+                chunks: load.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
+            })), Buffer.concat(shipping.map(({ load }) => load.bytes)), legs);
+            for (const { item, load } of shipping) {
+                uploadedChunks += load.manifest.chunks.length;
+                if (item.source.repack) {
+                    repackedArtifacts += 1;
+                    repackedBytes += load.manifest.bytes;
+                }
+            }
             uploadedBytes += wireBytes;
             cargoSegments += 1;
-            return sealed;
+            return [...sealed, ...dropped];
         };
         const transfer = async (source) => {
             const { artifact, file, manifest: knownManifest, bytes: fileBytes } = source;
             const sourceFile = { handle: null };
             let manifestPresent = false;
-            const putChunk = async (manifest, index, bytes) => {
+            const chunkBlocks = (manifest, indexes) => indexes.map((index) => {
                 const chunk = manifest.chunks[index];
                 if (!chunk)
                     throw new Error(`content manifest has no chunk ${index}`);
-                await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
-                    type: "private.entity-content.put",
-                    resource_id: resourceId,
-                    content_hash: artifact.contentHash,
-                    kind: "chunk",
-                    part_index: index,
-                    part_count: manifest.chunks.length,
-                    sha256: chunk.sha256,
-                    bytes: chunk.bytes,
-                }, bytes, ["private.entity-content.stored"])));
-                uploadedBytes += bytes.byteLength;
-            };
+                return { sha256: chunk.sha256, bytes: chunk.bytes };
+            });
             try {
                 const receipt = await uploadArtifact(artifact, {
                     bytes: fileBytes,
@@ -1595,40 +1745,16 @@ export class UserGroundHost {
                         }
                         return frame.missing;
                     },
-                    putChunk: async (_candidate, manifest, index, bytes) => putChunk(manifest, index, bytes),
+                    putChunk: async (_candidate, manifest, index, bytes) => {
+                        uploadedBytes += await this.putContentBlocks(resourceId, chunkBlocks(manifest, [index]), bytes, legs);
+                    },
                     putChunkBatch: async (_candidate, manifest, indexes, bytes) => {
-                        const encoded = await legs.time("encodeMs", () => encodeContentWireBytes(bytes));
-                        await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
-                            type: "private.entity-content.put-batch",
-                            resource_id: resourceId,
-                            content_hash: artifact.contentHash,
-                            part_count: manifest.chunks.length,
-                            chunks: indexes.map((index) => ({
-                                part_index: index,
-                                sha256: manifest.chunks[index]?.sha256,
-                                bytes: manifest.chunks[index]?.bytes,
-                            })),
-                            bytes: bytes.byteLength,
-                            wire_bytes: encoded.bytes.byteLength,
-                            ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
-                        }, encoded.bytes, ["private.entity-content.stored-batch"])));
-                        uploadedBytes += encoded.bytes.byteLength;
+                        uploadedBytes += await this.putContentBlocks(resourceId, chunkBlocks(manifest, indexes), bytes, legs);
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
                             return;
-                        const bytes = Buffer.from(stableJson(manifest), "utf8");
-                        await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
-                            type: "private.entity-content.put",
-                            resource_id: resourceId,
-                            content_hash: artifact.contentHash,
-                            kind: "manifest",
-                            part_index: manifest.chunks.length,
-                            part_count: manifest.chunks.length,
-                            sha256: sha256Hex(bytes),
-                            bytes: bytes.length,
-                        }, bytes, ["private.entity-content.stored"])));
-                        uploadedBytes += bytes.byteLength;
+                        uploadedBytes += await this.putContentManifest(resourceId, manifest, legs);
                     },
                 });
                 uploadedChunks += receipt.uploadedChunks;
@@ -1645,7 +1771,7 @@ export class UserGroundHost {
             }
         };
         try {
-            await streamCargo(small.map((source) => ({
+            await streamCargo([...small, ...repackSources].map((source) => ({
                 contentHash: source.artifact.contentHash,
                 bytes: source.bytes,
                 source,
@@ -1672,6 +1798,12 @@ export class UserGroundHost {
                     cargoBytes: small.reduce((total, source) => total + source.bytes, 0),
                     largeArtifacts: large.length,
                     largeBytes: large.reduce((total, source) => total + source.bytes, 0),
+                    // Placement work: sealed-but-standalone smalls re-shipped into
+                    // packs by this guarantor. Candidates counts what the inventory
+                    // named; repacked counts what actually shipped this pass.
+                    repackCandidates: unpacked.length,
+                    repackedArtifacts,
+                    repackedBytes,
                     uploadedBytes,
                     loadedBytes,
                     uploadedChunks,
@@ -1701,10 +1833,11 @@ export class UserGroundHost {
         }
     }
     /** 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. */
     async downloadContentSet(resourceId, cacheDir, wants, retryAttempts = 10, trace, staged) {
         const unique = new Map(wants.map((want) => [want.artifact.contentHash, want]));
         const sole = unique.size === 1 ? [...unique.values()][0]?.artifact : undefined;
@@ -1745,56 +1878,75 @@ export class UserGroundHost {
                 throw new Error("download cache has no content manifest");
             return found;
         };
-        // Every storage object — the manifest and each block — is fetched
-        // straight from content storage over a presigned URL and opened locally;
-        // packed objects arrive as merged byte ranges of their immutable pack.
-        // The wire carries only the key handoff and refs requests. A retry asks
-        // for a fresh ref every attempt.
-        const fetchObject = async (object) => {
-            requests += 1;
-            const bytes = await legs.time("fetchMs", () => retryContent(() => this.direct.fetchObject(resourceId, object), true, retryAttempts));
-            downloadedBytes += bytes.byteLength;
-            return bytes;
+        // An Add stages ordinary files directly at their hidden final
+        // destination — except content this machine already holds sealed,
+        // which stays on the cache rail so a warm re-Add remains a local
+        // clone instead of a fresh download.
+        const route = (artifact, manifest) => {
+            const stagedPaths = stagedSet && staged?.destinations.get(artifact.contentHash);
+            if (stagedPaths && !hasSealedContent(cacheDir, artifact.contentHash, manifest.bytes)) {
+                stagedArtifacts += 1;
+                targets.set(artifact.contentHash, stagedSet.target(artifact, manifest, stagedPaths));
+            }
+            else {
+                targets.set(artifact.contentHash, downloads.target(artifact, manifest));
+            }
         };
         try {
-            const receipts = await downloadAllArtifacts([...unique.values()].map((want) => want.artifact), {
+            // Every storage object — manifests and blocks alike — is fetched
+            // straight from content storage over a presigned URL and opened
+            // locally; the engine plans whole waves against these primitives, so
+            // the wire carries only the key handoff and batched refs requests. A
+            // retried read refreshes its URL but never its geometry: placement is
+            // immutable, and a moved answer fails loudly instead of retrying.
+            const { receipts, shape } = await downloadAllArtifacts([...unique.values()].map((want) => want.artifact), {
                 sha256Hex: timedSha256Hex,
-                getManifest: async (artifact) => {
+                localManifest: (artifact) => legs.timeSync("planMs", () => {
                     // The record's plan or this machine's own manifest cache already
                     // proves chunk identity; downloaded bytes are still hash-verified,
                     // so a stale local manifest can only fail loudly, never corrupt.
-                    const local = legs.timeSync("planMs", () => unique.get(artifact.contentHash)?.manifest
-                        ?? readCachedManifest(cacheDir, artifact.contentHash));
-                    const manifest = local ?? await (async () => {
-                        const bytes = await fetchObject({ kind: "manifest", sha256: artifact.contentHash });
-                        const checked = checkContentManifest(JSON.parse(bytes.toString("utf8")), artifact.contentHash);
-                        if (!checked.ok)
-                            throw new Error(checked.error);
-                        return checked.value;
-                    })();
-                    // An Add stages ordinary files directly at their hidden final
-                    // destination — except content this machine already holds sealed,
-                    // which stays on the cache rail so a warm re-Add remains a local
-                    // clone instead of a fresh download.
-                    legs.timeSync("planMs", () => {
-                        const stagedPaths = stagedSet && staged?.destinations.get(artifact.contentHash);
-                        if (stagedPaths && !hasSealedContent(cacheDir, artifact.contentHash, manifest.bytes)) {
-                            stagedArtifacts += 1;
-                            targets.set(artifact.contentHash, stagedSet.target(artifact, manifest, stagedPaths));
-                        }
-                        else {
-                            targets.set(artifact.contentHash, downloads.target(artifact, manifest));
+                    const local = unique.get(artifact.contentHash)?.manifest
+                        ?? readCachedManifest(cacheDir, artifact.contentHash);
+                    if (local)
+                        route(artifact, local);
+                    return local ?? null;
+                }),
+                requestRefs: async (objects) => legs.time("fetchMs", () => retryContent(() => this.direct.requestRefs(resourceId, objects), true, retryAttempts)),
+                fetchSpan: async (url, span, refresh) => legs.time("fetchMs", async () => {
+                    let attempt = 0;
+                    return retryContent(async () => {
+                        let signed = url;
+                        if (attempt > 0) {
+                            try {
+                                signed = await refresh();
+                            }
+                            catch (error) {
+                                // A moved placement (or a refused re-resolution) is a
+                                // planning fact, not a transient fetch fault — surface it
+                                // without burning the remaining attempts.
+                                throw new WireRequestError({
+                                    type: "shared.error",
+                                    code: "entity_content_moved",
+                                    message: error instanceof Error ? error.message : String(error),
+                                    status: 409,
+                                    retryable: false,
+                                });
+                            }
                         }
-                    });
-                    return manifest;
+                        attempt += 1;
+                        return this.direct.fetchSpan(signed, span);
+                    }, true, retryAttempts);
+                }),
+                openEnvelope: async (_object, sealed) => {
+                    requests += 1;
+                    const plain = await legs.time("fetchMs", () => this.direct.openEnvelope(resourceId, sealed));
+                    downloadedBytes += plain.byteLength;
+                    return plain;
                 },
-                hasChunk: async (artifact, _manifest, index) => legs.time("reuseMs", () => target(artifact).hasChunk(index)),
-                getChunk: async (_artifact, manifest, index) => {
-                    const chunk = manifest.chunks[index];
-                    if (!chunk)
-                        throw new Error(`content manifest has no chunk ${index}`);
-                    return fetchObject({ kind: "block", sha256: chunk.sha256 });
+                manifestProven: async (artifact, manifest) => {
+                    legs.timeSync("planMs", () => route(artifact, manifest));
                 },
+                hasChunk: async (artifact, _manifest, index) => legs.time("reuseMs", () => target(artifact).hasChunk(index)),
                 putChunk: async (artifact, _manifest, index, bytes) => legs.time("writeMs", () => target(artifact).putChunk(index, bytes)),
                 sealArtifact: async (artifact) => {
                     const sealed = await legs.time("sealMs", () => target(artifact).seal());
@@ -1835,6 +1987,10 @@ export class UserGroundHost {
                     // nothing in flight. The staged rail decomposes its own write and
                     // seal internals below; `stagedArtifacts` counts its placements.
                     requests,
+                    // The engine's own geometry: how manifests were known (local vs
+                    // fetched, packed vs standalone) and how many planned pack spans
+                    // carried the packed objects.
+                    ...shape,
                     ...physicalPlaneDelta(planeBefore, this.direct.metrics()),
                     ...legs.report(),
                     ...(stagedSet ? stagedSet.report() : {}),
@@ -2415,27 +2571,35 @@ export class UserGroundHost {
         });
     }
     /** 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. */
-    async sealedContentHashes(resourceId, hashes) {
+     * 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. */
+    async sealInventory(resourceId, hashes) {
         const batches = [];
         for (let start = 0; start < hashes.length; start += CONTENT_REFS_BATCH_OBJECTS) {
             batches.push(hashes.slice(start, start + CONTENT_REFS_BATCH_OBJECTS));
         }
         const sealed = new Set();
+        const packed = new Set();
         const answers = await Promise.all(batches.map((batch) => retryContent(() => this.wire.request({
             type: "private.entity-content.sealed",
             resource_id: resourceId,
             content_hashes: batch,
         }, ["private.entity-content.sealed-result"]))));
         for (const frame of answers) {
-            if (!Array.isArray(frame.sealed)) {
-                throw new Error("content authority answered an invalid seal inventory");
+            if (!Array.isArray(frame.sealed) || !Array.isArray(frame.packed)) {
+                throw new Error("content authority answered a seal inventory without "
+                    + "placement; protocol 16 requires the gateway to deploy before this machine");
             }
             for (const hash of frame.sealed)
                 sealed.add(String(hash));
+            for (const hash of frame.packed)
+                packed.add(String(hash));
         }
-        return sealed;
+        return { sealed, packed };
     }
     async publishPendingSnapshots(identity, trace, manifestHints) {
         for (const pending of readSnapshotPublications(this.databasePath(identity))) {
@@ -2456,7 +2620,7 @@ export class UserGroundHost {
             return;
         const started = performance.now();
         const legs = new TransferLegs();
-        const sealed = await legs.time("planMs", () => this.sealedContentHashes(resourceId, pages.map((page) => page.sha256)));
+        const { sealed } = await legs.time("planMs", () => this.sealInventory(resourceId, pages.map((page) => page.sha256)));
         const unsealed = pages
             .filter((page) => !sealed.has(page.sha256))
             .map((page) => ({ contentHash: page.sha256, bytes: page.bytes.byteLength, page }));
@@ -4102,7 +4266,7 @@ function materializedWorkspaceBindings(bindingDir) {
     return bindings.sort((left, right) => left.workspaceId.localeCompare(right.workspaceId));
 }
 async function reconcileGround(input) {
-    const { identity, userRoot, database, cacheDir, suspicions, coreScan, registrationWorkspaceId, onScan, measuring = false, } = input;
+    const { identity, userRoot, database, cacheDir, suspicions, coreScan, registrationWorkspaceId, fusion, onScan, measuring = false, } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
     const boundRootEntries = materializedWorkspaceBindings(bindingDir);
@@ -4328,9 +4492,11 @@ async function reconcileGround(input) {
             suspicion: observationFor(rootPath),
             // A register scan publishes one complete snapshot; it never mints Send
             // records for the same initial contents, so it plans no detection and
-            // stages no cache bytes — upload reads the ground itself.
+            // stages no cache bytes — the fused rail ships content from the walk's
+            // own read, and upload re-reads only what fusion could not seal.
             plansSendRecords: suspicions !== undefined && registrationWorkspaceId === undefined,
             largeManifests,
+            fusion,
         });
     }
     const changedUUIDs = new Set([
@@ -4358,7 +4524,7 @@ async function reconcileGround(input) {
     };
 }
 async function reconcileRoot(input) {
-    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, measureEvidence = false, plansSendRecords, largeManifests, } = input;
+    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, measureEvidence = false, plansSendRecords, largeManifests, fusion, } = input;
     // Prior rows reach this scan from every binding this root encloses. A row's
     // stored relativePath is relative to the root that last committed it, which
     // is a different frame when an enclosing boundary was just registered
@@ -4711,9 +4877,20 @@ async function reconcileRoot(input) {
                 captureTasks.push(captureGate(async () => {
                     const taskStarted = measureEvidence ? performance.now() : 0;
                     let current = stats;
+                    // Repository leaves ship on the Git-native rail; everything else
+                    // may fuse its capture read with upload. Fusion is opportunistic:
+                    // once disabled, captures continue exactly as the classic path
+                    // and the upload stage ships what the walk could not.
+                    const fused = activeRepository ? undefined : fusion;
                     for (let attempt = 1;; attempt++) {
                         try {
-                            const captured = await captureContentFile(absolutePath, current, activeRepository || !plansSendRecords ? null : cacheDir);
+                            const collect = fused?.enabled && current.size <= CHUNK_BYTES
+                                ? contentBlockCollector(current.size)
+                                : null;
+                            const captured = fused && current.size > CHUNK_BYTES
+                                ? (await fused.captureLarge(absolutePath, current))
+                                    ?? await captureContentFile(absolutePath, current, activeRepository || !plansSendRecords ? null : cacheDir)
+                                : await captureContentFile(absolutePath, current, activeRepository || !plansSendRecords ? null : cacheDir, collect);
                             if (measureEvidence && evidence) {
                                 evidence.captureBusyMs += performance.now() - taskStarted;
                                 evidence.captureBytes += captured.bytes;
@@ -4726,6 +4903,12 @@ async function reconcileRoot(input) {
                             if (captured.bytes > CHUNK_BYTES) {
                                 largeManifests?.set(captured.contentHash, captured.manifest);
                             }
+                            // The capture proved these exact bytes against the fingerprint
+                            // law; hand them to the cargo rail. Waiting here is window
+                            // backpressure, bounding memory by the capture pool's width.
+                            if (collect && fused) {
+                                await fused.addSmall(absolutePath, current, captured, collect.collected);
+                            }
                             return;
                         }
                         catch (error) {