@interf/compiler 0.22.2 → 0.50.0

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

@@ -3,23 +3,33 @@ 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`
- * but conceptually distinct — it identifies a produced thing inside
- * one Build Plan, while `BuildPlanIdSchema` identifies the Build Plan itself.
+ * The user's agent task for a Project.
+ *
+ * Project intent is the compact, durable instruction that explains what
+ * the Context Graph must prepare the Source for. Build Plans operationalize
+ * this field, but Project owns it.
+ */
+export const ProjectIntentSchema = z.string().trim().min(1);
+/**
+ * Legacy internal output identifier. Same shape as `BuildPlanIdSchema` but
+ * conceptually distinct: it identifies a requested output inside one Build
+ * Plan, while `BuildPlanIdSchema` identifies the Build Plan itself.
+ *
+ * The exported name remains `ArtifactIdSchema` until the ABI rename lands.
  */
 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 +67,17 @@ 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 SourceBindingSchema = z.object({
+    kind: SourceKindSchema,
+    locator: z.string().min(1),
+}).strict();
 export const SourceSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     kind: SourceKindSchema,
@@ -73,6 +87,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 +97,367 @@ 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(["file", "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
+// Context Graph manifests — canonical coverage/runtime proof
+// ───────────────────────────────────────────────────────────────────────────
+export const ResourceRoleSchema = z.enum([
+    "source",
+    "summary",
+    "knowledge",
+    "entrypoint",
+    "diagnostic",
+    "other",
+]);
+export const MetricKeySchema = z.string().regex(/^[a-z][a-z0-9_.:-]*$/);
+export const ResourceRefSchema = z.object({
+    id: z.string().min(1),
+    role: ResourceRoleSchema,
+    kind: z.string().min(1),
+    label: z.string().min(1),
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Resource paths must stay inside their root (no `..`, no absolute paths).",
+    }).optional(),
+    locator: z.string().min(1).optional(),
+    stage_id: RuntimeStageSchema.optional(),
+    source_refs: z.array(z.string().min(1)).default([]),
+    links: z.array(z.string().min(1)).default([]),
+    required: z.boolean().default(false),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+// metadata.guarantee groups a metric under one honest guarantee: "coverage" (every Source file read), "traceability" (every claim/summary/knowledge node linked). Verification (qa_match) is a separate fallible Check scope, never a coverage/traceability metric and never gates readiness.
+export const MetricCountSchema = z.object({
+    key: MetricKeySchema,
+    label: z.string().min(1),
+    value: z.number().int().min(0),
+    total: z.number().int().min(0).optional(),
+    unit: z.string().min(1).optional(),
+    primary: z.boolean().default(false),
+    issue_state: z.enum(["pass", "missing", "review", "fail"]).optional(),
+    detail: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict().superRefine((value, ctx) => {
+    if (typeof value.total === "number" && value.value > value.total) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["value"],
+            message: "Metric value cannot exceed total.",
+        });
+    }
+});
+export const ReviewedInputDecisionSchema = z.enum([
+    "used",
+    "reviewed",
+    "missing",
+    "blocked",
+    "not-relevant",
+]);
+export const ReviewedInputSchema = z.object({
+    resource_id: z.string().min(1),
+    decision: ReviewedInputDecisionSchema,
+    reason: z.string().min(1).optional(),
+    output_resource_ids: z.array(z.string().min(1)).default([]),
+    source_refs: z.array(z.string().min(1)).default([]),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const MissingInputSchema = z.object({
+    resource_id: z.string().min(1),
+    status: z.enum(["missing", "blocked", "not-relevant"]),
+    reason: z.string().min(1),
+}).strict();
+/**
+ * Stage runtime-file contracts: the `expected-inputs.json` and
+ * `reviewed-inputs.json` files a stage shell reads and writes. Defined once
+ * here so the build engine (stage-manifest writer, native entrypoint reader)
+ * and any future client validate against one shape instead of a hand-rolled
+ * parallel `interface`.
+ */
+export const ExpectedInputsFileSchema = z.object({
+    kind: z.literal("interf-stage-expected-inputs"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    stage_id: z.string().min(1),
+    expected: z.array(ResourceRefSchema),
+}).strict();
+export const ReviewedInputsFileSchema = z.object({
+    kind: z.literal("interf-stage-reviewed-inputs"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    stage_id: z.string().min(1),
+    reviewed: z.array(ReviewedInputSchema),
+}).strict();
+export const StageManifestSchema = z.object({
+    kind: z.literal("interf-stage-manifest"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    project: ProjectIdSchema,
+    run_id: z.string().min(1).nullable(),
+    build_plan: BuildPlanIdSchema,
+    stage_id: RuntimeStageSchema,
+    stage_label: z.string().min(1),
+    role: ResourceRoleSchema,
+    summary: z.string().min(1),
+    input_manifests: z.array(ResourceRefSchema).default([]),
+    expected: z.array(ResourceRefSchema).default([]),
+    reviewed: z.array(ReviewedInputSchema).default([]),
+    referenced: z.array(ResourceRefSchema).default([]),
+    missing: z.array(MissingInputSchema).default([]),
+    produced: z.array(ResourceRefSchema).default([]),
+    metrics: z.array(MetricCountSchema).default([]),
+}).strict().superRefine((value, ctx) => {
+    for (const field of ["input_manifests", "expected", "referenced", "produced"]) {
+        const seen = new Set();
+        for (const [index, resource] of value[field].entries()) {
+            if (seen.has(resource.id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field, index, "id"],
+                    message: `Duplicate resource id: ${resource.id}.`,
+                });
+            }
+            seen.add(resource.id);
+        }
+    }
+    const expectedIds = new Set(value.expected.map((resource) => resource.id));
+    const producedIds = new Set(value.produced.map((resource) => resource.id));
+    const reviewedIds = new Set(value.reviewed.map((review) => review.resource_id));
+    const missingIds = new Set(value.missing.map((entry) => entry.resource_id));
+    for (const [index, review] of value.reviewed.entries()) {
+        if (!expectedIds.has(review.resource_id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["reviewed", index, "resource_id"],
+                message: `Reviewed input "${review.resource_id}" is not in expected inputs.`,
+            });
+        }
+        for (const [outputIndex, outputId] of review.output_resource_ids.entries()) {
+            if (!producedIds.has(outputId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["reviewed", index, "output_resource_ids", outputIndex],
+                    message: `Reviewed input references unknown produced output "${outputId}".`,
+                });
+            }
+        }
+    }
+    for (const [index, entry] of value.missing.entries()) {
+        if (!expectedIds.has(entry.resource_id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["missing", index, "resource_id"],
+                message: `Missing input "${entry.resource_id}" is not in expected inputs.`,
+            });
+        }
+    }
+    for (const [index, resource] of value.expected.entries()) {
+        if (resource.required !== true)
+            continue;
+        if (!reviewedIds.has(resource.id) && !missingIds.has(resource.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["expected", index, "id"],
+                message: `Required expected input "${resource.id}" must be reviewed or marked missing.`,
+            });
+        }
+    }
+});
+export const GraphManifestStageSummarySchema = z.object({
+    stage_id: RuntimeStageSchema,
+    stage_label: z.string().min(1),
+    role: ResourceRoleSchema,
+    manifest_path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Stage manifest paths must stay inside the Context Graph root.",
+    }),
+    summary: z.string().min(1),
+    produced_total: z.number().int().min(0),
+    missing_required_total: z.number().int().min(0),
+    metrics: z.array(MetricCountSchema).default([]),
+}).strict();
+export const GraphReadinessRollupSchema = z.object({
+    status: z.enum(["ready", "not-ready"]),
+    ready: z.boolean(),
+    summary: z.string().min(1),
+    context_graph_path: z.string().min(1).nullable().optional(),
+    missing_required_total: z.number().int().min(0),
+    missing: z.array(MissingInputSchema).default([]),
+}).strict();
+export const GraphOutputCountsSchema = z.object({
+    nodes: z.number().int().min(0),
+    edges: z.number().int().min(0),
+    notes: z.number().int().min(0),
+    links: z.number().int().min(0),
+    source_refs: z.number().int().min(0),
+    claims: z.number().int().min(0).optional(),
+    entities: z.number().int().min(0).optional(),
+}).strict();
+export const GraphManifestSchema = z.object({
+    kind: z.literal("interf-graph-manifest"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    project: ProjectIdSchema,
+    graph_id: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    build_plan: BuildPlanIdSchema,
+    intent: ProjectIntentSchema.nullable(),
+    graph_path: z.string().min(1),
+    primary_metrics: z.array(MetricCountSchema).default([]),
+    stages: z.array(GraphManifestStageSummarySchema).default([]),
+    entrypoints: z.array(ResourceRefSchema).default([]),
+    resources: z.array(ResourceRefSchema).default([]),
+    graph_outputs: GraphOutputCountsSchema,
+    readiness: GraphReadinessRollupSchema,
+}).strict().superRefine((value, ctx) => {
+    const resourceIds = new Set();
+    for (const [index, resource] of value.resources.entries()) {
+        if (resourceIds.has(resource.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["resources", index, "id"],
+                message: `Duplicate graph resource id: ${resource.id}.`,
+            });
+        }
+        resourceIds.add(resource.id);
+    }
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Check / Diagnostics / Ready — legacy verification primitives
 //
 // 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)
+//   - Diagnostics: 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`
+//   - Output diagnostic — Build Plan-declared per requested output; 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 +466,153 @@ 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
+ *   summary_backlinks_present      — every summary cited by a note's source_refs is also wikilinked from that layer (no orphaned summaries)
+ *   knowledge_web_connectivity     — every knowledge note links at least one OTHER knowledge note (no disconnected islands in the knowledge web)
+ *   graph_notes_connected          — every markdown note across the WHOLE Context Graph (summaries, knowledge, artifacts, home) is link-connected to at least one other note (no free-floating island anywhere, including uncited summaries)
  *   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",
