daftari 1.29.0 → 1.31.0

package/dist/tools/write.js

@@ -8,24 +8,32 @@
 // Git is the version-control layer: the auto-commit *is* the document history.
 // The provenance log is a separate advisory audit trail.
 import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+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
 // ---------------------------------------------------------------------------
@@ -52,6 +60,23 @@ function requireIndexReady() {
 function collectionOf(relPath, fm) {
     return fm.collection || (relPath.split("/")[0] ?? "");
 }
+// The collection the write gate for a *new* write must key off: the top-level
+// directory the bytes physically land in, i.e. the resolved target path's first
+// path segment — NEVER the caller-declared frontmatter.collection. Honoring the
+// declared string let a role with write on collection A drop a file into
+// collection B by lying in the frontmatter (S1, 2026-07-01 review): the gate
+// checked A while `resolveVaultPath` wrote into B.
+//
+// `relPath` is lexically canonicalized against the vault root so an aliased path
+// (`competitive-intel/../pricing/x.md`) resolves to its true top-level dir
+// before the gate. This is pure path math — no disk I/O — so the check still
+// runs before we touch the target, preserving "deny before revealing anything".
+// A path that escapes the root yields a `..`-leading segment, which no role can
+// write; `resolveVaultPath` rejects it properly downstream.
+function targetCollection(vaultRoot, relPath) {
+    const rel = relative(resolve(vaultRoot), resolve(vaultRoot, relPath));
+    return rel.split(sep)[0] ?? "";
+}
 // Resolves an extension field's serializable value from the raw frontmatter:
 // the value as written, with a js-yaml Date normalized to a YYYY-MM-DD string.
 // A missing field — `undefined` or `null`, the latter matching how the
@@ -95,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,
@@ -207,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>"}`,
@@ -237,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,
@@ -283,12 +325,118 @@ 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);
+}
 // ---------------------------------------------------------------------------
 // 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)
@@ -302,6 +450,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"));
@@ -312,11 +463,15 @@ export async function vaultWrite(vaultRoot, args, access) {
     const rawFrontmatter = args.frontmatter;
     // RBAC is checked before any file I/O or frontmatter validation: an
     // unauthorized caller is denied without learning anything about the target.
+    // The gate keys off the directory the bytes physically land in (the resolved
+    // target path's top-level dir), NOT the caller-declared frontmatter.collection
+    // — otherwise a role with write on collection A could write into collection B
+    // by declaring `collection: A` while pointing `path` at B (S1). The declared
+    // 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 declared = rawFrontmatter.collection;
-        const collection = typeof declared === "string" && declared.length > 0
-            ? declared
-            : (path.value.split("/")[0] ?? "");
+        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}'`));
@@ -325,9 +480,81 @@ export async function vaultWrite(vaultRoot, args, access) {
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
-    const existing = await readFile(resolved.value);
+    // #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) {
@@ -342,9 +569,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,
@@ -367,6 +607,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.
@@ -433,10 +686,13 @@ export async function vaultWrite(vaultRoot, args, access) {
         updated: todayISO(),
         updated_by: agent.value,
     };
-    return performWrite({
+    const written = await performWrite({
         vaultRoot,
-        relPath: path.value,
-        absPath: resolved.value,
+        // 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,
         agent: agent.value,
         tool: "vault_write",
         action: isUpdate ? "update" : "create",
@@ -450,6 +706,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 } : {}),
     });
 }
 // ---------------------------------------------------------------------------
@@ -473,10 +754,16 @@ 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;
-    const existing = await readFile(resolved.value);
+    const existing = await readFile(resolved.value.absPath);
     if (!existing.ok) {
         return err(new Error(`vault_append: document not found: ${path.value}`));
     }
@@ -522,10 +809,13 @@ 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,
-        relPath: path.value,
-        absPath: resolved.value,
+        // 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,
         agent: agent.value,
         tool: "vault_append",
         action: "append",
