akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/core/time.js

@@ -21,23 +21,20 @@ const MONTH_MS = 30 * DAY_MS;
  *
  * The grammar is intentionally uniform across the whole CLI:
  *   - `m` = MINUTES, `M` = MONTHS (30-day approximation)
- *   - `h`/`H` = hours, `d`/`D` = days
+ *   - `h` = hours, `d` = days
  *
  * Matching is CASE-SENSITIVE (see {@link parseDuration}), which is what lets
  * `m` and `M` mean different things. Historically `akm health --since` and
  * `remember --expires` read a case-insensitive `m` as MONTHS while
  * `consolidate` / `--window-compare` read it as MINUTES; that split is now
  * resolved in favour of the conventional `m`=minutes, with `M` reserved for
- * months. Upper-case `H`/`D` aliases are retained so specs that previously
- * relied on the old case-insensitive parsers (e.g. `"7D"`) keep working.
+ * months.
  */
 export const DURATION_UNITS = {
     m: MINUTE_MS,
     M: MONTH_MS,
     h: HOUR_MS,
-    H: HOUR_MS,
     d: DAY_MS,
-    D: DAY_MS,
 };
 /**
  * Parse a compact duration shorthand (e.g. `"30d"`, `"12h"`, `"5m"`, `"3M"`)
@@ -118,10 +115,3 @@ export function parseSinceToIsoLenient(since) {
         return since;
     return new Date(Date.now() - ms).toISOString();
 }
-/**
- * Convert an ISO-8601 timestamp string to the SQLite datetime format
- * `"YYYY-MM-DD HH:MM:SS"` used by `datetime('now')`.
- */
-export function isoToSqlite(iso) {
-    return iso.replace("T", " ").replace(/\.\d+Z$/, "");
-}

package/dist/core/write-source.js

