mdkg 0.4.1 → 0.5.0

package/dist/commands/work.js

@@ -13,10 +13,10 @@ exports.runWorkReceiptUpdateCommand = runWorkReceiptUpdateCommand;
 exports.runWorkReceiptVerifyCommand = runWorkReceiptVerifyCommand;
 exports.runWorkValidateCommand = runWorkValidateCommand;
 exports.runWorkArtifactAddCommand = runWorkArtifactAddCommand;
-const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
 const config_1 = require("../core/config");
+const filesystem_authority_1 = require("../core/filesystem_authority");
 const frontmatter_1 = require("../graph/frontmatter");
 const indexer_1 = require("../graph/indexer");
 const index_cache_1 = require("../graph/index_cache");
@@ -28,7 +28,6 @@ const errors_1 = require("../util/errors");
 const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
 const qid_1 = require("../util/qid");
-const atomic_1 = require("../util/atomic");
 const lock_1 = require("../util/lock");
 const event_support_1 = require("./event_support");
 const archive_1 = require("./archive");
@@ -323,7 +322,12 @@ function filterWorkflowMessages(messages, nodes, candidatePaths) {
 function buildWorkValidateReceipt(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
-    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config, tolerant: true });
+    const { index } = (0, index_cache_1.loadIndex)({
+        root: options.root,
+        config,
+        tolerant: true,
+        persistReindex: false,
+    });
     const type = normalizeWorkflowValidateType(options.type);
     let targets;
     let target;
@@ -636,10 +640,10 @@ function resolveTypedReadableNode(index, ws, idOrQid, type) {
     const node = index.nodes[resolved.qid];
     return node?.type === type ? node : undefined;
 }