@@ -539,7 +829,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
@@ -551,6 +860,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;
@@ -566,7 +878,7 @@ export async function vaultPromote(vaultRoot, args, access) {
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
-    const existing = await readFile(resolved.value);
+    const existing = await readFile(resolved.value.absPath);
     if (!existing.ok) {
         return err(new Error(`vault_promote: document not found: ${path.value}`));
     }
@@ -603,8 +915,11 @@ export async function vaultPromote(vaultRoot, args, access) {
     };
     return performWrite({
         vaultRoot,
-        relPath: path.value,
-        absPath: resolved.value,
+        // 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,
         agent: agent.value,
         tool: "vault_promote",
         action: "promote",
@@ -618,6 +933,7 @@ export async function vaultPromote(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        bodyChanged: false,
     });
 }
 // ---------------------------------------------------------------------------
@@ -630,6 +946,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;
@@ -652,7 +971,7 @@ export async function vaultDeprecate(vaultRoot, args, access) {
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
-    const existing = await readFile(resolved.value);
+    const existing = await readFile(resolved.value.absPath);
     if (!existing.ok) {
         return err(new Error(`vault_deprecate: document not found: ${path.value}`));
     }
@@ -680,8 +999,11 @@ export async function vaultDeprecate(vaultRoot, args, access) {
     };
     return performWrite({
         vaultRoot,
-        relPath: path.value,
-        absPath: resolved.value,
+        // 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,
         agent: agent.value,
         tool: "vault_deprecate",
         action: "deprecate",
@@ -696,6 +1018,7 @@ export async function vaultDeprecate(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        bodyChanged: false,
     });
 }
 // ---------------------------------------------------------------------------
@@ -709,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;
@@ -730,7 +1056,7 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
     const resolved = resolveVaultPath(vaultRoot, path.value);
     if (!resolved.ok)
         return resolved;
-    const existing = await readFile(resolved.value);
+    const existing = await readFile(resolved.value.absPath);
     if (!existing.ok) {
         return err(new Error(`vault_set_confidence: document not found: ${path.value}`));
     }
@@ -772,8 +1098,11 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
     };
     return performWrite({
         vaultRoot,
-        relPath: path.value,
-        absPath: resolved.value,
+        // 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,
         agent: agent.value,
         tool: "vault_set_confidence",
         action: "confidence-set",
@@ -788,6 +1117,112 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        bodyChanged: false,
+    });
+}
+// ---------------------------------------------------------------------------
+// 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 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}'`));
+        }
+    }
+    // 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 = parsed.value.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({
+        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,
+        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,
+        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,
     });
 }
 // ---------------------------------------------------------------------------
@@ -801,6 +1236,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;
@@ -831,12 +1269,12 @@ export async function vaultSupersede(vaultRoot, args, access) {
     const resolvedNew = resolveVaultPath(vaultRoot, newPath.value);
     if (!resolvedNew.ok)
         return resolvedNew;
-    const existing = await readFile(resolvedOld.value);
+    const existing = await readFile(resolvedOld.value.absPath);
     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);
+    const successor = await readFile(resolvedNew.value.absPath);
     if (!successor.ok) {
         return err(new Error(`vault_supersede: successor not found: ${newPath.value}`));
     }
@@ -864,8 +1302,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
     };
     return performWrite({
         vaultRoot,
-        relPath: oldPath.value,
-        absPath: resolvedOld.value,
+        // Canonical relPath keys the lock/provenance/commit (#127/#128).
+        relPath: resolvedOld.value.relPath,
+        absPath: resolvedOld.value.absPath,
         agent: agent.value,
         tool: "vault_supersede",
         action: "supersede",
@@ -880,6 +1319,7 @@ export async function vaultSupersede(vaultRoot, args, access) {
         baseVersion: baseVersion.value,
         shadowMode: config.value.shadowMode,
         principal: access?.user,
+        bodyChanged: false,
     });
 }
 // Combines two source documents into a target and supersedes both sources to
@@ -896,6 +1336,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;
@@ -921,11 +1364,11 @@ export async function vaultMerge(vaultRoot, args, access) {
         ? 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).
