@ccdd/project 3.2.0 → 3.3.0

package/dist/src/workspaces/index.js

@@ -3,9 +3,12 @@ import { constants, watch } from 'node:fs';
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, symlink, unlink } from 'node:fs/promises';
 import { setTimeout as delay } from 'node:timers/promises';
 import path from 'node:path';
+// Bound open files, filesystem requests and 128 KiB hash buffers independently of tree width.
+const SCAN_CONCURRENCY = 8;
 const errorCode = (error) => error !== null && typeof error === 'object' && 'code' in error ? error.code : undefined;
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const HASH = /^[a-f0-9]{64}$/;
+const validHash = (value) => typeof value === 'string' && HASH.test(value);
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const contained = (root, candidate) => {
     const relative = path.relative(root, candidate);
@@ -43,10 +46,17 @@ export async function validateStateLocation(repoPath, stateDir) {
 function metadata(info) {
     return [info.dev, info.ino, info.mode, info.size, info.mtimeNs, info.ctimeNs, info.birthtimeNs].map(String);
 }
+/** Permit the root ctime change from publication; retain every child tuple and root identity. */
+function publicationMetadataHash(entries) {
+    const [rootPath, dev, ino, mode, size, mtime, , birthtime] = entries[0];
+    return digest(JSON.stringify([[rootPath, dev, ino, mode, size, mtime, birthtime], ...entries.slice(1)]));
+}
 /** Every entry participates: no Git, ignore rules, extension filters or implicit exclusions. */
-async function inspect(root, { signal, requireReadonly = false, contents = true, onProgress } = {}) {
+async function inspect(root, { signal, requireReadonly = false, contents = true, publicationProof = false, onProgress } = {}) {
+    const mode = requireReadonly ? 'copy' : 'lock';
     const entries = [];
     const metadataEntries = [];
+    const rootNode = { relative: '' };
     let files = 0, bytes = 0, lastProgress = 0;
     const progress = (force = false, completed = false) => {
         if (!onProgress || (!force && Date.now() - lastProgress < 1000))
@@ -55,95 +65,168 @@ async function inspect(root, { signal, requireReadonly = false, contents = true,
         onProgress({ kind: contents ? 'content' : 'metadata', files, bytes, completed });
     };
     progress(true);
-    const walk = async (relative) => {
-        signal?.throwIfAborted();
-        const absolute = relative ? path.join(root, relative) : root;
-        const before = await lstat(absolute, { bigint: true });
-        metadataEntries.push([relative, ...metadata(before)]);
-        if (requireReadonly && !before.isSymbolicLink() && (before.mode & 146n))
-            throw changed('copy', `writable cache entry ${relative || '.'}`);
-        if (before.isDirectory()) {
-            if (relative)
-                entries.push({ path: relative, type: 'directory', executable: Number(before.mode & 73n) });
-            const names = (await readdir(absolute)).sort();
-            for (const name of names)
-                await walk(relative ? `${relative}/${name}` : name);
-        }
-        else if (before.isFile() && contents) {
-            const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
-            let content;
-            try {
-                const opened = await file.stat({ bigint: true });
-                if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(opened)))
-                    throw changed('lock', relative);
-                const hash = createHash('sha256');
-                const buffer = Buffer.allocUnsafe(128 * 1024);
-                let position = 0;
-                while (true) {
-                    signal?.throwIfAborted();
-                    const { bytesRead } = await file.read(buffer, 0, buffer.length, position);
-                    if (!bytesRead)
-                        break;
-                    hash.update(buffer.subarray(0, bytesRead));
-                    position += bytesRead;
-                    bytes += bytesRead;
-                    progress();
+    await new Promise((resolve, reject) => {
+        const pending = [];
+        let next = 0, active = 0, stopped = false;
+        let firstError;
+        const check = () => { if (stopped)
+            throw firstError; signal?.throwIfAborted(); };
+        const enqueue = (task) => { if (!stopped)
+            pending.push(task); };
+        const complete = (node) => {
+            const parent = node.parent;
+            if (parent) {
+                parent.remaining = parent.remaining - 1;
+                if (!parent.remaining)
+                    enqueue(() => finishDirectory(parent));
+            }
+        };
+        const finishDirectory = async (node) => {
+            check();
+            const after = await lstat(node.relative ? path.join(root, node.relative) : root, { bigint: true });
+            if (JSON.stringify(node.metadata) !== JSON.stringify(metadata(after)))
+                throw changed(mode, node.relative || '.');
+            complete(node);
+        };
+        const walk = async (node) => {
+            check();
+            const relative = node.relative;
+            const absolute = relative ? path.join(root, relative) : root;
+            const before = await lstat(absolute, { bigint: true });
+            node.metadata = metadata(before);
+            if (requireReadonly && !before.isSymbolicLink() && (before.mode & 146n))
+                throw changed('copy', `writable cache entry ${relative || '.'}`);
+            if (before.isDirectory()) {
+                if (relative)
+                    node.entry = { path: relative, type: 'directory', executable: Number(before.mode & 73n) };
+                const names = (await readdir(absolute)).sort();
+                node.children = names.map(name => ({ relative: relative ? `${relative}/${name}` : name, parent: node }));
+                node.remaining = names.length;
+                for (const child of node.children)
+                    enqueue(() => walk(child));
+                if (!node.remaining)
+                    enqueue(() => finishDirectory(node));
+                return;
+            }
+            else if (before.isFile() && contents) {
+                const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                let content;
+                try {
+                    const opened = await file.stat({ bigint: true });
+                    if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(opened)))
+                        throw changed(mode, relative);
+                    const hash = createHash('sha256');
+                    const buffer = Buffer.allocUnsafe(128 * 1024);
+                    let position = 0;
+                    while (true) {
+                        check();
+                        const { bytesRead } = await file.read(buffer, 0, buffer.length, position);
+                        if (!bytesRead)
+                            break;
+                        hash.update(buffer.subarray(0, bytesRead));
+                        position += bytesRead;
+                        bytes += bytesRead;
+                        progress();
+                    }
+                    content = hash.digest('hex');
+                }
+                finally {
+                    await file.close();
                 }
-                content = hash.digest('hex');
+                node.entry = { path: relative, type: 'file', executable: Number(before.mode & 73n), content };
+                files++;
+                progress();
             }
-            finally {
-                await file.close();
+            else if (before.isFile()) {
+                node.entry = { path: relative, type: 'file', executable: Number(before.mode & 73n) };
+                files++;
+                progress();
             }
-            entries.push({ path: relative, type: 'file', executable: Number(before.mode & 73n), content });
-            files++;
-            progress();
-        }
-        else if (before.isFile()) {
-            entries.push({ path: relative, type: 'file', executable: Number(before.mode & 73n) });
-            files++;
-            progress();
-        }
-        else if (before.isSymbolicLink()) {
-            const target = await readlink(absolute);
-            if (path.isAbsolute(target) || !contained(root, path.resolve(path.dirname(absolute), target))) {
-                throw failure(`Workspace symlink must be relative and stay inside the workspace: ${relative}`);
+            else if (before.isSymbolicLink()) {
+                const target = await readlink(absolute);
+                if (path.isAbsolute(target) || !contained(root, path.resolve(path.dirname(absolute), target))) {
+                    throw failure(`Workspace symlink must be relative and stay inside the workspace: ${relative}`);
+                }
+                let resolved;
+                try {
+                    resolved = await realpath(absolute);
+                }
+                catch {
+                    throw failure(`Workspace symlink must resolve to an existing internal entry: ${relative}`);
+                }
+                if (!contained(root, resolved))
+                    throw failure(`Workspace symlink escapes the workspace: ${relative}`);
+                node.entry = { path: relative, type: 'symlink', target };
             }
-            let resolved;
-            try {
-                resolved = await realpath(absolute);
+            else {
+                throw failure(`Unsupported workspace entry (only directories, regular files and internal symlinks are supported): ${relative}`);
             }
-            catch {
-                throw failure(`Workspace symlink must resolve to an existing internal entry: ${relative}`);
+            const after = await lstat(absolute, { bigint: true });
+            if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(after)))
+                throw changed(mode, relative || '.');
+            complete(node);
+        };
+        const pump = () => {
+            while (!stopped && active < SCAN_CONCURRENCY && next < pending.length) {
+                const task = pending[next];
+                pending[next++] = undefined;
+                active++;
+                void task().then(() => { active--; pump(); }, error => {
+                    if (!stopped) {
+                        stopped = true;
+                        firstError = error;
+                        pending.length = 0;
+                        next = 0;
+                    }
+                    active--;
+                    pump();
+                });
             }
-            if (!contained(root, resolved))
-                throw failure(`Workspace symlink escapes the workspace: ${relative}`);
-            entries.push({ path: relative, type: 'symlink', target });
-        }
-        else {
-            throw failure(`Unsupported workspace entry (only directories, regular files and internal symlinks are supported): ${relative}`);
-        }
-        const after = await lstat(absolute, { bigint: true });
-        if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(after)))
-            throw changed('lock', relative || '.');
-    };
-    await walk('');
+            // Reject only after active readers have closed their handles in finally blocks.
+            if (!active && (stopped || next === pending.length))
+                stopped ? reject(firstError) : resolve();
+        };
+        enqueue(() => walk(rootNode));
+        pump();
+    });
+    signal?.throwIfAborted();
+    // Preserve the existing sorted depth-first wire identity, regardless of IO completion order.
+    const stack = [rootNode];
+    while (stack.length) {
+        const node = stack.pop();
+        if (node.entry)
+            entries.push(node.entry);
+        metadataEntries.push([node.relative, ...node.metadata]);
+        if (node.children)
+            for (let i = node.children.length - 1; i >= 0; i--)
+                stack.push(node.children[i]);
+    }
     progress(true, true);
-    return { hash: digest(JSON.stringify(entries)), metadataHash: digest(JSON.stringify(metadataEntries)), entries };
+    const hash = digest(JSON.stringify(entries));
+    const structureHash = contents ? digest(JSON.stringify(entries.map(entry => entry.type === 'file'
+        ? { path: entry.path, type: entry.type, executable: entry.executable } : entry))) : hash;
+    return { hash, metadataHash: digest(JSON.stringify(metadataEntries)), structureHash, entries,
+        ...(publicationProof ? { publicationMetadataHash: publicationMetadataHash(metadataEntries) } : {}) };
 }
 export async function fingerprintWorkspace(workspacePath) {
     return (await inspect(await realpath(workspacePath))).hash;
 }
-function observe(root, mode, externalSignal, onProgress) {
+function observe(root, mode, externalSignal, onProgress, integrity = 'content') {
     const controller = new AbortController();
     let closed = false;
     let watcher;
     let timer;
     let scanning;
+    let requestedGeneration = 0;
     let baseline;
     let initialized = false;
     let eventPending = false;
-    const abort = (reason) => { if (!controller.signal.aborted)
-        controller.abort(reason); };
+    const abort = (reason) => {
+        if (!controller.signal.aborted)
+            controller.abort(reason);
+        clearTimeout(timer);
+        timer = undefined;
+    };
     const externalAbort = () => abort(externalSignal?.reason);
     externalSignal?.addEventListener('abort', externalAbort, { once: true });
     if (externalSignal?.aborted)
@@ -160,88 +243,157 @@ function observe(root, mode, externalSignal, onProgress) {
         externalSignal?.removeEventListener('abort', externalAbort);
         throw failure(`Cannot monitor review workspace: ${errorMessage(error)}`);
     }
-    const check = async (contents = true) => {
-        controller.signal.throwIfAborted();
-        if (closed)
-            throw failure('Workspace handle is closed.');
-        if (scanning) {
-            await scanning;
-            // A caller asking for a full validation must not inherit a metadata-only poll.
-            if (!contents)
-                return;
-        }
-        scanning = (async () => {
-            let current;
-            do {
-                eventPending = false;
-                current = await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', contents, ...(contents ? { onProgress } : {}) });
-                if (baseline && ((contents && current.hash !== baseline.hash) || current.metadataHash !== baseline.metadataHash))
-                    throw changed(mode);
-                controller.signal.throwIfAborted();
-            } while (eventPending);
+    const check = async (contents = integrity === 'content', fresh = false) => {
+        const requested = fresh ? ++requestedGeneration : 0;
+        const assertOpen = () => {
+            controller.signal.throwIfAborted();
+            if (closed)
+                throw failure('Workspace handle is closed.');
+        };
+        while (true) {
+            assertOpen();
+            const active = scanning;
+            if (active) {
+                const current = await active.promise;
+                assertOpen();
+                // Explicit boundaries may only share a traversal that started after
+                // their request. Background polls may reuse any adequate active scan.
+                if ((!contents || active.contents) && (!fresh || active.generation >= requested))
+                    return current;
+                continue;
+            }
+            // Defer progress callbacks until this operation owns the slot, including
+            // callers that reenter from a synchronous progress callback.
+            const operation = { contents, generation: 0, promise: Promise.resolve().then(async () => {
+                    assertOpen();
+                    operation.generation = requestedGeneration;
+                    let current;
+                    do {
+                        eventPending = false;
+                        current = await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', contents, ...(contents ? { onProgress } : {}) });
+                        if (baseline && ((contents && current.hash !== baseline.hash) || current.metadataHash !== baseline.metadataHash ||
+                            (integrity === 'metadata' && current.structureHash !== baseline.structureHash)))
+                            throw changed(mode);
+                        controller.signal.throwIfAborted();
+                    } while (eventPending);
+                    return current;
+                }) };
+            scanning = operation;
+            operation.promise = operation.promise.catch((error) => {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                // An entry can disappear or stop being a directory between lstat and readdir.
+                // Once a baseline exists, these races are input mutations, not unrelated IO failures.
+                if (baseline && (errorCode(error) === 'ENOENT' || errorCode(error) === 'ENOTDIR'))
+                    error = changed(mode, errorMessage(error));
+                if (mode === 'copy' && errorCode(error) === 'WORKSPACE_CHANGED')
+                    error = changed(mode, errorMessage(error));
+                abort(error);
+                throw error;
+            }).finally(() => { if (scanning === operation)
+                scanning = undefined; });
+            const current = await operation.promise;
+            assertOpen();
             return current;
-        })().catch((error) => {
-            if (controller.signal.aborted)
-                throw controller.signal.reason;
-            // An entry can disappear or stop being a directory between lstat and readdir.
-            // Once a baseline exists, these races are input mutations, not unrelated IO failures.
-            if (baseline && (errorCode(error) === 'ENOENT' || errorCode(error) === 'ENOTDIR'))
-                error = changed(mode, errorMessage(error));
-            if (mode === 'copy' && errorCode(error) === 'WORKSPACE_CHANGED')
-                error = changed(mode, errorMessage(error));
-            abort(error);
-            throw error;
-        }).finally(() => { scanning = undefined; });
-        return scanning;
+        }
+    };
+    const scheduleMetadataPoll = (waitMs = 1000) => {
+        if (closed || controller.signal.aborted)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            const started = performance.now();
+            // Schedule only after this fallback finishes. Filesystem events still check
+            // immediately; slow trees must not accumulate interval callbacks behind IO.
+            void check(false).catch(() => { }).finally(() => {
+                scheduleMetadataPoll(Math.min(30_000, Math.max(1000, (performance.now() - started) * 10)));
+            });
+        }, waitMs);
+        timer.unref();
     };
     return {
         signal: controller.signal,
-        async initialize(expected) {
-            const before = await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', contents: false, onProgress });
-            const current = await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', onProgress });
+        async initialize(expected, publishedFrom) {
+            const before = await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', contents: false,
+                publicationProof: integrity === 'metadata' && publishedFrom !== undefined, onProgress });
+            // A staged full-content inspection may cross our own atomic rename under metadata
+            // policy only when directory identity, structure and all other metadata still match.
+            // Any unexpected difference falls back to actual bytes, as does content policy.
+            const publicationMatches = publishedFrom?.publicationMetadataHash !== undefined &&
+                publishedFrom.publicationMetadataHash === before.publicationMetadataHash && publishedFrom.structureHash === before.structureHash;
+            const current = integrity === 'metadata' && (expected || publicationMatches) ? { ...before, hash: expected?.hash ?? publishedFrom.hash }
+                : await inspect(root, { signal: controller.signal, requireReadonly: mode === 'copy', onProgress });
             if (before.metadataHash !== current.metadataHash)
                 throw changed(mode, 'input changed while acquiring the workspace');
             baseline = current;
-            if (expected && (expected.hash !== baseline.hash || expected.metadataHash !== baseline.metadataHash)) {
+            if (expected && (expected.hash !== baseline.hash || expected.metadataHash !== baseline.metadataHash ||
+                (expected.structureHash !== undefined && expected.structureHash !== baseline.structureHash))) {
                 abort(changed(mode, 'input changed since the request was prepared'));
                 controller.signal.throwIfAborted();
             }
             initialized = true;
             if (eventPending)
                 await check(false);
+            controller.signal.throwIfAborted();
             // FSEvents can deliver notifications from before watch registration. Compare ctime/inode
             // metadata rather than treating a delayed notification alone as a new mutation.
-            timer = setInterval(() => { if (!closed && !controller.signal.aborted)
-                void check(false).catch(() => { }); }, 1000);
-            timer.unref();
+            scheduleMetadataPoll();
             return baseline;
         },
-        assertUnchanged: check,
+        assertUnchanged: () => check(integrity === 'content', true),
         async close() {
-            if (closed)
-                return;
-            closed = true;
-            clearInterval(timer);
-            watcher.close();
-            externalSignal?.removeEventListener('abort', externalAbort);
-            await scanning?.catch(() => { });
+            if (!closed) {
+                closed = true;
+                clearTimeout(timer);
+                watcher.close();
+                externalSignal?.removeEventListener('abort', externalAbort);
+            }
+            // Repeated close calls drain the same owned operation. Queued callers see
+            // closed after their await and cannot restart scanning without a watcher.
+            await scanning?.promise.catch(() => { });
         },
     };
 }
 async function copyEntries(source, destination, entries, signal) {
+    // Parents must exist before copying children. Keep staging writable until every
+    // in-flight operation has settled, including when another operation fails.
     for (const entry of entries) {
+        if (entry.type !== 'directory')
+            continue;
         signal?.throwIfAborted();
-        const target = path.join(destination, entry.path);
-        if (entry.type === 'directory')
-            await mkdir(target, { mode: 0o700 });
-        else if (entry.type === 'symlink')
-            await symlink(entry.target, target);
-        else {
-            await copyFile(path.join(source, entry.path), target, constants.COPYFILE_EXCL);
-            await chmod(target, 0o444 | entry.executable);
-        }
+        await mkdir(path.join(destination, entry.path), { mode: 0o700 });
     }
+    const leaves = entries.filter(entry => entry.type !== 'directory');
+    let next = 0, failed = false;
+    let failure;
+    const copyNext = async () => {
+        while (!failed && next < leaves.length) {
+            const entry = leaves[next++];
+            try {
+                signal?.throwIfAborted();
+                const target = path.join(destination, entry.path);
+                if (entry.type === 'symlink')
+                    await symlink(entry.target, target);
+                else {
+                    await copyFile(path.join(source, entry.path), target, constants.COPYFILE_EXCL);
+                    await chmod(target, 0o444 | entry.executable);
+                }
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    };
+    // Bound filesystem pressure independently of the number of input files.
+    await Promise.all(Array.from({ length: Math.min(8, leaves.length) }, copyNext));
+    if (failed)
+        throw failure;
+    signal?.throwIfAborted();
     for (const entry of [...entries].reverse()) {
+        signal?.throwIfAborted();
         if (entry.type === 'directory')
             await chmod(path.join(destination, entry.path), 0o444 | entry.executable);
     }
@@ -318,18 +470,21 @@ export async function removeOwnedWorkspaceTree(directory) {
             throw error;
     }
 }
-export async function prepareWorkspace({ repoPath, stateDir, mode = 'copy', signal } = {}) {
+export async function prepareWorkspace({ repoPath, stateDir, mode = 'copy', integrity = 'content', signal } = {}) {
     if (!['copy', 'lock'].includes(mode))
         throw failure('Workspace mode must be copy or lock.');
+    if (!['content', 'metadata'].includes(integrity))
+        throw failure('Workspace integrity must be content or metadata.');
     const canonical = await validateStateLocation(repoPath, stateDir);
     const source = canonical.repoPath;
-    const observer = observe(source, 'lock', signal);
+    const observer = observe(source, 'lock', signal, undefined, integrity);
     let stage;
     let releasePublication;
     try {
         const initial = await observer.initialize();
         if (mode === 'lock') {
-            const descriptor = Object.freeze({ version: 1, mode, sourcePath: source, path: source, hash: initial.hash, stateDir: canonical.stateDir, baselineMetadataHash: initial.metadataHash });
+            const descriptor = Object.freeze({ version: 1, mode, sourcePath: source, path: source, hash: initial.hash, stateDir: canonical.stateDir, baselineMetadataHash: initial.metadataHash,
+                ...(integrity === 'metadata' ? { integrity, structureHash: initial.structureHash } : {}) });
             return { descriptor, signal: observer.signal, assertUnchanged: observer.assertUnchanged, close: observer.close };
         }
         const cacheRoot = path.join(canonical.stateDir, 'workspaces');
@@ -338,42 +493,63 @@ export async function prepareWorkspace({ repoPath, stateDir, mode = 'copy', sign
             throw failure('Workspace cache directory must not be a symlink.');
         const destination = path.join(cacheRoot, initial.hash);
         releasePublication = await acquirePublication(cacheRoot, initial.hash, observer.signal);
-        let cached;
+        let cached = false;
+        let publishedFrom;
         try {
             if (!(await lstat(destination)).isDirectory())
                 throw changed('copy', 'cache root must be a regular directory');
-            cached = await inspect(destination, { signal, requireReadonly: true });
+            cached = true;
         }
         catch (error) {
             if (errorCode(error) !== 'ENOENT')
                 throw error;
         }
-        if (cached && cached.hash !== initial.hash)
-            throw changed('copy', 'cached content does not match its hash');
         if (!cached) {
             stage = path.join(cacheRoot, `.capture-${randomUUID()}`);
             await mkdir(stage, { mode: 0o700 });
             await copyEntries(source, stage, initial.entries, observer.signal);
-            const copied = await inspect(stage, { signal: observer.signal, requireReadonly: true });
+            const copied = await inspect(stage, { signal: observer.signal, requireReadonly: true, publicationProof: integrity === 'metadata' });
             if (copied.hash !== initial.hash)
                 throw changed('lock', 'source changed during copy');
+            publishedFrom = copied;
             await observer.assertUnchanged();
             await rename(stage, destination);
             stage = undefined;
         }
-        await observer.assertUnchanged();
+        else {
+            // Cache reuse still validates the source whose identity selected this copy.
+            await observer.assertUnchanged();
+        }
+        // A new copy was already checked against stable source immediately before
+        // publication. No source bytes are consumed after that capture boundary.
+        observer.signal.throwIfAborted();
         await observer.close();
+        observer.signal.throwIfAborted();
         if (stage) {
             await removeOwnedWorkspaceTree(stage);
             stage = undefined;
         }
         await releasePublication();
         releasePublication = undefined;
-        const verified = await inspect(destination, { signal, requireReadonly: true });
-        if (verified.hash !== initial.hash)
-            throw changed('copy', 'cached content does not match its hash');
-        const descriptor = Object.freeze({ version: 1, mode, sourcePath: source, path: destination, hash: initial.hash, stateDir: canonical.stateDir, baselineMetadataHash: verified.metadataHash });
-        return await reopenWorkspace(descriptor, { signal });
+        // Cache hits have no staged proof and receive a full byte validation here under
+        // either policy. This same live observer owns every subsequent boundary.
+        if (await realpath(destination) !== destination || !(await lstat(destination)).isDirectory()) {
+            throw failure('Persisted workspace descriptor has an invalid input path.');
+        }
+        const copyObserver = observe(destination, 'copy', signal, undefined, integrity);
+        try {
+            const verified = await copyObserver.initialize(undefined, publishedFrom);
+            if (verified.hash !== initial.hash)
+                throw changed('copy', 'cached content does not match its hash');
+            copyObserver.signal.throwIfAborted();
+            const descriptor = Object.freeze({ version: 1, mode, sourcePath: source, path: destination, hash: initial.hash, stateDir: canonical.stateDir, baselineMetadataHash: verified.metadataHash,
+                ...(integrity === 'metadata' ? { integrity, structureHash: verified.structureHash } : {}) });
+            return { descriptor, signal: copyObserver.signal, assertUnchanged: copyObserver.assertUnchanged, close: copyObserver.close };
+        }
+        catch (error) {
+            await copyObserver.close();
+            throw error;
+        }
     }
     catch (error) {
         await observer.close();
@@ -383,12 +559,20 @@ export async function prepareWorkspace({ repoPath, stateDir, mode = 'copy', sign
         throw error;
     }
 }
-export async function reopenWorkspace(descriptor, { signal, onProgress } = {}) {
+export async function reopenWorkspace(descriptor, { signal, onProgress, integrity } = {}) {
     if (!descriptor || descriptor.version !== 1 || !['copy', 'lock'].includes(descriptor.mode) ||
-        !HASH.test(descriptor.hash ?? '') || !HASH.test(descriptor.baselineMetadataHash ?? '') ||
+        !validHash(descriptor.hash) || !validHash(descriptor.baselineMetadataHash) ||
+        (descriptor.integrity !== undefined && !['content', 'metadata'].includes(descriptor.integrity)) ||
+        (descriptor.structureHash !== undefined && !validHash(descriptor.structureHash)) ||
+        (descriptor.integrity === 'metadata' && !validHash(descriptor.structureHash)) ||
         ['sourcePath', 'path', 'stateDir'].some(key => typeof descriptor[key] !== 'string' || !path.isAbsolute(descriptor[key]))) {
         throw failure('Invalid persisted workspace descriptor.');
     }
+    if (integrity !== undefined && !['content', 'metadata'].includes(integrity))
+        throw failure('Workspace integrity must be content or metadata.');
+    if (integrity === 'metadata' && descriptor.integrity !== 'metadata')
+        throw failure('Metadata integrity requires an explicitly captured metadata-policy descriptor.');
+    const effectiveIntegrity = integrity ?? descriptor.integrity ?? 'content';
     const { mode, sourcePath, stateDir } = descriptor;
     if (contained(sourcePath, stateDir))
         throw failure('Persisted stateDir must be outside the source workspace.');
@@ -396,10 +580,10 @@ export async function reopenWorkspace(descriptor, { signal, onProgress } = {}) {
     if (descriptor.path !== expectedPath || await realpath(descriptor.path) !== expectedPath || !(await lstat(expectedPath)).isDirectory()) {
         throw failure('Persisted workspace descriptor has an invalid input path.');
     }
-    const observer = observe(expectedPath, mode, signal, onProgress);
+    const observer = observe(expectedPath, mode, signal, onProgress, effectiveIntegrity);
     try {
-        await observer.initialize({ hash: descriptor.hash, metadataHash: descriptor.baselineMetadataHash });
-        return { descriptor: Object.freeze({ ...descriptor }), signal: observer.signal, assertUnchanged: observer.assertUnchanged, close: observer.close };
+        await observer.initialize({ hash: descriptor.hash, metadataHash: descriptor.baselineMetadataHash, structureHash: descriptor.structureHash });
+        return { descriptor: Object.freeze({ ...descriptor, ...(integrity !== undefined ? { integrity } : {}) }), signal: observer.signal, assertUnchanged: observer.assertUnchanged, close: observer.close };
     }
     catch (error) {
         await observer.close();