@amalgm/shell 0.1.135 → 0.1.136

package/dist/workspace-add-staging.d.ts

@@ -2,18 +2,28 @@
  * Direct-to-staging content placement for Cold Add.
  *
  * During Cold Add each ordinary file's bytes are written once, directly into
- * their hidden staged destination: every chunk is verified before its
- * positioned write, the whole-file hash is proven from that same stream, the
- * complete file is fsynced, and the workspace is revealed later by one atomic
- * rename. A second cache copy is not part of the critical path.
+ * their hidden staged destination. The cold Add's mass — single-chunk files —
+ * pays one handle lifecycle per file; a multi-chunk file pays one bounded
+ * lifecycle per chunk rather than retaining descriptors across a whole wave.
+ * The directory skeleton exists before the first byte lands, the open that
+ * writes a cold file is the open that creates it, every chunk is verified
+ * before its positioned write, the whole-file hash is proven from that same
+ * stream, and the chunk that completes the stream makes the proven bytes
+ * durable and user-visible through the handle that wrote them before it
+ * closes. Nothing waits for a seal pass: seal asserts the proof the stream
+ * already produced and places duplicates. A second cache copy is not part of
+ * the critical path, and the workspace is revealed later by one atomic rename.
  *
  * SQLite chunk evidence makes an interrupted staging resumable. Retained
  * staged bytes are never trusted: every retained chunk is re-read and
- * re-hashed against its manifest before it may satisfy the download, and the
- * whole-file digest is proven again from that same stream.
+ * re-hashed against its manifest before it may satisfy the download, a
+ * retained file is cut to its manifest length so no stale tail survives under
+ * a proven prefix, and the whole-file digest is proven again from that same
+ * stream.
  */
 import type { ContentManifest, TransferArtifact } from "@amalgm/live";
 import type { SealedContentFile } from "./content-cache-host.js";
