@amalgm/live 0.2.59 → 0.2.60

package/PURPOSE.md

@@ -204,11 +204,12 @@ its cutover.
     complete-file allocation in the bounded transfer path.
 31. **A content block is not a round trip.** Text and binary retain independent
     content-addressed block identities. Cold upload moves complete small
-    artifacts in bounded cargo segments and adjacent missing large-file
-    blocks in bounded binary batches, while cold download merges packed spans.
-    Packing may reduce
-    transport work but can never weaken per-block verification, durable sealing,
-    or commit order.
+    artifacts in bounded cargo segments and adjacent missing large-file blocks
+    in bounded binary batches. Cold download plans whole waves against
+    placement: all missing manifests, then all missing blocks, each wave
+    grouped by pack so adjacent members merge into bounded range reads.
+    Packing may reduce transport work but can never weaken per-block
+    verification, durable sealing, or commit order.
 32. **A content layout owns a cloud namespace.** A writer change that derives
     different block identities for the same complete bytes advances the
     content contract and storage namespace together. Readers remain additive;
@@ -297,6 +298,17 @@ its cutover.
     current pointer atomically. Retries never reactivate an older id, prior
     deployments remain addressable, and SQLite rows, WAL pages, locks, and
     offsets remain machine-local materializations rather than sync payloads.
+44. **Sealed answers correctness; packed answers placement.** `sealed` proves
+    an artifact's bytes are durably valid under the current content contract,
+    and record submission trusts it unconditionally, whatever the placement.
+    `packed` proves the artifact is stored efficiently inside an immutable
+    pack — and one manifest location row proves its complete packed closure,
+    because the authority records every block location and the manifest
+    location before sealing. Upload skips a small artifact only when it is
+    both sealed and packed; a large artifact requires only sealed. Repacking
+    is placement work, never correctness work: placement rows converge
+    first-wins, a source missing at repack time is skipped silently, and
+    what readers can open never changes.
 
 ## Five surfaces, one behavior
 

package/dist/transfer/download.d.ts

@@ -1,37 +1,59 @@
 /**
  * Download a set of immutable artifacts into a machine cache.
  *
- * The set is the primitive: one plan phase proves every manifest and asks the
- * cache which chunks are gaps, one fetch phase obtains every gap across the
- * whole set under a single bound, and one seal phase verifies each complete
- * artifact. A lone artifact is a set of one — there is no second path. This
- * shape removes per-artifact serialization: no artifact waits behind
- * another's plan or seal, only behind the shared fetch bound. Each chunk is
- * still its own storage request — the set changes scheduling, not the
- * request count.
+ * The set is the primitive and the plan is physical. Wave one proves every
+ * manifest: locally held ones are checked in place, missing ones are
+ * resolved as one want-list and fetched grouped by the pack that holds
+ * them. Wave two reads the proven manifests, asks the cache which chunks
+ * are gaps, resolves the whole gap list, and fetches it the same way: all
+ * members of one pack collapse into a few broad byte spans — approximately
+ * one read per pack — while standalone objects remain one read each. A
+ * lone artifact is a set of one; there is no second download path.
  *
- * Fetches complete in whatever order the network answers, but each artifact
+ * Spans complete in whatever order storage answers, but each artifact
  * stores its chunks in chunk order: a verified chunk waits until every
- * earlier gap of the same artifact has been stored. Gaps are admitted round
- * robin across artifacts, so one large artifact cannot occupy the whole
- * window while unrelated work waits. Held bytes stay inside the in-flight
- * byte bound.
+ * earlier gap of the same artifact is stored, so a host assembling a
+ * whole-file digest never re-reads what landed early. The scheduler admits
+ * fetch units strictly in fair plan order, and the plan orders units so a
+ * chunk's predecessor always lives in the same or an earlier unit — an
+ * artifact whose gaps do not line up ascending inside one pack falls back
+ * to per-object reads at its own positions — so ordered stores can never
+ * deadlock. Chains enter the plan round-robin by depth, so one multi-chunk
+ * artifact cannot monopolize the bounded window while unrelated artifacts
+ * wait. In-flight span bytes stay inside one explicit bound; raising request
+ * concurrency never silently raises memory.
  *
- * Every chunk keeps one content-addressed identity, whether its sealed
- * envelope lives alone or as a byte range inside an immutable pack. The
- * host's ports resolve and fetch those identities; parallelism, storage
- * layout, transport, and decryption are the host's concern, while the
- * verification laws here remain singular.
+ * Every object keeps one content-addressed identity whether its sealed
+ * envelope lives alone or as a byte range inside an immutable pack, and
+ * placement is immutable: a retried read may refresh its URL but never its
+ * geometry. Wrong or shifted bytes cannot leak — every dispensed slice is
+ * still an authenticated envelope the host opens and this engine
+ * hash-verifies before a single byte is stored.
  */
 import { type ContentManifest } from '../contracts/content.js';
 import type { Sha256Hex } from '../entities/types.js';
 import { type TransferArtifact } from './artifacts.js';
