@productbrain/mcp 0.0.1-beta.158 → 0.0.1-beta.159

package/dist/{chunk-ZZHGJKLF.js → chunk-LKUFRQUO.js}

@@ -7,6 +7,7 @@ import {
   trackCaptureQualityHints,
   trackCaptureRelationSuggestions,
   trackChainEntryCommitted,
+  trackClassifierDivergence,
   trackCollectionClassified,
   trackCommitErrorByCode,
   trackFieldGuidanceApplied,
@@ -18,7 +19,7 @@ import {
   trackToolCall,
   trackWriteBackHintServed,
   trackZeroCaptureAuditFired
-} from "./chunk-KGGSEIZ3.js";
+} from "./chunk-YMF3IQ5E.js";
 
 // src/auth.ts
 import { AsyncLocalStorage } from "async_hooks";
@@ -1835,7 +1836,9 @@ var captureSchema = z2.object({
     "If true, commits the entry immediately after capture + linking. If omitted, Open mode workspaces auto-commit by default and consensus/role modes stay draft-first."
   ),
   sourceRef: z2.string().optional().describe("URI or path of the source document backing this entry (e.g. 'meeting-2026-03-28.md', 'import://batch-5'). Stored as top-level entry field, not in data."),
-  sourceExcerpt: z2.string().optional().describe("Verbatim excerpt from the source that backs this entry's claims. Stored as top-level entry field, not in data.")
+  sourceExcerpt: z2.string().optional().describe("Verbatim excerpt from the source that backs this entry's claims. Stored as top-level entry field, not in data."),
+  // WP-316 S3: Preview gate — dry-run mode. Returns what would happen, no DB writes.
+  preview: z2.boolean().optional().describe("If true, validates the capture without writing. Returns what would happen. Default false.")
 });
 var batchCaptureSchema = z2.object({
   entries: z2.array(z2.object({
@@ -1850,7 +1853,9 @@ var batchCaptureSchema = z2.object({
   })).min(1).max(50).describe("Array of entries to capture"),
   autoCommit: z2.boolean().optional().describe(
     "If true, commits created entries immediately after linking. If omitted, Open mode workspaces commit by default and consensus/role modes stay draft-first."
-  )
+  ),
+  // WP-316 S3: Preview gate — dry-run mode. Returns what would happen, no DB writes.
+  preview: z2.boolean().optional().describe("If true, validates all captures without writing. Returns what would happen. Default false.")
 });
 var captureClassifierSchema = z2.object({
   enabled: z2.boolean(),
@@ -1864,7 +1869,9 @@ var captureClassifierSchema = z2.object({
     z2.object({
       collection: z2.string(),
       signalScore: z2.number().optional(),
-      confidence: z2.number()
+      confidence: z2.number(),
+      /** WP-316 S2: required-field cost — how many fields the agent must supply for this collection. */
+      requiredFieldCount: z2.number().optional()
     })
   ),
   agentProvidedCollection: z2.string().optional(),
@@ -1922,7 +1929,17 @@ function buildLowConfidenceResult(resolved, classifierMeta) {
     { collection: resolved.collection, confidence: resolved.confidence },
     ...resolved.alternatives
   ];
-  const suggestions = allCandidates.map((c) => `- \`${c.collection}\` (${c.confidence}% confidence)`).join("\n");
+  const candidateFieldCounts = /* @__PURE__ */ new Map();
+  for (const c of classifierMeta.candidates) {
+    if (c.requiredFieldCount !== void 0) {
+      candidateFieldCounts.set(c.collection, c.requiredFieldCount);
+    }
+  }
+  const suggestions = allCandidates.map((c) => {
+    const fieldCost = candidateFieldCounts.get(c.collection);
+    const fieldNote = fieldCost !== void 0 ? `, ${fieldCost} required field${fieldCost === 1 ? "" : "s"}` : "";
+    return `- \`${c.collection}\` (${c.confidence}% confidence${fieldNote})`;
+  }).join("\n");
   const textBody = `Low confidence classification (${resolved.confidence}%, classified by ${resolved.classifiedBy}).
 
 Predicted: \`${resolved.collection}\`
@@ -1966,6 +1983,19 @@ function buildClassifierMeta(resolved, overrides = {}) {
     ...overrides
   };
 }
+async function enrichCandidatesWithFieldCounts(meta) {
+  try {
+    const cols = await getCollections();
+    const reqBySlug = new Map(
+      cols.map((c) => [c.slug, (c.fields ?? []).filter((f) => f.required === true).length])
+    );
+    meta.candidates = meta.candidates.map((c) => ({
+      ...c,
+      requiredFieldCount: reqBySlug.get(c.collection) ?? 0
+    }));
+  } catch {
+  }
+}
 function emitClassificationTelemetry(resolved, workspaceId, opts) {
   const topAlt = resolved.alternatives?.[0] ?? null;
   trackCollectionClassified(workspaceId, {
@@ -2001,6 +2031,7 @@ async function resolveCaptureCollection(params) {
           overrideCommand: `capture collection="${resolved2.collection}"`
         }
       });
+      await enrichCandidatesWithFieldCounts(classifierMeta2);
       emitClassificationTelemetry(resolved2, workspaceId, {
         explicitCollectionProvided: true,
         autoRouted: false
@@ -2015,6 +2046,14 @@ async function resolveCaptureCollection(params) {
           explicitCollectionProvided: true,
           outcome: "fallback"
         });
+        const agentInCandidates = resolved2.alternatives.some((a) => a.collection === collection) || resolved2.collection === collection;
+        trackClassifierDivergence(workspaceId, {
+          classifier_collection: resolved2.collection,
+          agent_collection: collection,
+          classifier_confidence: resolved2.confidence,
+          classifier_tier: resolved2.tier,
+          agent_in_candidates: agentInCandidates
+        });
       }
       return { resolvedCollection: collection, classifierMeta: classifierMeta2 };
     }
@@ -2051,6 +2090,7 @@ async function resolveCaptureCollection(params) {
   }
   const autoRoute = resolved.tier !== "low";
   const classifierMeta = buildClassifierMeta(resolved, { autoRouted: autoRoute });
+  await enrichCandidatesWithFieldCounts(classifierMeta);
   emitClassificationTelemetry(resolved, workspaceId, {
     explicitCollectionProvided,
     autoRouted: autoRoute
@@ -2226,7 +2266,7 @@ function registerSmartCaptureTools(server) {
       inputSchema: captureSchema.shape,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    withEnvelope(async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit, sourceRef, sourceExcerpt }) => {
+    withEnvelope(async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit, sourceRef, sourceExcerpt, preview }) => {
       requireWriteAccess();
       const timingStart = Date.now();
       const wsCtx = await getWorkspaceContext();
@@ -2385,8 +2425,33 @@ Or use \`collections action=list\` to see available collections.`
           createdBy: agentId ? `agent:${agentId}` : "capture",
           sessionId: agentId ?? void 0,
           ...sourceRef ? { sourceRef } : {},
-          ...sourceExcerpt ? { sourceExcerpt } : {}
+          ...sourceExcerpt ? { sourceExcerpt } : {},
+          ...preview ? { preview: true } : {}
         });
+        if (result?.preview) {
+          const previewEnvelope = success(
+            `Preview: would capture "${name}" \u2014 no DB writes`,
+            {
+              entryId: result.entryId,
+              name,
+              collection: resolvedCollection,
+              outcome: "preview",
+              warnings: result.warnings ?? []
+            },
+            [{ tool: "capture", description: "Capture for real", parameters: { collection: resolvedCollection, name, description } }]
+          );
+          if (result.contract) {
+            previewEnvelope.contract = result.contract;
+          }
+          return {
+            content: [{ type: "text", text: `# Preview: would capture "${name}" [${resolvedCollection}]
+
+No DB writes \u2014 call without \`preview:true\` to capture for real.${result.warnings?.length ? `
+
+**Warnings:** ${result.warnings.join("; ")}` : ""}` }],
+            structuredContent: previewEnvelope
+          };
+        }
         internalId = result.docId;
         finalEntryId = result.entryId;
         entryWarnings.push(...result.warnings ?? []);
@@ -2468,9 +2533,9 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
           if (linksSuggested.length >= MAX_SUGGESTIONS) break;
           if (autoTargetIds.has(c.entryId)) continue;
           if (c.confidence < 10) continue;
-          const preview = extractPreview(c.data, 80);
+          const preview2 = extractPreview(c.data, 80);
           const reason = c.confidence >= AUTO_LINK_CONFIDENCE_THRESHOLD ? "high relevance (already linked)" : `"${c.name.toLowerCase().split(/\s+/).filter((w) => `${name} ${description}`.toLowerCase().includes(w) && w.length > 3).slice(0, 2).join('", "')}" appears in content`;
-          linksSuggested.push({ entryId: c.entryId, name: c.name, collection: c.collSlug, reason, preview });
+          linksSuggested.push({ entryId: c.entryId, name: c.name, collection: c.collSlug, reason, preview: preview2 });
         }
         conflictCandidates = candidates.filter((c) => c.entryId && c.entryId !== finalEntryId).slice(0, 3).map((c) => ({ entryId: c.entryId, name: c.name, collection: c.collSlug }));
       }
