@volter/browser-runtime 0.1.166 → 0.1.167

package/dist/browser-pack-store.js

@@ -1,6 +1,8 @@
+import { adaptBrowserOpfsSyncAccess, browserOpfsAccessError, isBrowserOpfsAccessContention } from "./browser-opfs-access.js";
 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";
+import { ImageExtentOwnership } from "./browser-image-ownership.js";
 /** The one shared store of an origin: every package version's files, once, under `/packages/<name>@<version>/`. */
 export { PACKAGES_STORE };
 export const PACKAGES_ROOT = "/packages";
@@ -64,6 +66,10 @@ const DIRECTORY_MODE = 0o755;
 const FILE_MODE = 0o644;
 /** The store, bound to the worker that holds its handles. */
 export function createPackStore(environment, options = {}) {
+    return createPackStoreInternal(environment, options);
+}
+/** Maintenance callers already hold PACKAGES_OPEN_LOCK exclusively. */
+function createPackStoreInternal(environment, options = {}, maintenance = false) {
     const explicitBytes = options.limits?.maxBytes;
     const maximumEntries = options.limits?.maxEntries ?? MAX_ENTRIES;
     if ((explicitBytes !== undefined && (!Number.isSafeInteger(explicitBytes) || explicitBytes < 1))
@@ -82,6 +88,8 @@ export function createPackStore(environment, options = {}) {
     let linkedBytes = 0;
     /** Linked bytes under the retention root, which the project budget excludes. */
     let releaseLock;
+    let releaseUsersLock;
+    let committedPredecessor;
     let projectId;
     let generation;
     let entries = new Map();
@@ -90,6 +98,7 @@ export function createPackStore(environment, options = {}) {
     let packAccess;
     let imageRangesDigest;
     let imageReader;
+    let imageOwnership;
     let deferredImage;
     let receivedImageCompletion;
     let receivedImageLine;
@@ -366,7 +375,13 @@ export function createPackStore(environment, options = {}) {
         if (!access)
             throw new Error("OPFS filesystem worker is not initialized.");
         const value = new Uint8Array(length);
-        if (length > 0 && length <= READ_AHEAD_BYTES && offset >= 0 && offset + length <= immutableReadEnd) {
+        const aheadStart = Math.floor(offset / READ_AHEAD_BYTES) * READ_AHEAD_BYTES;
+        const aheadEnd = Math.min(Math.ceil((offset + length) / READ_AHEAD_BYTES) * READ_AHEAD_BYTES, immutableReadEnd);
+        // Recovered files must not fetch an unrelated old range merely to
+        // fill an aligned cache block containing still-unacquired neighbours.
+        const boundedOwnership = imageReader && ownsImageExtent(offset, length)
+            && !ownsImageExtent(aheadStart, Math.max(0, aheadEnd - aheadStart));
+        if (!boundedOwnership && length > 0 && length <= READ_AHEAD_BYTES && offset >= 0 && offset + length <= immutableReadEnd) {
             let copied = 0;
             while (copied < length) {
                 const position = offset + copied;
@@ -410,6 +425,17 @@ export function createPackStore(environment, options = {}) {
         const opening = new AbortController();
         openingController = opening;
         try {
+            if (!maintenance) {
+                const locks = environment.navigator.locks;
+                if (!locks)
+                    throw new Error("Opening a store requires storage ownership locks.");
+                await new Promise((ready, fail) => {
+                    void locks.request(PACKAGES_OPEN_LOCK, { mode: "shared", signal: opening.signal }, () => new Promise(release => {
+                        releaseUsersLock = release;
+                        ready();
+                    })).catch(fail);
+                });
+            }
             // A closed holder can be reopened, but no index or failed-write latch from
             // its previous workspace may become the opening state of the next one.
             entries = new Map();
@@ -577,10 +603,10 @@ export function createPackStore(environment, options = {}) {
                 }
                 if (!shared) {
                     packAccess.truncate(packBytes);
-                    // Cleanup follows successful validation and replay. On unreadable metadata,
-                    // even staging records may be useful recovery evidence and must survive.
-                    await removeEntry(project, STAGING_DIRECTORY, true);
-                    await discardGenerations(generation);
+                    // A committed index does not identify interrupted staging files as ours
+                    // to delete. Each atomic writer cleans only its own temporary file.
+                    // An open cannot identify a validated predecessor; unknown generations
+                    // remain available for interrupted-operation diagnosis.
                     opening.signal.throwIfAborted();
                     if (deadBytes > COMPACTION_FLOOR_BYTES && deadBytes > liveBytes)
                         await compact();
@@ -614,7 +640,14 @@ export function createPackStore(environment, options = {}) {
             catch (error) {
                 failures.push(error);
             }
+            try {
+                releaseUsersLock?.();
+            }
+            catch (error) {
+                failures.push(error);
+            }
             releaseLock = undefined;
+            releaseUsersLock = undefined;
             project = undefined;
             if (failures.length > 1)
                 throw new AggregateError(failures, "OPFS workspace open and cleanup failed.");
@@ -731,14 +764,21 @@ export function createPackStore(environment, options = {}) {
                         abort();
                 });
                 const opened = await Promise.race([
-                    pending.then((access) => ({ access })).catch((cause) => { refusal = cause; return undefined; }),
+                    pending.then((access) => ({ access })).catch((cause) => {
+                        refusal = cause;
+                        // Keep the unsupported sharing-mode explanation below; retry only
+                        // actual access contention, not quota/security/device failures.
+                        if (!(cause instanceof TypeError) && !isBrowserOpfsAccessContention(cause))
+                            throw browserOpfsAccessError("open", cause);
+                        return undefined;
+                    }),
                     new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), OPEN_ATTEMPT_MS); }),
                     cancelled,
                 ]);
                 signal?.throwIfAborted();
                 if (opened) {
                     claimed = true;
-                    return opened.access;
+                    return adaptBrowserOpfsSyncAccess(opened.access);
                 }
             }
             finally {
@@ -756,8 +796,10 @@ export function createPackStore(environment, options = {}) {
             }
             await new Promise((resolve) => setTimeout(resolve, 500));
         }
-        const reason = refusal instanceof Error ? ` (${refusal.message})` : "";
-        throw new Error(`This browser workspace's ${name} is held by another page${reason}.`);
+        if (isBrowserOpfsAccessContention(refusal))
+            throw browserOpfsAccessError("open", refusal);
+        // No observed permission error means no evidence that another page owns it.
+        throw new Error(`This browser workspace's ${name} access handle did not become available.`);
     }
     async function openGenerationHandles(directory) {
         closeGenerationHandles();
@@ -800,7 +842,9 @@ export function createPackStore(environment, options = {}) {
                 if (!line)
                     receivedImageLine?.port.close();
                 receivedImageLine = undefined;
-                imageReader = new ImageRangeReader(ranges, directory, `${projectId}.${generation}`, completion?.completed, receiptKey, line);
+                imageOwnership = new ImageExtentOwnership();
+                await imageOwnership.open(directory, ranges.bytes, !readOnly);
+                imageReader = new ImageRangeReader(ranges, directory, `${projectId}.${generation}`, completion?.completed, receiptKey, line, (offset, length) => imageOwnership?.covers(offset, length) ?? false);
                 // Whether this reader shares its owner's completion: one that does not
                 // asks the materializer for every range the owner already placed.
                 console.log(`[boot-trace] ${JSON.stringify({ event: "image-reader-open", at: Date.now(), reader: `${projectId}.${generation}`, offered: supplied !== undefined,
@@ -817,6 +861,8 @@ export function createPackStore(environment, options = {}) {
     function closeGenerationHandles() {
         imageReader?.close();
         imageReader = undefined;
+        imageOwnership?.close();
+        imageOwnership = undefined;
         deferredImage = undefined;
         const pack = packAccess, log = logAccess;
         packAccess = undefined;
@@ -969,12 +1015,6 @@ export function createPackStore(environment, options = {}) {
             clearTimeout(timer);
         }
     }
-    function validProjectId(value) {
-        if (typeof value !== "string" || !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u.test(value)) {
-            throw new Error("OPFS filesystem projectId is invalid.");
-        }
-        return value;
-    }
     async function projectDirectory() {
         if (!project)
             throw new Error("OPFS filesystem worker is not initialized.");
@@ -1000,8 +1040,13 @@ export function createPackStore(environment, options = {}) {
         }
     }
     /** Only validated committed state establishes which generations are unreachable. */
-    async function discardGenerations(retain) {
+    async function discardPredecessor(previous, retain) {
+        if (!previous || previous === retain)
+            return;
         const directory = await projectDirectory();
+        const state = readStorageState(await readJson(directory, STATE_FILE));
+        if (!state || state.generation !== retain)
+            throw new Error("Committed state changed before predecessor release; generations were retained.");
         let root;
         try {
             root = await directory.getDirectoryHandle(GENERATIONS_DIRECTORY);
@@ -1011,9 +1056,12 @@ export function createPackStore(environment, options = {}) {
                 return;
             throw cause;
         }
-        for await (const [name] of root.entries()) {
-            if (name !== retain)
-                await removeGenerationQuietly(root, name);
+        try {
+            await root.removeEntry(previous, { recursive: true });
+        }
+        catch (cause) {
+            if (!notFound(cause))
+                throw cause;
         }
     }
     // ---------------------------------------------------------------- writes
@@ -1771,7 +1819,7 @@ export function createPackStore(environment, options = {}) {
             pack.flush();
             log.flush();
             flushStorage();
-            const previous = { pack: packAccess, log: logAccess };
+            const previous = { pack: packAccess, log: logAccess, generation };
             packAccess = pack;
             logAccess = log;
             logBytes = 0;
@@ -1799,7 +1847,7 @@ export function createPackStore(environment, options = {}) {
                 throw mutationFailure;
             }
             named();
-            await discardGenerations(next);
+            await discardPredecessor(previous.generation, next);
         }
         finally {
             if (!switched) {
@@ -1841,10 +1889,10 @@ export function createPackStore(environment, options = {}) {
         if (changed)
             await checkpoint();
     }
-    function retain(keep) {
-        return rewriteGeneration(() => retainGeneration(keep));
+    function retain(keep, options = {}) {
+        return rewriteGeneration(() => retainGeneration(keep, options.preserveOffsets));
     }
-    async function retainGeneration(keep) {
+    async function retainGeneration(keep, preserveOffsets = false) {
         const source = packAccess;
         if (!source)
             throw new Error("OPFS filesystem worker is not initialized.");
@@ -1868,7 +1916,7 @@ export function createPackStore(environment, options = {}) {
                     index.set(path, { ...entry, offset: 0, length: 0 });
                     continue;
                 }
-                const offset = cursor;
+                const offset = preserveOffsets ? entry.offset : cursor;
                 moved.set(entry.offset, offset);
                 let copied = 0;
                 while (copied < entry.length) {
@@ -1887,7 +1935,7 @@ export function createPackStore(environment, options = {}) {
                     }
                     copied += span;
                 }
-                cursor += entry.length;
+                cursor = Math.max(cursor, offset + entry.length);
                 const { capacity: _room, ...extent } = entry;
                 index.set(path, { ...extent, offset, length: entry.length });
             }
@@ -1911,6 +1959,7 @@ export function createPackStore(environment, options = {}) {
         }
     }
     async function commitGenerationIn(name, directory, index, bytes, prepared, rangesDigest) {
+        const previous = generation;
         // Publish only a generation whose pack, index and initial journal exist.
         // Opening a committed generation must never fabricate missing data files.
         const journal = await directory.getFileHandle(LOG_FILE, { create: true });
@@ -1952,8 +2001,9 @@ export function createPackStore(environment, options = {}) {
             measureBytes();
         // Another tab may hold a shared store's older generation open; only a
         // project's own are discarded.
+        committedPredecessor = previous;
         if (!shared)
-            await discardGenerations(name);
+            await discardPredecessor(previous, name);
     }
     async function installPreparedImage(prepared, json, binary, suppliedRanges, verified = false) {
         assertWritable();
@@ -2522,9 +2572,6 @@ export function createPackStore(environment, options = {}) {
                 segments += 1;
         return segments;
     }
-    function notFound(cause) {
-        return cause instanceof DOMException && cause.name === "NotFoundError";
-    }
     /** FNV-1a: enough to tell a whole record from a torn one. */
     function fingerprint(value) {
         let hash = 0x811c9dc5;
@@ -2542,6 +2589,7 @@ export function createPackStore(environment, options = {}) {
             logAccess?.flush();
             closeGenerationHandles();
             releaseLock?.();
+            releaseUsersLock?.();
         });
     function applyNow(mutations, options = {}) {
         assertWritable();
@@ -2598,6 +2646,50 @@ export function createPackStore(environment, options = {}) {
             }
         }, options);
     }
+    function ownsImageExtent(offset, length) {
+        return imageOwnership?.covers(offset, length) ?? true;
+    }
+    function materializeImageExtentsNow(bytes, files, sourceDigest) {
+        assertWritable();
+        if (!shared || !imageReader || !imageOwnership || !packAccess)
+            throw new Error("Only a reserved shared image can acquire existing immutable extents.");
+        if (!/^[a-f0-9]{64}$/u.test(sourceDigest))
+            throw new Error("Immutable acquisition requires its verified source digest.");
+        const acquired = [];
+        // Validate the entire unit before its first write. Matching metadata
+        // comes from an integrity-addressed unit, never a filename substitution.
+        for (const file of files) {
+            const entry = entries.get(requiredPath(file.path));
+            if (!entry || entry.pack || entry.type !== file.type || entry.mode !== file.mode
+                || (file.type !== "directory" && (entry.length !== file.length || file.offset === undefined
+                    || !Number.isSafeInteger(file.offset) || file.offset < 0 || file.offset + entry.length > bytes.byteLength))) {
+                throw new Error(`The current image's immutable unit disagrees with retained metadata at ${file.path}. Stored offsets were retained.`);
+            }
+        }
+        for (const file of files) {
+            const entry = entries.get(file.path);
+            if (entry.type === "directory" || entry.length === 0 || ownsImageExtent(entry.offset, entry.length))
+                continue;
+            const content = bytes.subarray(file.offset, file.offset + entry.length);
+            writePackAt(entry.offset, content);
+            acquired.push([entry.offset, entry.length]);
+        }
+        if (acquired.length === 0)
+            return;
+        // Adjacent verified files are one ownership interval; no gap is inferred.
+        acquired.sort((left, right) => left[0] - right[0]);
+        const joined = [];
+        for (const [offset, length] of acquired) {
+            const last = joined.at(-1);
+            if (last && last[0] + last[1] === offset)
+                last[1] += length;
+            else
+                joined.push([offset, length]);
+        }
+        packAccess.flush();
+        imageOwnership.record(joined, sourceDigest);
+        readAhead.clear();
+    }
     /** One batch of index changes: applied, bounded, recorded as one record, or rolled back whole. */
     function runBatch(apply, options) {
         if (!packAccess || !logAccess)
@@ -2696,10 +2788,13 @@ export function createPackStore(environment, options = {}) {
             }
             finally {
                 const release = releaseLock;
+                const releaseUsers = releaseUsersLock;
                 releaseLock = undefined;
+                releaseUsersLock = undefined;
                 project = undefined;
                 try {
                     release?.();
+                    releaseUsers?.();
                 }
                 finally {
                     if (options.ownsPackages)
@@ -2718,6 +2813,13 @@ export function createPackStore(environment, options = {}) {
         readExtent,
         descendants,
         retain,
+        discardUnreferencedGenerations: async () => {
+            assertWritable();
+            if (!generation)
+                throw new Error("No committed generation establishes what can be released.");
+            await discardPredecessor(committedPredecessor, generation);
+            committedPredecessor = undefined;
+        },
         remapLinks,
         childrenOf: (path) => [...(children.get(path) ?? [])].sort(),
         refresh,
@@ -2733,6 +2835,8 @@ export function createPackStore(environment, options = {}) {
         checkpoint,
         deferMaintenance,
         installPreparedImage,
+        ownsImageExtent,
+        materializeImageExtentsNow,
         installPreparedProject,
         get deferredImage() { return deferredImage; },
         get imagePlacedAt() { return project && imageRangesDigest ? generationInitializedAt : undefined; },
@@ -2774,6 +2878,7 @@ export async function openPackReader(environment, projectId, seed, imageLine) {
         throw cause;
     }
     if (!opened && !project.opened()) {
+        project.close();
         packages.close();
         return undefined;
     }
@@ -2785,6 +2890,158 @@ const SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const SWEEP_MARK_FILE = "sweep.json";
 /** A package or module linked this recently is kept, linked now or not: two projects taking turns on one origin keep both trees. */
 const SWEEP_GRACE_MS = 14 * 24 * 60 * 60 * 1000;
+/** Stop/dispose the selected project first. Reclamation never relocates another project's offsets. */
+export async function releaseProjectStore(environment, id, progress) {
+    validProjectId(id);
+    if (id === PACKAGES_STORE || id === STAGING_DIRECTORY || id.startsWith(TREE_STORE_PREFIX))
+        throw new Error("Select an application project to release.");
+    const locks = environment.navigator.locks;
+    if (!locks)
+        throw new Error("Project release requires storage ownership locks.");
+    return locks.request(`supercode-browser-project:${id}`, { mode: "exclusive", ifAvailable: true }, async (projectLock) => {
+        if (!projectLock)
+            throw new Error("This project is still open. Stop it before releasing its saved files.");
+        return locks.request(PACKAGES_OPEN_LOCK, { mode: "exclusive", ifAvailable: true }, async (packagesLock) => {
+            if (!packagesLock)
+                throw new Error("Another project still uses shared packages. Close its page before releasing saved files.");
+            const root = await environment.navigator.storage.getDirectory();
+            let base;
+            try {
+                base = await root.getDirectoryHandle(BASE_DIRECTORY);
+            }
+            catch (cause) {
+                if (!notFound(cause))
+                    throw cause;
+                return { project: id, removed: false, projectsRetained: 0, unitsReleased: 0, bytesReleased: 0, before: [], after: [] };
+            }
+            const ids = [];
+            let exists = false, hasPackages = false;
+            for await (const [name, handle] of base.entries()) {
+                if (handle.kind !== "directory")
+                    continue;
+                if (name === id) {
+                    exists = true;
+                    continue;
+                }
+                if (name === PACKAGES_STORE) {
+                    hasPackages = true;
+                    continue;
+                }
+                if (name === STAGING_DIRECTORY || name.startsWith(TREE_STORE_PREFIX))
+                    continue;
+                ids.push(name);
+            }
+            if (!exists)
+                throw new Error(`Saved project ${id} was not found; no files were released.`);
+            ids.sort();
+            const shared = hasPackages ? createPackStoreInternal(environment, {}, true) : undefined;
+            const referenced = new Set();
+            const before = [];
+            try {
+                if (shared)
+                    await shared.initialize(PACKAGES_STORE, { shared: true });
+                const known = new Map();
+                for (const entry of shared?.entries.values() ?? [])
+                    if (entry.type !== "directory" && entry.length > 0 && !entry.pack) {
+                        const same = known.get(entry.offset) ?? [];
+                        same.push(entry);
+                        known.set(entry.offset, same);
+                    }
+                // Read every committed index without maintenance on another project's
+                // generations. Any unreadable or partial state stops before deletion.
+                for (const [position, name] of [...ids, id].entries()) {
+                    progress?.(`Checking saved project ${position + 1} of ${ids.length + 1}`);
+                    await (await base.getDirectoryHandle(name)).getFileHandle(STATE_FILE);
+                    const store = createPackStoreInternal(environment, shared ? { packages: shared } : {}, true);
+                    try {
+                        await store.initialize(name, { readOnly: true });
+                        before.push({ project: name, entries: [...store.entries].sort(([left], [right]) => left.localeCompare(right)) });
+                        for (const entry of store.entries.values()) {
+                            if (!entry.pack || entry.length === 0)
+                                continue;
+                            if (!shared)
+                                throw new Error(`Retained project ${name} has unknown shared package references.`);
+                            if (entry.offset + entry.length > shared.packBytes || !known.get(entry.offset)?.some(source => source.type === entry.type && source.length === entry.length)) {
+                                throw new Error(`Project ${name} has an unknown shared extent ${entry.offset}+${entry.length}; all stores were retained.`);
+                            }
+                            if (name !== id)
+                                referenced.add(entry.offset);
+                        }
+                    }
+                    finally {
+                        store.close();
+                    }
+                }
+                const kept = new Set(), units = new Set(), unitBytes = new Map();
+                if (shared) {
+                    for (const [path, entry] of shared.entries) {
+                        const unit = unitOf(path);
+                        if (unit === undefined)
+                            continue;
+                        units.add(unit);
+                        unitBytes.set(unit, (unitBytes.get(unit) ?? 0) + entry.length);
+                        if (entry.type !== "directory" && entry.length > 0 && referenced.has(entry.offset))
+                            kept.add(unit);
+                    }
+                    // An empty unit costs no file bytes; its zero-length links cannot
+                    // identify a unique shared offset, so keep its metadata conservatively.
+                    for (const [unit, bytes] of unitBytes)
+                        if (bytes === 0)
+                            kept.add(unit);
+                }
+                const released = [...units].filter(unit => !kept.has(unit));
+                if (released.length) {
+                    kept.delete(".layers");
+                    kept.delete(".layers-deferred");
+                    kept.delete(".layers-local");
+                }
+                // Removing the selected store first is fail-safe: an interrupted
+                // reclamation leaves unused packages, never a project pointing at holes.
+                if (exists) {
+                    progress?.("Removing this project's saved files");
+                    await base.removeEntry(id, { recursive: true });
+                }
+                let bytesReleased = 0;
+                if (shared && released.length) {
+                    bytesReleased = released.reduce((sum, unit) => sum + (unitBytes.get(unit) ?? 0), 0);
+                    progress?.("Reclaiming packages no retained project uses");
+                    await shared.retain(path => { const unit = unitOf(path); return unit === undefined || kept.has(unit); }, { preserveOffsets: true });
+                    // All package users are excluded; every retained link still names
+                    // the same offset in the newly committed sparse generation.
+                    await shared.discardUnreferencedGenerations();
+                }
+                const after = [];
+                for (const name of ids) {
+                    const store = createPackStoreInternal(environment, shared ? { packages: shared } : {}, true);
+                    try {
+                        await store.initialize(name, { readOnly: true });
+                        after.push({ project: name, entries: [...store.entries].sort(([left], [right]) => left.localeCompare(right)) });
+                    }
+                    finally {
+                        store.close();
+                    }
+                }
+                return { project: id, removed: exists, projectsRetained: ids.length, unitsReleased: released.length, bytesReleased, before, after };
+            }
+            catch (cause) {
+                throw new Error(`Project release did not finish: ${cause instanceof Error ? cause.message : String(cause)} Other projects were retained; shared reclamation is not complete.`, { cause });
+            }
+            finally {
+                shared?.close();
+            }
+        });
+    });
+}
+/** Shared by store initialization and the origin's project-release door. */
+function validProjectId(value) {
+    if (typeof value !== "string" || !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u.test(value)) {
+        throw new Error("OPFS filesystem projectId is invalid.");
+    }
+    return value;
+}
+function notFound(cause) {
+    return cause instanceof DOMException && cause.name === "NotFoundError";
+}
 /**
  * Packages and modules no project links leave the shared store. Runs only
  * when no tab holds the store open, so no reader is under it: every
@@ -2824,7 +3081,7 @@ export async function sweepSharedPackages(environment, progress) {
             if (handle.kind === "directory" && name !== PACKAGES_STORE && name !== STAGING_DIRECTORY && !name.startsWith(TREE_STORE_PREFIX))
                 projectIds.push(name);
         }
-        const shared = createPackStore(environment);
+        const shared = createPackStoreInternal(environment, {}, true);
         if (!await shared.initialize(PACKAGES_STORE, { shared: true })) {
             shared.close();
             return undefined;
@@ -2836,7 +3093,7 @@ export async function sweepSharedPackages(environment, progress) {
                 // A sweep has no fixed length; each project opened is a sign of life
                 // for the page waiting on the worker's start.
                 progress?.(`sweeping the origin's packages, project ${index + 1} of ${projectIds.length}`);
-                const project = createPackStore(environment, { packages: shared });
+                const project = createPackStoreInternal(environment, { packages: shared }, true);
                 try {
                     const opened = await project.initialize(id);
                     if (!opened && !project.opened()) {
@@ -2844,9 +3101,9 @@ export async function sweepSharedPackages(environment, progress) {
                         continue;
                     }
                 }
-                catch {
+                catch (cause) {
                     project.close();
-                    continue;
+                    throw new Error(`Shared package references for project ${id} are unknown; stored packages were retained.`, { cause });
                 }
                 for (const entry of project.entries.values())
                     if (entry.pack && entry.length > 0)
@@ -2879,9 +3136,10 @@ export async function sweepSharedPackages(environment, progress) {
             }
             // A layers document's marker says every unit it names is here: once any
             // unit goes, none of those markers may stand (ADR-0045).
-            if ([...units].some((unit) => !kept.has(unit) && unit !== ".layers" && unit !== ".layers-deferred")) {
+            if ([...units].some((unit) => !kept.has(unit) && unit !== ".layers" && unit !== ".layers-deferred" && unit !== ".layers-local")) {
                 kept.delete(".layers");
                 kept.delete(".layers-deferred");
+                kept.delete(".layers-local");
             }
             for (const unit of units)
                 if (!kept.has(unit))
@@ -2945,7 +3203,7 @@ function unitOf(path) {
         return parts.length >= 4 ? parts.slice(0, 4).join("/") : undefined;
     // Each program's tree is its own unit: kept while a project links it or it
     // was placed lately, swept with its receipt when neither holds.
-    if (parts[0] === ".programs")
+    if (parts[0] === ".programs" || parts[0] === ".prepared" || parts[0] === ".trees")
         return parts.length >= 2 ? parts.slice(0, 2).join("/") : undefined;
     if (parts[0] === ".browser-packs") {
         if (parts[1] === "objects" && parts.length >= 3)