daftari 1.30.0 → 1.32.0

package/dist/tools/write.js

@@ -11,21 +11,29 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve, sep } from "node:path";
 import matter from "gray-matter";
 import { acquireLock, openLockDb, releaseLock } from "../access/locks.js";
-import { canPromote, canWrite } from "../access/rbac.js";
+import { canPromote, canWrite, isProposeOnly } from "../access/rbac.js";
+import { mintConsumesEdges } from "../curation/consumes.js";
 import { frontmatterDiff, recordProvenance } from "../curation/provenance.js";
 import { recordShadowAction } from "../curation/shadow.js";
+import { stageActionWithConflictCheck } from "../curation/staged-actions.js";
+import { sourceReadable } from "../curation/tension-access.js";
+import { EXTERNAL_REF } from "../curation/tier0.js";
+import { buildPathIndexes, extractLinks, outgoingLinkTargets, resolveLink, } from "../curation/vault-docs.js";
 import { parseDocument } from "../frontmatter/parser.js";
 import { validateFrontmatter } from "../frontmatter/schema.js";
-import { CONFIDENCES, DOMAINS, err, ok, PROVENANCES, STATUSES, } from "../frontmatter/types.js";
+import { CONFIDENCES, DOMAINS, err, ok, PROVENANCES, STATUSES, TIERS, } from "../frontmatter/types.js";
 import { loadHooks, loadPreWriteTransformHooks } from "../hooks/loader.js";
 import { runPreWriteHooks, runPreWriteTransformHooks } from "../hooks/runner.js";
 import { getIndexStatus, indexingBusyMessage } from "../search/index-state.js";
 import { indexDocument } from "../search/reindex.js";
 import { noteSelfWrite } from "../search/self-write.js";
+import { allDocumentPaths, getDocumentsByPaths } from "../storage/index-db.js";
 import { readFile, resolveVaultPath } from "../storage/local.js";
 import { loadConfig } from "../utils/config.js";
 import { commit } from "../utils/git.js";
 import { sha256Hex } from "../utils/hash.js";
+import { readRunId } from "../utils/run-id.js";
+import { openIndexForAccessOrNull } from "./search.js";
 // ---------------------------------------------------------------------------
 // shared helpers
 // ---------------------------------------------------------------------------
