daftari 1.31.0 → 1.32.0

package/dist/tools/write.js

@@ -338,6 +338,64 @@ function denyIfProposeOnly(access, tool) {
     }
     return ok(undefined);
 }
+// The uniform RBAC write gate. One helper because the denial string is part
+// of the tool contract — every write tool emits the identical message shape,
+// and it must never leak more than the collection name.
+function requireWriteAccess(access, collection) {
+    if (access && !canWrite(access.role, collection)) {
+        return err(new Error(`access denied: role '${access.roleName}' cannot write to ` + `collection '${collection}'`));
+    }
+    return ok(undefined);
+}
+async function loadTargetDocument(vaultRoot, rawPath, tool) {
+    const resolved = resolveVaultPath(vaultRoot, rawPath);
+    if (!resolved.ok)
+        return resolved;
+    const existing = await readFile(resolved.value.absPath);
+    if (!existing.ok) {
+        return err(new Error(`${tool}: document not found: ${rawPath}`));
+    }
+    const parsed = parseDocument(existing.value);
+    if (!parsed.ok)
+        return parsed;
+    const config = loadConfig(vaultRoot);
+    if (!config.ok)
+        return config;
+    return ok({
+        // Lock key, provenance, and commit path are all keyed on the CANONICAL
+        // relPath, never the raw caller string: aliased spellings of one file
+        // must contend on one lock (#127/#128).
+        relPath: resolved.value.relPath,
+        absPath: resolved.value.absPath,
+        parsed: parsed.value,
+        config: config.value,
+    });
+}
+// The shared performWrite tail for frontmatter-only mutations: body preserved
+// verbatim (bodyChanged false), file text re-serialized from the new
+// frontmatter over the existing content.
+function performFrontmatterWrite(opts) {
+    const { target } = opts;
+    return performWrite({
+        vaultRoot: opts.vaultRoot,
+        relPath: target.relPath,
+        absPath: target.absPath,
+        agent: opts.agent,
+        tool: opts.tool,
+        action: opts.action,
+        fileText: serializeDocument(opts.newFrontmatter, target.parsed.content, target.config.schemaExtensions, target.parsed.raw),
+        newFrontmatter: opts.newFrontmatter,
+        oldFrontmatter: target.parsed.frontmatter,
+        validation: target.parsed.validation,
+        commitMessage: opts.commitMessage,
+        autoCommit: target.config.autoCommit,
+        gitDir: target.config.gitDir,
+        baseVersion: opts.baseVersion,
+        shadowMode: target.config.shadowMode,
+        principal: opts.access?.user,
+        bodyChanged: false,
+    });
+}
 // ---------------------------------------------------------------------------
 // vault_write
 // ---------------------------------------------------------------------------
