comisai 1.0.41 → 1.0.44

package/node_modules/@comis/daemon/dist/api/google-images-transport.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Google (Gemini) Images transport (PRV-02).
+ *
+ * A pi-ai `ImagesApiFunction` over the `@google/genai` SDK. It is registered
+ * into pi-ai's module-level IMAGES registry under the `google-images` api
+ * (`registerComisImageProviders()` — Plan 04's PI-02 seam, extended in this
+ * phase) and dispatched through the ONE `generateImages()` call site.
+ *
+ * Call shape (RESEARCH CRITICAL #4, VERIFIED against `@google/genai@1.52.0`):
+ *   `ai.models.generateContent({ model, contents, config: { responseModalities:
+ *   [Modality.IMAGE] } })` where `contents` is a `Part[]` built from the
+ *   `ImagesContext.input` (a `{text}` part per text input + a
+ *   `{inlineData:{data,mimeType}}` part per IMAGE reference, IN-01). The image
+ *   returns in `candidates[0].content.parts[].inlineData.{data(base64),mimeType}`.
+ *
+ * `gemini-2.5-flash-image` is a Gemini MULTIMODAL model -> `generateContent`,
+ * NOT `models.generateImages` (that is the Imagen `imagen-*` path and would 404
+ * the gemini id). The image part is found by scanning ALL parts for the first
+ * `inlineData.data` (A2 — it is not guaranteed to be at index 0).
+ *
+ * Never-throw discipline (mirrors `codex-images-transport.ts`): EVERY miss (no
+ * key, SDK throw, blocked, no image) returns `AssistantImages{
+ * stopReason:"error", errorMessage }` so the SHIPPED `classifyImageError`
+ * (`pi-image-adapter.ts`) maps it. So this file needs NO `@allow-throw` header.
+ *
+ * SEC (T-185-01): the api key rides `options.apiKey` -> the SDK client only; it
+ * is never interpolated or logged. This transport logs NOTHING (logging happens
+ * in the reused `toImageGenOutput`). The catch surfaces the raw SDK message
+ * ONLY on the result's `errorMessage` for classification — never to a logger.
+ *
+ * @module
+ */
+import { GoogleGenAI, Modality } from "@google/genai";
+// systemNowMs is the globals-gate-sanctioned wall-clock read — NOT Date.now().
+import { systemNowMs } from "@comis/core";
+/**
+ * Hand-built `ImagesModel` for the Gemini image path (Pitfall 4 — pi-ai's image
+ * catalog is openrouter-only). The 8 fields tsc requires for `ImagesModel<TApi>`
+ * are `id,name,api,provider,baseUrl,input,output,cost`. The id defaults to
+ * `gemini-2.5-flash-image` (the stable id; VERIFIED in the `@google/genai@1.52.0`
+ * `Model_2` union) and is overridable by config/tool. `cost: 0` is the
+ * Phase-186 placeholder.
+ */
+export const GOOGLE_IMAGE_MODEL = {
+    id: "gemini-2.5-flash-image",
+    name: "Google Gemini Image (gemini-2.5-flash-image)",
+    api: "google-images",
+    provider: "google",
+    baseUrl: "https://generativelanguage.googleapis.com",
+    input: ["text", "image"],
+    output: ["image"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, // 186: real cost mapping (OBS-03)
+};
+/**
+ * The `google-images` transport (PRV-02).
+ *
+ * Reads the api key from `options.apiKey`, constructs a `GoogleGenAI` client per
+ * call, and calls `models.generateContent` with `responseModalities:[IMAGE]`.
+ * NEVER throws out — every failure -> an `AssistantImages{ stopReason:"error" }`
+ * the shipped classifier maps.
+ */
+export const generateImagesGoogle = async (model, context, options) => {
+    const out = {
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        output: [],
+        stopReason: "stop",
+        timestamp: systemNowMs(),
+    };
+    if (!options?.apiKey) {
+        // No SDK call issued. The message lets the shipped classifier map it
+        // (-> auth_required). Never log the (absent) key.
+        out.stopReason = "error";
+        out.errorMessage = "No API key for provider: google";
+        return out;
+    }
+    try {
+        const ai = new GoogleGenAI({ apiKey: options.apiKey });
+        // Build the contents Part[] from the input: a text part per text input, an
+        // inlineData part per IMAGE reference (IN-01), preserving order.
+        const parts = [];
+        for (const c of context.input) {
+            if (c.type === "text")
+                parts.push({ text: c.text });
+            else if (c.type === "image")
+                parts.push({ inlineData: { data: c.data, mimeType: c.mimeType } });
+        }
+        const r = await ai.models.generateContent({
+            model: model.id,
+            contents: parts,
+            config: { responseModalities: [Modality.IMAGE] },
+        });
+        // A2: scan ALL parts for the first inline image (not guaranteed at index 0).
+        const img = (r.candidates?.[0]?.content?.parts ?? []).find((p) => p.inlineData?.data);
+        const b64 = img?.inlineData?.data;
+        if (!b64) {
+            out.stopReason = "error";
+            // A blocked prompt populates promptFeedback with no candidates; otherwise
+            // the model replied without an image. Both -> a classifiable errorMessage.
+            out.errorMessage = r.promptFeedback ? "content blocked" : "Gemini returned no image";
+            return out;
+        }
+        out.output.push({ type: "image", data: b64, mimeType: img?.inlineData?.mimeType ?? "image/png" });
+        return out;
+    }
+    catch (e) {
+        // NEVER throw out — the shipped classifyImageError maps the errorMessage
+        // substring. The raw SDK message is surfaced for classification only.
+        out.stopReason = "error";
+        out.errorMessage = e instanceof Error ? e.message : String(e);
+        return out;
+    }
+};

package/node_modules/@comis/daemon/dist/api/graph-handlers/graph-export.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { GraphLoadContract, stripInternalFields, } from "@comis/core";
+import { GraphLoadContract, stripInternalFields, requireCapability, } from "@comis/core";
 import { IS_DEV } from "./graph-helpers.js";
 // ---------------------------------------------------------------------------
 // Export handlers
@@ -20,6 +20,10 @@ import { IS_DEV } from "./graph-helpers.js";
 export function bindGraphExportHandlers(deps) {
     return {
         [GraphLoadContract.method]: async (rawParams) => {
+            // CAP-03/05 (v8 §3.7): in-process capability gate — the agent loop skips
+            // checkScope, so orch:graph is enforced here (graph.load is in the gated
+            // graph family per HANDLER_CAPABILITY_MAP). Read _capabilities BEFORE strip.
+            requireCapability(rawParams._capabilities, "orch:graph");
             // Bespoke pre-Zod validation FIRST.
             if (!deps.namedGraphStore) {
                 throw new Error("Named graph storage not available");

package/node_modules/@comis/daemon/dist/api/graph-handlers/graph-helpers.d.ts

@@ -1,33 +1,68 @@
 /**
  * Graph handler helpers.
  *
- * Pure helpers shared across the mutate / query / export handler bundles.
- * No closures, no factory: every helper is a pure function or interface so
- * the dependency graph stays one-directional (mutate / query / export →
- * graph-helpers).
- *
- *   - GraphHandlerDeps type re-export (composition of OrchestratorApiDeps)
- *   - ValidationIssue interface (warning record shape)
- *   - transformNodes (snake_case to camelCase node param adapter)
- *   - validateGraphWarnings (soft validation; emits LLM-friendly warnings)
- *   - schemaToExample (Zod schema introspection for LLM hints)
- *   - validateTypeConfigs (typeConfig validation against driver schemas)
- *   - buildGraphInput (RPC params → validated graph + execution order)
- *   - IS_DEV (NODE_ENV !== "production" dev-mode flag)
+ * Pure helpers shared across the mutate / query / export handler bundles
+ * (GraphHandlerDeps, ValidationIssue, transformNodes, validateGraphWarnings,
+ * schemaToExample, validateTypeConfigs, buildGraphInput, IS_DEV). No closures,
+ * no factory: every helper is a pure function or interface so the dependency
+ * graph stays one-directional (mutate / query / export → graph-helpers →
+ * graph-repair). The conservative weak-model repair branch lives in the sibling
+ * graph-repair.ts (DEFER-174-FILESIZE-01).
  *
  * @module
  */
-import { type ExecutionGraph } from "@comis/core";
-import { z } from "zod";
+import { validateAndSortGraph, type ExecutionGraph } from "@comis/core";
+import type { CapabilityClass, TemplateMatch } from "@comis/agent";
+import { isWeakCapabilityClass, type CapabilityClassParam, type BuildGraphRepairContext } from "./graph-repair.js";
+export { isWeakCapabilityClass };
+import { schemaToExample } from "./graph-schema-example.js";
+export { schemaToExample };
+export type { CapabilityClassParam, BuildGraphRepairContext };
 /**
  * Run `contract.response.parse(result)` only when NODE_ENV !== "production".
- * Daemon side is the trust boundary; in production the trust check is
- * the in-handler logic, not the contract parse.
+ * Daemon side is the trust boundary; in production the trust check is the
+ * in-handler logic, not the contract parse.
  */
 export declare const IS_DEV: boolean;
 import type { OrchestratorApiDeps } from "../types.js";
 export type GraphHandlerDeps = OrchestratorApiDeps & {
     graphCoordinator: import("../../graph/graph-coordinator.js").GraphCoordinator;
+    /**
+     * TELEM-01 (Phase 173-02): resolve the calling agent's capabilityClass tier
+     * from its `_agentId` for the `pipeline:authored` emit (graph-mutate.ts).
+     * INJECTED dep (mirrors the 172 `resolvePosture` pattern) — the tier is
+     * resolved DAEMON-SIDE, never read from a tool-supplied param (Spoofing
+     * mitigation T-173-03). Wired at the createGraphHandlers({...}) call in
+     * rpc-dispatch.ts. Returns `undefined` when the agent/provider cannot be
+     * mapped; the emit then records "unknown" (never silently dropped). A wiring
+     * test (rpc-dispatch.test.ts) proves it is actually constructed in production
+     * so the metric is not a permanent "unknown" (the 172-WR-02 fail-default
+     * class / T-173-13 silent-metric-loss).
+     */
+    resolveCapabilityClass?: (agentId: string | undefined) => CapabilityClass | undefined;
+    /**
+     * AUTHOR-01 (Phase 174-03): the orchestration.authoring gate
+     * (config.orchestration.authoring). When `repairProducer` is true AND the
+     * calling agent resolves to a weak tier, an invalid graph routes to the
+     * conservative deterministic repair (template-match + fillDagTemplate) instead
+     * of the fail-closed Phase-157 throw. ABSENT / `repairProducer:false` ⇒ the
+     * tier is never resolved ⇒ byte-identical to today (D-GATED-OFF). Threaded
+     * from config at the rpc-dispatch composition site.
+     */
+    authoringConfig?: {
+        repairProducer: boolean;
+        intentAction: boolean;
+        gbnfConstrain: boolean;
+    };
+    /**
+     * AUTHOR-01 (Phase 174-03): the injected conservative repair matcher
+     * (`matchRawGraphToTemplate` from @comis/agent). INJECTED — never a direct
+     * daemon→agent import inside this pure helper; the boundary is crossed only at
+     * the rpc-dispatch composition site (which legitimately imports @comis/agent),
+     * mirroring the `resolveCapabilityClass` precedent. Returns a deterministic
+     * "matched"/"ambiguous"/"no-match" verdict (no model reprompt).
+     */
+    repairMatch?: (rawGraph: unknown) => TemplateMatch;
 };
 /** A single validation issue returned to the LLM for self-correction. */
 export interface ValidationIssue {
@@ -42,13 +77,30 @@ export interface ValidationIssue {
  * schemas in @comis/core use camelCase. This function bridges the gap.
  */
 export declare function transformNodes(rawNodes: unknown[]): unknown[];
+/** The ValidatedGraph shape returned by validateAndSortGraph (ok branch). */
+type ValidatedGraphResult = Extract<ReturnType<typeof validateAndSortGraph>, {
+    ok: true;
+}>["value"];
 /**
  * Build a validated graph from RPC params.
  * Extracts and transforms common graph params from RPC input, parses with
  * parseExecutionGraph, and validates with validateAndSortGraph. Throws
  * descriptive errors on parse or validation failure.
+ *
+ * ASYNC (AUTHOR-01 / Phase 174-03): the weak-model invalid branch may run the
+ * conservative repair (graph-repair.ts), so the function returns a Promise. ALL
+ * call sites await it (3 production in graph-mutate.ts + the O3 test call sites).
+ *
+ *   - Capable tier (frontier / mid / undefined): the existing direct path —
+ *     byte-identical, no behavior change. The repairProducer gate resolves the
+ *     tier to undefined when OFF (the default), so this is also the FLAGS-OFF path.
+ *   - Weak tier (small / nano): a valid graph returns immediately (fast-path); an
+ *     invalid graph delegates to attemptWeakModelRepair (graph-repair.ts), which
+ *     conservatively repairs an unambiguous match (re-governed), throws a
+ *     structured did-you-mean on ambiguity, or falls through to the fail-closed
+ *     throw below on no-match / failed re-validation.
  */
-export declare function buildGraphInput(params: Record<string, unknown>): import("@comis/core").ValidatedGraph;
+export declare function buildGraphInput(params: Record<string, unknown>, capabilityClass?: CapabilityClassParam, repair?: BuildGraphRepairContext): Promise<ValidatedGraphResult>;
 /**
  * Produce LLM-friendly warnings for a structurally valid graph.
  * Hard errors (cycles, missing deps) are already caught by
@@ -65,12 +117,6 @@ export declare function validateGraphWarnings(graph: ExecutionGraph): {
     warnings: ValidationIssue[];
     errors: ValidationIssue[];
 };
-/**
- * Generate an example object from a Zod schema's shape for LLM self-correction hints.
- * Uses instanceof checks against Zod v4 class hierarchy (not _def.typeName).
- * For ZodDefault, uses _def.innerType (no public API alternative).
- */
-export declare function schemaToExample(schema: z.ZodObject<z.ZodRawShape>): Record<string, string>;
 /**
  * Validate typeConfig for all typed nodes against driver config schemas.
  * Called in graph.define and graph.execute handlers after buildGraphInput().

package/node_modules/@comis/daemon/dist/api/graph-handlers/graph-helpers.js

@@ -3,31 +3,36 @@
 /**
  * Graph handler helpers.
  *
- * Pure helpers shared across the mutate / query / export handler bundles.
- * No closures, no factory: every helper is a pure function or interface so
- * the dependency graph stays one-directional (mutate / query / export →
- * graph-helpers).
- *
- *   - GraphHandlerDeps type re-export (composition of OrchestratorApiDeps)
- *   - ValidationIssue interface (warning record shape)
- *   - transformNodes (snake_case to camelCase node param adapter)
- *   - validateGraphWarnings (soft validation; emits LLM-friendly warnings)
- *   - schemaToExample (Zod schema introspection for LLM hints)
- *   - validateTypeConfigs (typeConfig validation against driver schemas)
- *   - buildGraphInput (RPC params → validated graph + execution order)
- *   - IS_DEV (NODE_ENV !== "production" dev-mode flag)
+ * Pure helpers shared across the mutate / query / export handler bundles
+ * (GraphHandlerDeps, ValidationIssue, transformNodes, validateGraphWarnings,
+ * schemaToExample, validateTypeConfigs, buildGraphInput, IS_DEV). No closures,
+ * no factory: every helper is a pure function or interface so the dependency
+ * graph stays one-directional (mutate / query / export → graph-helpers →
+ * graph-repair). The conservative weak-model repair branch lives in the sibling
+ * graph-repair.ts (DEFER-174-FILESIZE-01).
  *
  * @module
  */
 import { parseExecutionGraph, validateAndSortGraph, systemGetEnv, } from "@comis/core";
-import { z } from "zod";
-// ---------------------------------------------------------------------------
-// Dev-mode response parse helper
-// ---------------------------------------------------------------------------
+// DEFER-174-FILESIZE-01: the routing predicate, repair context, and the
+// conservative deterministic weak-model repair branch (AUTHOR-01, Phase 174-03)
+// live in the sibling `graph-repair.ts` to keep this file under the
+// graph-handlers/ 500-line cap (§2.8 shrink-only — behavior byte-identical).
+// `isWeakCapabilityClass` + the two repair types are re-exported below so the
+// canonical import surface of `./graph-helpers.js` is unchanged (the
+// graph-helpers tests import `isWeakCapabilityClass` from this module).
+import { isWeakCapabilityClass, attemptWeakModelRepair, } from "./graph-repair.js";
+export { isWeakCapabilityClass };
+// schemaToExample lives in `graph-schema-example.ts` (#217 split — keeps this
+// file under the graph-handlers/ 500-line cap; behavior byte-identical).
+// Imported for validateTypeConfigs's self-correction hint below AND re-exported
+// so the canonical import surface of `./graph-helpers.js` is unchanged.
+import { schemaToExample } from "./graph-schema-example.js";
+export { schemaToExample };
 /**
  * Run `contract.response.parse(result)` only when NODE_ENV !== "production".
- * Daemon side is the trust boundary; in production the trust check is
- * the in-handler logic, not the contract parse.
+ * Daemon side is the trust boundary; in production the trust check is the
+ * in-handler logic, not the contract parse.
  */
 export const IS_DEV = systemGetEnv("NODE_ENV") !== "production";
 // ---------------------------------------------------------------------------
@@ -41,23 +46,54 @@ export const IS_DEV = systemGetEnv("NODE_ENV") !== "production";
 export function transformNodes(rawNodes) {
     return rawNodes.map((raw) => {
         const node = raw;
+        const rawTypeId = node.type_id ?? node.typeId;
+        const rawTypeConfig = node.type_config ?? node.typeConfig;
+        // Bug-1 (OR-01) — collapse the redundant `agent` node type, in ALL its forms,
+        // to a regular single-agent node. The `agent` driver's config
+        // (`{agent, model?, max_steps?}`) merely duplicates fields a regular
+        // {agent, task} node already carries. Weak models emit it three malformed
+        // ways, each tripping the validator's both-or-neither refine: (1) type_id:
+        // "agent" with NO type_config; (2) type_config:{agent:X} with NO type_id (the
+        // live 8-node NVDA DAG); (3) type_id:"agent" WITH type_config:{agent:X}.
+        // Collapse all three to a regular node (lifting agent/model/max_steps out of
+        // the config), keeping the both-or-neither rule strict for the SIX real typed
+        // nodes (debate/vote/refine/collaborate/approval-gate/map-reduce — none of
+        // which use a bare `agent` config). See design/small-model-orchestration-fidelity.md §4.
+        const tc = (rawTypeConfig !== null && typeof rawTypeConfig === "object" && !Array.isArray(rawTypeConfig))
+            ? rawTypeConfig : undefined;
+        // A "bare agent config" is the agent-driver shape: an `agent` string plus at
+        // most the optional model/max_steps the agent driver also accepts.
+        const isBareAgentConfig = tc !== undefined && typeof tc.agent === "string"
+            && Object.keys(tc).every((k) => k === "agent" || k === "model" || k === "max_steps" || k === "maxSteps");
+        const isAgentFootgun = rawTypeId === "agent" || (rawTypeId === undefined && isBareAgentConfig);
+        // Lift agent/model/max_steps out of a bare agent config (the node's own fields win).
+        const agentId = node.agent ?? node.agentId ?? (isAgentFootgun ? tc?.agent : undefined);
+        const model = node.model ?? (isAgentFootgun ? tc?.model : undefined);
+        const maxSteps = node.max_steps ?? node.maxSteps ?? (isAgentFootgun ? (tc?.max_steps ?? tc?.maxSteps) : undefined);
         return {
             nodeId: node.node_id ?? node.nodeId,
             task: node.task,
-            agentId: node.agent ?? node.agentId,
-            model: node.model,
+            agentId,
+            model,
             dependsOn: node.depends_on ?? node.dependsOn,
             timeoutMs: node.timeout_ms ?? node.timeoutMs,
-            maxSteps: node.max_steps ?? node.maxSteps,
+            maxSteps,
+            ...(node.mcp_servers ?? node.mcpServers
+                ? { mcpServers: node.mcp_servers ?? node.mcpServers } : {}),
             ...(node.barrier_mode ?? node.barrierMode
                 ? { barrierMode: node.barrier_mode ?? node.barrierMode } : {}),
             ...(node.retries !== undefined ? { retries: node.retries } : {}),
+            // P0-A: forward the per-node tokenBudget override (GraphNodeSchema field, highest-
+            // precedence budget source — resolveNodeBudgetWithSource capSource "node"). Without
+            // this it was silently dropped here, so an author-set per-node cap never bound the node.
+            ...((node.token_budget ?? node.tokenBudget) !== undefined
+                ? { tokenBudget: node.token_budget ?? node.tokenBudget } : {}),
             ...(node.context_mode ?? node.contextMode
                 ? { contextMode: node.context_mode ?? node.contextMode } : {}),
-            ...(node.type_id ?? node.typeId
-                ? { typeId: node.type_id ?? node.typeId } : {}),
-            ...(node.type_config ?? node.typeConfig
-                ? { typeConfig: node.type_config ?? node.typeConfig } : {}),
+            // Drop typeId+typeConfig entirely for the agent footgun (collapse to a regular
+            // node); preserve them for the six real typed nodes.
+            ...(rawTypeId !== undefined && !isAgentFootgun ? { typeId: rawTypeId } : {}),
+            ...(rawTypeConfig !== undefined && !isAgentFootgun ? { typeConfig: rawTypeConfig } : {}),
         };
     });
 }
@@ -66,8 +102,21 @@ export function transformNodes(rawNodes) {
  * Extracts and transforms common graph params from RPC input, parses with
  * parseExecutionGraph, and validates with validateAndSortGraph. Throws
  * descriptive errors on parse or validation failure.
+ *
+ * ASYNC (AUTHOR-01 / Phase 174-03): the weak-model invalid branch may run the
+ * conservative repair (graph-repair.ts), so the function returns a Promise. ALL
+ * call sites await it (3 production in graph-mutate.ts + the O3 test call sites).
+ *
+ *   - Capable tier (frontier / mid / undefined): the existing direct path —
+ *     byte-identical, no behavior change. The repairProducer gate resolves the
+ *     tier to undefined when OFF (the default), so this is also the FLAGS-OFF path.
+ *   - Weak tier (small / nano): a valid graph returns immediately (fast-path); an
+ *     invalid graph delegates to attemptWeakModelRepair (graph-repair.ts), which
+ *     conservatively repairs an unambiguous match (re-governed), throws a
+ *     structured did-you-mean on ambiguity, or falls through to the fail-closed
+ *     throw below on no-match / failed re-validation.
  */
-export function buildGraphInput(params) {
+export async function buildGraphInput(params, capabilityClass, repair) {
     const rawNodes = params.nodes;
     if (!rawNodes || !Array.isArray(rawNodes) || rawNodes.length === 0) {
         throw new Error("Missing required parameter: nodes");
@@ -87,10 +136,35 @@ export function buildGraphInput(params) {
         throw new Error(`Graph validation failed: ${issues}`);
     }
     const validateResult = validateAndSortGraph(parseResult.value);
-    if (!validateResult.ok) {
-        throw new Error(`Graph validation failed: ${validateResult.error.message}`);
+    if (!isWeakCapabilityClass(capabilityClass)) {
+        // Capable path (frontier / mid / undefined) — unchanged direct-emit path.
+        if (!validateResult.ok) {
+            throw new Error(`Graph validation failed: ${validateResult.error.message}`);
+        }
+        return validateResult.value;
+    }
+    // Weak path (small / nano): fast-path on valid graph.
+    if (validateResult.ok) {
+        // Graph is already valid — return immediately without repair.
+        return validateResult.value;
     }
-    return validateResult.value;
+    // Weak + INVALID. AUTHOR-01: the conservative, gated, deterministic repair
+    // (extracted into graph-repair.ts — DEFER-174-FILESIZE-01; behavior unchanged).
+    // (FLAGS-OFF can never reach here — capabilityClass resolves undefined when the
+    // gate is off, so isWeakCapabilityClass is false above and the capable path
+    // ran. This is reached ONLY when repairProducer is on AND the server-resolved
+    // tier is weak.) An unambiguous match re-governed clean returns the repaired
+    // graph; an ambiguous shape throws a structured did-you-mean from within the
+    // repair helper (T-174-FALSESYNTH); no-match / gate-off / a repaired graph that
+    // itself fails re-validation falls through to the fail-closed throw below.
+    const repaired = attemptWeakModelRepair(rawGraph, capabilityClass, repair);
+    if (repaired.kind === "repaired") {
+        return repaired.value;
+    }
+    // FLAGS-OFF (and no-match / failed-repair): the existing fail-closed throw.
+    // Phase 174 (the former Phase 157) IS the repair consumer above; this throw
+    // remains the recourse when the gate is off or no conservative match exists.
+    throw new Error(`Graph validation failed (weak model, Phase 157 repair deferred): ${validateResult.error.message}`);
 }
 // ---------------------------------------------------------------------------
 // Graph Warnings (soft validation)
@@ -264,40 +338,6 @@ export function validateGraphWarnings(graph) {
 // ---------------------------------------------------------------------------
 // Type Config Validation Helpers
 // ---------------------------------------------------------------------------
-/**
- * Generate an example object from a Zod schema's shape for LLM self-correction hints.
- * Uses instanceof checks against Zod v4 class hierarchy (not _def.typeName).
- * For ZodDefault, uses _def.innerType (no public API alternative).
- */
-export function schemaToExample(schema) {
-    const shape = schema.shape;
-    const result = {};
-    for (const [key, type] of Object.entries(shape)) {
-        const t = type;
-        if (t.description) {
-            result[key] = t.description;
-            continue;
-        }
-        const inner = t instanceof z.ZodOptional ? t.unwrap()
-            : t instanceof z.ZodDefault ? t._def.innerType
-                : t;
-        if (inner instanceof z.ZodString)
-            result[key] = "string";
-        else if (inner instanceof z.ZodNumber)
-            result[key] = "number";
-        else if (inner instanceof z.ZodBoolean)
-            result[key] = "boolean";
-        else if (inner instanceof z.ZodArray)
-            result[key] = "array";
-        else if (inner instanceof z.ZodObject)
-            result[key] = "object";
-        else
-            result[key] = "unknown";
-        if (t instanceof z.ZodOptional)
-            result[key] += " (optional)";
-    }
-    return result;
-}
 /**
  * Validate typeConfig for all typed nodes against driver config schemas.
  * Called in graph.define and graph.execute handlers after buildGraphInput().

package/node_modules/@comis/daemon/dist/api/graph-handlers/graph-mutate-telemetry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Graph-mutate authoring telemetry/audit helpers.
+ *
+ * The best-effort, counts-only telemetry + audit emitters and the server-side
+ * tier/repair-context derivations consumed by the write-side graph handlers
+ * (graph-mutate.ts). Extracted to keep graph-mutate.ts under the graph-handlers/
+ * 500-line cap (§2.8 shrink-only) — behavior is byte-identical to the prior
+ * inline closures.
+ *
+ * `createGraphMutateTelemetry(deps)` returns the closures over the injected
+ * GraphHandlerDeps; graph-mutate.ts calls it once at bind time and destructures
+ * the helpers.
+ *
+ * @module
+ */
+import type { GraphHandlerDeps, BuildGraphRepairContext } from "./graph-helpers.js";
+/** The closed set of canonical from_intent patterns (mirrors the synthesizer). */
+export declare const SYNTH_PATTERNS: readonly ["research-fanout", "debate", "vote", "map-reduce"];
+export type SynthPattern = (typeof SYNTH_PATTERNS)[number];
+export declare const isSynthPattern: (v: string) => v is SynthPattern;
+/** The authoring telemetry/audit helpers bound over GraphHandlerDeps. */
+export interface GraphMutateTelemetry {
+    /** TELEM-01: emit a counts-only `pipeline:authored` per authoring invocation. */
+    emitPipelineAuthored: (action: "define" | "execute", schemaValid: boolean, rawParams: Record<string, unknown>) => void;
+    /** AUTHOR-01: resolve the calling agent's tier SERVER-SIDE, gated on repairProducer. */
+    resolveAuthoringTier: (d: GraphHandlerDeps, rawParams: Record<string, unknown>) => "frontier" | "mid" | "small" | "nano" | undefined;
+    /** AUTHOR-01: assemble the repair context buildGraphInput needs for the gated branch. */
+    repairContext: (d: GraphHandlerDeps, rawParams: Record<string, unknown>) => BuildGraphRepairContext;
+    /** AUTHOR-02: best-effort audit emit for a from_intent synthesis. */
+    emitGraphSynthesized: (pattern: SynthPattern, nodeCount: number, rawParams: Record<string, unknown>) => void;
+}
+/**
+ * Build the authoring telemetry/audit helpers over the injected deps. The
+ * emitters are best-effort (try/catch guarded) — telemetry can never break the
+ * operation it measures (WR-01, Phase 173 review).
+ */
+export declare function createGraphMutateTelemetry(deps: GraphHandlerDeps): GraphMutateTelemetry;

package/node_modules/@comis/daemon/dist/api/graph-handlers/graph-mutate-telemetry.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Graph-mutate authoring telemetry/audit helpers.
+ *
+ * The best-effort, counts-only telemetry + audit emitters and the server-side
+ * tier/repair-context derivations consumed by the write-side graph handlers
+ * (graph-mutate.ts). Extracted to keep graph-mutate.ts under the graph-handlers/
+ * 500-line cap (§2.8 shrink-only) — behavior is byte-identical to the prior
+ * inline closures.
+ *
+ * `createGraphMutateTelemetry(deps)` returns the closures over the injected
+ * GraphHandlerDeps; graph-mutate.ts calls it once at bind time and destructures
+ * the helpers.
+ *
+ * @module
+ */
+import { systemNowMs } from "@comis/core";
+/** The closed set of canonical from_intent patterns (mirrors the synthesizer). */
+export const SYNTH_PATTERNS = ["research-fanout", "debate", "vote", "map-reduce"];
+export const isSynthPattern = (v) => SYNTH_PATTERNS.includes(v);
+/**
+ * Build the authoring telemetry/audit helpers over the injected deps. The
+ * emitters are best-effort (try/catch guarded) — telemetry can never break the
+ * operation it measures (WR-01, Phase 173 review).
+ */
+export function createGraphMutateTelemetry(deps) {
+    // TELEM-01 (Phase 173-02): emit a counts-only `pipeline:authored` per
+    // authoring invocation (define + execute), where schema validity and the
+    // resolved capabilityClass tier converge. Counts/ids/closed-enums ONLY — no
+    // node task, type_config value, label, or any pipeline body reaches the bus
+    // (§2.7 / D-EVENT). The tier is resolved DAEMON-SIDE from the RAW _agentId
+    // (Spoofing mitigation T-173-03) via the injected resolver — never a
+    // tool-supplied param — and fail-safes to "unknown" when unresolvable
+    // (Pitfall 2: record honestly, never silently drop, never default to
+    // "frontier"). `repaired` is the literal false: the weak-model repair
+    // producer is Phase 174 / AUTHOR-01 and is NOT wired here.
+    //
+    // METRIC DENOMINATOR (Phase 173 review WR-02): an authoring invocation is
+    // counted on every CONTRACT-PARSE-REACHABLE path — graph.define emits on a
+    // strict-contract parse rejection AND a buildGraphInput throw; graph.execute
+    // (a loose z.record contract) emits on the buildGraphInput throw. The bespoke
+    // pre-Zod guards (define's "Missing required parameter: nodes" empty-call
+    // check, execute's a2a-disabled policy gate) emit NOTHING — an empty/garbage
+    // call or a policy rejection is not an authoring attempt. This boundary is
+    // deliberate (documented in fleet-findings.ts's pipeline_authoring finding +
+    // docs/developer-guide/event-bus.mdx).
+    const emitPipelineAuthored = (action, schemaValid, rawParams) => {
+        // WR-01 (Phase 173 review): the emit MUST be best-effort — telemetry can
+        // never break the operation it measures. `deps.eventBus.emit` delegates to
+        // Node's EventEmitter with NO listener error isolation, and the subscribed
+        // `pipeline:authored` listener pushes into the obs diagnostic buffer whose
+        // synchronous SQLite flush (on its 50th item) can throw SQLITE_BUSY/FULL/
+        // disk-error. On the SUCCESS path this emit is called OUTSIDE the handler's
+        // buildGraphInput try (and, for graph.execute, BEFORE graphCoordinator.run),
+        // so an unguarded throw here would fail a VALID graph.define/execute purely
+        // because a telemetry insert failed — and on the invalid path it would mask
+        // the user-facing graph-validation error. Swallow any emit throw and log it
+        // at WARN (hint + errorKind) so the measured operation always proceeds.
+        try {
+            const capabilityClass = deps.resolveCapabilityClass?.(rawParams._agentId) ?? "unknown";
+            deps.eventBus?.emit("pipeline:authored", {
+                action,
+                capabilityClass,
+                schemaValid,
+                repaired: false,
+                agentId: rawParams._agentId,
+                sessionKey: rawParams._callerSessionKey,
+                timestamp: systemNowMs(),
+            });
+        }
+        catch (err) {
+            deps.logger?.warn({
+                err,
+                action,
+                errorKind: "internal",
+                hint: "pipeline:authored telemetry emit failed (likely an obs-buffer SQLite flush throw); the graph operation proceeds unaffected",
+            }, "pipeline-authoring telemetry emit failed (best-effort)");
+        }
+    };
+    // AUTHOR-01 (Phase 174-03): resolve the calling agent's capabilityClass tier
+    // for the buildGraphInput repair decision, GATED on repairProducer. When the
+    // gate is off (or absent) this returns undefined so buildGraphInput takes the
+    // capable direct path — byte-identical to pre-174 (D-GATED-OFF). The tier is
+    // resolved SERVER-SIDE from the RAW _agentId (Spoofing mitigation T-174-SPOOF /
+    // T-173-03), reusing 173's injected resolveCapabilityClass — the tool-supplied
+    // capabilityClass param is NEVER read for the tier.
+    const resolveAuthoringTier = (d, rawParams) => d.authoringConfig?.repairProducer
+        ? d.resolveCapabilityClass?.(rawParams._agentId)
+        : undefined;
+    // AUTHOR-01: assemble the repair context buildGraphInput needs for the gated
+    // weak-model branch (the injected matcher + gate + best-effort emit inputs).
+    // Correlation ids ride from the RAW params (envelope-only — never body).
+    const repairContext = (d, rawParams) => ({
+        authoringConfig: d.authoringConfig,
+        repairMatch: d.repairMatch,
+        eventBus: d.eventBus,
+        logger: d.logger,
+        agentId: rawParams._agentId,
+        sessionKey: rawParams._callerSessionKey,
+    });
+    // AUTHOR-02 (Phase 174-04): best-effort audit emit for a from_intent synthesis
+    // (mirrors emitPipelineAuthored's WR-01 guard — telemetry never breaks the
+    // measured op). Counts/ids/closed-enums ONLY (pattern + GOVERNED node count +
+    // correlation ids; NEVER the graph body / node task / one-line intent — §2.7).
+    // Called AFTER buildGraphInput + validateTypeConfigs, so it reflects a GOVERNED graph.
+    const emitGraphSynthesized = (pattern, nodeCount, rawParams) => {
+        try {
+            deps.eventBus?.emit("graph:synthesized_from_intent", {
+                pattern,
+                nodeCount,
+                agentId: rawParams._agentId,
+                sessionKey: rawParams._callerSessionKey,
+                timestamp: systemNowMs(),
+            });
+        }
+        catch (err) {
+            deps.logger?.warn({
+                err,
+                pattern,
+                errorKind: "internal",
+                hint: "graph:synthesized_from_intent audit emit failed (likely an obs-buffer SQLite flush throw); the synthesized graph proceeds unaffected",
+            }, "from-intent synthesis audit emit failed (best-effort)");
+        }
+    };
+    return { emitPipelineAuthored, resolveAuthoringTier, repairContext, emitGraphSynthesized };
+}