@interf/compiler 0.4.0 → 0.5.0

package/dist/lib/runtime-acceptance.js

@@ -1,23 +1,32 @@
-import { existsSync, readFileSync, } from "node:fs";
+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 { RuntimeStageContractSchema, } from "./schema.js";
-import { warnInterf } from "./logger.js";
 import { stageContractPath } from "./runtime-paths.js";
-function readWorkspaceJsonFile(dirPath, relativePath) {
-    const targetPath = join(dirPath, relativePath);
-    if (!existsSync(targetPath))
-        return null;
-    try {
-        const parsed = JSON.parse(readFileSync(targetPath, "utf8"));
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : null;
-    }
-    catch (error) {
-        warnInterf(`Warning: failed to read workspace JSON at ${targetPath}: ${error instanceof Error ? error.message : String(error)}`);
+import { workflowPackagePathForCompiled } from "./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 ||
+        (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)
@@ -31,92 +40,218 @@ function readPathValue(record, keyPath) {
         return current[segment];
     }, record);
 }
-function toFiniteNumber(value) {
-    if (typeof value !== "number" || !Number.isFinite(value))
+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 value;
+    return safeReadText(artifactPath);
 }
-function hasAcceptanceRules(acceptance) {
-    if (!acceptance)
-        return false;
-    return (acceptance.artifacts_exist?.length ?? 0) > 0 ||
-        (acceptance.state_truthy?.length ?? 0) > 0 ||
-        Object.keys(acceptance.state_equals_counts ?? {}).length > 0 ||
-        Object.keys(acceptance.state_at_least ?? {}).length > 0 ||
-        Object.keys(acceptance.state_at_least_counts ?? {}).length > 0;
+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 validateStageContractAcceptance(dirPath, contract = null) {
-    const resolvedContract = contract ?? (() => {
-        const path = stageContractPath(dirPath);
-        if (!existsSync(path))
-            return null;
-        return readJsonFileWithSchema(path, "stage contract", RuntimeStageContractSchema);
-    })();
-    if (!resolvedContract) {
+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 active stage contract found for acceptance validation.",
+            summary: "No additional stage acceptance criteria were declared.",
             failures: [],
         };
     }
-    const acceptance = resolvedContract.acceptance;
-    if (!hasAcceptanceRules(acceptance)) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    if (!schema) {
         return {
-            ok: true,
-            summary: "No additional stage acceptance criteria were declared.",
-            failures: [],
+            ok: false,
+            summary: `Stage acceptance failed for ${options.stageId}: missing compiled schema.`,
+            failures: ["Missing workflow/compiled.schema.json."],
         };
     }
     const failures = [];
-    const state = readWorkspaceJsonFile(dirPath, ".interf/runtime/state.json");
+    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?.state_truthy ?? []) {
-        if (!readPathValue(state, keyPath)) {
-            failures.push(`Expected truthy state value at "${keyPath}".`);
+    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?.state_equals_counts ?? {})) {
-        const actual = readPathValue(state, keyPath);
-        const expected = resolvedContract.counts[countKey];
+    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 contract count "${countKey}" for "${keyPath}".`);
+            failures.push(`Acceptance references missing count "${countKey}" for "${keyPath}".`);
             continue;
         }
         if (actual !== expected) {
-            failures.push(`Expected state "${keyPath}" to equal count "${countKey}" (${expected}), got ${JSON.stringify(actual)}.`);
+            failures.push(`Expected stage "${keyPath}" to equal count "${countKey}" (${expected}), got ${JSON.stringify(actual)}.`);
         }
     }
-    for (const [keyPath, minimum] of Object.entries(acceptance?.state_at_least ?? {})) {
-        const actual = toFiniteNumber(readPathValue(state, keyPath));
+    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 state "${keyPath}" to be at least ${minimum}, got ${actual === null ? "non-numeric" : actual}.`);
+            failures.push(`Expected stage "${keyPath}" to be at least ${minimum}, got ${actual === null ? "non-numeric" : actual}.`);
         }
     }
