@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/engine/compile/check-evaluator.d.ts

@@ -0,0 +1,66 @@
+import { type Check, type CheckKind, type Proof } from "../../contracts/lib/schema.js";
+/**
+ * 0.17 — Check evaluator for the locked verification vocabulary.
+ *
+ * One evaluator per `CheckKind` from `CHECK_KINDS`. The evaluator is
+ * scope-agnostic: it takes a Check, a target path, and optional
+ * runtime context (counts, source-file totals); it returns a Proof.
+ *
+ * The same evaluator serves stage-level checks, artifact-level checks,
+ * and (for `qa_match`) user-level checks. Methods and user-defined
+ * verification declare `Check[]`; the runtime invokes this evaluator
+ * to produce `Proof[]`.
+ *
+ * This evaluator is the source of truth for declared verification
+ * checks. Legacy stage-acceptance rules were retired after the
+ * artifact-first migration.
+ */
+export interface CheckEvaluationContext {
+    /**
+     * Filesystem root the check evaluates against. For artifact checks
+     * this is the portable-context root; the artifact's path is
+     * resolved relative to it. For stage checks this can be the same
+     * root or a stage-output sub-directory.
+     */
+    rootPath: string;
+    /**
+     * Optional: the path the check targets. For artifact-scoped checks
+     * this is the artifact's `shape.path`; for stage-scoped checks
+     * this is the stage's writes path. Some kinds (qa_match) ignore
+     * targetPath because they operate on agent answers, not files.
+     */
+    targetPath?: string;
+    /**
+     * Optional runtime-derived counts used by `min_file_count_matches_source`
+     * and similar rules. `source_total` is the canonical key for "how
+     * many source files were processed." Methods reference it in check
+     * params via `{ match: "source_total" }`.
+     */
+    counts?: Record<string, number>;
+    /**
+     * Optional: the agent's answer for a `qa_match` check. Provided by
+     * the verify-run flow, not relevant for compile-time evaluation.
+     */
+    agentAnswer?: string;
+}
+export type CheckEvaluator = (check: Check, context: CheckEvaluationContext) => Proof;
+/**
+ * Evaluate a single Check against a context, returning a Proof.
+ */
+export declare function evaluateCheck(check: Check, context: CheckEvaluationContext): Proof;
+/**
+ * Evaluate a list of checks. Aggregate ready/not_ready verdict over
+ * the proofs: `ready` if every required check passed, otherwise
+ * `not_ready`. Soft checks (required: false) that fail produce a
+ * proof but don't change the verdict.
+ */
+export declare function evaluateChecks(checks: readonly Check[], context: CheckEvaluationContext): {
+    proofs: Proof[];
+    ready: boolean;
+    failures: Proof[];
+};
+/**
+ * Type guard for the canonical CheckKinds. Useful at parse boundaries
+ * where a string came from on-disk JSON.
+ */
+export declare function isCheckKind(value: unknown): value is CheckKind;

