@interf/compiler 0.5.0 → 0.6.1

package/dist/lib/local-workflows.js

@@ -6,9 +6,10 @@ import { isMarkdownFile } from "./util.js";
 import { listFilesRecursive } from "./filesystem.js";
 import { warnInterf } from "./logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "./parse.js";
-import { listBuiltinCompiledZoneSpecs, } from "./workflow-abi.js";
-import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowStageZoneAccessSchema, WorkflowCompiledSchemaSchema, WorkflowIdPattern, } from "./schema.js";
-import { writeCompiledSchemaFile, compiledSchemaFilePath } from "./compiled-schema.js";
+import { listBuiltinCompiledZoneSpecs, } from "./builtin-compiled-workflow.js";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, WorkflowIdPattern, } from "./schema.js";
+import { WORKFLOW_SCHEMA_FILE, workflowSchemaExists, writeWorkflowSchemaDocument, workflowSchemaFilePath, readWorkflowSchemaFile, } from "./compiled-schema.js";
+import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 const LocalWorkflowStageDefinitionSchema = z.object({
     id: z.string().regex(WorkflowIdPattern),
     label: z.string().min(1),
@@ -23,6 +24,7 @@ const LocalWorkflowDefinitionSchema = z.object({
     id: z.string().regex(WorkflowIdPattern),
     type: z.literal("compiled"),
     compiler_api: WorkflowCompilerApiSchema.optional(),
+    purpose: WorkflowPurposeSchema.optional(),
     label: z.string().min(1),
     hint: z.string().min(1),
     extends: z.string().regex(WorkflowIdPattern).optional(),
@@ -38,15 +40,49 @@ function builtinWorkflowRootPath(workflowId) {
 export function workflowDefinitionPath(sourcePath, id) {
     return join(workflowRootPath(sourcePath), id);
 }
+function isSupportedWorkflowStarterDocPath(relativePath) {
+    if (relativePath === "README.md")
+        return true;
+    if (relativePath.startsWith("improve/"))
+        return true;
+    if (relativePath.startsWith("use/query/"))
+        return true;
+    if (relativePath.startsWith("compile/stages/"))
+        return true;
+    return false;
+}
 function collectStarterDocs(dirPath) {
     return listFilesRecursive(dirPath, isMarkdownFile)
-        .filter((filePath) => relative(dirPath, filePath).replaceAll("\\", "/") !== "workflow.json")
-        .map((filePath) => ({
-        relativePath: relative(dirPath, filePath).replaceAll("\\", "/"),
-        content: readFileSync(filePath, "utf8"),
+        .map((filePath) => relative(dirPath, filePath).replaceAll("\\", "/"))
+        .filter((relativePath) => isSupportedWorkflowStarterDocPath(relativePath))
+        .map((relativePath) => ({
+        relativePath,
+        content: readFileSync(join(dirPath, relativePath), "utf8"),
     }))
         .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
 }
+function workflowPackageCopyPaths(dirPath) {
+    return [
+        "workflow.json",
+        WORKFLOW_SCHEMA_FILE,
+        ...collectStarterDocs(dirPath).map((doc) => doc.relativePath),
+    ];
+}
+function copyRelativeFile(sourceRoot, targetRoot, relativePath) {
+    const sourcePath = join(sourceRoot, relativePath);
+    if (!existsSync(sourcePath))
+        return;
+    const targetPath = join(targetRoot, relativePath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    cpSync(sourcePath, targetPath, { force: true });
+}
+function copyWorkflowPackageFiles(sourceWorkflowPath, targetWorkflowPath) {
+    rmSync(targetWorkflowPath, { recursive: true, force: true });
+    mkdirSync(targetWorkflowPath, { recursive: true });
+    for (const relativePath of workflowPackageCopyPaths(sourceWorkflowPath)) {
+        copyRelativeFile(sourceWorkflowPath, targetWorkflowPath, relativePath);
+    }
+}
 export function loadWorkflowDefinitionFromDir(dirPath) {
     const workflowPath = existsSync(join(dirPath, "workflow.json"))
         ? join(dirPath, "workflow.json")
@@ -56,9 +92,8 @@ export function loadWorkflowDefinitionFromDir(dirPath) {
     const definition = readJsonFileWithSchema(workflowPath, "local workflow definition", LocalWorkflowDefinitionSchema);
     if (!definition)
         return null;
-    const schemaPath = compiledSchemaFilePath(dirPath);
-    const compiledSchema = readJsonFileWithSchema(schemaPath, "compiled schema", WorkflowCompiledSchemaSchema);
-    if (!compiledSchema)
+    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    if (!workflowSchema)
         return null;
     if (definition.type !== "compiled") {
         warnInterf(`Warning: local workflow definition at ${workflowPath} has unexpected type "${definition.type}".`);
@@ -66,11 +101,11 @@ export function loadWorkflowDefinitionFromDir(dirPath) {
     }
     return {
         ...definition,
-        compiled_schema: compiledSchema,
+        workflow_schema: workflowSchema,
         starter_docs: collectStarterDocs(dirPath),
         directoryPath: dirPath,
         workflowPath,
-        compiledSchemaPath: schemaPath,
+        workflowSchemaPath: workflowSchemaFilePath(dirPath),
     };
 }
 export function listLocalWorkflowDefinitions(sourcePath) {
@@ -108,36 +143,6 @@ export function resolveWorkflowPackageSourcePath(sourcePath, workflowId) {
 export function isWorkflowId(value) {
     return WorkflowIdPattern.test(value);
 }
-function normalizeStagePolicyNotes(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const normalized = {};
-    for (const [stageId, notes] of Object.entries(value)) {
-        if (!Array.isArray(notes))
-            continue;
-        const cleaned = Array.from(new Set(notes
-            .filter((note) => typeof note === "string")
-            .map((note) => note.trim())
-            .filter((note) => note.length > 0)));
-        if (cleaned.length > 0) {
-            normalized[stageId] = cleaned;
-        }
-    }
-    return Object.keys(normalized).length > 0 ? normalized : undefined;
-}
-function mergeStagePolicyNotes(currentValue, nextValue) {
-    const current = normalizeStagePolicyNotes(currentValue);
-    if (!nextValue || Object.keys(nextValue).length === 0)
-        return current;
-    const merged = { ...(current ?? {}) };
-    for (const [stageId, notes] of Object.entries(nextValue)) {
-        merged[stageId] = Array.from(new Set([
-            ...(merged[stageId] ?? []),
-            ...notes.map((note) => note.trim()).filter((note) => note.length > 0),
-        ]));
-    }
-    return Object.keys(merged).length > 0 ? merged : undefined;
-}
 function readWorkflowJsonObject(dirPath) {
     const workflowPath = join(dirPath, "workflow.json");
     const raw = readJsonFileUnchecked(workflowPath, "workflow package");
@@ -148,7 +153,6 @@ function readWorkflowJsonObject(dirPath) {
 }
 export function patchWorkflowPackageMetadata(dirPath, options = {}) {
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = compiledSchemaFilePath(dirPath);
     const workflowJson = readWorkflowJsonObject(dirPath);
     const normalizedStages = Array.isArray(workflowJson.stages) && workflowJson.stages.length > 0
         ? workflowJson.stages
@@ -169,7 +173,7 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
         ...(options.hint ? { hint: options.hint } : {}),
     };
     delete nextWorkflowJson.extends;
-    const mergedStagePolicyNotes = mergeStagePolicyNotes(workflowJson.stage_policy_notes, options.stagePolicyNotes);
+    const mergedStagePolicyNotes = mergeStagePolicyNotesForStages(normalizedStages, workflowJson.stage_policy_notes, options.stagePolicyNotes);
     if (mergedStagePolicyNotes) {
         nextWorkflowJson.stage_policy_notes = mergedStagePolicyNotes;
     }
@@ -177,33 +181,57 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
         delete nextWorkflowJson.stage_policy_notes;
     }
     writeFileSync(workflowPath, JSON.stringify(nextWorkflowJson, null, 2) + "\n");
-    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} compiled schema`;
-    if (!existsSync(schemaPath)) {
-        writeCompiledSchemaFile(dirPath, normalizedStages, schemaLabel);
-        return;
+    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} workflow schema`;
+    const existingSchema = readWorkflowSchemaFile(dirPath);
+    if (!existingSchema) {
+        throw new Error(`Cannot patch workflow package at ${dirPath}: missing ${WORKFLOW_SCHEMA_FILE}. Restore or reseed the package instead of regenerating a schema from workflow.json.`);
     }
-    const rawSchema = readJsonFileUnchecked(schemaPath, "compiled schema");
-    if (!rawSchema || typeof rawSchema !== "object" || Array.isArray(rawSchema))
-        return;
-    writeFileSync(schemaPath, JSON.stringify({
-        ...rawSchema,
+    writeWorkflowSchemaDocument(dirPath, {
+        ...existingSchema,
         label: schemaLabel,
-    }, null, 2) + "\n");
+    });
 }
-export function describeWorkflowPackagePortability(dirPath) {
+function collectWorkflowPackageStructureIssues(dirPath, stages) {
     const issues = [];
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = compiledSchemaFilePath(dirPath);
     if (!existsSync(workflowPath))
         issues.push("missing workflow.json");
-    if (!existsSync(schemaPath))
-        issues.push("missing compiled.schema.json");
+    if (!workflowSchemaExists(dirPath))
+        issues.push("missing workflow.schema.json");
     if (!existsSync(join(dirPath, "README.md")))
         issues.push("missing README.md");
     if (!existsSync(join(dirPath, "improve", "SKILL.md")))
         issues.push("missing improve/SKILL.md");
     if (!existsSync(join(dirPath, "use", "query", "SKILL.md")))
         issues.push("missing use/query/SKILL.md");
+    if (!stages)
+        return issues;
+    for (const stage of stages) {
+        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+            ? stage.skill_dir
+            : stage.id;
+        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+function collectWorkflowStageSkillIssues(dirPath, stages) {
+    if (!stages)
+        return [];
+    const issues = [];
+    for (const stage of stages) {
+        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+            ? stage.skill_dir
+            : stage.id;
+        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+export function describeWorkflowPackagePortability(dirPath) {
+    const issues = collectWorkflowPackageStructureIssues(dirPath, null);
     if (issues.length > 0)
         return issues;
     let workflowJson;
@@ -228,15 +256,10 @@ export function describeWorkflowPackagePortability(dirPath) {
         issues.push("workflow.json must declare explicit stages for a portable workflow package");
         return issues;
     }
-    for (const stage of parsed.data.stages) {
-        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
-            ? stage.skill_dir
-            : stage.id;
-        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
-            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
-        }
-    }
-    return issues;
+    return [
+        ...issues,
+        ...collectWorkflowStageSkillIssues(dirPath, parsed.data.stages ?? null),
+    ];
 }
 export function isPortableWorkflowPackage(dirPath) {
     return describeWorkflowPackagePortability(dirPath).length === 0;
@@ -246,13 +269,11 @@ export function copyWorkflowPackageDirectory(sourceWorkflowPath, targetWorkflowP
     if (portabilityIssues.length > 0) {
         throw new Error(`Workflow package at ${sourceWorkflowPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
     }
-    rmSync(targetWorkflowPath, { recursive: true, force: true });
     mkdirSync(dirname(targetWorkflowPath), { recursive: true });
-    cpSync(sourceWorkflowPath, targetWorkflowPath, { recursive: true });
+    copyWorkflowPackageFiles(sourceWorkflowPath, targetWorkflowPath);
 }
 export function validateWorkflowPackage(dirPath) {
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = compiledSchemaFilePath(dirPath);
     if (!existsSync(workflowPath)) {
         return {
             ok: false,
@@ -288,38 +309,30 @@ export function validateWorkflowPackage(dirPath) {
     if (!def.stages || def.stages.length === 0) {
         errors.push("workflow.json must declare explicit stages. Legacy inherited packages are not portable.");
     }
-    if (!existsSync(schemaPath)) {
-        errors.push("Missing compiled.schema.json.");
-    }
-    if (!existsSync(join(dirPath, "README.md"))) {
-        errors.push("Missing README.md.");
-    }
-    if (!existsSync(join(dirPath, "improve", "SKILL.md"))) {
-        errors.push("Missing improve/SKILL.md.");
-    }
-    if (!existsSync(join(dirPath, "use", "query", "SKILL.md"))) {
-        errors.push("Missing use/query/SKILL.md.");
-    }
-    const compiledSchema = readJsonFileWithSchema(schemaPath, "compiled schema", WorkflowCompiledSchemaSchema);
-    if (!compiledSchema) {
-        errors.push("compiled.schema.json is missing or invalid.");
-    }
-    if (def.stages && def.stages.length > 0) {
-        for (const stage of def.stages) {
-            const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
-                ? stage.skill_dir
-                : stage.id;
-            if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
-                errors.push(`Missing compile/stages/${skillDir}/SKILL.md.`);
+    if (def.stage_policy_notes && def.stages) {
+        const stageIds = new Set(def.stages.map((stage) => stage.id));
+        for (const stageId of Object.keys(def.stage_policy_notes)) {
+            if (!stageIds.has(stageId)) {
+                errors.push(`workflow.json stage_policy_notes references unknown stage "${stageId}".`);
             }
         }
     }
-    if (compiledSchema) {
+    for (const issue of collectWorkflowPackageStructureIssues(dirPath, def.stages ?? null)) {
+        const formatted = issue.startsWith("missing ")
+            ? `Missing ${issue.slice("missing ".length)}.`
+            : issue;
+        errors.push(formatted);
+    }
+    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    if (!workflowSchema) {
+        errors.push("workflow.schema.json is missing or invalid.");
+    }
+    if (workflowSchema) {
         const stages = def.stages ?? [];
         const stageIds = new Set(stages.map((stage) => stage.id));
         const seenPaths = new Map();
         const seenZoneIds = new Set();
-        const zoneById = new Map(compiledSchema.zones.map((zone) => [zone.id, zone]));
+        const zoneById = new Map(workflowSchema.zones.map((zone) => [zone.id, zone]));
         const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
         const hasOverlappingPath = (value, other) => {
             const a = normalizedParts(value);
@@ -328,26 +341,29 @@ export function validateWorkflowPackage(dirPath) {
             const longer = a.length <= b.length ? b : a;
             return shorter.every((part, index) => longer[index] === part);
         };
-        for (const zone of compiledSchema.zones) {
+        for (const zone of workflowSchema.zones) {
             if (seenZoneIds.has(zone.id)) {
-                errors.push(`compiled.schema.json repeats zone id "${zone.id}".`);
+                errors.push(`workflow.schema.json repeats zone id "${zone.id}".`);
             }
             seenZoneIds.add(zone.id);
             const existingPathOwner = seenPaths.get(zone.path);
             if (existingPathOwner) {
-                errors.push(`compiled.schema.json repeats zone path "${zone.path}".`);
+                errors.push(`workflow.schema.json repeats zone path "${zone.path}".`);
             }
             for (const [existingPath, existingZoneId] of seenPaths.entries()) {
                 if (existingPath === zone.path)
                     continue;
                 if (hasOverlappingPath(zone.path, existingPath)) {
-                    errors.push(`compiled.schema.json zones "${zone.id}" and "${existingZoneId}" overlap on path "${zone.path}" / "${existingPath}".`);
+                    errors.push(`workflow.schema.json zones "${zone.id}" and "${existingZoneId}" overlap on path "${zone.path}" / "${existingPath}".`);
                 }
             }
             seenPaths.set(zone.path, zone.id);
+            if ((zone.role === "input" || zone.role === "runtime") && zone.owned_by.length > 0) {
+                errors.push(`workflow.schema.json zone "${zone.id}" cannot declare owners because its role is "${zone.role}".`);
+            }
             for (const owner of zone.owned_by) {
                 if (!stageIds.has(owner)) {
-                    errors.push(`compiled.schema.json references unknown stage "${owner}" for zone "${zone.path}".`);
+                    errors.push(`workflow.schema.json references unknown stage "${owner}" for zone "${zone.path}".`);
                 }
             }
         }
@@ -363,19 +379,25 @@ export function validateWorkflowPackage(dirPath) {
                     errors.push(`Stage "${stage.id}" writes unknown zone "${zoneId}".`);
                     continue;
                 }
+                if (zone.role === "input" || zone.role === "runtime") {
+                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but zones with role "${zone.role}" are engine-owned inputs, not writable stage outputs.`);
+                }
                 if (!zone.owned_by.includes(stage.id)) {
-                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but that zone is not owned by the stage in compiled.schema.json.`);
+                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but that zone is not owned by the stage in workflow.schema.json.`);
                 }
             }
         }
         for (const requiredZone of listBuiltinCompiledZoneSpecs().filter((zone) => zone.id === "raw" || zone.id === "runtime")) {
             const match = zoneById.get(requiredZone.id);
             if (!match) {
-                errors.push(`compiled.schema.json is missing required zone "${requiredZone.id}".`);
+                errors.push(`workflow.schema.json is missing required zone "${requiredZone.id}".`);
                 continue;
             }
             if (match.kind !== requiredZone.kind) {
-                errors.push(`compiled.schema.json zone "${requiredZone.id}" should be kind "${requiredZone.kind}".`);
+                errors.push(`workflow.schema.json zone "${requiredZone.id}" should be kind "${requiredZone.kind}".`);
+            }
+            if (match.role !== requiredZone.role) {
+                errors.push(`workflow.schema.json zone "${requiredZone.id}" should have role "${requiredZone.role}".`);
             }
         }
     }
@@ -385,7 +407,8 @@ export function validateWorkflowPackage(dirPath) {
     const counts = {
         starter_docs: collectStarterDocs(dirPath).length,
         compile_stage_docs: stageDirs.length,
-        compiled_zones: compiledSchema?.zones.length ?? 0,
+        compiled_zones: workflowSchema?.zones.length ?? 0,
+        workflow_zones: workflowSchema?.zones.length ?? 0,
     };
     return {
         ok: errors.length === 0,

package/dist/lib/project-paths.d.ts

@@ -1,13 +1,11 @@
 export declare const PROJECT_INTERF_DIR = "interf";
-export declare const PROJECT_WORKFLOW_DIR = "workflows";
-export declare const PROJECT_COMPILED_DIR = "compiled";
 export declare const PROJECT_TESTS_DIR = "tests";
 export declare function projectInterfRoot(projectPath: string): string;
-export declare function projectWorkflowRoot(projectPath: string): string;
-export declare function datasetArtifactRoot(projectPath: string, datasetName: string): string;
 export declare function compiledCompiledPathForDataset(projectPath: string, datasetName: string): string;
 export declare function datasetTestsRoot(projectPath: string, datasetName: string): string;
 export type DatasetTestTargetLabel = "file-as-is" | "compiled";
 export declare function datasetTestRunsRoot(projectPath: string, datasetName: string, target: DatasetTestTargetLabel): string;
 export declare function datasetLatestTestStatePath(projectPath: string, datasetName: string): string;
 export declare function datasetLatestTestSummaryPath(projectPath: string, datasetName: string): string;
+export declare function normalizeDatasetTestRunId(input: string): string;
+export declare function datasetTestRunPath(projectPath: string, datasetName: string, target: DatasetTestTargetLabel, generatedAt: string, runId: string, runSuffix?: string | null): string;

package/dist/lib/project-paths.js

@@ -1,22 +1,14 @@
 import { join } from "node:path";
 export const PROJECT_INTERF_DIR = "interf";
-export const PROJECT_WORKFLOW_DIR = "workflows";
-export const PROJECT_COMPILED_DIR = "compiled";
 export const PROJECT_TESTS_DIR = "tests";
 export function projectInterfRoot(projectPath) {
     return join(projectPath, PROJECT_INTERF_DIR);
 }
-export function projectWorkflowRoot(projectPath) {
-    return join(projectInterfRoot(projectPath), PROJECT_WORKFLOW_DIR);
-}
-export function datasetArtifactRoot(projectPath, datasetName) {
-    return join(projectInterfRoot(projectPath), datasetName);
-}
 export function compiledCompiledPathForDataset(projectPath, datasetName) {
-    return join(datasetArtifactRoot(projectPath, datasetName), PROJECT_COMPILED_DIR);
+    return join(projectInterfRoot(projectPath), datasetName);
 }
 export function datasetTestsRoot(projectPath, datasetName) {
-    return join(datasetArtifactRoot(projectPath, datasetName), PROJECT_TESTS_DIR);
+    return join(projectInterfRoot(projectPath), PROJECT_TESTS_DIR, datasetName);
 }
 export function datasetTestRunsRoot(projectPath, datasetName, target) {
     return join(datasetTestsRoot(projectPath, datasetName), target, "runs");
@@ -27,3 +19,14 @@ export function datasetLatestTestStatePath(projectPath, datasetName) {
 export function datasetLatestTestSummaryPath(projectPath, datasetName) {
     return join(datasetTestsRoot(projectPath, datasetName), "latest.md");
 }
+export function normalizeDatasetTestRunId(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+export function datasetTestRunPath(projectPath, datasetName, target, generatedAt, runId, runSuffix) {
+    return join(datasetTestRunsRoot(projectPath, datasetName, target), `${generatedAt.replace(/[:.]/g, "-")}-${runId}${runSuffix ? `-${normalizeDatasetTestRunId(runSuffix)}` : ""}.json`);
+}

package/dist/lib/runtime-acceptance.js

@@ -2,7 +2,7 @@ import { existsSync, } from "node:fs";
 import { join } from "node:path";
 import { listFilesRecursive } from "./filesystem.js";
 import { readJsonFileWithSchema } from "./parse.js";
-import { compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
+import { WORKFLOW_SCHEMA_FILE, compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
 import { RuntimeStageContractSchema, } from "./schema.js";
 import { stageContractPath } from "./runtime-paths.js";
 import { workflowPackagePathForCompiled } from "./compiled-paths.js";
@@ -24,6 +24,7 @@ function hasAcceptanceRules(acceptance) {
         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;
@@ -106,8 +107,8 @@ export function validateResolvedStageAcceptance(dirPath, options) {
     if (!schema) {
         return {
             ok: false,
-            summary: `Stage acceptance failed for ${options.stageId}: missing compiled schema.`,
-            failures: ["Missing workflow/compiled.schema.json."],
+            summary: `Stage acceptance failed for ${options.stageId}: missing workflow schema.`,
+            failures: [`Missing workflow/${WORKFLOW_SCHEMA_FILE}.`],
         };
     }
     const failures = [];
@@ -190,6 +191,17 @@ export function validateResolvedStageAcceptance(dirPath, options) {
             failures.push(`Zone "${zoneId}" has ${validation.invalid_frontmatter} markdown file(s) with invalid or incomplete frontmatter.`);
         }
     }
+    for (const [zoneId, requiredKeys] of Object.entries(acceptance?.frontmatter_required_keys_in_zones ?? {})) {
+        const zone = findCompiledSchemaZone(schema, zoneId);
+        if (!zone) {
+            failures.push(`Acceptance references unknown zone "${zoneId}".`);
+            continue;
+        }
+        const validation = validateSynthFiles(markdownFilesForZone(dirPath, zone.path, zone.kind), { requiredFrontmatterKeys: requiredKeys });
+        if (validation.invalid_frontmatter > 0) {
+            failures.push(`Zone "${zoneId}" has ${validation.invalid_frontmatter} markdown file(s) missing required frontmatter keys (${requiredKeys.join(", ")}).`);
+        }
+    }
     for (const zoneId of acceptance?.markdown_abstract_valid_zones ?? []) {
         const zone = findCompiledSchemaZone(schema, zoneId);
         if (!zone) {

package/dist/lib/runtime-contracts.js

@@ -1,3 +1,4 @@
+import { WORKFLOW_SCHEMA_FILE } from "./compiled-schema.js";
 export function buildRuntimeStageContract(options) {
     const localSkillDocs = options.localSkillDocs ?? [];
     const workflowNotes = options.workflowNotes ?? [];
@@ -11,7 +12,7 @@ export function buildRuntimeStageContract(options) {
         artifacts: {
             reads: [
                 "interf.json",
-                "workflow/compiled.schema.json",
+                `workflow/${WORKFLOW_SCHEMA_FILE}`,
                 ...(options.extraReadArtifacts ?? []),
                 ...options.stageReadArtifacts,
                 ...localSkillDocs,
@@ -27,7 +28,7 @@ export function buildRuntimeStageContract(options) {
             notes: [
                 `This is the "${options.stageLabel}" stage for the compiled dataset "${options.compiledName}".`,
                 "The workflow package is the authoritative method layer for this run.",
-                "Use `workflow/compiled.schema.json` as the deterministic output-shape reference for this compiled dataset.",
+                `Use \`workflow/${WORKFLOW_SCHEMA_FILE}\` as the deterministic zone-contract reference for this compiled dataset.`,
                 "Honor the declared read and write artifacts instead of inventing a parallel workflow.",
                 "Only create or update files that fall under the declared write targets for this stage.",
                 "The CLI owns `.interf/runtime/` ledgers such as run, state, health, and view-spec files. Read them if needed, but do not create, edit, or replace them in this stage unless the contract explicitly marks a runtime artifact as stage-owned.",

package/dist/lib/runtime-paths.d.ts

@@ -1,6 +1,7 @@
 export declare function runPath(dirPath: string): string;
 export declare function runHistoryPath(dirPath: string): string;
 export declare function stageContractPath(dirPath: string): string;
+export declare function archivedStageContractPath(dirPath: string, runId: string): string;
 export declare function logsDirPath(dirPath: string): string;
 export declare function promptLogPath(dirPath: string, runId: string): string;
 export declare function eventLogPath(dirPath: string, runId: string): string;

package/dist/lib/runtime-paths.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { compiledRuntimeLogsRoot, compiledRuntimeRunHistoryPath, compiledRuntimeRunPath, compiledRuntimeStageContractPath, } from "./compiled-paths.js";
+import { compiledRuntimeArchivedStageContractPath, compiledRuntimeLogsRoot, compiledRuntimeRunHistoryPath, compiledRuntimeRunPath, compiledRuntimeStageContractPath, } from "./compiled-paths.js";
 export function runPath(dirPath) {
     return compiledRuntimeRunPath(dirPath);
 }
@@ -9,6 +9,9 @@ export function runHistoryPath(dirPath) {
 export function stageContractPath(dirPath) {
     return compiledRuntimeStageContractPath(dirPath);
 }
+export function archivedStageContractPath(dirPath, runId) {
+    return compiledRuntimeArchivedStageContractPath(dirPath, runId);
+}
 export function logsDirPath(dirPath) {
     return compiledRuntimeLogsRoot(dirPath);
 }

package/dist/lib/runtime-prompt.js

@@ -1,7 +1,5 @@
 export function buildStagePrompt(instructions, contractPath, statusLines) {
-    const stageSkillDir = instructions.stage_skill_dir ||
-        (instructions.bundled_skill?.split(/[\\/]/).filter(Boolean).pop()) ||
-        "stage";
+    const stageSkillDir = instructions.stage_skill_dir || "stage";
     const modeNotes = instructions.effective_mode === "override"
         ? [
             "Local stage instruction docs are authoritative for this run.",
@@ -27,11 +25,13 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "For file-zone mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
         "Honor the contract's counts, artifact paths, and policies instead of inventing another workflow.",
         "Read only the files named by the contract's `artifacts.reads` list plus any paths they explicitly direct you to open.",
+        "Prefer direct file-reading and search tools over shell commands when you inspect inputs, docs, or generated outputs.",
+        "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` for routine file inspection if a native read/search tool can do the same job.",
         "If the contract lists `instructions.local_docs`, open every one of those files before you write artifacts or declare the stage complete.",
         "If `AGENTS.md` is listed in the contract, use it only for compiled routing that is directly relevant to this stage.",
         "`.interf/runtime/run.json`, `.interf/runtime/state.json`, `.interf/runtime/health.json`, and `.interf/runtime/view-spec.json` are CLI-owned runtime artifacts. You may read them, but do not create, edit, or replace them unless the contract explicitly marks a different proof artifact as stage-owned.",
         "If a contract-listed output file does not exist yet, create it in one whole-file write. Do not attempt patch-style edits against a missing runtime path.",
-        "Stay inside the current compiled dataset. Do not try to open SDK repo docs, SDK source files, or other paths outside the compiled dataset unless the stage contract explicitly requires them.",
+        "Stay inside the current compiled dataset. Do not try to open repo docs, repo source files, or other paths outside the compiled dataset unless the stage contract explicitly requires them.",
         instructions.effective_mode === "override"
             ? "Do not depend on any repo-root or globally installed skill cache for this run. Local stage instruction docs are the primary workflow layer for this run."
             : "Do not depend on any repo-root or globally installed skill cache for this run. Use the current compiled workflow docs and the contract as the default behavior.",