@interf/compiler 0.16.0 → 0.21.0

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

@@ -1,4 +1,7 @@
 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", "methods"]);
@@ -7,28 +10,60 @@ export const PreparationNameSchema = z
     .regex(PreparationNamePattern, "Preparation names must use lowercase letters, numbers, and dashes only.")
     .refine((value) => !RESERVED_PREPARATION_NAMES.has(value), "Preparation name is reserved.");
 export const MethodIdSchema = z.string().regex(InterfIdPattern);
+/**
+ * Method-declared artifact identifier. Same shape as `MethodIdSchema`
+ * but conceptually distinct — it identifies a produced thing inside
+ * one Method, while `MethodIdSchema` identifies the Method itself.
+ */
+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(["compiled"]);
 export const TestTargetTypeSchema = z.enum(["compiled", "source-files"]);
-export const SourceKindSchema = z.enum(["local-folder"]);
+// ───────────────────────────────────────────────────────────────────────────
+// Path validation
+//
+// Used by Artifact paths and any other relative path the schema needs to
+// validate. Rejects path traversal (`..`), absolute paths, and Windows
+// drive letters. Centralized here so engine-side path checks share the
+// definition with schema-level refinements.
+// ───────────────────────────────────────────────────────────────────────────
+const RELATIVE_PATH_SEGMENT = /^(?!\.{1,2}$)[^/\\]+$/;
+export function isInterfRelativePath(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith("/") || value.startsWith("\\"))
+        return false;
+    if (/^[A-Za-z]:/.test(value))
+        return false;
+    return value
+        .split(/[\\/]+/)
+        .every((segment) => RELATIVE_PATH_SEGMENT.test(segment));
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Locator — discriminated resource address
+// ───────────────────────────────────────────────────────────────────────────
 /**
- * Canonical locator-kind enum. A locator identifies where a resource
- * lives so the API and UI can route the right action without hard-coding
- * deployment shape:
- *
- *   local-path  → the engine has filesystem access; UI opens via OS shell
- *   remote-url  → a signed URL; UI opens in a browser tab
- *   api-served  → relative API route; UI fetches via the engine and renders
- *                 inline (text/markdown drawer, image preview, download)
+ * A locator identifies where a resource lives so the API and UI can
+ * route the right action without hard-coding deployment shape.
  *
- * All three forms carry a string `value` whose meaning depends on `kind`.
+ *   local-path  → engine has filesystem access; UI opens via OS shell
+ *   remote-url  → signed URL; UI opens in a browser tab
+ *   api-served  → relative API route; UI fetches via the engine
  */
 export const LocatorKindSchema = z.enum(["local-path", "remote-url", "api-served"]);
 export const LocatorSchema = z.object({
     kind: LocatorKindSchema,
     value: z.string().min(1),
 }).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// 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).
+// ───────────────────────────────────────────────────────────────────────────
+export const SourceKindSchema = z.enum(["local-folder", "remote-folder"]);
 export const SourceSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     kind: SourceKindSchema,
@@ -75,6 +110,161 @@ export const StageInputsSchema = z.object({
 }).strict();
 export const SourceCompiledMaxAttemptsSchema = z.number().int().min(1).max(5);
 export const SourceCompiledMaxLoopsSchema = z.number().int().min(1).max(3);
