@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/methods/authoring/method-authoring.js

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createMethodAuthoringShell, } from "../../engine/agents/lib/shells.js";
+import { createScratchLocalMethodPackage } from "../package/interf-method-package.js";
+import { CONTEXT_INTERFACE_FILE, listContextInterfaceArtifacts } from "../package/context-interface.js";
+import { loadMethodDefinitionFromDir, validateMethodPackage, methodDefinitionPath, } from "../package/local-methods.js";
+import { runMethodEditSession } from "./method-edit-session.js";
+/**
+ * Walk method.json after a successful authoring run and fill in
+ * `role: "general"` for any stage missing a role field. Custom role
+ * names are kept as-is. Idempotent — does nothing when every stage
+ * already declares a role. Returns the list of stage ids that were
+ * touched so the runtime can surface that to the user.
+ */
+export function ensureStageRoles(methodPath) {
+    const methodJsonPath = join(methodPath, "method.json");
+    if (!existsSync(methodJsonPath))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(methodJsonPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return [];
+    const value = parsed;
+    if (!Array.isArray(value.stages))
+        return [];
+    const touched = [];
+    let changed = false;
+    const nextStages = value.stages.map((stage) => {
+        if (!stage || typeof stage !== "object" || Array.isArray(stage))
+            return stage;
+        const stageRecord = stage;
+        const declaredRole = typeof stageRecord.role === "string" && stageRecord.role.trim().length > 0
+            ? stageRecord.role.trim()
+            : null;
+        if (declaredRole)
+            return stage;
+        const id = typeof stageRecord.id === "string" ? stageRecord.id : "(unknown)";
+        touched.push(id);
+        changed = true;
+        return { ...stageRecord, role: "general" };
+    });
+    if (!changed)
+        return [];
+    value.stages = nextStages;
+    writeFileSync(methodJsonPath, `${JSON.stringify(value, null, 2)}\n`);
+    return touched;
+}
+function buildMethodAuthoringPrompt() {
+    return [
+        "This is an automated Interf Method-authoring run, not an open-ended chat session.",
+        "Execute it now.",
+        "Create one standalone Method package for the source data, desired portable-context outputs, and proof requirements in this source folder.",
+        "Read `runtime/authoring-context.json` first.",
+        "Treat `task_prompt` as the user's preparation-and-evidence brief: source data, output shape, and evidence that should show the data is ready.",
+        `Then read \`method/README.md\`, \`method/method.json\`, and \`method/${CONTEXT_INTERFACE_FILE}\`.`,
+        "The `method/` directory starts as a neutral Method package scaffold, not as a suggested Method.",
+        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Method this agent work actually needs.",
+        "Read `runtime/source-files.json` and inspect the listed source locators before editing the package.",
+        "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
+        "Edit only files under `method/`.",
+        "Keep the Method package valid for the current compiler API and `method.schema.json`.",
+        "Choose stage ids, stage order, artifact reads, artifact writes, artifact checks, and stage docs from the source data and preparation-and-evidence brief.",
+        "Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
+        "Each stage MAY declare a `role`: one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Pick the role that best matches what the stage's prompt asks the agent to do. Omit `role` (or use `general`) when the stage doesn't fit any specialized role. Custom role names are allowed; the engine treats unknown roles as `general`.",
+        "Do not preserve the placeholder `prepare` stage unless the final Method genuinely needs a stage with that exact role.",
+        "Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "Use only the CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases.",
+        "Keep Artifact checks and the producing stage docs aligned: every checked output requirement must be described in the stage doc that writes that Artifact.",
+        "For every stage in `method.json`, create `method/compile/stages/<skill_dir>/SKILL.md` and make the folder name exactly match that stage's kebab-case `skill_dir`.",
+        "Every Artifact path in `method.schema.json` must be unique and non-overlapping.",
+        "Make the package materially specific to this Preparation task, output shape, and proof requirement. A no-op scaffold is not acceptable.",
+        "Treat the Method package as four aligned layers: purpose, inputs, context interface, and stages.",
+        "If the Method writes an agent entrypoint, declare it as an Artifact and make the final shaping stage own it.",
+        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and context-interface edits over vague rewrites.",
+        "Do not introduce wikilinks unless the Method also creates the target note by exact basename or explicit relative path.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
+        "Do not make one stage point at files or notes that are only created later by another stage.",
+        "Prefer conservative retrieval routing over speculative note sprawl.",
+        "Do not narrate plans or ask follow-up questions.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "As soon as the Method edits are complete, stop.",
+    ].join("\n");
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value ?? {});
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableJson(entry)).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(",")}}`;
+}
+function checkMatchesRequirement(actual, required) {
+    return actual.id === required.id &&
+        actual.kind === required.kind &&
+        (actual.required ?? true) === (required.required ?? true) &&
+        stableJson(actual.params) === stableJson(required.params);
+}
+function producingStagesForArtifact(definition, artifactId) {
+    return (definition.stages ?? []).filter((stage) => Array.isArray(stage.writes) && stage.writes.includes(artifactId));
+}
+function readProducingStageDocs(methodPath, stages) {
+    return stages
+        .map((stage) => join(methodPath, "compile", "stages", stage.skill_dir ?? stage.id, "SKILL.md"))
+        .filter((filePath) => existsSync(filePath))
+        .map((filePath) => readFileSync(filePath, "utf8"))
+        .join("\n");
+}
+function validateMustContainStageDocs(methodPath, definition) {
+    const artifacts = definition.method_schema.artifacts ?? [];
+    const errors = [];
+    for (const artifact of artifacts) {
+        const producingStages = producingStagesForArtifact(definition, artifact.id);
+        if (producingStages.length === 0)
+            continue;
+        const producingStageDocs = readProducingStageDocs(methodPath, producingStages);
+        for (const check of artifact.checks ?? []) {
+            if (check.kind !== "must_contain")
+                continue;
+            const phrases = check.params?.phrases;
+            if (!Array.isArray(phrases))
+                continue;
+            for (const phrase of phrases) {
+                if (typeof phrase !== "string")
+                    continue;
+                if (!producingStageDocs.includes(phrase)) {
+                    errors.push(`Artifact \`${artifact.id}\` check \`${check.id}\` requires phrase not present in producing stage docs.`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+function validateArtifactRequirements(methodPath, definition, requirements) {
+    const artifacts = definition.method_schema.artifacts ?? [];
+    const errors = [];
+    for (const requirement of requirements) {
+        const artifact = artifacts.find((candidate) => candidate.id === requirement.id);
+        if (!artifact) {
+            errors.push(`Missing required Artifact \`${requirement.id}\`.`);
+            continue;
+        }
+        if (artifact.shape.kind !== requirement.shape.kind ||
+            artifact.shape.path !== requirement.shape.path ||
+            artifact.shape.artifact_kind !== requirement.shape.artifact_kind) {
+            errors.push(`Artifact \`${requirement.id}\` does not match required shape.`);
+        }
+        for (const check of requirement.checks) {
+            if (!artifact.checks.some((candidate) => checkMatchesRequirement(candidate, check))) {
+                errors.push(`Artifact \`${requirement.id}\` is missing required check \`${check.id}\`.`);
+            }
+        }
+        const producingStages = producingStagesForArtifact(definition, requirement.id);
+        if (producingStages.length === 0) {
+            errors.push(`Artifact \`${requirement.id}\` is not written by any stage.`);
+        }
+    }
+    return errors;
+}
+function validateAuthoredMethodPackage(methodPath, artifactRequirements = []) {
+    const validation = validateMethodPackage(methodPath);
+    if (!validation.ok)
+        return validation;
+    const definition = loadMethodDefinitionFromDir(methodPath);
+    if (!definition)
+        return validation;
+    const errors = [...validation.errors];
+    const placeholderStage = definition.stages?.find((stage) => stage.id === "prepare" &&
+        stage.contract_type === "method-draft-stage" &&
+        stage.writes.includes("draft-context"));
+    const placeholderArtifact = listContextInterfaceArtifacts(definition.method_schema).find((artifact) => artifact.id === "draft-context");
+    const placeholderPurpose = definition.purpose?.label === "From-scratch Method draft" ||
+        definition.purpose?.task_hint?.includes("Replace this neutral scaffold");
+    if (placeholderStage) {
+        errors.push("Authored Method still contains the neutral scaffold stage `prepare`.");
+    }
+    if (placeholderArtifact) {
+        errors.push("Authored Method still contains the neutral scaffold artifact `draft-context`.");
+    }
+    if (placeholderPurpose) {
+        errors.push("Authored Method still contains the neutral scaffold purpose.");
+    }
+    errors.push(...validateArtifactRequirements(methodPath, definition, artifactRequirements));
+    errors.push(...validateMustContainStageDocs(methodPath, definition));
+    return {
+        ok: validation.ok && errors.length === 0,
+        summary: errors.length === 0
+            ? validation.summary
+            : `Method package has ${errors.length} issue(s).`,
+        errors,
+        counts: validation.counts,
+    };
+}
+export async function runMethodAuthoringDraft(options) {
+    const methodPath = createScratchLocalMethodPackage({
+        prepDataDir: options.prepDataDir,
+        methodId: options.methodId,
+        label: options.label,
+        hint: options.hint,
+    });
+    const shell = createMethodAuthoringShell({
+        methodPath,
+        methodId: options.methodId,
+        label: options.label,
+        referenceMethodId: options.baseMethodId ?? null,
+        sourceFolderPath: options.sourceFolderPath,
+        taskPrompt: options.taskPrompt,
+        checks: options.checks ?? [],
+        artifactRequirements: options.artifactRequirements ?? [],
+    });
+    const session = await runMethodEditSession({
+        executor: options.executor,
+        methodPath,
+        shell,
+        prompt: buildMethodAuthoringPrompt(),
+        validate: (methodPath) => validateAuthoredMethodPackage(methodPath, options.artifactRequirements ?? []),
+        maxValidationRepairAttempts: 1,
+        onStatus: options.onStatus,
+    });
+    if (session.status !== "updated") {
+        rmSync(methodPath, { recursive: true, force: true });
+    }
+    else {
+        // 0.15 — auto-fill `role: "general"` for any stage the agent
+        // didn't explicitly tag. Idempotent and silent when every stage
+        // already declares a role.
+        const touched = ensureStageRoles(methodPath);
+        if (touched.length > 0 && options.onStatus) {
+            options.onStatus(`STATUS: filled role=general on ${touched.length} stage(s) the author didn't tag (${touched.join(", ")}).`);
+        }
+    }
+    return {
+        status: session.status,
+        changed: session.changed,
+        summary: session.summary,
+        validation: session.validation,
+        methodPath,
+        shellPath: shell.rootPath,
+    };
+}
+export function resolveMethodDraftPath(sourcePath, methodId) {
+    return methodDefinitionPath(sourcePath, methodId);
+}

