src/namespace-delete.ts

Functions

Imports

It imports src/auth.ts, src/env.ts, src/jobs-schema.ts, src/limits.ts, src/namespace-delete-token.ts, src/roster.ts, src/signed-docs.ts, src/store-guards.ts, src/tools/docs.ts. Imported by src/tools/namespaces.ts.

Source

1import { sha256Hex } from "./auth";
2import type { Env } from "./env";
3import { onRoster } from "./roster";
4import { POLICY_PREFIX } from "./signed-docs";
5import { OPEN_JOB_STATUSES } from "./jobs-schema";
6import { D1_BATCH_STATEMENTS } from "./limits";
7import { isMissingRowAbort } from "./store-guards";
8import { pathMutation } from "./tools/docs";
9import { signDeleteToken, type Verified, verifyDeleteToken } from "./namespace-delete-token";
10
11// Deleting a namespace (capsid_admin_manage_namespaces actions delete_preview and
12// delete_perform): the plan, the refusals, the signed confirmation and the one batch.
13// Its operation is registered in src/tools/namespaces.ts, admin only (TOOL_GRANTS in
14// src/scope.ts). Ruled 2026-09-29, "Capsid MCP roadmap, build or don't build".
15//
16// Two calls, as the Portal's controls are (src/portal-actions.ts). The preview reads
17// everything that names the namespace, writes nothing, and when nothing refuses returns
18// a token signed over the namespace, cascade, allow_improve_paths, the plan's counts,
19// the caller's actor and a five-minute expiry. The perform re-reads the plan, requires
20// the token to match it exactly, and commits one batch whose first statement aborts it
21// unless the store still is what the plan read.
22//
23// WHAT IS DELETED: every live document (any path not under archive/), each snapshotted
24// to document_versions inside the batch before it goes and removed by
25// pathMutation(db, ns, path, null), the one path mutation site
26// (path mutation invariant, test/path-mutation.test.ts); every edge touching one of those documents, removed by the same
27// helper and recorded whole in the audit row; the ops_sites row and the
28// access_sync_groups pin, each recorded whole in the audit row; and the namespaces row.
29//
30// WHAT IS KEPT, because it is history: archived documents (archive/...), every
31// document_versions and audit_log row, finished jobs, job_outcomes, job_claims,
32// job_touches, revoked agents that name the namespace, and the nightly backup
33// objects. The kept
34// archived documents still name a namespace that is no longer registered. The read
35// tools (capsid_read_doc, capsid_find_docs, capsid_start_session) still return them by
36// that name; capsid_write_doc and capsid_delete_doc refuse there until the namespace is registered again, and a
37// later capsid_admin_manage_namespaces action register of the same name brings them back into scope.
38//
39// WHAT ALWAYS REFUSES, whatever cascade says: an open job (queued, claimed, blocked),
40// a live agent whose scopes name the namespace, and a namespace on the roster.
41// cascade reaches documents only. A namespace with more live documents than one batch
42// can delete (NAMESPACE_DELETE_MAX_DOCUMENTS) is refused too, never half deleted.
43//
44// An edge whose end in this namespace names a path no document holds (already
45// dangling) touches no deleted document, so pathMutation leaves it, as a document
46// delete would; docs/schema.md, "Links", says dangling edges are reported, never
47// repaired.
48
49// The statements every perform batch carries besides the per-document ones: the plan
50// guard, the snapshot, the audit row, the ops_sites delete, the access_sync_groups
51// delete and the namespaces delete.
52const FIXED_STATEMENTS = 6;
53// pathMutation(db, ns, path, null) is two statements: the edges, then the row.
54const STATEMENTS_PER_DOCUMENT = 2;
55/** The most live documents one delete_namespace batch can remove, from D1's batch
56 *  ceiling (D1_BATCH_STATEMENTS in src/limits.ts). */
57export const NAMESPACE_DELETE_MAX_DOCUMENTS = Math.floor((D1_BATCH_STATEMENTS - FIXED_STATEMENTS) / STATEMENTS_PER_DOCUMENT);
58
59const DELETE_TOKEN_TTL_SECONDS = 5 * 60;
60// How many of each blocker a refusal names. The counts are always whole.
61const NAMED = 20;
62
63export interface PlanCounts {
64  documents_live: number;
65  documents_archived: number;
66  document_versions: number;
67  audit_log: number;
68  document_links_removed: number;
69  jobs_open: number;
70  jobs_finished: number;
71  job_outcomes: number;
72  job_claims: number;
73  job_touches: number;
74  agents_live: number;
75  agents_revoked: number;
76  policy_documents: number;
77}
78
79export interface DeletePlan {
80  namespace: string;
81  registered: boolean;
82  on_roster: boolean;
83  counts: PlanCounts;
84  jobs_by_status: Record<string, number>;
85  // The whole ops_sites row, or null when the namespace has none.
86  ops_site: Record<string, unknown> | null;
87  ops_site_revision: number | null;
88  open_jobs: Array<{ id: string; status: string; title: string }>;
89  live_agents: string[];
90  policy_paths: string[];
91  // Every live path in path order, at most NAMESPACE_DELETE_MAX_DOCUMENTS + 1 of them:
92  // one more than fits says the namespace is over the cap. The perform deletes exactly
93  // these, and the token binds them, so a document swapped for another refuses.
94  live_paths: string[];
95  // sha256 of JSON.stringify(live_paths), which is what the fingerprint binds.
96  live_paths_sha256: string;
97}
98
99export interface DeleteOptions {
100  cascade: boolean;
101  // allow_improve_paths keeps its name from the improve loop; it now covers only the
102  // signed policy documents (policyWriteRefusal in src/signed-docs.ts).
103  allowImprovePaths: boolean;
104}
105
106function count(result: D1Result | undefined): number {
107  const row = result?.results?.[0] as { n?: number } | undefined;
108  return Number(row?.n ?? 0);
109}
110
111function rows<T>(result: D1Result | undefined): T[] {
112  return (result?.results ?? []) as T[];
113}
114
115/** Everything that names the namespace, read in one batch so the counts agree with
116 *  each other. Writes nothing. */
117export async function readDeletePlan(db: D1Database, namespace: string): Promise<DeletePlan> {
118  const open = JSON.stringify(OPEN_JOB_STATUSES);
119  const results = await db.batch([
120    db.prepare("SELECT namespace FROM namespaces WHERE namespace = ?1").bind(namespace),
121    db.prepare("SELECT COUNT(*) AS n FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%'").bind(namespace),
122    db.prepare("SELECT COUNT(*) AS n FROM documents WHERE namespace = ?1 AND path LIKE 'archive/%'").bind(namespace),
123    db.prepare("SELECT COUNT(*) AS n FROM document_versions WHERE namespace = ?1").bind(namespace),
124    db.prepare("SELECT COUNT(*) AS n FROM audit_log WHERE namespace = ?1").bind(namespace),
125    // The edges pathMutation will remove: those touching a live document.
126    db
127      .prepare(
128        `SELECT COUNT(*) AS n FROM document_links
129         WHERE (from_ns = ?1 AND from_path IN (SELECT path FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%'))
130            OR (to_ns = ?1 AND to_path IN (SELECT path FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%'))`
131      )
132      .bind(namespace),
133    db.prepare("SELECT status, COUNT(*) AS n FROM jobs WHERE namespace = ?1 GROUP BY status").bind(namespace),
134    db
135      .prepare(
136        `SELECT id, status, title FROM jobs
137         WHERE namespace = ?1 AND status IN (SELECT value FROM json_each(?2))
138         ORDER BY created_at, id LIMIT 20`
139      )
140      .bind(namespace, open),
141    db.prepare("SELECT COUNT(*) AS n FROM job_outcomes WHERE namespace = ?1").bind(namespace),
142    db.prepare("SELECT COUNT(*) AS n FROM job_claims WHERE namespace = ?1").bind(namespace),
143    db.prepare("SELECT COUNT(*) AS n FROM job_touches WHERE namespace = ?1").bind(namespace),
144    // The same reading of the scopes column as parseScopes (src/agents-schema.ts): a
145    // row that is not a JSON object with a namespaces array names no namespace. The
146    // nested CASE fixes the evaluation order, so json_type never sees malformed JSON.
147    db
148      .prepare(
149        `SELECT name, revoked_at FROM agents
150         WHERE CASE WHEN json_valid(scopes) THEN
151           CASE WHEN json_type(scopes) = 'object' AND json_type(scopes, '$.namespaces') = 'array'
152             THEN EXISTS (SELECT 1 FROM json_each(scopes, '$.namespaces') WHERE value = ?1) ELSE 0 END
153         ELSE 0 END
154         ORDER BY name`
155      )
156      .bind(namespace),
157    // The signed policy documents (policyWriteRefusal in src/signed-docs.ts), matched
158    // case-exactly on the same prefix. Deleting one is a ruling, so it needs
159    // allow_improve_paths as a document delete does.
160    db.prepare("SELECT COUNT(*) AS n FROM documents WHERE namespace = ?1 AND substr(path, 1, length(?2)) = ?2").bind(namespace, POLICY_PREFIX),
161    db
162      .prepare("SELECT path FROM documents WHERE namespace = ?1 AND substr(path, 1, length(?2)) = ?2 ORDER BY path LIMIT 20")
163      .bind(namespace, POLICY_PREFIX),
164    db
165      .prepare(
166        `SELECT namespace, name, origin, health_path, platform, script, self_probe, revision, created_at, updated_at
167         FROM ops_sites WHERE namespace = ?1`
168      )
169      .bind(namespace),
170    db
171      .prepare("SELECT path FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%' ORDER BY path LIMIT ?2")
172      .bind(namespace, NAMESPACE_DELETE_MAX_DOCUMENTS + 1),
173  ]);
174
175  const jobsByStatus: Record<string, number> = {};
176  for (const row of rows<{ status: string; n: number }>(results[6])) jobsByStatus[row.status] = Number(row.n);
177  let jobsOpen = 0;
178  let jobsFinished = 0;
179  for (const [status, n] of Object.entries(jobsByStatus)) {
180    if ((OPEN_JOB_STATUSES as readonly string[]).includes(status)) jobsOpen += n;
181    else jobsFinished += n;
182  }
183  const agents = rows<{ name: string; revoked_at: string | null }>(results[11]);
184  const live = agents.filter((a) => a.revoked_at === null).map((a) => a.name);
185  const site = rows<Record<string, unknown>>(results[14])[0] ?? null;
186
187  const livePaths = rows<{ path: string }>(results[15]).map((r) => r.path);
188  return {
189    namespace,
190    registered: rows(results[0]).length > 0,
191    on_roster: onRoster(namespace),
192    counts: {
193      documents_live: count(results[1]),
194      documents_archived: count(results[2]),
195      document_versions: count(results[3]),
196      audit_log: count(results[4]),
197      document_links_removed: count(results[5]),
198      jobs_open: jobsOpen,
199      jobs_finished: jobsFinished,
200      job_outcomes: count(results[8]),
201      job_claims: count(results[9]),
202      job_touches: count(results[10]),
203      agents_live: live.length,
204      agents_revoked: agents.length - live.length,
205      policy_documents: count(results[12]),
206    },
207    jobs_by_status: jobsByStatus,
208    ops_site: site,
209    ops_site_revision: site ? Number(site.revision) : null,
210    open_jobs: rows<{ id: string; status: string; title: string }>(results[7]),
211    live_agents: live,
212    live_paths: livePaths,
213    live_paths_sha256: await sha256Hex(JSON.stringify(livePaths)),
214    policy_paths: rows<{ path: string }>(results[13]).map((r) => r.path),
215  };
216}
217
218// The first NAMED entries, and how many more the count holds.
219function named(list: string[], total: number): string {
220  const shown = list.slice(0, NAMED);
221  const rest = total - shown.length;
222  return rest > 0 ? `${shown.join(", ")}, and ${rest} more` : shown.join(", ");
223}
224
225/** Why the delete may not happen, or an empty list. Pure. An unregistered namespace
226 *  is the only refusal, since nothing else about it matters. */
227export function deleteRefusals(plan: DeletePlan, opts: DeleteOptions): string[] {
228  const ns = plan.namespace;
229  if (!plan.registered) return [`namespace not found: ${ns}. There is no registered namespace to delete.`];
230  const refusals: string[] = [];
231  if (plan.on_roster) {
232    refusals.push(
233      `${ns} is on the roster (ROSTER in src/roster.ts), which the watcher, auto-merge and maintenance iterate by name. Remove it from the roster in code first; this tool will not.`
234    );
235  }
236  if (plan.counts.jobs_open > 0) {
237    const jobs = plan.open_jobs.map((j) => `${j.id} (${j.status}, '${j.title}')`);
238    refusals.push(
239      `${ns} has ${plan.counts.jobs_open} open job${plan.counts.jobs_open === 1 ? "" : "s"}: ${named(jobs, plan.counts.jobs_open)}. ` +
240        `cascade never reaches jobs. End each with the capsid_work_jobs tool: action 'supersede' for a queued job, action 'fail' for a claimed or blocked one (the admin may fail a job another credential holds), or 'release' then 'supersede'.`
241    );
242  }
243  if (plan.counts.agents_live > 0) {
244    refusals.push(
245      `${plan.counts.agents_live} live agent${plan.counts.agents_live === 1 ? " names" : "s name"} ${ns} in its scopes: ${named(plan.live_agents, plan.counts.agents_live)}. ` +
246        `cascade never reaches agents. Use the capsid_admin_manage_agents tool: action 'revoke', or action 'update_scopes' to drop ${ns} from its namespaces.`
247    );
248  }
249  if (plan.counts.documents_live > NAMESPACE_DELETE_MAX_DOCUMENTS) {
250    refusals.push(
251      `${ns} holds ${plan.counts.documents_live} live documents, and one delete_namespace batch deletes at most ${NAMESPACE_DELETE_MAX_DOCUMENTS} ` +
252        `(D1's ${D1_BATCH_STATEMENTS}-statement batch ceiling: ${FIXED_STATEMENTS} fixed statements plus ${STATEMENTS_PER_DOCUMENT} per document). ` +
253        `Delete documents with capsid_delete_doc, or move them with capsid_write_doc action move, first, or ask the seat to rule a set-based helper.`
254    );
255  }
256  if (plan.counts.documents_live > 0 && !opts.cascade) {
257    refusals.push(
258      `${ns} holds ${plan.counts.documents_live} live document${plan.counts.documents_live === 1 ? "" : "s"}. Pass cascade: true to delete them; each is snapshotted to document_versions first. Archived documents (archive/...) are kept either way.`
259    );
260  }
261  if (plan.counts.policy_documents > 0 && !opts.allowImprovePaths) {
262    refusals.push(
263      `${ns} holds ${plan.counts.policy_documents} signed policy document${plan.counts.policy_documents === 1 ? "" : "s"} (${named(plan.policy_paths, plan.counts.policy_documents)}). ` +
264        `Deleting one is a ruling, so it needs allow_improve_paths: true, which needs the can_touch_protected flag and is audit-logged.`
265    );
266  }
267  return refusals;
268}
269
270/** The part of the plan a token binds, in one canonical spelling: every count, the
271 *  jobs by status, the ops_sites revision and the sha256 of the
272 *  live path list (a digest, so fifty 512-character paths do not ride in the token).
273 *  Any change between the preview and the perform changes this string. */
274export function planFingerprint(plan: DeletePlan): string {
275  const counts: Record<string, number> = {};
276  for (const key of Object.keys(plan.counts).sort()) counts[key] = plan.counts[key as keyof PlanCounts];
277  const jobs: Record<string, number> = {};
278  for (const key of Object.keys(plan.jobs_by_status).sort()) jobs[key] = plan.jobs_by_status[key];
279  return JSON.stringify({
280    counts,
281    jobs_by_status: jobs,
282    ops_site_revision: plan.ops_site_revision,
283    live_paths_sha256: plan.live_paths_sha256,
284  });
285}
286
287/** The keys of two fingerprints that differ, for the refusal. Pure. */
288export function fingerprintDifference(signed: string, current: string): string[] {
289  let a: Record<string, unknown>;
290  let b: Record<string, unknown>;
291  try {
292    a = JSON.parse(signed) as Record<string, unknown>;
293    b = JSON.parse(current) as Record<string, unknown>;
294  } catch {
295    return ["the plan"];
296  }
297  const flat = (o: Record<string, unknown>): Record<string, string> => {
298    const out: Record<string, string> = {};
299    for (const [k, v] of Object.entries(o)) {
300      if (v && typeof v === "object" && !Array.isArray(v)) for (const [k2, v2] of Object.entries(v)) out[`${k}.${k2}`] = JSON.stringify(v2);
301      else out[k] = JSON.stringify(v);
302    }
303    return out;
304  };
305  const fa = flat(a);
306  const fb = flat(b);
307  const keys = [...new Set([...Object.keys(fa), ...Object.keys(fb)])].sort();
308  return keys.filter((k) => fa[k] !== fb[k]).map((k) => `${k} ${fa[k] ?? "absent"} -> ${fb[k] ?? "absent"}`);
309}
310
311// ---- Preview and perform ------------------------------------------------------------
312
313function summarize(plan: DeletePlan): { will_delete: string[]; will_keep: string[] } {
314  const c = plan.counts;
315  return {
316    will_delete: [
317      `${c.documents_live} live document(s), each snapshotted to document_versions first`,
318      `${c.document_links_removed} edge(s) touching those documents, recorded whole in the audit row (an already dangling edge touches none and stays)`,
319      plan.ops_site ? `the ops_sites row (revision ${plan.ops_site_revision}), recorded whole in the audit row` : "no ops_sites row (there is none)",
320      "the access_sync_groups pin, if any, recorded whole in the audit row",
321      `the namespaces row and its repo mapping, recorded in the audit row`,
322    ],
323    will_keep: [
324      `${c.documents_archived} archived document(s) under archive/, still readable by this namespace name; write, delete, move and restore refuse there until the namespace is registered again`,
325      `${c.document_versions} document_versions row(s) and ${c.audit_log} audit_log row(s)`,
326      `${c.jobs_finished} finished job(s), ${c.job_outcomes} job_outcomes, ${c.job_claims} job_claims, ${c.job_touches} job_touches row(s)`,
327      `${c.agents_revoked} revoked agent(s) that name it`,
328      "the nightly backup objects",
329    ],
330  };
331}
332
333export type ToolAnswer = { ok: true; data: unknown } | { ok: false; refusal: string };
334
335export async function previewNamespaceDelete(
336  env: Env,
337  actor: string,
338  namespace: string,
339  opts: DeleteOptions,
340  now: Date
341): Promise<ToolAnswer> {
342  let plan: DeletePlan;
343  try {
344    plan = await readDeletePlan(env.DB, namespace);
345  } catch (err) {
346    return { ok: false, refusal: `delete_namespace preview failed, nothing changed: ${err instanceof Error ? err.message : String(err)}` };
347  }
348  const refusals = deleteRefusals(plan, opts);
349  if (!plan.registered) return { ok: false, refusal: refusals[0] };
350  const base = {
351    namespace,
352    action: "preview",
353    verdict: refusals.length ? "refused" : "allowed",
354    refusals,
355    cascade: opts.cascade,
356    allow_improve_paths: opts.allowImprovePaths,
357    counts: plan.counts,
358    jobs_by_status: plan.jobs_by_status,
359    open_jobs: plan.open_jobs,
360    live_agents: plan.live_agents,
361    live_paths: plan.live_paths,
362    max_documents: NAMESPACE_DELETE_MAX_DOCUMENTS,
363    policy_paths: plan.policy_paths,
364    ops_site: plan.ops_site,
365    ...summarize(plan),
366  };
367  if (refusals.length) return { ok: true, data: base };
368  const exp = Math.floor(now.getTime() / 1000) + DELETE_TOKEN_TTL_SECONDS;
369  let token: string;
370  try {
371    token = await signDeleteToken(env, {
372      v: 1,
373      namespace,
374      cascade: opts.cascade,
375      allow_improve_paths: opts.allowImprovePaths,
376      actor,
377      plan: planFingerprint(plan),
378      exp,
379    });
380  } catch (err) {
381    return { ok: false, refusal: `delete_namespace preview failed, nothing changed: ${err instanceof Error ? err.message : String(err)}` };
382  }
383  return {
384    ok: true,
385    data: {
386      ...base,
387      token,
388      expires_at: new Date(exp * 1000).toISOString(),
389      next: `Call capsid_admin_manage_namespaces with action 'delete_perform', the same namespace, cascade and allow_improve_paths, and this token within five minutes. Any change to what the preview counted refuses it.`,
390    },
391  };
392}
393
394// The batch's first statement: an INSERT that violates NOT NULL (the same abort as
395// requireExists in src/store-guards.ts), fired unless the store is still what the plan
396// read. The preview's reads are another transaction, so this is what makes the
397// refusals and the counts hold at commit. The live set is pinned exactly: the count
398// equals the plan's, and no live path lies outside the plan's list (?6, JSON), so a
399// document swapped for another in between aborts too, and every live document the
400// batch finds is one pathMutation below deletes.
401function planGuard(db: D1Database, plan: DeletePlan, pathsJson: string): D1PreparedStatement {
402  return db
403    .prepare(
404      `INSERT INTO document_versions (document_id, namespace, path)
405       SELECT NULL, ?1, 'delete_namespace'
406       WHERE NOT (
407         EXISTS (SELECT 1 FROM namespaces WHERE namespace = ?1)
408         AND (SELECT COUNT(*) FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%') = ?2
409         AND NOT EXISTS (SELECT 1 FROM documents WHERE namespace = ?1 AND path NOT LIKE 'archive/%'
410                         AND path NOT IN (SELECT value FROM json_each(?6)))
411         AND (SELECT COUNT(*) FROM document_links
412              WHERE (from_ns = ?1 AND from_path IN (SELECT value FROM json_each(?6)))
413                 OR (to_ns = ?1 AND to_path IN (SELECT value FROM json_each(?6)))) = ?3
414         AND NOT EXISTS (SELECT 1 FROM jobs WHERE namespace = ?1 AND status IN (SELECT value FROM json_each(?4)))
415         AND NOT EXISTS (SELECT 1 FROM agents WHERE revoked_at IS NULL AND
416           CASE WHEN json_valid(scopes) THEN
417             CASE WHEN json_type(scopes) = 'object' AND json_type(scopes, '$.namespaces') = 'array'
418               THEN EXISTS (SELECT 1 FROM json_each(scopes, '$.namespaces') WHERE value = ?1) ELSE 0 END
419           ELSE 0 END)
420         AND (SELECT revision FROM ops_sites WHERE namespace = ?1) IS ?5
421       )`
422    )
423    .bind(
424      plan.namespace,
425      plan.counts.documents_live,
426      plan.counts.document_links_removed,
427      JSON.stringify(OPEN_JOB_STATUSES),
428      plan.ops_site_revision,
429      pathsJson
430    );
431}
432
433/**
434 * The perform: the token, the plan read again, then one batch. Each live document is
435 * deleted by pathMutation(db, namespace, path, null), the one site that deletes a
436 * documents row (path mutation invariant, test/path-mutation.test.ts), so the batch is FIXED_STATEMENTS plus
437 * two per document and the cap refuses anything larger before it is built.
438 */
439export async function performNamespaceDelete(
440  env: Env,
441  actor: string,
442  namespace: string,
443  opts: DeleteOptions,
444  token: string | undefined,
445  now: Date
446): Promise<ToolAnswer> {
447  const db = env.DB;
448  if (typeof token !== "string" || token.length === 0) {
449    return { ok: false, refusal: "delete_perform needs the token capsid_admin_manage_namespaces action delete_preview returned. Preview first." };
450  }
451  let verified: Verified;
452  try {
453    verified = await verifyDeleteToken(env, token, { actor, namespace, cascade: opts.cascade, allowImprovePaths: opts.allowImprovePaths }, now);
454  } catch (err) {
455    return { ok: false, refusal: `delete_namespace refused, nothing changed: ${err instanceof Error ? err.message : String(err)}` };
456  }
457  if (!verified.ok) return { ok: false, refusal: `delete_namespace refused, nothing changed: ${verified.refusal}` };
458
459  let plan: DeletePlan;
460  try {
461    plan = await readDeletePlan(db, namespace);
462  } catch (err) {
463    return { ok: false, refusal: `delete_namespace failed, nothing changed: ${err instanceof Error ? err.message : String(err)}` };
464  }
465  const refusals = deleteRefusals(plan, opts);
466  if (refusals.length) return { ok: false, refusal: `delete_namespace refused, nothing changed: ${refusals.join(" ")}` };
467  const current = planFingerprint(plan);
468  if (current !== verified.claims.plan) {
469    const changed = fingerprintDifference(verified.claims.plan, current);
470    return {
471      ok: false,
472      refusal: `delete_namespace refused, nothing changed: the namespace changed since the preview (${changed.join("; ")}). Preview again.`,
473    };
474  }
475  // The cap is in deleteRefusals, so this holds already; checked again because the
476  // batch below is sized from this list, and a list the read truncated would delete
477  // part of the namespace.
478  const paths = plan.live_paths;
479  if (paths.length !== plan.counts.documents_live || paths.length > NAMESPACE_DELETE_MAX_DOCUMENTS) {
480    return {
481      ok: false,
482      refusal: `delete_namespace failed, nothing changed: the plan read ${paths.length} live paths for ${plan.counts.documents_live} live documents, with a cap of ${NAMESPACE_DELETE_MAX_DOCUMENTS}.`,
483    };
484  }
485  const pathsJson = JSON.stringify(paths);
486  const deletion = paths.flatMap((path) => pathMutation(db, namespace, path, null));
487
488  // What the audit row carries besides what it reads inside the batch.
489  const recorded = JSON.stringify({
490    cascade: opts.cascade,
491    allow_improve_paths: opts.allowImprovePaths,
492    counts: plan.counts,
493    jobs_by_status: plan.jobs_by_status,
494    documents_deleted: paths,
495  });
496  let results: D1Result[];
497  try {
498    results = await db.batch([
499      planGuard(db, plan, pathsJson),
500      // Exactly the paths pathMutation deletes below, bound, from the rows the table
501      // holds when the batch runs. The guard has pinned the live set to this list.
502      db
503        .prepare(
504          `INSERT INTO document_versions (document_id, namespace, path, title, body)
505           SELECT id, namespace, path, title, body FROM documents
506           WHERE namespace = ?1 AND path IN (SELECT value FROM json_each(?2))
507           RETURNING id`
508        )
509        .bind(namespace, pathsJson),
510      // The one audit row, read inside the batch before anything is removed: the
511      // edges, the whole ops_sites row, the access_sync_groups pin and the namespaces row are recorded here and
512      // nowhere else afterwards; the deleted paths ride in the plan. The aggregate
513      // always yields a row.
514      db
515        .prepare(
516          `INSERT INTO audit_log (actor, action, namespace, path, params)
517           SELECT ?1, 'namespace-delete', ?2, NULL, json_object(
518             'plan', json(?3),
519             'edges_removed', json_group_array(json_object('from_ns', from_ns, 'from_path', from_path, 'type', type, 'to_ns', to_ns, 'to_path', to_path)),
520             'ops_site', json((SELECT json_object('namespace', namespace, 'name', name, 'origin', origin, 'health_path', health_path,
521                 'platform', platform, 'script', script, 'self_probe', self_probe, 'revision', revision,
522                 'created_at', created_at, 'updated_at', updated_at) FROM ops_sites WHERE namespace = ?2)),
523             'access_sync_group', json((SELECT json_object('namespace', namespace, 'group_id', group_id, 'group_name', group_name,
524                 'pinned_by', pinned_by, 'pinned_at', pinned_at) FROM access_sync_groups WHERE namespace = ?2)),
525             'namespace_row', json((SELECT json_object('namespace', namespace, 'repos', repos, 'created_at', created_at) FROM namespaces WHERE namespace = ?2)))
526           FROM document_links
527           WHERE (from_ns = ?2 AND from_path IN (SELECT value FROM json_each(?4)))
528              OR (to_ns = ?2 AND to_path IN (SELECT value FROM json_each(?4)))
529           RETURNING params`
530        )
531        .bind(actor, namespace, recorded, pathsJson),
532      db.prepare("DELETE FROM ops_sites WHERE namespace = ?1 RETURNING namespace").bind(namespace),
533      // The Access group pin (migrations/0040), so a later register of the same name
534      // does not inherit the old app's group.
535      db.prepare("DELETE FROM access_sync_groups WHERE namespace = ?1 RETURNING namespace").bind(namespace),
536      db.prepare("DELETE FROM namespaces WHERE namespace = ?1 RETURNING namespace").bind(namespace),
537      ...deletion,
538    ]);
539  } catch (err) {
540    if (isMissingRowAbort(err)) {
541      return {
542        ok: false,
543        refusal: `delete_namespace aborted, nothing changed: ${namespace} changed between the plan and the commit (a document, an edge, an open job, a live agent or its ops_sites row). Preview again.`,
544      };
545    }
546    return { ok: false, refusal: `delete_namespace failed, nothing changed: ${err instanceof Error ? err.message : String(err)}` };
547  }
548
549  // Counted from RETURNING, never meta.changes (path mutation invariant, test/path-mutation.test.ts). The
550  // batch committed, so the guard held: the live set was exactly `paths`, and
551  // pathMutation deleted each of them.
552  const snapshots = rows(results[1]).length;
553  const auditParams = rows<{ params: string }>(results[2])[0]?.params;
554  let edgesRemoved = 0;
555  if (auditParams) edgesRemoved = (JSON.parse(auditParams) as { edges_removed: unknown[] }).edges_removed.length;
556  const siteRemoved = rows(results[3]).length > 0;
557  const documentsDeleted = paths.length;
558
559  return {
560    ok: true,
561    data: {
562      namespace,
563      action: "deleted",
564      documents_deleted: documentsDeleted,
565      snapshots,
566      edges_removed: edgesRemoved,
567      ops_site_removed: siteRemoved,
568      kept: {
569        documents_archived: plan.counts.documents_archived,
570        document_versions: plan.counts.document_versions + snapshots,
571        jobs_finished: plan.counts.jobs_finished,
572        agents_revoked: plan.counts.agents_revoked,
573      },
574    },
575  };
576}