@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/mcp/output-schemas.ts

@@ -0,0 +1,3071 @@
+import {
+  MINIMUM_PRODUCT_COMPLEXITY_SESSIONS,
+  SEARCH_JOURNEY_ABANDON_REASON_CODES,
+  SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS,
+  SEARCH_JOURNEY_TARGET_CODE_COMPLEXITY_UNAVAILABLE_REASONS,
+  canonicalJson,
+  searchJourneyValidationIssue,
+} from "@untangle-code/domain";
+import * as z from "zod/v4";
+
+import { frontendBoundaryReportSchema } from "./boundaries-schema.js";
+import type { UntangleMcpToolName } from "./types.js";
+
+const text = z.string();
+const isoTimestamp = text.refine((value) => Number.isFinite(Date.parse(value)), {
+  message: "Expected an ISO timestamp",
+});
+// Validate semantic content without transforming wire values. In particular,
+// raw import specifiers may intentionally carry leading/trailing whitespace
+// and must round-trip byte-for-byte through the MCP response boundary.
+const nonEmpty = text.refine((value) => value.trim().length > 0, {
+  message: "Expected a non-empty string",
+});
+const finite = z.number().finite();
+const nonNegative = finite.nonnegative();
+const ratio = finite.min(0).max(1);
+const integer = z.number().int();
+const nonNegativeInt = integer.nonnegative();
+const positiveInt = integer.positive();
+const sha256Fingerprint = text.regex(/^[0-9a-f]{64}$/u);
+const stringArray = z.array(text);
+const stringMap = z.record(z.string(), text);
+const optionalStringMap = z.record(z.string(), text.nullable());
+const numberMap = z.record(z.string(), finite);
+const jsonMap = z.record(z.string(), z.json());
+
+const sourceRangeSchema = z
+  .object({
+    startLine: positiveInt,
+    endLine: positiveInt,
+    startByte: nonNegativeInt,
+    endByte: nonNegativeInt,
+  })
+  .strict();
+
+const skipLedgerEntrySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    stage: z.enum([
+      "scan",
+      "parse",
+      "chunk",
+      "embed",
+      "store",
+      "file_graph",
+      "symbol_graph",
+      "search",
+      "findability",
+      "extension",
+    ]),
+    subjectKind: z.enum([
+      "file",
+      "range",
+      "symbol",
+      "chunk",
+      "file_edge",
+      "symbol_edge",
+      "search_candidate",
+      "artifact",
+      "extension",
+    ]),
+    subjectId: text.optional(),
+    path: text.optional(),
+    range: sourceRangeSchema.optional(),
+    repoId: text.optional(),
+    refId: text.optional(),
+    reason: z.enum([
+      "unsupported_language",
+      "parse_failed",
+      "file_too_large",
+      "binary_content",
+      "excluded_by_configuration",
+      "token_budget_exceeded",
+      "time_budget_exceeded",
+      "resolution_failed",
+      "ambiguous_resolution",
+      "missing_index_entry",
+      "provider_unavailable",
+      "extension_unavailable",
+      "duplicate",
+      "no_metric_defined",
+      "generated_content",
+      "relevance_policy_rejected",
+    ]),
+    detail: nonEmpty,
+    recoverable: z.boolean(),
+  })
+  .strict();
+
+const indexCountsSchema = z
+  .object({
+    filesSeen: nonNegativeInt,
+    filesPlanned: nonNegativeInt,
+    filesUnchanged: nonNegativeInt,
+    filesIgnored: nonNegativeInt,
+    filesAnalyzed: nonNegativeInt,
+    filesRemoved: nonNegativeInt,
+    chunks: nonNegativeInt,
+    symbols: nonNegativeInt,
+    points: nonNegativeInt,
+    embeddingCacheHits: nonNegativeInt,
+    embeddingsComputed: nonNegativeInt,
+    parseCacheHits: nonNegativeInt,
+    parseCacheMisses: nonNegativeInt,
+    chunkCacheHits: nonNegativeInt,
+    chunkCacheMisses: nonNegativeInt,
+    metricsCacheHits: nonNegativeInt,
+    metricsCacheMisses: nonNegativeInt,
+    truncated: nonNegativeInt,
+    fileGraphNodes: nonNegativeInt,
+    fileGraphEdges: nonNegativeInt,
+    symbolGraphNodes: nonNegativeInt,
+    symbolGraphEdges: nonNegativeInt,
+  })
+  .strict();
+
+const indexReportSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    jobId: nonEmpty,
+    generationId: text.nullable(),
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    embeddingProfileId: nonEmpty,
+    collection: nonEmpty,
+    outcome: z.enum(["completed", "failed", "cancelled"]),
+    counts: indexCountsSchema,
+    failure: z
+      .object({ code: nonEmpty, message: nonEmpty, retryable: z.boolean() })
+      .strict()
+      .optional(),
+    skipped: z.array(skipLedgerEntrySchema),
+    skippedByReason: z.record(z.string(), nonNegativeInt),
+    skippedByStage: z.record(z.string(), nonNegativeInt),
+    skippedTruncated: nonNegativeInt,
+  })
+  .strict();
+
+const jobStatusSchema = z
+  .object({
+    jobId: nonEmpty,
+    operation: nonEmpty,
+    status: z.enum([
+      "queued",
+      "preparing_infrastructure",
+      "discovering_files",
+      "parsing_and_chunking",
+      "computing_metrics",
+      "embedding",
+      "storing",
+      "checkpointing",
+      "building_graphs",
+      "indexing_context",
+      "finalizing",
+      "completed",
+      "failed",
+      "cancel_requested",
+      "cancelled",
+    ]),
+    workspaceId: nonEmpty,
+    generationId: text.optional(),
+    updatedAt: text.optional(),
+  })
+  .strict();
+
+const checkResultSchema = z
+  .object({
+    id: nonEmpty,
+    title: nonEmpty,
+    status: z.enum(["ok", "warn", "fail"]),
+    detail: nonEmpty,
+    nextStep: nonEmpty.optional(),
+    facts: z.record(z.string(), z.union([text, finite, z.boolean()])).optional(),
+  })
+  .strict();
+
+const repositoryConfigSchema = z
+  .object({
+    id: nonEmpty,
+    path: nonEmpty,
+    label: text.optional(),
+    ref: text.optional(),
+    include: stringArray.optional(),
+    exclude: stringArray.optional(),
+    packageAliases: stringMap.optional(),
+    metadata: stringMap.optional(),
+  })
+  .strict();
+
+const contextArtifactSchema = z
+  .object({
+    name: nonEmpty,
+    path: nonEmpty,
+    description: text,
+    type: z
+      .enum([
+        "auto",
+        "sql",
+        "openapi",
+        "asyncapi",
+        "protobuf",
+        "markdown",
+        "terraform",
+        "kubernetes",
+        "text",
+      ])
+      .optional(),
+    include: stringArray.optional(),
+    exclude: stringArray.optional(),
+  })
+  .strict();
+
+const warningDataSchema = z
+  .object({
+    code: nonEmpty,
+    message: nonEmpty,
+    details: jsonMap.optional(),
+  })
+  .strict();
+
+const scoreComponentSchema = z
+  .object({
+    kind: z.enum([
+      "base_hybrid",
+      "exact_symbol_boost",
+      "exact_path_boost",
+      "repo_priority_boost",
+      "graph_proximity_boost",
+      "recency_boost",
+      "duplicate_penalty",
+      "complexity_modifier",
+    ]),
+    rawValue: finite,
+    weight: finite,
+    contribution: finite,
+    evidence: text.optional(),
+  })
+  .strict();
+
+const scoreBreakdownSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    final: finite,
+    components: z.array(scoreComponentSchema),
+    inputs: z
+      .object({
+        dense: finite.optional(),
+        sparseRank: positiveInt.optional(),
+        rrf: finite.optional(),
+        denseRank: positiveInt.optional(),
+        lexicalScore: finite.optional(),
+        lexicalRank: positiveInt.optional(),
+        symbolRank: positiveInt.optional(),
+      })
+      .strict(),
+    rankerVersion: nonEmpty,
+    clamped: z.boolean(),
+    clampReason: text.optional(),
+  })
+  .strict();
+
+const complexitySummarySchema = z
+  .object({
+    metricsScope: z.enum(["symbol", "file", "chunk"]),
+    metricsScopeId: nonEmpty,
+    metricsVersion: nonEmpty,
+    cyclomaticClassic: nonNegativeInt.optional(),
+    cyclomaticExtended: nonNegativeInt.optional(),
+    cognitive: nonNegativeInt.optional(),
+    maxNesting: nonNegativeInt.optional(),
+    sloc: nonNegativeInt.optional(),
+    halsteadVolume: nonNegative.optional(),
+    maintainabilityIndex: finite.min(0).max(100).optional(),
+    riskScore: nonNegative.optional(),
+  })
+  .strict()
+  .refine(
+    (summary) =>
+      summary.cyclomaticClassic !== undefined ||
+      summary.cyclomaticExtended !== undefined ||
+      summary.cognitive !== undefined ||
+      summary.maxNesting !== undefined ||
+      summary.sloc !== undefined ||
+      summary.halsteadVolume !== undefined ||
+      summary.maintainabilityIndex !== undefined ||
+      summary.riskScore !== undefined,
+    { message: "complexity summary requires at least one metric" },
+  );
+
+const graphRelationSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    source: z.enum(["file_graph", "symbol_graph"]),
+    edgeId: nonEmpty,
+    direction: z.enum(["incoming", "outgoing"]),
+    edgeKind: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    fileId: nonEmpty,
+    path: text,
+    crossRepository: z.boolean(),
+    symbol: z
+      .object({ id: nonEmpty, name: text, qualifiedName: text, kind: text })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const graphRelationsSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    relations: z.array(graphRelationSchema),
+    relationLimit: nonNegativeInt,
+    truncated: z.boolean(),
+    omittedCount: nonNegativeInt,
+    omissions: z.array(
+      z
+        .object({
+          reason: z.enum([
+            "graph_unavailable",
+            "graph_partial",
+            "source_not_in_graph",
+            "symbol_id_missing",
+            "unresolved_endpoint",
+            "heuristic_endpoint",
+            "ambiguous_endpoint",
+            "endpoint_missing",
+            "provider_result_missing",
+            "relation_limit",
+          ]),
+          count: nonNegativeInt,
+          detail: nonEmpty,
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+
+const relatedFragmentSchema = z
+  .object({
+    chunkId: nonEmpty,
+    chunkKind: nonEmpty,
+    fragmentIndex: nonNegativeInt.optional(),
+    startLine: positiveInt,
+    endLine: positiveInt,
+    score: finite,
+  })
+  .strict();
+
+const findabilitySummarySchema = z
+  .object({
+    score: ratio,
+    isHeuristic: z.literal(true),
+    algorithm: nonEmpty,
+    primaryCause: z
+      .enum(["scattered-responsibility", "weak-naming", "high-entanglement", "undocumented"])
+      .optional(),
+    primaryCauseConfidence: ratio.optional(),
+  })
+  .strict();
+
+const searchHitSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    rank: positiveInt,
+    repoId: nonEmpty,
+    repoLabel: text,
+    refId: nonEmpty,
+    refName: text,
+    commitSha: text.optional(),
+    fileId: nonEmpty,
+    filePath: text,
+    range: sourceRangeSchema,
+    language: nonEmpty,
+    parseQuality: z.enum(["complete", "partial", "failed"]),
+    chunkId: nonEmpty,
+    chunkKind: nonEmpty,
+    fragmentIndex: nonNegativeInt.optional(),
+    fragmentCount: positiveInt.optional(),
+    symbolId: text.optional(),
+    symbolName: text.optional(),
+    symbolFqn: text.optional(),
+    symbolKind: text.optional(),
+    signature: text.optional(),
+    score: scoreBreakdownSchema,
+    dedupeKey: nonEmpty,
+    relatedFragments: z.array(relatedFragmentSchema),
+    embeddingProfileId: nonEmpty,
+    indexGeneration: nonEmpty,
+    complexity: complexitySummarySchema.optional(),
+    findability: findabilitySummarySchema.optional(),
+    content: text.optional(),
+    contentOmittedReason: text.optional(),
+    graphContext: graphRelationsSchema.optional(),
+    linkedSymbols: graphRelationsSchema.optional(),
+    incompletePayloadFields: stringArray.optional(),
+  })
+  .strict();
+
+const searchQuerySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    text: nonEmpty,
+    workspaceId: nonEmpty,
+    filters: z
+      .object({
+        repoIds: stringArray,
+        refIds: stringArray,
+        commitSha: text.optional(),
+        languages: stringArray,
+        pathGlobs: stringArray,
+        symbolNames: stringArray,
+        symbolKinds: stringArray,
+        chunkKinds: stringArray,
+        complexity: z
+          .object({
+            cyclomaticMin: finite.optional(),
+            cyclomaticMax: finite.optional(),
+            cognitiveMin: finite.optional(),
+            cognitiveMax: finite.optional(),
+            riskMin: finite.optional(),
+            riskMax: finite.optional(),
+          })
+          .strict()
+          .optional(),
+        findability: z
+          .object({
+            maxScore: finite.optional(),
+            minScore: finite.optional(),
+            causes: z
+              .array(
+                z.enum([
+                  "scattered-responsibility",
+                  "weak-naming",
+                  "high-entanglement",
+                  "undocumented",
+                ]),
+              )
+              .optional(),
+          })
+          .strict()
+          .optional(),
+        changed: z.object({ since: nonEmpty, until: nonEmpty.optional() }).strict().optional(),
+      })
+      .strict(),
+    limit: positiveInt,
+    candidateLimit: positiveInt,
+    minScore: finite.optional(),
+    diversify: z.boolean(),
+    includeGraphContext: z.boolean(),
+    includeLinked: z.boolean(),
+    includeContent: z.boolean(),
+    rankerVersion: nonEmpty,
+  })
+  .strict();
+
+const searchResultSetSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    queryFingerprint: nonEmpty,
+    indexFreshness: z
+      .object({
+        status: z.enum(["fresh", "stale", "unknown", "incompatible"]),
+        checkedAt: isoTimestamp,
+        repositories: z.array(
+          z
+            .object({
+              repoId: nonEmpty,
+              refId: nonEmpty,
+              status: z.enum(["fresh", "stale", "unknown", "incompatible"]),
+              reason: nonEmpty,
+              filesChecked: nonNegativeInt,
+              indexedAt: isoTimestamp.optional(),
+              indexedCorpusFingerprint: sha256Fingerprint.optional(),
+              currentCorpusFingerprint: sha256Fingerprint.optional(),
+            })
+            .strict(),
+        ),
+      })
+      .strict()
+      .optional(),
+    rankingContextFingerprint: nonEmpty.optional(),
+    query: searchQuerySchema,
+    groups: z.array(
+      z
+        .object({
+          embeddingProfileId: nonEmpty,
+          indexGenerations: z.array(nonEmpty).optional(),
+          corpusRevisionFingerprint: sha256Fingerprint.optional(),
+          repoIds: stringArray,
+          hits: z.array(searchHitSchema),
+          rankNormalized: z.boolean(),
+          caveats: stringArray,
+          notSearchedReason: text.optional(),
+          relevanceDecision: z
+            .object({
+              abstention: z.enum(["strict", "evidence"]),
+              status: z.enum(["accepted", "rejected", "not_evaluated"]),
+              basis: nonEmpty,
+              calibrationId: nonEmpty.optional(),
+            })
+            .strict()
+            .optional(),
+          retrieval: z
+            .object({
+              branchCandidateCounts: z
+                .object({
+                  dense: nonNegativeInt,
+                  sparse: nonNegativeInt,
+                  symbol: nonNegativeInt,
+                })
+                .strict(),
+              uniqueRetrievedCandidateCount: nonNegativeInt,
+              eligibleCandidateCount: nonNegativeInt,
+              rankedCandidateCount: nonNegativeInt,
+              deduplicatedCandidateCount: nonNegativeInt,
+              qualifiedHitCount: nonNegativeInt,
+              returnedHitCount: nonNegativeInt,
+              uniqueEligibleFileCount: nonNegativeInt,
+              uniqueEligibleSymbolCount: nonNegativeInt,
+              eligibleFileDispersion: ratio,
+              topScoreGap: finite.nullable(),
+              candidateLimitReached: z.boolean(),
+            })
+            .strict()
+            .optional(),
+        })
+        .strict(),
+    ),
+    profileSeparation: z.boolean(),
+    totalHits: nonNegativeInt,
+    skipped: z.array(skipLedgerEntrySchema),
+    warnings: z.array(warningDataSchema),
+    timings: z
+      .object({
+        queryEmbeddingMs: nonNegative.optional(),
+        vectorSearchMs: nonNegative.optional(),
+        totalMs: nonNegative.optional(),
+      })
+      .strict()
+      .optional(),
+    searchObservation: z
+      .discriminatedUnion("status", [
+        z
+          .object({
+            sessionId: nonEmpty,
+            attemptId: nonEmpty,
+            status: z.literal("recorded"),
+          })
+          .strict(),
+        z
+          .object({
+            sessionId: nonEmpty,
+            status: z.literal("not_recorded"),
+            warningCode: nonEmpty,
+          })
+          .strict(),
+      ])
+      .optional(),
+  })
+  .strict();
+
+const searchJourneyTargetSchema = z
+  .object({
+    repoId: nonEmpty.optional(),
+    refId: nonEmpty.optional(),
+    filePath: nonEmpty.optional(),
+    chunkId: nonEmpty.optional(),
+    symbolId: nonEmpty.optional(),
+    embeddingProfileId: nonEmpty.optional(),
+    indexGeneration: nonEmpty.optional(),
+  })
+  .strict()
+  .refine(
+    (target) =>
+      target.filePath !== undefined ||
+      target.chunkId !== undefined ||
+      target.symbolId !== undefined,
+    {
+      message: "search journey target requires filePath, chunkId or symbolId",
+    },
+  );
+
+const searchJourneyCandidateSchema = z
+  .object({
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    filePath: text,
+    chunkId: nonEmpty,
+    symbolId: nonEmpty.optional(),
+    symbolFqn: text.optional(),
+    embeddingProfileId: nonEmpty,
+    indexGeneration: nonEmpty,
+    rank: positiveInt,
+    score: finite,
+    complexity: complexitySummarySchema.optional(),
+    incompletePayloadFields: stringArray.optional(),
+  })
+  .strict();
+
+const searchJourneyTargetCodeCandidateSchema = z
+  .object({
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    filePath: text,
+    chunkId: nonEmpty,
+    symbolId: nonEmpty.optional(),
+    symbolFqn: text.optional(),
+    embeddingProfileId: nonEmpty,
+    indexGeneration: nonEmpty,
+  })
+  .strict();
+
+const searchJourneyTargetCodeComplexitySchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("observed"),
+      source: z.literal("indexed-search-hit"),
+      candidate: searchJourneyTargetCodeCandidateSchema,
+      complexity: complexitySummarySchema,
+      payloadComplete: z.boolean(),
+      incompletePayloadFields: stringArray,
+    })
+    .strict()
+    .superRefine((evidence, context) => {
+      if (evidence.payloadComplete !== (evidence.incompletePayloadFields.length === 0)) {
+        context.addIssue({
+          code: "custom",
+          path: ["payloadComplete"],
+          message: "payload completeness must match incompletePayloadFields",
+        });
+      }
+      if (
+        new Set(evidence.incompletePayloadFields).size !== evidence.incompletePayloadFields.length
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["incompletePayloadFields"],
+          message: "incomplete payload fields must be unique",
+        });
+      }
+    }),
+  z
+    .object({
+      status: z.literal("unavailable"),
+      reason: z.enum(SEARCH_JOURNEY_TARGET_CODE_COMPLEXITY_UNAVAILABLE_REASONS),
+    })
+    .strict(),
+]);
+
+const searchRetrievalDiagnosticsSchema = z
+  .object({
+    branchCandidateCounts: z
+      .object({ dense: nonNegativeInt, sparse: nonNegativeInt, symbol: nonNegativeInt })
+      .strict(),
+    uniqueRetrievedCandidateCount: nonNegativeInt,
+    eligibleCandidateCount: nonNegativeInt,
+    rankedCandidateCount: nonNegativeInt,
+    deduplicatedCandidateCount: nonNegativeInt,
+    qualifiedHitCount: nonNegativeInt,
+    returnedHitCount: nonNegativeInt,
+    uniqueEligibleFileCount: nonNegativeInt,
+    uniqueEligibleSymbolCount: nonNegativeInt,
+    eligibleFileDispersion: ratio,
+    topScoreGap: finite.nullable(),
+    candidateLimitReached: z.boolean(),
+  })
+  .strict();
+
+const searchJourneyAttemptSchema = z
+  .object({
+    attemptId: nonEmpty,
+    sequence: positiveInt,
+    clientStep: positiveInt.optional(),
+    observationFingerprint: nonEmpty,
+    measurementContextVersion: z.literal(2).optional(),
+    abstention: z.enum(["strict", "evidence"]).optional(),
+    queryFingerprint: nonEmpty,
+    queryText: text.optional(),
+    rankerVersion: nonEmpty,
+    rankingContextFingerprint: nonEmpty.optional(),
+    resultLimit: positiveInt.optional(),
+    candidateLimit: positiveInt.optional(),
+    observedAt: nonEmpty,
+    status: z.enum(["succeeded", "failed"]),
+    failureCode: nonEmpty.optional(),
+    failureReason: text.optional(),
+    warningCodes: stringArray,
+    retrievalHealthy: z.boolean(),
+    profiles: z.array(
+      z
+        .object({
+          embeddingProfileId: nonEmpty,
+          indexGenerations: stringArray,
+          corpusRevisionFingerprint: sha256Fingerprint.optional(),
+          retrievalPerformed: z.boolean(),
+          notSearchedReason: text.optional(),
+          retrieval: searchRetrievalDiagnosticsSchema.optional(),
+          candidates: z.array(searchJourneyCandidateSchema),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+
+const dynamicSearchComplexitySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    algorithm: z.literal("untangle-dynamic-search-complexity-v1"),
+    isHeuristic: z.literal(true),
+    searchesToTarget: positiveInt,
+    successfulSearchesToTarget: nonNegativeInt,
+    failedSearchesToTarget: nonNegativeInt,
+    distinctQueryCount: positiveInt,
+    queryReformulations: nonNegativeInt,
+    acceptedTargetRank: positiveInt.nullable(),
+    reciprocalRank: ratio.nullable(),
+    targetWasReturned: z.boolean(),
+    targetFirstReturnedAtSearch: positiveInt.nullable(),
+    targetAcceptedAtSearch: positiveInt.nullable(),
+    selectionLagSearches: nonNegativeInt.nullable(),
+    directHit: z.boolean(),
+    eligibleCandidatesExamined: nonNegativeInt,
+    uniqueCandidatesExposed: nonNegativeInt,
+    uniqueFilesExposed: nonNegativeInt,
+    navigationEventsToTarget: nonNegativeInt,
+    observedToolAndFileHops: positiveInt,
+    meanCandidateFileDispersion: ratio.nullable(),
+    meanCandidateChurn: ratio.nullable(),
+    candidateLimitHitRate: ratio,
+    healthyRetrievalRate: ratio,
+    acceptedTargetScoreMargin: finite.nullable(),
+    acceptedTargetCodeComplexity: searchJourneyTargetCodeComplexitySchema.optional(),
+    measurementContextId: nonEmpty,
+    measurementContextComplete: z.boolean(),
+    caveats: stringArray,
+  })
+  .strict();
+
+const journeyExecutionValueSchema = z
+  .object({ fingerprint: sha256Fingerprint, text: text.optional() })
+  .strict();
+const journeyExecutionContextSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    source: z.literal("caller-declared"),
+    agentModel: journeyExecutionValueSchema,
+    harness: journeyExecutionValueSchema,
+    searchStrategy: journeyExecutionValueSchema,
+    taskClass: journeyExecutionValueSchema,
+    taskMix: journeyExecutionValueSchema.optional(),
+    priorContext: journeyExecutionValueSchema.optional(),
+  })
+  .strict();
+const journeyExecutionEvidenceSchema = z
+  .object({
+    status: z.enum(["caller-declared", "not-recorded"]),
+    fingerprint: sha256Fingerprint.optional(),
+    uncontrolledDimensions: z.array(z.enum(SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS)),
+  })
+  .strict()
+  .superRefine((evidence, context) => {
+    if ((evidence.status === "caller-declared") !== (evidence.fingerprint !== undefined)) {
+      context.addIssue({
+        code: "custom",
+        message: "caller-declared conditions require a fingerprint",
+      });
+    }
+    if (new Set(evidence.uncontrolledDimensions).size !== evidence.uncontrolledDimensions.length) {
+      context.addIssue({ code: "custom", message: "uncontrolled dimensions must be unique" });
+    }
+    const allowedMissing =
+      evidence.status === "not-recorded"
+        ? SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS
+        : ["taskMix", "priorContext"];
+    if (
+      evidence.uncontrolledDimensions.some((dimension) => !allowedMissing.includes(dimension)) ||
+      (evidence.status === "not-recorded" &&
+        evidence.uncontrolledDimensions.length !==
+          SEARCH_JOURNEY_EXECUTION_CONTEXT_DIMENSIONS.length)
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "missing execution dimensions must agree with declaration status",
+      });
+    }
+  });
+
+const searchJourneySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    revision: nonNegativeInt,
+    sessionId: nonEmpty,
+    workspaceId: nonEmpty,
+    status: z.enum(["active", "completed", "abandoned"]),
+    recordingConsent: z.literal("explicit"),
+    retainText: z.boolean(),
+    goal: z.object({ fingerprint: nonEmpty, text: text.optional() }).strict(),
+    feature: z
+      .object({ fingerprint: sha256Fingerprint, text: text.optional() })
+      .strict()
+      .optional(),
+    executionContext: journeyExecutionContextSchema.optional(),
+    createdAt: nonEmpty,
+    updatedAt: nonEmpty,
+    attempts: z.array(searchJourneyAttemptSchema),
+    navigation: z.array(
+      z
+        .object({
+          eventId: nonEmpty,
+          sequence: positiveInt,
+          kind: z.enum(["open-file", "open-symbol", "graph-query", "other-tool"]),
+          observedAt: nonEmpty,
+          toolName: nonEmpty.optional(),
+          target: searchJourneyTargetSchema.optional(),
+        })
+        .strict(),
+    ),
+    outcome: z
+      .discriminatedUnion("kind", [
+        z
+          .object({
+            kind: z.literal("completed"),
+            completedAt: nonEmpty,
+            target: searchJourneyTargetSchema,
+            acceptedAttemptId: nonEmpty.optional(),
+            assessment: dynamicSearchComplexitySchema,
+          })
+          .strict(),
+        z
+          .object({
+            kind: z.literal("abandoned"),
+            abandonedAt: nonEmpty,
+            reasonCode: z.enum(SEARCH_JOURNEY_ABANDON_REASON_CODES).optional(),
+            reason: text.optional(),
+          })
+          .strict(),
+      ])
+      .optional(),
+  })
+  .strict()
+  .superRefine((session, context) => {
+    const validationIssue = searchJourneyValidationIssue(session);
+    if (validationIssue !== null) {
+      context.addIssue({
+        code: "custom",
+        message: `invalid search journey: ${validationIssue}`,
+      });
+    }
+    const terminalKind = session.outcome?.kind;
+    if (
+      (session.status === "active" && terminalKind !== undefined) ||
+      (session.status === "completed" && terminalKind !== "completed") ||
+      (session.status === "abandoned" && terminalKind !== "abandoned")
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "search journey status and outcome are inconsistent",
+      });
+    }
+    if (
+      !session.retainText &&
+      (session.goal.text !== undefined ||
+        session.attempts.some(
+          (attempt) => attempt.queryText !== undefined || attempt.failureReason !== undefined,
+        ))
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "redacted search journey contains retained text",
+      });
+    }
+    if (session.attempts.some((attempt, index) => attempt.sequence !== index + 1)) {
+      context.addIssue({ code: "custom", message: "search journey attempts are not ordered" });
+    }
+    const numbered = session.attempts.filter((attempt) => attempt.clientStep !== undefined);
+    if (numbered.length !== 0 && numbered.length !== session.attempts.length) {
+      context.addIssue({
+        code: "custom",
+        message: "search journey mixes numbered and unnumbered attempts",
+      });
+    }
+  });
+
+const dynamicProductComplexityCohortSchema = z
+  .object({
+    measurementContextId: sha256Fingerprint,
+    completedSessionCount: positiveInt,
+    measurementContextComplete: z.boolean(),
+    sufficientEvidence: z.boolean(),
+    minimumCompletedSessions: z.literal(MINIMUM_PRODUCT_COMPLEXITY_SESSIONS),
+    executionContext: journeyExecutionEvidenceSchema.optional(),
+    callerConditionsControlled: z.boolean().optional(),
+    medianSearchesToTarget: finite.positive(),
+    p90SearchesToTarget: finite.positive(),
+    medianQueryReformulations: nonNegative,
+    medianAcceptedTargetRank: finite.positive().nullable(),
+    meanReciprocalRank: ratio.nullable(),
+    targetReturnedRate: ratio,
+    directHitRate: ratio,
+    healthyRetrievalRate: ratio,
+    medianEligibleCandidatesExamined: nonNegative,
+    medianUniqueFilesExposed: nonNegative,
+    meanCandidateFileDispersion: ratio.nullable(),
+    meanCandidateChurn: ratio.nullable(),
+    candidateLimitHitRate: ratio,
+    caveats: stringArray,
+  })
+  .strict()
+  .superRefine((cohort, context) => {
+    if (
+      cohort.callerConditionsControlled !== undefined &&
+      cohort.callerConditionsControlled !==
+        (cohort.executionContext?.status === "caller-declared" &&
+          cohort.executionContext.uncontrolledDimensions.length === 0)
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "caller conditions require all declared dimensions",
+      });
+    }
+    const expectedSufficient =
+      cohort.measurementContextComplete &&
+      cohort.completedSessionCount >= cohort.minimumCompletedSessions;
+    if (cohort.sufficientEvidence !== expectedSufficient) {
+      context.addIssue({
+        code: "custom",
+        path: ["sufficientEvidence"],
+        message: "sufficient evidence requires a complete context and the minimum cohort size",
+      });
+    }
+    if (cohort.p90SearchesToTarget < cohort.medianSearchesToTarget) {
+      context.addIssue({
+        code: "custom",
+        path: ["p90SearchesToTarget"],
+        message: "p90 searches must not be below the median",
+      });
+    }
+    if (cohort.measurementContextComplete && cohort.healthyRetrievalRate !== 1) {
+      context.addIssue({
+        code: "custom",
+        path: ["healthyRetrievalRate"],
+        message: "a complete measurement context requires fully healthy retrieval",
+      });
+    }
+    if (cohort.directHitRate > cohort.targetReturnedRate) {
+      context.addIssue({
+        code: "custom",
+        path: ["directHitRate"],
+        message: "the direct-hit rate cannot exceed the target-returned rate",
+      });
+    }
+  });
+
+const featureCodeComplexityVariantSchema = z
+  .object({
+    evidence: searchJourneyTargetCodeComplexitySchema,
+    completedSessionCount: positiveInt,
+  })
+  .strict();
+
+const featureCodeTargetMappingSchema = z
+  .object({
+    target: searchJourneyTargetSchema,
+    completedSessionCount: positiveInt,
+    complexityVariants: z.array(featureCodeComplexityVariantSchema).min(1),
+  })
+  .strict()
+  .superRefine((mapping, context) => {
+    const variantKeys = mapping.complexityVariants.map((variant) =>
+      canonicalJson(variant.evidence),
+    );
+    if (new Set(variantKeys).size !== variantKeys.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["complexityVariants"],
+        message: "complexity evidence variants must be unique",
+      });
+    }
+    for (const [index, variant] of mapping.complexityVariants.entries()) {
+      if (variant.evidence.status !== "observed") continue;
+      const candidate = variant.evidence.candidate;
+      const target = mapping.target;
+      const matches =
+        (target.repoId === undefined || target.repoId === candidate.repoId) &&
+        (target.refId === undefined || target.refId === candidate.refId) &&
+        (target.filePath === undefined || target.filePath === candidate.filePath) &&
+        (target.chunkId === undefined || target.chunkId === candidate.chunkId) &&
+        (target.symbolId === undefined || target.symbolId === candidate.symbolId) &&
+        (target.embeddingProfileId === undefined ||
+          target.embeddingProfileId === candidate.embeddingProfileId) &&
+        (target.indexGeneration === undefined ||
+          target.indexGeneration === candidate.indexGeneration);
+      if (!matches) {
+        context.addIssue({
+          code: "custom",
+          path: ["complexityVariants", index, "evidence", "candidate"],
+          message: "observed complexity candidate must match the confirmed target locator",
+        });
+      }
+    }
+    const variantSessions = mapping.complexityVariants.reduce(
+      (sum, variant) => sum + variant.completedSessionCount,
+      0,
+    );
+    if (variantSessions !== mapping.completedSessionCount) {
+      context.addIssue({
+        code: "custom",
+        path: ["complexityVariants"],
+        message: "complexity variants must account for every completed target session",
+      });
+    }
+  });
+
+const dynamicProductComplexityFeatureMappingSchema = z
+  .object({
+    featureFingerprint: sha256Fingerprint,
+    measurementContextId: sha256Fingerprint,
+    distinctGoalCount: positiveInt,
+    search: dynamicProductComplexityCohortSchema,
+    code: z
+      .object({
+        confirmedTargetCount: positiveInt,
+        observedComplexitySessionCount: nonNegativeInt,
+        unavailableComplexitySessionCount: nonNegativeInt,
+        targets: z.array(featureCodeTargetMappingSchema).min(1),
+      })
+      .strict(),
+    caveats: stringArray,
+  })
+  .strict()
+  .superRefine((mapping, context) => {
+    if (mapping.search.measurementContextId !== mapping.measurementContextId) {
+      context.addIssue({
+        code: "custom",
+        path: ["search", "measurementContextId"],
+        message: "feature mapping and search cohort must share a measurement context",
+      });
+    }
+    if (mapping.distinctGoalCount > mapping.search.completedSessionCount) {
+      context.addIssue({
+        code: "custom",
+        path: ["distinctGoalCount"],
+        message: "distinct goals cannot exceed completed feature sessions",
+      });
+    }
+    if (mapping.code.confirmedTargetCount !== mapping.code.targets.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["code", "confirmedTargetCount"],
+        message: "confirmed target count must equal the target mapping count",
+      });
+    }
+    const targetKeys = mapping.code.targets.map((target) => canonicalJson(target.target));
+    if (new Set(targetKeys).size !== targetKeys.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["code", "targets"],
+        message: "confirmed feature targets must be unique",
+      });
+    }
+    const targetSessions = mapping.code.targets.reduce(
+      (sum, target) => sum + target.completedSessionCount,
+      0,
+    );
+    if (targetSessions !== mapping.search.completedSessionCount) {
+      context.addIssue({
+        code: "custom",
+        path: ["code", "targets"],
+        message: "target mappings must account for every completed feature session",
+      });
+    }
+    const observedSessions = mapping.code.targets.reduce(
+      (sum, target) =>
+        sum +
+        target.complexityVariants.reduce(
+          (targetSum, variant) =>
+            targetSum +
+            (variant.evidence.status === "observed" ? variant.completedSessionCount : 0),
+          0,
+        ),
+      0,
+    );
+    if (
+      observedSessions !== mapping.code.observedComplexitySessionCount ||
+      targetSessions - observedSessions !== mapping.code.unavailableComplexitySessionCount
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["code"],
+        message: "observed and unavailable complexity counts must partition feature sessions",
+      });
+    }
+  });
+
+const journeyOutcomeCohortSchema = z
+  .object({
+    measurementContextId: sha256Fingerprint,
+    retrievalContextId: sha256Fingerprint,
+    executionContext: journeyExecutionEvidenceSchema,
+    featureFingerprint: sha256Fingerprint.optional(),
+    distinctGoalCount: positiveInt,
+    sessionCounts: z
+      .object({
+        total: positiveInt,
+        active: nonNegativeInt,
+        completed: nonNegativeInt,
+        abandoned: nonNegativeInt,
+        terminal: nonNegativeInt,
+      })
+      .strict(),
+    terminalCompletionRate: ratio.nullable(),
+    retrievalContextComplete: z.boolean(),
+    statusEffort: z.array(
+      z
+        .object({
+          status: z.enum(["active", "completed", "abandoned"]),
+          sessionCount: nonNegativeInt,
+          sessionsWithSearches: nonNegativeInt,
+          totalSearches: nonNegativeInt,
+          failedSearches: nonNegativeInt,
+          totalNavigationEvents: nonNegativeInt,
+          totalObservedHops: nonNegativeInt,
+          medianSearches: nonNegative.nullable(),
+        })
+        .strict(),
+    ),
+    abandonmentReasons: z.array(
+      z
+        .object({
+          reasonCode: z.enum([...SEARCH_JOURNEY_ABANDON_REASON_CODES, "not-recorded"]),
+          count: positiveInt,
+        })
+        .strict(),
+    ),
+    caveats: stringArray,
+  })
+  .strict()
+  .superRefine((cohort, context) => {
+    const counts = cohort.sessionCounts;
+    if (
+      counts.total !== counts.active + counts.completed + counts.abandoned ||
+      counts.terminal !== counts.completed + counts.abandoned ||
+      cohort.distinctGoalCount > counts.total
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "outcome session counts must partition their cohort",
+      });
+    }
+    const expectedRate = counts.terminal === 0 ? null : counts.completed / counts.terminal;
+    if (cohort.terminalCompletionRate !== expectedRate) {
+      context.addIssue({
+        code: "custom",
+        message: "completion rate must use completed plus abandoned sessions",
+      });
+    }
+    if (
+      cohort.statusEffort.length !== 3 ||
+      new Set(cohort.statusEffort.map((effort) => effort.status)).size !== 3
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "outcome effort must include each session status once",
+      });
+    }
+    for (const effort of cohort.statusEffort) {
+      if (
+        effort.sessionCount !== counts[effort.status] ||
+        effort.sessionsWithSearches > effort.sessionCount ||
+        effort.sessionsWithSearches > effort.totalSearches ||
+        effort.failedSearches > effort.totalSearches ||
+        effort.totalObservedHops !== effort.totalSearches + effort.totalNavigationEvents ||
+        (effort.sessionCount === 0) !== (effort.medianSearches === null) ||
+        (effort.sessionCount === 0 && effort.totalObservedHops !== 0) ||
+        (effort.sessionsWithSearches === 0) !== (effort.totalSearches === 0) ||
+        (effort.medianSearches !== null && effort.medianSearches > effort.totalSearches)
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "outcome effort must account for its status sessions and observations",
+        });
+      }
+    }
+    if (
+      cohort.abandonmentReasons.reduce((sum, reason) => sum + reason.count, 0) !==
+        counts.abandoned ||
+      new Set(cohort.abandonmentReasons.map((reason) => reason.reasonCode)).size !==
+        cohort.abandonmentReasons.length
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "abandonment reasons must partition abandoned sessions",
+      });
+    }
+  });
+
+const dynamicProductComplexityReportSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    algorithm: z.literal("untangle-dynamic-search-complexity-v1"),
+    isHeuristic: z.literal(true),
+    workspaceId: nonEmpty,
+    generatedAt: nonEmpty,
+    sessionCounts: z
+      .object({
+        total: nonNegativeInt,
+        active: nonNegativeInt,
+        completed: nonNegativeInt,
+        featureTaggedCompleted: nonNegativeInt,
+        abandoned: nonNegativeInt,
+      })
+      .strict(),
+    cohorts: z.array(dynamicProductComplexityCohortSchema),
+    featureMappings: z.array(dynamicProductComplexityFeatureMappingSchema),
+    outcomeCohorts: z.array(journeyOutcomeCohortSchema).optional(),
+    caveats: stringArray,
+  })
+  .strict()
+  .superRefine((report, context) => {
+    const counts = report.sessionCounts;
+    if (report.outcomeCohorts !== undefined) {
+      const keys = report.outcomeCohorts.map(
+        (cohort) => `${cohort.measurementContextId}:${cohort.featureFingerprint ?? ""}`,
+      );
+      for (const status of ["total", "active", "completed", "abandoned"] as const) {
+        if (
+          report.outcomeCohorts.reduce((sum, cohort) => sum + cohort.sessionCounts[status], 0) !==
+          counts[status]
+        ) {
+          context.addIssue({
+            code: "custom",
+            message: "outcome cohorts must partition all recorded sessions",
+          });
+        }
+      }
+      if (new Set(keys).size !== keys.length) {
+        context.addIssue({
+          code: "custom",
+          message: "outcome context and feature pairs must be unique",
+        });
+      }
+    }
+    if (counts.total !== counts.active + counts.completed + counts.abandoned) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionCounts", "total"],
+        message: "total sessions must equal active, completed and abandoned sessions",
+      });
+    }
+    if (counts.featureTaggedCompleted > counts.completed) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionCounts", "featureTaggedCompleted"],
+        message: "feature-tagged completed sessions cannot exceed completed sessions",
+      });
+    }
+    const contextIds = report.cohorts.map((cohort) => cohort.measurementContextId);
+    if (new Set(contextIds).size !== contextIds.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["cohorts"],
+        message: "measurement context IDs must be unique",
+      });
+    }
+    const cohortSessions = report.cohorts.reduce(
+      (sum, cohort) => sum + cohort.completedSessionCount,
+      0,
+    );
+    if (cohortSessions !== counts.completed) {
+      context.addIssue({
+        code: "custom",
+        path: ["cohorts"],
+        message: "every completed session must belong to exactly one cohort",
+      });
+    }
+    const featureKeys = report.featureMappings.map(
+      (mapping) => `${mapping.featureFingerprint}\u001f${mapping.measurementContextId}`,
+    );
+    if (new Set(featureKeys).size !== featureKeys.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["featureMappings"],
+        message: "feature and measurement-context pairs must be unique",
+      });
+    }
+    const featureSessions = report.featureMappings.reduce(
+      (sum, mapping) => sum + mapping.search.completedSessionCount,
+      0,
+    );
+    if (featureSessions !== counts.featureTaggedCompleted) {
+      context.addIssue({
+        code: "custom",
+        path: ["featureMappings"],
+        message: "feature mappings must account for every feature-tagged completed session",
+      });
+    }
+    const knownContexts = new Set(contextIds);
+    for (const [index, mapping] of report.featureMappings.entries()) {
+      if (!knownContexts.has(mapping.measurementContextId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["featureMappings", index, "measurementContextId"],
+          message: "feature mapping must reference an existing workspace cohort",
+        });
+      }
+    }
+    for (const cohort of report.cohorts) {
+      const taggedInContext = report.featureMappings
+        .filter((mapping) => mapping.measurementContextId === cohort.measurementContextId)
+        .reduce((sum, mapping) => sum + mapping.search.completedSessionCount, 0);
+      if (taggedInContext > cohort.completedSessionCount) {
+        context.addIssue({
+          code: "custom",
+          path: ["featureMappings"],
+          message: "feature sessions in a context cannot exceed its completed cohort sessions",
+        });
+      }
+    }
+  });
+
+const searchSessionResultSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("start"), session: searchJourneySchema }).strict(),
+  z.object({ action: z.literal("get"), session: searchJourneySchema }).strict(),
+  z.object({ action: z.literal("observe"), session: searchJourneySchema }).strict(),
+  z.object({ action: z.literal("complete"), session: searchJourneySchema }).strict(),
+  z.object({ action: z.literal("abandon"), session: searchJourneySchema }).strict(),
+  z.object({ action: z.literal("report"), report: dynamicProductComplexityReportSchema }).strict(),
+]);
+
+const graphConfidenceSchema = z
+  .object({ value: ratio, basis: z.enum(["deterministic", "heuristic"]), signals: stringArray })
+  .strict();
+
+const symbolNodeSchema = z
+  .object({
+    id: nonEmpty,
+    name: text,
+    qualifiedName: text,
+    kind: text,
+    signature: text.optional(),
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    fileId: nonEmpty,
+    filePath: text,
+    language: text,
+    startLine: positiveInt,
+    endLine: positiveInt,
+    startByte: nonNegativeInt,
+    endByte: nonNegativeInt,
+    exportedAs: stringArray.optional(),
+    visibility: text.optional(),
+    contentHash: text,
+  })
+  .strict();
+
+const symbolEdgeTargetSchema = z
+  .object({
+    symbolId: nonEmpty,
+    qualifiedName: text,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    filePath: text,
+  })
+  .strict();
+
+const symbolEdgeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    edgeId: nonEmpty,
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    fromSymbolId: nonEmpty,
+    kind: z.enum(["calls", "references", "extends", "implements", "overrides", "unresolved"]),
+    toName: text,
+    toQualifier: text.optional(),
+    resolution: z.enum(["exact", "heuristic", "ambiguous", "unresolved"]),
+    target: symbolEdgeTargetSchema.optional(),
+    candidates: z.array(symbolEdgeTargetSchema.extend({ weight: ratio }).strict()).optional(),
+    unresolvedReason: z
+      .enum([
+        "no_candidate_found",
+        "target_outside_index",
+        "target_in_unparsed_file",
+        "dynamic_dispatch_not_statically_analyzable",
+        "import_unresolved",
+        "budget_exceeded",
+      ])
+      .optional(),
+    unresolvedDetail: text.optional(),
+    confidence: graphConfidenceSchema,
+    crossRepo: z.boolean(),
+    sites: z.array(
+      z
+        .object({
+          repoId: nonEmpty,
+          refId: nonEmpty,
+          filePath: text,
+          range: sourceRangeSchema,
+          column: positiveInt.optional(),
+        })
+        .strict(),
+    ),
+    sitesMissingReason: text.optional(),
+    occurrenceOrdinal: nonNegativeInt,
+    graphGeneration: nonEmpty,
+    graphVersion: nonEmpty,
+  })
+  .strict();
+
+const symbolBindingSchema = z
+  .object({
+    symbolId: nonEmpty,
+    edgeId: nonEmpty,
+    resolution: z.enum(["exact", "heuristic", "ambiguous", "unresolved"]),
+    weight: ratio,
+    ambiguous: z.boolean(),
+  })
+  .strict();
+
+const traversalLimitsSchema = z
+  .object({
+    maxDepth: nonNegativeInt,
+    maxNodes: positiveInt,
+    maxEdges: positiveInt,
+    maxWallTimeMs: positiveInt,
+  })
+  .strict();
+
+const traversalResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    direction: z.enum(["forward", "reverse"]),
+    rootSymbolIds: stringArray,
+    visitedSymbolIds: stringArray,
+    edgeIds: stringArray,
+    depthReached: nonNegativeInt,
+    truncated: z.boolean(),
+    truncationReason: z
+      .enum(["max_depth", "max_nodes", "max_edges", "max_wall_time", "cancelled"])
+      .optional(),
+    revisitSkippedSymbolIds: stringArray,
+    limits: traversalLimitsSchema,
+  })
+  .strict();
+
+const callPathSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    symbolIds: stringArray,
+    edgeIds: stringArray,
+    depth: nonNegativeInt,
+    confidence: ratio,
+    weakestResolution: z.enum(["exact", "heuristic", "ambiguous", "unresolved"]),
+    containsAmbiguous: z.boolean(),
+  })
+  .strict();
+
+const shortestPathSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    path: callPathSchema.nullable(),
+    missReason: z
+      .enum(["unknown_source_symbol", "unknown_target_symbol", "no_path_within_limits"])
+      .optional(),
+    missDetail: text.optional(),
+    truncated: z.boolean(),
+    truncationReason: z
+      .enum(["max_depth", "max_nodes", "max_edges", "max_wall_time", "cancelled"])
+      .optional(),
+    limits: traversalLimitsSchema,
+  })
+  .strict();
+
+const allPathsSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    paths: z.array(callPathSchema),
+    missReason: z
+      .enum(["unknown_source_symbol", "unknown_target_symbol", "no_path_within_limits"])
+      .optional(),
+    missDetail: text.optional(),
+    truncated: z.boolean(),
+    truncationReason: z
+      .enum(["max_depth", "max_nodes", "max_edges", "max_wall_time", "max_paths", "cancelled"])
+      .optional(),
+    droppedPathCount: nonNegativeInt,
+    droppedPathCountExact: z.boolean(),
+    pathLimitReached: z.boolean(),
+    skipped: z.array(skipLedgerEntrySchema),
+    maxDepth: nonNegativeInt,
+  })
+  .strict();
+
+const impactResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    rootSymbolIds: stringArray,
+    affected: z.array(
+      z
+        .object({
+          symbolId: nonEmpty,
+          qualifiedName: text,
+          filePath: text,
+          repoId: nonEmpty,
+          depth: nonNegativeInt,
+          minDepth: nonNegativeInt,
+          confidence: ratio,
+          weakestResolution: z.enum(["exact", "heuristic", "ambiguous", "unresolved"]),
+          viaEdgeIds: stringArray,
+          throughAmbiguous: z.boolean(),
+        })
+        .strict(),
+    ),
+    containsAmbiguousEdges: z.boolean(),
+    ambiguousEdgeIds: stringArray,
+    minConfidence: ratio,
+    traversal: traversalResultSchema,
+    skipped: z.array(skipLedgerEntrySchema),
+  })
+  .strict();
+
+const fileNodeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    fileId: nonEmpty,
+    filePath: text,
+    language: text,
+    contentHash: text,
+    imports: stringArray,
+    dependencies: stringArray,
+    dependents: stringArray,
+    graphGeneration: nonEmpty,
+    packageName: text.optional(),
+    containerService: text.optional(),
+    unresolvedImportCount: nonNegativeInt,
+  })
+  .strict();
+
+const fileEdgeResolutionSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("resolved"),
+      mechanism: nonEmpty,
+      targetFileId: nonEmpty,
+      targetRepoId: nonEmpty,
+      targetRefId: nonEmpty,
+      targetPath: text,
+      viaPackageName: text.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      status: z.literal("external"),
+      mechanism: nonEmpty,
+      packageName: nonEmpty,
+      declaredVersion: text.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      status: z.literal("unresolved"),
+      reason: nonEmpty,
+      detail: nonEmpty,
+      rejectedCandidates: stringArray.optional(),
+    })
+    .strict(),
+]);
+
+const fileEdgeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    edgeId: nonEmpty,
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    fromFileId: nonEmpty,
+    fromPath: text,
+    kind: z.enum([
+      "import",
+      "re-export",
+      "dynamic-import",
+      "asset-reference",
+      "config-reference",
+      "unresolved",
+    ]),
+    rawSpecifier: nonEmpty,
+    resolution: fileEdgeResolutionSchema,
+    boundary: z
+      .object({
+        crossRepo: z.boolean(),
+        crossPackage: z.boolean(),
+        crossContainer: z.boolean(),
+        fromPackageName: text.optional(),
+        toPackageName: text.optional(),
+        fromContainerService: text.optional(),
+        toContainerService: text.optional(),
+      })
+      .strict(),
+    sites: z.array(
+      z
+        .object({
+          range: sourceRangeSchema,
+          importedNames: stringArray.optional(),
+          typeOnly: z.boolean().optional(),
+        })
+        .strict(),
+    ),
+    sitesMissingReason: text.optional(),
+    occurrenceOrdinal: nonNegativeInt,
+    graphGeneration: nonEmpty,
+    graphVersion: nonEmpty,
+  })
+  .strict();
+
+const centralitySchema = z
+  .object({
+    fileId: nonEmpty,
+    filePath: text,
+    inDegree: nonNegativeInt,
+    outDegree: nonNegativeInt,
+    centrality: ratio,
+  })
+  .strict();
+
+const fileGraphMetricsSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    workspaceId: nonEmpty,
+    graphGeneration: nonEmpty,
+    graphVersion: nonEmpty,
+    nodeCount: nonNegativeInt,
+    edgeCount: nonNegativeInt,
+    orphanFileIds: stringArray,
+    stronglyConnectedComponents: z.array(stringArray),
+    cycles: z.array(stringArray),
+    importResolution: z
+      .object({
+        resolvedCount: nonNegativeInt,
+        externalCount: nonNegativeInt,
+        unresolvedCount: nonNegativeInt,
+        rate: ratio,
+      })
+      .strict(),
+    repositoryDistribution: numberMap,
+    languageDistribution: numberMap,
+    topCentralFiles: z.array(centralitySchema),
+    centralityFormula: nonEmpty,
+    truncationReason: text.optional(),
+  })
+  .strict();
+
+const snapshotReadIssueSchema = z
+  .object({
+    kind: z.enum([
+      "missing_meta",
+      "missing_path_index",
+      "missing_file_shard",
+      "malformed_payload",
+      "count_mismatch",
+      "workspace_scope_required",
+      "scope_mismatch",
+    ]),
+    message: nonEmpty,
+  })
+  .strict();
+
+const fileTraversalSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    direction: z.enum(["forward", "reverse"]),
+    rootFileIds: stringArray,
+    visitedFileIds: stringArray,
+    edgeIds: stringArray,
+    depthReached: nonNegativeInt,
+    truncated: z.boolean(),
+    truncationReason: z
+      .enum(["max_depth", "max_nodes", "max_edges", "max_wall_time", "cancelled"])
+      .optional(),
+    revisitSkippedFileIds: stringArray,
+    cycles: z.array(stringArray),
+    unvisitedRootFileIds: stringArray.optional(),
+    unknownRootFileIds: stringArray.optional(),
+    limits: traversalLimitsSchema,
+    visitedPaths: stringArray,
+    cyclePaths: z.array(stringArray),
+  })
+  .strict();
+
+const boundaryCountsSchema = z
+  .object({
+    crossRepo: nonNegativeInt,
+    crossPackage: nonNegativeInt,
+    crossContainer: nonNegativeInt,
+  })
+  .strict();
+
+const graphFileViewSchema = z
+  .object({
+    generationId: nonEmpty,
+    workspaceId: nonEmpty,
+    node: fileNodeSchema,
+    edges: z.array(fileEdgeSchema),
+    dependencies: fileTraversalSchema.optional(),
+    dependents: fileTraversalSchema.optional(),
+    issues: z.array(snapshotReadIssueSchema),
+  })
+  .strict();
+
+const boundedGraphFileViewSchema = graphFileViewSchema.extend({
+  truncated: z.boolean(),
+  omittedCount: nonNegativeInt,
+});
+
+const graphViewStatsSchema = z
+  .object({
+    inputNodeCount: nonNegativeInt,
+    shownNodeCount: nonNegativeInt,
+    nodeLimitDroppedCount: nonNegativeInt,
+    sourceEdgeCount: nonNegativeInt,
+    candidateLinkCount: nonNegativeInt,
+    renderableLinkCount: nonNegativeInt,
+    shownLinkCount: nonNegativeInt,
+    unrenderableSourceEdgeCount: nonNegativeInt,
+    missingEndpointLinkCount: nonNegativeInt,
+    nodeLimitDroppedLinkCount: nonNegativeInt,
+    edgeLimitDroppedLinkCount: nonNegativeInt,
+  })
+  .strict();
+
+const graphVisualizationArtifactShape = {
+  path: nonEmpty,
+  bytes: positiveInt,
+  sha256: text.regex(/^[0-9a-f]{64}$/u),
+  limits: z.object({ maxNodes: positiveInt, maxEdges: positiveInt }).strict(),
+};
+
+const graphVisualizationShape = {
+  generationId: nonEmpty,
+  workspaceId: nonEmpty,
+  issues: z.array(snapshotReadIssueSchema),
+};
+
+const graphVisualizationSchema = z.union([
+  z
+    .object({
+      ...graphVisualizationShape,
+      artifact: z
+        .object({
+          ...graphVisualizationArtifactShape,
+          views: z.object({ file: graphViewStatsSchema, symbol: graphViewStatsSchema }).strict(),
+        })
+        .strict(),
+      symbolGraph: z.object({ available: z.literal(true) }).strict(),
+    })
+    .strict(),
+  z
+    .object({
+      ...graphVisualizationShape,
+      artifact: z
+        .object({
+          ...graphVisualizationArtifactShape,
+          views: z.object({ file: graphViewStatsSchema, symbol: z.null() }).strict(),
+        })
+        .strict(),
+      symbolGraph: z.object({ available: z.literal(false), missingReason: nonEmpty }).strict(),
+    })
+    .strict(),
+]);
+
+const symbolListSchema = z
+  .object({
+    generationId: nonEmpty,
+    symbols: z.array(symbolNodeSchema),
+    total: nonNegativeInt,
+    truncated: z.boolean(),
+  })
+  .strict();
+
+const symbolDetailSchema = z
+  .object({
+    generationId: nonEmpty,
+    matchedBy: z.enum(["symbol_id", "qualified_name", "file_and_name", "name"]).optional(),
+    symbol: symbolNodeSchema,
+    outgoing: z.array(symbolEdgeSchema),
+    callers: z.array(symbolBindingSchema),
+  })
+  .strict();
+
+const boundedFlowSymbolDetailSchema = symbolDetailSchema.extend({
+  truncated: z.boolean(),
+  omittedCount: nonNegativeInt,
+});
+
+const flowSchema = z.union([
+  boundedFlowSymbolDetailSchema,
+  z
+    .object({
+      generationId: nonEmpty,
+      from: symbolNodeSchema,
+      to: symbolNodeSchema,
+      shortest: shortestPathSchema,
+      all: allPathsSchema,
+    })
+    .strict(),
+]);
+
+const impactSchema = z
+  .object({
+    generationId: nonEmpty,
+    root: symbolNodeSchema,
+    impact: impactResultSchema,
+    truncated: z.boolean(),
+    omittedCount: nonNegativeInt,
+  })
+  .strict();
+
+const proseNumberSchema = z
+  .object({
+    proseMeasurement: z.literal(true),
+    value: finite,
+    unit: z.enum(["levels", "lines", "per_100_lines", "ratio", "count"]),
+  })
+  .strict();
+
+const complexitySymbolSchema = z
+  .object({
+    filePath: text,
+    name: text,
+    kind: text,
+    line: positiveInt,
+    executionUnit: z.boolean(),
+    cognitive: nonNegative,
+    cyclomatic: nonNegative,
+    sloc: nonNegative,
+  })
+  .strict();
+
+const complexityViolationSchema = z
+  .object({
+    filePath: text,
+    line: positiveInt,
+    name: text,
+    metric: z.enum(["cognitive", "cyclomatic"]),
+    value: nonNegative,
+    threshold: finite,
+  })
+  .strict();
+
+const proseSummarySchema = z
+  .object({
+    path: text,
+    metricsVersion: nonEmpty,
+    structureLoad: proseNumberSchema,
+    sectionCount: proseNumberSchema,
+    sectionDepth: proseNumberSchema,
+    maxSectionLines: proseNumberSchema,
+    linkDensity: proseNumberSchema,
+    unresolvedLinkRatio: proseNumberSchema.nullable(),
+    repetitionRatio: proseNumberSchema,
+    contentLines: proseNumberSchema,
+  })
+  .strict();
+
+const complexityReportSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    root: nonEmpty,
+    filesDiscovered: nonNegativeInt,
+    filesAnalyzed: nonNegativeInt,
+    filesProse: nonNegativeInt,
+    totalsReading: z.enum(["execution_unit"]).optional(),
+    totals: z
+      .object({
+        executionUnits: nonNegativeInt,
+        executionUnitRoots: nonNegativeInt.optional(),
+        cognitive: nonNegative,
+        cyclomatic: nonNegative,
+      })
+      .strict(),
+    hotspots: z.array(complexitySymbolSchema),
+    violations: z.array(complexityViolationSchema),
+    prose: z.array(proseSummarySchema),
+    skipped: z.array(skipLedgerEntrySchema),
+  })
+  .strict();
+
+const metricContributionSchema = z
+  .object({
+    line: positiveInt,
+    column: positiveInt.optional(),
+    kind: nonEmpty,
+    value: finite,
+    note: text.optional(),
+  })
+  .strict();
+
+const cognitiveContributionSchema = z
+  .object({
+    line: positiveInt,
+    column: positiveInt.optional(),
+    kind: nonEmpty,
+    base: finite,
+    nestingPenalty: finite,
+    total: finite,
+    note: text.optional(),
+  })
+  .strict();
+
+const complexitySnapshotSchema = z
+  .object({
+    snapshotId: nonEmpty,
+    scope: z.enum(["symbol", "file", "repository", "workspace"]),
+    scopeId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    commitSha: text.optional(),
+    metricsVersion: nonEmpty,
+    measuredAt: nonEmpty,
+    parseQuality: z.enum(["complete", "partial", "failed"]),
+    cyclomatic: z
+      .object({
+        classic: finite,
+        extended: finite,
+        contributors: z.array(metricContributionSchema),
+      })
+      .strict(),
+    cognitive: z
+      .object({
+        value: finite,
+        algorithm: nonEmpty,
+        contributors: z.array(cognitiveContributionSchema),
+      })
+      .strict(),
+    structural: numberMap,
+    textual: numberMap,
+    syntactic: numberMap,
+    halstead: numberMap,
+    maintainabilityIndex: finite,
+    maintainabilityFormula: nonEmpty,
+  })
+  .strict();
+
+const metricDeltaSchema = z
+  .object({
+    metric: nonEmpty,
+    baseValue: finite.nullable(),
+    headValue: finite.nullable(),
+    delta: finite.nullable(),
+    relativeDelta: finite.nullable(),
+  })
+  .strict();
+
+const changeEventSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    changeId: nonEmpty,
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    baseRef: nonEmpty,
+    headRef: nonEmpty,
+    baseCommit: text.optional(),
+    headCommit: text.optional(),
+    changedAt: nonEmpty,
+    changeKind: z.enum(["added", "modified", "deleted", "renamed", "moved", "moved_and_renamed"]),
+    oldSymbolId: text.optional(),
+    newSymbolId: text.optional(),
+    oldFilePath: text.optional(),
+    newFilePath: text.optional(),
+    textDiffSummary: z
+      .object({
+        linesAdded: nonNegativeInt,
+        linesRemoved: nonNegativeInt,
+        hunkCount: nonNegativeInt,
+        binary: z.boolean(),
+        bytesAdded: nonNegativeInt.optional(),
+        bytesRemoved: nonNegativeInt.optional(),
+      })
+      .strict(),
+    astDiffSummary: z
+      .object({
+        nodesAdded: nonNegativeInt,
+        nodesRemoved: nonNegativeInt,
+        nodesMoved: nonNegativeInt,
+        nodesUpdated: nonNegativeInt,
+        affectedNodeKinds: stringArray,
+        fingerprintChanged: z.boolean(),
+      })
+      .strict()
+      .optional(),
+    complexityDelta: z
+      .object({
+        metricsVersion: nonEmpty,
+        epsilon: nonNegative,
+        entries: z.array(metricDeltaSchema),
+      })
+      .strict()
+      .optional(),
+    graphDelta: z
+      .object({
+        addedFileImports: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        removedFileImports: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        addedSymbolCalls: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        removedSymbolCalls: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        addedCrossRepoEdges: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        removedCrossRepoEdges: z.array(
+          z
+            .object({
+              fromId: nonEmpty,
+              toId: nonEmpty,
+              edgeKind: nonEmpty,
+              crossRepo: z.boolean(),
+            })
+            .strict(),
+        ),
+        addedCycles: z.array(stringArray),
+        removedCycles: z.array(stringArray),
+        fanChanges: z.array(
+          z
+            .object({
+              nodeId: nonEmpty,
+              fanInBefore: nonNegativeInt,
+              fanInAfter: nonNegativeInt,
+              fanOutBefore: nonNegativeInt,
+              fanOutAfter: nonNegativeInt,
+            })
+            .strict(),
+        ),
+        impactSizeBefore: nonNegativeInt,
+        impactSizeAfter: nonNegativeInt,
+      })
+      .strict()
+      .optional(),
+    blastRadius: z
+      .object({
+        impactedFileCount: nonNegativeInt,
+        impactedSymbolCount: nonNegativeInt,
+        impactedRepoIds: stringArray,
+        maxDepthReached: nonNegativeInt,
+        truncated: z.boolean(),
+        truncationReason: text.optional(),
+        sampleImpactedSymbolIds: stringArray,
+      })
+      .strict()
+      .optional(),
+    risk: z
+      .object({
+        value: ratio,
+        level: z.enum(["low", "medium", "high", "critical"]),
+        algorithm: nonEmpty,
+        components: z.record(
+          z.string(),
+          z.object({ value: finite, weight: finite, contribution: finite }).strict(),
+        ),
+        caveats: stringArray,
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const qualityGateSchema = z
+  .object({
+    status: z.enum(["passed", "warning", "failed", "incomplete"]),
+    base: nonEmpty,
+    head: nonEmpty,
+    violations: z.array(
+      z
+        .object({
+          rule: nonEmpty,
+          severity: z.enum(["warning", "error"]),
+          scope: z.enum(["symbol", "file", "workspace"]),
+          scopeId: nonEmpty,
+          filePath: text.optional(),
+          symbolId: text.optional(),
+          symbolFqn: text.optional(),
+          metric: text.optional(),
+          baseValue: finite.optional(),
+          headValue: finite.optional(),
+          threshold: finite.optional(),
+          newViolation: z.boolean(),
+          worsened: z.boolean(),
+          message: nonEmpty,
+        })
+        .strict(),
+    ),
+    improvements: z.array(
+      z
+        .object({
+          rule: nonEmpty,
+          scope: z.enum(["symbol", "file", "workspace"]),
+          scopeId: nonEmpty,
+          filePath: text.optional(),
+          symbolId: text.optional(),
+          symbolFqn: text.optional(),
+          metric: text.optional(),
+          baseValue: finite.optional(),
+          headValue: finite.optional(),
+          message: nonEmpty,
+        })
+        .strict(),
+    ),
+    analysisCoverage: z
+      .object({
+        filesChanged: nonNegativeInt,
+        filesAnalyzed: nonNegativeInt,
+        symbolsChanged: nonNegativeInt,
+        parseFailures: nonNegativeInt,
+      })
+      .strict(),
+  })
+  .strict();
+
+// Portfolio contracts: portfolio.md sections 7 and 14.2.
+const portfolioEvidenceKindSchema = z.enum([
+  "manifest",
+  "lockfile",
+  "config",
+  "import_graph",
+  "symbol_graph",
+  "ci",
+  "container",
+  "iac",
+  "change_history",
+  "heuristic",
+]);
+
+const portfolioProvenanceSchema = z
+  .object({
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    commitSha: text.optional(),
+    sourceFile: text,
+    startLine: positiveInt.optional(),
+    endLine: positiveInt.optional(),
+    detectorId: nonEmpty,
+    detectorVersion: nonEmpty,
+    evidenceKind: portfolioEvidenceKindSchema,
+  })
+  .strict();
+
+const portfolioConfidenceSchema = z
+  .object({ value: ratio, basis: z.enum(["deterministic", "heuristic"]), signals: stringArray })
+  .strict();
+
+const repositoryHealthSchema = z
+  .object({
+    metricsVersion: nonEmpty,
+    measuredAt: nonEmpty,
+    maintainabilityIndexMedian: finite.optional(),
+    cognitiveP90: finite.optional(),
+    cyclomaticP90: finite.optional(),
+    dependencyCycleCount: nonNegativeInt.optional(),
+    hotspotShare: ratio.optional(),
+    unresolvedImportRatio: ratio.optional(),
+    parseFailureRatio: ratio.optional(),
+    caveats: stringArray,
+  })
+  .strict();
+
+const stackMatrixEntrySchema = z
+  .object({
+    technologyId: nonEmpty,
+    name: nonEmpty,
+    category: nonEmpty,
+    ecosystem: text.optional(),
+    problemDomain: text.optional(),
+    adoption: z
+      .object({ repoCount: nonNegativeInt, repoShare: ratio, repoIds: stringArray })
+      .strict(),
+    versionSpread: z
+      .object({
+        distinctVersions: stringArray,
+        byRepo: optionalStringMap,
+        majorSpread: nonNegativeInt,
+        comparable: z.boolean(),
+      })
+      .strict(),
+    usageDepth: z
+      .object({
+        importingFilesByRepo: z.record(z.string(), nonNegativeInt),
+        declaredOnlyRepos: stringArray,
+        importOnlyRepos: stringArray,
+      })
+      .strict(),
+    firstSeenAt: text.optional(),
+    lastSeenAt: text.optional(),
+    confidence: portfolioConfidenceSchema,
+  })
+  .strict();
+
+export const stackMatrixResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    matrixId: nonEmpty,
+    workspaceId: nonEmpty,
+    generationId: nonEmpty,
+    generatedAt: nonEmpty,
+    analyzerVersion: nonEmpty,
+    repositories: z.array(
+      z.object({ repoId: nonEmpty, refId: nonEmpty, profileId: nonEmpty }).strict(),
+    ),
+    entries: z.array(stackMatrixEntrySchema),
+    warnings: stringArray,
+  })
+  .strict();
+
+const conventionRuleSchema = z
+  .object({
+    ruleKind: z.enum([
+      "path_exists",
+      "path_layout",
+      "naming_pattern",
+      "dependency_present",
+      "layering",
+      "symbol_pattern",
+      "config_pattern",
+    ]),
+    expression: jsonMap,
+    humanReadable: nonEmpty,
+  })
+  .strict();
+
+const conventionSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    conventionId: nonEmpty,
+    workspaceId: nonEmpty,
+    generationId: nonEmpty,
+    kind: z.enum([
+      "directory_layout",
+      "layering",
+      "naming",
+      "test_setup",
+      "error_handling",
+      "config_handling",
+      "logging",
+    ]),
+    title: nonEmpty,
+    description: text,
+    rule: conventionRuleSchema,
+    evidence: z
+      .object({
+        applicableRepos: stringArray,
+        supportingRepos: stringArray,
+        matchCount: nonNegativeInt,
+        counterexamples: z.array(
+          z
+            .object({
+              repoId: nonEmpty,
+              provenance: portfolioProvenanceSchema,
+              note: text.optional(),
+            })
+            .strict(),
+        ),
+        sampleProvenance: z.array(portfolioProvenanceSchema),
+      })
+      .strict(),
+    confidence: portfolioConfidenceSchema,
+    detectorId: nonEmpty,
+    detectorVersion: nonEmpty,
+    heuristic: z.boolean(),
+  })
+  .strict();
+
+const archetypeNameSchema = z.enum([
+  "layered_service",
+  "hexagonal_service",
+  "modular_monolith",
+  "api_service",
+  "worker",
+  "cli_tool",
+  "library",
+  "frontend_app",
+  "mcp_server",
+  "infra_repo",
+  "monorepo_root",
+  "unclassified",
+]);
+
+const archetypeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    archetypeId: nonEmpty,
+    workspaceId: nonEmpty,
+    repoId: nonEmpty,
+    refId: nonEmpty,
+    generationId: nonEmpty,
+    classifierVersion: nonEmpty,
+    archetype: archetypeNameSchema,
+    score: ratio,
+    alternatives: z.array(z.object({ archetype: archetypeNameSchema, score: ratio }).strict()),
+    signals: z.array(
+      z
+        .object({
+          signalId: nonEmpty,
+          description: nonEmpty,
+          weight: finite,
+          matched: z.boolean(),
+          contribution: finite,
+          provenance: portfolioProvenanceSchema.optional(),
+          heuristic: z.boolean(),
+        })
+        .strict(),
+    ),
+    confidence: portfolioConfidenceSchema,
+  })
+  .strict();
+
+const radarEntrySchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    entryId: nonEmpty,
+    workspaceId: nonEmpty,
+    generationId: nonEmpty,
+    radarVersion: nonEmpty,
+    technologyId: nonEmpty,
+    name: nonEmpty,
+    category: nonEmpty,
+    problemDomain: text.optional(),
+    ring: z.enum(["adopt", "maintain", "consolidate", "retire"]),
+    ringReason: stringArray,
+    versionDrift: z
+      .object({
+        distinctVersions: stringArray,
+        majorSpread: nonNegativeInt,
+        byRepo: optionalStringMap,
+        comparable: z.boolean(),
+      })
+      .strict(),
+    duplicates: z.array(
+      z.object({ problemDomain: nonEmpty, competingTechnologyIds: stringArray }).strict(),
+    ),
+    trend: z
+      .object({
+        direction: z.enum(["converging", "diverging", "stable", "declining", "new", "unknown"]),
+        points: z.array(
+          z
+            .object({
+              window: nonEmpty,
+              repoCount: nonNegativeInt,
+              distinctVersionCount: nonNegativeInt,
+            })
+            .strict(),
+        ),
+      })
+      .strict(),
+    evidence: z.array(portfolioProvenanceSchema),
+    confidence: portfolioConfidenceSchema,
+  })
+  .strict();
+
+const blueprintKindSchema = z.enum([
+  "api-service",
+  "worker",
+  "cli",
+  "library",
+  "web-app",
+  "mcp-server",
+]);
+
+const blueprintFileSchema = z
+  .object({
+    path: text,
+    templateId: nonEmpty,
+    contentPreviewHash: nonEmpty,
+    sizeBytes: nonNegativeInt,
+  })
+  .strict();
+
+const blueprintDependencySchema = z
+  .object({
+    technologyId: nonEmpty,
+    name: nonEmpty,
+    ecosystem: nonEmpty,
+    version: nonEmpty,
+    usage: z.enum(["runtime", "dev"]),
+    recommendationId: nonEmpty,
+  })
+  .strict();
+
+const recommendationComponentSchema = z
+  .object({
+    name: z.enum(["adoption", "recency", "health", "version_consistency"]),
+    value: ratio,
+    weight: finite,
+    contribution: finite,
+    inputs: jsonMap,
+  })
+  .strict();
+
+const blueprintSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    blueprintId: nonEmpty,
+    workspaceId: nonEmpty,
+    generationId: nonEmpty,
+    advisorVersion: nonEmpty,
+    generatedAt: nonEmpty,
+    kind: blueprintKindSchema,
+    language: nonEmpty,
+    runtime: z.object({ name: nonEmpty, versionRange: nonEmpty }).strict(),
+    directoryLayout: z.array(
+      z
+        .object({
+          path: text,
+          kind: z.enum(["directory", "file"]),
+          purpose: nonEmpty,
+          sourceConventionId: text.optional(),
+        })
+        .strict(),
+    ),
+    dependencies: z.array(blueprintDependencySchema),
+    toolchain: z.array(blueprintDependencySchema),
+    testSetup: z
+      .object({ framework: nonEmpty, layout: nonEmpty, recommendationId: nonEmpty })
+      .strict(),
+    ciSkeleton: z
+      .object({ system: nonEmpty, workflowFiles: stringArray, recommendationId: nonEmpty })
+      .strict(),
+    appliedConventionIds: stringArray,
+    recommendationIds: stringArray,
+    files: z.array(blueprintFileSchema).optional(),
+    evidenceSummary: z
+      .object({
+        reposConsidered: nonNegativeInt,
+        reposMatchingKind: stringArray,
+        portfolioGenerationId: nonEmpty,
+      })
+      .strict(),
+    warnings: stringArray,
+  })
+  .strict();
+
+const blueprintRecommendationSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    recommendationId: nonEmpty,
+    blueprintId: nonEmpty,
+    workspaceId: nonEmpty,
+    generationId: nonEmpty,
+    advisorVersion: nonEmpty,
+    topic: nonEmpty,
+    recommended: z
+      .object({ technologyId: nonEmpty, name: nonEmpty, version: text.optional() })
+      .strict(),
+    fitScore: ratio,
+    components: z.array(recommendationComponentSchema),
+    evidence: z
+      .object({
+        supportingRepoIds: stringArray,
+        supportingRecordIds: stringArray,
+        healthByRepo: z.record(z.string(), repositoryHealthSchema.nullable()),
+      })
+      .strict(),
+    alternatives: z.array(
+      z
+        .object({
+          technologyId: nonEmpty,
+          name: nonEmpty,
+          version: text.optional(),
+          fitScore: ratio,
+          components: z.array(recommendationComponentSchema),
+          note: text.optional(),
+        })
+        .strict(),
+    ),
+    risks: z.array(
+      z
+        .object({
+          kind: z.enum([
+            "outdated_version",
+            "low_adoption",
+            "high_hotspot_share",
+            "version_divergence",
+            "single_repo_evidence",
+            "declared_only_evidence",
+            "heuristic_evidence",
+          ]),
+          severity: z.enum(["info", "warning", "critical"]),
+          message: nonEmpty,
+          evidence: z.array(portfolioProvenanceSchema),
+        })
+        .strict(),
+    ),
+    confidence: portfolioConfidenceSchema,
+  })
+  .strict();
+
+export const portfolioScanResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    jobId: nonEmpty,
+    generationId: nonEmpty,
+    status: z.enum(["queued", "running", "completed", "failed", "cancelled"]),
+    repositoriesPlanned: nonNegativeInt,
+    repositoriesCompleted: nonNegativeInt,
+    technologiesDetected: nonNegativeInt.optional(),
+    conventionsDetected: nonNegativeInt.optional(),
+    warnings: stringArray,
+  })
+  .strict();
+
+export const whoUsesResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    technology: z
+      .object({
+        technologyId: nonEmpty,
+        name: nonEmpty,
+        category: nonEmpty,
+        ecosystem: text.optional(),
+      })
+      .strict(),
+    generationId: nonEmpty,
+    usages: z.array(
+      z
+        .object({
+          repoId: nonEmpty,
+          repoLabel: text,
+          refId: nonEmpty,
+          versionRaw: text.optional(),
+          versionResolved: text.optional(),
+          usage: nonEmpty,
+          declaredOnly: z.boolean(),
+          importOnly: z.boolean(),
+          importingFileCount: nonNegativeInt.optional(),
+          firstSeenAt: text.optional(),
+          lastSeenAt: text.optional(),
+          provenance: z.array(portfolioProvenanceSchema),
+        })
+        .strict(),
+    ),
+    notUsingRepoIds: stringArray,
+    warnings: stringArray,
+  })
+  .strict();
+
+export const conventionsResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    generationId: nonEmpty,
+    conventions: z.array(conventionSchema),
+    suppressedCount: nonNegativeInt,
+    warnings: stringArray,
+  })
+  .strict();
+
+export const archetypesResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    generationId: nonEmpty,
+    classifierVersion: nonEmpty,
+    assignments: z.array(archetypeSchema),
+    warnings: stringArray,
+  })
+  .strict();
+
+export const techRadarResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    generationId: nonEmpty,
+    radarVersion: nonEmpty,
+    entries: z.array(radarEntrySchema),
+    historyAvailable: z.boolean(),
+    warnings: stringArray,
+  })
+  .strict();
+
+export const blueprintResultSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    blueprint: blueprintSchema,
+    recommendations: z.array(blueprintRecommendationSchema),
+    scaffold: z
+      .object({
+        mode: z.enum(["dry_run", "applied"]),
+        targetDir: nonEmpty,
+        files: z.array(blueprintFileSchema),
+        manifestPath: text.optional(),
+      })
+      .strict()
+      .optional(),
+    warnings: stringArray,
+  })
+  .strict();
+
+const graphStatusSchema = z
+  .object({
+    generationId: nonEmpty,
+    workspaceId: nonEmpty,
+    metrics: fileGraphMetricsSchema,
+    issues: z.array(snapshotReadIssueSchema),
+  })
+  .strict();
+
+const graphStatsSchema = z
+  .object({
+    generationId: nonEmpty,
+    metrics: fileGraphMetricsSchema,
+    boundaries: boundaryCountsSchema,
+    issues: z.array(snapshotReadIssueSchema),
+  })
+  .strict();
+
+const graphCyclesSchema = z
+  .object({
+    generationId: nonEmpty,
+    cycles: z.array(stringArray),
+    total: nonNegativeInt,
+    issues: z.array(snapshotReadIssueSchema),
+  })
+  .strict();
+
+const aboutSchema = z
+  .object({
+    name: z.literal("untangle"),
+    version: nonEmpty,
+    license: z.literal("AGPL-3.0-only"),
+    source: nonEmpty,
+    commit: nonEmpty,
+    availableTools: z.array(nonEmpty),
+    unavailableToolsReturn: z.literal("FEATURE_UNAVAILABLE"),
+  })
+  .strict();
+
+/** Tool-specific success payload contracts; none falls back to an arbitrary object. */
+const productSourceReferenceSchema = z.object({ path: text, heading: text }).strict();
+const productFileSelectionSchema = z
+  .object({ include: stringArray, exclude: stringArray.optional() })
+  .strict();
+const productManifestSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    owners: z.array(
+      z
+        .object({
+          id: text,
+          label: text,
+          kind: z.enum(["person", "team", "role"]),
+          status: z.enum(["declared", "confirmed"]),
+          confirmedBy: text.optional(),
+          sources: z.array(productSourceReferenceSchema),
+        })
+        .strict(),
+    ),
+    features: z.array(
+      z
+        .object({
+          id: text,
+          title: text,
+          stage: z.enum(["implemented", "planned"]),
+          review: z.enum(["proposed", "confirmed"]),
+          confirmedBy: text.optional(),
+          intent: z.array(
+            productSourceReferenceSchema.extend({ role: z.enum(["vision", "specification"]) }),
+          ),
+          owners: stringArray,
+          code: productFileSelectionSchema,
+          tests: productFileSelectionSchema,
+          criteria: z.array(
+            z
+              .object({
+                id: text,
+                description: text,
+                tests: stringArray,
+                testNames: stringArray.optional(),
+              })
+              .strict(),
+          ),
+          dependsOn: stringArray,
+          budgets: z
+            .object({
+              maxCognitivePerUnit: nonNegative.optional(),
+              maxCognitiveTotal: nonNegative.optional(),
+              maxCodeFiles: nonNegativeInt.optional(),
+              maxOwners: nonNegativeInt.optional(),
+            })
+            .strict()
+            .optional(),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+const productSourceEvidenceSchema = productSourceReferenceSchema.extend({
+  status: z.enum(["resolved", "missing", "ambiguous", "not_in_scan", "changed", "unreadable"]),
+  contentHash: sha256Fingerprint.optional(),
+  startLine: positiveInt.optional(),
+  endLine: positiveInt.optional(),
+});
+const productFileEvidenceSchema = z
+  .object({
+    path: nonEmpty,
+    status: z.enum([
+      "measured",
+      "not_in_scan",
+      "changed",
+      "unreadable",
+      "unsupported",
+      "partial",
+      "invalid_metrics",
+    ]),
+    contentHash: sha256Fingerprint.optional(),
+    scannedContentHash: sha256Fingerprint.optional(),
+  })
+  .strict();
+const productMetricReadingsSchema = z
+  .object({ top_level: nonNegative, execution_unit: nonNegative, self: nonNegative })
+  .strict();
+const productCodeMetricsSchema = z
+  .object({
+    metricsVersion: nonEmpty,
+    cognitiveAlgorithm: nonEmpty,
+    cognitive: productMetricReadingsSchema,
+    cyclomaticClassic: productMetricReadingsSchema,
+    cyclomaticExtended: productMetricReadingsSchema,
+    files: nonNegativeInt,
+    scopes: nonNegativeInt,
+    executionUnitRoots: nonNegativeInt,
+    sloc: nonNegativeInt,
+    cyclomaticPerScopeBase: z.literal(1),
+  })
+  .strict();
+const productMeasuredSelectionSchema = z
+  .object({
+    complete: z.boolean(),
+    files: z.array(productFileEvidenceSchema),
+    metrics: productCodeMetricsSchema.nullable(),
+  })
+  .strict();
+const productHotspotSchema = z
+  .object({
+    path: nonEmpty,
+    contentHash: sha256Fingerprint,
+    symbol: nonEmpty,
+    scopeId: nonEmpty,
+    startLine: positiveInt,
+    endLine: positiveInt,
+    cognitive: nonNegative,
+    cyclomaticClassic: nonNegative,
+    cyclomaticExtended: nonNegative,
+  })
+  .strict();
+const productAgentHintSchema = z
+  .object({
+    code: nonEmpty,
+    severity: z.enum(["info", "warning", "error"]),
+    message: text,
+    paths: stringArray,
+    suggestedAction: text,
+    search: z
+      .object({ symbol: nonEmpty, path: nonEmpty, requireFresh: z.literal(true) })
+      .strict()
+      .optional(),
+  })
+  .strict();
+const productFeatureAlignmentSchema = z
+  .object({
+    id: nonEmpty,
+    title: text,
+    stage: z.enum(["implemented", "planned"]),
+    review: z.enum(["proposed", "confirmed"]),
+    status: z.enum(["evidence_consistent", "needs_review", "incomplete", "violated"]),
+    intent: z.array(
+      productSourceEvidenceSchema.extend({ role: z.enum(["vision", "specification"]) }),
+    ),
+    ownership: z.array(
+      z
+        .object({
+          id: nonEmpty,
+          label: text.optional(),
+          status: z.enum(["declared", "confirmed", "missing"]),
+          sources: z.array(productSourceEvidenceSchema),
+        })
+        .strict(),
+    ),
+    code: productMeasuredSelectionSchema.extend({ hotspots: z.array(productHotspotSchema) }),
+    tests: productMeasuredSelectionSchema,
+    testEvidence: z
+      .object({
+        status: z.enum(["bound_passed", "bound_failed", "not_run", "stale", "invalid"]),
+        passed: nonNegativeInt,
+        failed: nonNegativeInt,
+        skipped: nonNegativeInt,
+        proof: z.enum(["supplied_source_bound_report", "none"]),
+      })
+      .strict(),
+    criteria: z.array(
+      z
+        .object({
+          id: nonEmpty,
+          description: text,
+          matchedFiles: stringArray,
+          status: z.enum(["passed", "failed", "not_run", "missing_tests", "unverified"]),
+        })
+        .strict(),
+    ),
+    dimensions: z
+      .object({
+        requirements: nonNegativeInt,
+        owners: nonNegativeInt,
+        codeFiles: nonNegativeInt,
+        testFiles: nonNegativeInt,
+        sharedCodeFiles: nonNegativeInt,
+        declaredDependencies: nonNegativeInt,
+        dependentFeatures: nonNegativeInt,
+      })
+      .strict(),
+    dependsOn: stringArray,
+    agentHints: z.array(productAgentHintSchema),
+    issues: stringArray,
+  })
+  .strict();
+const productAlignmentReportSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    root: nonEmpty,
+    status: z.enum([
+      "needs_manifest",
+      "invalid_manifest",
+      "evidence_consistent",
+      "needs_review",
+      "incomplete",
+      "violated",
+    ]),
+    manifest: z
+      .object({
+        path: nonEmpty,
+        status: z.enum(["missing", "loaded", "invalid", "not_in_scan", "changed", "unreadable"]),
+        contentHash: sha256Fingerprint.optional(),
+      })
+      .strict(),
+    sourceTreeDigest: sha256Fingerprint,
+    inventory: z
+      .object({ files: nonNegativeInt, truncated: z.boolean(), excluded: nonNegativeInt })
+      .strict(),
+    semanticConformance: z.literal("not_independently_proven"),
+    ownershipAuthority: z.literal("manifest_declarations"),
+    selection: z
+      .object({
+        path: nonEmpty,
+        status: z.enum(["matched", "unmapped", "missing", "not_in_scan", "changed", "unreadable"]),
+        matches: z.array(
+          z
+            .object({
+              featureId: nonEmpty,
+              roles: z.array(z.enum(["code", "test", "intent", "ownership"])),
+            })
+            .strict(),
+        ),
+      })
+      .strict()
+      .optional(),
+    testRun: z
+      .object({
+        status: z.enum([
+          "completed",
+          "stale",
+          "invalid_report",
+          "spawn_failed",
+          "timed_out",
+          "output_limit",
+          "cancelled",
+        ]),
+        directory: nonEmpty,
+        receiptPath: nonEmpty,
+        exitCode: integer.nullable(),
+        issue: text.optional(),
+      })
+      .strict()
+      .optional(),
+    features: z.array(productFeatureAlignmentSchema),
+    coverage: z
+      .object({
+        measuredCodeFiles: nonNegativeInt,
+        mappedCodeFiles: nonNegativeInt,
+        unmappedCodeFiles: stringArray,
+        unmappedCodeFileCount: nonNegativeInt,
+        sharedFiles: z.array(z.object({ path: nonEmpty, featureIds: stringArray }).strict()),
+        mappedCodeUnion: productCodeMetricsSchema.nullable(),
+      })
+      .strict(),
+    dependencyCycles: z.array(stringArray),
+    issues: stringArray,
+    limitations: stringArray,
+    draft: productManifestSchema.nullable(),
+  })
+  .strict();
+
+export const UNTANGLE_MCP_SUCCESS_DATA_SCHEMAS = {
+  untangle_index: indexReportSchema,
+  untangle_update: indexReportSchema,
+  untangle_stop: z.object({ job: jobStatusSchema, cancellationRequested: z.boolean() }).strict(),
+  untangle_watch: z.object({ job: jobStatusSchema, watching: z.boolean() }).strict(),
+  untangle_status: z.object({ jobs: z.array(jobStatusSchema) }).strict(),
+  untangle_health: z
+    .object({ schemaVersion: z.literal(1), ok: z.boolean(), checks: z.array(checkResultSchema) })
+    .strict(),
+  untangle_projects: z
+    .object({
+      root: nonEmpty,
+      repositories: z.array(repositoryConfigSchema),
+      projectId: text.optional(),
+    })
+    .strict(),
+  untangle_search: searchResultSetSchema,
+  untangle_search_session: searchSessionResultSchema,
+  untangle_context_list: z
+    .object({ artifacts: z.array(contextArtifactSchema), configured: nonNegativeInt })
+    .strict(),
+  untangle_context_index: z
+    .object({
+      generationId: nonEmpty,
+      artifacts: z.array(nonEmpty),
+      indexedDocuments: nonNegativeInt,
+    })
+    .strict(),
+  untangle_context_search: z
+    .object({
+      query: nonEmpty,
+      results: z.array(
+        z
+          .object({
+            artifactName: nonEmpty,
+            chunkId: nonEmpty,
+            path: text,
+            kind: nonEmpty,
+            title: text.optional(),
+            score: finite,
+            content: text.optional(),
+          })
+          .strict(),
+      ),
+      total: nonNegativeInt,
+    })
+    .strict(),
+  untangle_context_remove: z
+    .object({ target: nonEmpty, removed: z.boolean(), removedDocumentCount: nonNegativeInt })
+    .strict(),
+  untangle_graph_build: z
+    .object({
+      generationId: nonEmpty,
+      workspaceId: nonEmpty,
+      fileGraph: z.object({ nodeCount: nonNegativeInt, edgeCount: nonNegativeInt }).strict(),
+      symbolGraph: z.object({ nodeCount: nonNegativeInt, edgeCount: nonNegativeInt }).strict(),
+      skipped: z.array(skipLedgerEntrySchema),
+    })
+    .strict(),
+  untangle_graph_status: graphStatusSchema,
+  untangle_graph_query: boundedGraphFileViewSchema,
+  untangle_graph_stats: graphStatsSchema,
+  untangle_graph_cycles: graphCyclesSchema,
+  untangle_graph_visualize: graphVisualizationSchema,
+  untangle_graph_remove: z
+    .object({ target: nonEmpty, generationId: nonEmpty, removed: z.boolean() })
+    .strict(),
+  untangle_symbols: symbolListSchema,
+  untangle_symbol: symbolDetailSchema,
+  untangle_flow: flowSchema,
+  untangle_impact: impactSchema,
+  untangle_cross_repo_impact: z
+    .object({
+      generationId: nonEmpty,
+      root: symbolNodeSchema,
+      impact: impactResultSchema,
+      repoIds: stringArray,
+    })
+    .strict(),
+  untangle_complexity: complexityReportSchema,
+  untangle_complexity_explain: z
+    .object({ symbol: symbolNodeSchema, snapshot: complexitySnapshotSchema })
+    .strict(),
+  untangle_hotspots: complexityReportSchema,
+  untangle_complexity_diff: z
+    .object({
+      base: nonEmpty,
+      head: nonEmpty,
+      metricsVersion: nonEmpty,
+      entries: z.array(metricDeltaSchema),
+      warnings: stringArray,
+    })
+    .strict(),
+  untangle_changes: z
+    .object({
+      base: nonEmpty,
+      head: nonEmpty,
+      changes: z.array(changeEventSchema),
+      total: nonNegativeInt,
+    })
+    .strict(),
+  untangle_change_search: z
+    .object({ query: nonEmpty, changes: z.array(changeEventSchema), total: nonNegativeInt })
+    .strict(),
+  untangle_quality_gate: qualityGateSchema,
+  untangle_about: aboutSchema,
+  untangle_portfolio_scan: portfolioScanResultSchema,
+  untangle_stack_matrix: stackMatrixResultSchema,
+  untangle_who_uses: whoUsesResultSchema,
+  untangle_conventions: conventionsResultSchema,
+  untangle_archetypes: archetypesResultSchema,
+  untangle_tech_radar: techRadarResultSchema,
+  untangle_blueprint: blueprintResultSchema,
+  untangle_product: productAlignmentReportSchema,
+  untangle_boundaries: frontendBoundaryReportSchema,
+} as const satisfies Record<UntangleMcpToolName, z.ZodType>;
+
+export type UntangleMcpSuccessDataByOperation = {
+  [Name in UntangleMcpToolName]: z.output<(typeof UNTANGLE_MCP_SUCCESS_DATA_SCHEMAS)[Name]>;
+};