@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/contracts/lib/schema.d.ts

@@ -3,6 +3,12 @@ export declare const InterfIdPattern: RegExp;
 export declare const PreparationNamePattern: RegExp;
 export declare const PreparationNameSchema: z.ZodString;
 export declare const MethodIdSchema: z.ZodString;
+/**
+ * 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 declare const ArtifactIdSchema: z.ZodString;
 export declare const RuntimeStageSchema: z.ZodString;
 export declare const RuntimeContractTypeSchema: z.ZodString;
 export declare const RuntimeTargetTypeSchema: z.ZodEnum<{
@@ -12,13 +18,39 @@ export declare const TestTargetTypeSchema: z.ZodEnum<{
     "source-files": "source-files";
     compiled: "compiled";
 }>;
+export declare function isInterfRelativePath(value: string): boolean;
+/**
+ * A locator identifies where a resource lives so the API and UI can
+ * route the right action without hard-coding deployment shape.
+ *
+ *   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 declare const LocatorKindSchema: z.ZodEnum<{
+    "local-path": "local-path";
+    "remote-url": "remote-url";
+    "api-served": "api-served";
+}>;
+export declare const LocatorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "local-path": "local-path";
+        "remote-url": "remote-url";
+        "api-served": "api-served";
+    }>;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type LocatorKind = z.infer<typeof LocatorKindSchema>;
+export type Locator = z.infer<typeof LocatorSchema>;
 export declare const SourceKindSchema: z.ZodEnum<{
     "local-folder": "local-folder";
+    "remote-folder": "remote-folder";
 }>;
 export declare const SourceSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
         "local-folder": "local-folder";
+        "remote-folder": "remote-folder";
     }>;
     locator: z.ZodString;
 }, z.core.$strict>;
@@ -35,6 +67,7 @@ export declare const SourceFilesSchema: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             "local-folder": "local-folder";
+            "remote-folder": "remote-folder";
         }>;
         locator: z.ZodString;
     }, z.core.$strict>;
@@ -55,6 +88,7 @@ export declare const SourceSnapshotSchema: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             "local-folder": "local-folder";
+            "remote-folder": "remote-folder";
         }>;
         locator: z.ZodString;
     }, z.core.$strict>;
@@ -87,54 +121,266 @@ export declare const StageInputsSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const SourceCompiledMaxAttemptsSchema: z.ZodNumber;
 export declare const SourceCompiledMaxLoopsSchema: z.ZodNumber;
+/**
+ * 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 declare const CHECK_KINDS: readonly ["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 declare const CheckKindSchema: z.ZodEnum<{
+    file_exists: "file_exists";
+    min_file_count: "min_file_count";
+    min_file_count_matches_source: "min_file_count_matches_source";
+    frontmatter_valid: "frontmatter_valid";
+    frontmatter_required_keys: "frontmatter_required_keys";
+    wikilinks_valid: "wikilinks_valid";
+    must_not_contain: "must_not_contain";
+    must_contain: "must_contain";
+    qa_match: "qa_match";
+}>;
+export type CheckKind = z.infer<typeof CheckKindSchema>;
+/**
+ * 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 declare const CheckSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        file_exists: "file_exists";
+        min_file_count: "min_file_count";
+        min_file_count_matches_source: "min_file_count_matches_source";
+        frontmatter_valid: "frontmatter_valid";
+        frontmatter_required_keys: "frontmatter_required_keys";
+        wikilinks_valid: "wikilinks_valid";
+        must_not_contain: "must_not_contain";
+        must_contain: "must_contain";
+        qa_match: "qa_match";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type Check = z.infer<typeof CheckSchema>;
+/**
+ * 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 declare const ProofSchema: z.ZodObject<{
+    check_id: z.ZodString;
+    kind: z.ZodEnum<{
+        file_exists: "file_exists";
+        min_file_count: "min_file_count";
+        min_file_count_matches_source: "min_file_count_matches_source";
+        frontmatter_valid: "frontmatter_valid";
+        frontmatter_required_keys: "frontmatter_required_keys";
+        wikilinks_valid: "wikilinks_valid";
+        must_not_contain: "must_not_contain";
+        must_contain: "must_contain";
+        qa_match: "qa_match";
+    }>;
+    passed: z.ZodBoolean;
+    required: z.ZodBoolean;
+    summary: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    evaluated_at: z.ZodString;
+}, z.core.$strict>;
+export type Proof = z.infer<typeof ProofSchema>;
+/**
+ * Per-thing readiness verdict. Used for an artifact, a stage, or a
+ * preparation. Aggregate verdict over its required checks.
+ */
+export declare const ReadyVerdictSchema: z.ZodEnum<{
+    ready: "ready";
+    not_ready: "not_ready";
+    failed: "failed";
+    skipped: "skipped";
+}>;
+export type ReadyVerdict = z.infer<typeof ReadyVerdictSchema>;
+/**
+ * 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 declare const STANDARD_EVIDENCE_FRONTMATTER_KEYS: readonly ["source", "source_kind", "evidence_tier", "truth_mode", "state"];
+export type StandardEvidenceFrontmatterKey = typeof STANDARD_EVIDENCE_FRONTMATTER_KEYS[number];
+/**
+ * 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 declare const ArtifactPathShapeSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    path: z.ZodString;
+    artifact_kind: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+    }>;
+}, z.core.$strict>;
+export declare const ArtifactShapeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    path: z.ZodString;
+    artifact_kind: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+    }>;
+}, z.core.$strict>], "kind">;
+export type ArtifactPathShape = z.infer<typeof ArtifactPathShapeSchema>;
+export type ArtifactShape = z.infer<typeof ArtifactShapeSchema>;
+/**
+ * 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 declare const ArtifactSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    shape: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+        artifact_kind: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+        }>;
+    }, z.core.$strict>], "kind">;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            file_exists: "file_exists";
+            min_file_count: "min_file_count";
+            min_file_count_matches_source: "min_file_count_matches_source";
+            frontmatter_valid: "frontmatter_valid";
+            frontmatter_required_keys: "frontmatter_required_keys";
+            wikilinks_valid: "wikilinks_valid";
+            must_not_contain: "must_not_contain";
+            must_contain: "must_contain";
+            qa_match: "qa_match";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    built_by_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type Artifact = z.infer<typeof ArtifactSchema>;
+/**
+ * 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 declare const ArtifactStatusValueSchema: z.ZodEnum<{
+    ready: "ready";
+    not_ready: "not_ready";
+    failed: "failed";
+    skipped: "skipped";
+}>;
+export type ArtifactStatusValue = ReadyVerdict;
+export declare const ArtifactStatusSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    status: z.ZodEnum<{
+        ready: "ready";
+        not_ready: "not_ready";
+        failed: "failed";
+        skipped: "skipped";
+    }>;
+    built_by_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    proofs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        check_id: z.ZodString;
+        kind: z.ZodEnum<{
+            file_exists: "file_exists";
+            min_file_count: "min_file_count";
+            min_file_count_matches_source: "min_file_count_matches_source";
+            frontmatter_valid: "frontmatter_valid";
+            frontmatter_required_keys: "frontmatter_required_keys";
+            wikilinks_valid: "wikilinks_valid";
+            must_not_contain: "must_not_contain";
+            must_contain: "must_contain";
+            qa_match: "qa_match";
+        }>;
+        passed: z.ZodBoolean;
+        required: z.ZodBoolean;
+        summary: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        evaluated_at: z.ZodString;
+    }, z.core.$strict>>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ArtifactStatus = z.infer<typeof ArtifactStatusSchema>;
 export declare const ReadinessStatusSchema: z.ZodEnum<{
+    ready: "ready";
+    failed: "failed";
     "not-configured": "not-configured";
     "not-built": "not-built";
     building: "building";
     built: "built";
     checking: "checking";
-    ready: "ready";
     "not-ready": "not-ready";
     stale: "stale";
-    failed: "failed";
 }>;
 export declare const ReadinessGateSchema: z.ZodEnum<{
     "portable-context": "portable-context";
     "preparation-config": "preparation-config";
     "compile-run": "compile-run";
     "readiness-checks": "readiness-checks";
-    "source-baseline": "source-baseline";
-    "portable-context-check": "portable-context-check";
     "checks-current": "checks-current";
 }>;
-export declare const ReadinessCheckSchema: z.ZodObject<{
+/**
+ * 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 declare const GateStatusSchema: z.ZodObject<{
     gate: z.ZodEnum<{
         "portable-context": "portable-context";
         "preparation-config": "preparation-config";
         "compile-run": "compile-run";
         "readiness-checks": "readiness-checks";
-        "source-baseline": "source-baseline";
-        "portable-context-check": "portable-context-check";
         "checks-current": "checks-current";
     }>;
     ok: z.ZodBoolean;
     status: z.ZodOptional<z.ZodEnum<{
+        ready: "ready";
+        failed: "failed";
         "not-configured": "not-configured";
         "not-built": "not-built";
         building: "building";
         built: "built";
         checking: "checking";
-        ready: "ready";
         "not-ready": "not-ready";
         stale: "stale";
-        failed: "failed";
     }>>;
     summary: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     artifact_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
-export declare const ReadinessTargetResultSchema: z.ZodObject<{
+export declare const VerifyTargetResultSchema: z.ZodObject<{
     passed: z.ZodNumber;
     total: z.ZodNumber;
     pass_rate: z.ZodNullable<z.ZodNumber>;
@@ -143,21 +389,28 @@ export declare const ReadinessTargetResultSchema: z.ZodObject<{
     run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     run_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
-export declare const ReadinessStateSchema: z.ZodObject<{
+/**
+ * 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 declare const ReadinessSchema: z.ZodObject<{
     kind: z.ZodLiteral<"interf-readiness-state">;
     version: z.ZodLiteral<1>;
     generated_at: z.ZodString;
     preparation: z.ZodString;
     status: z.ZodEnum<{
+        ready: "ready";
+        failed: "failed";
         "not-configured": "not-configured";
         "not-built": "not-built";
         building: "building";
         built: "built";
         checking: "checking";
-        ready: "ready";
         "not-ready": "not-ready";
         stale: "stale";
-        failed: "failed";
     }>;
     ready: z.ZodBoolean;
     summary: z.ZodString;
@@ -170,21 +423,19 @@ export declare const ReadinessStateSchema: z.ZodObject<{
             "preparation-config": "preparation-config";
             "compile-run": "compile-run";
             "readiness-checks": "readiness-checks";
-            "source-baseline": "source-baseline";
-            "portable-context-check": "portable-context-check";
             "checks-current": "checks-current";
         }>;
         ok: z.ZodBoolean;
         status: z.ZodOptional<z.ZodEnum<{
+            ready: "ready";
+            failed: "failed";
             "not-configured": "not-configured";
             "not-built": "not-built";
             building: "building";
             built: "built";
             checking: "checking";
-            ready: "ready";
             "not-ready": "not-ready";
             stale: "stale";
-            failed: "failed";
         }>>;
         summary: z.ZodString;
         detail: z.ZodOptional<z.ZodString>;
@@ -219,21 +470,19 @@ export declare const ReadinessStateSchema: z.ZodObject<{
             "preparation-config": "preparation-config";
             "compile-run": "compile-run";
             "readiness-checks": "readiness-checks";
-            "source-baseline": "source-baseline";
-            "portable-context-check": "portable-context-check";
             "checks-current": "checks-current";
         }>;
         ok: z.ZodBoolean;
         status: z.ZodOptional<z.ZodEnum<{
+            ready: "ready";
+            failed: "failed";
             "not-configured": "not-configured";
             "not-built": "not-built";
             building: "building";
             built: "built";
             checking: "checking";
-            ready: "ready";
             "not-ready": "not-ready";
             stale: "stale";
-            failed: "failed";
         }>>;
         summary: z.ZodString;
         detail: z.ZodOptional<z.ZodString>;
@@ -241,6 +490,13 @@ export declare const ReadinessStateSchema: z.ZodObject<{
         artifact_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
+export declare const TestCaseExpectSchema: z.ZodObject<{
+    must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    min_words: z.ZodOptional<z.ZodNumber>;
+    max_words: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const RuntimeExecutorInfoSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         "local-agent": "local-agent";
@@ -255,15 +511,52 @@ export declare const RuntimeExecutorInfoSchema: z.ZodObject<{
     profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     timeout_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
-export declare const TestCaseExpectSchema: z.ZodObject<{
-    must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
-    must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    min_words: z.ZodOptional<z.ZodNumber>;
-    max_words: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
+/**
+ * The 5 canonical roles a Method stage can declare. Methods MAY declare
+ * custom role names; the engine treats any unknown role as `general`.
+ */
+export declare const CANONICAL_ROLES: readonly ["extractor", "summarizer", "structurer", "verifier", "general"];
+export type CanonicalRole = typeof CANONICAL_ROLES[number];
+/**
+ * Open-ended role identifier. Methods invent role names freely; the
+ * role-router maps unknown names to `general` at run time.
+ */
+export declare const RoleSchema: z.ZodString;
+/**
+ * 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 declare const AgentRecordSchema: z.ZodObject<{
+    name: z.ZodString;
+    display_name: z.ZodString;
+    command: z.ZodString;
+    source: z.ZodEnum<{
+        builtin: "builtin";
+        user: "user";
+    }>;
+    available: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AgentRecord = z.infer<typeof AgentRecordSchema>;
+export declare const RoleMapSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type RoleMap = z.infer<typeof RoleMapSchema>;
+export declare const AgentsRegistrySchema: z.ZodObject<{
+    agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        display_name: z.ZodString;
+        command: z.ZodString;
+        source: z.ZodEnum<{
+            builtin: "builtin";
+            user: "user";
+        }>;
+        available: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    role_map: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type AgentsRegistry = z.infer<typeof AgentsRegistrySchema>;
 export type PreparationName = z.infer<typeof PreparationNameSchema>;
 export type MethodId = z.infer<typeof MethodIdSchema>;
+export type ArtifactId = z.infer<typeof ArtifactIdSchema>;
 export type RuntimeStage = z.infer<typeof RuntimeStageSchema>;
 export type RuntimeContractType = z.infer<typeof RuntimeContractTypeSchema>;
 export type RuntimeTargetType = z.infer<typeof RuntimeTargetTypeSchema>;
@@ -277,8 +570,8 @@ export type StageInput = z.infer<typeof StageInputSchema>;
 export type StageInputs = z.infer<typeof StageInputsSchema>;
 export type ReadinessStatus = z.infer<typeof ReadinessStatusSchema>;
 export type ReadinessGate = z.infer<typeof ReadinessGateSchema>;
-export type ReadinessCheck = z.infer<typeof ReadinessCheckSchema>;
-export type ReadinessTargetResult = z.infer<typeof ReadinessTargetResultSchema>;
-export type ReadinessState = z.infer<typeof ReadinessStateSchema>;
+export type GateStatus = z.infer<typeof GateStatusSchema>;
+export type VerifyTargetResult = z.infer<typeof VerifyTargetResultSchema>;
+export type Readiness = z.infer<typeof ReadinessSchema>;
 export type RuntimeExecutorInfo = z.infer<typeof RuntimeExecutorInfoSchema>;
 export type TestCaseExpect = z.infer<typeof TestCaseExpectSchema>;