@interf/compiler 0.5.1 → 0.6.3

package/dist/packages/compiler/lib/schema.js

@@ -0,0 +1,361 @@
+import { z } from "zod";
+import { COMPILED_ZONE_KINDS, } from "../workflow-primitives.js";
+const JsonRecordSchema = z.record(z.string(), z.unknown());
+const COMPILED_RELATIVE_PATH_SEGMENT = /^(?!\.{1,2}$)[^/\\]+$/;
+function isCompiledRelativePath(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith("/") || value.startsWith("\\"))
+        return false;
+    return value
+        .split(/[\\/]+/)
+        .every((segment) => COMPILED_RELATIVE_PATH_SEGMENT.test(segment));
+}
+export const RuntimeTargetTypeSchema = z.enum(["compiled"]);
+export const TestTargetTypeSchema = z.enum(["compiled", "raw"]);
+export const WorkflowIdPattern = /^[a-z0-9][a-z0-9-]{0,79}$/;
+export const RuntimeStageSchema = z.string().regex(WorkflowIdPattern);
+export const RuntimeContractTypeSchema = z.string().regex(WorkflowIdPattern);
+export const WorkflowIdSchema = z.string().regex(WorkflowIdPattern);
+export const WorkflowZoneIdSchema = z.string().regex(WorkflowIdPattern);
+export const WorkflowCompiledZoneKindSchema = z.enum(COMPILED_ZONE_KINDS);
+export const WorkflowZoneRoleSchema = z.enum(["input", "working", "output", "runtime"]);
+export const CompiledStageStatusSchema = z.enum(["idle", "running", "succeeded", "failed"]);
+export const SourceCompiledMaxAttemptsSchema = z.number().int().min(1).max(5);
+export const SourceCompiledMaxLoopsSchema = z.number().int().min(1).max(3);
+export const CompiledStageStateSchema = z.object({
+    contract_type: RuntimeContractTypeSchema.optional(),
+    status: CompiledStageStatusSchema.optional(),
+    started_at: z.string().nullable().optional(),
+    finished_at: z.string().nullable().optional(),
+    counts: z.record(z.string(), z.number()).optional(),
+    zone_counts: z.record(z.string(), z.number()).optional(),
+    artifacts: z.array(z.string()).optional(),
+    summary: z.string().nullable().optional(),
+    run_id: z.string().nullable().optional(),
+});
+export const CompiledStateSchema = z.object({
+    version: z.number().int().min(1),
+    pending: z.array(z.string()),
+    stages: z.record(z.string().regex(WorkflowIdPattern), CompiledStageStateSchema).optional(),
+    last_add: z.string().nullable().optional(),
+    last_compile: z.string().nullable().optional(),
+    warning_count: z.number().optional(),
+    error_count: z.number().optional(),
+}).strict();
+export const ViewSectionSchema = z.object({
+    id: z.string(),
+    type: z.enum(["status", "cards", "graph", "documents", "table"]),
+    title: z.string(),
+    path: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+});
+export const ViewCardSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    metric: z.string(),
+    denominator_metric: z.string().optional(),
+    format: z.enum(["number", "fraction", "timestamp"]),
+});
+export const CompiledHealthSchema = z.object({
+    kind: z.literal("compiled-health"),
+    version: z.number().int().min(1),
+    generated_at: z.string(),
+    target_name: z.string(),
+    status: z.enum(["idle", "running", "compiled", "stale", "failed"]),
+    stage: z.union([
+        z.enum(["idle", "compiled", "failed"]),
+        RuntimeStageSchema,
+    ]),
+    summary: z.string(),
+    metrics: z.record(z.string(), z.number()),
+    checks: z.record(z.string(), z.boolean()),
+});
+export const CompiledViewSpecSchema = z.object({
+    kind: z.literal("compiled-view-spec"),
+    version: z.number().int().min(1),
+    generated_at: z.string(),
+    target_name: z.string(),
+    health_source: z.string(),
+    state_source: z.string(),
+    default_note: z.string().nullable(),
+    graph_scope: z.array(z.string()),
+    cards: z.array(ViewCardSchema),
+    sections: z.array(ViewSectionSchema),
+});
+export const CompiledRawSnapshotSchema = z.object({
+    kind: z.literal("compiled-raw-snapshot"),
+    version: z.literal(1),
+    generated_at: z.string(),
+    target_name: z.string(),
+    source_root: z.string(),
+    raw_root: z.string(),
+    source_total: z.number(),
+    sample_files: z.array(z.string()),
+});
+export const WorkflowPurposeSchema = z.object({
+    label: z.string().min(1),
+    task_hint: z.string().min(1),
+}).strict();
+export const WorkflowZoneSchema = z.object({
+    id: WorkflowZoneIdSchema,
+    role: WorkflowZoneRoleSchema,
+    path: z.string().min(1).refine(isCompiledRelativePath, {
+        message: "Zone paths must stay inside the compiled root",
+    }),
+    kind: WorkflowCompiledZoneKindSchema,
+    required: z.boolean(),
+    owned_by: z.array(z.string().regex(WorkflowIdPattern)),
+    description: z.string().min(1),
+});
+export const WorkflowCompiledZoneSchema = WorkflowZoneSchema;
+export const WorkflowSchemaSchema = z.object({
+    kind: z.literal("workflow-schema"),
+    version: z.literal(1),
+    target_type: z.literal("compiled"),
+    label: z.string().min(1),
+    zones: z.array(WorkflowZoneSchema).min(1),
+});
+export const WorkflowCompiledSchemaSchema = WorkflowSchemaSchema;
+export const WorkflowCompilerApiSchema = z.object({
+    kind: z.literal("compiled"),
+    version: z.literal(1),
+});
+export const WorkflowStageZoneAccessSchema = z.array(WorkflowZoneIdSchema).min(1);
+export const ExecutionShellZoneMountSchema = z.object({
+    zone_id: WorkflowZoneIdSchema,
+    compiled_path: z.string(),
+    shell_root_path: z.string(),
+    input_mount_path: z.string().nullable(),
+    output_mount_path: z.string().nullable(),
+});
+export const ExecutionShellPathsSchema = z.object({
+    kind: z.literal("interf-execution-shell"),
+    version: z.literal(1),
+    workflow: WorkflowIdSchema,
+    stage: RuntimeStageSchema,
+    reads: z.array(ExecutionShellZoneMountSchema),
+    writes: z.array(ExecutionShellZoneMountSchema),
+});
+export const RuntimeExecutorInfoSchema = z.object({
+    kind: z.enum(["local-agent", "connected-provider", "managed"]),
+    name: z.string(),
+    display_name: z.string(),
+    command: z.string().nullable(),
+    model: z.string().nullable().optional(),
+    effort: z.string().nullable().optional(),
+    profile: z.string().nullable().optional(),
+    timeout_ms: z.number().nullable().optional(),
+});
+export const RuntimeStageInstructionsSchema = z.object({
+    stage_skill_dir: z.string().regex(WorkflowIdPattern),
+    effective_mode: z.enum(["builtin", "extend", "override"]),
+    local_mode: z.enum(["extend", "override"]).nullable(),
+    local_docs: z.array(z.string()),
+    mode_sources: z.array(z.string()),
+}).strict();
+export const RuntimeStageAcceptanceSchema = z.object({
+    artifacts_exist: z.array(z.string()).optional(),
+    stage_truthy: z.array(z.string()).optional(),
+    stage_equals_counts: z.record(z.string(), z.string()).optional(),
+    stage_at_least: z.record(z.string(), z.number()).optional(),
+    stage_at_least_counts: z.record(z.string(), z.string()).optional(),
+    zone_counts_at_least: z.record(z.string().regex(WorkflowIdPattern), z.number()).optional(),
+    zone_counts_at_least_counts: z.record(z.string().regex(WorkflowIdPattern), z.string()).optional(),
+    markdown_frontmatter_valid_zones: z.array(WorkflowZoneIdSchema).optional(),
+    frontmatter_required_keys_in_zones: z.record(WorkflowZoneIdSchema, z.array(z.string().min(1)).min(1)).optional(),
+    markdown_abstract_valid_zones: z.array(WorkflowZoneIdSchema).optional(),
+    wikilinks_valid_in_zones: z.array(WorkflowZoneIdSchema).optional(),
+    artifacts_must_not_contain: z.record(z.string(), z.array(z.string().min(1))).optional(),
+}).strict();
+export const RuntimeStageContractSchema = z.object({
+    kind: z.literal("interf-stage-contract"),
+    version: z.literal(1),
+    generated_at: z.string(),
+    run_id: z.string(),
+    target_type: RuntimeTargetTypeSchema,
+    target_name: z.string(),
+    workflow: z.object({
+        id: WorkflowIdSchema,
+        stage_index: z.number().nullable(),
+        stage_total: z.number(),
+        stages: z.array(RuntimeStageSchema),
+    }),
+    stage: RuntimeStageSchema,
+    stage_label: z.string(),
+    contract_type: RuntimeContractTypeSchema,
+    executor: RuntimeExecutorInfoSchema,
+    instructions: RuntimeStageInstructionsSchema,
+    counts: z.record(z.string(), z.number()),
+    acceptance: RuntimeStageAcceptanceSchema.optional(),
+    artifacts: z.object({
+        reads: z.array(z.string()),
+        writes: z.array(z.string()),
+        verifies: z.array(z.string()).optional(),
+    }),
+    policies: z.object({
+        execution_mode: z.literal("deterministic"),
+        status_prefixes: z.array(z.string()),
+        notes: z.array(z.string()),
+        evidence_weighting: z.object({
+            required_fields: z.array(z.string()),
+            preserve_tiers: z.boolean(),
+        }).optional(),
+        working_set: z.object({
+            target_context_fraction: z.number(),
+            strategy: z.string(),
+        }).optional(),
+    }),
+});
+export const RuntimeRunSchema = z.object({
+    kind: z.literal("interf-run"),
+    version: z.literal(1),
+    run_id: z.string(),
+    target_type: RuntimeTargetTypeSchema,
+    target_name: z.string(),
+    workflow: WorkflowIdSchema,
+    stage: RuntimeStageSchema,
+    stage_label: z.string(),
+    contract_type: RuntimeContractTypeSchema,
+    status: z.enum(["running", "succeeded", "failed"]),
+    executor: RuntimeExecutorInfoSchema,
+    started_at: z.string(),
+    updated_at: z.string(),
+    finished_at: z.string().nullable(),
+    contract_path: z.string(),
+    execution_path: z.string().optional(),
+    counts: z.record(z.string(), z.number()),
+    output_artifacts: z.array(z.string()),
+    logs: z.object({
+        prompt_path: z.string(),
+        event_stream_path: z.string(),
+        status_path: z.string().optional(),
+    }).optional(),
+    summary: z.string(),
+    exit_code: z.number().nullable(),
+    error: z.string().nullable(),
+});
+export const CompiledInventoryEntrySchema = z.object({
+    input_zone: WorkflowZoneIdSchema.optional(),
+    input_path: z.string().min(1).optional(),
+    output_zone: WorkflowZoneIdSchema,
+    output_path: z.string().min(1),
+    state: z.string().min(1).optional(),
+    metadata: JsonRecordSchema.optional(),
+}).strict();
+export const CompiledInventorySchema = z.object({
+    kind: z.literal("compiled-runtime-ledger").optional(),
+    version: z.number().int().min(1).optional(),
+    stage: RuntimeStageSchema.optional(),
+    entries: z.array(CompiledInventoryEntrySchema),
+    total: z.number().int().nonnegative(),
+});
+export const TestCaseExpectSchema = z.object({
+    must_include: z.array(z.string().min(1)).optional(),
+    must_include_one_of: z.array(z.array(z.string().min(1)).min(1)).optional(),
+    must_not_include: z.array(z.string().min(1)).optional(),
+    min_words: z.number().int().nonnegative().optional(),
+    max_words: z.number().int().nonnegative().optional(),
+}).refine((value) => value.min_words === undefined ||
+    value.max_words === undefined ||
+    value.max_words >= value.min_words, {
+    message: "max_words must be greater than or equal to min_words",
+}).refine((value) => (value.must_include?.length ?? 0) > 0 ||
+    (value.must_include_one_of?.length ?? 0) > 0 ||
+    (value.must_not_include?.length ?? 0) > 0 ||
+    value.min_words !== undefined ||
+    value.max_words !== undefined, {
+    message: "Test expectations must include at least one check",
+});
+export const WorkflowImprovementLoopSummarySchema = z.object({
+    variation: z.number().int().min(1),
+    kind: z.enum(["baseline", "edited"]),
+    attempts_run: z.number().int().min(1),
+    passed: z.boolean(),
+    passed_questions: z.number().int().min(0),
+    total_questions: z.number().int().min(0),
+    failed_stage: z.string().nullable().optional(),
+    test_run_path: z.string().nullable().optional(),
+    test_sandbox_path: z.string().nullable().optional(),
+    summary: z.string().min(1),
+});
+export const WorkflowImprovementContextSchema = z.object({
+    kind: z.literal("interf-workflow-improvement-loop"),
+    version: z.literal(1),
+    generated_at: z.string(),
+    target_name: z.string(),
+    workflow_id: WorkflowIdSchema,
+    loop_index: z.number().int().min(1),
+    max_loops: SourceCompiledMaxLoopsSchema,
+    max_attempts: SourceCompiledMaxAttemptsSchema,
+    review_paths: z.object({
+        workflow_root: z.string(),
+        compiled_runtime: z.string().nullable(),
+        test_comparisons: z.string().nullable(),
+        execution_shells: z.string().nullable(),
+        test_runs: z.string().nullable(),
+        test_sandboxes: z.string().nullable(),
+    }),
+    truth_checks: z.object({
+        count: z.number().int().min(0),
+        questions: z.array(z.object({
+            id: z.string(),
+            question: z.string(),
+        })),
+    }),
+    previous_variations: z.array(WorkflowImprovementLoopSummarySchema),
+    latest_failure: WorkflowImprovementLoopSummarySchema.nullable(),
+});
+export const PreservedShellTypeSchema = z.enum([
+    "stage-execution",
+    "workflow-improvement",
+]);
+export const PreservedShellSnapshotSchema = z.object({
+    kind: z.literal("interf-preserved-shell"),
+    version: z.literal(1),
+    shell_type: PreservedShellTypeSchema,
+    generated_at: z.string(),
+    root_path: z.string(),
+    materialized_symlinks: z.number().int().min(0),
+});
+export const WorkflowPackageValidationSchema = z.object({
+    ok: z.boolean(),
+    summary: z.string(),
+    errors: z.array(z.string()),
+    counts: z.record(z.string(), z.number()),
+});
+export const WorkflowImprovementLoopRecordSchema = z.object({
+    kind: z.literal("interf-workflow-improvement-loop-record"),
+    version: z.literal(1),
+    recorded_at: z.string(),
+    run_id: z.string(),
+    loop_index: z.number().int().min(1),
+    target_name: z.string(),
+    workflow_id: WorkflowIdSchema,
+    result: z.enum(["updated", "no-change", "invalid", "executor-failed"]),
+    changed: z.boolean(),
+    applied: z.boolean(),
+    summary: z.string(),
+    shell_path: z.string(),
+    loop_root_path: z.string(),
+    context_path: z.string(),
+    workflow_before_path: z.string(),
+    workflow_after_path: z.string(),
+    prompt_log_path: z.string(),
+    event_log_path: z.string(),
+    status_log_path: z.string(),
+    preserved_shell_manifest_path: z.string().nullable(),
+    validation: WorkflowPackageValidationSchema.nullable(),
+});
+export const WorkflowImprovementRunLedgerSchema = z.object({
+    kind: z.literal("interf-workflow-improvement-run"),
+    version: z.literal(1),
+    generated_at: z.string(),
+    updated_at: z.string(),
+    run_id: z.string(),
+    target_name: z.string(),
+    workflow_id: WorkflowIdSchema,
+    max_loops: SourceCompiledMaxLoopsSchema,
+    max_attempts: SourceCompiledMaxAttemptsSchema,
+    loops: z.array(WorkflowImprovementLoopRecordSchema),
+});

