daftari 1.19.0 → 1.21.0

package/dist/tools/write.js

@@ -13,6 +13,7 @@ import matter from "gray-matter";
 import { acquireLock, openLockDb, releaseLock } from "../access/locks.js";
 import { canPromote, canWrite } from "../access/rbac.js";
 import { frontmatterDiff, recordProvenance } from "../curation/provenance.js";
+import { recordShadowAction } from "../curation/shadow.js";
 import { parseDocument } from "../frontmatter/parser.js";
 import { validateFrontmatter } from "../frontmatter/schema.js";
 import { CONFIDENCES, DOMAINS, err, ok, PROVENANCES, STATUSES, } from "../frontmatter/types.js";
@@ -148,6 +149,36 @@ function shortHash(h) {
 // entry is logged. When `baseVersion` is omitted the check is skipped entirely
 // and last-write-wins behavior is preserved.
 async function performWrite(params) {
+    // Shadow mode (spec §11.5): everything up to here ran exactly as live —
+    // validation, RBAC, frontmatter assembly, diff — so the logged do() is one
+    // that WOULD have executed. Log it with its impact/budget verdict and stop:
+    // no lock, no file, no commit, no index, no provenance. base_version is
+    // intentionally not checked — stale-write rejection guards a mutation, and
+    // there is none.
+    if (params.shadowMode) {
+        const recorded = await recordShadowAction(params.vaultRoot, {
+            tool: params.tool,
+            action: params.action,
+            targetPath: params.relPath,
+            agent: params.agent,
+            ...(params.principal ? { principal: params.principal } : {}),
+            frontmatterDiff: frontmatterDiff(params.oldFrontmatter, params.newFrontmatter),
+            commitMessage: params.commitMessage,
+        });
+        if (!recorded.ok)
+            return recorded;
+        return ok({
+            path: params.relPath,
+            action: params.action,
+            commit: null,
+            committed: false,
+            status: params.newFrontmatter.status,
+            updated: params.newFrontmatter.updated,
+            validation: params.validation,
+            indexUpdated: false,
+            shadow: true,
+        });
+    }
     const lockDbResult = openLockDb(params.vaultRoot);
     if (!lockDbResult.ok)
         return lockDbResult;
@@ -167,6 +198,7 @@ async function performWrite(params) {
                         tool: params.tool,
                         file: params.relPath,
                         agent: params.agent,
+                        ...(params.principal ? { principal: params.principal } : {}),
                         action: "rejected_stale",
                         reason: `stale: base_version ${shortHash(params.baseVersion)} != ` +
                             `current ${currentHash ? shortHash(currentHash) : "<absent>"}`,
@@ -196,6 +228,7 @@ async function performWrite(params) {
                 tool: params.tool,
                 file: params.relPath,
                 agent: params.agent,
+                ...(params.principal ? { principal: params.principal } : {}),
                 action: params.action,
                 frontmatter_diff: frontmatterDiff(params.oldFrontmatter, params.newFrontmatter),
             });
@@ -406,6 +439,8 @@ export async function vaultWrite(vaultRoot, args, access) {
         commitMessage: `vault_write: ${isUpdate ? "update" : "create"} ${path.value} ` + `by ${agent.value}`,
         autoCommit: config.value.autoCommit,
         baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
     });
 }
 // ---------------------------------------------------------------------------
@@ -492,6 +527,8 @@ export async function vaultAppend(vaultRoot, args, access) {
         commitMessage: `vault_append: ${path.value} by ${agent.value}`,
         autoCommit: config.value.autoCommit,
         baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
     });
 }
 // ---------------------------------------------------------------------------
@@ -568,6 +605,8 @@ export async function vaultPromote(vaultRoot, args, access) {
         commitMessage: `vault_promote: ${path.value} draft→canonical by ${agent.value}`,
         autoCommit: config.value.autoCommit,
         baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
     });
 }
 // ---------------------------------------------------------------------------