@@ -893,24 +893,6 @@ export function prepareWriteTargetForMutation(target, options = {}) {
 function gitTargetNotMaterialized(target, contentRoot) {
     return new ConfigError(`Writable Git target "${target.source.name}" is not materialized as a Git checkout at ${contentRoot}; refusing to write without a commit boundary.`, "INVALID_CONFIG_FILE", `Run \`akm bundle update ${target.source.name}\` to materialize it, or point the bundle at a writable Git checkout.`);
 }
-/** Enumerate enabled writable targets, deduplicated by materialized content root. */
-export function resolveWritableTargets(akmConfig) {
-    const byRoot = new Map();
-    for (const runtime of resolveConfiguredSources(akmConfig)) {
-        if (runtime.enabled === false || !resolveWritable({ type: runtime.type, writable: runtime.writable }))
-            continue;
-        const target = adaptConfiguredSource(runtime);
-        const root = path.resolve(target.source.path);
-        const existing = byRoot.get(root);
-        if (!existing || target.source.name === akmConfig.defaultWriteTarget)
-            byRoot.set(root, target);
-    }
-    if (process.env.AKM_BUNDLE_DIR?.trim()) {
-        const target = resolveWorkingStashTarget(akmConfig);
-        byRoot.set(path.resolve(target.source.path), target);
-    }
-    return [...byRoot.values()];
-}
 /**
  * Resolve the destination for a write per locked decision 3:
  *

package/dist/execution/directory-identity.js

@@ -0,0 +1,52 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../core/errors.js";
+export function captureFrozenDirectoryIdentity(rootInput, relativeCwd) {
+    const requestedRoot = path.resolve(rootInput);
+    const requestedCwd = path.resolve(requestedRoot, relativeCwd ?? ".");
+    requireContained(requestedRoot, requestedCwd);
+    const realRoot = fs.realpathSync(requestedRoot);
+    const realCwd = fs.realpathSync(requestedCwd);
+    requireContained(realRoot, realCwd);
+    const rootStat = fs.statSync(realRoot, { bigint: true });
+    const cwdStat = fs.statSync(realCwd, { bigint: true });
+    if (!rootStat.isDirectory() || !cwdStat.isDirectory()) {
+        throw new UsageError("Execution root and cwd must both be directories.", "INVALID_FLAG_VALUE");
+    }
+    return Object.freeze({
+        requestedRoot,
+        realRoot,
+        rootDevice: rootStat.dev.toString(),
+        rootInode: rootStat.ino.toString(),
+        requestedCwd,
+        realCwd,
+        cwdDevice: cwdStat.dev.toString(),
+        cwdInode: cwdStat.ino.toString(),
+    });
+}
+export function assertFrozenDirectoryIdentity(identity) {
+    let actual;
+    try {
+        const relative = path.relative(identity.requestedRoot, identity.requestedCwd);
+        actual = captureFrozenDirectoryIdentity(identity.requestedRoot, relative);
+    }
+    catch {
+        throw changed(identity.requestedCwd);
+    }
+    for (const key of ["realRoot", "rootDevice", "rootInode", "realCwd", "cwdDevice", "cwdInode"]) {
+        if (actual[key] !== identity[key])
+            throw changed(identity.requestedCwd);
+    }
+}
+function requireContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new UsageError(`${candidate} escapes its execution root.`, "PATH_ESCAPE_VIOLATION");
+    }
+}
+function changed(cwd) {
+    return new UsageError(`Frozen execution cwd ${cwd} changed after publication.`, "RESOURCE_ALREADY_EXISTS");
+}

package/dist/execution/executable-identity.js

@@ -0,0 +1,107 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../core/errors.js";
+export function freezeExecutableIdentity(requested, options = {}) {
+    const absolutePath = resolveExecutable(requested, options.cwd ?? process.cwd(), options.path ?? process.env.PATH ?? "");
+    let realPath;
+    let stat;
+    let bytes;
+    try {
+        fs.accessSync(absolutePath, fs.constants.X_OK);
+        realPath = fs.realpathSync(absolutePath);
+        stat = fs.lstatSync(realPath, { bigint: true });
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("not a regular executable file");
+        bytes = fs.readFileSync(realPath);
+    }
+    catch {
+        throw new UsageError(`Executable ${JSON.stringify(requested)} could not be frozen.`, "INVALID_FLAG_VALUE");
+    }
+    return Object.freeze({
+        requested,
+        absolutePath,
+        realPath,
+        device: stat.dev.toString(),
+        inode: stat.ino.toString(),
+        size: bytes.byteLength,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+}
+export function decodeFrozenExecutableIdentity(value, label = "executable") {
+    if (!isRecord(value))
+        throw invalid(label);
+    const allowed = new Set(["requested", "absolutePath", "realPath", "device", "inode", "size", "sha256"]);
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw invalid(label);
+    if (typeof value.requested !== "string" ||
+        typeof value.absolutePath !== "string" ||
+        !path.isAbsolute(value.absolutePath) ||
+        typeof value.realPath !== "string" ||
+        !path.isAbsolute(value.realPath) ||
+        typeof value.device !== "string" ||
+        typeof value.inode !== "string" ||
+        !Number.isSafeInteger(value.size) ||
+        value.size < 0 ||
+        typeof value.sha256 !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.sha256)) {
+        throw invalid(label);
+    }
+    const decoded = Object.freeze({
+        requested: value.requested,
+        absolutePath: value.absolutePath,
+        realPath: value.realPath,
+        device: value.device,
+        inode: value.inode,
+        size: value.size,
+        sha256: value.sha256,
+    });
+    assertFrozenExecutableIdentity(decoded, label);
+    return decoded;
+}
+export function assertFrozenExecutableIdentity(identity, label = "executable") {
+    let actual;
+    try {
+        actual = freezeExecutableIdentity(identity.absolutePath, { cwd: path.dirname(identity.absolutePath) });
+    }
+    catch {
+        throw changed(label);
+    }
+    for (const key of ["absolutePath", "realPath", "device", "inode", "size", "sha256"]) {
+        if (actual[key] !== identity[key])
+            throw changed(label);
+    }
+}
+function resolveExecutable(requested, cwd, pathValue) {
+    if (requested.includes("/") || requested.includes("\\"))
+        return path.resolve(cwd, requested);
+    const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+    for (const directory of pathValue.split(path.delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = path.resolve(directory, `${requested}${extension}`);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // Continue through the frozen search path.
+            }
+        }
+    }
+    throw new UsageError(`Executable ${JSON.stringify(requested)} was not found.`, "INVALID_FLAG_VALUE");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalid(label) {
+    return new UsageError(`Frozen ${label} identity is invalid.`, "INVALID_FLAG_VALUE");
+}
+function changed(label) {
+    return new UsageError(`Frozen ${label} changed after publication.`, "RESOURCE_ALREADY_EXISTS");
+}

package/dist/execution/guarded-source.js

@@ -0,0 +1,398 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../core/asset/frontmatter.js";
+import { UsageError } from "../core/errors.js";
+import { createExecutionSourceIdentity } from "./source.js";
+export const DEFAULT_GUARDED_SOURCE_MAX_BYTES = 1024 * 1024;
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function toPosix(value) {
+    return value.replaceAll("\\", "/");
+}
+function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function physicalIdentity(realPath, stat) {
+    return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
+}
+function statVersion(stat) {
+    return `${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+function sameBigIntStat(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function containedRelative(root, candidate, allowRoot) {
+    const relative = path.relative(root, candidate);
+    if ((!allowRoot && relative === "") || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new UsageError(`${candidate} resolves outside its guarded containment root.`, "PATH_ESCAPE_VIOLATION");
+    }
+    return relative;
+}
+function requireContainmentRoot(containmentRootInput) {
+    const containmentRoot = path.resolve(containmentRootInput);
+    const containmentRealPath = fs.realpathSync(containmentRoot);
+    const containmentStat = fs.statSync(containmentRealPath, { bigint: true });
+    if (!containmentStat.isDirectory()) {
+        throw new UsageError(`${containmentRootInput} is not a guarded source directory.`, "INVALID_FLAG_VALUE");
+    }
+    return { containmentRoot, containmentRealPath, containmentStat };
+}
+function numberStat(stat) {
+    return new Proxy(stat, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "bigint" ? Number(value) : value;
+        },
+    });
+}
+function decodeUtf8(bytes, sourcePath) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new UsageError(`${sourcePath} contains invalid UTF-8 bytes.`, "INVALID_FLAG_VALUE");
+    }
+}
+function freezeSource(source) {
+    const identity = source.identity ? createExecutionSourceIdentity(source.identity) : undefined;
+    return Object.freeze({ ...source, ...(identity ? { identity } : {}) });
+}
+function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
+    const sourcePath = path.resolve(sourcePathInput);
+    const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
+    const lexicalRelative = containedRelative(containmentRoot, sourcePath, false);
+    const maxBytes = options.maxBytes ?? DEFAULT_GUARDED_SOURCE_MAX_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new UsageError("Guarded source byte limit must be a non-negative safe integer.", "INVALID_FLAG_VALUE");
+    }
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(sourcePath, fs.constants.O_RDONLY | noFollow);
+        const before = fs.fstatSync(descriptor, { bigint: true });
+        if (!before.isFile()) {
+            throw new UsageError(`${sourcePath} is not a regular guarded source file.`, "INVALID_FLAG_VALUE");
+        }
+        if (before.size > BigInt(maxBytes)) {
+            throw new UsageError(`${sourcePath} exceeds the guarded source size limit (1 MiB; ${maxBytes} bytes).`, "INVALID_FLAG_VALUE");
+        }
+        const bytes = fs.readFileSync(descriptor);
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameBigIntStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
+            throw new UsageError(`${sourcePath} changed while its guarded bytes were read.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const pathnameStat = fs.lstatSync(sourcePath, { bigint: true });
+        if (pathnameStat.isSymbolicLink()) {
+            throw new UsageError(`${sourcePath} is a symbolic source; guarded reads require a regular no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        if (!pathnameStat.isFile() || pathnameStat.dev !== before.dev || pathnameStat.ino !== before.ino) {
+            throw new UsageError(`${sourcePath} changed physical identity during its guarded read.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const realPath = fs.realpathSync(sourcePath);
+        containedRelative(containmentRealPath, realPath, false);
+        const content = decodeUtf8(bytes, sourcePath);
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        if (options.identity && options.identity.hash !== sha256) {
+            throw new UsageError(`${sourcePath} adapter identity hash does not match its guarded bytes.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        if (options.identity && options.identity.file !== toPosix(lexicalRelative)) {
+            throw new UsageError(`${sourcePath} adapter identity file does not match its guarded relative path.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        return {
+            source: freezeSource({
+                sourcePath,
+                relativePath: toPosix(lexicalRelative),
+                realPath,
+                containmentRoot,
+                containmentRealPath,
+                containmentPhysicalIdentity: physicalIdentity(containmentRealPath, containmentStat),
+                physicalIdentity: physicalIdentity(realPath, before),
+                size: bytes.byteLength,
+                mtimeNs: String(before.mtimeNs),
+                ctimeNs: String(before.ctimeNs),
+                sha256,
+                bytesBase64: bytes.toString("base64"),
+                content,
+                authored: options.authored ?? false,
+                ...(options.identity ? { identity: options.identity } : {}),
+            }),
+            stat: numberStat(before),
+            maxBytes,
+        };
+    }
+    catch (cause) {
+        if (cause instanceof UsageError)
+            throw cause;
+        const code = cause.code;
+        if (code === "ELOOP") {
+            let linked;
+            try {
+                linked = fs.realpathSync(sourcePath);
+            }
+            catch {
+                // The no-follow failure itself is sufficient when the link is broken.
+            }
+            if (linked) {
+                const relative = path.relative(containmentRealPath, linked);
+                if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                    throw new UsageError(`${sourcePath} resolves outside its containment root through a symbolic source.`, "PATH_ESCAPE_VIOLATION");
+                }
+            }
+            throw new UsageError(`${sourcePath} is a symbolic source; guarded reads require a regular no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        throw new UsageError(`${sourcePath} could not be guarded as a contained regular source: ${errorMessage(cause)}`, code === "ENOENT" ? "RESOURCE_ALREADY_EXISTS" : "PATH_ESCAPE_VIOLATION");
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+export function captureGuardedExecutionSource(sourcePath, containmentRoot, options = {}) {
+    return captureRecord(sourcePath, containmentRoot, options).source;
+}
+export function captureGuardedDirectoryManifest(directoryPathInput, containmentRootInput) {
+    const directoryPath = path.resolve(directoryPathInput);
+    const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
+    const lexicalRelative = containedRelative(containmentRoot, directoryPath, true);
+    try {
+        const before = fs.lstatSync(directoryPath, { bigint: true });
+        if (before.isSymbolicLink()) {
+            throw new UsageError(`${directoryPath} is a symbolic directory with ambiguous guarded identity.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        if (!before.isDirectory()) {
+            throw new UsageError(`${directoryPath} is not a guarded directory.`, "INVALID_FLAG_VALUE");
+        }
+        const realPath = fs.realpathSync(directoryPath);
+        containedRelative(containmentRealPath, realPath, true);
+        const entries = fs
+            .readdirSync(directoryPath, { withFileTypes: true })
+            .sort((left, right) => compareCodePoints(left.name, right.name))
+            .map((entry) => {
+            const entryPath = path.join(directoryPath, entry.name);
+            const entryStat = fs.lstatSync(entryPath, { bigint: true });
+            if (entry.isSymbolicLink() || entryStat.isSymbolicLink()) {
+                let linked;
+                try {
+                    linked = fs.realpathSync(entryPath);
+                }
+                catch {
+                    // Broken symbolic entries still have ambiguous ownership.
+                }
+                if (linked) {
+                    const relative = path.relative(containmentRealPath, linked);
+                    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                        throw new UsageError(`${entryPath} resolves outside the bundle root through a symbolic source.`, "PATH_ESCAPE_VIOLATION");
+                    }
+                }
+                throw new UsageError(`${entryPath} is a symbolic source with a physical source identity collision; guarded reads require one no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
+            }
+            const kind = entry.isDirectory() && entryStat.isDirectory()
+                ? "directory"
+                : entry.isFile() && entryStat.isFile()
+                    ? "file"
+                    : undefined;
+            if (!kind) {
+                throw new UsageError(`${entryPath} is neither a regular file nor directory.`, "INVALID_FLAG_VALUE");
+            }
+            const entryRealPath = fs.realpathSync(entryPath);
+            containedRelative(containmentRealPath, entryRealPath, false);
+            return Object.freeze({
+                name: entry.name,
+                kind,
+                physicalIdentity: physicalIdentity(entryRealPath, entryStat),
+                version: statVersion(entryStat),
+            });
+        });
+        const after = fs.lstatSync(directoryPath, { bigint: true });
+        if (!sameBigIntStat(before, after)) {
+            throw new UsageError(`${directoryPath} changed while its guarded directory manifest was read.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        return Object.freeze({
+            directoryPath,
+            relativePath: lexicalRelative === "" ? "." : toPosix(lexicalRelative),
+            realPath,
+            containmentRoot,
+            containmentRealPath,
+            containmentPhysicalIdentity: physicalIdentity(containmentRealPath, containmentStat),
+            physicalIdentity: physicalIdentity(realPath, before),
+            version: statVersion(before),
+            entries: Object.freeze(entries),
+        });
+    }
+    catch (cause) {
+        if (cause instanceof UsageError)
+            throw cause;
+        throw new UsageError(`${directoryPath} could not be captured as a guarded directory manifest: ${errorMessage(cause)}`, cause.code === "ENOENT" ? "RESOURCE_ALREADY_EXISTS" : "PATH_ESCAPE_VIOLATION");
+    }
+}
+function sameSnapshotValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function sourceSortKey(source) {
+    const identity = source.identity;
+    return identity
+        ? `${identity.ref}\0${identity.adapter}\0${identity.file}`
+        : `${source.containmentRealPath}\0${source.relativePath}`;
+}
+function directorySortKey(manifest) {
+    return `${manifest.containmentRealPath}\0${manifest.relativePath}`;
+}
+export class GuardedExecutionSourceCollector {
+    #sources = new Map();
+    #directories = new Map();
+    capture(sourcePath, containmentRoot, options = {}) {
+        const key = path.resolve(sourcePath);
+        const existing = this.#sources.get(key);
+        if (existing) {
+            if (options.identity)
+                return this.bindIdentity(sourcePath, containmentRoot, options.identity);
+            return existing.source;
+        }
+        const record = captureRecord(sourcePath, containmentRoot, options);
+        this.#assertNoPhysicalOwnerAlias(record.source);
+        this.#sources.set(key, record);
+        return record.source;
+    }
+    readBytes(sourcePath, containmentRoot, options = {}) {
+        return Buffer.from(this.capture(sourcePath, containmentRoot, options).bytesBase64, "base64");
+    }
+    fileContext(root, file, options = {}) {
+        const source = this.capture(file, root, options);
+        const record = this.#sources.get(path.resolve(file));
+        if (!record)
+            throw new Error("guarded source collector lost a captured file");
+        const relPath = source.relativePath;
+        const ext = path.extname(file).toLowerCase();
+        const fileName = path.basename(file);
+        const parentDirAbs = path.dirname(path.resolve(file));
+        const relDir = path.posix.dirname(relPath);
+        const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter(Boolean);
+        let frontmatter;
+        let parsed = false;
+        return {
+            absPath: path.resolve(file),
+            relPath,
+            ext,
+            fileName,
+            parentDir: path.basename(parentDirAbs),
+            parentDirAbs,
+            ancestorDirs,
+            stashRoot: path.resolve(root),
+            content: () => source.content,
+            frontmatter: () => {
+                if (!parsed) {
+                    const result = parseFrontmatter(source.content);
+                    frontmatter = Object.keys(result.data).length > 0 ? result.data : null;
+                    parsed = true;
+                }
+                return frontmatter ?? null;
+            },
+            stat: () => record.stat,
+        };
+    }
+    bindIdentity(sourcePath, containmentRoot, identityInput) {
+        const key = path.resolve(sourcePath);
+        const existing = this.#sources.get(key) ?? captureRecord(sourcePath, containmentRoot);
+        const identity = createExecutionSourceIdentity(identityInput);
+        if (identity.file !== existing.source.relativePath || identity.hash !== existing.source.sha256) {
+            throw new UsageError(`${sourcePath} adapter identity does not match its guarded file owner or bytes.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        if (existing.source.identity) {
+            if (!sameSnapshotValue(existing.source.identity, identity)) {
+                throw new UsageError(`${sourcePath} already has a different guarded logical owner identity.`, "RESOURCE_ALREADY_EXISTS");
+            }
+            return existing.source;
+        }
+        const source = freezeSource({ ...existing.source, identity });
+        this.#assertNoPhysicalOwnerAlias(source, key);
+        this.#sources.set(key, { ...existing, source });
+        return source;
+    }
+    trackDirectory(directoryPath, containmentRoot) {
+        const manifest = captureGuardedDirectoryManifest(directoryPath, containmentRoot);
+        const key = path.resolve(directoryPath);
+        const existing = this.#directories.get(key);
+        if (existing && !sameSnapshotValue(existing, manifest)) {
+            throw new UsageError(`${directoryPath} changed between guarded directory reads.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        if (!existing)
+            this.#directories.set(key, manifest);
+        return existing ?? manifest;
+    }
+    enumerateTree(directoryPath, containmentRoot) {
+        const files = [];
+        const visit = (directory) => {
+            const manifest = this.trackDirectory(directory, containmentRoot);
+            for (const entry of manifest.entries) {
+                const candidate = path.join(directory, entry.name);
+                if (entry.kind === "directory")
+                    visit(candidate);
+                else
+                    files.push(candidate);
+            }
+        };
+        visit(path.resolve(directoryPath));
+        return Object.freeze(files.sort(compareCodePoints));
+    }
+    snapshot() {
+        return Object.freeze({
+            sources: Object.freeze([...this.#sources.values()]
+                .map((record) => record.source)
+                .sort((left, right) => compareCodePoints(sourceSortKey(left), sourceSortKey(right)))),
+            directoryManifests: Object.freeze([...this.#directories.values()].sort((left, right) => compareCodePoints(directorySortKey(left), directorySortKey(right)))),
+        });
+    }
+    revalidate() {
+        for (const record of this.#sources.values()) {
+            let current;
+            try {
+                current = captureRecord(record.source.sourcePath, record.source.containmentRoot, {
+                    authored: record.source.authored,
+                    maxBytes: record.maxBytes,
+                    ...(record.source.identity ? { identity: record.source.identity } : {}),
+                }).source;
+            }
+            catch (cause) {
+                throw new UsageError(`Guarded execution source read set changed before publication: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
+            }
+            if (!sameSnapshotValue(record.source, current)) {
+                throw new UsageError("Guarded execution source read set changed before publication.", "RESOURCE_ALREADY_EXISTS");
+            }
+        }
+        for (const manifest of this.#directories.values()) {
+            let current;
+            try {
+                current = captureGuardedDirectoryManifest(manifest.directoryPath, manifest.containmentRoot);
+            }
+            catch (cause) {
+                throw new UsageError(`Guarded execution source directory manifest changed before publication: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
+            }
+            if (!sameSnapshotValue(manifest, current)) {
+                throw new UsageError("Guarded execution source directory manifest changed before publication.", "RESOURCE_ALREADY_EXISTS");
+            }
+        }
+    }
+    #assertNoPhysicalOwnerAlias(candidate, selfKey) {
+        if (!candidate.identity)
+            return;
+        for (const [key, record] of this.#sources) {
+            if (key === selfKey || !record.source.identity)
+                continue;
+            if (record.source.containmentPhysicalIdentity === candidate.containmentPhysicalIdentity &&
+                record.source.physicalIdentity === candidate.physicalIdentity &&
+                !sameSnapshotValue(record.source.identity, candidate.identity)) {
+                throw new UsageError(`${candidate.sourcePath} aliases the same physical source and root under a different logical owner.`, "RESOURCE_ALREADY_EXISTS");
+            }
+        }
+    }
+}