@interf/compiler 0.13.0 → 0.18.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,11 +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
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * 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 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,
@@ -58,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     — ICP-declared per preparation; runs on `interf verify`
+//
+// 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",
@@ -74,11 +281,15 @@ export const ReadinessGateSchema = z.enum([
     "portable-context",
     "compile-run",
     "readiness-checks",
-    "source-baseline",
-    "portable-context-check",
     "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(),
@@ -87,7 +298,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(),
@@ -96,7 +307,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),
@@ -107,25 +325,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(),
-});
+// ───────────────────────────────────────────────────────────────────────────
+// 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(),
@@ -141,5 +352,54 @@ 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",
 });
+// ───────────────────────────────────────────────────────────────────────────
+// 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
+ * custom role names; the engine treats any unknown role as `general`.
+ */
+export const CANONICAL_ROLES = [
+    "extractor",
+    "summarizer",
+    "structurer",
+    "verifier",
+    "general",
+];
+/**
+ * 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. `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),
+    display_name: z.string().min(1),
+    command: z.string().min(1),
+    source: z.enum(["builtin", "user"]),
+    available: z.boolean().optional(),
+}).strict();
+export const RoleMapSchema = z.record(RoleSchema, z.string().min(1));
+export const AgentsRegistrySchema = z.object({
+    agents: z.array(AgentRecordSchema).default([]),
+    role_map: RoleMapSchema.default({}),
+}).strict();

package/dist/packages/{local-service → engine}/action-definitions.js

@@ -505,6 +505,14 @@ export function buildCreatePreparationActionDefinition(context) {
             };
         },
         fields: [
+            {
+                name: "path",
+                label: "Source folder",
+                type: "text",
+                help: "Absolute path to the folder Interf will read from. Files stay where they are; Interf reads them by reference.",
+                context: "Saved as the Preparation's source binding and sent as typed action input.",
+                placeholder: context.prepDataDir || "/Users/you/Documents/your-folder",
+            },
             {
                 name: "about",
                 label: "Agent job",
@@ -773,7 +781,7 @@ export function buildCreateMethodActionDefinition(context) {
                 type: "textarea",
                 rows: 3,
                 help: "What this Method output should be able to prove.",
-                context: "Guides readiness checks. Method acceptance criteria stay separate.",
+                context: "Guides readiness checks. Method Artifact checks stay separate.",
                 placeholder: "Describe the evidence that should make this Method output ready.",
             },
             {
@@ -1121,7 +1129,6 @@ export function buildReadinessActionDraft(options) {
             values: {
                 action_type: INTERF_SERVICE_ACTIONS.checkReadiness.serviceAction,
                 preparation: options.preparation,
-                mode: "both",
             },
         };
     }

package/dist/packages/{local-service → engine}/action-planner.d.ts

@@ -1,4 +1,4 @@
-import type { MethodExecutor } from "../agents/lib/executors.js";
+import type { MethodExecutor } from "./agents/lib/executors.js";
 import type { LocalServiceActionPlanningContext } from "./runtime.js";
 import { type ActionProposalCreateRequest, type ActionProposalPlan } from "./lib/schema.js";
 export declare function buildActionPlannerPrompt(request: ActionProposalCreateRequest, context: LocalServiceActionPlanningContext, outputPath: string): string;

package/dist/packages/{local-service → engine}/action-planner.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, } from "node:fs";
 import { join } from "node:path";
 import { methodIdForSourcePreparationConfig, } from "../methods/method-resolution.js";
-import { PACKAGE_ROOT } from "../method-package/lib/package-root.js";
+import { PACKAGE_ROOT } from "../methods/package/lib/package-root.js";
 import { asPreparationDataDir, preparationServiceActionPlansRoot, } from "../contracts/lib/preparation-paths.js";
 import { ActionProposalPlanSchema, } from "./lib/schema.js";
 function extractJsonObject(text) {

package/dist/packages/{agents → engine/agents}/index.d.ts

@@ -14,5 +14,8 @@ export * as executors from "./lib/executors.js";
 export * as schema from "./lib/schema.js";
 export * as userConfig from "./lib/user-config.js";
 export * as compiledBootstrap from "./lib/compiled-bootstrap.js";
+export * as registry from "./registry.js";
+export * as roleRouter from "./role-router.js";
+export * as roleExecutors from "./role-executors.js";
 export type { Agent, } from "./lib/types.js";
 export type { MethodExecutionProfile, MethodExecutor, MethodExecutorKind, } from "./lib/executors.js";

package/dist/packages/{agents → engine/agents}/index.js

@@ -14,3 +14,6 @@ export * as executors from "./lib/executors.js";
 export * as schema from "./lib/schema.js";
 export * as userConfig from "./lib/user-config.js";
 export * as compiledBootstrap from "./lib/compiled-bootstrap.js";
+export * as registry from "./registry.js";
+export * as roleRouter from "./role-router.js";
+export * as roleExecutors from "./role-executors.js";

package/dist/packages/{agents → engine/agents}/lib/compiled-bootstrap.js

@@ -1,6 +1,6 @@
 import { basename } from "node:path";
-import { readInterfConfig } from "../../project-model/interf-detect.js";
-import { resolveMethodId } from "../../methods/method-resolution.js";
+import { readInterfConfig } from "../../../project/interf-detect.js";
+import { resolveMethodId } from "../../../methods/method-resolution.js";
 import { projectCompiledQueryShell, renderClaudeBootstrap } from "./shells.js";
 export { renderClaudeBootstrap };
 export function refreshCompiledBootstrapGuidance(dirPath) {

package/dist/packages/engine/agents/lib/detection.d.ts

@@ -0,0 +1,13 @@
+import type { Agent } from "./types.js";
+export declare function detectAgents(): Agent[];
+/**
+ * Whether the executable named in an agent's `command` field resolves on
+ * PATH. Custom agents may register commands like `"opencode --prompt"`,
+ * so we only check the first whitespace-separated token.
+ */
+export declare function agentCommandAvailable(command: string): boolean;
+export declare function supportsAutomatedRuns(agent: Agent): boolean;
+export declare function resolveAgent(): {
+    agent: Agent | null;
+    error?: string;
+};