@@ -2701,8 +2766,8 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         lines.push("## Suggested links (review and use `relations action=create`)");
         for (let i = 0; i < linksSuggested.length; i++) {
           const s = linksSuggested[i];
-          const preview = s.preview ? ` \u2014 ${s.preview}` : "";
-          lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview}`);
+          const preview2 = s.preview ? ` \u2014 ${s.preview}` : "";
+          lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview2}`);
         }
       }
       lines.push("");
@@ -2902,7 +2967,7 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
       inputSchema: batchCaptureSchema.shape,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    withEnvelope(async ({ entries, autoCommit }) => {
+    withEnvelope(async ({ entries, autoCommit, preview }) => {
       requireWriteAccess();
       const batchTimingStart = Date.now();
       const agentId = getAgentSessionId();
@@ -3082,7 +3147,8 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
             sessionId: agentId ?? void 0,
             canonicalKey: entry.canonicalKey ?? void 0,
             ...entry.sourceRef ? { sourceRef: entry.sourceRef } : {},
-            ...entry.sourceExcerpt ? { sourceExcerpt: entry.sourceExcerpt } : {}
+            ...entry.sourceExcerpt ? { sourceExcerpt: entry.sourceExcerpt } : {},
+            ...preview ? { preview: true } : {}
           });
           const internalId = result.docId;
           const finalEntryId = result.entryId;
@@ -3669,7 +3735,9 @@ var getHistorySchema = z3.object({
   entryId: z3.string().describe("Entry ID, e.g. 'T-SUPPLIER', 'BR-001'")
 });
 var commitEntrySchema = z3.object({
-  entryId: z3.string().describe("Entry ID to commit, e.g. 'TEN-abc123', 'GT-019'")
+  entryId: z3.string().describe("Entry ID to commit, e.g. 'TEN-abc123', 'GT-019'"),
+  // WP-316 S3: Preview gate — dry-run mode. Returns would-succeed result, no DB writes.
+  preview: z3.boolean().optional().describe("If true, validates the commit without writing. Returns what would happen. Default false.")
 });
 function registerKnowledgeTools(server) {
   const updateTool = server.registerTool(
@@ -3838,7 +3906,7 @@ ${formatted}` }],
       inputSchema: commitEntrySchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
-    withEnvelope(async ({ entryId }) => {
+    withEnvelope(async ({ entryId, preview }) => {
       requireWriteAccess();
       const entry = await mcpQuery("chain.getEntry", { entryId });
       if (!entry) {
@@ -3901,7 +3969,8 @@ ${formatted}` }],
         result = await mcpMutation("chain.commitEntry", {
           entryId,
           author: getAgentSessionId() ? `agent:${getAgentSessionId()}` : void 0,
-          sessionId: getAgentSessionId() ?? void 0
+          sessionId: getAgentSessionId() ?? void 0,
+          ...preview ? { preview: true } : {}
         });
       } catch (commitErr) {
         const errCode = commitErr?.code;
@@ -3920,6 +3989,30 @@ ${formatted}` }],
         }
         throw commitErr;
       }
+      if (result?.preview) {
+        const previewEnvelope = success(
+          `Preview: would commit ${entryId} \u2014 no DB writes`,
+          {
+            entryId,
+            name: entry.name,
+            outcome: "preview",
+            currentStatus: result.currentStatus,
+            wouldSetStatus: result.wouldSetStatus
+          },
+          [{ tool: "commit-entry", description: "Commit for real", parameters: { entryId } }]
+        );
+        if (result.contract) {
+          previewEnvelope.contract = result.contract;
+        }
+        return {
+          content: [{ type: "text", text: `# Preview: would commit ${entryId}
+
+Current status: \`${result.currentStatus}\` \u2192 would become \`${result.wouldSetStatus}\`.
+
+No DB writes \u2014 call without \`preview:true\` to commit for real.` }],
+          structuredContent: previewEnvelope
+        };
+      }
       const docId = result?._id ?? entry._id;
       const wsCtx = await getWorkspaceContext();
       const isProposal = result?.status === "proposal_created";
