src/tools/docs-write.ts

Functions

Imports

It imports src/auth.ts, src/canon.ts, src/doc-meta.ts, src/jobs-schema.ts, src/limits.ts, src/links.ts, src/normalize.ts, src/rule-docs.ts, src/scope.ts, src/server.ts, src/signed-docs.ts, src/store-guards.ts, src/tools/docs.ts, src/tools/surface.ts, src/write-modes.ts. Imported by src/tools/docs-lifecycle.ts, src/tools/docs.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { IMPROVE_OVERRIDE_FLAGS } from "../scope";
4import { surfaceOf } from "./surface";
5import { sha256Hex } from "../auth";
6import { auditStatement, documentUpsert, guardedCommit, snapshotLive, snapshotTaken } from "../store-guards";
7import { normalizeDashes } from "../normalize";
8import { parseLinks, type LinkEdge } from "../links";
9import { JOB_DOC_PREFIX } from "../jobs-schema";
10import { validateDocStatus, validateDocType } from "../doc-meta";
11import { bounded, MAX_BODY, MAX_DOC_STATUS, MAX_DOC_TYPE, MAX_LINKS_JSON, MAX_SHA, MAX_TAGS, MAX_TITLE, nsName, docPath } from "../limits";
12import { assembleBody } from "../write-modes";
13import { policyWriteRefusal } from "../signed-docs";
14import { concurrentEditWarning } from "../server";
15import { canonGuarded, proposeCanon } from "../canon";
16import { ruleDocWriteRefusal } from "../rule-docs";
17import { ok, fail, type ToolCtx, requireConfirmation } from "./docs";
18
19// The document tools that change the store: write, restore, delete and move.
20// defineDocOperations in ./docs registers them in the published order.
21
22export async function requireRegisteredNamespace(db: D1Database, namespace: string): Promise<string | null> {
23  const row = await db.prepare("SELECT namespace FROM namespaces WHERE namespace = ?1").bind(namespace).first();
24  if (row) return null;
25  return (
26    `unknown namespace '${namespace}'. Nothing was written. Documents can only live in a registered namespace, ` +
27    `because an unregistered one is invisible to the namespaces list, the lint loop and every repo tool. ` +
28    `Check the spelling against capsid_find_docs action namespaces, or have the admin create it with capsid_admin_manage_namespaces action register.`
29  );
30}
31
32// The policy-document check for write, restore, delete and move. First the override
33// is itself scoped: allow_improve_paths is how a caller writes a signed policy
34// document, and it is the document-side twin of the repo-side protected-path flag, so
35// it asks for the same one (IMPROVE_OVERRIDE_FLAGS in src/scope.ts). Then
36// policyWriteRefusal runs on every path the call changes, and so does the job-mirror
37// check. Returns the first refusal, or null.
38export function policyPathsRefusal(
39  ctx: ToolCtx,
40  tool: "write" | "restore" | "delete" | "move",
41  namespace: string,
42  allowImprovePaths: boolean | undefined,
43  paths: string[]
44): string | null {
45  const allow = allowImprovePaths === true;
46  if (allow) {
47    const overrideRefusal = ctx.scope({ ...surfaceOf(tool), namespace, flags: IMPROVE_OVERRIDE_FLAGS });
48    if (overrideRefusal) return overrideRefusal;
49  }
50  for (const path of paths) {
51    const refusal = policyWriteRefusal(namespace, path, allow) ?? jobMirrorRefusal(tool, namespace, path);
52    if (refusal) return refusal;
53  }
54  return null;
55}
56
57// A document under jobs/ is a job's mirror (jobDocPath in src/jobs-schema.ts): a
58// projection of the jobs row, written only by the jobs code in the same batch as the
59// row. The brief serves it as a task, so one written here could stand in for a signed job
60// that was never posted (Grok audit 2026-10, M2). No caller and no flag writes one by hand.
61function jobMirrorRefusal(tool: "write" | "restore" | "delete" | "move", namespace: string, path: string): string | null {
62  if (!path.startsWith(JOB_DOC_PREFIX)) return null;
63  return (
64    `${namespace}/${path} is under ${JOB_DOC_PREFIX}, where each document mirrors a job and is written only by capsid_work_jobs. ` +
65    `A ${tool} here is refused for every caller. Nothing changed. Change the job through capsid_work_jobs.`
66  );
67}
68
69// A supersedes or replaces edge makes the daily pass mark its target superseded
70// (src/supersede.ts), so it is a change to the target and asks what a write to the target
71// asks: the write grant on its namespace, through checkScope
72// (one enforcement point, test/scope.test.ts), and the seat for a canon document (Grok audit 2026-10, M4). Other edge
73// types change nothing and may point anywhere. The refusal, or null.
74function supersedingEdgeRefusal(ctx: ToolCtx, namespace: string, edges: LinkEdge[]): string | null {
75  for (const edge of edges) {
76    if (edge.type !== "supersedes" && edge.type !== "replaces") continue;
77    const target = `${edge.to_ns}/${edge.to_path}`;
78    if (edge.to_ns !== namespace) {
79      const refusal = ctx.scope({ ...surfaceOf("write"), grant: "write", namespace: edge.to_ns });
80      if (refusal) return `a ${edge.type} edge to ${target} marks it superseded, so it needs the write grant on ${edge.to_ns}: ${refusal} Nothing was written.`;
81    }
82    if (canonGuarded(ctx.agent, edge.to_ns, edge.to_path)) {
83      return `a ${edge.type} edge to ${target} would mark a canon document superseded, which is the seat's change to make. Nothing was written. Use references, or ask the seat.`;
84    }
85  }
86  return null;
87}
88
89export function defineWriteOperation(server: McpServer, ctx: ToolCtx): void {
90  const { db, actor } = ctx;
91
92  ctx.ops.define(
93    "write",
94    {
95      description:
96        "Create or update a document. Snapshots the prior version and writes an audit log entry. mode selects how body is applied: 'replace' (default, full body, needs title and body), 'append' (body is added to the end; no title or confirmation needed), 'patch' (needs find and replace_with; find must occur EXACTLY ONCE or the write is refused), or 'meta' (change type, tags, status or title and leave the body byte-identical). Every response carries sha256 and bytes of the resulting body. Optional if_match: the sha256 of the body you believe is stored; when it does not match, the write is REFUSED and the error carries the current sha256. Overwriting with replace or patch needs confirmation: the server elicits it when the client supports elicitation, otherwise pass confirm: true. Optional links: a JSON array of outgoing edges [{\"type\":\"references\",\"to_path\":\"conventions.md\",\"to_ns\":\"capsid\"}] (types: governs, references, supersedes, replaces, depends-on; to_ns defaults to this namespace) that replaces this document's outgoing edges; omit it to keep them, pass [] to clear them. CANON: a write to capsid/conventions*.md, any namespace's core.md, or decisions.md and its archived volumes, by a caller that is not the seat or the admin, is NOT applied: it is stored as a proposal for the seat or Dustin to approve and returns action 'pending_review' with the proposal id (links are refused on such a write). Needs the write grant.",
97      inputSchema: {
98        namespace: nsName,
99        path: docPath,
100        // title and body are required for mode 'replace' and validated as such below.
101        // They are optional in the schema because append needs no title and patch
102        // needs neither. Requiring them here would force a caller to resupply a title
103        // it is not changing.
104        title: bounded(MAX_TITLE).optional(),
105        body: bounded(MAX_BODY).optional(),
106        mode: z.enum(["replace", "append", "patch", "meta"]).optional(),
107        find: bounded(MAX_BODY).optional(),
108        replace_with: bounded(MAX_BODY).optional(),
109        type: bounded(MAX_DOC_TYPE).optional(),
110        tags: bounded(MAX_TAGS).optional(),
111        status: bounded(MAX_DOC_STATUS).optional(),
112        confirm: z.boolean().optional(),
113        links: bounded(MAX_LINKS_JSON).optional(),
114        if_match: bounded(MAX_SHA).optional(),
115        // Opt-in to writing a signed policy document (policy/). Refused without it;
116        // audit-logged with it. See policyWriteRefusal.
117        allow_improve_paths: z.boolean().optional(),
118      },
119    },
120    async ({ namespace, path, title, body, mode, find, replace_with, type, tags, status, confirm, links, if_match, allow_improve_paths }) => {
121      const writeMode = mode ?? "replace";
122      const typeError = type === undefined ? null : validateDocType(type);
123      if (typeError) return fail(typeError);
124      const statusError = status === undefined ? null : validateDocStatus(status);
125      if (statusError) return fail(statusError);
126      const parsedLinks = links === undefined ? null : parseLinks(links, namespace);
127      if (parsedLinks && "error" in parsedLinks) return fail(parsedLinks.error);
128      const edgeRefusal = parsedLinks ? supersedingEdgeRefusal(ctx, namespace, parsedLinks.edges) : null;
129      if (edgeRefusal) return fail(edgeRefusal);
130      const nsError = await requireRegisteredNamespace(db, namespace);
131      if (nsError) return fail(nsError);
132
133      const prior = await db
134        .prepare("SELECT id, title, body, type, status, tags, updated_at FROM documents WHERE namespace = ?1 AND path = ?2")
135        .bind(namespace, path)
136        .first<{ id: number; title: string | null; body: string | null; type: string | null; status: string | null; tags: string | null; updated_at: string }>();
137
138      // Optimistic concurrency. if_match is the sha256 of the body the caller believes
139      // is stored, which every write already returns. A lost update otherwise leaves
140      // no trace in the result: the write succeeds, the prior body is snapshotted, and
141      // nothing says anything went wrong. Fail closed, the same shape as a patch
142      // anchor: on mismatch nothing is written and the error carries the current sha
143      // so the caller can rebase and retry. Opt-in, because requiring it would break
144      // append, which is safe by construction.
145      const commit = guardedCommit({
146        db,
147        namespace,
148        path,
149        prior,
150        if_match,
151        refusals: {
152          ifMatchOnMissing: `if_match was given but ${namespace}/${path} does not exist. Nothing was written. Omit if_match to create it.`,
153          ifMatchMismatch: (currentSha, passed) =>
154            `if_match mismatch on ${namespace}/${path}: the stored body is not the one you read. Nothing was written. ` +
155            `Current sha256 is ${currentSha}; you passed ${passed}. ` +
156            `Re-read the document, reapply your change to the current body, and retry.`,
157          createCollision:
158            `create collision on ${namespace}/${path}: the document did not exist when this write started and it does now, so another writer created it first. ` +
159            `Nothing was written and the other writer's body is intact. ` +
160            `Re-read the document and retry as an update if you still mean to change it.`,
161          deletedInFlight: `conflict on ${namespace}/${path}: the document was deleted while this write was in flight. Nothing was written.`,
162          bodyChanged: (currentSha, elicited) =>
163            `${if_match !== undefined ? "if_match mismatch" : "stale confirmation"} on ${namespace}/${path}: the stored body changed after this write read it${elicited && if_match === undefined ? " and while the overwrite confirmation was pending" : ""}. Nothing was written. ` +
164            `Current sha256 is ${currentSha}. ` +
165            `Re-read the document, reapply your change to the current body, and retry.`,
166          batchFailed: (reason) => `write failed, nothing was written: ${reason}`,
167        },
168      });
169      const staleIfMatch = await commit.precheckIfMatch();
170      if (staleIfMatch) return fail(staleIfMatch);
171
172      // Normalize wide dashes server-side so no client can store an em dash (see
173      // ./normalize). Only the caller's text is normalized, before assembly: body for
174      // replace and append, replace_with for patch. Normalizing the assembled body
175      // would rewrite stored text the caller did not touch, which conventions.md
176      // forbids. find is not normalized, because it has to match the stored bytes.
177      // meta takes no body, so the stored body stays byte-identical.
178      if (title !== undefined) title = normalizeDashes(title, "title");
179      if (body !== undefined) body = normalizeDashes(body, "prose");
180      if (replace_with !== undefined) replace_with = normalizeDashes(replace_with, "prose");
181
182      // Body assembly, per mode (./write-modes). Every mode returns the full new body,
183      // so the write path below is the same for all of them and the version snapshot
184      // and audit row apply identically. meta returns the stored body byte-identical.
185      const assembled = assembleBody({
186        mode: writeMode,
187        exists: Boolean(prior),
188        priorBody: prior?.body ?? null,
189        title,
190        body,
191        find,
192        replace_with,
193      });
194      if ("error" in assembled) return fail(`${assembled.error} (${namespace}/${path})`);
195      body = assembled.body;
196      if (writeMode === "meta" && title === undefined && type === undefined && tags === undefined && status === undefined) {
197        return fail(`mode 'meta' needs at least one of title, type, tags or status to change (${namespace}/${path}).`);
198      }
199
200      // The policy-document guard. Refused unless allow_improve_paths was passed.
201      const policyRefusal = policyPathsRefusal(ctx, "write", namespace, allow_improve_paths, [path]);
202      if (policyRefusal) return fail(policyRefusal);
203
204      // A rule document (src/rule-docs.ts) may not be made worse: over its cap and
205      // larger than before, or naming a tool the Worker does not serve. Checked before
206      // the canon branch, so a proposal that could never be applied is refused too.
207      const ruleRefusal = ruleDocWriteRefusal(namespace, path, prior?.body ?? null, body as string);
208      if (ruleRefusal) return fail(ruleRefusal);
209
210      // Canon write-protection (src/canon.ts). A driver's write to a canon document is
211      // stored as a proposal for the seat or Dustin to approve, never applied here. It
212      // needs no overwrite confirmation, because it overwrites nothing. links are not
213      // carried by a proposal, so a canon write that sets them is refused rather than
214      // having them dropped without a word.
215      if (canonGuarded(ctx.agent, namespace, path)) {
216        if (parsedLinks) {
217          return fail(`${namespace}/${path} is canon, so this write becomes a proposal, and a proposal carries no links. Nothing was written. Write it again without links.`);
218        }
219        const proposed = await proposeCanon(db, actor, new Date(), {
220          namespace,
221          path,
222          title: title ?? null,
223          body: body as string,
224          type: type ?? null,
225          tags: tags ?? null,
226          status: status ?? null,
227          mode: writeMode,
228          priorBody: prior?.body ?? null,
229          priorExists: Boolean(prior),
230        });
231        return ok({
232          namespace,
233          path,
234          action: "pending_review",
235          proposal: proposed.id,
236          base_sha256: proposed.base_sha,
237          directive_lines: proposed.directive_lines,
238          note:
239            `${namespace}/${path} is canon (src/canon.ts). Nothing was written to it: proposal ${proposed.id} waits for the seat or Dustin to approve it in Capsid Portal. ` +
240            `It is applied only if the document is still the one you read; if it changes first, the proposal is rejected and you write it again.` +
241            (proposed.directive_lines.length ? ` ${proposed.directive_lines.length} added line(s) read as instructions to agents and are highlighted for the reviewer.` : ""),
242        });
243      }
244
245      // append and meta are exempt from confirmation. Confirmation exists to stop an
246      // accidental clobber of existing text, and an append destroys none: the prior
247      // body is still snapshotted and the addition goes after it. Requiring a confirm
248      // there would put more friction on the safe operation than on the dangerous one.
249      // patch and replace both mutate existing text and are not exempt. `elicited` is whether a human answered a prompt. It arms the commit-time body
250      // guard; why that consent goes stale is stated on requireConfirmation.
251      let elicited = false;
252      if (prior && confirm !== true && writeMode !== "append" && writeMode !== "meta") {
253        const refusal = await requireConfirmation(server, confirm, {
254          prompt: `Overwrite ${namespace}/${path}? The current version will be snapshotted to document_versions first.`,
255          declined: `overwrite of ${namespace}/${path} declined`,
256          unsupported: `confirmation required: ${namespace}/${path} already exists. Re-run capsid_write_doc with confirm: true to overwrite it. The current version will be snapshotted to document_versions first.`,
257        });
258        if (!refusal.ok) return fail(refusal.message);
259        elicited = refusal.elicited;
260      }
261      // The guard itself is armed by commit.run() below, from this same pre-read.
262      const statements: D1PreparedStatement[] = [];
263      if (prior) {
264        // Snapshot from the live row, inside the batch. Binding the pre-read body would
265        // file what this handler read, not what the table held at commit: on an
266        // unguarded update, a body written in the gap would be overwritten while the
267        // snapshot recorded its predecessor. The SELECT runs in the same transaction as
268        // the overwrite.
269        statements.push(snapshotLive(db, namespace, path));
270      }
271      statements.push(documentUpsert(db, namespace, path, title ?? null, body, type ?? null, tags ?? null, status ?? null));
272      // The prior type, status, tags and title go into the audit params whenever a
273      // write changes any of them, and this is the only place they survive:
274      // document_versions snapshots title and body only. The snapshot schema stays
275      // title plus body, because widening a version row would mean a migration plus a
276      // rewrite of every restore path to answer a question the log already answers.
277      const metaChanged = title !== undefined || type !== undefined || tags !== undefined || status !== undefined;
278      statements.push(
279        auditStatement(db, actor, "write", namespace, path, {
280          title,
281          type,
282          tags,
283          status,
284          mode: writeMode,
285          updated: Boolean(prior),
286          ...(allow_improve_paths === true ? { allow_improve_paths: true } : {}),
287          ...(prior && metaChanged
288            ? { prior_meta: { title: prior.title, type: prior.type, status: prior.status, tags: prior.tags } }
289            : {}),
290        })
291      );
292      // links replaces this document's outgoing edges when provided. Left
293      // untouched when omitted, so a routine body edit never drops edges.
294      // The edges replaced are recorded before the DELETE in the same batch, as a delete
295      // records the edges it removes, so the audit row is where they survive.
296      if (parsedLinks && "edges" in parsedLinks) {
297        statements.push(
298          db
299            .prepare(
300              `INSERT INTO audit_log (actor, action, namespace, path, params)
301               SELECT ?1, 'links', ?2, ?3, json_object('edges', ?4, 'edges_replaced', json_group_array(
302                 json_object('type', type, 'to_ns', to_ns, 'to_path', to_path)))
303               FROM document_links WHERE from_ns = ?2 AND from_path = ?3`
304            )
305            .bind(actor, namespace, path, parsedLinks.edges.length),
306          db.prepare("DELETE FROM document_links WHERE from_ns = ?1 AND from_path = ?2").bind(namespace, path)
307        );
308        for (const edge of parsedLinks.edges) {
309          statements.push(
310            db
311              .prepare(
312                "INSERT OR IGNORE INTO document_links (from_ns, from_path, type, to_ns, to_path) VALUES (?1, ?2, ?3, ?4, ?5)"
313              )
314              .bind(namespace, path, edge.type, edge.to_ns, edge.to_path)
315          );
316        }
317      }
318      // The warning is computed from a read taken here, not from the pre-read: this
319      // handler may have sat in a 90 second elicitation in between, which is when a
320      // racing write is most likely to have landed. Reading it late costs one SELECT.
321      const atCommit = prior
322        ? await db
323            .prepare("SELECT updated_at FROM documents WHERE namespace = ?1 AND path = ?2")
324            .bind(namespace, path)
325            .first<{ updated_at: string }>()
326        : null;
327      const committed = await commit.run(elicited, statements);
328      if ("refusal" in committed) return fail(committed.refusal);
329      // From the snapshot statement's own result, not from the pre-read: with no guard
330      // armed, a row deleted between the pre-read and the batch is snapshotted by
331      // nothing. The snapshot is statements[0] when present.
332      const snapshotted = Boolean(prior) && snapshotTaken(committed.results[0]);
333      // Warn, do not reject, when an edge points at a document that does not exist.
334      // Rejecting would block asserting an edge before its target is written, and a
335      // silent dangling edge is how they accumulate unnoticed. The lint loop reports
336      // these per namespace; this is the same check when the edge is created.
337      let danglingTargets: string[] = [];
338      if (parsedLinks && "edges" in parsedLinks && parsedLinks.edges.length > 0) {
339        // This read runs after the commit, so a failure here must not be reported as a
340        // failed write: the document is stored.
341        try {
342          const checks = await db.batch(
343            parsedLinks.edges.map((edge) =>
344              db
345                .prepare("SELECT 1 AS ok FROM documents WHERE namespace = ?1 AND path = ?2")
346                .bind(edge.to_ns, edge.to_path)
347            )
348          );
349          danglingTargets = parsedLinks.edges
350            .filter((_, i) => (checks[i].results?.length ?? 0) === 0)
351            .map((edge) => `${edge.to_ns}/${edge.to_path}`);
352        } catch {
353          // A failed dangling-edge read cannot fail a write that already committed.
354        }
355      }
356      // The read-back: sha256 and byte length of the body now stored, so a caller can
357      // verify the write without fetching the document and comparing it by eye. That
358      // second read would itself be a transcription, with its own chance of error.
359      // Hashes the assembled body, since D1 stores exactly what was bound.
360      const bodySha = await sha256Hex(body);
361      const bodyBytes = new TextEncoder().encode(body).length;
362
363      return ok({
364        namespace,
365        path,
366        action: prior ? "updated" : "created",
367        mode: writeMode,
368        sha256: bodySha,
369        bytes: bodyBytes,
370        ...(writeMode !== "replace" && prior
371          ? { bytes_before: new TextEncoder().encode(prior.body ?? "").length }
372          : {}),
373        snapshotted,
374        ...(prior && if_match === undefined
375          ? (() => {
376              const warning = concurrentEditWarning(atCommit?.updated_at ?? prior.updated_at, Date.now());
377              return warning ? { concurrency_warning: warning } : {};
378            })()
379          : {}),
380        ...(parsedLinks && "edges" in parsedLinks ? { links: parsedLinks.edges.length } : {}),
381        ...(danglingTargets.length
382          ? {
383              warning: `${danglingTargets.length} link target(s) do not exist as Capsid documents: ${danglingTargets.join(", ")}. The edge was still written. This is fine if the target is a repo file or is about to be created; otherwise it is a dangling edge and the lint loop will report it.`,
384            }
385          : {}),
386      });
387    }
388  );
389}