@interf/compiler 0.13.0 → 0.16.0

package/dist/packages/engine/agents/role-router.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Role router — picks which connected agent runs a given stage role.
+ *
+ * The compile pipeline calls `resolveAgentForRole` for each agent-typed
+ * stage, passing the stage's declared role and the current registry +
+ * active agent. The verify pipeline always passes role `"verifier"`.
+ *
+ * Resolution priority (lean / explicit):
+ *   1. Explicit role-map entry for the requested role.
+ *   2. Role-map's `general` row (when the requested role isn't mapped).
+ *   3. The active agent (when `general` isn't mapped either).
+ *
+ * If the role-map points at an agent name that no longer exists in the
+ * merged agents list (e.g. user uninstalled it), we fall through to
+ * `general` then `activeAgent`. Only when ALL three are missing does the
+ * router return an error.
+ */
+import type { AgentRecord, RoleMap } from "../../contracts/lib/schema.js";
+export type RoleResolutionSource = "explicit" | "fallback-general" | "fallback-active";
+export interface ResolvedAgent {
+    agent: AgentRecord;
+    /** The role the caller asked for (kept for audit / logging). */
+    role: string;
+    /** Which fallback rung the agent came from. */
+    source: RoleResolutionSource;
+}
+export interface RoleResolutionContext {
+    roleMap: RoleMap;
+    agents: AgentRecord[];
+    /**
+     * The agent the role-map's `general` row points at — or, when no
+     * role-map exists yet, the first detected agent. Pass `null` when
+     * there is no agent available; the router then returns an error.
+     */
+    activeAgent: AgentRecord | null;
+}
+export type RoleResolutionError = {
+    error: "no-agents";
+    detail: string;
+} | {
+    error: "mapped-agent-missing";
+    detail: string;
+};
+/**
+ * Resolve a stage role to an agent + provenance trail. Returns
+ * `{ agent, role, source }` on success or `{ error, detail }` on
+ * failure.
+ */
+export declare function resolveAgentForRole(role: string, context: RoleResolutionContext): ResolvedAgent | RoleResolutionError;
+/**
+ * Resolve every role declared by a Method's stages. Useful for
+ * pre-flight: returns either `{ resolutions }` (one entry per stage)
+ * or `{ error, role }` if any stage cannot resolve.
+ */
+export declare function resolveAgentsForStages(stages: ReadonlyArray<{
+    id: string;
+    role: string;
+}>, context: RoleResolutionContext): {
+    resolutions: Array<{
+        stageId: string;
+        resolved: ResolvedAgent;
+    }>;
+} | (RoleResolutionError & {
+    stageId: string;
+    role: string;
+});

package/dist/packages/engine/agents/role-router.js

@@ -0,0 +1,73 @@
+/**
+ * Resolve a stage role to an agent + provenance trail. Returns
+ * `{ agent, role, source }` on success or `{ error, detail }` on
+ * failure.
+ */
+export function resolveAgentForRole(role, context) {
+    if (context.agents.length === 0) {
+        return {
+            error: "no-agents",
+            detail: "No agents are available. Install Claude Code, Codex, or another agent CLI, " +
+                "or register a custom CLI with `interf agents register`.",
+        };
+    }
+    const trimmedRole = role && role.trim().length > 0 ? role.trim() : "general";
+    // 1. Explicit role-map entry for the requested role.
+    const explicitName = context.roleMap[trimmedRole];
+    if (explicitName) {
+        const found = context.agents.find((agent) => agent.name === explicitName);
+        if (found) {
+            return { agent: found, role: trimmedRole, source: "explicit" };
+        }
+        // Map exists but points at a missing agent. Fall through to
+        // `general` and ultimately `activeAgent`. We do NOT return
+        // `mapped-agent-missing` here because the resolution priority
+        // explicitly allows fallback through `general` and active —
+        // returning an error would block a usable agent.
+    }
+    // 2. Role-map's `general` row, if the requested role isn't `general`.
+    if (trimmedRole !== "general") {
+        const generalName = context.roleMap["general"];
+        if (generalName) {
+            const found = context.agents.find((agent) => agent.name === generalName);
+            if (found) {
+                return { agent: found, role: trimmedRole, source: "fallback-general" };
+            }
+        }
+    }
+    // 3. Active agent.
+    if (context.activeAgent) {
+        return {
+            agent: context.activeAgent,
+            role: trimmedRole,
+            source: "fallback-active",
+        };
+    }
+    // Map points at an agent we cannot find AND there is no active fallback.
+    if (explicitName) {
+        return {
+            error: "mapped-agent-missing",
+            detail: `Role "${trimmedRole}" maps to agent "${explicitName}", which is not detected or registered.`,
+        };
+    }
+    return {
+        error: "no-agents",
+        detail: `No agent is mapped to role "${trimmedRole}" and no active agent fallback is available.`,
+    };
+}
+/**
+ * Resolve every role declared by a Method's stages. Useful for
+ * pre-flight: returns either `{ resolutions }` (one entry per stage)
+ * or `{ error, role }` if any stage cannot resolve.
+ */
+export function resolveAgentsForStages(stages, context) {
+    const resolutions = [];
+    for (const stage of stages) {
+        const result = resolveAgentForRole(stage.role, context);
+        if ("error" in result) {
+            return { ...result, stageId: stage.id, role: stage.role };
+        }
+        resolutions.push({ stageId: stage.id, resolved: result });
+    }
+    return { resolutions };
+}

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

@@ -1,4 +1,4 @@
-import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type CompileRunCreateRequest, type CompileRunResource, type LocalJobRunResource, type LocalServiceHealth, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type ResetRequest, type ResetResult, type TestRunCreateRequest, type TestRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult } from "./lib/schema.js";
+import { type ActionProposalApprovalRequest, type ActionProposalCreateRequest, type ActionProposalResource, type CompileRunCreateRequest, type CompileRunResource, type LocalJobRunResource, type LocalServiceHealth, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type ResetRequest, type ResetResult, type VerifyRunCreateRequest, type VerifyRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult } from "./lib/schema.js";
 export interface FindOrStartLocalServiceOptions {
     url?: string;
     authToken?: string;
@@ -41,12 +41,12 @@ export declare function submitCompileRunToLocalService(options: {
     serviceUrl: string;
     resource: CompileRunResource;
 } | null>;
-export declare function submitTestRunToLocalService(options: {
+export declare function submitVerifyRunToLocalService(options: {
     preparationId: string;
-    request: TestRunCreateRequest;
+    request: VerifyRunCreateRequest;
 }): Promise<{
     serviceUrl: string;
-    resource: TestRunResource;
+    resource: VerifyRunResource;
 } | null>;
 export declare function submitResetToLocalService(options: {
     preparationId: string;
@@ -103,18 +103,18 @@ export declare function waitForLocalCompileRun(options: {
     authToken?: string | null;
     onUpdate?: (resource: CompileRunResource) => void;
 }): Promise<CompileRunResource>;
-export declare function getLocalTestRun(options: {
+export declare function getLocalVerifyRun(options: {
     serviceUrl: string;
     runId: string;
     authToken?: string | null;
-}): Promise<TestRunResource>;
-export declare function waitForLocalTestRun(options: {
+}): Promise<VerifyRunResource>;
+export declare function waitForLocalVerifyRun(options: {
     serviceUrl: string;
     runId: string;
     pollMs?: number;
     authToken?: string | null;
-    onUpdate?: (resource: TestRunResource) => void;
-}): Promise<TestRunResource>;
+    onUpdate?: (resource: VerifyRunResource) => void;
+}): Promise<VerifyRunResource>;
 export declare function getLocalJobRun(options: {
     serviceUrl: string;
     runId: string;

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

@@ -1,4 +1,4 @@
-import { CompileRunCreateRequestSchema, CompileRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
+import { CompileRunCreateRequestSchema, CompileRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
 import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, preparationSubresourcePath, } from "./routes.js";
 import { readActiveConnection } from "./connection-config.js";
 async function connectOrNull(options = {}) {
@@ -8,8 +8,8 @@ async function connectOrNull(options = {}) {
     });
     if (!conn)
         return null;
-    // Probe the engine; we expose the LocalServiceHealth-shaped object the
-    // legacy callers expect so submitCompileRun et al. keep compiling.
+    // Probe the engine and surface a LocalServiceHealth object that
+    // submitCompileRun et al. consume.
     try {
         const headers = {};
         if (conn.auth_token)
@@ -102,13 +102,13 @@ export async function submitCompileRunToLocalService(options) {
         resource,
     };
 }
-export async function submitTestRunToLocalService(options) {
+export async function submitVerifyRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = TestRunCreateRequestSchema.parse(options.request);
-    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "testRuns")}`;
-    const resource = TestRunResourceSchema.parse(await fetchJson(url, {
+    const request = VerifyRunCreateRequestSchema.parse(options.request);
+    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "verifyRuns")}`;
+    const resource = VerifyRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
         headers: authHeaders(connection.authToken),
@@ -235,19 +235,19 @@ export async function waitForLocalCompileRun(options) {
         }
     }
 }
-export async function getLocalTestRun(options) {
-    return TestRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/test-runs/${encodeURIComponent(options.runId)}`, {
+export async function getLocalVerifyRun(options) {
+    return VerifyRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/verify-runs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
         headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
     }));
 }
-export async function waitForLocalTestRun(options) {
+export async function waitForLocalVerifyRun(options) {
     // Same exponential backoff as `waitForLocalCompileRun`.
     const explicit = options.pollMs;
     let delay = explicit ?? 250;
     while (true) {
-        const resource = await getLocalTestRun({
+        const resource = await getLocalVerifyRun({
             serviceUrl: options.serviceUrl,
             runId: options.runId,
             authToken: options.authToken ?? null,

package/dist/packages/{compiler → engine/compile}/artifact-counts.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { listFilesRecursive } from "../shared/filesystem.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { compiledZoneAbsolutePath } from "./compiled-schema.js";
 const SCAFFOLD_PLACEHOLDER_SNIPPETS = [
     "Not yet compiled. Run `interf compile` to build the portable context.",

package/dist/packages/{compiler → engine/compile}/compiled-pipeline.d.ts

@@ -1,5 +1,5 @@
 import { type MethodExecutor } from "../agents/lib/executors.js";
-import { type MethodReporter, type MethodStageResult } from "../method-package/method-helpers.js";
+import { type MethodReporter, type MethodStageResult } from "../../methods/package/method-helpers.js";
 import { type CompiledStageExecutionDefinition } from "./compiled-target.js";
 import type { RunEventSink } from "../execution/events.js";
 export interface CompiledSummarizeResult extends MethodStageResult {
@@ -15,8 +15,17 @@ export interface CompiledCompileResult {
     failedStage: string | null;
 }
 export type StageShellRetentionMode = "on-failure" | "always";
+/**
+ * Per-stage executor resolver. When provided, the pipeline calls this
+ * for each stage and uses the returned executor instead of the
+ * top-level `executor`. The top-level `executor` stays as the default
+ * fallback so single-active-agent setups keep working without any
+ * resolver wired up.
+ */
+export type ResolveStageExecutor = (stage: CompiledStageExecutionDefinition) => MethodExecutor;
 export declare function runCompiledSummarize(options: {
     executor: MethodExecutor;
+    resolveStageExecutor?: ResolveStageExecutor;
     compiledPath: string;
     reporter?: MethodReporter;
     reportSummary?: boolean;
@@ -28,6 +37,7 @@ export declare function runCompiledSummarize(options: {
 }): Promise<CompiledSummarizeResult>;
 export declare function runCompiledCompile(options: {
     executor: MethodExecutor;
+    resolveStageExecutor?: ResolveStageExecutor;
     compiledPath: string;
     reporter?: MethodReporter;
     reportStep?: boolean;
@@ -37,6 +47,7 @@ export declare function runCompiledCompile(options: {
 }): Promise<MethodStageResult>;
 export declare function compileCompiled(options: {
     executor: MethodExecutor;
+    resolveStageExecutor?: ResolveStageExecutor;
     compiledPath: string;
     reporter?: MethodReporter;
     preserveStageShells?: StageShellRetentionMode;

package/dist/packages/{compiler → engine/compile}/compiled-pipeline.js

@@ -1,15 +1,25 @@
 import { refreshCompiledBootstrapGuidance, } from "../agents/lib/compiled-bootstrap.js";
-import { validateMethodPackage } from "../method-package/local-methods.js";
-import { reportValidationFailure, } from "../method-package/method-helpers.js";
+import { validateMethodPackage } from "../../methods/package/local-methods.js";
+import { reportValidationFailure, } from "../../methods/package/method-helpers.js";
 import { validateCompiledMethod, } from "./validate.js";
 import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
 import { resetCompiledGeneratedState } from "./reset.js";
 import { compiledExecutionStages, resolveCompiledContext, } from "./compiled-target.js";
 import { discoverSourceFiles } from "./discovery.js";
 import { runCompiledStage } from "./compiled-stage-runner.js";
-import { resolveSourceInputPath } from "../project-model/interf-detect.js";
+import { resolveSourceInputPath } from "../../project/interf-detect.js";
 import { methodPackagePathForCompiled } from "./compiled-paths.js";
 import { writeCompiledSourceRuntime } from "./source-files.js";
+function pickStageExecutor(fallback, stage, resolve) {
+    if (!resolve)
+        return fallback;
+    try {
+        return resolve(stage) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 export async function runCompiledSummarize(options) {
     const context = resolveCompiledContext(options.compiledPath);
     const stageDefinition = options.stageDefinition
@@ -31,7 +41,7 @@ export async function runCompiledSummarize(options) {
         runId: options.runId ?? null,
     });
     const result = await runCompiledStage({
-        executor: options.executor,
+        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
         compiledPath: options.compiledPath,
         reporter: options.reporter,
         reportStep: options.reportStep,
@@ -66,7 +76,7 @@ export async function runCompiledCompile(options) {
         });
         for (const [index, stageDefinition] of stages.entries()) {
             const result = await runCompiledStage({
-                executor: options.executor,
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
                 compiledPath: options.compiledPath,
                 reporter: options.reporter,
                 reportStep: options.reportStep,
@@ -130,7 +140,7 @@ export async function compileCompiled(options) {
         });
         for (const [index, stageDefinition] of stages.entries()) {
             const stageResult = await runCompiledStage({
-                executor: options.executor,
+                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
                 compiledPath: options.compiledPath,
                 reporter: options.reporter,
                 reportStep: true,

package/dist/packages/{compiler → engine/compile}/compiled-schema.d.ts

@@ -1,10 +1,10 @@
-import { type BuiltinCompiledZoneId } from "../method-package/builtin-compiled-method.js";
+import { type BuiltinCompiledZoneId } from "../../methods/package/builtin-compiled-method.js";
 import { type MethodCompiledSchema, type MethodCompiledZone, type MethodZoneId } from "./lib/schema.js";
 export interface MethodSchemaStageLike {
     id: string;
     writes: readonly string[];
 }
-export { BUILTIN_COMPILED_ZONE_IDS } from "../method-package/builtin-compiled-method.js";
+export { BUILTIN_COMPILED_ZONE_IDS } from "../../methods/package/builtin-compiled-method.js";
 export declare const METHOD_SCHEMA_FILE = "method.schema.json";
 export declare function methodSchemaFilePath(rootPath: string): string;
 export declare function resolveMethodSchemaPath(rootPath: string): string | null;

package/dist/packages/{compiler → engine/compile}/compiled-schema.js

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { warnInterf } from "../shared/logger.js";
-import { readJsonFileUnchecked } from "../shared/parse.js";
-import { BUILTIN_COMPILED_ZONE_IDS, listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "../method-package/builtin-compiled-method.js";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
+import { BUILTIN_COMPILED_ZONE_IDS, listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "../../methods/package/builtin-compiled-method.js";
 import { MethodCompiledSchemaSchema, } from "./lib/schema.js";
-export { BUILTIN_COMPILED_ZONE_IDS } from "../method-package/builtin-compiled-method.js";
+export { BUILTIN_COMPILED_ZONE_IDS } from "../../methods/package/builtin-compiled-method.js";
 export const METHOD_SCHEMA_FILE = "method.schema.json";
 const BUILTIN_COMPILED_ZONE_SPEC_BY_ID = new Map(listBuiltinCompiledZoneSpecs().map((zone) => [zone.id, zone]));
 export function methodSchemaFilePath(rootPath) {

package/dist/packages/{compiler → engine/compile}/compiled-stage-plan.d.ts

@@ -1,5 +1,5 @@
 import { type RuntimeStageContractDraft } from "./runtime.js";
-import { type MethodStageDefinition } from "../method-package/method-definitions.js";
+import { type MethodStageDefinition } from "../../methods/package/method-definitions.js";
 import { resolveCompiledContext, type CompiledStageExecutionDefinition } from "./compiled-target.js";
 import type { RuntimeStageInstructions } from "./lib/schema.js";
 export declare function resolveStageContractArtifacts(compiledPath: string, stageDefinition: Pick<MethodStageDefinition, "id" | "reads" | "writes">): {

package/dist/packages/{compiler → engine/compile}/compiled-stage-plan.js

@@ -1,12 +1,12 @@
 import { join } from "node:path";
 import { buildRuntimeStageContract, } from "./runtime.js";
 import { discoverSourceFiles } from "./discovery.js";
-import { listFilesRecursive } from "../shared/filesystem.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { compiledContractArtifactPathsForZoneIds, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
-import { buildLocalSkillContractExtension, buildStageInstructions, methodCompileStageDirectory, } from "../method-package/method-helpers.js";
-import { getActiveCompiledStagePolicyNotes, resolveActiveCompiledStageAcceptance, } from "../method-package/method-definitions.js";
+import { buildLocalSkillContractExtension, buildStageInstructions, methodCompileStageDirectory, } from "../../methods/package/method-helpers.js";
+import { getActiveCompiledStagePolicyNotes, resolveActiveCompiledStageAcceptance, } from "../../methods/package/method-definitions.js";
 import { methodPackagePathForCompiled } from "./compiled-paths.js";
-import { readInterfConfig } from "../project-model/interf-detect.js";
+import { readInterfConfig } from "../../project/interf-detect.js";
 import { resolveCompiledContext, } from "./compiled-target.js";
 function zoneArtifactCount(compiledPath, zonePath, kind) {
     const absolutePath = join(compiledPath, zonePath);

package/dist/packages/{compiler → engine/compile}/compiled-stage-runner.d.ts

@@ -1,5 +1,5 @@
 import { type MethodExecutor } from "../agents/lib/executors.js";
-import { type MethodReporter, type MethodStageResult } from "../method-package/method-helpers.js";
+import { type MethodReporter, type MethodStageResult } from "../../methods/package/method-helpers.js";
 import { type CompiledStageExecutionDefinition } from "./compiled-target.js";
 import { type RunEventSink } from "../execution/events.js";
 export declare function runCompiledStage(options: {

package/dist/packages/{compiler → engine/compile}/compiled-stage-runner.js

@@ -2,9 +2,9 @@ import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutio
 import { reconcileCompiledStageRun } from "./runtime-reconcile.js";
 import { refreshCompiledArtifacts } from "./state.js";
 import { validateCompiledStage } from "./validate.js";
-import { executeValidatedStage, } from "../method-package/method-stage-runner.js";
-import { formatActiveCompiledMethodStageStep, } from "../method-package/method-definitions.js";
-import { reportBlankLine, reportLine, } from "../method-package/method-helpers.js";
+import { executeValidatedStage, } from "../../methods/package/method-stage-runner.js";
+import { formatActiveCompiledMethodStageStep, } from "../../methods/package/method-definitions.js";
+import { reportBlankLine, reportLine, } from "../../methods/package/method-helpers.js";
 import { buildCompiledStageExecutionPlan, } from "./compiled-stage-plan.js";
 import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
 async function emitRunEvent(sink, event) {

package/dist/packages/{compiler → engine/compile}/compiled-target.d.ts

@@ -1,5 +1,5 @@
-import { type MethodStageDefinition } from "../method-package/method-definitions.js";
-import { type CompiledMethodId } from "../method-package/method-definitions.js";
+import { type MethodStageDefinition } from "../../methods/package/method-definitions.js";
+import { type CompiledMethodId } from "../../methods/package/method-definitions.js";
 export interface CompiledStageExecutionDefinition extends MethodStageDefinition {
 }
 export declare function resolveCompiledContext(compiledPath: string): {

package/dist/packages/{compiler → engine/compile}/compiled-target.js

@@ -1,5 +1,5 @@
-import { getActiveCompiledMethod, resolveRequiredCompiledMethodFromConfig, } from "../method-package/method-definitions.js";
-import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../project-model/interf-detect.js";
+import { getActiveCompiledMethod, resolveRequiredCompiledMethodFromConfig, } from "../../methods/package/method-definitions.js";
+import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../../project/interf-detect.js";
 export function resolveCompiledContext(compiledPath) {
     const config = readInterfConfig(compiledPath);
     const methodId = resolveRequiredCompiledMethodFromConfig(config, `.interf/interf.json for ${compiledPath}`);

package/dist/packages/{compiler → engine/compile}/discovery.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
-import { listFilesRecursive } from "../shared/filesystem.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 const DEFAULT_IGNORE_DIRS = new Set([
     "interf",
     ".interf",

package/dist/packages/{compiler → engine/compile}/lib/schema.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, TestCaseExpectSchema, TestTargetTypeSchema, MethodIdSchema } from "../../contracts/lib/schema.js";
-export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
+import { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, TestCaseExpectSchema, TestTargetTypeSchema, MethodIdSchema } from "../../../contracts/lib/schema.js";
+export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../../contracts/lib/schema.js";
 export type RuntimeStatus = "idle" | "running" | "compiled" | "stale" | "failed";
 export type CompiledStage = "idle" | "compiled" | "failed" | string;
 export declare const MethodZoneIdSchema: z.ZodString;
@@ -264,8 +264,8 @@ export declare const ExecutionShellPathsSchema: z.ZodObject<{
 export declare const RuntimeStageInstructionsSchema: z.ZodObject<{
     stage_skill_dir: z.ZodString;
     effective_mode: z.ZodEnum<{
-        override: "override";
         builtin: "builtin";
+        override: "override";
         extend: "extend";
     }>;
     local_mode: z.ZodNullable<z.ZodEnum<{
@@ -324,8 +324,8 @@ export declare const RuntimeStageContractSchema: z.ZodObject<{
     instructions: z.ZodObject<{
         stage_skill_dir: z.ZodString;
         effective_mode: z.ZodEnum<{
-            override: "override";
             builtin: "builtin";
+            override: "override";
             extend: "extend";
         }>;
         local_mode: z.ZodNullable<z.ZodEnum<{

package/dist/packages/{compiler → engine/compile}/lib/schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { COMPILED_ZONE_KINDS, } from "../method-primitives.js";
-import { RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
-export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../contracts/lib/schema.js";
+import { RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, InterfIdPattern, MethodIdSchema, } from "../../../contracts/lib/schema.js";
+export { ReadinessCheckSchema, ReadinessGateSchema, ReadinessStateSchema, ReadinessStatusSchema, ReadinessTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceSchema, SourceSnapshotSchema, StageInputSchema, StageInputsSchema, SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, MethodIdSchema, } from "../../../contracts/lib/schema.js";
 const JsonRecordSchema = z.record(z.string(), z.unknown());
 const COMPILED_RELATIVE_PATH_SEGMENT = /^(?!\.{1,2}$)[^/\\]+$/;
 function isCompiledRelativePath(value) {

package/dist/packages/{compiler → engine/compile}/method-runs.d.ts

@@ -1,5 +1,5 @@
-import { type InterfConfig } from "../project-model/interf-detect.js";
-export type { MethodReporter } from "../method-package/method-helpers.js";
+import { type InterfConfig } from "../../project/interf-detect.js";
+export type { MethodReporter } from "../../methods/package/method-helpers.js";
 export type CompiledCheck = "compiled" | "stage";
 export interface DetectedInterfTarget {
     path: string;
@@ -11,4 +11,4 @@ export declare function detectCompiled(cwd: string): DetectedInterfTarget | null
 export declare function createCompiled(name: string, sourcePath: string, methodId: string | undefined, about: string | undefined, sourceFolderPath: string): string;
 export declare function verifyCompiledCheck(check: CompiledCheck, compiledPath: string): import("./validate-compiled.js").CompiledMethodValidation;
 export { runCompiledSummarize, runCompiledCompile, compileCompiled, resolveCompiledContext, compiledExecutionStages, } from "./compiled-compile.js";
-export type { CompiledSummarizeResult, CompiledCompileResult, CompiledStageExecutionDefinition, StageShellRetentionMode, } from "./compiled-compile.js";
+export type { CompiledSummarizeResult, CompiledCompileResult, CompiledStageExecutionDefinition, StageShellRetentionMode, ResolveStageExecutor, } from "./compiled-compile.js";

package/dist/packages/{compiler → engine/compile}/method-runs.js

@@ -1,7 +1,7 @@
-import { createCompiled as createCompiledScaffold, } from "../project-model/interf-scaffold.js";
-import { detectInterf } from "../project-model/interf-detect.js";
+import { createCompiled as createCompiledScaffold, } from "../../project/interf-scaffold.js";
+import { detectInterf } from "../../project/interf-detect.js";
 import { validateCompiledCompile, } from "./validate.js";
-import { DEFAULT_METHOD_ID } from "../methods/method-resolution.js";
+import { DEFAULT_METHOD_ID } from "../../methods/method-resolution.js";
 export function detectCompiled(cwd) {
     const detected = detectInterf(cwd);
     if (!detected)

package/dist/packages/{compiler → engine/compile}/runtime-acceptance.js

@@ -1,9 +1,10 @@
 import { existsSync, } from "node:fs";
 import { join } from "node:path";
-import { listFilesRecursive } from "../shared/filesystem.js";
-import { readJsonFileWithSchema } from "../shared/parse.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { METHOD_SCHEMA_FILE, compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
 import { RuntimeStageContractSchema, } from "./lib/schema.js";
+import { ACCEPTANCE_RULE_KEYS } from "../../contracts/lib/schema.js";
 import { stageContractPath } from "./runtime-paths.js";
 import { methodPackagePathForCompiled } from "./compiled-paths.js";
 import { loadState } from "./state-io.js";
@@ -17,18 +18,20 @@ function toFiniteNumber(value) {
 function hasAcceptanceRules(acceptance) {
     if (!acceptance)
         return false;
-    return (acceptance.artifacts_exist?.length ?? 0) > 0 ||
-        (acceptance.stage_truthy?.length ?? 0) > 0 ||
-        Object.keys(acceptance.stage_equals_counts ?? {}).length > 0 ||
-        Object.keys(acceptance.stage_at_least ?? {}).length > 0 ||
-        Object.keys(acceptance.stage_at_least_counts ?? {}).length > 0 ||
-        Object.keys(acceptance.zone_counts_at_least ?? {}).length > 0 ||
-        Object.keys(acceptance.zone_counts_at_least_counts ?? {}).length > 0 ||
-        (acceptance.markdown_frontmatter_valid_zones?.length ?? 0) > 0 ||
-        Object.keys(acceptance.frontmatter_required_keys_in_zones ?? {}).length > 0 ||
-        (acceptance.markdown_abstract_valid_zones?.length ?? 0) > 0 ||
-        (acceptance.wikilinks_valid_in_zones?.length ?? 0) > 0 ||
-        Object.keys(acceptance.artifacts_must_not_contain ?? {}).length > 0;
+    // Drive off the canonical rule-key list so a new key added to
+    // contracts/ is automatically considered here.
+    for (const key of ACCEPTANCE_RULE_KEYS) {
+        const value = acceptance[key];
+        if (Array.isArray(value)) {
+            if (value.length > 0)
+                return true;
+        }
+        else if (value && typeof value === "object") {
+            if (Object.keys(value).length > 0)
+                return true;
+        }
+    }
+    return false;
 }
 function readPathValue(record, keyPath) {
     if (!record)

package/dist/packages/{compiler → engine/compile}/runtime-reconcile.d.ts

@@ -1,2 +1,2 @@
-import { type MethodStageDefinition } from "../method-package/method-definitions.js";
+import { type MethodStageDefinition } from "../../methods/package/method-definitions.js";
 export declare function reconcileCompiledStageRun(dirPath: string, stage: Pick<MethodStageDefinition, "id" | "contractType" | "reads" | "writes">): boolean;

package/dist/packages/{compiler → engine/compile}/runtime-reconcile.js

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import { extname, join, relative } from "node:path";
-import { listFilesRecursive } from "../shared/filesystem.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
-import { parseJsonFrontmatter } from "../shared/parse.js";
+import { parseJsonFrontmatter } from "../../contracts/utils/parse.js";
 import { loadRuntimeRun } from "./runtime.js";
 import { initCompiledState, loadState, refreshCompiledArtifacts, saveState, } from "./state.js";
 import { compiledInventoryFromEntries } from "./runtime-inventory.js";
+import { STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "../../contracts/lib/schema.js";
 import { compiledRuntimeRoot, methodPackagePathForCompiled } from "./compiled-paths.js";
 import { extractSynthAbstract, isOutputMarkdownFile } from "./validate.js";
 function readActiveRunStartedAtMs(dirPath) {
@@ -80,15 +81,16 @@ function buildInventoryMetadata(options) {
         metadata.abstract = abstract;
         metadata.abstract_read = true;
     }
+    // Project the standard evidence frontmatter keys onto the inventory
+    // metadata. Method authors that emit the canonical evidence keys
+    // (`STANDARD_EVIDENCE_FRONTMATTER_KEYS` in contracts) get them
+    // surfaced on stage inventory entries; non-standard keys are ignored.
     const frontmatter = options.parsedFrontmatter.frontmatter;
-    if (typeof frontmatter.source_kind === "string") {
-        metadata.source_kind = frontmatter.source_kind;
-    }
-    if (typeof frontmatter.evidence_tier === "string") {
-        metadata.evidence_tier = frontmatter.evidence_tier;
-    }
-    if (typeof frontmatter.truth_mode === "string") {
-        metadata.truth_mode = frontmatter.truth_mode;
+    for (const key of STANDARD_EVIDENCE_FRONTMATTER_KEYS) {
+        const value = frontmatter[key];
+        if (typeof value === "string") {
+            metadata[key] = value;
+        }
     }
     return metadata;
 }