@volter/browser-runtime 0.1.84 → 0.1.86

package/dist/browser-pack-store.js

@@ -1,7 +1,8 @@
 import { encodeSharedIndex, OverlaidChildren, OverlaidIndex, SharedIndex, sameIndexEntry } from "./browser-pack-index.js";
+import { PACKAGES_STORE, STORE_BASE_DIRECTORY, STORE_STATE_FILE } from "./browser-store-layout.js";
 import { ImageRangeReader, IMAGE_RANGES_FILE, validateImageRanges } from "./browser-image-ranges.js";
 /** The one shared store of an origin: every package version's files, once, under `/packages/<name>@<version>/`. */
-export const PACKAGES_STORE = "packages";
+export { PACKAGES_STORE };
 export const PACKAGES_ROOT = "/packages";
 /**
  * A project's live-pack retention roots (W62): links that keep an installed
@@ -22,7 +23,7 @@ export const PACKAGES_LOCK = "supercode-browser-packages";
 export const PACKAGES_OPEN_LOCK = "supercode-browser-packages-open";
 const encoder = new TextEncoder();
 const decoder = new TextDecoder("utf-8", { fatal: true });
-const BASE_DIRECTORY = "supercode-browser-filesystems";
+const BASE_DIRECTORY = STORE_BASE_DIRECTORY;
 /**
  * A store whose name begins so is a tree a host installed (ADR-0048), not a
  * project: it links no shared packages, and a sweep of them leaves it alone.
@@ -31,7 +32,7 @@ const BASE_DIRECTORY = "supercode-browser-filesystems";
 export const TREE_STORE_PREFIX = "host-tree.";
 const GENERATIONS_DIRECTORY = "generations";
 const STAGING_DIRECTORY = "atomic-staging";
-const STATE_FILE = "state.json";
+const STATE_FILE = STORE_STATE_FILE;
 const INDEX_FILE = "index.json";
 const LOG_FILE = "index-log.bin";
 const PACK_FILE = "pack.bin";
@@ -85,6 +86,7 @@ export function createPackStore(environment, options = {}) {
     let imageReader;
     let deferredImage;
     let receivedImageCompletion;
+    let receivedImageLine;
     let generationInitializedAt = 0;
     let logAccess;
     /** Committed package bytes captured under the writer lock; never mutable workspace bytes. */