+// ───────────────────────────────────────────────────────────────────────────
+// Check / Proof / 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)
+//   - Ready: aggregate verdict (`ready` or `not_ready`)
+//
+// A check has a SCOPE (where it's declared), not a different name:
+//   - stage check    — Method-declared per stage; runs end-of-stage
+//   - artifact check — Method-declared per artifact; runs end-of-compile
+//   - user check     — Preparation-declared; runs on `interf test`
+//
+// Same `Check` primitive across all three scopes. Same `CheckKind`
+// canonical list — methods/users/engine pick from it.
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Canonical check kinds the engine knows how to evaluate.
+ *
+ * Adding a new kind requires an engine release (the evaluator must
+ * implement it). Methods and user checks pick from this list; they
+ * cannot invent custom kinds.
+ *
+ *   file_exists                    — file is present and non-empty
+ *   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)
+ *   frontmatter_valid              — every markdown file has parseable YAML frontmatter
+ *   frontmatter_required_keys      — every markdown file has these frontmatter keys (params: { keys: string[] })
+ *   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 })
+ */
+export const CHECK_KINDS = [
+    "file_exists",
+    "min_file_count",
+    "min_file_count_matches_source",
+    "frontmatter_valid",
+    "frontmatter_required_keys",
+    "wikilinks_valid",
+    "must_not_contain",
+    "must_contain",
+    "qa_match",
+];
+export const CheckKindSchema = z.enum(CHECK_KINDS);
+/**
+ * One check declaration. Reusable across stage/artifact/user scopes.
+ *
+ * `id` is local to the declaring container (a stage's checks have ids
+ * scoped to the stage; an artifact's checks have ids scoped to the
+ * artifact). `kind` selects the canonical evaluator. `params` carries
+ * 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
+ * warn but don't block the `ready` verdict.
+ */
+export const CheckSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    kind: CheckKindSchema,
+    description: z.string().min(1).optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+    required: z.boolean().default(true),
+}).strict();
+/**
+ * Evidence a check ran. `passed` is the binary outcome; `summary` is a
+ * 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({
+    check_id: z.string().regex(InterfIdPattern),
+    kind: CheckKindSchema,
+    passed: z.boolean(),
+    required: z.boolean(),
+    summary: z.string().min(1),
+    details: z.record(z.string(), z.unknown()).optional(),
+    evaluated_at: z.string().min(1),
+}).strict();
+/**
+ * Per-thing readiness verdict. Used for an artifact, a stage, or a
+ * preparation. Aggregate verdict over its required checks.
+ */
+export const ReadyVerdictSchema = z.enum(["ready", "not_ready", "failed", "skipped"]);
+/**
+ * Standard frontmatter key list used by Methods that emit markdown
+ * summaries of source files. Method authors that adopt this evidence
+ * convention reference this constant in `frontmatter_required_keys`
+ * check params rather than re-typing the list.
+ */
+export const STANDARD_EVIDENCE_FRONTMATTER_KEYS = [
+    "source",
+    "source_kind",
+    "evidence_tier",
+    "truth_mode",
+    "state",
+];
+// ───────────────────────────────────────────────────────────────────────────
+// Artifact — a produced thing the user can see and verify
+//
+// Every output of a Method is an Artifact. No internal/working/output
+// distinction — if it's named, it's an Artifact. The engine 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 portable-context root,
+ * and `artifact_kind` tells consumers whether the target materializes
+ * as a file or directory.
+ */
+export const ArtifactPathShapeSchema = z.object({
+    kind: z.literal("path"),
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Artifact paths must stay inside the portable-context root (no `..`, no absolute paths).",
+    }),
+    artifact_kind: z.enum(["file", "directory"]),
+}).strict();
+export const ArtifactShapeSchema = z.discriminatedUnion("kind", [
+    ArtifactPathShapeSchema,
+]);
+/**
+ * Method-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 compile run.
+ */
+export const ArtifactSchema = z.object({
+    id: ArtifactIdSchema,
+    description: z.string().min(1),
+    shape: ArtifactShapeSchema,
+    checks: z.array(CheckSchema).default([]),
+    built_by_stages: z.array(z.string().regex(InterfIdPattern)).default([]),
+}).strict();
+/**
+ * Per-Artifact runtime status. Lives on compile-run resources and on
+ * preparation resources. `proofs[]` carries the structured evidence
+ * emitted by the shared check evaluator.
+ */
+export const ArtifactStatusValueSchema = ReadyVerdictSchema;
+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([]),
+    summary: z.string().min(1).optional(),
+}).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// Readiness — preparation-level aggregate verdict
+//
+// Rolls up artifact statuses + user-check results + engine-level gates
+// (is the prep configured, has compile run, etc.) into a single
+// `ready` / `not_ready` answer for the ICP.
+// ───────────────────────────────────────────────────────────────────────────
 export const ReadinessStatusSchema = z.enum([
     "not-configured",
     "not-built",
@@ -90,10 +280,17 @@ export const ReadinessGateSchema = z.enum([
     "preparation-config",
     "portable-context",
     "compile-run",
+    "artifact-checks",
     "readiness-checks",
     "checks-current",
 ]);
-export const ReadinessCheckSchema = z.object({
+/**
+ * Per-gate status — one row in the readiness summary. A gate is a
+ * high-level layer (is config valid? is portable context built? did
+ * latest compile succeed?). Gate failures are aggregated alongside
+ * artifact-check failures into the overall `Readiness` verdict.
+ */
+export const GateStatusSchema = z.object({
     gate: ReadinessGateSchema,
     ok: z.boolean(),
     status: ReadinessStatusSchema.optional(),
@@ -102,7 +299,7 @@ export const ReadinessCheckSchema = z.object({
     run_id: z.string().min(1).nullable().optional(),
     artifact_path: z.string().min(1).nullable().optional(),
 }).strict();
-export const ReadinessTargetResultSchema = z.object({
+export const VerifyTargetResultSchema = z.object({
     passed: z.number().int().min(0),
     total: z.number().int().min(0),
     pass_rate: z.number().min(0).max(100).nullable(),
@@ -111,7 +308,14 @@ export const ReadinessTargetResultSchema = z.object({
     run_id: z.string().min(1).nullable().optional(),
     run_path: z.string().min(1).nullable().optional(),
 }).strict();
-export const ReadinessStateSchema = z.object({
+/**
+ * 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`.
+ */
+export const ReadinessSchema = z.object({
     kind: z.literal("interf-readiness-state"),
     version: z.literal(1),
     generated_at: z.string().min(1),
@@ -122,61 +326,18 @@ export const ReadinessStateSchema = z.object({
     portable_context_path: z.string().min(1).nullable(),
     latest_compile_run_id: z.string().min(1).nullable().optional(),
     latest_test_run_id: z.string().min(1).nullable().optional(),
-    compile: ReadinessCheckSchema.nullable(),
+    compile: GateStatusSchema.nullable(),
     check_results: z.object({
         configured: z.number().int().min(0),
         fingerprint: z.string().min(1).nullable(),
-        source_files: ReadinessTargetResultSchema.nullable(),
-        portable_context: ReadinessTargetResultSchema.nullable(),
+        source_files: VerifyTargetResultSchema.nullable(),
+        portable_context: VerifyTargetResultSchema.nullable(),
     }).strict(),
-    checks: z.array(ReadinessCheckSchema).default([]),
+    checks: z.array(GateStatusSchema).default([]),
 }).strict();
-export const RuntimeExecutorInfoSchema = z.object({
-    kind: z.enum(["local-agent", "connected-provider", "managed"]),
-    name: z.string(),
-    display_name: z.string(),
-    command: z.string().nullable(),
-    model: z.string().nullable().optional(),
-    effort: z.string().nullable().optional(),
-    profile: z.string().nullable().optional(),
-    timeout_ms: z.number().nullable().optional(),
-});
-/**
- * Canonical list of stage acceptance-rule keys the engine understands.
- *
- * Method packages (`method.json`) declare per-stage `acceptance: {…}` blocks
- * that use a flat shape with these keys as optional properties. The runtime
- * walks the same key set when validating a stage outcome. The list is the
- * single source of truth; method-authoring prompts and runtime exhaustiveness
- * checks should both read from it instead of duplicating string literals.
- */
-export const ACCEPTANCE_RULE_KEYS = [
-    "artifacts_exist",
-    "stage_truthy",
-    "stage_equals_counts",
-    "stage_at_least",
-    "stage_at_least_counts",
-    "zone_counts_at_least",
-    "zone_counts_at_least_counts",
-    "markdown_frontmatter_valid_zones",
-    "frontmatter_required_keys_in_zones",
-    "markdown_abstract_valid_zones",
-    "wikilinks_valid_in_zones",
-    "artifacts_must_not_contain",
-];
-/**
- * Standard Interf evidence frontmatter keys used by Methods that emit
- * markdown summaries of source files. Method authors that adopt this
- * frontmatter convention should use this constant in
- * `frontmatter_required_keys_in_zones` rather than re-typing the list.
- */
-export const STANDARD_EVIDENCE_FRONTMATTER_KEYS = [
-    "source",
-    "source_kind",
-    "evidence_tier",
-    "truth_mode",
-    "state",
-];
+// ───────────────────────────────────────────────────────────────────────────
+// User-defined verification (Q/A pairs) — the "user check" scope
+// ───────────────────────────────────────────────────────────────────────────
 export const TestCaseExpectSchema = z.object({
     must_include: z.array(z.string().min(1)).optional(),
     must_include_one_of: z.array(z.array(z.string().min(1)).min(1)).optional(),
@@ -192,10 +353,23 @@ export const TestCaseExpectSchema = z.object({
     (value.must_not_include?.length ?? 0) > 0 ||
     value.min_words !== undefined ||
     value.max_words !== undefined, {
-    message: "Test expectations must include at least one check",
+    message: "User check expectations must include at least one constraint",
 });
 // ───────────────────────────────────────────────────────────────────────────
-// 0.15 — connected agents + roles
+// Executor info
+// ───────────────────────────────────────────────────────────────────────────
+export const RuntimeExecutorInfoSchema = z.object({
+    kind: z.enum(["local-agent", "connected-provider", "managed"]),
+    name: z.string(),
+    display_name: z.string(),
+    command: z.string().nullable(),
+    model: z.string().nullable().optional(),
+    effort: z.string().nullable().optional(),
+    profile: z.string().nullable().optional(),
+    timeout_ms: z.number().nullable().optional(),
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Connected agents + roles (0.15)
 // ───────────────────────────────────────────────────────────────────────────
 /**
  * The 5 canonical roles a Method stage can declare. Methods MAY declare
@@ -209,17 +383,14 @@ export const CANONICAL_ROLES = [
     "general",
 ];
 /**
- * Open-ended role identifier. Methods are free to invent new role names
- * (e.g. `pdf-extractor`, `chart-builder`); the role-router maps unknown
- * names to `general` at run time.
+ * Open-ended role identifier. Methods invent role names freely; the
+ * role-router maps unknown names to `general` at run time.
  */
 export const RoleSchema = z.string().min(1);
 /**
- * One agent in the registry. `source` distinguishes built-in detected
- * agents (Claude Code, Codex, Cursor) from user-registered custom CLIs
- * persisted in `~/.interf/agents.json`. `available` is a runtime-only
- * field — true if the command's first token resolves on PATH. It is
- * populated when the merged registry is read and is NOT persisted.
+ * One agent in the registry. `available` is a runtime-only flag — true
+ * if the command's first token resolves on PATH. Stripped before
+ * persistence.
  */
 export const AgentRecordSchema = z.object({
     name: z.string().min(1),
@@ -228,17 +399,7 @@ export const AgentRecordSchema = z.object({
     source: z.enum(["builtin", "user"]),
     available: z.boolean().optional(),
 }).strict();
-/**
- * Map from role name → agent name. Updated by the user via UI / CLI;
- * persisted in `~/.interf/agents.json`. Roles missing from this map
- * fall through to the active agent at run time.
- */
 export const RoleMapSchema = z.record(RoleSchema, z.string().min(1));
-/**
- * Wire shape of `~/.interf/agents.json`. Built-in agents are detected
- * dynamically and merged in at read time, so this file persists only
- * the user-registered subset and the role-map.
- */
 export const AgentsRegistrySchema = z.object({
     agents: z.array(AgentRecordSchema).default([]),
     role_map: RoleMapSchema.default({}),