package/dist/packages/engine/compile/check-evaluator.js

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { CheckKindSchema, } from "../../contracts/lib/schema.js";
+import { countBrokenWikilinks, isOutputMarkdownFile, validateSynthFiles, } from "./validate.js";
+/**
+ * Build a Proof envelope from an evaluator outcome. Centralizes the
+ * timestamp + required-flag plumbing so individual evaluators can
+ * focus on the pass/fail decision and a one-line summary.
+ */
+function makeProof(check, passed, summary, details) {
+    return {
+        check_id: check.id,
+        kind: check.kind,
+        passed,
+        required: check.required,
+        summary,
+        ...(details !== undefined ? { details } : {}),
+        evaluated_at: new Date().toISOString(),
+    };
+}
+function resolveTargetPath(check, context) {
+    const target = context.targetPath;
+    if (!target)
+        return null;
+    const root = resolve(context.rootPath);
+    const absolute = resolve(root, target);
+    // Defense in depth — schema-level validation already rejects path
+    // traversal, but a hand-edited Method or stale on-disk fixture could
+    // slip through. Reject anything that escapes the root.
+    if (absolute !== root && !absolute.startsWith(`${root}/`)) {
+        return null;
+    }
+    return absolute;
+}
+function listMarkdownFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return [];
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile()) {
+            return isOutputMarkdownFile(absolutePath) ? [absolutePath] : [];
+        }
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, isOutputMarkdownFile);
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function countFiles(absolutePath) {
+    if (!existsSync(absolutePath))
+        return 0;
+    try {
+        const stats = statSync(absolutePath);
+        if (stats.isFile())
+            return 1;
+        if (stats.isDirectory()) {
+            return listFilesRecursive(absolutePath, () => true).length;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return 0;
+}
+const EVALUATORS = {
+    file_exists(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for file_exists check.");
+        }
+        if (!existsSync(target)) {
+            return makeProof(check, false, "File or directory does not exist.", { path: context.targetPath });
+        }
+        try {
+            const stats = statSync(target);
+            if (stats.isFile() && stats.size === 0) {
+                return makeProof(check, false, "File exists but is empty.", { path: context.targetPath });
+            }
+            return makeProof(check, true, `Path exists (${stats.isDirectory() ? "directory" : "file"}).`);
+        }
+        catch {
+            return makeProof(check, false, "Could not stat target path.", { path: context.targetPath });
+        }
+    },
+    min_file_count(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for min_file_count check.");
+        }
+        const min = typeof check.params?.min === "number" ? check.params.min : 1;
+        const actual = countFiles(target);
+        if (actual >= min) {
+            return makeProof(check, true, `${actual} file(s) (≥ ${min}).`, { actual, min });
+        }
+        return makeProof(check, false, `Found ${actual} file(s); expected at least ${min}.`, { actual, min });
+    },
+    min_file_count_matches_source(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for min_file_count_matches_source check.");
+        }
+        const matchKey = typeof check.params?.match === "string" ? check.params.match : "source_total";
+        const expected = context.counts?.[matchKey];
+        if (typeof expected !== "number") {
+            return makeProof(check, false, `Cannot evaluate: count "${matchKey}" not available in context.`, { matchKey });
+        }
+        const actual = countFiles(target);
+        if (actual >= expected) {
+            return makeProof(check, true, `${actual} of ${expected} source files covered.`, { actual, expected });
+        }
+        return makeProof(check, false, `Only ${actual} of ${expected} source files covered.`, { actual, expected, matchKey });
+    },
+    frontmatter_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for frontmatter_valid check.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeProof(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files);
+        if (validation.invalid_frontmatter === 0) {
+            return makeProof(check, true, `${files.length} markdown file(s) have valid frontmatter.`);
+        }
+        return makeProof(check, false, `${validation.invalid_frontmatter} of ${files.length} markdown file(s) have invalid frontmatter.`, { invalid: validation.invalid_frontmatter, total: files.length });
+    },
+    frontmatter_required_keys(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for frontmatter_required_keys check.");
+        }
+        const keys = Array.isArray(check.params?.keys) ? check.params.keys.filter((k) => typeof k === "string") : [];
+        if (keys.length === 0) {
+            return makeProof(check, false, "frontmatter_required_keys check requires `params.keys: string[]`.");
+        }
+        const files = listMarkdownFiles(target);
+        if (files.length === 0) {
+            return makeProof(check, true, "No markdown files to validate.");
+        }
+        const validation = validateSynthFiles(files, { requiredFrontmatterKeys: keys });
+        if (validation.invalid_frontmatter === 0) {
+            return makeProof(check, true, `All ${files.length} markdown file(s) have required keys: ${keys.join(", ")}.`);
+        }
+        return makeProof(check, false, `${validation.invalid_frontmatter} of ${files.length} file(s) missing required keys (${keys.join(", ")}).`, { invalid: validation.invalid_frontmatter, total: files.length, requiredKeys: keys });
+    },
+    wikilinks_valid(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target) {
+            return makeProof(check, false, "No target path provided for wikilinks_valid check.");
+        }
+        const broken = countBrokenWikilinks(context.rootPath, [context.rootPath], [target]);
+        if (broken === 0) {
+            return makeProof(check, true, "All wikilinks resolve.");
+        }
+        return makeProof(check, false, `${broken} broken wikilink(s).`, { broken });
+    },
+    must_not_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeProof(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = Array.isArray(check.params?.phrases)
+            ? check.params.phrases.filter((p) => typeof p === "string")
+            : [];
+        if (phrases.length === 0) {
+            return makeProof(check, false, "must_not_contain check requires `params.phrases: string[]`.");
+        }
+        try {
+            const stats = statSync(target);
+            const files = stats.isFile() ? [target] : listFilesRecursive(target, () => true);
+            const offenders = [];
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of phrases) {
+                    if (content.includes(phrase)) {
+                        offenders.push(`${file}: contains "${phrase}"`);
+                        break;
+                    }
+                }
+            }
+            if (offenders.length === 0) {
+                return makeProof(check, true, `No forbidden phrases found across ${files.length} file(s).`);
+            }
+            return makeProof(check, false, `${offenders.length} file(s) contain forbidden phrases.`, { offenders, phrases });
+        }
+        catch (error) {
+            return makeProof(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    must_contain(check, context) {
+        const target = resolveTargetPath(check, context);
+        if (!target || !existsSync(target)) {
+            return makeProof(check, false, "Target path does not exist.", { path: context.targetPath });
+        }
+        const phrases = Array.isArray(check.params?.phrases)
+            ? check.params.phrases.filter((p) => typeof p === "string")
+            : [];
+        if (phrases.length === 0) {
+            return makeProof(check, false, "must_contain check requires `params.phrases: string[]`.");
+        }
+        try {
+            const stats = statSync(target);
+            // For directories, must_contain checks across ALL files (every phrase
+            // must appear in at least one file). For files, all phrases must
+            // appear in that single file.
+            if (stats.isFile()) {
+                const content = readFileSync(target, "utf8");
+                const missing = phrases.filter((phrase) => !content.includes(phrase));
+                if (missing.length === 0) {
+                    return makeProof(check, true, `All ${phrases.length} required phrase(s) present.`);
+                }
+                return makeProof(check, false, `${missing.length} required phrase(s) missing.`, { missing });
+            }
+            const files = listFilesRecursive(target, () => true);
+            const remaining = new Set(phrases);
+            for (const file of files) {
+                const content = readFileSync(file, "utf8");
+                for (const phrase of [...remaining]) {
+                    if (content.includes(phrase))
+                        remaining.delete(phrase);
+                }
+                if (remaining.size === 0)
+                    break;
+            }
+            if (remaining.size === 0) {
+                return makeProof(check, true, `All ${phrases.length} required phrase(s) found across files.`);
+            }
+            return makeProof(check, false, `${remaining.size} required phrase(s) missing across all files.`, { missing: [...remaining] });
+        }
+        catch (error) {
+            return makeProof(check, false, `Error reading target: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+    qa_match(check, context) {
+        const expected = typeof check.params?.expected === "string" ? check.params.expected : "";
+        const strictness = typeof check.params?.strictness === "string" ? check.params.strictness : "loose";
+        const answer = context.agentAnswer ?? "";
+        if (!expected) {
+            return makeProof(check, false, "qa_match check requires `params.expected: string`.");
+        }
+        if (!answer) {
+            return makeProof(check, false, "No agent answer available for qa_match evaluation.");
+        }
+        if (strictness === "strict") {
+            const passed = answer.trim() === expected.trim();
+            return makeProof(check, passed, passed ? "Answer matches expected exactly." : "Answer does not match expected.");
+        }
+        // Loose: case-insensitive substring match either direction.
+        const a = answer.trim().toLowerCase();
+        const e = expected.trim().toLowerCase();
+        const passed = a.includes(e) || e.includes(a);
+        return makeProof(check, passed, passed ? "Answer matches expected (loose)." : "Answer does not match expected.");
+    },
+};
+/**
+ * Evaluate a single Check against a context, returning a Proof.
+ */
+export function evaluateCheck(check, context) {
+    const evaluator = EVALUATORS[check.kind];
+    if (!evaluator) {
+        return {
+            check_id: check.id,
+            kind: check.kind,
+            passed: false,
+            required: check.required,
+            summary: `Unknown check kind: ${check.kind}`,
+            evaluated_at: new Date().toISOString(),
+        };
+    }
+    return evaluator(check, context);
+}
+/**
+ * Evaluate a list of checks. Aggregate ready/not_ready verdict over
+ * the proofs: `ready` if every required check passed, otherwise
+ * `not_ready`. Soft checks (required: false) that fail produce a
+ * proof but don't change the verdict.
+ */
+export function evaluateChecks(checks, context) {
+    const proofs = checks.map((check) => evaluateCheck(check, context));
+    const failures = proofs.filter((proof) => !proof.passed && proof.required);
+    return {
+        proofs,
+        ready: failures.length === 0,
+        failures,
+    };
+}
+/**
+ * Type guard for the canonical CheckKinds. Useful at parse boundaries
+ * where a string came from on-disk JSON.
+ */
+export function isCheckKind(value) {
+    return CheckKindSchema.safeParse(value).success;
+}

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/engine/compile/compiled-schema.d.ts

@@ -0,0 +1,21 @@
+import { type MethodCompiledSchema, type MethodCompiledArtifact, type MethodArtifactId } from "./lib/schema.js";
+export interface MethodSchemaStageLike {
+    id: string;
+    writes: readonly string[];
+}
+export declare const METHOD_SCHEMA_FILE = "method.schema.json";
+export declare function methodSchemaFilePath(rootPath: string): string;
+export declare function resolveMethodSchemaPath(rootPath: string): string | null;
+export declare function methodSchemaExists(rootPath: string): boolean;
+export declare function methodSchemaRelativePath(): string;
+export declare function listCompiledSchemaArtifacts(schema: MethodCompiledSchema): MethodCompiledArtifact[];
+export declare function findCompiledSchemaArtifact(schema: MethodCompiledSchema, artifactId: MethodArtifactId): MethodCompiledArtifact | null;
+export declare function compiledArtifactAbsolutePath(compiledPath: string, artifact: Pick<MethodCompiledArtifact, "path">): string;
+export declare function compiledContractArtifactPath(artifact: Pick<MethodCompiledArtifact, "path" | "kind">): string;
+export declare function compiledContractArtifactPathsForArtifactIds(schema: MethodCompiledSchema, artifactIds: readonly MethodArtifactId[]): string[];
+export declare function ensureCompiledArtifactTargets(compiledPath: string, schema: MethodCompiledSchema): void;
+export declare function buildMethodSchema(stages: MethodSchemaStageLike[], label?: string): MethodCompiledSchema;
+export declare function writeMethodSchemaFile(rootPath: string, stages: MethodSchemaStageLike[], label?: string): MethodCompiledSchema;
+export declare function writeMethodSchemaDocument(rootPath: string, schema: MethodCompiledSchema): MethodCompiledSchema;
+export declare function readMethodSchemaFile(rootPath: string): MethodCompiledSchema | null;
+export declare function readCompiledSchemaFile(rootPath: string): MethodCompiledSchema | null;

package/dist/packages/engine/compile/compiled-schema.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { readJsonFileUnchecked } from "../../contracts/utils/parse.js";
+import { listBuiltinCompiledArtifactSpecs, requiredCompiledArtifactOwners, } from "../../methods/package/builtin-compiled-method.js";
+import { MethodCompiledSchemaSchema, } from "./lib/schema.js";
+export const METHOD_SCHEMA_FILE = "method.schema.json";
+export function methodSchemaFilePath(rootPath) {
+    return join(rootPath, METHOD_SCHEMA_FILE);
+}
+export function resolveMethodSchemaPath(rootPath) {
+    const path = methodSchemaFilePath(rootPath);
+    return existsSync(path) ? path : null;
+}
+export function methodSchemaExists(rootPath) {
+    return existsSync(methodSchemaFilePath(rootPath));
+}
+export function methodSchemaRelativePath() {
+    return `method/${METHOD_SCHEMA_FILE}`;
+}
+export function listCompiledSchemaArtifacts(schema) {
+    return schema.artifacts.map(artifactToMethodArtifact);
+}
+export function findCompiledSchemaArtifact(schema, artifactId) {
+    return listCompiledSchemaArtifacts(schema).find((artifact) => artifact.id === artifactId) ?? null;
+}
+export function compiledArtifactAbsolutePath(compiledPath, artifact) {
+    return join(compiledPath, artifact.path);
+}
+export function compiledContractArtifactPath(artifact) {
+    if (artifact.kind === "file")
+        return artifact.path;
+    return artifact.path.endsWith("/") ? artifact.path : `${artifact.path}/`;
+}
+export function compiledContractArtifactPathsForArtifactIds(schema, artifactIds) {
+    return artifactIds.map((artifactId) => {
+        const artifact = findCompiledSchemaArtifact(schema, artifactId);
+        if (!artifact) {
+            throw new Error(`Compiled schema is missing declared Artifact "${artifactId}".`);
+        }
+        return compiledContractArtifactPath(artifact);
+    });
+}
+export function ensureCompiledArtifactTargets(compiledPath, schema) {
+    for (const artifact of listCompiledSchemaArtifacts(schema)) {
+        if (artifact.kind === "directory" || artifact.kind === "runtime") {
+            mkdirSync(compiledArtifactAbsolutePath(compiledPath, artifact), { recursive: true });
+            continue;
+        }
+        mkdirSync(dirname(compiledArtifactAbsolutePath(compiledPath, artifact)), { recursive: true });
+    }
+}
+function normalizeMethodSchema(schema) {
+    return {
+        ...schema,
+        kind: "method-schema",
+    };
+}
+function artifactToMethodArtifact(artifact) {
+    if (artifact.shape.kind !== "path") {
+        return {
+            id: artifact.id,
+            role: "output",
+            path: artifact.id,
+            kind: "directory",
+            required: true,
+            owned_by: [...artifact.built_by_stages],
+            description: artifact.description,
+        };
+    }
+    return {
+        id: artifact.id,
+        role: "output",
+        path: artifact.shape.path,
+        kind: artifact.shape.artifact_kind,
+        required: true,
+        owned_by: [...artifact.built_by_stages],
+        description: artifact.description,
+    };
+}
+export function buildMethodSchema(stages, label = "Method schema") {
+    return {
+        kind: "method-schema",
+        version: 1,
+        target_type: "compiled",
+        label,
+        artifacts: listBuiltinCompiledArtifactSpecs().map((artifact) => ({
+            id: artifact.id,
+            description: artifact.description,
+            shape: {
+                kind: "path",
+                path: artifact.path,
+                artifact_kind: artifact.kind === "file" ? "file" : "directory",
+            },
+            checks: [],
+            built_by_stages: requiredCompiledArtifactOwners(stages, artifact.id),
+        })),
+    };
+}
+export function writeMethodSchemaFile(rootPath, stages, label) {
+    const schema = buildMethodSchema(stages, label);
+    writeMethodSchemaDocument(rootPath, schema);
+    return schema;
+}
+export function writeMethodSchemaDocument(rootPath, schema) {
+    const normalized = normalizeMethodSchema(schema);
+    writeFileSync(methodSchemaFilePath(rootPath), `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+}
+export function readMethodSchemaFile(rootPath) {
+    const path = methodSchemaFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "Method schema");
+    if (raw === null)
+        return null;
+    const parsed = MethodCompiledSchemaSchema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate Method schema at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return normalizeMethodSchema(parsed.data);
+}
+export function readCompiledSchemaFile(rootPath) {
+    return readMethodSchemaFile(rootPath);
+}

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

@@ -1,10 +1,11 @@
 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">): {
     reads: string[];
     writes: string[];
+    writeContracts: RuntimeStageContractDraft["artifacts"]["write_contracts"];
 };
 export declare function buildStageCounts(compiledPath: string, stageDefinition: MethodStageDefinition): Record<string, number>;
 export declare function buildStageContract(compiledPath: string, stageDefinition: MethodStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;