@@ -220,7 +222,8 @@ export function createPackStore(environment, options = {}) {
     function imageCompletionSeed() {
         if (!imageReader || !imageRangesDigest || !generation || initializing || transitions > 0 || closing)
             return undefined;
-        return { generation, rangesDigest: imageRangesDigest, completed: imageReader.completionBuffer };
+        return { generation, rangesDigest: imageRangesDigest, completed: imageReader.completionBuffer,
+            ...(imageReader.receiptKey ? { metadata: { ranges: imageReader.verifiedRanges, receiptKey: imageReader.receiptKey } } : {}) };
     }
     /**
      * The owner stands on the seed it just encoded, as its readers do: the index
@@ -417,6 +420,7 @@ export function createPackStore(environment, options = {}) {
             projectId = validProjectId(requestedProjectId);
             readOnly = openOptions.readOnly === true;
             receivedImageCompletion = readOnly ? openOptions.imageCompletion : undefined;
+            receivedImageLine = readOnly ? openOptions.imageLine : undefined;
             extentsOnly = readOnly && openOptions.extentsOnly === true;
             shared = openOptions.shared === true || readOnly;
             if (!shared)
@@ -753,17 +757,38 @@ export function createPackStore(environment, options = {}) {
             logAccess = await openSyncAccess(log, "record of changes");
             logBytes = logAccess.getSize();
             if (imageRangesDigest) {
-                const file = await (await directory.getFileHandle(IMAGE_RANGES_FILE)).getFile();
-                const bytes = new Uint8Array(await file.arrayBuffer());
-                if (await indexDigest(bytes) !== imageRangesDigest)
-                    throw new Error("The committed immutable image ranges have changed. Stored data was retained.");
-                const ranges = validateImageRanges(JSON.parse(decoder.decode(bytes)));
+                const supplied = receivedImageCompletion;
+                const completion = supplied && supplied.generation === generation && supplied.rangesDigest === imageRangesDigest
+                    ? supplied : undefined;
+                let ranges;
+                let receiptKey;
+                if (completion?.metadata) {
+                    // This is the existing private owner/reader seed, not an image or
+                    // guest-supplied claim. Current committed state binds its identity.
+                    ranges = validateImageRanges(completion.metadata.ranges);
+                    receiptKey = completion.metadata.receiptKey;
+                    if (!/^[a-f0-9]{64}$/u.test(receiptKey))
+                        throw new Error("The owner's immutable receipt key is invalid.");
+                }
+                else {
+                    const file = await (await directory.getFileHandle(IMAGE_RANGES_FILE)).getFile();
+                    const bytes = new Uint8Array(await file.arrayBuffer());
+                    if (await indexDigest(bytes) !== imageRangesDigest)
+                        throw new Error("The committed immutable image ranges have changed. Stored data was retained.");
+                    ranges = validateImageRanges(JSON.parse(decoder.decode(bytes)));
+                    // The ledger key retains ADR-0076's canonical validated-table hash,
+                    // including for old files whose JSON whitespace differs.
+                    receiptKey = await indexDigest(encoder.encode(JSON.stringify(ranges)));
+                }
                 if (ranges.bytes > packAccess.getSize())
                     throw new Error("The immutable image reservation is incomplete. Stored data was retained.");
-                const completion = receivedImageCompletion;
-                const completed = completion && completion.generation === generation && completion.rangesDigest === imageRangesDigest
-                    ? completion.completed : undefined;
-                imageReader = new ImageRangeReader(ranges, directory, `${projectId}.${generation}`, completed);
+                // The owner's line serves only the generation and table its completion names.
+                const line = completion ? receivedImageLine : undefined;
+                if (!line)
+                    receivedImageLine?.port.close();
+                receivedImageLine = undefined;
+                imageReader = new ImageRangeReader(ranges, directory, `${projectId}.${generation}`, completion?.completed, receiptKey, line);
+                await imageReader.initialize();
                 deferredImage = ranges.image;
             }
         }
@@ -1900,7 +1925,7 @@ export function createPackStore(environment, options = {}) {
         if (!shared)
             await discardGenerations(name);
     }
-    async function installPreparedImage(prepared, json, binary, suppliedRanges) {
+    async function installPreparedImage(prepared, json, binary, suppliedRanges, verified = false) {
         assertWritable();
         if (!shared || projectId !== PACKAGES_STORE)
             throw new Error("Only the shared package store can reserve immutable image extents.");
@@ -1911,7 +1936,7 @@ export function createPackStore(environment, options = {}) {
         const ranges = validateImageRanges(suppliedRanges);
         if (ranges.bytes !== prepared.packBytes || prepared.entries > MAX_ENTRIES || prepared.liveBytes > prepared.packBytes
             || json.byteLength !== prepared.json.raw || binary.byteLength !== prepared.binary.raw
-            || await indexDigest(json) !== prepared.json.sha256 || await indexDigest(binary) !== prepared.binary.sha256) {
+            || !await matchesDigest(json, prepared.json.sha256, verified) || !await matchesDigest(binary, prepared.binary.sha256, verified)) {
             throw new Error("The image's prepared metadata does not match its document.");
         }
         // The pinned host emits the authoritative JSON checkpoint and its matching
@@ -1923,7 +1948,8 @@ export function createPackStore(environment, options = {}) {
         const retained = JSON.parse(`${decoder.decode(json.subarray(0, newline - 1))}}`);
         const measures = { packBytes: prepared.packBytes, liveBytes: prepared.liveBytes, linked: 0, linkedBytes: 0 };
         const header = retained.retainedIndex;
-        if (header.version !== 1 || header.digest !== await retainedIndexDigest(binary, measures)
+        // The binary's digest is the descriptor's, now matched: it is not hashed a second time.
+        if (header.version !== 1 || header.digest !== await retainedIndexDigestOf(prepared.binary.sha256, measures)
             || header.packBytes !== measures.packBytes || header.liveBytes !== measures.liveBytes || header.linked !== 0 || header.linkedBytes !== 0) {
             throw new Error("The prepared index's retained measures are inconsistent.");
         }
@@ -1951,14 +1977,14 @@ export function createPackStore(environment, options = {}) {
             return true;
         });
     }
-    async function installPreparedProject(prepared, json, binary) {
+    async function installPreparedProject(prepared, json, binary, verified = false, imageInstalled) {
         assertWritable();
-        if (shared || !options.packages?.deferredImage)
+        if (shared || !options.packages || (!imageInstalled && !options.packages.deferredImage))
             throw new Error("Prepared project paths require a verified shared image.");
         if (packBytes !== 0 || [...entries.values()].some(entry => entry.type !== "directory"))
             return false;
         if (json.byteLength !== prepared.json.raw || binary.byteLength !== prepared.binary.raw
-            || await indexDigest(json) !== prepared.json.sha256 || await indexDigest(binary) !== prepared.binary.sha256) {
+            || !await matchesDigest(json, prepared.json.sha256, verified) || !await matchesDigest(binary, prepared.binary.sha256, verified)) {
             throw new Error("The image's prepared project does not match its descriptor.");
         }
         const newline = json.subarray(0, 4096).indexOf(10);
@@ -1966,7 +1992,7 @@ export function createPackStore(environment, options = {}) {
             throw new Error("The prepared project has no bounded retained header.");
         const header = JSON.parse(`${decoder.decode(json.subarray(0, newline - 1))}}`).retainedIndex;
         const measures = { packBytes: 0, liveBytes: 0, linked: prepared.linked, linkedBytes: prepared.linkedBytes };
-        if (header.version !== 1 || header.digest !== await retainedIndexDigest(binary, measures)
+        if (header.version !== 1 || header.digest !== await retainedIndexDigestOf(prepared.binary.sha256, measures)
             || header.packBytes !== 0 || header.liveBytes !== 0 || header.linked !== prepared.linked || header.linkedBytes !== prepared.linkedBytes) {
             throw new Error("The prepared project's retained measures are inconsistent.");
         }
@@ -1988,6 +2014,12 @@ export function createPackStore(environment, options = {}) {
             }
             await writeBytesAtomically(directory, RETAINED_INDEX_FILE, binary);
             await writeBytesAtomically(directory, INDEX_FILE, json);
+            // Written beside the shared image's install; committed only over it. A
+            // generation left uncommitted is swept with any other on the next open.
+            if (imageInstalled && !await imageInstalled)
+                return false;
+            if (!options.packages?.deferredImage)
+                throw new Error("Prepared project paths require a verified shared image.");
             await commitGeneration(name, directory, new Map(), 0, { index, ...measures });
             return true;
         });
@@ -2061,6 +2093,18 @@ export function createPackStore(environment, options = {}) {
         const hash = await crypto.subtle.digest("SHA-256", bytes);
         return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, "0")).join("");
     }
+    /**
+     * Whether these bytes are the ones a digest names: hashed here, unless they
+     * were already checked against this same digest where they were inflated.
+     */
+    async function matchesDigest(bytes, digest, verified) {
+        return verified || await indexDigest(bytes) === digest;
+    }
+    /** The retained index digest from the binary index's own SHA-256, when that is already known. */
+    function retainedIndexDigestOf(binaryDigest, measures) {
+        const { packBytes, liveBytes, linked, linkedBytes, journalPrefix } = measures;
+        return indexDigest(encoder.encode(`${JSON.stringify({ packBytes, liveBytes, linked, linkedBytes, ...(journalPrefix ? { journalPrefix } : {}) })}:${binaryDigest}`));
+    }
     async function retainedIndexDigest(bytes, measures) {
         const { packBytes, liveBytes, linked, linkedBytes, journalPrefix } = measures;
         // Bind the byte measures too: none may be trusted independently of the
@@ -2651,6 +2695,14 @@ export function createPackStore(environment, options = {}) {
         clock,
         readerSeed,
         imageCompletionSeed,
+        imageLine: () => imageReader?.lineForReader() ?? options.packages?.imageLine(),
+        imageStartupSet: () => imageReader?.readDigests() ?? imageReader?.completedDigests() ?? [],
+        prefetchImage: (digests, streams) => imageReader?.prefetch(digests, streams) ?? { queued: 0, done: Promise.resolve() },
+        imageBlockedReads: () => {
+            const own = imageReader?.blockedReads ?? { ranges: 0, ms: 0 };
+            const linked = options.packages?.imageBlockedReads() ?? { ranges: 0, ms: 0 };
+            return { ranges: own.ranges + linked.ranges, ms: own.ms + linked.ms };
+        },
         seeded: () => startedFromSeed,
         get logBytes() { return logBytes; },
         checkpoint,
@@ -2682,10 +2734,10 @@ export function createPackStore(environment, options = {}) {
  * the origin's packages it links, both open for reading beside their
  * owners. Undefined when the project has no store yet.
  */
-export async function openPackReader(environment, projectId, seed) {
+export async function openPackReader(environment, projectId, seed, imageLine) {
     const packages = createPackStore(environment);
     await packages.initialize(PACKAGES_STORE, { readOnly: true, extentsOnly: true,
-        ...(seed?.packagesImage ? { imageCompletion: seed.packagesImage } : {}) });
+        ...(seed?.packagesImage ? { imageCompletion: seed.packagesImage, ...(imageLine ? { imageLine } : {}) } : {}) });
     const project = createPackStore(environment, { packages, ownsPackages: true });
     let opened;
     try {