+import { ConcurrentActivityClock } from "./transfer-instrumentation.js";
 /** The shape every download-set target satisfies, whether it stages bytes in
  * the machine cache or directly inside a hidden Add staging root. */
 export interface ContentDownloadTarget {
@@ -29,15 +39,32 @@ export interface AddStagingRouting {
     readonly evidenceDir: string;
     readonly destinations: ReadonlyMap<string, readonly string[]>;
 }
+type StoreActivity = "file" | "evidence" | "hash";
 /** Where one download set's staged placement time went, accumulated across
- * every staged file: positioned chunk writes, whole-file hash drain work
- * (including the bytes an out-of-order arrival forces back off the disk),
- * durability fsyncs, and duplicate-destination copies. */
+ * every staged file. Legs are the wall time of the named work; the activity
+ * clock beside them partitions the same wall time by what was physically in
+ * flight. */
 interface StagedPlacementMetrics {
+    /** Creating the directory skeleton, once per set. */
+    skeletonMs: number;
+    directories: number;
+    /** Creating or reclaiming a file. */
+    openMs: number;
+    /** Positioned chunk writes. */
     writeMs: number;
+    /** Chunk evidence rows. */
+    evidenceMs: number;
+    /** Waiting for, then running, the ordered whole-file proof. */
+    hashTurnMs: number;
+    /** The proof's own work, including bytes an out-of-order arrival forces
+     * back off the disk. */
     drainMs: number;
     preadBytes: number;
-    fsyncMs: number;
+    /** Making a proven file user-visible and durable. */
+    finishMs: number;
+    /** Releasing handles. */
+    closeMs: number;
+    /** Duplicate destinations. */
     copyMs: number;
 }
 /** The device-scoped home of one workspace Add's staging resume evidence.
@@ -60,16 +87,20 @@ declare class AddStagingEvidence {
 }
 /** One ordinary file downloading directly into its staged destination.
  *
- * Chunks may arrive in any order; each lands with a positioned write, and a
- * serialized drain feeds the whole-file hasher strictly in chunk order — from
- * the arriving bytes when the next expected chunk is at hand, otherwise by
- * reading an already-written later chunk when its turn arrives. This keeps no
- * unaccounted buffers and cannot deadlock failure settlement. Resume rereads
- * every retained chunk by necessity so local staging can never stand in for
- * content proof. */
+ * Chunks may arrive in any order; each lands with a positioned write through
+ * its own handle, and a serialized proof turn feeds the whole-file hasher
+ * strictly in chunk order — from the arriving bytes when the next expected
+ * chunk is at hand, otherwise by reading an already-written later chunk back
+ * through that same handle. The turn that completes the stream proves the
+ * digest and finishes the file before the handle closes, so a single-chunk
+ * file — the cold Add's mass — is created, written, proven, made durable, and
+ * released inside one putChunk, and open handles never outnumber chunks in
+ * flight. Resume rereads every retained chunk by necessity so local staging
+ * can never stand in for content proof. */
 export declare class StagedContentFile implements ContentDownloadTarget {
     private readonly evidence;
     private readonly metrics;
+    private readonly storeActivity;
     readonly artifact: TransferArtifact;
     readonly manifest: ContentManifest;
     private readonly destinations;
@@ -79,36 +110,69 @@ export declare class StagedContentFile implements ContentDownloadTarget {
     private readonly ready;
     private nextChunk;
     private hashTurn;
-    private prepared;
+    private failure;
+    private placed;
+    private finished;
     private sealed;
-    constructor(evidence: AddStagingEvidence, metrics: StagedPlacementMetrics, artifact: TransferArtifact, manifest: ContentManifest, destinations: readonly string[]);
-    private prepare;
-    /** Feed the whole-file hasher every chunk that is now in order. Turns are
-     * serialized: parallel chunk arrivals only mark readiness. */
-    private queueHash;
+    constructor(evidence: AddStagingEvidence, metrics: StagedPlacementMetrics, storeActivity: ConcurrentActivityClock<StoreActivity>, artifact: TransferArtifact, manifest: ContentManifest, destinations: readonly string[]);
+    /** Time one leg of placement. An activity names what is physically in
+     * flight; a leg without one is a wait. */
+    private leg;
+    private legSync;
+    /** One handle on the staged file. A cold Add's first open creates the file
+     * outright — never a probing open that is guaranteed to fail. The first
+     * open of a retained file proves it is a regular file and cuts it to its
+     * manifest length. Every later chunk open still re-proves that its exact,
+     * no-follow target is a regular file; retained staging never becomes trust. */
+    private openHandle;
+    /** Feed the whole-file hasher every chunk now in order — the arriving bytes
+     * on the arrival's own turn, otherwise an already-written chunk read back
+     * through this handle. True when this turn completed the stream. */
+    private drain;
+    /** The stream is complete in order: prove its digest, then make the proven
+     * bytes user-visible and durable through the handle that wrote them. */
+    private finish;
+    /** Queue one serialized proof turn. A failed turn rejects its own caller
+     * and is remembered for seal; the chain stays usable so later chunks fail
+     * on their own evidence, not on a poisoned chain. */
+    private turn;
+    private prove;
     /** Re-prove one retained staged chunk before it may satisfy the download.
-     * Evidence rows only say what should be there; the bytes decide. */
+     * Evidence rows only say what should be there; the bytes decide. A retained
+     * chunk that verifies joins the ordered proof exactly like an arrival. */
     hasChunk(index: number): Promise<boolean>;
     /** Persist one block already verified by @amalgm/live with a positioned
-     * write, then advance the streaming whole-file proof. */
+     * write through this chunk's own handle, then advance the ordered proof.
+     * The chunk that completes the proof finishes the file before its handle
+     * closes; any other chunk simply releases its handle. */
     putChunk(index: number, bytes: Uint8Array): Promise<void>;
-    /** Prove the streamed whole-file digest, fsync, and place every duplicate
-     * destination. The staged file needs no rename of its own: the whole
-     * staging root is revealed by one atomic rename after rows commit. */
+    /** Assert the proof this file's own stream already produced, and place
+     * every duplicate destination from the proven primary. An artifact with no
+     * chunks has no stream: its proof is the empty digest, made here. */
     seal(): Promise<SealedContentFile>;
-    /** Keep staged bytes and evidence for the next attempt. */
+    /** Keep staged bytes and evidence for the next attempt. Handles live only
+     * inside the chunk operations that opened them, so an interrupted file
+     * holds nothing here; an in-flight proof turn is merely allowed to settle. */
     close(): Promise<void>;
 }
-/** One evidence database shared by every staged file in a download set. */
+/** One evidence database and one directory skeleton shared by every staged
+ * file in a download set. */
 export declare class StagedContentSet {
     private readonly evidence;
+    private readonly storeActivity;
     private readonly metrics;
     private closed;
-    constructor(evidenceDir: string);
+    private constructor();
+    /** Open the set for these destinations. Every directory that will hold a
+     * staged file — primary or duplicate — exists before the first byte lands,
+     * so no chunk's store path ever includes a mkdir. */
+    static open(evidenceDir: string, destinations: ReadonlyMap<string, readonly string[]>): Promise<StagedContentSet>;
     target(artifact: TransferArtifact, manifest: ContentManifest, destinations: readonly string[]): StagedContentFile;
-    /** The staged rail's internal placement split, keyed for the download
-     * stage ledger. `stagedWriteMs` and `stagedDrainMs` decompose the outer
-     * write leg; `stagedFsyncMs` and `stagedCopyMs` decompose the seal leg. */
+    /** The staged rail's placement split, keyed for the download stage ledger:
+     * the one-time skeleton, then the per-file legs — open, write, evidence,
+     * the ordered proof (turn wait and drain work), finish, close — and
+     * duplicate copies. The `stagedStore*` states partition the same wall time
+     * by which of file, evidence, and hash work was physically in flight. */
     report(): Record<string, number>;
     close(): void;
 }