@@ -4794,7 +4887,9 @@ var relationsSchema = z6.object({
     from: z6.string(),
     to: z6.string(),
     type: z6.string()
-  })).min(1).max(20).optional().describe("Array of relations for batch-create")
+  })).min(1).max(20).optional().describe("Array of relations for batch-create"),
+  // WP-316 S3: Preview gate — dry-run mode for action=create.
+  preview: z6.boolean().optional().describe("If true, validates the relation without writing. Returns what would happen. Default false. Only applies to action=create.")
 });
 function registerRelationsTools(server) {
   const tool = server.registerTool(
@@ -4808,13 +4903,13 @@ function registerRelationsTools(server) {
     withEnvelope(async (args) => {
       const parsed = parseOrFail(relationsSchema, args);
       if (!parsed.ok) return parsed.result;
-      const { action, from, to, type, score, relations } = parsed.data;
+      const { action, from, to, type, score, relations, preview } = parsed.data;
       return runWithToolContext({ tool: "relations", action }, async () => {
         if (action === "create") {
           if (!from || !to || !type) {
             return validationResult("from, to, and type are required when action is 'create'.");
           }
-          return handleCreate(from, to, type, score);
+          return handleCreate(from, to, type, score, preview);
         }
         if (action === "batch-create") {
           if (!relations || relations.length === 0) {
@@ -4840,7 +4935,7 @@ function registerRelationsTools(server) {
   );
   trackWriteTool(tool);
 }
-async function handleCreate(from, to, type, score) {
+async function handleCreate(from, to, type, score, preview) {
   requireWriteAccess();
   const agentSessionId = getAgentSessionId();
   const result = await mcpMutation("chain.createEntryRelation", {
@@ -4848,8 +4943,31 @@ async function handleCreate(from, to, type, score) {
     toEntryId: to,
     type,
     suggestionScore: score ?? void 0,
-    sessionId: agentSessionId ?? void 0
+    sessionId: agentSessionId ?? void 0,
+    ...preview ? { preview: true } : {}
   });
+  if (result?.preview) {
+    const suggested2 = result.suggestedType;
+    const suggestedWithPosture2 = suggested2 ? { ...suggested2, governancePosture: suggested2.type === "governs" ? "requires_consent" : "direct" } : void 0;
+    return {
+      content: [{ type: "text", text: `# Preview: would relate ${from} \u2192 ${to} (${type})
+
+No DB writes \u2014 call without \`preview:true\` to create for real.${suggestedWithPosture2 ? `
+
+**Type suggestion:** \`${suggestedWithPosture2.type}\` may be more precise (${suggestedWithPosture2.confidence}% confidence). Governance: ${suggestedWithPosture2.governancePosture}.` : ""}` }],
+      structuredContent: success(
+        `Preview: would relate ${from} \u2192 ${to} (${type}) \u2014 no DB writes`,
+        {
+          status: "preview",
+          from,
+          to,
+          type,
+          ...suggestedWithPosture2 && { suggestedType: suggestedWithPosture2 }
+        },
+        [{ tool: "relations", description: "Create for real", parameters: { action: "create", from, to, type } }]
+      )
+    };
+  }
   const wsCtx = await getWorkspaceContext();
   if (result?.status === "proposal_created") {
     const existingNote = result.existing ? " (existing proposal reused)" : "";
@@ -4880,11 +4998,12 @@ The relation was **not applied** \u2014 it will be created when the proposal is
     `**Workspace:** ${wsCtx.workspaceSlug} (${wsCtx.workspaceId})`
   ];
   const suggested = result?.suggestedType;
-  if (suggested) {
+  const suggestedWithPosture = suggested ? { ...suggested, governancePosture: suggested.type === "governs" ? "requires_consent" : "direct" } : void 0;
+  if (suggestedWithPosture) {
     lines.push("");
-    lines.push(`**Type suggestion:** \`${suggested.type}\` may be more precise (${suggested.confidence}% confidence).`);
-    lines.push(`_${suggested.reasoning}_`);
-    lines.push(`To use instead: \`relations action=create from="${from}" to="${to}" type="${suggested.type}"\``);
+    lines.push(`**Type suggestion:** \`${suggestedWithPosture.type}\` may be more precise (${suggestedWithPosture.confidence}% confidence). Governance: ${suggestedWithPosture.governancePosture}.`);
+    lines.push(`_${suggestedWithPosture.reasoning}_`);
+    lines.push(`To use instead: \`relations action=create from="${from}" to="${to}" type="${suggestedWithPosture.type}"\``);
   }
   return {
     content: [{ type: "text", text: lines.join("\n") }],
@@ -4895,7 +5014,7 @@ The relation was **not applied** \u2014 it will be created when the proposal is
         from,
         to,
         type,
-        ...suggested && { suggestedType: suggested }
+        ...suggestedWithPosture && { suggestedType: suggestedWithPosture }
       },
       [{ tool: "graph", description: "See connections", parameters: { action: "find", entryId: from } }]
     )
@@ -15520,4 +15639,4 @@ export {
   SERVER_VERSION,
   createProductBrainServer
 };
-//# sourceMappingURL=chunk-ZZHGJKLF.js.map
+//# sourceMappingURL=chunk-LKUFRQUO.js.map