+import { type ByteSpan } from './ranges.js';
+import { type ContentObjectName, type ContentRef } from './refs.js';
 export interface DownloadPorts<LocalArtifact> {
     readonly sha256Hex: Sha256Hex;
-    getManifest(artifact: TransferArtifact): Promise<unknown>;
+    /** A manifest the host already holds for this artifact, or null to have
+     * the set fetch it. A hint only — the answer is still proven here. */
+    localManifest(artifact: TransferArtifact): unknown;
+    /** Resolve one batch of named objects to storage locations, aligned by
+     * index. Called with at most CONTENT_REFS_BATCH_OBJECTS names. */
+    requestRefs(objects: readonly ContentObjectName[]): Promise<readonly ContentRef[]>;
+    /** Perform one storage read: a byte range of a pack, or a whole
+     * standalone object when span is null. `refresh` re-resolves the read's
+     * location for a retry attempt and throws loudly if placement moved. */
+    fetchSpan(url: string, span: ByteSpan | null, refresh: () => Promise<string>): Promise<Uint8Array>;
+    /** Open one sealed envelope into its plaintext bytes. */
+    openEnvelope(object: ContentObjectName, sealed: Uint8Array): Promise<Uint8Array>;
+    /** A fetched manifest just proved against its artifact; the host persists
+     * it wherever this artifact is being assembled. */
+    manifestProven(artifact: TransferArtifact, manifest: ContentManifest): Promise<void>;
     /** True only when this exact content-addressed chunk is locally verified. */
     hasChunk(artifact: TransferArtifact, manifest: ContentManifest, index: number): Promise<boolean>;
-    getChunk(artifact: TransferArtifact, manifest: ContentManifest, index: number): Promise<Uint8Array>;
     putChunk(artifact: TransferArtifact, manifest: ContentManifest, index: number, bytes: Uint8Array): Promise<void>;
     /** Verify and expose the complete immutable artifact assembled from cache. */
     sealArtifact(artifact: TransferArtifact, manifest: ContentManifest): Promise<SealedArtifact<LocalArtifact>>;
@@ -43,8 +65,10 @@ export interface SealedArtifact<LocalArtifact> {
 }
 export interface DownloadOptions {
     readonly concurrency?: number;
-    /** Maximum plaintext chunk bytes held by in-flight fetch effects. Raising
-     * request concurrency never silently raises this memory bound. */
+    /** Maximum bytes held by in-flight fetch units. Raising request
+     * concurrency never silently raises this memory bound. A single sealed
+     * envelope larger than the bound still fetches whole; admission then
+     * serializes around it. */
     readonly maxInFlightBytes?: number;
 }
 export interface DownloadReceipt<LocalArtifact> {
@@ -54,10 +78,26 @@ export interface DownloadReceipt<LocalArtifact> {
     readonly downloadedChunks: number;
     readonly reusedChunks: number;
 }
+/** The physical geometry one download performed — how knowledge arrived and
+ * how many storage reads carried it. */
+export interface DownloadShape {
+    readonly localManifests: number;
+    readonly fetchedManifests: number;
+    readonly packedManifests: number;
+    readonly standaloneManifests: number;
+    /** Ranged pack reads that carried manifests. */
+    readonly manifestSpans: number;
+    readonly packedBlocks: number;
+    readonly standaloneBlocks: number;
+    /** Ranged pack reads that carried chunk blocks. */
+    readonly blockSpans: number;
+}
+export interface DownloadResult<LocalArtifact> {
+    readonly receipts: readonly DownloadReceipt<LocalArtifact>[];
+    readonly shape: DownloadShape;
+}
 /** Download a set of immutable artifacts, fetching only machine-cache gaps.
  * Receipts return in input order; any failure fails the whole set after
  * letting in-flight effects settle. */
-export declare function downloadAll<LocalArtifact>(artifacts: readonly TransferArtifact[], ports: DownloadPorts<LocalArtifact>, options?: DownloadOptions): Promise<readonly DownloadReceipt<LocalArtifact>[]>;
-/** Download one immutable artifact — a set of one. */
-export declare function download<LocalArtifact>(artifact: TransferArtifact, ports: DownloadPorts<LocalArtifact>, options?: DownloadOptions): Promise<DownloadReceipt<LocalArtifact>>;
+export declare function downloadAll<LocalArtifact>(artifacts: readonly TransferArtifact[], ports: DownloadPorts<LocalArtifact>, options?: DownloadOptions): Promise<DownloadResult<LocalArtifact>>;
 //# sourceMappingURL=download.d.ts.map

package/dist/transfer/download.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/transfer/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAO/E,MAAM,WAAW,aAAa,CAAC,aAAa;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,6EAA6E;IAC7E,QAAQ,CACN,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,QAAQ,CACN,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,QAAQ,CACN,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,8EAA8E;IAC9E,YAAY,CACV,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc,CAAC,aAAa;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;sEACkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,eAAe,CAAC,aAAa;IAC5C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAmBD;;uCAEuC;AACvC,wBAAsB,WAAW,CAAC,aAAa,EAC7C,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,SAAS,eAAe,CAAC,aAAa,CAAC,EAAE,CAAC,CA0FpD;AAED,sDAAsD;AACtD,wBAAsB,QAAQ,CAAC,aAAa,EAC1C,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,EACnC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAIzC"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/transfer/download.ts"],"names":[],"mappings":"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"}