src/tools/docs-lifecycle.ts

Functions

Imports

It imports src/auth.ts, src/canon.ts, src/limits.ts, src/rule-docs.ts, src/store-guards.ts, src/tools/docs-write.ts, src/tools/docs.ts. Imported by src/tools/docs.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { sha256Hex } from "../auth";
4import { auditStatement, guardedCommit, isMissingRowAbort, requireBodyUnchanged, requireExists, snapshotLive, snapshotTaken } from "../store-guards";
5import { bounded, MAX_SHA, nsName, docPath } from "../limits";
6import { canonGuarded, canonRefusal } from "../canon";
7import { ruleDocCap, ruleDocWriteRefusal } from "../rule-docs";
8import { ok, fail, type ToolCtx, requireConfirmation, pathMutation, edgesTouching } from "./docs";
9import { policyPathsRefusal, requireRegisteredNamespace } from "./docs-write";
10
11// The document lifecycle beyond writing (src/tools/docs-write.ts writes): restore an
12// earlier version, delete, and move.
13
14export function defineRestoreOperation(server: McpServer, ctx: ToolCtx): void {
15  const { db, actor } = ctx;
16
17  ctx.ops.define(
18    "restore",
19    {
20      description:
21        "Restore a document's title and body from one of its retained versions (see capsid_read_doc action versions). The current body is snapshotted first and the restore is audit-logged, so a restore can itself be undone. The stored bytes go back exactly, with no dash normalization; type, status, tags and links are not restored. Restoring a deleted document recreates it. Refused on a canon document for a caller that is not the seat or the admin (see capsid_write_doc action write). Optional if_match: the sha256 of the body you believe is live; the restore is refused if it changed. Needs the write grant and confirm: true.",
22      inputSchema: {
23        namespace: nsName,
24        path: docPath,
25        version_id: z.number().int().positive(),
26        confirm: z.boolean().optional(),
27        if_match: bounded(MAX_SHA).optional(),
28        allow_improve_paths: z.boolean().optional(),
29      },
30    },
31    async ({ namespace, path, version_id, confirm, if_match, allow_improve_paths }) => {
32      const nsError = await requireRegisteredNamespace(db, namespace);
33      if (nsError) return fail(nsError);
34      if (canonGuarded(ctx.agent, namespace, path)) return fail(canonRefusal("restore", namespace, path));
35      const version = await db
36        .prepare("SELECT id, title, body, snapshot_at FROM document_versions WHERE id = ?1 AND namespace = ?2 AND path = ?3")
37        .bind(version_id, namespace, path)
38        .first<{ id: number; title: string | null; body: string | null; snapshot_at: string }>();
39      if (!version) return fail(`no version ${version_id} for ${namespace}/${path}`);
40      const prior = await db
41        .prepare("SELECT id, title, body FROM documents WHERE namespace = ?1 AND path = ?2")
42        .bind(namespace, path)
43        .first<{ id: number; title: string | null; body: string | null }>();
44      // The policy-document guard (see policyPathsRefusal).
45      const restorePolicyRefusal = policyPathsRefusal(ctx, "restore", namespace, allow_improve_paths, [path]);
46      if (restorePolicyRefusal) return fail(restorePolicyRefusal);
47      // A rule document is held to the same checks as a write (src/rule-docs.ts). A restore
48      // that recreates a deleted document puts back what was there, so it is judged
49      // against the version itself and passes.
50      const restoreRuleRefusal = ruleDocWriteRefusal(namespace, path, prior ? (prior.body ?? "") : (version.body ?? ""), version.body ?? "");
51      if (restoreRuleRefusal) return fail(restoreRuleRefusal);
52      // The same protocol capsid_write_doc action write runs, with restore's wordings. On the
53      // recreate path the guard is the ABSENCE of a row: the snapshot statement is
54      // only added when the pre-read saw one, so a racing create would otherwise be
55      // overwritten with nothing kept.
56      const commit = guardedCommit({
57        db,
58        namespace,
59        path,
60        prior,
61        if_match,
62        refusals: {
63          ifMatchOnMissing: `if_match was given but ${namespace}/${path} does not exist. Nothing was written. Omit if_match to recreate it from a version.`,
64          ifMatchMismatch: (currentSha, passed) =>
65            `if_match mismatch on ${namespace}/${path}: the live body is not the one you read. Nothing was restored. ` +
66            `Current sha256 is ${currentSha}; you passed ${passed}.`,
67          createCollision: `create collision on ${namespace}/${path}: it did not exist when this restore started and it does now, so another writer created it first. Nothing was written and that body is intact.`,
68          deletedInFlight: `conflict on ${namespace}/${path}: the document was deleted while this restore was in flight. Nothing was written.`,
69          bodyChanged: (currentSha) =>
70            `conflict on ${namespace}/${path}: the live body changed after this restore read it. Nothing was written. ` +
71            `Current sha256 is ${currentSha}. Re-read the versions with capsid_read_doc action versions and retry.`,
72          batchFailed: (reason) => `restore failed, nothing was written: ${reason}`,
73        },
74      });
75      const staleIfMatch = await commit.precheckIfMatch();
76      if (staleIfMatch) return fail(staleIfMatch);
77      const restoreRefusal = await requireConfirmation(server, confirm, {
78        prompt: `Restore ${namespace}/${path} to the version snapshotted at ${version.snapshot_at}? The current body will be snapshotted first.`,
79        declined: `restore of ${namespace}/${path} declined`,
80        unsupported: `confirmation required: re-run capsid_write_doc action restore with confirm: true to overwrite ${namespace}/${path} with version ${version_id} (snapshotted ${version.snapshot_at}). The current body will be snapshotted first.`,
81      });
82      if (!restoreRefusal.ok) return fail(restoreRefusal.message);
83      const elicited = restoreRefusal.elicited;
84      // The stored body goes back EXACTLY as snapshotted, with no dash normalization.
85      // A snapshot is a record of what the document said.
86      const body = version.body ?? "";
87      const statements: D1PreparedStatement[] = [];
88      if (prior) {
89        // Snapshot from the live row, inside the batch, as on write. Restore elicits a
90        // confirmation, so the gap between the read and the commit can be the full 90
91        // second prompt.
92        statements.push(snapshotLive(db, namespace, path));
93      }
94      statements.push(
95        db
96          .prepare(
97            `INSERT INTO documents (namespace, path, title, body)
98             VALUES (?1, ?2, ?3, ?4)
99             ON CONFLICT(namespace, path) DO UPDATE SET
100               title = ?3,
101               body = excluded.body,
102               updated_at = datetime('now')`
103          )
104          .bind(namespace, path, version.title, body)
105      );
106      statements.push(
107        auditStatement(db, actor, "restore", namespace, path, {
108          version_id,
109          snapshot_at: version.snapshot_at,
110          recreated: !prior,
111          snapshotted: Boolean(prior),
112        })
113      );
114      const committed = await commit.run(elicited, statements);
115      if ("refusal" in committed) return fail(committed.refusal);
116      return ok({
117        namespace,
118        path,
119        action: prior ? "restored" : "recreated",
120        version_id,
121        snapshot_at: version.snapshot_at,
122        sha256: await sha256Hex(body),
123        bytes: new TextEncoder().encode(body).length,
124        // From the snapshot statement's result, as on write.
125        snapshotted: Boolean(prior) && snapshotTaken(committed.results[0]),
126        ...(prior ? {} : { note: "the document did not exist and was recreated; its type, status, tags and links are defaults, not the ones it had" }),
127      });
128    }
129  );
130}
131
132export function defineDeleteOperation(server: McpServer, ctx: ToolCtx): void {
133  const { db, actor } = ctx;
134
135  ctx.ops.define(
136    "delete",
137    {
138      description: "Delete a document. Snapshots it first and writes an audit log entry. Refused on a canon document for a caller that is not the seat or the admin (see capsid_write_doc). Needs confirmation: the server elicits it when the client supports elicitation, otherwise pass confirm: true. Needs the write grant.",
139      inputSchema: { namespace: nsName, path: docPath, confirm: z.boolean().optional(), allow_improve_paths: z.boolean().optional() },
140    },
141    async ({ namespace, path, confirm, allow_improve_paths }) => {
142      const nsError = await requireRegisteredNamespace(db, namespace);
143      if (nsError) return fail(nsError);
144      if (canonGuarded(ctx.agent, namespace, path)) return fail(canonRefusal("delete", namespace, path));
145      const prior = await db
146        .prepare("SELECT id, title, body FROM documents WHERE namespace = ?1 AND path = ?2")
147        .bind(namespace, path)
148        .first<{ id: number; title: string | null; body: string | null }>();
149      if (!prior) return fail(`not found: ${namespace}/${path}`);
150      // The policy-document guard (see policyPathsRefusal).
151      const deletePolicyRefusal = policyPathsRefusal(ctx, "delete", namespace, allow_improve_paths, [path]);
152      if (deletePolicyRefusal) return fail(deletePolicyRefusal);
153      const deleteRefusal = await requireConfirmation(server, confirm, {
154        prompt: `Delete ${namespace}/${path}? It will be snapshotted to document_versions first, so it can be recovered.`,
155        declined: `delete of ${namespace}/${path} declined`,
156        unsupported: `confirmation required: re-run capsid_delete_doc with confirm: true to remove ${namespace}/${path}. It will be snapshotted to document_versions first.`,
157      });
158      if (!deleteRefusal.ok) return fail(deleteRefusal.message);
159      const elicited = deleteRefusal.elicited;
160      // The edges are recorded inside the batch, before pathMutation removes them, so
161      // an edge added after an earlier read is still recorded; the audit row is the
162      // only place they survive. The aggregate always yields one row ('[]' when there
163      // are no edges), and RETURNING hands the list back for the count.
164      //
165      // The guard is not redundant with the `prior` read, which is a separate
166      // transaction: a delete matching zero rows would otherwise snapshot a body, write
167      // an audit row saying 'delete', and answer "deleted" having removed nothing.
168      // After an elicitation the guard is the body one: the human consented to deleting
169      // the body they were shown, so a body written in that window must abort the
170      // delete. The snapshot itself SELECTs the live row inside the batch.
171      let edgesRemoved = 0;
172      try {
173        const results = await db.batch([
174          elicited ? requireBodyUnchanged(db, namespace, path, prior.body) : requireExists(db, namespace, path),
175          snapshotLive(db, namespace, path),
176          db
177            .prepare(
178              `INSERT INTO audit_log (actor, action, namespace, path, params)
179               SELECT ?1, 'delete', ?2, ?3, json_object('edges_removed', json_group_array(
180                 json_object('from_ns', from_ns, 'from_path', from_path, 'type', type, 'to_ns', to_ns, 'to_path', to_path)))
181               FROM document_links WHERE (from_ns = ?2 AND from_path = ?3) OR (to_ns = ?2 AND to_path = ?3)
182               RETURNING params`
183            )
184            .bind(actor, namespace, path),
185          ...pathMutation(db, namespace, path, null),
186        ]);
187        const recordedParams = (results[2]?.results?.[0] as { params?: string } | undefined)?.params;
188        if (recordedParams) edgesRemoved = (JSON.parse(recordedParams) as { edges_removed: unknown[] }).edges_removed.length;
189      } catch (err) {
190        if (isMissingRowAbort(err)) {
191          return fail(
192            elicited
193              ? `delete aborted, nothing changed: ${namespace}/${path} changed or was removed while the confirmation was open. Re-read it and try again.`
194              : `delete aborted, nothing changed: ${namespace}/${path} no longer exists. Another session removed it after this call started.`
195          );
196        }
197        return fail(`delete failed, nothing changed: ${err instanceof Error ? err.message : String(err)}`);
198      }
199      return ok({
200        namespace,
201        path,
202        action: "deleted",
203        snapshotted: true,
204        edges_removed: edgesRemoved,
205      });
206    }
207  );
208}
209
210export function defineMoveOperation(server: McpServer, ctx: ToolCtx): void {
211  const { db, actor } = ctx;
212
213  ctx.ops.define(
214    "move",
215    {
216      description: "Rename a document path within its namespace, repointing every typed edge that touches it. Audit logged. Refused when either path is a canon document, for a caller that is not the seat or the admin (see capsid_write_doc action write). Needs confirmation: the server elicits it when the client supports elicitation, otherwise pass confirm: true. Needs the write grant.",
217      inputSchema: { namespace: nsName, path: docPath, new_path: docPath, confirm: z.boolean().optional(), allow_improve_paths: z.boolean().optional() },
218    },
219    async ({ namespace, path, new_path, confirm, allow_improve_paths }) => {
220      const nsError = await requireRegisteredNamespace(db, namespace);
221      if (nsError) return fail(nsError);
222      // Both ends: moving canon away empties it, and moving a document onto a canon path
223      // that does not exist yet creates canon without review.
224      for (const end of [path, new_path]) {
225        if (canonGuarded(ctx.agent, namespace, end)) return fail(canonRefusal("move", namespace, end));
226      }
227      // Existence and the edge count are both read BEFORE the batch. D1's meta.changes
228      // cannot be used for either: documents carries FTS5 sync triggers, so an UPDATE
229      // reports the trigger's row changes too, and in a batch those accumulate across
230      // statements.
231      const exists = await db
232        .prepare("SELECT 1 AS ok FROM documents WHERE namespace = ?1 AND path = ?2")
233        .bind(namespace, path)
234        .first<{ ok: number }>();
235      if (!exists) return fail(`not found: ${namespace}/${path}`);
236      // The policy-document guard on both ends (see policyPathsRefusal).
237      const movePolicyRefusal = policyPathsRefusal(ctx, "move", namespace, allow_improve_paths, [path, new_path]);
238      if (movePolicyRefusal) return fail(movePolicyRefusal);
239      const moved = await db
240        .prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2")
241        .bind(namespace, path)
242        .first<{ body: string | null }>();
243      const movedBody = moved?.body ?? "";
244      // Moving a document onto a rule path makes it a rule document, held to the same
245      // checks as a write that creates one (src/rule-docs.ts). Moving one away is free, and
246      // so is moving a rule document to another rule path: the
247      // body is the one already held to the checks.
248      const moveRuleRefusal = ruleDocWriteRefusal(namespace, new_path, ruleDocCap(namespace, path) !== null ? movedBody : null, movedBody);
249      if (moveRuleRefusal) return fail(moveRuleRefusal);
250      // move needs confirmation: it repoints every edge and, unlike delete, leaves no
251      // snapshot of the old path, only an audit row.
252      const moveRefusal = await requireConfirmation(server, confirm, {
253        prompt: `Rename ${namespace}/${path} to ${namespace}/${new_path}? Edges pointing at the old path are repointed.`,
254        declined: `move of ${namespace}/${path} declined`,
255        unsupported: `confirmation required: re-run capsid_write_doc action move with confirm: true to rename ${namespace}/${path} to ${new_path}.`,
256      });
257      if (!moveRefusal.ok) return fail(moveRefusal.message);
258      const { results: movingEdges } = await edgesTouching(db, namespace, path).all();
259      const repointed = movingEdges.length;
260      // One batch: the guard, the rename, the edge repointing and the audit row, so a
261      // move cannot succeed without a record or be recorded without happening.
262      try {
263        await db.batch([
264          requireExists(db, namespace, path),
265          ...pathMutation(db, namespace, path, new_path),
266          auditStatement(db, actor, "move", namespace, path, { new_path, edges_repointed: repointed }),
267        ]);
268      } catch (err) {
269        if (isMissingRowAbort(err)) {
270          return fail(`move aborted, nothing changed: ${namespace}/${path} no longer exists. Another session moved or removed it after this call started.`);
271        }
272        return fail(`move failed, nothing changed (target may already exist): ${err instanceof Error ? err.message : String(err)}`);
273      }
274      return ok({ namespace, path, new_path, action: "moved", edges_repointed: repointed });
275    }
276  );
277}