@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/contracts/lib/schema.js

@@ -3,12 +3,12 @@ import { z } from "zod";
 // Identity primitives
 // ───────────────────────────────────────────────────────────────────────────
 export const InterfIdPattern = /^[a-z0-9][a-z0-9-]{0,79}$/;
-export const PreparationNamePattern = /^[a-z0-9][a-z0-9-]*$/;
-const RESERVED_PREPARATION_NAMES = new Set(["tests", "build-plans"]);
-export const PreparationNameSchema = z
+export const ProjectIdPattern = /^[a-z0-9][a-z0-9-]*$/;
+const RESERVED_PROJECT_IDS = new Set(["tests", "build-plans"]);
+export const ProjectIdSchema = z
     .string()
-    .regex(PreparationNamePattern, "Preparation names must use lowercase letters, numbers, and dashes only.")
-    .refine((value) => !RESERVED_PREPARATION_NAMES.has(value), "Preparation name is reserved.");
+    .regex(ProjectIdPattern, "Project names must use lowercase letters, numbers, and dashes only.")
+    .refine((value) => !RESERVED_PROJECT_IDS.has(value), "Project name is reserved.");
 export const BuildPlanIdSchema = z.string().regex(InterfIdPattern);
 /**
  * Build Plan-declared artifact identifier. Same shape as `BuildPlanIdSchema`
@@ -18,8 +18,8 @@ export const BuildPlanIdSchema = z.string().regex(InterfIdPattern);
 export const ArtifactIdSchema = z.string().regex(InterfIdPattern);
 export const RuntimeStageSchema = z.string().regex(InterfIdPattern);
 export const RuntimeContractTypeSchema = z.string().regex(InterfIdPattern);
-export const RuntimeTargetTypeSchema = z.enum(["verifiable-context"]);
-export const TestTargetTypeSchema = z.enum(["verifiable-context", "source-files"]);
+export const RuntimeTargetTypeSchema = z.enum(["context-graph"]);
+export const TestTargetTypeSchema = z.enum(["context-graph", "source-files"]);
 // ───────────────────────────────────────────────────────────────────────────
 // Path validation
 //
@@ -57,13 +57,13 @@ export const LocatorSchema = z.object({
     value: z.string().min(1),
 }).strict();
 // ───────────────────────────────────────────────────────────────────────────
-// Source primitives — what the user puts in
+// Source primitives — what the user puts in.
 //
-// `local-folder` is the only kind the local binary accepts in 0.17;
-// `remote-folder` is type plumbing for the future cloud variant
-// (rejected at the validator branch in server.ts).
+// `local-folder` is the only Source kind Interf accepts. Cloud / remote
+// storage kinds will be re-introduced when a real variant ships; see
+// `internal/iterations/0.23-service-variant-parking-lot.md`.
 // ───────────────────────────────────────────────────────────────────────────
-export const SourceKindSchema = z.enum(["local-folder", "remote-folder"]);
+export const SourceKindSchema = z.enum(["local-folder"]);
 export const SourceSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     kind: SourceKindSchema,
@@ -73,6 +73,7 @@ export const SourceFileSchema = z.object({
     id: z.string().min(1),
     path: z.string().min(1),
     locator: z.string().min(1),
+    size_bytes: z.number().int().nonnegative().optional(),
 }).strict();
 export const SourceFilesSchema = z.object({
     kind: z.literal("interf-source-files"),
@@ -82,46 +83,146 @@ export const SourceFilesSchema = z.object({
     source_total: z.number().int().min(0),
     files: z.array(SourceFileSchema),
 }).strict();
-export const SourceSnapshotSchema = z.object({
-    kind: z.literal("interf-source-snapshot"),
+export const SourceStateSchema = z.object({
+    kind: z.literal("interf-source-state"),
     version: z.literal(1),
-    snapshot_id: z.string().min(1),
+    graph_id: z.string().min(1),
     generated_at: z.string().min(1),
     run_id: z.string().min(1).nullable(),
     source: SourceSchema,
     source_total: z.number().int().min(0),
     files: z.array(SourceFileSchema),
 }).strict();
+export const SourceInspectableUnitSchema = z.object({
+    kind: z.enum(["page", "slide", "sheet", "table", "image", "section"]),
+    index: z.number().int().min(1).optional(),
+    label: z.string().min(1).optional(),
+}).strict();
+export const SourceManifestEvidenceSchema = z.object({
+    kind: z.enum(["agent-observation", "connector-metadata", "user-provided"]),
+    summary: z.string().min(1),
+}).strict();
+export const SourceManifestFileKindSchema = z.enum([
+    "pdf",
+    "document",
+    "spreadsheet",
+    "presentation",
+    "image",
+    "text",
+    "other",
+]);
+export const SourceManifestFileSchema = SourceFileSchema.extend({
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Source manifest paths must be relative and cannot contain path traversal.",
+    }),
+    kind: SourceManifestFileKindSchema.default("other"),
+    size_bytes: z.number().int().nonnegative().optional(),
+    content_hash: z.string().min(1).optional(),
+    page_count: z.number().int().min(1).optional(),
+    inspectable_units: z.array(SourceInspectableUnitSchema).default([]),
+    confidence: z.enum(["high", "medium", "low"]).default("medium"),
+    evidence: z.array(SourceManifestEvidenceSchema).min(1),
+}).strict();
+export const SourceManifestScannerSchema = z.object({
+    executor: z.string().min(1),
+    agent_label: z.string().min(1),
+    attempt: z.number().int().min(1),
+}).strict();
+export const SourceManifestSchema = z.object({
+    kind: z.literal("interf-source-manifest"),
+    version: z.literal(1),
+    manifest_id: z.string().min(1),
+    generated_at: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    project: ProjectIdSchema,
+    source: SourceSchema,
+    scanner: SourceManifestScannerSchema,
+    source_total: z.number().int().min(1),
+    files: z.array(SourceManifestFileSchema).min(1),
+    warnings: z.array(z.string().min(1)).default([]),
+}).strict().superRefine((value, ctx) => {
+    if (value.files.length !== value.source_total) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["source_total"],
+            message: "source_total must equal files.length.",
+        });
+    }
+    const ids = new Set();
+    const paths = new Set();
+    for (const [index, file] of value.files.entries()) {
+        if (ids.has(file.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["files", index, "id"],
+                message: `Duplicate source file id: ${file.id}.`,
+            });
+        }
+        ids.add(file.id);
+        if (paths.has(file.path)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["files", index, "path"],
+                message: `Duplicate source file path: ${file.path}.`,
+            });
+        }
+        paths.add(file.path);
+    }
+});
+export const SourceManifestAuditSchema = z.object({
+    kind: z.literal("interf-source-manifest-audit"),
+    version: z.literal(1),
+    run_id: z.string().min(1).nullable(),
+    manifest_id: z.string().min(1),
+    generated_at: z.string().min(1),
+    auditor: SourceManifestScannerSchema,
+    verdict: z.enum(["pass", "fail", "needs-review"]),
+    findings: z.array(z.string().min(1)).default([]),
+}).strict();
 export const StageInputSchema = z.object({
     source_file_id: z.string().min(1),
     path: z.string().min(1),
     locator: z.string().min(1),
+    kind: SourceManifestFileKindSchema.default("other").optional(),
+    size_bytes: z.number().int().nonnegative().optional(),
+    page_count: z.number().int().min(1).optional(),
+    inspectable_units: z.array(SourceInspectableUnitSchema).default([]).optional(),
+    content_hash: z.string().min(1).optional(),
 }).strict();
 export const StageInputsSchema = z.object({
     kind: z.literal("interf-stage-inputs"),
-    version: z.literal(1),
+    version: z.literal(3),
     generated_at: z.string().min(1),
     run_id: z.string().min(1).nullable(),
     build_plan: BuildPlanIdSchema,
     stage: RuntimeStageSchema,
-    source_snapshot_id: z.string().min(1),
+    source_state_id: z.string().min(1),
+    source_manifest_id: z.string().min(1),
     input_total: z.number().int().min(0),
     inputs: z.array(StageInputSchema),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    if (value.input_total !== value.inputs.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["input_total"],
+            message: "input_total must equal inputs.length.",
+        });
+    }
+});
 export const SourceBuildMaxAttemptsSchema = z.number().int().min(1).max(5);
 export const SourceBuildMaxLoopsSchema = z.number().int().min(1).max(3);
 // ───────────────────────────────────────────────────────────────────────────
-// Check / Proof / Ready — the locked verification vocabulary
+// Check / Evidence / Ready — the locked verification vocabulary
 //
 // Three words doing three precise jobs:
 //   - Check: the rule that must pass (with a `kind` and optional params)
-//   - Proof: evidence a check ran (pass/fail + summary + details)
+//   - Evidence: records that a check ran (pass/fail + summary + details)
 //   - Ready: aggregate verdict (`ready` or `not_ready`)
 //
 // A check has a SCOPE (where it's declared), not a different name:
 //   - stage check    — Build Plan-declared per stage; runs end-of-stage
-//   - artifact check — Build Plan-declared per artifact; runs end-of-build
-//   - user check     — Preparation-declared; runs on `interf test`
+//   - Artifact diagnostic — Build Plan-declared per artifact; runs end-of-build
+//   - benchmark check — Project-declared Q&A / fact check; runs on `interf benchmark`
 //
 // Same `Check` primitive across all three scopes. Same `CheckKind`
 // canonical list - Build Plans, users, and engine code pick from it.
@@ -130,31 +231,127 @@ export const SourceBuildMaxLoopsSchema = z.number().int().min(1).max(3);
  * Canonical check kinds the engine knows how to evaluate.
  *
  * Adding a new kind requires an engine release (the evaluator must
- * implement it). Build Plans and user checks pick from this list; they
+ * implement it). Plans and user checks pick from this list; they
  * cannot invent custom kinds.
  *
  *   file_exists                    — file is present and non-empty
+ *   source_manifest_valid          — source-manifest.json exists, parses, and has at least one file
  *   min_file_count                 — directory has ≥ N files (params: { min: number })
  *   min_file_count_matches_source  — directory has ≥ source_total files (the "all files analyzed" check)
+ *   source_summary_folders         — summaries directory has ≥ source_total source folders, each with summary.md or manifest.md
+ *   source_page_coverage           — page summary outputs exist for every manifest page unit
  *   frontmatter_valid              — every markdown file has parseable YAML frontmatter
  *   frontmatter_required_keys      — every markdown file has these frontmatter keys (params: { keys: string[] })
+ *   frontmatter_nonempty_keys      — every markdown file has non-empty values for these frontmatter keys
+ *   source_refs_required           — every markdown file has non-empty source_refs/source_ref/source_path frontmatter
  *   wikilinks_valid                — every wikilink resolves
- *   must_not_contain               — file/directory does not contain forbidden phrases (params: { phrases: string[] })
- *   must_contain                   — file/directory contains required phrases (params: { phrases: string[] })
- *   qa_match                       — user-defined Q/A: agent answer matches expected (params: { question, expected, strictness })
+ *   must_not_contain               — file/directory does not contain forbidden phrases (params: { phrases: string[] } or { text: string })
+ *   must_contain                   — file/directory contains required phrases (params: { phrases: string[] } or { text: string })
+ *   qa_match                       — user-defined Q/A: agent answer matches expected (params: { expected: string, strictness?: "loose" | "strict" })
  */
 export const CHECK_KINDS = [
     "file_exists",
+    "source_manifest_valid",
     "min_file_count",
     "min_file_count_matches_source",
+    "source_summary_folders",
+    "source_page_coverage",
     "frontmatter_valid",
     "frontmatter_required_keys",
+    "frontmatter_nonempty_keys",
+    "source_refs_required",
     "wikilinks_valid",
     "must_not_contain",
     "must_contain",
     "qa_match",
 ];
 export const CheckKindSchema = z.enum(CHECK_KINDS);
