@cleocode/cleo 2026.4.153 → 2026.4.154

package/dist/cli/index.js

@@ -3783,6 +3783,17 @@ var init_registry = __esm({
         requiredParams: [],
         params: []
       },
+      {
+        gateway: "query",
+        domain: "check",
+        operation: "test.coverage",
+        description: "check.test.coverage (query) \u2014 dedicated test coverage sub-op (T1434)",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: [],
+        params: []
+      },
       {
         gateway: "query",
         domain: "check",
@@ -17929,6 +17940,7 @@ var init_check = __esm({
             "compliance.summary",
             "workflow.compliance",
             "test",
+            "test.coverage",
             "coherence",
             "gate.status",
             "archive.stats",
@@ -18701,197 +18713,375 @@ function mimeFromPath(filePath) {
   if (lower.endsWith(".css")) return "text/css";
   return "application/octet-stream";
 }
-var DocsHandler;
+function docsEnvelopeToResponse(envelope, gateway, operation, startTime) {
+  if (!envelope.success) {
+    return {
+      meta: dispatchMeta(gateway, "docs", operation, startTime),
+      success: false,
+      error: {
+        code: String(envelope.error?.code ?? "E_INTERNAL"),
+        message: envelope.error?.message ?? "Unknown error"
+      }
+    };
+  }
+  let attachmentBackend;
+  let responseData = envelope.data;
+  if (responseData !== null && responseData !== void 0 && typeof responseData === "object") {
+    const dataObj = responseData;
+    if ("attachmentBackend" in dataObj && dataObj["attachmentBackend"] !== void 0) {
+      attachmentBackend = dataObj["attachmentBackend"];
+      const { attachmentBackend: _lifted, ...cleanData } = dataObj;
+      responseData = cleanData;
+    }
+  }
+  return {
+    meta: {
+      ...dispatchMeta(gateway, "docs", operation, startTime),
+      ...attachmentBackend !== void 0 ? { attachmentBackend } : {}
+    },
+    success: true,
+    data: responseData
+  };
+}
+var _docsTypedHandler, QUERY_OPS3, MUTATE_OPS3, DocsHandler;
 var init_docs = __esm({
   "packages/cleo/src/dispatch/domains/docs.ts"() {
     "use strict";
+    init_typed();
     init_base();
     init_meta2();
+    _docsTypedHandler = defineTypedHandler("docs", {
+      // ── docs.list ──────────────────────────────────────────────────────────────
+      list: async (params) => {
+        const ownerId = params.task ?? params.session ?? params.observation;
+        if (!ownerId) {
+          return lafsError(
+            "E_INVALID_INPUT",
+            "Provide one of --task, --session, or --observation to scope the list.",
+            "list"
+          );
+        }
+        const ownerType = inferOwnerType(ownerId);
+        const store = createAttachmentStore();
+        const attachments = await store.listByOwner(ownerType, ownerId);
+        const backend = await resolveAttachmentBackend();
+        return lafsSuccess(
+          {
+            ownerId,
+            ownerType,
+            count: attachments.length,
+            attachments: attachments.map((m) => ({
+              id: m.id,
+              sha256: `${m.sha256.slice(0, 8)}\u2026`,
+              // Cast: contracts AttachmentKind doesn't include 'llmtxt-doc' (contracts gap T1529)
+              kind: m.attachment.kind,
+              mime: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.mime : m.attachment.mime ?? "\u2014",
+              size: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.size : void 0,
+              description: m.attachment.description,
+              labels: m.attachment.labels,
+              createdAt: m.createdAt,
+              refCount: m.refCount
+            })),
+            // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (drift T1529)
+            attachmentBackend: backend
+          },
+          "list"
+        );
+      },
+      // ── docs.generate ──────────────────────────────────────────────────────────
+      generate: async (params) => {
+        const forId = params.for;
+        if (!forId) {
+          return lafsError("E_INVALID_INPUT", "--for <taskId|epicId> is required", "generate");
+        }
+        const cwd = getProjectRoot4();
+        const result = await generateDocsLlmsTxt({ ownerId: forId, cwd });
+        let attachmentId;
+        let attachmentSha256;
+        if (params.attach) {
+          const store = createAttachmentStore();
+          const ownerType = inferOwnerType(forId);
+          const contentBytes = Buffer.from(result.content, "utf-8");
+          const llmsTxtDescriptor = {
+            kind: "llms-txt",
+            source: "generated",
+            content: result.content,
+            description: `llms.txt for ${forId} (${result.attachmentCount} docs)`,
+            labels: ["llms-txt", "generated"]
+          };
+          const meta = await store.put(
+            contentBytes,
+            llmsTxtDescriptor,
+            ownerType,
+            forId,
+            "cleo-docs-generate",
+            cwd
+          );
+          attachmentId = meta.id;
+          attachmentSha256 = meta.sha256;
+        }
+        return lafsSuccess(
+          {
+            forId,
+            content: result.content,
+            attachmentCount: result.attachmentCount,
+            usedLlmtxtPackage: result.usedLlmtxtPackage,
+            ...attachmentId !== void 0 ? {
+              attached: true,
+              attachmentId,
+              attachmentSha256
+            } : { attached: false }
+          },
+          "generate"
+        );
+      },
+      // ── docs.fetch ─────────────────────────────────────────────────────────────
+      fetch: async (params) => {
+        const ref = params.attachmentRef;
+        if (!ref) {
+          return lafsError(
+            "E_INVALID_INPUT",
+            "attachmentRef is required (attachment ID or SHA-256 hex)",
+            "fetch"
+          );
+        }
+        const store = createAttachmentStore();
+        const isSha256 = /^[0-9a-f]{64}$/i.test(ref);
+        let fetchResult = null;
+        let metadata = await store.getMetadata(ref);
+        if (metadata) {
+          fetchResult = await store.get(metadata.sha256);
+        } else if (isSha256) {
+          fetchResult = await store.get(ref);
+          if (fetchResult) {
+            metadata = fetchResult.metadata;
+          }
+        }
+        if (!fetchResult || !metadata) {
+          return lafsError("E_NOT_FOUND", `Attachment not found: ${ref}`, "fetch");
+        }
+        const cwd = getProjectRoot4();
+        const cleoDir = getCleoDirAbsolute(cwd);
+        let storagePath;
+        if (metadata.attachment.kind === "local-file") {
+          storagePath = metadata.attachment.path;
+        } else if (metadata.attachment.kind === "blob") {
+          const prefix = metadata.sha256.slice(0, 2);
+          const rest = metadata.sha256.slice(2);
+          const extMap = {
+            "text/markdown": ".md",
+            "text/plain": ".txt",
+            "application/json": ".json",
+            "application/pdf": ".pdf"
+          };
+          const mime = metadata.attachment.kind === "blob" ? metadata.attachment.mime : "application/octet-stream";
+          const ext = extMap[mime] ?? ".bin";
+          storagePath = resolve2(cleoDir, "attachments", "sha256", prefix, `${rest}${ext}`);
+        }
+        const MAX_INLINE = 1024 * 1024;
+        const bytesBase64 = fetchResult.bytes.length <= MAX_INLINE ? fetchResult.bytes.toString("base64") : void 0;
+        const backend = await resolveAttachmentBackend();
+        return lafsSuccess(
+          {
+            // Cast: core's AttachmentMetadata vs contracts/operations/docs AttachmentMetadata differ
+            // in their nested attachment field structure (T1529 contracts gap). The runtime
+            // value is compatible for all callers; the two interfaces diverged at the type level.
+            metadata,
+            path: storagePath,
+            sizeBytes: fetchResult.bytes.length,
+            ...bytesBase64 !== void 0 ? { bytesBase64 } : {},
+            inlined: bytesBase64 !== void 0,
+            // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+            attachmentBackend: backend
+          },
+          "fetch"
+        );
+      },
+      // ── docs.add ───────────────────────────────────────────────────────────────
+      add: async (params) => {
+        const {
+          ownerId,
+          file: filePath,
+          url,
+          desc: description,
+          labels: rawLabels,
+          attachedBy: rawAttachedBy
+        } = params;
+        if (!ownerId) {
+          return lafsError("E_INVALID_INPUT", "ownerId is required", "add");
+        }
+        if (!filePath && !url) {
+          return lafsError(
+            "E_INVALID_INPUT",
+            "Provide either a file path (positional or --file) or --url",
+            "add"
+          );
+        }
+        const labels = parseLabels(rawLabels);
+        const attachedBy = rawAttachedBy ?? "human";
+        const ownerType = inferOwnerType(ownerId);
+        const store = createAttachmentStore();
+        if (filePath) {
+          const absPath = resolve2(filePath);
+          let bytes;
+          try {
+            bytes = await readFile(absPath);
+          } catch {
+            return lafsError("E_FILE_ERROR", `Cannot read file: ${absPath}`, "add");
+          }
+          const mime = mimeFromPath(absPath);
+          const attachment = {
+            kind: "local-file",
+            path: absPath,
+            mime,
+            size: bytes.length,
+            ...description ? { description } : {},
+            ...labels ? { labels } : {}
+          };
+          const meta = await store.put(bytes, attachment, ownerType, ownerId, attachedBy);
+          let backend = "legacy";
+          try {
+            const v2 = createAttachmentStoreV2(getProjectRoot4());
+            const v2Result = await v2.put(ownerId, {
+              name: absPath.split(/[\\/]/).pop() ?? meta.sha256.slice(0, 12),
+              data: new Uint8Array(bytes),
+              contentType: mime
+            });
+            backend = v2Result.backend;
+          } catch {
+            backend = await resolveAttachmentBackend();
+          }
+          import("@cleocode/core/internal").then(
+            ({ ensureLlmtxtNode }) => ensureLlmtxtNode(
+              getProjectRoot4(),
+              meta.sha256,
+              `${ownerType}:${ownerId}`,
+              absPath.split("/").pop() ?? meta.sha256.slice(0, 12)
+            )
+          ).catch(() => {
+          });
+          return lafsSuccess(
+            {
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              refCount: meta.refCount,
+              kind: "local-file",
+              ownerId,
+              ownerType,
+              // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+              attachmentBackend: backend
+            },
+            "add"
+          );
+        }
+        if (url) {
+          const attachment = {
+            kind: "url",
+            url,
+            ...description ? { description } : {},
+            ...labels ? { labels } : {}
+          };
+          const urlBytes = Buffer.from(url, "utf-8");
+          const meta = await store.put(urlBytes, attachment, ownerType, ownerId, attachedBy);
+          import("@cleocode/core/internal").then(
+            ({ ensureLlmtxtNode }) => ensureLlmtxtNode(getProjectRoot4(), meta.sha256, `${ownerType}:${ownerId}`, url)
+          ).catch(() => {
+          });
+          const backend = "legacy";
+          return lafsSuccess(
+            {
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              refCount: meta.refCount,
+              kind: "url",
+              url,
+              ownerId,
+              ownerType,
+              // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+              attachmentBackend: backend
+            },
+            "add"
+          );
+        }
+        return lafsError("E_INVALID_INPUT", "Unreachable: no file or url", "add");
+      },
+      // ── docs.remove ────────────────────────────────────────────────────────────
+      remove: async (params) => {
+        const { attachmentRef: ref, from: fromOwner } = params;
+        if (!ref) {
+          return lafsError(
+            "E_INVALID_INPUT",
+            "attachmentRef is required (attachment ID or SHA-256 hex)",
+            "remove"
+          );
+        }
+        if (!fromOwner) {
+          return lafsError("E_INVALID_INPUT", "--from <ownerId> is required", "remove");
+        }
+        const store = createAttachmentStore();
+        const ownerType = inferOwnerType(fromOwner);
+        let attachmentId = ref;
+        if (/^[0-9a-f]{64}$/i.test(ref)) {
+          const result = await store.get(ref);
+          if (!result) {
+            return lafsError("E_NOT_FOUND", `No attachment found with SHA-256: ${ref}`, "remove");
+          }
+          attachmentId = result.metadata.id;
+        }
+        const derefResult = await store.deref(attachmentId, ownerType, fromOwner);
+        if (derefResult.status === "not-found") {
+          return lafsError(
+            "E_NOT_FOUND",
+            `Attachment ref not found: ${attachmentId} on owner ${fromOwner}`,
+            "remove"
+          );
+        }
+        const blobPurged = derefResult.status === "removed";
+        const refCountAfter = derefResult.status === "derefd" ? derefResult.refCountAfter : 0;
+        try {
+          const v2 = createAttachmentStoreV2(getProjectRoot4());
+          await v2.remove(attachmentId, fromOwner);
+        } catch {
+        }
+        const backend = await resolveAttachmentBackend();
+        return lafsSuccess(
+          {
+            removed: blobPurged,
+            attachmentId,
+            from: fromOwner,
+            refCountAfter,
+            blobPurged,
+            // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+            attachmentBackend: backend
+          },
+          "remove"
+        );
+      }
+    });
+    QUERY_OPS3 = /* @__PURE__ */ new Set(["list", "fetch", "generate"]);
+    MUTATE_OPS3 = /* @__PURE__ */ new Set(["add", "remove"]);
     DocsHandler = class {
       // -----------------------------------------------------------------------
       // Query
       // -----------------------------------------------------------------------
+      /**
+       * Execute a read-only docs query operation.
+       *
+       * @param operation - The docs query op name (e.g. 'list', 'fetch', 'generate').
+       * @param params - Raw params from the dispatcher (narrowed internally).
+       */
       async query(operation, params) {
         const startTime = Date.now();
+        if (!QUERY_OPS3.has(operation)) {
+          return unsupportedOp("query", "docs", operation, startTime);
+        }
         try {
-          switch (operation) {
-            // ── docs.list ────────────────────────────────────────────────────
-            case "list": {
-              const taskId = params?.task;
-              const sessionId = params?.session;
-              const observationId = params?.observation;
-              const ownerId = taskId ?? sessionId ?? observationId;
-              if (!ownerId) {
-                return errorResult(
-                  "query",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "Provide one of --task, --session, or --observation to scope the list.",
-                  startTime
-                );
-              }
-              const ownerType = inferOwnerType(ownerId);
-              const store = createAttachmentStore();
-              const attachments = await store.listByOwner(ownerType, ownerId);
-              const backend = await resolveAttachmentBackend();
-              return {
-                meta: {
-                  ...dispatchMeta("query", "docs", operation, startTime),
-                  attachmentBackend: backend
-                },
-                success: true,
-                data: {
-                  ownerId,
-                  ownerType,
-                  count: attachments.length,
-                  attachments: attachments.map((m) => ({
-                    id: m.id,
-                    sha256: `${m.sha256.slice(0, 8)}\u2026`,
-                    kind: m.attachment.kind,
-                    mime: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.mime : m.attachment.mime ?? "\u2014",
-                    size: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.size : void 0,
-                    description: m.attachment.description,
-                    labels: m.attachment.labels,
-                    createdAt: m.createdAt,
-                    refCount: m.refCount
-                  }))
-                }
-              };
-            }
-            // ── docs.generate ────────────────────────────────────────────────
-            case "generate": {
-              const forId = params?.for;
-              if (!forId) {
-                return errorResult(
-                  "query",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "--for <taskId|epicId> is required",
-                  startTime
-                );
-              }
-              const attach = params?.attach;
-              const cwd = getProjectRoot4();
-              const result = await generateDocsLlmsTxt({
-                ownerId: forId,
-                cwd
-              });
-              let attachmentId;
-              let attachmentSha256;
-              if (attach) {
-                const store = createAttachmentStore();
-                const ownerType = inferOwnerType(forId);
-                const contentBytes = Buffer.from(result.content, "utf-8");
-                const llmsTxtDescriptor = {
-                  kind: "llms-txt",
-                  source: "generated",
-                  content: result.content,
-                  description: `llms.txt for ${forId} (${result.attachmentCount} docs)`,
-                  labels: ["llms-txt", "generated"]
-                };
-                const meta = await store.put(
-                  contentBytes,
-                  llmsTxtDescriptor,
-                  ownerType,
-                  forId,
-                  "cleo-docs-generate",
-                  cwd
-                );
-                attachmentId = meta.id;
-                attachmentSha256 = meta.sha256;
-              }
-              return {
-                meta: dispatchMeta("query", "docs", operation, startTime),
-                success: true,
-                data: {
-                  forId,
-                  content: result.content,
-                  attachmentCount: result.attachmentCount,
-                  usedLlmtxtPackage: result.usedLlmtxtPackage,
-                  ...attachmentId !== void 0 ? {
-                    attached: true,
-                    attachmentId,
-                    attachmentSha256
-                  } : { attached: false }
-                }
-              };
-            }
-            // ── docs.fetch ───────────────────────────────────────────────────
-            case "fetch": {
-              const ref = params?.attachmentRef;
-              if (!ref) {
-                return errorResult(
-                  "query",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "attachmentRef is required (attachment ID or SHA-256 hex)",
-                  startTime
-                );
-              }
-              const store = createAttachmentStore();
-              const isSha256 = /^[0-9a-f]{64}$/i.test(ref);
-              let result = null;
-              let metadata = await store.getMetadata(ref);
-              if (metadata) {
-                result = await store.get(metadata.sha256);
-              } else if (isSha256) {
-                result = await store.get(ref);
-                if (result) {
-                  metadata = result.metadata;
-                }
-              }
-              if (!result || !metadata) {
-                return errorResult(
-                  "query",
-                  "docs",
-                  operation,
-                  "E_NOT_FOUND",
-                  `Attachment not found: ${ref}`,
-                  startTime
-                );
-              }
-              const cwd = getProjectRoot4();
-              const cleoDir = getCleoDirAbsolute(cwd);
-              let storagePath;
-              if (metadata.attachment.kind === "local-file") {
-                storagePath = metadata.attachment.path;
-              } else if (metadata.attachment.kind === "blob") {
-                const prefix = metadata.sha256.slice(0, 2);
-                const rest = metadata.sha256.slice(2);
-                const extMap = {
-                  "text/markdown": ".md",
-                  "text/plain": ".txt",
-                  "application/json": ".json",
-                  "application/pdf": ".pdf"
-                };
-                const mime = metadata.attachment.kind === "blob" ? metadata.attachment.mime : "application/octet-stream";
-                const ext = extMap[mime] ?? ".bin";
-                storagePath = resolve2(cleoDir, "attachments", "sha256", prefix, `${rest}${ext}`);
-              }
-              const MAX_INLINE = 1024 * 1024;
-              const bytesBase64 = result.bytes.length <= MAX_INLINE ? result.bytes.toString("base64") : void 0;
-              const backend = await resolveAttachmentBackend();
-              return {
-                meta: {
-                  ...dispatchMeta("query", "docs", operation, startTime),
-                  attachmentBackend: backend
-                },
-                success: true,
-                data: {
-                  metadata,
-                  path: storagePath,
-                  sizeBytes: result.bytes.length,
-                  ...bytesBase64 !== void 0 ? { bytesBase64 } : {},
-                  inlined: bytesBase64 !== void 0
-                }
-              };
-            }
-            default:
-              return unsupportedOp("query", "docs", operation, startTime);
-          }
+          const envelope = await typedDispatch(
+            _docsTypedHandler,
+            operation,
+            params ?? {}
+          );
+          return docsEnvelopeToResponse(envelope, "query", operation, startTime);
         } catch (error) {
           return handleErrorResult("query", "docs", operation, error, startTime);
         }
@@ -18899,220 +19089,24 @@ var init_docs = __esm({
       // -----------------------------------------------------------------------
       // Mutate
       // -----------------------------------------------------------------------
+      /**
+       * Execute a state-modifying docs mutation operation.
+       *
+       * @param operation - The docs mutate op name (e.g. 'add', 'remove').
+       * @param params - Raw params from the dispatcher (narrowed internally).
+       */
       async mutate(operation, params) {
         const startTime = Date.now();
+        if (!MUTATE_OPS3.has(operation)) {
+          return unsupportedOp("mutate", "docs", operation, startTime);
+        }
         try {
-          switch (operation) {
-            // ── docs.add ─────────────────────────────────────────────────────
-            case "add": {
-              const ownerId = params?.ownerId;
-              if (!ownerId) {
-                return errorResult(
-                  "mutate",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "ownerId is required",
-                  startTime
-                );
-              }
-              const filePath = params?.file;
-              const url = params?.url;
-              if (!filePath && !url) {
-                return errorResult(
-                  "mutate",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "Provide either a file path (positional or --file) or --url",
-                  startTime
-                );
-              }
-              const description = params?.desc;
-              const labels = parseLabels(params?.labels);
-              const attachedBy = params?.attachedBy ?? "human";
-              const ownerType = inferOwnerType(ownerId);
-              const store = createAttachmentStore();
-              if (filePath) {
-                const absPath = resolve2(filePath);
-                let bytes;
-                try {
-                  bytes = await readFile(absPath);
-                } catch {
-                  return errorResult(
-                    "mutate",
-                    "docs",
-                    operation,
-                    "E_FILE_ERROR",
-                    `Cannot read file: ${absPath}`,
-                    startTime
-                  );
-                }
-                const mime = mimeFromPath(absPath);
-                const attachment = {
-                  kind: "local-file",
-                  path: absPath,
-                  mime,
-                  size: bytes.length,
-                  ...description ? { description } : {},
-                  ...labels ? { labels } : {}
-                };
-                const meta = await store.put(bytes, attachment, ownerType, ownerId, attachedBy);
-                let backend = "legacy";
-                try {
-                  const v2 = createAttachmentStoreV2(getProjectRoot4());
-                  const v2Result = await v2.put(ownerId, {
-                    name: absPath.split(/[\\/]/).pop() ?? meta.sha256.slice(0, 12),
-                    data: new Uint8Array(bytes),
-                    contentType: mime
-                  });
-                  backend = v2Result.backend;
-                } catch {
-                  backend = await resolveAttachmentBackend();
-                }
-                import("@cleocode/core/internal").then(
-                  ({ ensureLlmtxtNode }) => ensureLlmtxtNode(
-                    getProjectRoot4(),
-                    meta.sha256,
-                    `${ownerType}:${ownerId}`,
-                    absPath.split("/").pop() ?? meta.sha256.slice(0, 12)
-                  )
-                ).catch(() => {
-                });
-                return {
-                  meta: {
-                    ...dispatchMeta("mutate", "docs", operation, startTime),
-                    attachmentBackend: backend
-                  },
-                  success: true,
-                  data: {
-                    attachmentId: meta.id,
-                    sha256: meta.sha256,
-                    refCount: meta.refCount,
-                    kind: "local-file",
-                    ownerId,
-                    ownerType
-                  }
-                };
-              }
-              if (url) {
-                const attachment = {
-                  kind: "url",
-                  url,
-                  ...description ? { description } : {},
-                  ...labels ? { labels } : {}
-                };
-                const urlBytes = Buffer.from(url, "utf-8");
-                const meta = await store.put(urlBytes, attachment, ownerType, ownerId, attachedBy);
-                import("@cleocode/core/internal").then(
-                  ({ ensureLlmtxtNode }) => ensureLlmtxtNode(getProjectRoot4(), meta.sha256, `${ownerType}:${ownerId}`, url)
-                ).catch(() => {
-                });
-                const backend = "legacy";
-                return {
-                  meta: {
-                    ...dispatchMeta("mutate", "docs", operation, startTime),
-                    attachmentBackend: backend
-                  },
-                  success: true,
-                  data: {
-                    attachmentId: meta.id,
-                    sha256: meta.sha256,
-                    refCount: meta.refCount,
-                    kind: "url",
-                    url,
-                    ownerId,
-                    ownerType
-                  }
-                };
-              }
-              return errorResult(
-                "mutate",
-                "docs",
-                operation,
-                "E_INVALID_INPUT",
-                "Unreachable: no file or url",
-                startTime
-              );
-            }
-            // ── docs.remove ──────────────────────────────────────────────────
-            case "remove": {
-              const ref = params?.attachmentRef;
-              const fromOwner = params?.from;
-              if (!ref) {
-                return errorResult(
-                  "mutate",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "attachmentRef is required (attachment ID or SHA-256 hex)",
-                  startTime
-                );
-              }
-              if (!fromOwner) {
-                return errorResult(
-                  "mutate",
-                  "docs",
-                  operation,
-                  "E_INVALID_INPUT",
-                  "--from <ownerId> is required",
-                  startTime
-                );
-              }
-              const store = createAttachmentStore();
-              const ownerType = inferOwnerType(fromOwner);
-              let attachmentId = ref;
-              if (/^[0-9a-f]{64}$/i.test(ref)) {
-                const result = await store.get(ref);
-                if (!result) {
-                  return errorResult(
-                    "mutate",
-                    "docs",
-                    operation,
-                    "E_NOT_FOUND",
-                    `No attachment found with SHA-256: ${ref}`,
-                    startTime
-                  );
-                }
-                attachmentId = result.metadata.id;
-              }
-              const derefResult = await store.deref(attachmentId, ownerType, fromOwner);
-              if (derefResult.status === "not-found") {
-                return errorResult(
-                  "mutate",
-                  "docs",
-                  operation,
-                  "E_NOT_FOUND",
-                  `Attachment ref not found: ${attachmentId} on owner ${fromOwner}`,
-                  startTime
-                );
-              }
-              const blobPurged = derefResult.status === "removed";
-              const refCountAfter = derefResult.status === "derefd" ? derefResult.refCountAfter : 0;
-              try {
-                const v2 = createAttachmentStoreV2(getProjectRoot4());
-                await v2.remove(attachmentId, fromOwner);
-              } catch {
-              }
-              const backend = await resolveAttachmentBackend();
-              return {
-                meta: {
-                  ...dispatchMeta("mutate", "docs", operation, startTime),
-                  attachmentBackend: backend
-                },
-                success: true,
-                data: {
-                  removed: blobPurged,
-                  attachmentId,
-                  from: fromOwner,
-                  refCountAfter,
-                  blobPurged
-                }
-              };
-            }
-            default:
-              return unsupportedOp("mutate", "docs", operation, startTime);
-          }
+          const envelope = await typedDispatch(
+            _docsTypedHandler,
+            operation,
+            params ?? {}
+          );
+          return docsEnvelopeToResponse(envelope, "mutate", operation, startTime);
         } catch (error) {
           return handleErrorResult("mutate", "docs", operation, error, startTime);
         }
@@ -19120,6 +19114,7 @@ var init_docs = __esm({
       // -----------------------------------------------------------------------
       // Supported operations
       // -----------------------------------------------------------------------
+      /** Declared operations for introspection and validation. */
       getSupportedOperations() {
         return {
           query: ["list", "fetch", "generate"],
@@ -22205,7 +22200,7 @@ async function handleImpact(operation, params, startTime) {
     return handleErrorResult("query", "nexus", operation, dbErr, startTime);
   }
 }
-var _nexusTypedHandler, QUERY_OPS3, MUTATE_OPS3, NexusHandler, IMPACT_REVERSE_TYPES;
+var _nexusTypedHandler, QUERY_OPS4, MUTATE_OPS4, NexusHandler, IMPACT_REVERSE_TYPES;
 var init_nexus2 = __esm({
   "packages/cleo/src/dispatch/domains/nexus.ts"() {
     "use strict";
@@ -22521,7 +22516,7 @@ var init_nexus2 = __esm({
       },
       "sigil.sync": async (_params) => wrapCoreResult(await nexusSigilSync(), "sigil.sync")
     });
-    QUERY_OPS3 = /* @__PURE__ */ new Set([
+    QUERY_OPS4 = /* @__PURE__ */ new Set([
       "share.status",
       "status",
       "list",
@@ -22553,7 +22548,7 @@ var init_nexus2 = __esm({
       "profile.get",
       "sigil.list"
     ]);
-    MUTATE_OPS3 = /* @__PURE__ */ new Set([
+    MUTATE_OPS4 = /* @__PURE__ */ new Set([
       "share.snapshot.export",
       "share.snapshot.import",
       "init",
@@ -22582,7 +22577,7 @@ var init_nexus2 = __esm({
        */
       async query(operation, params) {
         const startTime = Date.now();
-        if (!QUERY_OPS3.has(operation)) {
+        if (!QUERY_OPS4.has(operation)) {
           return unsupportedOp("query", "nexus", operation, startTime);
         }
         if (operation === "top-entries") {
@@ -22614,7 +22609,7 @@ var init_nexus2 = __esm({
        */
       async mutate(operation, params) {
         const startTime = Date.now();
-        if (!MUTATE_OPS3.has(operation)) {
+        if (!MUTATE_OPS4.has(operation)) {
           return unsupportedOp("mutate", "nexus", operation, startTime);
         }
         try {
@@ -22635,8 +22630,8 @@ var init_nexus2 = __esm({
       /** Declared operations for introspection and validation. */
       getSupportedOperations() {
         return {
-          query: Array.from(QUERY_OPS3),
-          mutate: Array.from(MUTATE_OPS3)
+          query: Array.from(QUERY_OPS4),
+          mutate: Array.from(MUTATE_OPS4)
         };
       }
     };
@@ -27541,7 +27536,7 @@ async function lookupApprovalByTokenForDispatch(token) {
   const db = await acquireDb();
   return getPlaybookApprovalByToken(db, token);
 }
-var __playbookRuntimeOverrides, _playbookTypedHandler, QUERY_OPS4, MUTATE_OPS4, PlaybookHandler;
+var __playbookRuntimeOverrides, _playbookTypedHandler, QUERY_OPS5, MUTATE_OPS5, PlaybookHandler;
 var init_playbook2 = __esm({
   "packages/cleo/src/dispatch/domains/playbook.ts"() {
     "use strict";
@@ -27807,15 +27802,15 @@ var init_playbook2 = __esm({
         }
       }
     });
-    QUERY_OPS4 = /* @__PURE__ */ new Set(["status", "list", "validate"]);
-    MUTATE_OPS4 = /* @__PURE__ */ new Set(["run", "resume"]);
+    QUERY_OPS5 = /* @__PURE__ */ new Set(["status", "list", "validate"]);
+    MUTATE_OPS5 = /* @__PURE__ */ new Set(["run", "resume"]);
     PlaybookHandler = class {
       /**
        * Query gateway — `status`, `list`, and `validate`.
        */
       async query(operation, params) {
         const startTime = Date.now();
-        if (!QUERY_OPS4.has(operation)) {
+        if (!QUERY_OPS5.has(operation)) {
           return unsupportedOp("query", "playbook", operation, startTime);
         }
         try {
@@ -27843,7 +27838,7 @@ var init_playbook2 = __esm({
        */
       async mutate(operation, params) {
         const startTime = Date.now();
-        if (!MUTATE_OPS4.has(operation)) {
+        if (!MUTATE_OPS5.has(operation)) {
           return unsupportedOp("mutate", "playbook", operation, startTime);
         }
         try {
@@ -29890,7 +29885,7 @@ function envelopeToEngineResult3(envelope) {
     }
   };
 }
-var coreOps2, _sentientTypedHandler, QUERY_OPS5, MUTATE_OPS5, SentientHandler;
+var coreOps2, _sentientTypedHandler, QUERY_OPS6, MUTATE_OPS6, SentientHandler;
 var init_sentient2 = __esm({
   "packages/cleo/src/dispatch/domains/sentient.ts"() {
     "use strict";
@@ -30010,8 +30005,8 @@ var init_sentient2 = __esm({
         }
       }
     });
-    QUERY_OPS5 = /* @__PURE__ */ new Set(["propose.list", "propose.diff", "allowlist.list"]);
-    MUTATE_OPS5 = /* @__PURE__ */ new Set([
+    QUERY_OPS6 = /* @__PURE__ */ new Set(["propose.list", "propose.diff", "allowlist.list"]);
+    MUTATE_OPS6 = /* @__PURE__ */ new Set([
       "propose.accept",
       "propose.reject",
       "propose.run",
@@ -30044,7 +30039,7 @@ var init_sentient2 = __esm({
        */
       async query(operation, params) {
         const startTime = Date.now();
-        if (!QUERY_OPS5.has(operation)) {
+        if (!QUERY_OPS6.has(operation)) {
           return unsupportedOp("query", "sentient", operation, startTime);
         }
         try {
@@ -30072,7 +30067,7 @@ var init_sentient2 = __esm({
        */
       async mutate(operation, params) {
         const startTime = Date.now();
-        if (!MUTATE_OPS5.has(operation)) {
+        if (!MUTATE_OPS6.has(operation)) {
           return unsupportedOp("mutate", "sentient", operation, startTime);
         }
         try {
@@ -30212,7 +30207,7 @@ async function storeSessionOwnerAuthToken(projectRoot, sessionId, token) {
   const db = await getDb(projectRoot);
   db.update(sessions).set({ ownerAuthToken: token }).where(eq(sessions.id, sessionId)).run();
 }
-var coreOps3, _sessionTypedHandler, QUERY_OPS6, MUTATE_OPS6, SessionHandler;
+var coreOps3, _sessionTypedHandler, QUERY_OPS7, MUTATE_OPS7, SessionHandler;
 var init_session3 = __esm({
   "packages/cleo/src/dispatch/domains/session.ts"() {
     "use strict";
@@ -30428,7 +30423,7 @@ var init_session3 = __esm({
         return wrapCoreResult(result, "record.assumption");
       }
     });
-    QUERY_OPS6 = /* @__PURE__ */ new Set([
+    QUERY_OPS7 = /* @__PURE__ */ new Set([
       "status",
       "list",
       "show",
@@ -30438,7 +30433,7 @@ var init_session3 = __esm({
       "handoff.show",
       "briefing.show"
     ]);
-    MUTATE_OPS6 = /* @__PURE__ */ new Set([
+    MUTATE_OPS7 = /* @__PURE__ */ new Set([
       "start",
       "end",
       "resume",
@@ -30459,7 +30454,7 @@ var init_session3 = __esm({
        */
       async query(operation, params) {
         const startTime = Date.now();
-        if (!QUERY_OPS6.has(operation)) {
+        if (!QUERY_OPS7.has(operation)) {
           return unsupportedOp("query", "session", operation, startTime);
         }
         try {
@@ -30488,7 +30483,7 @@ var init_session3 = __esm({
        */
       async mutate(operation, params) {
         const startTime = Date.now();
-        if (!MUTATE_OPS6.has(operation)) {
+        if (!MUTATE_OPS7.has(operation)) {
           return unsupportedOp("mutate", "session", operation, startTime);
         }
         try {
@@ -30870,7 +30865,7 @@ function envelopeToEngineResult5(envelope) {
     }
   };
 }
-var _tasksTypedHandler, QUERY_OPS7, MUTATE_OPS7, TasksHandler;
+var _tasksTypedHandler, QUERY_OPS8, MUTATE_OPS8, TasksHandler;
 var init_tasks3 = __esm({
   "packages/cleo/src/dispatch/domains/tasks.ts"() {
     "use strict";
@@ -31209,7 +31204,7 @@ var init_tasks3 = __esm({
         return wrapCoreResult(await taskUnclaim(projectRoot, params.taskId), "unclaim");
       }
     });
-    QUERY_OPS7 = /* @__PURE__ */ new Set([
+    QUERY_OPS8 = /* @__PURE__ */ new Set([
       "show",
       "list",
       "find",
@@ -31227,7 +31222,7 @@ var init_tasks3 = __esm({
       "label.list",
       "sync.links"
     ]);
-    MUTATE_OPS7 = /* @__PURE__ */ new Set([
+    MUTATE_OPS8 = /* @__PURE__ */ new Set([
       "add",
       "update",
       "complete",
@@ -31257,7 +31252,7 @@ var init_tasks3 = __esm({
        */
       async query(operation, params) {
         const startTime = Date.now();
-        if (!QUERY_OPS7.has(operation)) {
+        if (!QUERY_OPS8.has(operation)) {
           return unsupportedOp("query", "tasks", operation, startTime);
         }
         if (operation === "impact" && !params?.change) {
@@ -31296,7 +31291,7 @@ var init_tasks3 = __esm({
        */
       async mutate(operation, params) {
         const startTime = Date.now();
-        if (!MUTATE_OPS7.has(operation)) {
+        if (!MUTATE_OPS8.has(operation)) {
           return unsupportedOp("mutate", "tasks", operation, startTime);
         }
         try {