@@ -112,6 +120,10 @@ export function serializeDocument(fm, body, extensions = [], raw = {}) {
         updated: fm.updated,
         updated_by: fm.updated_by,
         provenance: fm.provenance,
+        // `?? null` — a hand-built Frontmatter that predates tier may carry
+        // undefined here, which js-yaml refuses to dump (null it serializes fine,
+        // matching the superseded_by convention).
+        tier: fm.tier ?? null,
         sources: fm.sources,
         superseded_by: fm.superseded_by,
         ttl_days: fm.ttl_days,
@@ -224,6 +236,7 @@ async function performWrite(params) {
                         file: params.relPath,
                         agent: params.agent,
                         ...(params.principal ? { principal: params.principal } : {}),
+                        ...(params.runId ? { run_id: params.runId } : {}),
                         action: "rejected_stale",
                         reason: `stale: base_version ${shortHash(params.baseVersion)} != ` +
                             `current ${currentHash ? shortHash(currentHash) : "<absent>"}`,
@@ -254,9 +267,21 @@ async function performWrite(params) {
                 file: params.relPath,
                 agent: params.agent,
                 ...(params.principal ? { principal: params.principal } : {}),
+                ...(params.runId ? { run_id: params.runId } : {}),
+                ...(params.bodyChanged !== undefined ? { body_changed: params.bodyChanged } : {}),
                 action: params.action,
                 frontmatter_diff: frontmatterDiff(params.oldFrontmatter, params.newFrontmatter),
             });
+            // #233: a run-correlated write compiles its input set — every path the
+            // run read beforehand becomes a consumes edge. Best-effort like the
+            // provenance/index steps: the write is already durable, and the graph
+            // is advisory substrate, so a mint failure never fails the write.
+            if (params.runId) {
+                await mintConsumesEdges(params.vaultRoot, {
+                    artifact: params.relPath,
+                    runId: params.runId,
+                });
+            }
             return ok({
                 path: params.relPath,
                 action: params.action,
@@ -300,12 +325,176 @@ function readBaseVersion(args, tool) {
     }
     return ok(v.length === 0 ? undefined : v);
 }
+// #235: a propose-only role cannot mutate the vault directly. vault_write
+// coerces into a staged proposal (see vaultWrite); every OTHER write tool is
+// denied with a pointer to the staging surface. Structural enforcement — the
+// permission layer decides, not convention.
+function denyIfProposeOnly(access, tool) {
+    if (access && isProposeOnly(access.role)) {
+        return err(new Error(`${tool}: role '${access.roleName}' is propose-only — direct writes are ` +
+            `disabled. Propose the change instead: vault_write stages a 'write' ` +
+            `proposal, and vault_stage_action stages lifecycle actions ` +
+            `(promote, deprecate, supersede, merge, confidence-up) for ratification.`));
+    }
+    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
 // ---------------------------------------------------------------------------
 // Creates a new document or overwrites an existing one. The caller supplies
 // the full frontmatter; `updated` and `updated_by` are always stamped by the
 // server, and `created` is preserved from the existing document on an update.
+// --- tier write-protection (#141) ------------------------------------------
+//
+// `tier: source` bodies are immutable to EVERY writer; `tier: manual` bodies
+// only accept rewrites from a human:* identity. The escape hatch is
+// deliberately NOT an inline force flag — a refusal that names a bypass
+// parameter teaches the calling model to pass it reflexively. Instead the
+// caller must demote the tier first (vault_set_tier, reason required, change
+// provenance-logged), then write. Frontmatter-only writes pass unchanged, so
+// curation tools (promote, deprecate, supersede, set_confidence) and tag
+// edits keep working on tiered docs.
+// Body equality up to a leading-newline / trailing-whitespace difference:
+// gray-matter's parsed content starts with the newline after the frontmatter
+// fence and serializeDocument re-adds one, so a byte comparison would flag
+// every round-tripped body as changed.
+function sameBody(a, b) {
+    const norm = (s) => s.replace(/^\n+/, "").replace(/\s+$/, "");
+    return norm(a) === norm(b);
+}
+function checkTierGuard(args) {
+    const { tool, path, tier, oldBody, newBody, agent } = args;
+    if (tier !== "source" && tier !== "manual")
+        return ok(undefined);
+    if (sameBody(oldBody, newBody))
+        return ok(undefined);
+    if (tier === "source") {
+        return err(new Error(`${tool}: ${path} is tier 'source' — its body is immutable. If this ` +
+            `rewrite is deliberate, demote the tier first with vault_set_tier ` +
+            `(a reason is required and the change is logged), then write. ` +
+            `vault_append can add to it without a tier change.`));
+    }
+    if (!agent.startsWith("human:")) {
+        return err(new Error(`${tool}: ${path} is tier 'manual' — body rewrites require a ` +
+            `human:* identity (got '${agent}'). vault_append can add to it.`));
+    }
+    return ok(undefined);
+}
+// #4: the generative-domain documents an accumulation-domain doc references
+// (typed `sources` entries plus body links), resolved against the indexed
+// path universe. Advisory only — callers attach the result as
+// domain_warnings; index unavailability degrades to silence.
+function generativeDomainRefs(vaultRoot, doc, access) {
+    if (doc.domain !== "accumulation")
+        return null;
+    // Most accumulation writes reference nothing; skip the index entirely
+    // rather than loading every vault path to resolve an empty candidate set.
+    const localSources = doc.sources.filter((s) => !EXTERNAL_REF.test(s));
+    if (localSources.length === 0 && extractLinks(doc.body).length === 0)
+        return null;
+    const db = openIndexForAccessOrNull(vaultRoot);
+    if (!db)
+        return null;
+    try {
+        const indexes = buildPathIndexes(allDocumentPaths(db).map((p) => ({ path: p })));
+        const candidates = new Set(outgoingLinkTargets(doc.body, doc.relPath, indexes));
+        for (const raw of localSources) {
+            const target = resolveLink(raw, doc.relPath, indexes.byPath, indexes.byBasename);
+            if (target && target !== doc.relPath)
+                candidates.add(target);
+        }
+        if (candidates.size === 0)
+            return null;
+        const generative = getDocumentsByPaths(db, [...candidates])
+            .filter((d) => d.domain === "generative")
+            .map((d) => d.path)
+            // Vantage rule (#217, security review on #261): a warning names the
+            // RESOLVED path and discloses the target's domain — metadata about a
+            // doc the caller may not read, and resolveLink's basename fallback can
+            // reveal a location the caller never typed. Targets outside the
+            // caller's read scope are omitted entirely, the same rule lint's
+            // domainLeaks inherits from runLint's pre-filtered doc set.
+            .filter((p) => !access || sourceReadable(db, access, p))
+            .sort();
+        if (generative.length === 0)
+            return null;
+        return generative.map((p) => `${p} is generative-domain — speculative material referenced from accumulation canon`);
+    }
+    catch {
+        // This runs after performWrite returned ok — the write is durable. A
+        // query failure here (index rebuilt mid-query, locked db) must degrade
+        // to "no warnings", never surface as a failed write to the caller.
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}
+// The #169 nudge, verbatim on every vault_write overwrite. One fixed string:
+// the signal is the field's presence, and a stable text is grep-able in
+// agent traces.
+const SUPERSEDE_HINT = "This write replaced an existing document in place. If it records a changed " +
+    "fact, prefer vault_supersede: it preserves the prior version and mints the " +
+    "superseded_by edge instead of erasing lineage. Advisory only — this write " +
+    "has already landed.";
 export async function vaultWrite(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
@@ -319,6 +508,9 @@ export async function vaultWrite(vaultRoot, args, access) {
     const baseVersion = readBaseVersion(args, "vault_write");
     if (!baseVersion.ok)
         return baseVersion;
+    const runId = readRunId(args, "vault_write");
+    if (!runId.ok)
+        return runId;
     const body = args.body;
     if (typeof body !== "string") {
         return err(new Error("vault_write requires a string 'body' argument"));
@@ -336,19 +528,87 @@ 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;
+    // #235: a propose-only role's write lands as a staged `write` proposal, not
+    // a mutation. Coerced EARLY — before file I/O, tier guards, hooks, or
+    // validation — because all of that runs for real at ratify time when
+    // vault_ratify dispatches the payload back through this tool with the
+    // ratifier's access. The write grant above still scopes which collections
+    // the role may propose into. Inter-proposal conflicts are checked the same
+    // way vault_stage_action checks them: both proposals stay pending, a
+    // tension is logged, the result names the contenders. Staged under the
+    // CANONICAL relPath, matching vault_stage_action — a raw caller spelling
+    // (`pricing/./x.md`) would dodge the exact-string conflict match and the
+    // ratify gate's existing-doc lookup (#127/#128 rule).
+    if (access && isProposeOnly(access.role)) {
+        // The validation report is REAL, not fabricated: run the payload through
+        // the same merge-then-validate the eventual dispatch will apply (merged
+        // under any existing frontmatter, server-stamped fields defaulted), so a
+        // propose-only agent gets its schema feedback NOW instead of at ratify
+        // time up to ttl_days later. Advisory here — staging proceeds regardless;
+        // the blocking check runs for real when vault_ratify dispatches.
+        const proposeConfig = loadConfig(vaultRoot);
+        if (!proposeConfig.ok)
+            return proposeConfig;
+        let previewRaw = { ...rawFrontmatter };
+        const onDisk = await readFile(resolved.value.absPath);
+        if (onDisk.ok) {
+            const parsedExisting = parseDocument(onDisk.value);
+            if (parsedExisting.ok) {
+                const merged = { ...parsedExisting.value.raw };
+                for (const [key, value] of Object.entries(rawFrontmatter)) {
+                    if (value === null)
+                        delete merged[key];
+                    else
+                        merged[key] = value;
+                }
+                previewRaw = merged;
+            }
+        }
+        if (previewRaw.updated === undefined || previewRaw.updated === null) {
+            previewRaw.updated = todayISO();
+        }
+        if (previewRaw.updated_by === undefined || previewRaw.updated_by === null) {
+            previewRaw.updated_by = agent.value;
+        }
+        const preview = validateFrontmatter(previewRaw, proposeConfig.value.schemaExtensions);
+        const staged = await stageActionWithConflictCheck(vaultRoot, {
+            actionType: "write",
+            targetPath: resolved.value.relPath,
+            proposedBy: agent.value,
+            rationale: typeof args.reason === "string" && args.reason.trim().length > 0
+                ? args.reason.trim()
+                : `propose-only role '${access.roleName}': write staged for ratification`,
+            proposedDiff: { frontmatter: rawFrontmatter, body },
+            ...(runId.value !== undefined ? { runId: runId.value } : {}),
+        });
+        if (!staged.ok)
+            return staged;
+        return ok({
+            path: resolved.value.relPath,
+            action: "staged",
+            commit: null,
+            committed: false,
+            status: "pending",
+            updated: todayISO(),
+            validation: preview.report,
+            indexUpdated: false,
+            staged_id: staged.value.id,
+            expires_at: staged.value.expires_at,
+            conflicts_with: staged.value.conflicts_with,
+            tension_id: staged.value.tension_id,
+            ...(staged.value.tension_error ? { tension_error: staged.value.tension_error } : {}),
+        });
+    }
     const existing = await readFile(resolved.value.absPath);
     let oldFrontmatter = null;
     let oldRaw = null;
+    let oldContent = "";
     if (existing.ok) {
         const parsed = parseDocument(existing.value);
         if (!parsed.ok) {
@@ -363,9 +623,22 @@ export async function vaultWrite(vaultRoot, args, access) {
         }
         oldFrontmatter = parsed.value.frontmatter;
         oldRaw = parsed.value.raw;
+        oldContent = parsed.value.content;
     }
     const isUpdate = oldFrontmatter !== null;
     const hookOperation = isUpdate ? "update" : "create";
+    if (isUpdate && oldFrontmatter) {
+        const guard = checkTierGuard({
+            tool: "vault_write",
+            path: path.value,
+            tier: oldFrontmatter.tier,
+            oldBody: oldContent,
+            newBody: body,
+            agent: agent.value,
+        });
+        if (!guard.ok)
+            return guard;
+    }
     // On update, merge the document's existing frontmatter under the payload, so
     // a tool-mediated write never silently drops a field the author put there
     // (#113). `oldRaw` is the frontmatter exactly as parsed — built-in fields,
@@ -388,6 +661,19 @@ export async function vaultWrite(vaultRoot, args, access) {
             delete rawFrontmatter[key];
         Object.assign(rawFrontmatter, merged);
     }
+    // #141: a protected doc's tier only changes via vault_set_tier. Allowing it
+    // here would let a frontmatter-only write (which sameBody waves through)
+    // demote the tier — dodging set_tier's reason requirement and manual's
+    // human gate — and then rewrite the body in a second call.
+    if (isUpdate &&
+        oldFrontmatter &&
+        (oldFrontmatter.tier === "source" || oldFrontmatter.tier === "manual")) {
+        if (rawFrontmatter.tier !== oldFrontmatter.tier) {
+            return err(new Error(`vault_write: ${path.value} is tier '${oldFrontmatter.tier}' — changing ` +
+                `its tier requires vault_set_tier (a reason is required` +
+                `${oldFrontmatter.tier === "manual" ? ", and a human:* identity" : ""}).`));
+        }
+    }
     // Config-declared schema extensions participate in validation and
     // serialization. A malformed config fails the write loudly, matching the
     // server's loud-config contract.
@@ -454,7 +740,7 @@ export async function vaultWrite(vaultRoot, args, access) {
         updated: todayISO(),
         updated_by: agent.value,
     };
-    return performWrite({
+    const written = await performWrite({
         vaultRoot,
         // Lock key, provenance, and commit path are all keyed on the CANONICAL
         // relPath (resolved.value.relPath), never the raw caller string: aliased
@@ -474,6 +760,31 @@ export async function vaultWrite(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        ...(runId.value !== undefined ? { runId: runId.value } : {}),
+        bodyChanged: !isUpdate || !sameBody(oldContent, body),
+    });
+    // #169: an in-place overwrite destroys the prior version's lineage, and
+    // daftari HAS the preserve-not-overwrite primitive — steer toward it at
+    // the moment of overwrite, the decay banner's channel: additive, advisory,
+    // never blocking, never auto-minting an edge. The agent still chooses.
+    // Attached here (not in performWrite) so vault_supersede and the other
+    // lifecycle tools never nudge about themselves. A shadow-mode result is
+    // excluded: nothing landed and nothing was replaced, so the hints' text
+    // would be false. #4's domain warnings ride the same channel.
+    if (!written.ok || written.value.shadow)
+        return written;
+    const warnings = generativeDomainRefs(vaultRoot, {
+        domain: stamped.domain,
+        sources: stamped.sources ?? [],
+        body,
+        relPath: resolved.value.relPath,
+    }, access);
+    if (!isUpdate && warnings === null)
+        return written;
+    return ok({
+        ...written.value,
+        ...(isUpdate ? { supersede_hint: SUPERSEDE_HINT } : {}),
+        ...(warnings ? { domain_warnings: warnings } : {}),
     });
 }
 // ---------------------------------------------------------------------------
@@ -497,6 +808,12 @@ export async function vaultAppend(vaultRoot, args, access) {
     const baseVersion = readBaseVersion(args, "vault_append");
     if (!baseVersion.ok)
         return baseVersion;
+    const runId = readRunId(args, "vault_append");
+    if (!runId.ok)
+        return runId;
+    const proposeGate = denyIfProposeOnly(access, "vault_append");
+    if (!proposeGate.ok)
+        return proposeGate;
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
@@ -512,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(),
@@ -546,7 +859,7 @@ export async function vaultAppend(vaultRoot, args, access) {
         const summary = appendIssues.map((i) => `${i.field}: ${i.message}`).join("; ");
         return err(new Error(`invalid frontmatter: ${summary}`));
     }
-    return performWrite({
+    const appended = await performWrite({
         vaultRoot,
         // Lock key, provenance, and commit path are all keyed on the CANONICAL
         // relPath (resolved.value.relPath), never the raw caller string: aliased
@@ -566,7 +879,26 @@ export async function vaultAppend(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        ...(runId.value !== undefined ? { runId: runId.value } : {}),
+        bodyChanged: true,
     });
+    // #4: an appended section can introduce body links into generative-domain
+    // docs — same advisory channel as vault_write, scoped to what THIS append
+    // added: only the new section is scanned (a doc that already leaned on
+    // generative material warned at write time; re-warning on every later,
+    // unrelated append would drown the signal), and sources are skipped
+    // entirely because an append cannot change frontmatter.
+    if (!appended.ok || appended.value.shadow)
+        return appended;
+    const appendWarnings = generativeDomainRefs(vaultRoot, {
+        domain: newFrontmatter.domain,
+        sources: [],
+        body: section.value,
+        relPath: resolved.value.relPath,
+    }, access);
+    if (appendWarnings === null)
+        return appended;
+    return ok({ ...appended.value, domain_warnings: appendWarnings });
 }
 // ---------------------------------------------------------------------------
 // vault_promote
@@ -578,6 +910,9 @@ export async function vaultPromote(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
         return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_promote");
+    if (!proposeGate.ok)
+        return proposeGate;
     const path = requireString(args, "path", "vault_promote");
     if (!path.ok)
         return path;
@@ -590,64 +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,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -660,6 +973,9 @@ export async function vaultDeprecate(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
         return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_deprecate");
+    if (!proposeGate.ok)
+        return proposeGate;
     const path = requireString(args, "path", "vault_deprecate");
     if (!path.ok)
         return path;
@@ -679,56 +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,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -742,6 +1032,9 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
         return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_set_confidence");
+    if (!proposeGate.ok)
+        return proposeGate;
     const path = requireString(args, "path", "vault_set_confidence");
     if (!path.ok)
         return path;
@@ -760,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
@@ -790,40 +1068,107 @@ 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,
+        access,
+    });
+}
+// ---------------------------------------------------------------------------
+// vault_set_tier (#141)
+// ---------------------------------------------------------------------------
+// Changes only a document's write-protection tier, leaving body and status
+// untouched. This is the escape hatch for the tier guards — a separate,
+// reason-carrying, provenance-logged act rather than an inline force flag on
+// the destructive call. Moving a doc AWAY from `manual` requires a human:*
+// identity (otherwise demote-then-write would bypass the consent boundary);
+// moving away from `source` is open to any identity — deliberate demotions
+// are allowed, and vault_lint surfaces them for review.
+export async function vaultSetTier(vaultRoot, args, access) {
+    const ready = requireIndexReady();
+    if (!ready.ok)
+        return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_set_tier");
+    if (!proposeGate.ok)
+        return proposeGate;
+    const path = requireString(args, "path", "vault_set_tier");
+    if (!path.ok)
+        return path;
+    const agent = requireString(args, "agent", "vault_set_tier");
+    if (!agent.ok)
+        return agent;
+    const reason = requireString(args, "reason", "vault_set_tier");
+    if (!reason.ok)
+        return reason;
+    const tier = requireString(args, "tier", "vault_set_tier");
+    if (!tier.ok)
+        return tier;
+    if (!TIERS.includes(tier.value)) {
+        return err(new Error(`vault_set_tier: 'tier' must be one of: ${TIERS.join(", ")}`));
+    }
+    const newTier = tier.value;
+    const baseVersion = readBaseVersion(args, "vault_set_tier");
+    if (!baseVersion.ok)
+        return baseVersion;
+    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" &&
+        !agent.value.startsWith("human:")) {
+        return err(new Error(`vault_set_tier: ${path.value} is tier 'manual' — moving it away from ` +
+            `'manual' requires a human:* identity (got '${agent.value}').`));
+    }
+    // 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 = 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}'`));
+    }
+    return performFrontmatterWrite({
+        vaultRoot,
+        target: target.value,
+        agent: agent.value,
+        tool: "vault_set_tier",
+        action: "tier-set",
+        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}`,
+        baseVersion: baseVersion.value,
+        access,
     });
 }
 // ---------------------------------------------------------------------------
@@ -837,6 +1182,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
         return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_supersede");
+    if (!proposeGate.ok)
+        return proposeGate;
     const oldPath = requireString(args, "old_path", "vault_supersede");
     if (!oldPath.ok)
         return oldPath;
@@ -882,41 +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,
+        access,
     });
 }
 // Combines two source documents into a target and supersedes both sources to
@@ -933,6 +1273,9 @@ export async function vaultMerge(vaultRoot, args, access) {
     const ready = requireIndexReady();
     if (!ready.ok)
         return ready;
+    const proposeGate = denyIfProposeOnly(access, "vault_merge");
+    if (!proposeGate.ok)
+        return proposeGate;
     const pathA = requireString(args, "path_a", "vault_merge");
     if (!pathA.ok)
         return pathA;
@@ -1007,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
@@ -1019,14 +1361,31 @@ export async function vaultMerge(vaultRoot, args, access) {
     // inherit path_a's. The supplied body replaces whatever was there.
     const existingTarget = await readFile(resolvedTarget.value.absPath);
     let targetOldFrontmatter = null;
+    let targetOldContent = "";
     let targetCreated = parsedA.value.frontmatter.created;
     if (existingTarget.ok) {
         const parsedTarget = parseDocument(existingTarget.value);
         if (parsedTarget.ok) {
             targetOldFrontmatter = parsedTarget.value.frontmatter;
+            targetOldContent = parsedTarget.value.content;
             targetCreated = parsedTarget.value.frontmatter.created;
         }
     }
+    // Tier guard (#141): the merged body wholly replaces the target's. path_a
+    // and path_b only receive a frontmatter-level supersede, so their tiers
+    // don't gate the merge.
+    if (targetOldFrontmatter) {
+        const guard = checkTierGuard({
+            tool: "vault_merge",
+            path: targetPath.value,
+            tier: targetOldFrontmatter.tier,
+            oldBody: targetOldContent,
+            newBody: body,
+            agent: agent.value,
+        });
+        if (!guard.ok)
+            return guard;
+    }
     const targetRaw = {
         ...parsedA.value.raw,
         provenance: "synthesized",
@@ -1176,6 +1535,9 @@ export async function vaultMerge(vaultRoot, args, access) {
                 agent: agent.value,
                 ...(access?.user ? { principal: access.user } : {}),
                 action: w.action,
+                // The merge target gets a new body; the superseded sources only get
+                // frontmatter stamps.
+                body_changed: w.action === "merge",
                 frontmatter_diff: frontmatterDiff(w.oldFrontmatter, w.newFrontmatter),
             });
         }
@@ -1221,6 +1583,11 @@ const baseVersionProperty = {
         "write is rejected as stale and nothing is changed. Omit for " +
         "last-write-wins behavior.",
 };
+const runIdProperty = {
+    type: "string",
+    description: "Optional trace/run identifier of the calling run. Recorded in the " +
+        "provenance log so one run's writes correlate.",
+};
 // Built-in frontmatter properties, projected from the canonical TS constants
 // in src/frontmatter/types.ts so the MCP input schema, the runtime validator,
 // and the source-of-truth enums never drift. `additionalProperties: true`
@@ -1310,7 +1677,15 @@ 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. If the caller's role is propose-only, nothing is " +
+            "written: the payload lands as a staged 'write' proposal awaiting " +
+            "vault_ratify, and the result carries action: 'staged' with the " +
+            "proposal id (plus any competing pending proposals on the same target). " +
+            "Overwriting an existing document returns an advisory supersede_hint — " +
+            "when the write records a changed fact, vault_supersede preserves the " +
+            "prior version and its lineage instead. An accumulation-domain write " +
+            "that cites or links generative-domain docs returns advisory " +
+            "domain_warnings naming them; the write still lands." +
             shadowNote,
         inputSchema: {
             type: "object",
@@ -1323,6 +1698,12 @@ export const writeTools = [
                 frontmatter: frontmatterProperty,
                 agent: agentProperty,
                 base_version: baseVersionProperty,
+                run_id: runIdProperty,
+                reason: {
+                    type: "string",
+                    description: "Optional rationale. Used as the proposal rationale when a " +
+                        "propose-only role's write is staged for ratification.",
+                },
             },
             required: ["path", "body", "frontmatter", "agent"],
             additionalProperties: false,
@@ -1334,7 +1715,10 @@ 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. " +
+            "Appending links to generative-domain docs onto an accumulation-domain " +
+            "doc returns advisory domain_warnings naming them; the append still " +
+            "lands." +
             shadowNote,
         inputSchema: {
             type: "object",
@@ -1349,6 +1733,7 @@ export const writeTools = [
                 },
                 agent: agentProperty,
                 base_version: baseVersionProperty,
+                run_id: runIdProperty,
             },
             required: ["path", "section", "agent"],
             additionalProperties: false,
@@ -1440,6 +1825,43 @@ export const writeTools = [
         },
         handler: (vaultRoot, args, access) => vaultSetConfidence(vaultRoot, args, access),
     },
+    {
+        name: "vault_set_tier",
+        title: "Set a document's write-protection tier",
+        annotations: { destructiveHint: true },
+        description: "Change only a document's write-protection tier (source | compiled | " +
+            "manual), leaving its body untouched. `source` bodies are immutable; " +
+            "`manual` bodies only accept rewrites from a human:* identity; " +
+            "`compiled` and unset are unenforced. This is the escape hatch for the " +
+            "tier guards: demote first (a reason is required and the change is " +
+            "logged for lint review), then write. Moving a doc away from 'manual' " +
+            "requires a human:* identity. Rejects if the tier is already at the " +
+            "target. Auto-commits." +
+            shadowNote,
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Vault-relative path of the document",
+                },
+                tier: {
+                    type: "string",
+                    enum: [...TIERS],
+                    description: "The new tier",
+                },
+                reason: {
+                    type: "string",
+                    description: "Why the tier is changing (recorded in the commit and provenance)",
+                },
+                agent: agentProperty,
+                base_version: baseVersionProperty,
+            },
+            required: ["path", "tier", "reason", "agent"],
+            additionalProperties: false,
+        },
+        handler: (vaultRoot, args, access) => vaultSetTier(vaultRoot, args, access),
+    },
     {
         name: "vault_supersede",
         title: "Supersede a document",