package/dist/packages/compiler/runtime-acceptance.d.ts

@@ -0,0 +1,9 @@
+import { type CompiledState, type RuntimeStageAcceptance, type RuntimeStageContract } from "./lib/schema.js";
+import { type RuntimeStageAcceptanceValidation } from "./runtime-types.js";
+export declare function stageRecordFromState(state: CompiledState | null, stageId: string): Record<string, unknown> | null;
+export declare function validateResolvedStageAcceptance(dirPath: string, options: {
+    stageId: string;
+    acceptance?: RuntimeStageAcceptance;
+    counts?: Record<string, number>;
+}): RuntimeStageAcceptanceValidation;
+export declare function validateStageContractAcceptance(dirPath: string, contract?: RuntimeStageContract | null): RuntimeStageAcceptanceValidation;

package/dist/packages/compiler/runtime-acceptance.js

@@ -0,0 +1,269 @@
+import { existsSync, } from "node:fs";
+import { join } from "node:path";
+import { listFilesRecursive } from "../../lib/filesystem.js";
+import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { WORKFLOW_SCHEMA_FILE, compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
+import { RuntimeStageContractSchema, } from "./lib/schema.js";
+import { stageContractPath } from "./runtime-paths.js";
+import { workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { loadState } from "./state-io.js";
+import { countBrokenWikilinks, isOutputMarkdownFile, safeReadText, validateSynthFiles } from "./validate.js";
+function toFiniteNumber(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return value;
+}
+function hasAcceptanceRules(acceptance) {
+    if (!acceptance)
+        return false;
+    return (acceptance.artifacts_exist?.length ?? 0) > 0 ||
+        (acceptance.stage_truthy?.length ?? 0) > 0 ||
+        Object.keys(acceptance.stage_equals_counts ?? {}).length > 0 ||
+        Object.keys(acceptance.stage_at_least ?? {}).length > 0 ||
+        Object.keys(acceptance.stage_at_least_counts ?? {}).length > 0 ||
+        Object.keys(acceptance.zone_counts_at_least ?? {}).length > 0 ||
+        Object.keys(acceptance.zone_counts_at_least_counts ?? {}).length > 0 ||
+        (acceptance.markdown_frontmatter_valid_zones?.length ?? 0) > 0 ||
+        Object.keys(acceptance.frontmatter_required_keys_in_zones ?? {}).length > 0 ||
+        (acceptance.markdown_abstract_valid_zones?.length ?? 0) > 0 ||
+        (acceptance.wikilinks_valid_in_zones?.length ?? 0) > 0 ||
+        Object.keys(acceptance.artifacts_must_not_contain ?? {}).length > 0;
+}
+function readPathValue(record, keyPath) {
+    if (!record)
+        return undefined;
+    return keyPath
+        .split(".")
+        .filter((segment) => segment.length > 0)
+        .reduce((current, segment) => {
+        if (!current || typeof current !== "object" || Array.isArray(current))
+            return undefined;
+        return current[segment];
+    }, record);
+}
+function countZoneArtifacts(compiledPath, zonePath, kind) {
+    const absolutePath = compiledZoneAbsolutePath(compiledPath, { path: zonePath });
+    if (!existsSync(absolutePath))
+        return 0;
+    if (kind === "file")
+        return 1;
+    return listFilesRecursive(absolutePath).length;
+}
+function markdownFilesForZone(compiledPath, zonePath, kind) {
+    const absolutePath = compiledZoneAbsolutePath(compiledPath, { path: zonePath });
+    if (!existsSync(absolutePath))
+        return [];
+    if (kind === "file") {
+        return isOutputMarkdownFile(absolutePath) ? [absolutePath] : [];
+    }
+    return listFilesRecursive(absolutePath, isOutputMarkdownFile);
+}
+function zoneRoots(compiledPath, acceptanceZones) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema)
+        return [];
+    return acceptanceZones
+        .map((zoneId) => findCompiledSchemaZone(schema, zoneId))
+        .filter((zone) => zone !== null)
+        .map((zone) => compiledZoneAbsolutePath(compiledPath, zone));
+}
+function readArtifactText(compiledPath, relativePath) {
+    const artifactPath = join(compiledPath, relativePath);
+    if (!existsSync(artifactPath))
+        return null;
+    return safeReadText(artifactPath);
+}
+function resolveStageCounts(contract, stageRecord) {
+    const merged = { ...contract.counts };
+    const fromStage = stageRecord?.counts;
+    if (fromStage && typeof fromStage === "object" && !Array.isArray(fromStage)) {
+        for (const [key, value] of Object.entries(fromStage)) {
+            const numeric = toFiniteNumber(value);
+            if (numeric !== null)
+                merged[key] = numeric;
+        }
+    }
+    return merged;
+}
+export function stageRecordFromState(state, stageId) {
+    const stages = state?.stages;
+    if (!stages || typeof stages !== "object")
+        return null;
+    const stage = stages[stageId];
+    if (!stage || typeof stage !== "object" || Array.isArray(stage))
+        return null;
+    return stage;
+}
+export function validateResolvedStageAcceptance(dirPath, options) {
+    const acceptance = options.acceptance;
+    if (!hasAcceptanceRules(acceptance)) {
+        return {
+            ok: true,
+            summary: "No additional stage acceptance criteria were declared.",
+            failures: [],
+        };
+    }
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    if (!schema) {
+        return {
+            ok: false,
+            summary: `Stage acceptance failed for ${options.stageId}: missing workflow schema.`,
+            failures: [`Missing workflow/${WORKFLOW_SCHEMA_FILE}.`],
+        };
+    }
+    const failures = [];
+    const state = loadState(dirPath);
+    const stageRecord = stageRecordFromState(state, options.stageId);
+    const counts = options.counts ?? {};
+    for (const relativePath of acceptance?.artifacts_exist ?? []) {
+        if (!existsSync(join(dirPath, relativePath))) {
+            failures.push(`Missing required artifact: ${relativePath}.`);
+        }
+    }
+    for (const keyPath of acceptance?.stage_truthy ?? []) {
+        if (!readPathValue(stageRecord, keyPath)) {
+            failures.push(`Expected truthy stage value at "${keyPath}".`);
+        }
+    }
+    for (const [keyPath, countKey] of Object.entries(acceptance?.stage_equals_counts ?? {})) {
+        const actual = readPathValue(stageRecord, keyPath);
+        const expected = counts[countKey];
+        if (typeof expected !== "number") {
+            failures.push(`Acceptance references missing count "${countKey}" for "${keyPath}".`);
+            continue;
+        }
+        if (actual !== expected) {
+            failures.push(`Expected stage "${keyPath}" to equal count "${countKey}" (${expected}), got ${JSON.stringify(actual)}.`);
+        }
+    }
+    for (const [keyPath, minimum] of Object.entries(acceptance?.stage_at_least ?? {})) {
+        const actual = toFiniteNumber(readPathValue(stageRecord, keyPath));
+        if (actual === null || actual < minimum) {
+            failures.push(`Expected stage "${keyPath}" to be at least ${minimum}, got ${actual === null ? "non-numeric" : actual}.`);
+        }
+    }
+    for (const [keyPath, countKey] of Object.entries(acceptance?.stage_at_least_counts ?? {})) {
+        const actual = toFiniteNumber(readPathValue(stageRecord, keyPath));
+        const expected = counts[countKey];
+        if (typeof expected !== "number") {
+            failures.push(`Acceptance references missing count "${countKey}" for "${keyPath}".`);
+            continue;
+        }
+        if (actual === null || actual < expected) {
+            failures.push(`Expected stage "${keyPath}" to be at least count "${countKey}" (${expected}), got ${actual === null ? "non-numeric" : actual}.`);
+        }
+    }
+    for (const [zoneId, minimum] of Object.entries(acceptance?.zone_counts_at_least ?? {})) {
+        const zone = findCompiledSchemaZone(schema, zoneId);
+        if (!zone) {
+            failures.push(`Acceptance references unknown zone "${zoneId}".`);
+            continue;
+        }
+        const actual = countZoneArtifacts(dirPath, zone.path, zone.kind);
+        if (actual < minimum) {
+            failures.push(`Expected zone "${zoneId}" to contain at least ${minimum} artifact(s), got ${actual}.`);
+        }
+    }
+    for (const [zoneId, countKey] of Object.entries(acceptance?.zone_counts_at_least_counts ?? {})) {
+        const zone = findCompiledSchemaZone(schema, zoneId);
+        if (!zone) {
+            failures.push(`Acceptance references unknown zone "${zoneId}".`);
+            continue;
+        }
+        const expected = counts[countKey];
+        if (typeof expected !== "number") {
+            failures.push(`Acceptance references missing count "${countKey}" for zone "${zoneId}".`);
+            continue;
+        }
+        const actual = countZoneArtifacts(dirPath, zone.path, zone.kind);
+        if (actual < expected) {
+            failures.push(`Expected zone "${zoneId}" to contain at least count "${countKey}" (${expected}) artifact(s), got ${actual}.`);
+        }
+    }
+    for (const zoneId of acceptance?.markdown_frontmatter_valid_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));
+        if (validation.invalid_frontmatter > 0) {
+            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) {
+            failures.push(`Acceptance references unknown zone "${zoneId}".`);
+            continue;
+        }
+        const validation = validateSynthFiles(markdownFilesForZone(dirPath, zone.path, zone.kind));
+        if (validation.short_abstracts > 0) {
+            failures.push(`Zone "${zoneId}" has ${validation.short_abstracts} markdown file(s) with missing or weak abstracts.`);
+        }
+    }
+    if ((acceptance?.wikilinks_valid_in_zones?.length ?? 0) > 0) {
+        const roots = zoneRoots(dirPath, acceptance?.wikilinks_valid_in_zones ?? []);
+        const brokenLinks = countBrokenWikilinks(dirPath, roots, roots);
+        if (brokenLinks > 0) {
+            failures.push(`Detected ${brokenLinks} broken wikilink(s) across the declared acceptance zones.`);
+        }
+    }
+    for (const [relativePath, disallowedTexts] of Object.entries(acceptance?.artifacts_must_not_contain ?? {})) {
+        const content = readArtifactText(dirPath, relativePath);
+        if (content === null) {
+            failures.push(`Missing artifact required for content check: ${relativePath}.`);
+            continue;
+        }
+        for (const disallowed of disallowedTexts) {
+            if (content.includes(disallowed)) {
+                failures.push(`Artifact "${relativePath}" still contains forbidden text: ${JSON.stringify(disallowed)}.`);
+            }
+        }
+    }
+    if (failures.length === 0) {
+        return {
+            ok: true,
+            summary: `Stage acceptance satisfied for ${options.stageId}.`,
+            failures: [],
+        };
+    }
+    return {
+        ok: false,
+        summary: `Stage acceptance failed for ${options.stageId}: ${failures.join(" ")}`,
+        failures,
+    };
+}
+export function validateStageContractAcceptance(dirPath, contract = null) {
+    const resolvedContract = contract ?? (() => {
+        const path = stageContractPath(dirPath);
+        if (!existsSync(path))
+            return null;
+        return readJsonFileWithSchema(path, "stage contract", RuntimeStageContractSchema);
+    })();
+    if (!resolvedContract) {
+        return {
+            ok: true,
+            summary: "No active stage contract found for acceptance validation.",
+            failures: [],
+        };
+    }
+    const state = loadState(dirPath);
+    const stageRecord = stageRecordFromState(state, resolvedContract.stage);
+    return validateResolvedStageAcceptance(dirPath, {
+        stageId: resolvedContract.stage,
+        acceptance: resolvedContract.acceptance,
+        counts: resolveStageCounts(resolvedContract, stageRecord),
+    });
+}

package/dist/packages/compiler/runtime-contracts.d.ts

@@ -0,0 +1,2 @@
+import { type RuntimeStageContractDraft, type RuntimeStageContractOptions } from "./runtime-types.js";
+export declare function buildRuntimeStageContract(options: RuntimeStageContractOptions): RuntimeStageContractDraft;