-function writeFrontmatterFile(filePath, frontmatter, body) {
+function writeFrontmatterFile(root, filePath, frontmatter, body) {
     const lines = (0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER);
     const content = ["---", ...lines, "---", body.trimStart()].join("\n");
-    (0, atomic_1.atomicWriteFile)(filePath, content.endsWith("\n") ? content : `${content}\n`);
+    (0, filesystem_authority_1.atomicReplaceContainedFile)({ root, relativePath: path_1.default.relative(root, filePath).split(path_1.default.sep).join("/") }, content.endsWith("\n") ? content : `${content}\n`);
 }
 function mergeRenderedFrontmatter(content, filePath, additions) {
     const entries = Object.entries(additions).filter((entry) => entry[1] !== undefined);
@@ -679,8 +683,9 @@ function createAgentWorkflowNode(options) {
         ...options.overrides,
     });
     const content = mergeRenderedFrontmatter(renderedContent, filePath, options.overrides);
+    const relativeFilePath = path_1.default.relative(options.root, filePath).split(path_1.default.sep).join("/");
     try {
-        (0, atomic_1.writeFileExclusive)(filePath, content);
+        (0, filesystem_authority_1.writeContainedFileExclusive)({ root: options.root, relativePath: relativeFilePath }, content);
     }
     catch (err) {
         const code = typeof err === "object" && err !== null && "code" in err ? String(err.code) : "";
@@ -689,16 +694,28 @@ function createAgentWorkflowNode(options) {
         }
         throw err;
     }
-    maybeReindex(options.root, config);
-    (0, event_support_1.appendAutomaticEvent)({
-        root: options.root,
-        ws,
-        kind: "WORK_NODE_CREATED",
-        status: "ok",
-        refs: [id],
-        notes: `${options.type} semantic mirror created via mdkg work`,
-        now: options.now,
-    });
+    try {
+        maybeReindex(options.root, config);
+        (0, event_support_1.appendAutomaticEvent)({
+            root: options.root,
+            ws,
+            kind: "WORK_NODE_CREATED",
+            status: "ok",
+            refs: [id],
+            notes: `${options.type} semantic mirror created via mdkg work`,
+            now: options.now,
+        });
+    }
+    catch (error) {
+        (0, filesystem_authority_1.removeContainedPath)({ root: options.root, relativePath: relativeFilePath, force: true });
+        try {
+            maybeReindex(options.root, config);
+        }
+        catch {
+            // Canonical state is rolled back; a later explicit index rebuild repairs derived caches.
+        }
+        throw error;
+    }
     return {
         workspace: ws,
         id,
@@ -728,7 +745,7 @@ function loadMutableAgentNode(root, idOrQid, wsRaw, type) {
     const { index } = (0, index_cache_1.loadIndex)({ root, config });
     const node = resolveWorkNode(index, idOrQid, ws, new Set([type]), type);
     const filePath = path_1.default.resolve(root, node.path);
-    const parsed = (0, frontmatter_1.parseFrontmatter)(fs_1.default.readFileSync(filePath, "utf8"), filePath);
+    const parsed = (0, frontmatter_1.parseFrontmatter)((0, filesystem_authority_1.readContainedFile)({ root, relativePath: node.path }), filePath);
     return { config, node, filePath, frontmatter: { ...parsed.frontmatter }, body: parsed.body };
 }
 function printReceipt(action, receipt, json) {
@@ -857,9 +874,10 @@ function runWorkTriggerCommandLocked(options) {
     const requester = options.requester ?? "user.local";
     const requestRef = "request.redacted";
     const triggerRef = "trigger.mdkg-work-trigger";
+    const workRef = workNode.source?.imported ? workNode.qid : workNode.id;
     const requestedOutputs = toStringList(workNode.attributes.outputs);
     const payloadHash = buildWorkOrderPayloadHash({
-        workId: workNode.id,
+        workId: workRef,
         workVersion: String(workNode.attributes.version ?? "0.1.0"),
         requester,
         requestRef,
@@ -881,7 +899,7 @@ function runWorkTriggerCommandLocked(options) {
         ws,
         title,
         id,
-        workId: workNode.id,
+        workId: workRef,
         workNode,
         requester,
         requestRef,
@@ -896,7 +914,7 @@ function runWorkTriggerCommandLocked(options) {
             kind: "mdkg.work_order.triggered",
             schema_version: 1,
             target_ref: options.targetRef,
-            work_id: workNode.id,
+            work_id: workRef,
             work_qid: workNode.qid,
             work_order_id: created.receipt.id,
             work_order_qid: created.receipt.qid,
@@ -932,7 +950,7 @@ function runWorkTriggerCommandLocked(options) {
         ws,
         kind: queueDelivery ? "WORK_TRIGGER_ENQUEUED" : "WORK_TRIGGERED",
         status: "ok",
-        refs: [created.receipt.id, workNode.id, ...(queueRef ? [queueRef] : [])],
+        refs: [created.receipt.id, workRef, ...(queueRef ? [queueRef] : [])],
         notes: queueDelivery
             ? `work trigger created order mirror and enqueued ${queueDelivery.message_id} on project DB queue ${queueDelivery.queue_name}; no work executed`
             : "work trigger created order mirror; no work executed",
@@ -980,14 +998,14 @@ function runWorkOrderUpdateCommandLocked(options) {
     loaded.frontmatter.queue_refs = appendUnique(toStringList(loaded.frontmatter.queue_refs), parseCsvList(options.addQueueRefs));
     loaded.frontmatter.artifacts = appendUnique(toStringList(loaded.frontmatter.artifacts), parseCsvList(options.addArtifacts));
     loaded.frontmatter.updated = (0, date_1.formatDate)(options.now ?? new Date());
-    writeFrontmatterFile(loaded.filePath, loaded.frontmatter, loaded.body);
+    writeFrontmatterFile(options.root, loaded.filePath, loaded.frontmatter, loaded.body);
     maybeReindex(options.root, loaded.config);
     printReceipt("order updated", nodeReceipt(options.root, loaded.node), options.json);
 }
 function runWorkOrderStatusCommandLocked(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
-    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config });
+    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config, persistReindex: false });
     const order = resolveReadableWorkNode(index, options.id, ws, "work_order", "work order");
     const receipt = buildWorkOrderStatusReceipt(index, order);
     if (options.json) {
@@ -1043,14 +1061,14 @@ function runWorkReceiptUpdateCommandLocked(options) {
     loaded.frontmatter.attestation_refs = appendUnique(toStringList(loaded.frontmatter.attestation_refs), parseCsvList(options.addAttestationRefs));
     loaded.frontmatter.evidence_hashes = appendUnique(toStringList(loaded.frontmatter.evidence_hashes), normalizeSha256Refs(options.addEvidenceHashes, "--add-evidence-hashes"));
     loaded.frontmatter.updated = (0, date_1.formatDate)(options.now ?? new Date());
-    writeFrontmatterFile(loaded.filePath, loaded.frontmatter, loaded.body);
+    writeFrontmatterFile(options.root, loaded.filePath, loaded.frontmatter, loaded.body);
     maybeReindex(options.root, loaded.config);
     printReceipt("receipt updated", nodeReceipt(options.root, loaded.node), options.json);
 }
 function runWorkReceiptVerifyCommandLocked(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
-    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config });
+    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config, persistReindex: false });
     const receiptNode = resolveReadableWorkNode(index, options.id, ws, "receipt", "receipt");
     const receipt = buildWorkReceiptVerifyReceipt(index, receiptNode);
     if (options.json) {
@@ -1114,7 +1132,7 @@ function runWorkArtifactAddCommandLocked(options) {
         loaded.frontmatter.relates = appendUnique(toStringList(loaded.frontmatter.relates), [archivePayload.archive.id]);
     }
     loaded.frontmatter.updated = (0, date_1.formatDate)(options.now ?? new Date());
-    writeFrontmatterFile(loaded.filePath, loaded.frontmatter, loaded.body);
+    writeFrontmatterFile(options.root, loaded.filePath, loaded.frontmatter, loaded.body);
     maybeReindex(options.root, loaded.config);
     if (options.json) {
         console.log(JSON.stringify({

package/dist/commands/workspace.js

@@ -12,6 +12,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const migrate_1 = require("../core/migrate");
+const filesystem_authority_1 = require("../core/filesystem_authority");
 const workspace_path_1 = require("../core/workspace_path");
 const atomic_1 = require("../util/atomic");
 const errors_1 = require("../util/errors");
@@ -67,6 +68,9 @@ function normalizeAlias(alias) {
     if (alias.toLowerCase() === "all") {
         throw new errors_1.UsageError("workspace alias cannot be 'all'");
     }
+    if (alias === "__proto__" || alias === "constructor" || alias === "prototype") {
+        throw new errors_1.UsageError(`workspace alias is reserved: ${alias}`);
+    }
     if (alias !== alias.toLowerCase() || !ALIAS_RE.test(alias)) {
         throw new errors_1.UsageError("workspace alias must be lowercase and use [a-z0-9_]");
     }
@@ -145,14 +149,16 @@ function runWorkspaceAddCommandLocked(options) {
             throw new errors_1.UsageError(`workspace document root already registered by ${existingAlias}`);
         }
     }
+    for (const folder of ["core", "design", "work"]) {
+        (0, filesystem_authority_1.ensureContainedDirectory)({
+            root: options.root,
+            relativePath: (0, workspace_path_1.workspaceDocumentRelativePath)(workspacePath, mdkgDir, folder),
+        });
+    }
     const workspace = { path: workspacePath, enabled: true, mdkg_dir: mdkgDir, visibility };
     workspaces[alias] = workspace;
     raw.workspaces = workspaces;
     writeRawConfig(configPath, raw);
-    const wsRoot = path_1.default.resolve(options.root, workspacePath, mdkgDir);
-    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "core"), { recursive: true });
-    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "design"), { recursive: true });
-    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "work"), { recursive: true });
     printWorkspaceMutationReceipt("added", workspaceReceipt(alias, workspace), options.json);
 }
 function runWorkspaceRemoveCommandLocked(options) {

package/dist/core/config.js

@@ -13,6 +13,7 @@ const migrate_1 = require("./migrate");
 const workspace_path_1 = require("./workspace_path");
 const project_db_1 = require("./project_db");
 const WORKSPACE_ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+const RESERVED_OBJECT_ALIASES = new Set(["__proto__", "constructor", "prototype"]);
 const PACK_EDGE_KEYS = new Set([
     "parent",
     "epic",
@@ -31,6 +32,12 @@ const SQL_IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 const DEFAULT_ARCHIVE_LARGE_CACHE_WARNING_BYTES = 26214400;
 const DEFAULT_SQLITE_COMMIT_WARNING_BYTES = 52428800;
 const DEFAULT_LOCK_TIMEOUT_MS = 10000;
+const DEFAULT_INDEX_LIMITS = {
+    max_files: 100000,
+    max_file_bytes: 8 * 1024 * 1024,
+    max_total_bytes: 512 * 1024 * 1024,
+    max_depth: 64,
+};
 const DEFAULT_SUBGRAPH_MAX_STALE_SECONDS = 3600;
 exports.DEFAULT_SKILL_MIRROR_TARGETS = [".agents/skills", ".claude/skills"];
 const DEFAULT_PROJECT_DB_CONFIG = {
@@ -229,6 +236,10 @@ function validateWorkspaceAlias(alias, errors) {
         errors.push("workspaces.all alias is reserved");
         return;
     }
+    if (RESERVED_OBJECT_ALIASES.has(alias)) {
+        errors.push(`workspaces.${alias} alias is reserved`);
+        return;
+    }
     if (alias !== alias.toLowerCase() || !WORKSPACE_ALIAS_RE.test(alias)) {
         errors.push(`workspaces.${alias} alias must be lowercase and use [a-z0-9_]`);
     }
@@ -238,6 +249,10 @@ function validateSubgraphAlias(alias, workspaces, errors) {
         errors.push("subgraphs.all alias is reserved");
         return;
     }
+    if (RESERVED_OBJECT_ALIASES.has(alias)) {
+        errors.push(`subgraphs.${alias} alias is reserved`);
+        return;
+    }
     if (alias !== alias.toLowerCase() || !WORKSPACE_ALIAS_RE.test(alias)) {
         errors.push(`subgraphs.${alias} alias must be lowercase and use [a-z0-9_]`);
     }
@@ -364,23 +379,36 @@ function validateConfigSchema(raw) {
         }
         : undefined;
     const index = indexRaw
-        ? {
-            auto_reindex: requireBoolean(indexRaw.auto_reindex, "index.auto_reindex", errors),
-            tolerant: requireBoolean(indexRaw.tolerant, "index.tolerant", errors),
-            backend: indexRaw.backend === undefined
-                ? "json"
-                : requireStringInSet(indexRaw.backend, "index.backend", INDEX_BACKEND_VALUES, errors),
-            global_index_path: requireContainedPath(indexRaw.global_index_path, "index.global_index_path", errors),
-            sqlite_path: indexRaw.sqlite_path === undefined
-                ? ".mdkg/index/mdkg.sqlite"
-                : requireContainedPath(indexRaw.sqlite_path, "index.sqlite_path", errors),
-            sqlite_commit_warning_bytes: indexRaw.sqlite_commit_warning_bytes === undefined
-                ? DEFAULT_SQLITE_COMMIT_WARNING_BYTES
-                : requireNonNegativeInteger(indexRaw.sqlite_commit_warning_bytes, "index.sqlite_commit_warning_bytes", errors),
-            lock_timeout_ms: indexRaw.lock_timeout_ms === undefined
-                ? DEFAULT_LOCK_TIMEOUT_MS
-                : requirePositiveInteger(indexRaw.lock_timeout_ms, "index.lock_timeout_ms", errors),
-        }
+        ? (() => {
+            const limitsRaw = indexRaw.limits === undefined
+                ? undefined
+                : requireObject(indexRaw.limits, "index.limits", errors);
+            return {
+                auto_reindex: requireBoolean(indexRaw.auto_reindex, "index.auto_reindex", errors),
+                tolerant: requireBoolean(indexRaw.tolerant, "index.tolerant", errors),
+                backend: indexRaw.backend === undefined
+                    ? "json"
+                    : requireStringInSet(indexRaw.backend, "index.backend", INDEX_BACKEND_VALUES, errors),
+                global_index_path: requireContainedPath(indexRaw.global_index_path, "index.global_index_path", errors),
+                sqlite_path: indexRaw.sqlite_path === undefined
+                    ? ".mdkg/index/mdkg.sqlite"
+                    : requireContainedPath(indexRaw.sqlite_path, "index.sqlite_path", errors),
+                sqlite_commit_warning_bytes: indexRaw.sqlite_commit_warning_bytes === undefined
+                    ? DEFAULT_SQLITE_COMMIT_WARNING_BYTES
+                    : requireNonNegativeInteger(indexRaw.sqlite_commit_warning_bytes, "index.sqlite_commit_warning_bytes", errors),
+                lock_timeout_ms: indexRaw.lock_timeout_ms === undefined
+                    ? DEFAULT_LOCK_TIMEOUT_MS
+                    : requirePositiveInteger(indexRaw.lock_timeout_ms, "index.lock_timeout_ms", errors),
+                limits: limitsRaw
+                    ? {
+                        max_files: requirePositiveInteger(limitsRaw.max_files, "index.limits.max_files", errors),
+                        max_file_bytes: requirePositiveInteger(limitsRaw.max_file_bytes, "index.limits.max_file_bytes", errors),
+                        max_total_bytes: requirePositiveInteger(limitsRaw.max_total_bytes, "index.limits.max_total_bytes", errors),
+                        max_depth: requirePositiveInteger(limitsRaw.max_depth, "index.limits.max_depth", errors),
+                    }
+                    : { ...DEFAULT_INDEX_LIMITS },
+            };
+        })()
         : undefined;
     const capabilities = capabilitiesRaw
         ? {

package/dist/core/filesystem_authority.js

@@ -0,0 +1,281 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainedPathError = void 0;
+exports.withContainedPathSink = withContainedPathSink;
+exports.withContainedTreeSink = withContainedTreeSink;
+exports.containedPathExists = containedPathExists;
+exports.ensureContainedDirectory = ensureContainedDirectory;
+exports.readContainedDirectory = readContainedDirectory;
+exports.readContainedFile = readContainedFile;
+exports.writeContainedFileExclusive = writeContainedFileExclusive;
+exports.appendContainedFile = appendContainedFile;
+exports.atomicReplaceContainedFile = atomicReplaceContainedFile;
+exports.removeContainedPath = removeContainedPath;
+exports.authorizeOperatorSelectedExternalPath = authorizeOperatorSelectedExternalPath;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+class ContainedPathError extends Error {
+    constructor(code, operation, relativePath, message) {
+        super(message);
+        this.name = "ContainedPathError";
+        this.code = code;
+        this.operation = operation;
+        this.relativePath = relativePath;
+    }
+}
+exports.ContainedPathError = ContainedPathError;
+function fail(code, operation, relativePath, message) {
+    throw new ContainedPathError(code, operation, relativePath, message);
+}
+function isAbsoluteOnSupportedPlatform(value) {
+    return (path_1.default.isAbsolute(value) ||
+        path_1.default.posix.isAbsolute(value) ||
+        path_1.default.win32.isAbsolute(value) ||
+        path_1.default.win32.parse(value).root.length > 0);
+}
+function normalizeRelativePath(value, operation) {
+    if (!value) {
+        fail("ERR_CONTAINED_PATH_EMPTY", operation, value, "contained path cannot be empty");
+    }
+    if (value.includes("\0")) {
+        fail("ERR_CONTAINED_PATH_NUL", operation, value, "contained path cannot contain NUL bytes");
+    }
+    if (isAbsoluteOnSupportedPlatform(value)) {
+        fail("ERR_CONTAINED_PATH_ABSOLUTE", operation, value, "contained path must be relative");
+    }
+    const components = value.split(/[\\/]/);
+    if (components.some((component) => component === "" || component === "." || component === "..")) {
+        fail("ERR_CONTAINED_PATH_COMPONENT", operation, value, "contained path cannot contain empty, current-directory, or parent-directory components");
+    }
+    return components.join(path_1.default.sep);
+}
+function isInside(root, target) {
+    const relative = path_1.default.relative(root, target);
+    return relative === "" || (!relative.startsWith("..") && !path_1.default.isAbsolute(relative));
+}
+function lstatIfPresent(target) {
+    try {
+        return fs_1.default.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function validatedRoot(root, operation, relativePath) {
+    const absoluteRoot = path_1.default.resolve(root);
+    const stat = lstatIfPresent(absoluteRoot);
+    if (!stat || !stat.isDirectory() || stat.isSymbolicLink()) {
+        fail("ERR_CONTAINED_PATH_ROOT", operation, relativePath, "contained path root must be an existing non-linked directory");
+    }
+    return {
+        absoluteRoot,
+        canonicalRoot: fs_1.default.realpathSync.native(absoluteRoot),
+    };
+}
+function inspectPath(root, relativePath, operation, createParents) {
+    // Node has no portable openat-style API. Keep validation and the sink in one
+    // authority, reject every visible link, and use O_NOFOLLOW for file opens.
+    const normalized = normalizeRelativePath(relativePath, operation);
+    const { absoluteRoot, canonicalRoot } = validatedRoot(root, operation, relativePath);
+    const components = normalized.split(path_1.default.sep);
+    let current = absoluteRoot;
+    let nearestExisting = absoluteRoot;
+    for (let index = 0; index < components.length; index += 1) {
+        current = path_1.default.join(current, components[index]);
+        const final = index === components.length - 1;
+        let stat = lstatIfPresent(current);
+        if (!stat && !final && createParents) {
+            try {
+                fs_1.default.mkdirSync(current);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST") {
+                    throw error;
+                }
+            }
+            stat = fs_1.default.lstatSync(current);
+        }
+        if (!stat) {
+            continue;
+        }
+        if (stat.isSymbolicLink()) {
+            fail("ERR_CONTAINED_PATH_LINK", operation, relativePath, final ? "contained path target cannot be a symbolic link" : "contained path has a linked ancestor");
+        }
+        if (!final && !stat.isDirectory()) {
+            fail("ERR_CONTAINED_PATH_NOT_DIRECTORY", operation, relativePath, "contained path ancestor is not a directory");
+        }
+        nearestExisting = current;
+    }
+    const absolutePath = path_1.default.resolve(absoluteRoot, normalized);
+    if (!isInside(absoluteRoot, absolutePath)) {
+        fail("ERR_CONTAINED_PATH_ESCAPE", operation, relativePath, "contained path resolves outside its root");
+    }
+    const canonicalExisting = fs_1.default.realpathSync.native(nearestExisting);
+    if (!isInside(canonicalRoot, canonicalExisting)) {
+        fail("ERR_CONTAINED_PATH_ESCAPE", operation, relativePath, "contained path resolves outside its canonical root");
+    }
+    return Object.freeze({
+        root: absoluteRoot,
+        operation,
+        relativePath: components.join("/"),
+        absolutePath,
+    });
+}
+function noFollowFlag() {
+    return typeof fs_1.default.constants.O_NOFOLLOW === "number" ? fs_1.default.constants.O_NOFOLLOW : 0;
+}
+function writeAndSync(filePath, data, flags) {
+    const handle = fs_1.default.openSync(filePath, flags, 0o666);
+    try {
+        fs_1.default.writeFileSync(handle, data, typeof data === "string" ? "utf8" : undefined);
+        fs_1.default.fsyncSync(handle);
+    }
+    finally {
+        fs_1.default.closeSync(handle);
+    }
+}
+function randomSuffix() {
+    return `${process.pid}-${Date.now()}-${crypto_1.default.randomBytes(6).toString("hex")}`;
+}
+function withContainedPathSink(input, sink) {
+    const descriptor = inspectPath(input.root, input.relativePath, input.operation, input.createParents ?? false);
+    return sink(descriptor);
+}
+function rejectLinkedTree(descriptor, currentPath) {
+    const entries = fs_1.default.readdirSync(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const child = path_1.default.join(currentPath, entry.name);
+        if (entry.isSymbolicLink()) {
+            fail("ERR_CONTAINED_PATH_LINK", descriptor.operation, descriptor.relativePath, "contained managed tree cannot contain symbolic links");
+        }
+        if (entry.isDirectory()) {
+            rejectLinkedTree(descriptor, child);
+        }
+    }
+}
+function withContainedTreeSink(input, sink) {
+    return withContainedPathSink(input, (descriptor) => {
+        const stat = lstatIfPresent(descriptor.absolutePath);
+        if (stat) {
+            if (!stat.isDirectory()) {
+                fail("ERR_CONTAINED_PATH_TYPE", descriptor.operation, descriptor.relativePath, "contained managed tree target must be a directory");
+            }
+            rejectLinkedTree(descriptor, descriptor.absolutePath);
+        }
+        return sink(descriptor);
+    });
+}
+function containedPathExists(input) {
+    return withContainedPathSink({ ...input, operation: "read" }, ({ absolutePath }) => lstatIfPresent(absolutePath) !== undefined);
+}
+function ensureContainedDirectory(input) {
+    let descriptor = inspectPath(input.root, input.relativePath, "create", true);
+    try {
+        fs_1.default.mkdirSync(descriptor.absolutePath);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+    descriptor = inspectPath(input.root, input.relativePath, "create", false);
+    if (!fs_1.default.lstatSync(descriptor.absolutePath).isDirectory()) {
+        fail("ERR_CONTAINED_PATH_TYPE", "create", input.relativePath, "contained directory target is not a directory");
+    }
+    return descriptor;
+}
+function readContainedDirectory(input) {
+    return withContainedPathSink({ ...input, operation: "read" }, ({ absolutePath }) => {
+        if (!fs_1.default.lstatSync(absolutePath).isDirectory()) {
+            fail("ERR_CONTAINED_PATH_TYPE", "read", input.relativePath, "contained read target must be a directory");
+        }
+        return fs_1.default.readdirSync(absolutePath, { withFileTypes: true });
+    });
+}
+function readContainedFile(input, encoding = "utf8") {
+    return withContainedPathSink({ ...input, operation: "read" }, ({ absolutePath }) => {
+        const handle = fs_1.default.openSync(absolutePath, fs_1.default.constants.O_RDONLY | noFollowFlag());
+        try {
+            const stat = fs_1.default.fstatSync(handle);
+            if (!stat.isFile()) {
+                fail("ERR_CONTAINED_PATH_TYPE", "read", input.relativePath, "contained read target must be a file");
+            }
+            if (input.maxBytes !== undefined && stat.size > input.maxBytes) {
+                fail("ERR_CONTAINED_PATH_TYPE", "read", input.relativePath, `contained read exceeds byte limit: ${input.maxBytes}`);
+            }
+            return encoding === null ? fs_1.default.readFileSync(handle) : fs_1.default.readFileSync(handle, encoding);
+        }
+        finally {
+            fs_1.default.closeSync(handle);
+        }
+    });
+}
+function writeContainedFileExclusive(input, data) {
+    const descriptor = inspectPath(input.root, input.relativePath, "create", true);
+    writeAndSync(descriptor.absolutePath, data, fs_1.default.constants.O_WRONLY | fs_1.default.constants.O_CREAT | fs_1.default.constants.O_EXCL | noFollowFlag());
+    return descriptor;
+}
+function appendContainedFile(input, data) {
+    const descriptor = inspectPath(input.root, input.relativePath, "replace", false);
+    const handle = fs_1.default.openSync(descriptor.absolutePath, fs_1.default.constants.O_WRONLY | fs_1.default.constants.O_APPEND | noFollowFlag());
+    try {
+        if (!fs_1.default.fstatSync(handle).isFile()) {
+            fail("ERR_CONTAINED_PATH_TYPE", "replace", input.relativePath, "contained append target must be a file");
+        }
+        fs_1.default.writeFileSync(handle, data, typeof data === "string" ? "utf8" : undefined);
+        fs_1.default.fsyncSync(handle);
+    }
+    finally {
+        fs_1.default.closeSync(handle);
+    }
+    return descriptor;
+}
+function atomicReplaceContainedFile(input, data) {
+    let descriptor = inspectPath(input.root, input.relativePath, "replace", true);
+    const tempRelative = `${descriptor.relativePath}.${randomSuffix()}.tmp`;
+    const temp = inspectPath(input.root, tempRelative, "create", false);
+    try {
+        writeAndSync(temp.absolutePath, data, fs_1.default.constants.O_WRONLY | fs_1.default.constants.O_CREAT | fs_1.default.constants.O_EXCL | noFollowFlag());
+        descriptor = inspectPath(input.root, input.relativePath, "replace", false);
+        inspectPath(input.root, tempRelative, "create", false);
+        fs_1.default.renameSync(temp.absolutePath, descriptor.absolutePath);
+        return descriptor;
+    }
+    catch (error) {
+        try {
+            const stat = lstatIfPresent(temp.absolutePath);
+            if (stat && !stat.isSymbolicLink()) {
+                fs_1.default.rmSync(temp.absolutePath, { force: true });
+            }
+        }
+        catch {
+            // Preserve the primary failure; any temp residue remains in the allowed root.
+        }
+        throw error;
+    }
+}
+function removeContainedPath(input) {
+    const descriptor = inspectPath(input.root, input.relativePath, "delete", false);
+    fs_1.default.rmSync(descriptor.absolutePath, {
+        recursive: input.recursive ?? false,
+        force: input.force ?? false,
+    });
+    return descriptor;
+}
+function authorizeOperatorSelectedExternalPath(input) {
+    if (!input.path || input.path.includes("\0")) {
+        throw new Error("operator-selected external path must be non-empty and cannot contain NUL bytes");
+    }
+    return Object.freeze({
+        operation: input.operation,
+        absolutePath: path_1.default.resolve(input.path),
+        operatorSelected: true,
+    });
+}

package/dist/core/project_db_events.js

@@ -351,6 +351,10 @@ function applyProjectDbReducer(databasePath, input) {
         if (!event) {
             throw new Error(`project DB event not found: ${input.event_id}`);
         }
+        if ((input.expected_project_id && event.project_id !== input.expected_project_id) ||
+            (input.expected_branch_id && event.branch_id !== input.expected_branch_id)) {
+            throw new Error(`project DB event scope mismatch: expected ${input.expected_project_id ?? event.project_id}/${input.expected_branch_id ?? event.branch_id}, found ${event.project_id}/${event.branch_id}`);
+        }
         if (event.status === "applied") {
             const receipt = writeReceiptWithDb(db, databasePath, {
                 project_id: event.project_id,

package/dist/core/project_db_materializer.js

@@ -339,6 +339,8 @@ function runNextProjectDbMaterializer(databasePath, input) {
         }
         const reducer = (0, project_db_events_1.applyProjectDbReducer)(databasePath, {
             event_id: payload.event_id,
+            expected_project_id: payload.project_id,
+            expected_branch_id: payload.branch_id,
             reducer_name: payload.reducer_name,
             reducer_version: payload.reducer_version,
             actor: input.lease_owner,