+export const CHECK_PARAM_CONTRACTS = {
+    file_exists: {
+        params: {},
+        examples: [{}],
+    },
+    source_manifest_valid: {
+        params: {
+            path: "optional manifest path; defaults to .interf/runtime/source-manifest.json",
+        },
+        examples: [{}],
+    },
+    min_file_count: {
+        params: {
+            min: "optional number; defaults to 1",
+        },
+        examples: [{ min: 26 }],
+    },
+    min_file_count_matches_source: {
+        params: {
+            match: "optional count key string; defaults to source_total",
+        },
+        examples: [{ match: "source_total" }],
+    },
+    source_summary_folders: {
+        params: {
+            match: "optional count key string; defaults to source_total",
+            summary_file: "optional filename string; defaults to summary.md",
+            manifest_file: "optional filename string; defaults to manifest.md",
+        },
+        examples: [{ match: "source_total" }],
+    },
+    source_page_coverage: {
+        params: {
+            pages_dir: "optional directory name inside each source summary folder; defaults to pages",
+            summary_file: "optional filename string; defaults to summary.md",
+        },
+        examples: [{ pages_dir: "pages" }],
+    },
+    frontmatter_valid: {
+        params: {},
+        examples: [{}],
+    },
+    frontmatter_required_keys: {
+        params: {
+            keys: "required string[]",
+        },
+        examples: [{ keys: ["page", "title", "summary"] }],
+    },
+    frontmatter_nonempty_keys: {
+        params: {
+            keys: "required string[]",
+        },
+        examples: [{ keys: ["source_refs", "verification_state"] }],
+    },
+    source_refs_required: {
+        params: {
+            keys: "optional string[]; defaults to source_refs, source_ref, source_path",
+        },
+        examples: [{ keys: ["source_refs"] }],
+    },
+    wikilinks_valid: {
+        params: {},
+        examples: [{}],
+    },
+    must_not_contain: {
+        params: {
+            phrases: "preferred string[] of forbidden phrases",
+            text: "optional string shorthand for one forbidden phrase",
+        },
+        examples: [{ phrases: ["TODO", "Not yet built."] }, { text: "TODO" }],
+    },
+    must_contain: {
+        params: {
+            phrases: "preferred string[] of required phrases",
+            text: "optional string shorthand for one required phrase",
+        },
+        examples: [{ phrases: ["Bristol", "Central London"] }, { text: "Bristol" }],
+    },
+    qa_match: {
+        params: {
+            expected: "required expected answer string",
+            strictness: "optional string; loose or strict; defaults to loose",
+        },
+        examples: [{ expected: "Acme Corp", strictness: "loose" }],
+    },
+};
 /**
  * One check declaration. Reusable across stage/artifact/user scopes.
  *
@@ -164,7 +361,7 @@ export const CheckKindSchema = z.enum(CHECK_KINDS);
  * rule-specific config (typed at the engine evaluator).
  *
  * `required: true` (default) → a failed check fails the parent
- * (stage/artifact/preparation). `required: false` → soft check, fails
+ * (stage/artifact/Project). `required: false` → soft check, fails
  * warn but don't block the `ready` verdict.
  */
 export const CheckSchema = z.object({
@@ -179,7 +376,7 @@ export const CheckSchema = z.object({
  * short one-line label for the UI; `details` carries rule-specific
  * structured data (e.g., file count, missing keys, broken link list).
  */
-export const ProofSchema = z.object({
+export const CheckResultSchema = z.object({
     check_id: z.string().regex(InterfIdPattern),
     kind: CheckKindSchema,
     passed: z.boolean(),
@@ -188,9 +385,36 @@ export const ProofSchema = z.object({
     details: z.record(z.string(), z.unknown()).optional(),
     evaluated_at: z.string().min(1),
 }).strict();
+export const ContextCheckStatusSchema = z.enum([
+    "pending",
+    "running",
+    "passed",
+    "failed",
+    "skipped",
+]);
+/**
+ * User-facing Build Plan check: the plain-English assertion the user
+ * reviews as a Context Check. Requested Artifacts back these checks.
+ * Deterministic Artifact diagnostics remain nested under Artifacts
+ * and use `CheckSchema`.
+ */
+export const ContextCheckDeclarationSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    backed_by_artifact_ids: z.array(ArtifactIdSchema).default([]),
+    required: z.boolean().default(true),
+    evidence_expectation: z.string().min(1).optional(),
+}).strict();
+export const ContextCheckProjectionSchema = ContextCheckDeclarationSchema.extend({
+    status: ContextCheckStatusSchema.optional(),
+    evidence: z.string().min(1).optional(),
+    issue: z.string().min(1).optional(),
+}).strict();
+export const ContextCheckSchema = ContextCheckProjectionSchema;
 /**
  * Per-thing readiness verdict. Used for an artifact, a stage, or a
- * preparation. Aggregate verdict over its required checks.
+ * Project. Aggregate verdict over its required checks.
  */
 export const ReadyVerdictSchema = z.enum(["ready", "not_ready", "failed", "skipped"]);
 /**
@@ -201,6 +425,9 @@ export const ReadyVerdictSchema = z.enum(["ready", "not_ready", "failed", "skipp
  */
 export const STANDARD_EVIDENCE_FRONTMATTER_KEYS = [
     "source",
+    "source_file_id",
+    "source_path",
+    "source_locator",
     "source_kind",
     "evidence_tier",
     "truth_mode",
@@ -210,33 +437,31 @@ export const STANDARD_EVIDENCE_FRONTMATTER_KEYS = [
 // Artifact — a produced thing the user can see and verify
 //
 // Every output of a Build Plan is an Artifact. No internal/working/output
-// distinction — if it's named, it's an Artifact. The engine reserves
+// distinction — if it's named, it's an Artifact. The runtime reserves
 // `.interf/runtime/` as its own namespace by convention; those paths
 // are not artifacts.
 // ───────────────────────────────────────────────────────────────────────────
 /**
- * Where an Artifact materializes. Discriminated union so future kinds
- * (literal value, remote handle, confirmation-only) slot in without a
- * schema break. `path` is always relative to the verifiable-context root,
- * and `artifact_kind` tells consumers whether the target materializes
- * as a file or directory.
+ * Where an Artifact materializes. `path` is always relative to the
+ * Context Graph root, and `artifact_kind` tells consumers whether the
+ * target materializes as a file or directory. The `kind: "path"`
+ * discriminator is retained on the wire so a future shape variant can be
+ * added as a discriminated union without renaming existing data.
  */
 export const ArtifactPathShapeSchema = z.object({
     kind: z.literal("path"),
     path: z.string().min(1).refine(isInterfRelativePath, {
-        message: "Artifact paths must stay inside the verifiable-context root (no `..`, no absolute paths).",
+        message: "Artifact paths must stay inside the Context Graph root (no `..`, no absolute paths).",
     }),
     artifact_kind: z.enum(["file", "directory"]),
 }).strict();
-export const ArtifactShapeSchema = z.discriminatedUnion("kind", [
-    ArtifactPathShapeSchema,
-]);
+export const ArtifactShapeSchema = ArtifactPathShapeSchema;
 /**
  * Build Plan-declared Artifact — a produced thing.
  *
  * `checks[]` is the locked vocabulary: an array of `Check` (with
  * `kind` from `CHECK_KINDS`). The runtime evaluates them via the
- * shared check evaluator and produces `Proof[]` on each Build run.
+ * shared check evaluator and produces `CheckResult[]` on each Build.
  */
 export const ArtifactSchema = z.object({
     id: ArtifactIdSchema,
@@ -246,8 +471,8 @@ export const ArtifactSchema = z.object({
     built_by_stages: z.array(z.string().regex(InterfIdPattern)).default([]),
 }).strict();
 /**
- * Per-Artifact runtime status. Lives on Build run resources and on
- * preparation resources. `proofs[]` carries the structured evidence
+ * Per-Artifact runtime status. Lives on Build resources and on
+ * Project resources. `check_results[]` carries the structured evidence
  * emitted by the shared check evaluator.
  */
 export const ArtifactStatusValueSchema = ReadyVerdictSchema;
@@ -255,14 +480,121 @@ export const ArtifactStatusSchema = z.object({
     artifact_id: ArtifactIdSchema,
     status: ReadyVerdictSchema,
     built_by_stages: z.array(z.string().regex(InterfIdPattern)).default([]),
-    proofs: z.array(ProofSchema).default([]),
+    check_results: z.array(CheckResultSchema).default([]),
+    summary: z.string().min(1).optional(),
+}).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// Build evidence — user-visible readiness rows
+//
+// Check rows are the app-facing review primitive for a Build. They
+// deliberately keep the surface small:
+//   assertion label + metric + evidence link/ref + optional issue state
+//
+// Denominators are engine-owned (Source inventory or declared Build Plan
+// expectations). Observed values come from Build runs: stage records,
+// accepted Outputs, validators, and traces. Benchmarks remain separate.
+// ───────────────────────────────────────────────────────────────────────────
+export const BuildEvidenceIssueStateSchema = z.enum([
+    "pass",
+    "missing",
+    "review",
+    "fail",
+]);
+export const BuildEvidenceMetricSchema = z.object({
+    observed: z.number().int().min(0),
+    total: z.number().int().min(0).optional(),
+    unit: z.string().min(1).optional(),
+}).strict();
+export const BuildEvidenceRefSchema = z.object({
+    kind: z.enum([
+        "source-inventory",
+        "stage-record",
+        "output",
+        "validator",
+        "trace",
+        "stage-evidence",
+    ]),
+    label: z.string().min(1),
+    ref: z.string().min(1).optional(),
+    path: z.string().min(1).optional(),
+    run_id: z.string().min(1).optional(),
+    stage_id: z.string().regex(InterfIdPattern).optional(),
+    artifact_id: ArtifactIdSchema.optional(),
+}).strict();
+export const BuildCheckRowSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    assertion: z.string().min(1),
+    metric: BuildEvidenceMetricSchema,
+    evidence: BuildEvidenceRefSchema,
+    issue_state: BuildEvidenceIssueStateSchema.optional(),
+    issue: z.string().min(1).optional(),
+}).strict();
+export const BuildEvidenceResourceSchema = z.object({
+    kind: z.literal("interf-build-evidence"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    project_id: z.string().min(1),
+    build_run_id: z.string().min(1).nullable(),
+    ready: z.boolean(),
+    summary: z.string().min(1),
+    rows: z.array(BuildCheckRowSchema).default([]),
+}).strict();
+export const EvidenceCountKeySchema = z.string().regex(/^[a-z][a-z0-9_.:-]*$/);
+export const StageEvidenceSourceRefSchema = z.object({
+    path: z.string().min(1),
+    source_file_id: z.string().min(1).optional(),
+    locator: z.string().min(1).optional(),
+}).strict();
+export const StageEvidenceOutputRefSchema = z.object({
+    artifact_id: ArtifactIdSchema,
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Output refs must stay inside the Context Graph root.",
+    }),
+}).strict();
+export const StageEvidenceCountSchema = z.object({
+    key: EvidenceCountKeySchema,
+    label: z.string().min(1),
+    value: z.number().int().min(0),
+    total: z.number().int().min(0).optional(),
+    unit: z.string().min(1).optional(),
+    source: z.enum(["engine", "stage"]),
+    stage_id: z.string().regex(InterfIdPattern).optional(),
+    artifact_id: ArtifactIdSchema.optional(),
+    primary: z.boolean().optional(),
+    expected: z.boolean().optional(),
+}).strict();
+export const StageEvidenceItemSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    kind: EvidenceCountKeySchema,
+    label: z.string().min(1),
     summary: z.string().min(1).optional(),
+    source_refs: z.array(StageEvidenceSourceRefSchema).default([]),
+    output_refs: z.array(StageEvidenceOutputRefSchema).default([]),
+    stage_id: z.string().regex(InterfIdPattern),
+    artifact_id: ArtifactIdSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const StageEvidenceEdgeSchema = z.object({
+    from: z.string().regex(InterfIdPattern),
+    to: z.string().regex(InterfIdPattern),
+    relation: EvidenceCountKeySchema,
+    stage_id: z.string().regex(InterfIdPattern),
+}).strict();
+export const StageEvidenceSchema = z.object({
+    kind: z.literal("interf-stage-evidence"),
+    version: z.literal(1),
+    run_id: z.string().min(1),
+    stage: z.string().regex(InterfIdPattern),
+    counts: z.array(StageEvidenceCountSchema).default([]),
+    items: z.array(StageEvidenceItemSchema).default([]),
+    edges: z.array(StageEvidenceEdgeSchema).default([]),
+    warnings: z.array(z.string().min(1)).optional(),
 }).strict();
 // ───────────────────────────────────────────────────────────────────────────
-// Readiness — preparation-level aggregate verdict
+// Readiness — project-level aggregate verdict
 //
-// Rolls up artifact statuses + user-check results + engine-level gates
-// (is the prep configured, has a Build run, etc.) into a single
+// Rolls up Artifact diagnostics, benchmark results, and engine-level gates
+// (is the project configured, has a Build, etc.) into a single
 // `ready` / `not_ready` answer for the ICP.
 // ───────────────────────────────────────────────────────────────────────────
 export const ReadinessStatusSchema = z.enum([
@@ -277,18 +609,19 @@ export const ReadinessStatusSchema = z.enum([
     "failed",
 ]);
 export const ReadinessGateSchema = z.enum([
-    "preparation-config",
-    "verifiable-context",
+    "project-config",
+    "context-graph",
     "build-run",
-    "artifact-checks",
-    "readiness-checks",
-    "checks-current",
+    "artifact-diagnostics",
+    "context-checks",
+    "benchmarks",
+    "benchmarks-current",
 ]);
 /**
  * Per-gate status — one row in the readiness summary. A gate is a
- * high-level layer (is config valid? is verifiable context built? did
- * latest Build run succeed?). Gate failures are aggregated alongside
- * artifact-check failures into the overall `Readiness` verdict.
+ * high-level layer (is config valid? is the Context Graph built? did
+ * the latest Build succeed?). Gate failures are aggregated alongside
+ * Artifact diagnostic failures into the overall `Readiness` verdict.
  */
 export const GateStatusSchema = z.object({
     gate: ReadinessGateSchema,
@@ -309,40 +642,28 @@ export const VerifyTargetResultSchema = z.object({
     run_path: z.string().min(1).nullable().optional(),
 }).strict();
 /**
- * Preparation-level readiness verdict.
- *
- * Field names retain the preparation-readiness wire shape
- * (`latest_test_run_id`, `check_results`, `checks`). The exported type
- * name is `Readiness`.
+ * Project-level readiness verdict.
  */
-function mapReadinessRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return value;
-    const record = value;
-    return {
-        ...record,
-    };
-}
-export const ReadinessSchema = z.preprocess(mapReadinessRecord, z.object({
+export const ReadinessSchema = z.object({
     kind: z.literal("interf-readiness-state"),
     version: z.literal(1),
     generated_at: z.string().min(1),
-    preparation: z.string().min(1),
+    project: z.string().min(1),
     status: ReadinessStatusSchema,
     ready: z.boolean(),
     summary: z.string().min(1),
-    verifiable_context_path: z.string().min(1).nullable(),
+    context_graph_path: z.string().min(1).nullable(),
     latest_build_run_id: z.string().min(1).nullable().optional(),
-    latest_test_run_id: z.string().min(1).nullable().optional(),
+    latest_benchmark_run_id: z.string().min(1).nullable().optional(),
     build: GateStatusSchema.nullable(),
     check_results: z.object({
         configured: z.number().int().min(0),
         fingerprint: z.string().min(1).nullable(),
         source_files: VerifyTargetResultSchema.nullable(),
-        verifiable_context: VerifyTargetResultSchema.nullable(),
+        context_graph: VerifyTargetResultSchema.nullable(),
     }).strict(),
     checks: z.array(GateStatusSchema).default([]),
-}).strict());
+}).strict();
 // ───────────────────────────────────────────────────────────────────────────
 // User-defined verification (Q/A pairs) — the "user check" scope
 // ───────────────────────────────────────────────────────────────────────────
@@ -377,7 +698,7 @@ export const RuntimeExecutorInfoSchema = z.object({
     timeout_ms: z.number().nullable().optional(),
 });
 // ───────────────────────────────────────────────────────────────────────────
-// Connected agents + roles (0.15)
+// Execution agents + roles
 // ───────────────────────────────────────────────────────────────────────────
 /**
  * The 5 canonical roles a Build Plan stage can declare. Build Plans MAY declare
@@ -391,7 +712,7 @@ export const CANONICAL_ROLES = [
     "general",
 ];
 /**
- * Open-ended role identifier. Build Plans invent role names freely; the
+ * Open-ended role identifier. Plans invent role names freely; the
  * role-router maps unknown names to `general` at run time.
  */
 export const RoleSchema = z.string().min(1);
@@ -399,16 +720,30 @@ export const RoleSchema = z.string().min(1);
  * One agent in the registry. `available` is a runtime-only flag — true
  * if the command's first token resolves on PATH. Stripped before
  * persistence.
+ *
+ * `prefs` carries the merged-at-runtime per-agent preferences (env vars,
+ * model, effort). It is filled in at load time by looking up the
+ * registry's `agent_prefs` map by name. The persisted shape never carries
+ * `prefs` — it lives in `agent_prefs` on disk so built-in agents (which
+ * are detected, not persisted) can also receive preferences.
  */
+export const AgentPrefsSchema = z.object({
+    env_vars: z.record(z.string().min(1), z.string()).optional(),
+    model: z.string().min(1).nullable().optional(),
+    effort: z.string().min(1).nullable().optional(),
+}).strict();
 export const AgentRecordSchema = z.object({
     name: z.string().min(1),
     display_name: z.string().min(1),
     command: z.string().min(1),
     source: z.enum(["builtin", "user"]),
     available: z.boolean().optional(),
+    prefs: AgentPrefsSchema.optional(),
 }).strict();
 export const RoleMapSchema = z.record(RoleSchema, z.string().min(1));
+export const AgentPrefsMapSchema = z.record(z.string().min(1), AgentPrefsSchema);
 export const AgentsRegistrySchema = z.object({
     agents: z.array(AgentRecordSchema).default([]),
     role_map: RoleMapSchema.default({}),
+    agent_prefs: AgentPrefsMapSchema.default({}),
 }).strict();