@@ -643,7 +682,461 @@ export async function vaultDeprecate(vaultRoot, args, access) {
             (supersededBy ? ` (superseded by ${supersededBy})` : ""),
         autoCommit: config.value.autoCommit,
         baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
+    });
+}
+// ---------------------------------------------------------------------------
+// vault_set_confidence (§11.4)
+// ---------------------------------------------------------------------------
+// Changes only a document's `confidence`, leaving status and body untouched.
+// A narrow tool so a calibration nudge never rides a full-document overwrite.
+// A reason is mandatory — a confidence change is a claim about the document's
+// trustworthiness and earns an audit trail.
+export async function vaultSetConfidence(vaultRoot, args, access) {
+    const ready = requireIndexReady();
+    if (!ready.ok)
+        return ready;
+    const path = requireString(args, "path", "vault_set_confidence");
+    if (!path.ok)
+        return path;
+    const agent = requireString(args, "agent", "vault_set_confidence");
+    if (!agent.ok)
+        return agent;
+    const reason = requireString(args, "reason", "vault_set_confidence");
+    if (!reason.ok)
+        return reason;
+    const confidence = requireString(args, "confidence", "vault_set_confidence");
+    if (!confidence.ok)
+        return confidence;
+    if (!CONFIDENCES.includes(confidence.value)) {
+        return err(new Error(`vault_set_confidence: 'confidence' must be one of: ${CONFIDENCES.join(", ")}`));
+    }
+    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);
+    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}'`));
+        }
+    }
+    // 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
+    // against the *raw* on-disk value, not the validated frontmatter — the
+    // validator defaults a missing confidence to "low", so comparing the
+    // 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 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({
+        vaultRoot,
+        relPath: path.value,
+        absPath: resolved.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,
+        commitMessage: `vault_set_confidence: ${path.value} ${oldFrontmatter.confidence}→${confidence.value} ` +
+            `by ${agent.value} — ${reason.value}`,
+        autoCommit: config.value.autoCommit,
+        baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
+    });
+}
+// ---------------------------------------------------------------------------
+// vault_supersede (§11.4)
+// ---------------------------------------------------------------------------
+// Marks a document explicitly superseded by a named successor. Distinct from
+// vault_deprecate: deprecate sets status="deprecated" with an *optional*
+// successor; supersede sets status="superseded" and *requires* a successor that
+// must already exist. Permissive on source status in v1 (last-write-wins).
+export async function vaultSupersede(vaultRoot, args, access) {
+    const ready = requireIndexReady();
+    if (!ready.ok)
+        return ready;
+    const oldPath = requireString(args, "old_path", "vault_supersede");
+    if (!oldPath.ok)
+        return oldPath;
+    const newPath = requireString(args, "new_path", "vault_supersede");
+    if (!newPath.ok)
+        return newPath;
+    const agent = requireString(args, "agent", "vault_supersede");
+    if (!agent.ok)
+        return agent;
+    const baseVersion = readBaseVersion(args, "vault_supersede");
+    if (!baseVersion.ok)
+        return baseVersion;
+    let reason;
+    if (args.reason !== undefined && args.reason !== null) {
+        if (typeof args.reason !== "string") {
+            return err(new Error("vault_supersede: 'reason' must be a string"));
+        }
+        const trimmed = args.reason.trim();
+        if (trimmed.length > 0)
+            reason = trimmed;
+    }
+    if (oldPath.value === newPath.value) {
+        return err(new Error("vault_supersede: a document cannot supersede itself"));
+    }
+    const resolvedOld = resolveVaultPath(vaultRoot, oldPath.value);
+    if (!resolvedOld.ok)
+        return resolvedOld;
+    const resolvedNew = resolveVaultPath(vaultRoot, newPath.value);
+    if (!resolvedNew.ok)
+        return resolvedNew;
+    const existing = await readFile(resolvedOld.value);
+    if (!existing.ok) {
+        return err(new Error(`vault_supersede: document not found: ${oldPath.value}`));
+    }
+    // The successor must be a real document — superseded_by must never dangle.
+    const successor = await readFile(resolvedNew.value);
+    if (!successor.ok) {
+        return err(new Error(`vault_supersede: successor not found: ${newPath.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(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({
+        vaultRoot,
+        relPath: oldPath.value,
+        absPath: resolvedOld.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,
+        commitMessage: `vault_supersede: ${oldPath.value} superseded by ${newPath.value} ` +
+            `by ${agent.value}${reason ? ` — ${reason}` : ""}`,
+        autoCommit: config.value.autoCommit,
+        baseVersion: baseVersion.value,
+        shadowMode: config.value.shadowMode,
+        principal: access?.user,
+    });
+}
+// Combines two source documents into a target and supersedes both sources to
+// point at it. Mechanical, not generative: the merged body is supplied by the
+// caller (a human at ratification, or the loop) — vault_merge never synthesizes
+// prose (that would be an LLM call; the write layer is LLM-free).
+//
+// Unlike the single-file write tools this touches up to three files, so it does
+// not use performWrite. It mirrors the backfill apply pattern: write each file,
+// index each, then one git commit for the whole set (src/backfill/apply.ts). A
+// source that *is* the target is written once (with the merged body), not also
+// superseded. base_version optimistic concurrency is not offered for merge.
+export async function vaultMerge(vaultRoot, args, access) {
+    const ready = requireIndexReady();
+    if (!ready.ok)
+        return ready;
+    const pathA = requireString(args, "path_a", "vault_merge");
+    if (!pathA.ok)
+        return pathA;
+    const pathB = requireString(args, "path_b", "vault_merge");
+    if (!pathB.ok)
+        return pathB;
+    const targetPath = requireString(args, "target_path", "vault_merge");
+    if (!targetPath.ok)
+        return targetPath;
+    const agent = requireString(args, "agent", "vault_merge");
+    if (!agent.ok)
+        return agent;
+    const body = args.body;
+    if (typeof body !== "string" || body.trim().length === 0) {
+        return err(new Error("vault_merge requires a non-empty string 'body' argument"));
+    }
+    if (args.frontmatter !== undefined && args.frontmatter !== null) {
+        if (typeof args.frontmatter !== "object") {
+            return err(new Error("vault_merge: 'frontmatter' must be an object"));
+        }
+    }
+    const frontmatterOverrides = args.frontmatter && typeof args.frontmatter === "object"
+        ? args.frontmatter
+        : {};
+    // Resolve all three paths up front and run every identity check against the
+    // resolved absolute paths, never the raw caller strings: `pricing/a.md` and
+    // `./pricing/a.md` name the same file but differ as strings, which would
+    // otherwise defeat the path_a≠path_b guard and the source-is-target skip
+    // below (writing one file twice in a single commit and superseding it against
+    // itself).
+    const resolvedA = resolveVaultPath(vaultRoot, pathA.value);
+    if (!resolvedA.ok)
+        return resolvedA;
+    const resolvedB = resolveVaultPath(vaultRoot, pathB.value);
+    if (!resolvedB.ok)
+        return resolvedB;
+    const resolvedTarget = resolveVaultPath(vaultRoot, targetPath.value);
+    if (!resolvedTarget.ok)
+        return resolvedTarget;
+    if (resolvedA.value === resolvedB.value) {
+        return err(new Error("vault_merge: path_a and path_b must differ"));
+    }
+    const existingA = await readFile(resolvedA.value);
+    if (!existingA.ok)
+        return err(new Error(`vault_merge: document not found: ${pathA.value}`));
+    const existingB = await readFile(resolvedB.value);
+    if (!existingB.ok)
+        return err(new Error(`vault_merge: document not found: ${pathB.value}`));
+    const parsedA = parseDocument(existingA.value);
+    if (!parsedA.ok)
+        return parsedA;
+    const parsedB = parseDocument(existingB.value);
+    if (!parsedB.ok)
+        return parsedB;
+    const config = loadConfig(vaultRoot);
+    if (!config.ok)
+        return config;
+    const extensions = config.value.schemaExtensions;
+    // RBAC: a merge writes/mutates all three docs, so the caller needs write on
+    // each one's collection.
+    if (access) {
+        // The target's collection is the override, else path_a's *raw* collection
+        // (the value actually serialized into the target below — not the validated
+        // frontmatter, which may differ if path_a's raw collection is malformed),
+        // else the target path's top-level dir. Deriving it from the same source
+        // the write uses keeps the gate and the write in agreement.
+        const rawACollection = parsedA.value.raw.collection;
+        const collections = [
+            collectionOf(pathA.value, parsedA.value.frontmatter),
+            collectionOf(pathB.value, parsedB.value.frontmatter),
+            typeof frontmatterOverrides.collection === "string" && frontmatterOverrides.collection
+                ? frontmatterOverrides.collection
+                : typeof rawACollection === "string" && rawACollection
+                    ? rawACollection
+                    : (targetPath.value.split("/")[0] ?? ""),
+        ];
+        for (const collection of collections) {
+            if (!canWrite(access.role, collection)) {
+                return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
+                    `collection '${collection}'`));
+            }
+        }
+    }
+    // Target frontmatter: inherit path_a's raw frontmatter, apply caller
+    // overrides, stamp provenance/updated/updated_by. If the target file already
+    // exists, preserve its `created` (the vault_write update idiom); otherwise
+    // inherit path_a's. The supplied body replaces whatever was there.
+    const existingTarget = await readFile(resolvedTarget.value);
+    let targetOldFrontmatter = null;
+    let targetCreated = parsedA.value.frontmatter.created;
+    if (existingTarget.ok) {
+        const parsedTarget = parseDocument(existingTarget.value);
+        if (parsedTarget.ok) {
+            targetOldFrontmatter = parsedTarget.value.frontmatter;
+            targetCreated = parsedTarget.value.frontmatter.created;
+        }
+    }
+    const targetRaw = {
+        ...parsedA.value.raw,
+        provenance: "synthesized",
+        ...frontmatterOverrides,
+        created: targetCreated,
+        updated: todayISO(),
+        updated_by: agent.value,
+    };
+    const { frontmatter: targetFm, report: targetReport } = validateFrontmatter(targetRaw, extensions);
+    if (!targetReport.valid) {
+        const summary = targetReport.issues.map((i) => `${i.field}: ${i.message}`).join("; ");
+        return err(new Error(`vault_merge: target frontmatter is invalid: ${summary}`));
+    }
+    const stampedTarget = {
+        ...targetFm,
+        created: targetCreated,
+        updated: todayISO(),
+        updated_by: agent.value,
+    };
+    // Build the write set. The target is always written. Each source that is NOT
+    // the target is superseded to point at the target.
+    const writes = [];
+    writes.push({
+        relPath: targetPath.value,
+        absPath: resolvedTarget.value,
+        fileText: serializeDocument(stampedTarget, body, extensions, applyExtensionDefaults(targetRaw, extensions)),
+        newFrontmatter: stampedTarget,
+        oldFrontmatter: targetOldFrontmatter,
+        action: "merge",
     });
+    for (const source of [
+        { path: pathA.value, abs: resolvedA.value, parsed: parsedA.value },
+        { path: pathB.value, abs: resolvedB.value, parsed: parsedB.value },
+    ]) {
+        // Compare resolved absolute paths, not raw strings: a source that aliases
+        // the target (e.g. target `./pricing/a.md`, source `pricing/a.md`) is the
+        // fold-into-A case — write it once with the merged body, never supersede it.
+        if (source.abs === resolvedTarget.value)
+            continue;
+        const supersededFm = {
+            ...source.parsed.frontmatter,
+            status: "superseded",
+            superseded_by: targetPath.value,
+            updated: todayISO(),
+            updated_by: agent.value,
+        };
+        writes.push({
+            relPath: source.path,
+            absPath: source.abs,
+            fileText: serializeDocument(supersededFm, source.parsed.content, extensions, source.parsed.raw),
+            newFrontmatter: supersededFm,
+            oldFrontmatter: source.parsed.frontmatter,
+            action: "supersede",
+        });
+    }
+    // Shadow mode (spec §11.5): the full write set is assembled and validated —
+    // the do() that WOULD have executed. Log one merge record whose blast seeds
+    // every touched path, write nothing.
+    if (config.value.shadowMode) {
+        const recorded = await recordShadowAction(vaultRoot, {
+            tool: "vault_merge",
+            action: "merge",
+            targetPath: targetPath.value,
+            touchedPaths: [...new Set(writes.map((w) => w.relPath))],
+            agent: agent.value,
+            ...(access?.user ? { principal: access.user } : {}),
+            frontmatterDiff: frontmatterDiff(targetOldFrontmatter, stampedTarget),
+            commitMessage: `vault_merge: ${pathA.value} + ${pathB.value} → ${targetPath.value} by ${agent.value}`,
+        });
+        if (!recorded.ok)
+            return recorded;
+        return ok({
+            path: targetPath.value,
+            action: "merge",
+            commit: null,
+            committed: false,
+            status: stampedTarget.status,
+            updated: stampedTarget.updated,
+            validation: targetReport,
+            indexUpdated: false,
+            shadow: true,
+        });
+    }
+    // Acquire file locks on every distinct path, in a deterministic sorted order
+    // (defensive against self-deadlock if two merges ever overlapped — the
+    // one-process invariant makes that theoretical). Release all in finally.
+    const lockDbResult = openLockDb(vaultRoot);
+    if (!lockDbResult.ok)
+        return lockDbResult;
+    const lockDb = lockDbResult.value;
+    const lockPaths = [...new Set(writes.map((w) => w.relPath))].sort();
+    const held = [];
+    try {
+        for (const relPath of lockPaths) {
+            const lock = acquireLock(lockDb, relPath, agent.value);
+            if (!lock.ok)
+                return lock;
+            held.push(relPath);
+        }
+        // Write all files, then a single git commit. This is NOT crash-atomic on
+        // the disk-write phase: like the single-file write path (performWrite), a
+        // throw mid-loop — or a commit() failure after the files are on disk —
+        // leaves the working tree dirty and uncommitted. For merge the dirty state
+        // can be a *partial* merge (target written, a source not yet superseded),
+        // which a later reindex/watcher would pick up. The git commit itself is
+        // atomic, and the one-process invariant plus human-gated ratification keep
+        // this window small; a full pre-write snapshot/rollback is deferred.
+        for (const w of writes) {
+            await mkdir(dirname(w.absPath), { recursive: true });
+            await writeFile(w.absPath, w.fileText, "utf-8");
+        }
+        let commitHash = null;
+        if (config.value.autoCommit) {
+            const committed = await commit(vaultRoot, writes.map((w) => w.relPath), `vault_merge: ${pathA.value} + ${pathB.value} → ${targetPath.value} by ${agent.value}`, agent.value);
+            if (!committed.ok)
+                return committed;
+            commitHash = committed.value.hash;
+        }
+        // Index each written doc and log provenance per file. Both are best-effort
+        // (the index is a rebuildable cache; the log is advisory) so a failure here
+        // does not unwind the durable commit. noteSelfWrite runs here, after the
+        // index lands, so the fs.watch reactive indexer drops the redundant change
+        // event for our own write (mirrors performWrite's ordering).
+        let allIndexed = true;
+        for (const w of writes) {
+            const indexed = await indexDocument(vaultRoot, w.relPath);
+            if (!indexed.ok)
+                allIndexed = false;
+            noteSelfWrite(w.absPath);
+            await recordProvenance(vaultRoot, {
+                tool: "vault_merge",
+                file: w.relPath,
+                agent: agent.value,
+                ...(access?.user ? { principal: access.user } : {}),
+                action: w.action,
+                frontmatter_diff: frontmatterDiff(w.oldFrontmatter, w.newFrontmatter),
+            });
+        }
+        return ok({
+            path: targetPath.value,
+            action: "merge",
+            commit: commitHash,
+            committed: config.value.autoCommit,
+            status: stampedTarget.status,
+            updated: stampedTarget.updated,
+            validation: targetReport,
+            indexUpdated: allIndexed,
+        });
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        return err(new Error(`vault_merge failed: ${reason}`));
+    }
+    finally {
+        for (const relPath of held)
+            releaseLock(lockDb, relPath, agent.value);
+        lockDb.close();
+    }
 }
 // ---------------------------------------------------------------------------
 // MCP tool definitions
@@ -653,6 +1146,11 @@ const agentProperty = {
     description: "Acting identity, e.g. 'agent:claude-code' or 'human:mihir'. Recorded " +
         "as updated_by, the git author, and in the provenance log.",
 };
+// Appended to every write-tool description: shadow_mode (§11.5) makes the
+// "auto-commits" claim conditionally false, and the description is the only
+// surface a caller reads before invoking.
+const shadowNote = " If the vault runs shadow_mode, the write is computed and logged to the " +
+    "shadow store but NOT applied; the result carries shadow: true.";
 const baseVersionProperty = {
     type: "string",
     description: "Optional optimistic-concurrency token: the 'version' that vault_read " +
@@ -750,7 +1248,8 @@ export const writeTools = [
             "full frontmatter and markdown body; the server stamps 'updated' and " +
             "'updated_by' (omit them — anything supplied is overwritten), preserves " +
             "'created' on updates, refreshes the search index, and auto-commits the " +
-            "change to git.",
+            "change to git." +
+            shadowNote,
         inputSchema: {
             type: "object",
             properties: {
@@ -773,7 +1272,8 @@ export const writeTools = [
         title: "Append to a document",
         annotations: { destructiveHint: true },
         description: "Append a markdown section to an existing vault document. Frontmatter " +
-            "is preserved; 'updated' and 'updated_by' are re-stamped. Auto-commits.",
+            "is preserved; 'updated' and 'updated_by' are re-stamped. Auto-commits." +
+            shadowNote,
         inputSchema: {
             type: "object",
             properties: {
@@ -799,7 +1299,8 @@ export const writeTools = [
         annotations: { destructiveHint: true },
         description: "Promote a draft document to canonical status. Refuses unless the " +
             "document is currently a draft, its frontmatter is complete, and a " +
-            "confidence level has been explicitly set. Auto-commits.",
+            "confidence level has been explicitly set. Auto-commits." +
+            shadowNote,
         inputSchema: {
             type: "object",
             properties: {
@@ -820,7 +1321,8 @@ export const writeTools = [
         title: "Deprecate a document",
         annotations: { destructiveHint: true },
         description: "Mark a document deprecated. A reason is required; optionally record " +
-            "the document that supersedes it. Auto-commits.",
+            "the document that supersedes it. Auto-commits." +
+            shadowNote,
         inputSchema: {
             type: "object",
             properties: {
@@ -844,5 +1346,111 @@ export const writeTools = [
         },
         handler: (vaultRoot, args, access) => vaultDeprecate(vaultRoot, args, access),
     },
+    {
+        name: "vault_set_confidence",
+        title: "Set a document's confidence",
+        annotations: { destructiveHint: true },
+        description: "Change only a document's confidence level (low | medium | high), leaving " +
+            "its status and body untouched. A reason is required and recorded. Rejects " +
+            "if the confidence is already at the target. Auto-commits." +
+            shadowNote,
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Vault-relative path of the document",
+                },
+                confidence: {
+                    type: "string",
+                    enum: [...CONFIDENCES],
+                    description: "The new confidence level",
+                },
+                reason: {
+                    type: "string",
+                    description: "Why the confidence is changing (recorded in the commit and provenance)",
+                },
+                agent: agentProperty,
+                base_version: baseVersionProperty,
+            },
+            required: ["path", "confidence", "reason", "agent"],
+            additionalProperties: false,
+        },
+        handler: (vaultRoot, args, access) => vaultSetConfidence(vaultRoot, args, access),
+    },
+    {
+        name: "vault_supersede",
+        title: "Supersede a document",
+        annotations: { destructiveHint: true },
+        description: "Mark a document superseded by a named successor. Sets status=superseded " +
+            "and superseded_by; the successor must already exist. Distinct from " +
+            "vault_deprecate (which sets status=deprecated with an optional " +
+            "successor). Auto-commits." +
+            shadowNote,
+        inputSchema: {
+            type: "object",
+            properties: {
+                old_path: {
+                    type: "string",
+                    description: "Vault-relative path of the document being superseded",
+                },
+                new_path: {
+                    type: "string",
+                    description: "Vault-relative path of the successor that replaces it (must exist)",
+                },
+                reason: {
+                    type: "string",
+                    description: "Optional reason recorded in the commit message",
+                },
+                agent: agentProperty,
+                base_version: baseVersionProperty,
+            },
+            required: ["old_path", "new_path", "agent"],
+            additionalProperties: false,
+        },
+        handler: (vaultRoot, args, access) => vaultSupersede(vaultRoot, args, access),
+    },
+    {
+        name: "vault_merge",
+        title: "Merge two documents into one",
+        annotations: { destructiveHint: true },
+        description: "Combine two source documents into a target and supersede both sources to " +
+            "point at it, all in one commit. The merged body is supplied by the caller " +
+            "— vault_merge does not synthesize prose. target_path may equal path_a (to " +
+            "fold B into A) or be a new path. The target's frontmatter inherits " +
+            "path_a's (provenance becomes 'synthesized') unless overridden. Auto-commits." +
+            shadowNote,
+        inputSchema: {
+            type: "object",
+            properties: {
+                path_a: {
+                    type: "string",
+                    description: "Vault-relative path of the first source document",
+                },
+                path_b: {
+                    type: "string",
+                    description: "Vault-relative path of the second source document",
+                },
+                target_path: {
+                    type: "string",
+                    description: "Vault-relative path of the merge target (may equal path_a, or be new)",
+                },
+                body: {
+                    type: "string",
+                    description: "The merged markdown body for the target (no frontmatter)",
+                },
+                frontmatter: {
+                    type: "object",
+                    description: "Optional frontmatter overrides for the target. Defaults to path_a's " +
+                        "frontmatter with provenance set to 'synthesized'.",
+                    additionalProperties: true,
+                },
+                agent: agentProperty,
+            },
+            required: ["path_a", "path_b", "target_path", "body", "agent"],
+            additionalProperties: false,
+        },
+        handler: (vaultRoot, args, access) => vaultMerge(vaultRoot, args, access),
+    },
 ];
 //# sourceMappingURL=write.js.map