-    for (const [keyPath, countKey] of Object.entries(acceptance?.state_at_least_counts ?? {})) {
-        const actual = toFiniteNumber(readPathValue(state, keyPath));
-        const expected = resolvedContract.counts[countKey];
+    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 contract count "${countKey}" for "${keyPath}".`);
+            failures.push(`Acceptance references missing count "${countKey}" for "${keyPath}".`);
             continue;
         }
         if (actual === null || actual < expected) {
-            failures.push(`Expected state "${keyPath}" to be at least count "${countKey}" (${expected}), got ${actual === null ? "non-numeric" : actual}.`);
+            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 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 ${resolvedContract.stage}.`,
+            summary: `Stage acceptance satisfied for ${options.stageId}.`,
             failures: [],
         };
     }
     return {
         ok: false,
-        summary: `Stage acceptance failed for ${resolvedContract.stage}: ${failures.join(" ")}`,
+        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/lib/runtime-contracts.d.ts

@@ -1,4 +1,2 @@
-import { type RuntimeStageContractDraft, type WorkspaceKnowledgeContractOptions, type WorkspaceShapeContractOptions, type WorkspaceSummarizeContractOptions } from "./runtime-types.js";
-export declare function buildWorkspaceSummarizeContract(options: WorkspaceSummarizeContractOptions): RuntimeStageContractDraft;
-export declare function buildWorkspaceStructureContract(options: WorkspaceKnowledgeContractOptions): RuntimeStageContractDraft;
-export declare function buildWorkspaceShapeContract(options: WorkspaceShapeContractOptions): RuntimeStageContractDraft;
+import { type RuntimeStageContractDraft, type RuntimeStageContractOptions } from "./runtime-types.js";
+export declare function buildRuntimeStageContract(options: RuntimeStageContractOptions): RuntimeStageContractDraft;

package/dist/lib/runtime-contracts.js

@@ -1,191 +1,47 @@
-import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-export function buildWorkspaceSummarizeContract(options) {
+export function buildRuntimeStageContract(options) {
     const localSkillDocs = options.localSkillDocs ?? [];
     const workflowNotes = options.workflowNotes ?? [];
     return {
         instructions: options.instructions,
         counts: {
-            target_files: options.targetCount,
-            expected_summary_total: options.expectedSummaryTotal,
+            ...(options.counts ?? {}),
             local_skill_docs: localSkillDocs.length,
         },
         ...(options.acceptance ? { acceptance: options.acceptance } : {}),
         artifacts: {
             reads: [
                 "interf.json",
-                options.planPath,
-                "workflow/workspace.schema.json",
-                ".interf/runtime/raw-snapshot.json",
+                "workflow/compiled.schema.json",
+                ...(options.extraReadArtifacts ?? []),
+                ...options.stageReadArtifacts,
                 ...localSkillDocs,
             ],
-            writes: [
-                "summaries/",
-                ".interf/runtime/inventory.json",
-            ],
-            verifies: [
-                "interf verify summarize --json",
-            ],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                `Process only the files listed in ${options.planPath}.`,
-                `When ${options.planPath} includes \`targets[].output\`, write each summary to that exact relative path instead of inferring a filename.`,
-                `Source files live at ${options.sourcePath}.`,
-                "This is a workspace file-evidence stage only. Do not do broad cross-file synthesis here.",
-                "Write every summary as markdown under `summaries/` with a `.md` filename, even when the source file has another extension. If the source file already ends in `.md`, keep a single `.md` suffix instead of appending another one.",
-                "Use JSON frontmatter wrapped in `---` markers. Do not use YAML frontmatter.",
-                "Every summary must include a non-trivial `abstract` in JSON frontmatter. Do not leave it blank or push the abstract only into body sections.",
-                "Also include a `## Abstract` section or another clearly labeled abstract block so humans can scan the summary quickly.",
-                "Use cautious, source-grounded titles. Summary filenames should describe what the file is or records without overstating uncertain conclusions.",
-                "If links are added, keep them minimal and source-grounded.",
-                "Do not precreate `.interf/runtime/inventory.json` with placeholder writes. Write the final JSON document directly.",
-                "When updating `.interf/runtime/inventory.json`, rewrite the full JSON document in one whole-file write instead of patching partial lines.",
-                "The CLI reconciles `.interf/runtime/state.json` and refreshes `.interf/runtime/health.json` after stage validation. Do not treat those files as stage-owned write targets for this stage.",
-                "Prefer the current inventory runtime shape: `.interf/runtime/inventory.json` should use `entries` plus `total`, with one object per source file containing at least `source`, `summary`, and a conservative status/state field.",
-                "Keep scratch extraction commands single-purpose and non-destructive. Do not use `rm`, wildcard cleanup, `;`, or `&&` chains during summarize.",
-                "Use `workflow/workspace.schema.json` as the deterministic output-shape reference for this workspace.",
-                "The workspace includes its own `raw/` snapshot. Read source files there when summary evidence depends on direct inspection.",
-                ...workflowNotes,
-                ...(localSkillDocs.length > 0
-                    ? [
-                        "Read any local instruction docs listed in the contract before processing source files.",
-                        options.instructions.effective_mode === "override"
-                            ? "Local docs replace the bundled file-evidence workflow for this run, but they still do not bypass per-file evidence capture, required writes, or deterministic runtime reconciliation."
-                            : "Local docs can refine summary structure and file-evidence heuristics, but they do not bypass per-file evidence capture, required proof artifacts, or deterministic runtime reconciliation.",
-                    ]
-                    : []),
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-        },
-    };
-}
-export function buildWorkspaceStructureContract(options) {
-    const localSkillDocs = options.localSkillDocs ?? [];
-    const workflowNotes = options.workflowNotes ?? [];
-    return {
-        instructions: options.instructions,
-        counts: {
-            summary_total: options.summaryCount,
-            local_skill_docs: localSkillDocs.length,
-        },
-        ...(options.acceptance ? { acceptance: options.acceptance } : {}),
-        artifacts: {
-            reads: [
-                "interf.json",
-                "workflow/workspace.schema.json",
-                "summaries/",
-                ".interf/runtime/inventory.json",
-                ...localSkillDocs,
-            ],
-            writes: [
-                "knowledge/entities/",
-                "knowledge/claims/",
-                "knowledge/indexes/",
-            ],
-            verifies: [
-                "interf verify structure --json",
-            ],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                "This is the cross-file knowledge-structure stage. Canonicalize entities, claims, timelines, and retrieval indexes from the summary set.",
-                "Use taxonomy and ontology only as means to improve retrieval, grounding, and navigation.",
-                "Prefer stable entity, claim, and index notes over one giant catch-all document.",
-                "Do not write `home.md` yet unless the contract explicitly lists it as a write target.",
-                "Do not copy expected answers from checks into the knowledge layer.",
-                "Use `workflow/workspace.schema.json` as the deterministic output-shape reference for this workspace.",
-                "Rewrite knowledge artifacts directly instead of doing destructive cleanup passes.",
-                ...workflowNotes,
-                ...(localSkillDocs.length > 0
-                    ? [
-                        "Read any local instruction docs listed in the contract before structuring the knowledge layer.",
-                        options.instructions.effective_mode === "override"
-                            ? "Local docs replace the bundled structure workflow for this run, but they still do not bypass required writes or deterministic runtime reconciliation."
-                            : "Local docs can refine structure heuristics, but they do not bypass required writes or deterministic runtime reconciliation.",
-                    ]
-                    : []),
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.4,
-                strategy: "Read summaries in bounded batches, then canonicalize and relate the cross-file knowledge structure.",
-            },
-        },
-    };
-}
-export function buildWorkspaceShapeContract(options) {
-    const localSkillDocs = options.localSkillDocs ?? [];
-    const workflowNotes = options.workflowNotes ?? [];
-    return {
-        instructions: options.instructions,
-        counts: {
-            summary_total: options.summaryCount,
-            local_skill_docs: localSkillDocs.length,
-        },
-        ...(options.acceptance ? { acceptance: options.acceptance } : {}),
-        artifacts: {
-            reads: [
-                "interf.json",
-                "workflow/workspace.schema.json",
-                options.shapeInputPath,
-                "raw/",
-                "knowledge/entities/",
-                "knowledge/claims/",
-                "knowledge/indexes/",
-                "summaries/",
-                ...localSkillDocs,
-            ],
-            writes: [
-                "home.md",
-                "knowledge/indexes/",
-            ],
+            writes: options.stageWriteArtifacts,
             verifies: [
-                "interf verify compile --json",
+                `interf verify stage ${options.stageId} --json`,
             ],
         },
         policies: {
             execution_mode: "deterministic",
             status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
             notes: [
-                `Use ${options.shapeInputPath} as the shaping input for this workspace.`,
-                "The shaping input provides the workspace focus plus saved truth-check question text only. It does not provide expected answers.",
-                "Use the focus and saved truth checks to bias routing, navigation, priority notes, and the final workspace home.",
-                "Replace any scaffold or placeholder content in `home.md`. The final home note must not keep the initial `Not yet compiled.` message.",
-                "Do not copy expected answers into the workspace or treat the checks as license to hallucinate missing evidence.",
-                "When a focused question depends on chart-derived or table-derived evidence, prefer the saved summaries and structured notes if they already preserve the needed bounded reads plus provenance.",
-                "Use `raw/` during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.",
-                "Carry the final bounded reads forward into focused indexes with clear provenance instead of repeatedly recomputing them from `raw/`.",
-                ...CHART_APPROXIMATION_NOTES,
-                "Use `workflow/workspace.schema.json` as the deterministic output-shape reference for this workspace.",
-                "Prefer better retrieval routes, tighter home.md guidance, and focused indexes over speculative synthesis.",
+                `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.",
+                "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.",
+                "Keep scratch extraction commands single-purpose and non-destructive. Avoid wildcard cleanup and multi-command chains.",
                 ...workflowNotes,
                 ...(localSkillDocs.length > 0
                     ? [
-                        "Read any local instruction docs listed in the contract before shaping the final workspace.",
+                        "Read any local instruction docs listed in the contract before you write artifacts or declare the stage complete.",
                         options.instructions.effective_mode === "override"
-                            ? "Local docs replace the bundled shaping workflow for this run, but they still do not bypass required writes or deterministic runtime reconciliation."
-                            : "Local docs can refine shaping behavior, but they do not bypass required writes or deterministic runtime reconciliation.",
+                            ? "Local stage docs replace the default workflow guidance for this run, but they still do not bypass required writes, declared proof artifacts, or deterministic runtime reconciliation."
+                            : "Local stage docs can refine the stage behavior, but they do not bypass required writes, declared proof artifacts, or deterministic runtime reconciliation.",
                     ]
                     : []),
             ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.3,
-                strategy: "Use the existing knowledge structure plus shaping input to produce the final workspace surface.",
-            },
         },
     };
 }

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

@@ -0,0 +1,7 @@
+import { type CompiledInventory, type CompiledInventoryEntry } from "./schema.js";
+export declare function emptyCompiledInventory(): CompiledInventory;
+export declare function compiledInventoryFromEntries(entries: CompiledInventoryEntry[], stage?: string): CompiledInventory;
+export declare function compiledInventoryEntryCount(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryTotal(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryFrontmatterScannedCount(inventory: CompiledInventory | null): number;
+export declare function compiledInventoryAbstractCoverageCount(inventory: CompiledInventory | null): number;

package/dist/lib/runtime-inventory.js

@@ -0,0 +1,29 @@
+export function emptyCompiledInventory() {
+    return {
+        kind: "compiled-runtime-ledger",
+        version: 1,
+        entries: [],
+        total: 0,
+    };
+}
+export function compiledInventoryFromEntries(entries, stage) {
+    return {
+        kind: "compiled-runtime-ledger",
+        version: 1,
+        ...(stage ? { stage } : {}),
+        entries,
+        total: entries.length,
+    };
+}
+export function compiledInventoryEntryCount(inventory) {
+    return inventory?.entries.length ?? 0;
+}
+export function compiledInventoryTotal(inventory) {
+    return inventory?.total ?? 0;
+}
+export function compiledInventoryFrontmatterScannedCount(inventory) {
+    return (inventory?.entries ?? []).filter((entry) => entry.metadata?.frontmatter_scanned === true).length;
+}
+export function compiledInventoryAbstractCoverageCount(inventory) {
+    return (inventory?.entries ?? []).filter((entry) => entry.metadata?.abstract_read === true || typeof entry.metadata?.abstract === "string").length;
+}

package/dist/lib/runtime-paths.js

@@ -1,16 +1,16 @@
 import { join } from "node:path";
-import { workspaceRuntimeLogsRoot, workspaceRuntimeRunHistoryPath, workspaceRuntimeRunPath, workspaceRuntimeStageContractPath, } from "./workspace-paths.js";
+import { compiledRuntimeLogsRoot, compiledRuntimeRunHistoryPath, compiledRuntimeRunPath, compiledRuntimeStageContractPath, } from "./compiled-paths.js";
 export function runPath(dirPath) {
-    return workspaceRuntimeRunPath(dirPath);
+    return compiledRuntimeRunPath(dirPath);
 }
 export function runHistoryPath(dirPath) {
-    return workspaceRuntimeRunHistoryPath(dirPath);
+    return compiledRuntimeRunHistoryPath(dirPath);
 }
 export function stageContractPath(dirPath) {
-    return workspaceRuntimeStageContractPath(dirPath);
+    return compiledRuntimeStageContractPath(dirPath);
 }
 export function logsDirPath(dirPath) {
-    return workspaceRuntimeLogsRoot(dirPath);
+    return compiledRuntimeLogsRoot(dirPath);
 }
 export function promptLogPath(dirPath, runId) {
     return join(logsDirPath(dirPath), `${runId}.prompt.txt`);

package/dist/lib/runtime-prompt.js

@@ -1,4 +1,7 @@
 export function buildStagePrompt(instructions, contractPath, statusLines) {
+    const stageSkillDir = instructions.stage_skill_dir ||
+        (instructions.bundled_skill?.split(/[\\/]/).filter(Boolean).pop()) ||
+        "stage";
     const modeNotes = instructions.effective_mode === "override"
         ? [
             "Local stage instruction docs are authoritative for this run.",
@@ -7,14 +10,14 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         ]
         : instructions.effective_mode === "extend"
             ? [
-                "Use the current workspace workflow docs as the default workflow for this run.",
+                "Use the current compiled workflow docs as the default workflow for this run.",
                 "Then apply any additional local stage instruction docs referenced by the contract as stage-specific extensions.",
             ]
             : [
-                "Use the current workspace workflow docs as the default workflow for this run.",
+                "Use the current compiled workflow docs as the default workflow for this run.",
             ];
     return [
-        `Interf built-in stage id: ${instructions.bundled_skill}`,
+        `Interf workflow stage docs: workflow/compile/stages/${stageSkillDir}/`,
         "",
         "This is an automated Interf stage run, not an open-ended chat session.",
         "The user has already invoked this stage through the Interf CLI. Execute it now.",
@@ -25,13 +28,13 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "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.",
         "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 workspace routing that is directly relevant to this stage.",
+        "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 workspace. Do not try to open SDK repo docs, SDK source files, or other paths outside the workspace unless the stage contract explicitly requires them.",
+        "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.",
         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 workspace workflow docs and the contract as the default behavior.",
+            : "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.",
         ...modeNotes,
         "Do not narrate intentions, plans, or reasoning to the user.",
         "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",