+    // CANONICAL relPath, never the raw caller strings: `pricing/a.md`,
+    // `./pricing/a.md`, and a symlink alias all name the same file but differ as
+    // strings (and as absPaths, for a symlink), 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;
@@ -935,13 +1378,13 @@ export async function vaultMerge(vaultRoot, args, access) {
     const resolvedTarget = resolveVaultPath(vaultRoot, targetPath.value);
     if (!resolvedTarget.ok)
         return resolvedTarget;
-    if (resolvedA.value === resolvedB.value) {
+    if (resolvedA.value.relPath === resolvedB.value.relPath) {
         return err(new Error("vault_merge: path_a and path_b must differ"));
     }
-    const existingA = await readFile(resolvedA.value);
+    const existingA = await readFile(resolvedA.value.absPath);
     if (!existingA.ok)
         return err(new Error(`vault_merge: document not found: ${pathA.value}`));
-    const existingB = await readFile(resolvedB.value);
+    const existingB = await readFile(resolvedB.value.absPath);
     if (!existingB.ok)
         return err(new Error(`vault_merge: document not found: ${pathB.value}`));
     const parsedA = parseDocument(existingA.value);
@@ -957,20 +1400,17 @@ export async function vaultMerge(vaultRoot, args, access) {
     // 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;
+        // path_a and path_b are gated on their existing on-disk collections. The
+        // target is gated on the directory the merged bytes physically land in — the
+        // resolved target path's top-level dir — NOT the caller-declared collection
+        // (override or path_a's raw value). Keying the target gate off a declared
+        // string let a role with write on collection A write the merge result into
+        // collection B by pointing target_path at B while declaring `collection: A`
+        // (S1, same shape as vault_write).
         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] ?? ""),
+            targetCollection(vaultRoot, targetPath.value),
         ];
         for (const collection of collections) {
             if (!canWrite(access.role, collection)) {
@@ -983,16 +1423,33 @@ export async function vaultMerge(vaultRoot, args, access) {
     // 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);
+    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",
@@ -1016,21 +1473,35 @@ export async function vaultMerge(vaultRoot, args, access) {
     // the target is superseded to point at the target.
     const writes = [];
     writes.push({
-        relPath: targetPath.value,
-        absPath: resolvedTarget.value,
+        // Canonical relPath keys the per-file lock, provenance, and commit path so
+        // aliased spellings collapse to one lock (#127/#128).
+        relPath: resolvedTarget.value.relPath,
+        absPath: resolvedTarget.value.absPath,
         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 },
+        {
+            path: pathA.value,
+            abs: resolvedA.value.absPath,
+            rel: resolvedA.value.relPath,
+            parsed: parsedA.value,
+        },
+        {
+            path: pathB.value,
+            abs: resolvedB.value.absPath,
+            rel: resolvedB.value.relPath,
+            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)
+        // Compare canonical relPaths, not raw strings or absPaths: a source that
+        // aliases the target — lexically (`./pricing/a.md`) OR via a symlink — is
+        // the fold-into-A case: write it once with the merged body, never supersede
+        // it. A symlink alias has a distinct absPath, so an absPath compare would
+        // miss it and clobber the merged body with the superseded write (#127/#128).
+        if (source.rel === resolvedTarget.value.relPath)
             continue;
         const supersededFm = {
             ...source.parsed.frontmatter,
@@ -1040,7 +1511,7 @@ export async function vaultMerge(vaultRoot, args, access) {
             updated_by: agent.value,
         };
         writes.push({
-            relPath: source.path,
+            relPath: source.rel,
             absPath: source.abs,
             fileText: serializeDocument(supersededFm, source.parsed.content, extensions, source.parsed.raw),
             newFrontmatter: supersededFm,
@@ -1128,6 +1599,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),
             });
         }
@@ -1173,6 +1647,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`
@@ -1262,7 +1741,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",
@@ -1275,6 +1762,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,
@@ -1286,7 +1779,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",
@@ -1301,6 +1797,7 @@ export const writeTools = [
                 },
                 agent: agentProperty,
                 base_version: baseVersionProperty,
+                run_id: runIdProperty,
             },
             required: ["path", "section", "agent"],
             additionalProperties: false,
@@ -1392,6 +1889,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",