@@ -470,13 +528,9 @@ export async function vaultWrite(vaultRoot, args, access) {
     // collection is allowed to differ from the physical dir (e.g. a draft staged
     // in _drafts/ that declares its destination collection); it just never widens
     // access.
-    if (access) {
-        const collection = targetCollection(vaultRoot, path.value);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
+    const writeGate = requireWriteAccess(access, targetCollection(vaultRoot, path.value));
+    if (!writeGate.ok)
+        return writeGate;
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
@@ -775,13 +829,9 @@ export async function vaultAppend(vaultRoot, args, access) {
         return config;
     const extensions = config.value.schemaExtensions;
     const oldFrontmatter = parsed.value.frontmatter;
-    if (access) {
-        const collection = collectionOf(path.value, oldFrontmatter);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
+    const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
+    if (!rbac.ok)
+        return rbac;
     const newFrontmatter = {
         ...oldFrontmatter,
         updated: todayISO(),
@@ -875,65 +925,42 @@ export async function vaultPromote(vaultRoot, args, access) {
     if (access && !canPromote(access.role)) {
         return err(new Error(`access denied: role '${access.roleName}' cannot promote documents`));
     }
-    const resolved = resolveVaultPath(vaultRoot, path.value);
-    if (!resolved.ok)
-        return resolved;
-    const existing = await readFile(resolved.value.absPath);
-    if (!existing.ok) {
-        return err(new Error(`vault_promote: document not found: ${path.value}`));
-    }
-    const parsed = parseDocument(existing.value);
-    if (!parsed.ok)
-        return parsed;
-    const config = loadConfig(vaultRoot);
-    if (!config.ok)
-        return config;
-    const extensions = config.value.schemaExtensions;
-    const oldFrontmatter = parsed.value.frontmatter;
+    const target = await loadTargetDocument(vaultRoot, path.value, "vault_promote");
+    if (!target.ok)
+        return target;
+    const oldFrontmatter = target.value.parsed.frontmatter;
     if (oldFrontmatter.status !== "draft") {
         return err(new Error(`vault_promote: only draft documents can be promoted ` +
             `(${path.value} is '${oldFrontmatter.status}')`));
     }
-    if (!parsed.value.validation.valid) {
-        const summary = parsed.value.validation.issues
+    if (!target.value.parsed.validation.valid) {
+        const summary = target.value.parsed.validation.issues
             .map((i) => `${i.field}: ${i.message}`)
             .join("; ");
         return err(new Error(`vault_promote: frontmatter is incomplete: ${summary}`));
     }
     // `confidence set` — the document must declare a confidence explicitly, not
     // ride on the validator's default.
-    const rawConfidence = parsed.value.raw.confidence;
+    const rawConfidence = target.value.parsed.raw.confidence;
     if (typeof rawConfidence !== "string" ||
         !CONFIDENCES.includes(rawConfidence)) {
         return err(new Error("vault_promote: confidence must be set before promotion"));
     }
-    const newFrontmatter = {
-        ...oldFrontmatter,
-        status: "canonical",
-        updated: todayISO(),
-        updated_by: agent.value,
-    };
-    return performWrite({
+    return performFrontmatterWrite({
         vaultRoot,
-        // Lock key, provenance, and commit path are all keyed on the CANONICAL
-        // relPath (resolved.value.relPath), never the raw caller string: aliased
-        // spellings of one file must contend on one lock (#127/#128).
-        relPath: resolved.value.relPath,
-        absPath: resolved.value.absPath,
+        target: target.value,
         agent: agent.value,
         tool: "vault_promote",
         action: "promote",
-        fileText: serializeDocument(newFrontmatter, parsed.value.content, extensions, parsed.value.raw),
-        newFrontmatter,
-        oldFrontmatter,
-        validation: parsed.value.validation,
+        newFrontmatter: {
+            ...oldFrontmatter,
+            status: "canonical",
+            updated: todayISO(),
+            updated_by: agent.value,
+        },
         commitMessage: `vault_promote: ${path.value} draft→canonical by ${agent.value}`,
-        autoCommit: config.value.autoCommit,
-        gitDir: config.value.gitDir,
         baseVersion: baseVersion.value,
-        shadowMode: config.value.shadowMode,
-        principal: access?.user,
-        bodyChanged: false,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -968,57 +995,30 @@ export async function vaultDeprecate(vaultRoot, args, access) {
         }
         supersededBy = args.superseded_by;
     }
-    const resolved = resolveVaultPath(vaultRoot, path.value);
-    if (!resolved.ok)
-        return resolved;
-    const existing = await readFile(resolved.value.absPath);
-    if (!existing.ok) {
-        return err(new Error(`vault_deprecate: document not found: ${path.value}`));
-    }
-    const parsed = parseDocument(existing.value);
-    if (!parsed.ok)
-        return parsed;
-    const config = loadConfig(vaultRoot);
-    if (!config.ok)
-        return config;
-    const extensions = config.value.schemaExtensions;
-    const oldFrontmatter = parsed.value.frontmatter;
-    if (access) {
-        const collection = collectionOf(path.value, oldFrontmatter);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
-    const newFrontmatter = {
-        ...oldFrontmatter,
-        status: "deprecated",
-        superseded_by: supersededBy,
-        updated: todayISO(),
-        updated_by: agent.value,
-    };
-    return performWrite({
+    const target = await loadTargetDocument(vaultRoot, path.value, "vault_deprecate");
+    if (!target.ok)
+        return target;
+    const oldFrontmatter = target.value.parsed.frontmatter;
+    const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
+    if (!rbac.ok)
+        return rbac;
+    return performFrontmatterWrite({
         vaultRoot,
-        // Lock key, provenance, and commit path are all keyed on the CANONICAL
-        // relPath (resolved.value.relPath), never the raw caller string: aliased
-        // spellings of one file must contend on one lock (#127/#128).
-        relPath: resolved.value.relPath,
-        absPath: resolved.value.absPath,
+        target: target.value,
         agent: agent.value,
         tool: "vault_deprecate",
         action: "deprecate",
-        fileText: serializeDocument(newFrontmatter, parsed.value.content, extensions, parsed.value.raw),
-        newFrontmatter,
-        oldFrontmatter,
-        validation: parsed.value.validation,
+        newFrontmatter: {
+            ...oldFrontmatter,
+            status: "deprecated",
+            superseded_by: supersededBy,
+            updated: todayISO(),
+            updated_by: agent.value,
+        },
         commitMessage: `vault_deprecate: ${path.value} by ${agent.value} — ${reason.value}` +
             (supersededBy ? ` (superseded by ${supersededBy})` : ""),
-        autoCommit: config.value.autoCommit,
-        gitDir: config.value.gitDir,
         baseVersion: baseVersion.value,
-        shadowMode: config.value.shadowMode,
-        principal: access?.user,
-        bodyChanged: false,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -1053,28 +1053,13 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
     const baseVersion = readBaseVersion(args, "vault_set_confidence");
     if (!baseVersion.ok)
         return baseVersion;
-    const resolved = resolveVaultPath(vaultRoot, path.value);
-    if (!resolved.ok)
-        return resolved;
-    const existing = await readFile(resolved.value.absPath);
-    if (!existing.ok) {
-        return err(new Error(`vault_set_confidence: document not found: ${path.value}`));
-    }
-    const parsed = parseDocument(existing.value);
-    if (!parsed.ok)
-        return parsed;
-    const config = loadConfig(vaultRoot);
-    if (!config.ok)
-        return config;
-    const extensions = config.value.schemaExtensions;
-    const oldFrontmatter = parsed.value.frontmatter;
-    if (access) {
-        const collection = collectionOf(path.value, oldFrontmatter);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
+    const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_confidence");
+    if (!target.ok)
+        return target;
+    const oldFrontmatter = target.value.parsed.frontmatter;
+    const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
+    if (!rbac.ok)
+        return rbac;
     // No-op guard: a confidence already at the target would churn a commit for no
     // change. Surface it as an error so a redundant staged confidence-up does not
     // silently no-op (and a caller learns the value was already set). Compare
@@ -1083,41 +1068,29 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
     // validated value would wrongly reject set_confidence(…, "low") on a doc that
     // never declared one and never write the field (the trap vault_promote dodges
     // the same way, via parsed.value.raw.confidence).
-    const rawConfidence = parsed.value.raw.confidence;
+    const rawConfidence = target.value.parsed.raw.confidence;
     const currentConfidence = typeof rawConfidence === "string" && CONFIDENCES.includes(rawConfidence)
         ? rawConfidence
         : undefined;
     if (currentConfidence === confidence.value) {
         return err(new Error(`vault_set_confidence: ${path.value} confidence is already '${confidence.value}'`));
     }
-    const newFrontmatter = {
-        ...oldFrontmatter,
-        confidence: confidence.value,
-        updated: todayISO(),
-        updated_by: agent.value,
-    };
-    return performWrite({
+    return performFrontmatterWrite({
         vaultRoot,
-        // Lock key, provenance, and commit path are all keyed on the CANONICAL
-        // relPath (resolved.value.relPath), never the raw caller string: aliased
-        // spellings of one file must contend on one lock (#127/#128).
-        relPath: resolved.value.relPath,
-        absPath: resolved.value.absPath,
+        target: target.value,
         agent: agent.value,
         tool: "vault_set_confidence",
         action: "confidence-set",
-        fileText: serializeDocument(newFrontmatter, parsed.value.content, extensions, parsed.value.raw),
-        newFrontmatter,
-        oldFrontmatter,
-        validation: parsed.value.validation,
+        newFrontmatter: {
+            ...oldFrontmatter,
+            confidence: confidence.value,
+            updated: todayISO(),
+            updated_by: agent.value,
+        },
         commitMessage: `vault_set_confidence: ${path.value} ${oldFrontmatter.confidence}→${confidence.value} ` +
             `by ${agent.value} — ${reason.value}`,
-        autoCommit: config.value.autoCommit,
-        gitDir: config.value.gitDir,
         baseVersion: baseVersion.value,
-        shadowMode: config.value.shadowMode,
-        principal: access?.user,
-        bodyChanged: false,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -1156,28 +1129,13 @@ export async function vaultSetTier(vaultRoot, args, access) {
     const baseVersion = readBaseVersion(args, "vault_set_tier");
     if (!baseVersion.ok)
         return baseVersion;
-    const resolved = resolveVaultPath(vaultRoot, path.value);
-    if (!resolved.ok)
-        return resolved;
-    const existing = await readFile(resolved.value.absPath);
-    if (!existing.ok) {
-        return err(new Error(`vault_set_tier: document not found: ${path.value}`));
-    }
-    const parsed = parseDocument(existing.value);
-    if (!parsed.ok)
-        return parsed;
-    const config = loadConfig(vaultRoot);
-    if (!config.ok)
-        return config;
-    const extensions = config.value.schemaExtensions;
-    const oldFrontmatter = parsed.value.frontmatter;
-    if (access) {
-        const collection = collectionOf(path.value, oldFrontmatter);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
+    const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_tier");
+    if (!target.ok)
+        return target;
+    const oldFrontmatter = target.value.parsed.frontmatter;
+    const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
+    if (!rbac.ok)
+        return rbac;
     // The manual consent boundary: only a human identity may lift `manual`.
     if (oldFrontmatter.tier === "manual" &&
         newTier !== "manual" &&
@@ -1188,41 +1146,29 @@ export async function vaultSetTier(vaultRoot, args, access) {
     // No-op guard, same shape as vault_set_confidence: compare against the raw
     // on-disk value so an invalid raw tier (validated down to null) can still be
     // set to any member.
-    const rawTier = parsed.value.raw.tier;
+    const rawTier = target.value.parsed.raw.tier;
     const currentTier = typeof rawTier === "string" && TIERS.includes(rawTier)
         ? rawTier
         : undefined;
     if (currentTier === newTier) {
         return err(new Error(`vault_set_tier: ${path.value} tier is already '${newTier}'`));
     }
-    const newFrontmatter = {
-        ...oldFrontmatter,
-        tier: newTier,
-        updated: todayISO(),
-        updated_by: agent.value,
-    };
-    return performWrite({
+    return performFrontmatterWrite({
         vaultRoot,
-        // Lock key, provenance, and commit path are all keyed on the CANONICAL
-        // relPath (resolved.value.relPath), never the raw caller string: aliased
-        // spellings of one file must contend on one lock (#127/#128).
-        relPath: resolved.value.relPath,
-        absPath: resolved.value.absPath,
+        target: target.value,
         agent: agent.value,
         tool: "vault_set_tier",
         action: "tier-set",
-        fileText: serializeDocument(newFrontmatter, parsed.value.content, extensions, parsed.value.raw),
-        newFrontmatter,
-        oldFrontmatter,
-        validation: parsed.value.validation,
+        newFrontmatter: {
+            ...oldFrontmatter,
+            tier: newTier,
+            updated: todayISO(),
+            updated_by: agent.value,
+        },
         commitMessage: `vault_set_tier: ${path.value} ${oldFrontmatter.tier ?? "unset"}→${newTier} ` +
             `by ${agent.value} — ${reason.value}`,
-        autoCommit: config.value.autoCommit,
-        gitDir: config.value.gitDir,
         baseVersion: baseVersion.value,
-        shadowMode: config.value.shadowMode,
-        principal: access?.user,
-        bodyChanged: false,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -1284,42 +1230,33 @@ export async function vaultSupersede(vaultRoot, args, access) {
     const config = loadConfig(vaultRoot);
     if (!config.ok)
         return config;
-    const extensions = config.value.schemaExtensions;
     const oldFrontmatter = parsed.value.frontmatter;
-    if (access) {
-        const collection = collectionOf(oldPath.value, oldFrontmatter);
-        if (!canWrite(access.role, collection)) {
-            return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                `collection '${collection}'`));
-        }
-    }
-    const newFrontmatter = {
-        ...oldFrontmatter,
-        status: "superseded",
-        superseded_by: newPath.value,
-        updated: todayISO(),
-        updated_by: agent.value,
-    };
-    return performWrite({
+    const rbac = requireWriteAccess(access, collectionOf(oldPath.value, oldFrontmatter));
+    if (!rbac.ok)
+        return rbac;
+    return performFrontmatterWrite({
         vaultRoot,
         // Canonical relPath keys the lock/provenance/commit (#127/#128).
-        relPath: resolvedOld.value.relPath,
-        absPath: resolvedOld.value.absPath,
+        target: {
+            relPath: resolvedOld.value.relPath,
+            absPath: resolvedOld.value.absPath,
+            parsed: parsed.value,
+            config: config.value,
+        },
         agent: agent.value,
         tool: "vault_supersede",
         action: "supersede",
-        fileText: serializeDocument(newFrontmatter, parsed.value.content, extensions, parsed.value.raw),
-        newFrontmatter,
-        oldFrontmatter,
-        validation: parsed.value.validation,
+        newFrontmatter: {
+            ...oldFrontmatter,
+            status: "superseded",
+            superseded_by: newPath.value,
+            updated: todayISO(),
+            updated_by: agent.value,
+        },
         commitMessage: `vault_supersede: ${oldPath.value} superseded by ${newPath.value} ` +
             `by ${agent.value}${reason ? ` — ${reason}` : ""}`,
-        autoCommit: config.value.autoCommit,
-        gitDir: config.value.gitDir,
         baseVersion: baseVersion.value,
-        shadowMode: config.value.shadowMode,
-        principal: access?.user,
-        bodyChanged: false,
+        access,
     });
 }
 // Combines two source documents into a target and supersedes both sources to
@@ -1413,10 +1350,9 @@ export async function vaultMerge(vaultRoot, args, access) {
             targetCollection(vaultRoot, targetPath.value),
         ];
         for (const collection of collections) {
-            if (!canWrite(access.role, collection)) {
-                return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
-                    `collection '${collection}'`));
-            }
+            const gate = requireWriteAccess(access, collection);
+            if (!gate.ok)
+                return gate;
         }
     }
     // Target frontmatter: inherit path_a's raw frontmatter, apply caller