package/dist/packages/{method-authoring → methods/authoring}/method-edit-session.d.ts

@@ -1,5 +1,5 @@
-import type { MethodExecutor } from "../agents/lib/executors.js";
-import type { MethodValidationResult } from "../method-package/local-methods.js";
+import type { MethodExecutor } from "../../engine/agents/lib/executors.js";
+import type { MethodValidationResult } from "../package/local-methods.js";
 import { type MethodEditShellArtifacts } from "./lib/method-edit-utils.js";
 export interface MethodEditSessionResult {
     status: "updated" | "no-change" | "invalid" | "executor-failed";

package/dist/packages/{method-authoring → methods/authoring}/method-edit-session.js

@@ -94,12 +94,12 @@ export async function runMethodEditSession(options) {
             "",
             "Rules:",
             "- Edit only files under `method/`.",
-            "- Use kebab-case ids everywhere: stage ids, skill_dir values, zone ids, reads/writes values, and package ids. Never use underscores.",
+            "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
             "- Keep every stage `skill_dir` matched by `method/compile/stages/<skill_dir>/SKILL.md`.",
-            "- Keep `method.schema.json` zone paths unique and non-overlapping.",
-            "- Keep zone-count acceptance keys declared in `method.schema.json`.",
-            "- Keep `artifacts_must_not_contain` keys as portable-context relative artifact paths such as `home.md`, not zone ids.",
-            "- Preserve root `home.md` as the main portable-context entrypoint when the Method writes an entrypoint.",
+            "- Keep `method.schema.json` Artifact paths unique and non-overlapping.",
+            "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+            "- Use only CheckKind values listed in `runtime/authoring-context.json`; replace invented aliases with valid kinds.",
+            "- If the Method writes an agent entrypoint, keep it declared as an Artifact owned by the producing stage.",
             "- Stop as soon as the package should validate.",
         ].join("\n");
         appendFileSync(options.shell.promptLogPath, `\n\n---\n\n${prompt}\n`);

package/dist/packages/{method-authoring → methods/authoring}/method-improvement.d.ts

@@ -1,7 +1,7 @@
-import type { MethodExecutor } from "../agents/lib/executors.js";
-import { type MethodValidationResult } from "../method-package/local-methods.js";
-import type { SourcePreparationConfig } from "../project-model/lib/schema.js";
-import type { MethodImprovementLoopSummary } from "../compiler/lib/schema.js";
+import type { MethodExecutor } from "../../engine/agents/lib/executors.js";
+import { type MethodValidationResult } from "../package/local-methods.js";
+import type { SourcePreparationConfig } from "../../project/lib/schema.js";
+import type { MethodImprovementLoopSummary } from "../../engine/compile/lib/schema.js";
 export interface MethodImprovementRunResult {
     status: "updated" | "no-change" | "invalid" | "executor-failed";
     changed: boolean;

package/dist/packages/{method-authoring → methods/authoring}/method-improvement.js

@@ -1,15 +1,16 @@
 import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { join, relative } from "node:path";
-import { createMethodImprovementShell, freezeMethodImprovementShell, } from "../agents/lib/shells.js";
-import { validateMethodPackage } from "../method-package/local-methods.js";
-import { CONTEXT_INTERFACE_FILE } from "../method-package/context-interface.js";
-import { readJsonFileWithSchema } from "../shared/parse.js";
-import { resolveMethodImprovementReviewPaths } from "../method-package/method-review-paths.js";
-import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, methodImprovementRunRoot, methodPackagePathForCompiled, } from "../compiler/compiled-paths.js";
-import { readInterfConfig } from "../project-model/interf.js";
-import { saveCompiledInterfConfig } from "../project-model/source-config.js";
-import { MethodImprovementRunLedgerSchema, } from "../compiler/lib/schema.js";
+import { createMethodImprovementShell, freezeMethodImprovementShell, } from "../../engine/agents/lib/shells.js";
+import { validateMethodPackage } from "../package/local-methods.js";
+import { CONTEXT_INTERFACE_FILE } from "../package/context-interface.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { resolveMethodImprovementReviewPaths } from "../package/method-review-paths.js";
+import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, methodImprovementRunRoot, methodPackagePathForCompiled, } from "../../engine/compile/compiled-paths.js";
+import { readInterfConfig } from "../../project/interf.js";
+import { saveCompiledInterfConfig } from "../../project/source-config.js";
+import { MethodImprovementRunLedgerSchema, } from "../../engine/compile/lib/schema.js";
 import { runMethodEditSession } from "./method-edit-session.js";