package/dist/packages/{agents → engine/agents}/lib/detection.js

@@ -19,6 +19,17 @@ function commandExists(command) {
         return false;
     }
 }
+/**
+ * Whether the executable named in an agent's `command` field resolves on
+ * PATH. Custom agents may register commands like `"opencode --prompt"`,
+ * so we only check the first whitespace-separated token.
+ */
+export function agentCommandAvailable(command) {
+    const firstToken = command.trim().split(/\s+/)[0];
+    if (!firstToken)
+        return false;
+    return commandExists(firstToken);
+}
 export function supportsAutomatedRuns(agent) {
     return agent.name === "claude-code" || agent.name === "codex";
 }

package/dist/packages/{agents → engine/agents}/lib/executors.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeExecutorInfo } from "../../contracts/lib/schema.js";
+import type { RuntimeExecutorInfo } from "../../../contracts/lib/schema.js";
 import type { Agent } from "./types.js";
 export type MethodExecutorKind = "local-agent" | "connected-provider" | "managed";
 export interface MethodExecutionProfile {
@@ -21,7 +21,7 @@ export interface MethodExecutor {
     executionProfile?: MethodExecutionProfile;
     execute(rootPath: string, prompt: string, options?: MethodExecuteOptions): Promise<number>;
 }
-export type { RuntimeExecutorInfo } from "../../contracts/lib/schema.js";
+export type { RuntimeExecutorInfo } from "../../../contracts/lib/schema.js";
 export declare function buildRuntimeExecutorInfo(executor: MethodExecutor): RuntimeExecutorInfo;
 export declare function createLocalAgentExecutor(agent: Agent, executionProfile?: MethodExecutionProfile): MethodExecutor;
 export declare function resolveLocalExecutor(options?: {

package/dist/packages/{agents → engine/agents}/lib/shells.d.ts

@@ -1,15 +1,22 @@
-import type { MethodImprovementContext } from "../../compiler/lib/schema.js";
-import type { RuntimeContractType } from "../../contracts/lib/schema.js";
-import type { SourceReadinessCheck } from "../../project-model/lib/schema.js";
-import { type ContextInterfaceZoneId as MethodZoneId } from "../../method-package/context-interface.js";
+import type { MethodImprovementContext } from "../../compile/lib/schema.js";
+import { type ArtifactPathShape, type Check, type RuntimeContractType } from "../../../contracts/lib/schema.js";
+import type { SourceReadinessCheck } from "../../../project/lib/schema.js";
+import { type ContextInterfaceArtifactId as MethodArtifactId } from "../../../methods/package/context-interface.js";
 export interface NativeStageDefinition {
     id: string;
     label: string;
     description: string;
     contractType: RuntimeContractType;
     skillDir: string;
-    reads: MethodZoneId[];
-    writes: MethodZoneId[];
+    reads: MethodArtifactId[];
+    writes: MethodArtifactId[];
+}
+export interface MethodAuthoringArtifactRequirement {
+    id: string;
+    description?: string;
+    shape: ArtifactPathShape;
+    checks: Check[];
+    stage_hint?: string;
 }
 export declare function writeNativeAgentSurface(rootPath: string, agentsContent: string, skillName: string, skillContent: string): boolean;
 export declare function renderCompiledAgents(compiledPath: string, name: string, methodId: string, about?: string, options?: {
@@ -27,6 +34,7 @@ export declare function createMethodAuthoringShell(options: {
     sourceFolderPath: string;
     taskPrompt: string;
     checks: SourceReadinessCheck[];
+    artifactRequirements?: MethodAuthoringArtifactRequirement[];
 }): {
     rootPath: string;
     methodBeforePath: string;