+    "summary_backlinks_present",
+    "knowledge_web_connectivity",
+    "graph_notes_connected",
     "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"] }],
+    },
+    summary_backlinks_present: {
+        params: {
+            summaries_dir: "optional summaries directory name; defaults to summaries",
+            summary_file: "optional summary filename; defaults to summary.md",
+            manifest_file: "optional manifest filename; defaults to manifest.md",
+        },
+        examples: [{}, { summaries_dir: "summaries" }],
+    },
+    knowledge_web_connectivity: {
+        params: {
+            knowledge_dir: "optional knowledge directory; defaults to the artifact's own target path. May only narrow the scan to a path inside that target layer.",
+        },
+        examples: [{}, { knowledge_dir: "knowledge" }],
+    },
+    graph_notes_connected: {
+        params: {
+            graph_root: "optional graph-root-relative directory to scan; defaults to the Context Graph root (every note in every layer). Use to narrow the floor to one layer (e.g. summaries) when a Build Plan splits the connectivity floor across outputs.",
+        },
+        examples: [{}, { graph_root: "summaries" }],
+    },
+    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 +622,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 +637,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 +646,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",
+]);
+/**
+ * Legacy Build Plan check declaration. Current product surfaces should prefer
+ * concrete coverage metrics, Stage Manifests, and Graph Manifest readiness.
+ * Deterministic output diagnostics remain nested under requested outputs 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 +686,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 +698,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.
+ * Legacy internal requested-output schema.
  *
  * `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 +732,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 +741,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();
 // ───────────────────────────────────────────────────────────────────────────
-// Readiness — preparation-level aggregate verdict
+// Supplemental graph diagnostics
 //
-// Rolls up artifact statuses + user-check results + engine-level gates
-// (is the prep configured, has a Build run, etc.) into a single
+// Diagnostic rows are secondary review records 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 = MetricKeySchema;
+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 — project-level aggregate verdict
+//
+// Rolls up output 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 +870,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
+ * output diagnostic failures into the overall `Readiness` verdict.
  */
 export const GateStatusSchema = z.object({
     gate: ReadinessGateSchema,
@@ -309,40 +903,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 +959,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 +973,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 +981,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();