+import { ensureStageRoles } from "./method-authoring.js";
 function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
     if (!absolutePath)
         return null;
@@ -66,7 +67,7 @@ function buildMethodImprovementPrompt() {
         "Edit only files under `method/`.",
         "Do not edit checks, test specs, source files, or generated portable-context outputs.",
         "Keep the Method package valid for the current compiler API and `method.schema.json`.",
-        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
         "Prefer small, defensible changes to Method docs, stage docs, stage policies, or schema ownership over random churn.",
         "Do not narrate plans or ask follow-up questions.",
@@ -169,6 +170,11 @@ export async function runMethodImprovementLoop(options) {
         validate: validateMethodPackage,
         maxValidationRepairAttempts: 1,
     });
+    if (session.status === "updated") {
+        // 0.15 — fill role=general on any stage the improvement run
+        // dropped a role from. Idempotent and silent when complete.
+        ensureStageRoles(methodRoot);
+    }
     const preservedShellManifestPath = freezeMethodImprovementShell(shell.rootPath);
     writeMethodImprovementRunLedger(options.compiledPath, options.runId, buildMethodImprovementLoopRecord({
         targetName: compiledName,

package/dist/packages/{method-package → methods/package}/builtin-compiled-method.d.ts

@@ -1,37 +1,37 @@
-import { type CompiledZoneKind } from "../compiler/method-primitives.js";
+import { type CompiledArtifactKind } from "../../engine/compile/method-primitives.js";
 declare const BUILTIN_COMPILED_STAGE_IDS: {
     readonly SUMMARIZE: "summarize";
     readonly STRUCTURE: "structure";
     readonly SHAPE: "shape";
 };
 type BuiltinCompiledStageId = typeof BUILTIN_COMPILED_STAGE_IDS[keyof typeof BUILTIN_COMPILED_STAGE_IDS];
-export declare const BUILTIN_COMPILED_ZONE_IDS: {
+export declare const BUILTIN_COMPILED_ARTIFACT_IDS: {
     readonly SUMMARIES: "summaries";
     readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
     readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
     readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
-    readonly HOME: "home";
+    readonly HOME: "atlas";
     readonly RUNTIME: "runtime";
 };
-export type BuiltinCompiledZoneId = typeof BUILTIN_COMPILED_ZONE_IDS[keyof typeof BUILTIN_COMPILED_ZONE_IDS];
-export interface BuiltinCompiledZoneSpec {
-    id: BuiltinCompiledZoneId;
+export type BuiltinCompiledArtifactId = typeof BUILTIN_COMPILED_ARTIFACT_IDS[keyof typeof BUILTIN_COMPILED_ARTIFACT_IDS];
+export interface BuiltinCompiledArtifactSpec {
+    id: BuiltinCompiledArtifactId;
     role: "input" | "working" | "output" | "runtime";
     path: string;
-    kind: CompiledZoneKind;
+    kind: CompiledArtifactKind;
     required: boolean;
     description: string;
 }
 export interface BuiltinCompiledStageAccessPattern {
     id: BuiltinCompiledStageId;
     contract_type: string;
-    reads: BuiltinCompiledZoneId[];
-    writes: BuiltinCompiledZoneId[];
+    reads: BuiltinCompiledArtifactId[];
+    writes: BuiltinCompiledArtifactId[];
 }
-export declare function listBuiltinCompiledZoneSpecs(): BuiltinCompiledZoneSpec[];
+export declare function listBuiltinCompiledArtifactSpecs(): BuiltinCompiledArtifactSpec[];
 export declare function listBuiltinCompiledFallbackStages(): BuiltinCompiledStageAccessPattern[];
-export declare function requiredCompiledZoneOwners<TStage extends {
+export declare function requiredCompiledArtifactOwners<TStage extends {
     id: string;
     writes: readonly string[];
-}>(stages: readonly TStage[], zoneId: BuiltinCompiledZoneId): string[];
+}>(stages: readonly TStage[], artifactId: BuiltinCompiledArtifactId): string[];
 export {};

package/dist/packages/{method-package → methods/package}/builtin-compiled-method.js

@@ -1,27 +1,27 @@
 import { join } from "node:path";
 import { z } from "zod";
-import { readJsonFileWithSchema } from "../shared/parse.js";
-import { MethodCompiledSchemaSchema } from "../compiler/lib/schema.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { MethodCompiledSchemaSchema } from "../../engine/compile/lib/schema.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const BUILTIN_COMPILED_STAGE_IDS = {
     SUMMARIZE: "summarize",
     STRUCTURE: "structure",
     SHAPE: "shape",
 };
-export const BUILTIN_COMPILED_ZONE_IDS = {
+export const BUILTIN_COMPILED_ARTIFACT_IDS = {
     SUMMARIES: "summaries",
     KNOWLEDGE_ENTITIES: "knowledge-entities",
     KNOWLEDGE_CLAIMS: "knowledge-claims",
     KNOWLEDGE_INDEXES: "knowledge-indexes",
-    HOME: "home",
+    HOME: "atlas",
     RUNTIME: "runtime",
 };
-const BUILTIN_ZONE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_ZONE_IDS));
+const BUILTIN_ARTIFACT_ID_SET = new Set(Object.values(BUILTIN_COMPILED_ARTIFACT_IDS));
 const BUILTIN_STAGE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_STAGE_IDS));
 const BuiltinMethodStageSchema = z.object({
     id: z.string(),
     contract_type: z.string(),
-    reads: z.array(z.string()).min(1),
+    reads: z.array(z.string()),
     writes: z.array(z.string()).min(1),
 });
 const BuiltinMethodPackageSchema = z.object({
@@ -29,9 +29,9 @@ const BuiltinMethodPackageSchema = z.object({
 });
 let builtinCompiledContractCache = null;
 const BUILTIN_DEFAULT_METHOD_ROOT = join(PACKAGE_ROOT, "builtin-methods", "interf-default");
-function assertBuiltinZoneId(value) {
-    if (!BUILTIN_ZONE_ID_SET.has(value)) {
-        throw new Error(`Built-in Interf Method schema declares unsupported zone id "${value}".`);
+function assertBuiltinArtifactId(value) {
+    if (!BUILTIN_ARTIFACT_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf Method schema declares unsupported Artifact id "${value}".`);
     }
     return value;
 }
@@ -54,25 +54,28 @@ function loadBuiltinCompiledContract() {
     if (!method) {
         throw new Error(`Missing or invalid built-in Method package at ${methodPath}.`);
     }
-    const zones = schema.zones.map((zone) => ({
-        id: assertBuiltinZoneId(zone.id),
-        role: zone.role,
-        path: zone.path,
-        kind: zone.kind,
-        required: zone.required,
-        description: zone.description,
-    }));
+    const artifacts = schema.artifacts.map((artifact) => {
+        const path = artifact.shape.path;
+        return {
+            id: assertBuiltinArtifactId(artifact.id),
+            role: "output",
+            path,
+            kind: artifact.shape.artifact_kind,
+            required: true,
+            description: artifact.description,
+        };
+    });
     const stages = method.stages.map((stage) => ({
         id: assertBuiltinStageId(stage.id),
         contract_type: stage.contract_type,
-        reads: stage.reads.map(assertBuiltinZoneId),
-        writes: stage.writes.map(assertBuiltinZoneId),
+        reads: stage.reads.map(assertBuiltinArtifactId),
+        writes: stage.writes.map(assertBuiltinArtifactId),
     }));
-    builtinCompiledContractCache = { zones, stages };
+    builtinCompiledContractCache = { artifacts, stages };
     return builtinCompiledContractCache;
 }
-export function listBuiltinCompiledZoneSpecs() {
-    return loadBuiltinCompiledContract().zones.map((zone) => ({ ...zone }));
+export function listBuiltinCompiledArtifactSpecs() {
+    return loadBuiltinCompiledContract().artifacts.map((artifact) => ({ ...artifact }));
 }
 export function listBuiltinCompiledFallbackStages() {
     return loadBuiltinCompiledContract().stages.map((stage) => ({
@@ -81,8 +84,8 @@ export function listBuiltinCompiledFallbackStages() {
         writes: [...stage.writes],
     }));
 }
-export function requiredCompiledZoneOwners(stages, zoneId) {
+export function requiredCompiledArtifactOwners(stages, artifactId) {
     return Array.from(new Set(stages
-        .filter((stage) => stage.writes.includes(zoneId))
+        .filter((stage) => stage.writes.includes(artifactId))
         .map((stage) => stage.id)));
 }

package/dist/packages/methods/package/context-interface.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type MethodCompiledSchema, type MethodCompiledArtifact, type MethodArtifactId } from "../../engine/compile/lib/schema.js";
+export declare const CONTEXT_INTERFACE_FILE = "method.schema.json";
+export declare const ContextInterfaceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"method-schema">;
+    version: z.ZodLiteral<1>;
+    target_type: z.ZodLiteral<"compiled">;
+    label: z.ZodString;
+    artifacts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        shape: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+            artifact_kind: z.ZodEnum<{
+                file: "file";
+                directory: "directory";
+            }>;
+        }, z.core.$strict>], "kind">;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                file_exists: "file_exists";
+                min_file_count: "min_file_count";
+                min_file_count_matches_source: "min_file_count_matches_source";
+                frontmatter_valid: "frontmatter_valid";
+                frontmatter_required_keys: "frontmatter_required_keys";
+                wikilinks_valid: "wikilinks_valid";
+                must_not_contain: "must_not_contain";
+                must_contain: "must_contain";
+                qa_match: "qa_match";
+            }>;
+            description: z.ZodOptional<z.ZodString>;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            required: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        built_by_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const MethodInputSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ContextInterface = MethodCompiledSchema;
+export type ContextInterfaceArtifact = MethodCompiledArtifact;
+export type ContextInterfaceArtifactId = MethodArtifactId;
+export type MethodInputSpec = z.infer<typeof MethodInputSpecSchema>;
+interface ContextInterfaceStageLike {
+    id: string;
+    writes: readonly string[];
+}
+interface ContextInterfaceSummary {
+    inputArtifacts: ContextInterfaceArtifact[];
+    workingArtifacts: ContextInterfaceArtifact[];
+    outputArtifacts: ContextInterfaceArtifact[];
+    runtimeArtifacts: ContextInterfaceArtifact[];
+}
+export declare function listContextInterfaceArtifacts(contextInterface: ContextInterface): ContextInterfaceArtifact[];
+export declare function contextInterfaceFilePath(rootPath: string): string;
+export declare function resolveContextInterfacePath(rootPath: string): string | null;
+export declare function contextInterfaceExists(rootPath: string): boolean;
+export declare function contextInterfaceArtifactAbsolutePath(compiledPath: string, artifact: Pick<ContextInterfaceArtifact, "path">): string;
+export declare function contextInterfaceArtifactPath(artifact: Pick<ContextInterfaceArtifact, "path" | "kind">): string;
+export declare function summarizeContextInterface(contextInterface: ContextInterface): ContextInterfaceSummary;
+export declare function deriveMethodInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): MethodInputSpec[];
+export declare function buildContextInterface(stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterfaceFile(rootPath: string, stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterface(rootPath: string, contextInterface: ContextInterface): ContextInterface;
+export declare function readContextInterface(rootPath: string): ContextInterface | null;
+export {};