@interf/compiler 0.4.1 → 0.5.1

package/dist/lib/{workflow-abi.d.ts → builtin-compiled-workflow.d.ts}

@@ -1,28 +1,27 @@
-export declare const WORKSPACE_CONTRACT_TYPES: readonly ["workspace-file-evidence", "workspace-knowledge-structure", "workspace-query-shape"];
-export type WorkspaceContractType = typeof WORKSPACE_CONTRACT_TYPES[number];
-export declare const WORKSPACE_ZONE_KINDS: readonly ["directory", "file", "runtime"];
-export type WorkspaceZoneKind = typeof WORKSPACE_ZONE_KINDS[number];
-export declare const WORKSPACE_CONTRACT_FAMILY_METADATA: {
-    readonly "workspace-file-evidence": {
+import { COMPILED_ZONE_KINDS, type CompiledZoneKind } from "./workflow-primitives.js";
+export declare const COMPILED_CONTRACT_TYPES: readonly ["compiled-file-evidence", "compiled-knowledge-structure", "compiled-query-shape"];
+export type CompiledContractType = typeof COMPILED_CONTRACT_TYPES[number];
+export declare const COMPILED_CONTRACT_FAMILY_METADATA: {
+    readonly "compiled-file-evidence": {
         readonly order: 0;
         readonly bundledSkill: "compile/stages/summarize";
     };
-    readonly "workspace-knowledge-structure": {
+    readonly "compiled-knowledge-structure": {
         readonly order: 1;
         readonly bundledSkill: "compile/stages/structure";
     };
-    readonly "workspace-query-shape": {
+    readonly "compiled-query-shape": {
         readonly order: 2;
         readonly bundledSkill: "compile/stages/shape";
     };
 };
-export declare const BUILTIN_WORKSPACE_STAGE_IDS: {
+export declare const BUILTIN_COMPILED_STAGE_IDS: {
     readonly SUMMARIZE: "summarize";
     readonly STRUCTURE: "structure";
     readonly SHAPE: "shape";
 };
-export type BuiltinWorkspaceStageId = typeof BUILTIN_WORKSPACE_STAGE_IDS[keyof typeof BUILTIN_WORKSPACE_STAGE_IDS];
-export declare const BUILTIN_WORKSPACE_ZONE_IDS: {
+export type BuiltinCompiledStageId = typeof BUILTIN_COMPILED_STAGE_IDS[keyof typeof BUILTIN_COMPILED_STAGE_IDS];
+export declare const BUILTIN_COMPILED_ZONE_IDS: {
     readonly RAW: "raw";
     readonly SUMMARIES: "summaries";
     readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
@@ -31,20 +30,20 @@ export declare const BUILTIN_WORKSPACE_ZONE_IDS: {
     readonly HOME: "home";
     readonly RUNTIME: "runtime";
 };
-export type BuiltinWorkspaceZoneId = typeof BUILTIN_WORKSPACE_ZONE_IDS[keyof typeof BUILTIN_WORKSPACE_ZONE_IDS];
-export interface BuiltinWorkspaceZoneSpec {
-    id: BuiltinWorkspaceZoneId;
+export type BuiltinCompiledZoneId = typeof BUILTIN_COMPILED_ZONE_IDS[keyof typeof BUILTIN_COMPILED_ZONE_IDS];
+export interface BuiltinCompiledZoneSpec {
+    id: BuiltinCompiledZoneId;
     path: string;
-    kind: WorkspaceZoneKind;
+    kind: CompiledZoneKind;
     required: true;
     description: string;
 }
-export declare const BUILTIN_WORKSPACE_ZONE_SPECS: readonly [{
+export declare const BUILTIN_COMPILED_ZONE_SPECS: readonly [{
     readonly id: "raw";
     readonly path: "raw";
     readonly kind: "directory";
     readonly required: true;
-    readonly description: "Workspace-local raw snapshot copied from the dataset for direct evidence and verification.";
+    readonly description: "Compiled-local raw snapshot copied from the dataset for direct evidence and verification.";
 }, {
     readonly id: "summaries";
     readonly path: "summaries";
@@ -74,7 +73,7 @@ export declare const BUILTIN_WORKSPACE_ZONE_SPECS: readonly [{
     readonly path: "home.md";
     readonly kind: "file";
     readonly required: true;
-    readonly description: "Primary entrypoint note for agents using the compiled workspace.";
+    readonly description: "Primary entrypoint note for agents using the compiled dataset.";
 }, {
     readonly id: "runtime";
     readonly path: ".interf/runtime";
@@ -82,20 +81,20 @@ export declare const BUILTIN_WORKSPACE_ZONE_SPECS: readonly [{
     readonly required: true;
     readonly description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.";
 }];
-export interface BuiltinWorkspaceStageAccessPattern {
-    id: BuiltinWorkspaceStageId;
+export interface BuiltinCompiledStageAccessPattern {
+    id: BuiltinCompiledStageId;
     label: string;
     description: string;
-    contractType: WorkspaceContractType;
+    contractType: CompiledContractType;
     skillDir: string;
-    reads: readonly BuiltinWorkspaceZoneId[];
-    writes: readonly BuiltinWorkspaceZoneId[];
+    reads: readonly BuiltinCompiledZoneId[];
+    writes: readonly BuiltinCompiledZoneId[];
 }
-export declare const BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS: readonly [{
+export declare const BUILTIN_COMPILED_STAGE_ACCESS_PATTERNS: readonly [{
     readonly id: "summarize";
     readonly label: "Summarize";
     readonly description: "Turn source files into per-file summaries.";
-    readonly contractType: "workspace-file-evidence";
+    readonly contractType: "compiled-file-evidence";
     readonly skillDir: "summarize";
     readonly reads: readonly ["raw", "runtime"];
     readonly writes: readonly ["summaries"];
@@ -103,36 +102,28 @@ export declare const BUILTIN_WORKSPACE_STAGE_ACCESS_PATTERNS: readonly [{
     readonly id: "structure";
     readonly label: "Structure";
     readonly description: "Build the cross-file knowledge structure from the summaries.";
-    readonly contractType: "workspace-knowledge-structure";
+    readonly contractType: "compiled-knowledge-structure";
     readonly skillDir: "structure";
     readonly reads: readonly ["summaries", "runtime"];
     readonly writes: readonly ["knowledge-entities", "knowledge-claims", "knowledge-indexes"];
 }, {
     readonly id: "shape";
     readonly label: "Shape";
-    readonly description: "Shape the final workspace around the saved focus and truth checks.";
-    readonly contractType: "workspace-query-shape";
+    readonly description: "Shape the final compiled around the saved focus and truth checks.";
+    readonly contractType: "compiled-query-shape";
     readonly skillDir: "shape";
     readonly reads: readonly ["raw", "summaries", "knowledge-entities", "knowledge-claims", "knowledge-indexes", "runtime"];
     readonly writes: readonly ["knowledge-indexes", "home"];
 }];
-export declare function workspaceContractOrder(contractType: WorkspaceContractType): number;
-export declare function workspaceBundledSkillForContractType(contractType: WorkspaceContractType): string;
-export declare function hasValidWorkspaceContractSequence(contractTypes: readonly WorkspaceContractType[]): boolean;
-export declare function listMissingWorkspaceContractTypes(contractTypes: readonly string[]): WorkspaceContractType[];
-export declare function validateWorkspaceContractSequence(contractTypes: readonly WorkspaceContractType[]): {
-    ok: boolean;
-    orderValid: boolean;
-    missing: WorkspaceContractType[];
-};
-export declare function listBuiltinWorkspaceZoneSpecs(): BuiltinWorkspaceZoneSpec[];
-export declare function listBuiltinWorkspaceFallbackStages(): Array<{
-    id: BuiltinWorkspaceStageId;
-    contract_type: WorkspaceContractType;
-    reads: BuiltinWorkspaceZoneId[];
-    writes: BuiltinWorkspaceZoneId[];
+export declare function listBuiltinCompiledZoneSpecs(): BuiltinCompiledZoneSpec[];
+export declare function listBuiltinCompiledFallbackStages(): Array<{
+    id: BuiltinCompiledStageId;
+    contract_type: CompiledContractType;
+    reads: BuiltinCompiledZoneId[];
+    writes: BuiltinCompiledZoneId[];
 }>;
-export declare function requiredWorkspaceZoneOwners<TStage extends {
+export declare function requiredCompiledZoneOwners<TStage extends {
     id: string;
-    contractType: WorkspaceContractType;
-}>(stages: readonly TStage[], zoneId: BuiltinWorkspaceZoneId): string[];
+    writes: readonly string[];
+}>(stages: readonly TStage[], zoneId: BuiltinCompiledZoneId): string[];
+export { COMPILED_ZONE_KINDS };

package/dist/lib/builtin-compiled-workflow.js

@@ -0,0 +1,153 @@
+import { COMPILED_ZONE_KINDS } from "./workflow-primitives.js";
+export const COMPILED_CONTRACT_TYPES = [
+    "compiled-file-evidence",
+    "compiled-knowledge-structure",
+    "compiled-query-shape",
+];
+export const COMPILED_CONTRACT_FAMILY_METADATA = {
+    "compiled-file-evidence": {
+        order: 0,
+        bundledSkill: "compile/stages/summarize",
+    },
+    "compiled-knowledge-structure": {
+        order: 1,
+        bundledSkill: "compile/stages/structure",
+    },
+    "compiled-query-shape": {
+        order: 2,
+        bundledSkill: "compile/stages/shape",
+    },
+};
+export const BUILTIN_COMPILED_STAGE_IDS = {
+    SUMMARIZE: "summarize",
+    STRUCTURE: "structure",
+    SHAPE: "shape",
+};
+export const BUILTIN_COMPILED_ZONE_IDS = {
+    RAW: "raw",
+    SUMMARIES: "summaries",
+    KNOWLEDGE_ENTITIES: "knowledge-entities",
+    KNOWLEDGE_CLAIMS: "knowledge-claims",
+    KNOWLEDGE_INDEXES: "knowledge-indexes",
+    HOME: "home",
+    RUNTIME: "runtime",
+};
+export const BUILTIN_COMPILED_ZONE_SPECS = [
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.RAW,
+        path: "raw",
+        kind: "directory",
+        required: true,
+        description: "Compiled-local raw snapshot copied from the dataset for direct evidence and verification.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.SUMMARIES,
+        path: "summaries",
+        kind: "directory",
+        required: true,
+        description: "Per-file evidence notes produced by file-evidence stages.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_ENTITIES,
+        path: "knowledge/entities",
+        kind: "directory",
+        required: true,
+        description: "Canonical entity notes produced by knowledge-structure stages.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_CLAIMS,
+        path: "knowledge/claims",
+        kind: "directory",
+        required: true,
+        description: "Claim notes produced by knowledge-structure stages.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_INDEXES,
+        path: "knowledge/indexes",
+        kind: "directory",
+        required: true,
+        description: "Retrieval indexes and navigation notes produced by structure and shape stages.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.HOME,
+        path: "home.md",
+        kind: "file",
+        required: true,
+        description: "Primary entrypoint note for agents using the compiled dataset.",
+    },
+    {
+        id: BUILTIN_COMPILED_ZONE_IDS.RUNTIME,
+        path: ".interf/runtime",
+        kind: "runtime",
+        required: true,
+        description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.",
+    },
+];
+export const BUILTIN_COMPILED_STAGE_ACCESS_PATTERNS = [
+    {
+        id: BUILTIN_COMPILED_STAGE_IDS.SUMMARIZE,
+        label: "Summarize",
+        description: "Turn source files into per-file summaries.",
+        contractType: "compiled-file-evidence",
+        skillDir: "summarize",
+        reads: [
+            BUILTIN_COMPILED_ZONE_IDS.RAW,
+            BUILTIN_COMPILED_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_COMPILED_ZONE_IDS.SUMMARIES,
+        ],
+    },
+    {
+        id: BUILTIN_COMPILED_STAGE_IDS.STRUCTURE,
+        label: "Structure",
+        description: "Build the cross-file knowledge structure from the summaries.",
+        contractType: "compiled-knowledge-structure",
+        skillDir: "structure",
+        reads: [
+            BUILTIN_COMPILED_ZONE_IDS.SUMMARIES,
+            BUILTIN_COMPILED_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_ENTITIES,
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_CLAIMS,
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_INDEXES,
+        ],
+    },
+    {
+        id: BUILTIN_COMPILED_STAGE_IDS.SHAPE,
+        label: "Shape",
+        description: "Shape the final compiled around the saved focus and truth checks.",
+        contractType: "compiled-query-shape",
+        skillDir: "shape",
+        reads: [
+            BUILTIN_COMPILED_ZONE_IDS.RAW,
+            BUILTIN_COMPILED_ZONE_IDS.SUMMARIES,
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_ENTITIES,
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_CLAIMS,
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_INDEXES,
+            BUILTIN_COMPILED_ZONE_IDS.RUNTIME,
+        ],
+        writes: [
+            BUILTIN_COMPILED_ZONE_IDS.KNOWLEDGE_INDEXES,
+            BUILTIN_COMPILED_ZONE_IDS.HOME,
+        ],
+    },
+];
+export function listBuiltinCompiledZoneSpecs() {
+    return BUILTIN_COMPILED_ZONE_SPECS.map((zone) => ({ ...zone }));
+}
+export function listBuiltinCompiledFallbackStages() {
+    return BUILTIN_COMPILED_STAGE_ACCESS_PATTERNS.map((stage) => ({
+        id: stage.id,
+        contract_type: stage.contractType,
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+    }));
+}
+export function requiredCompiledZoneOwners(stages, zoneId) {
+    return Array.from(new Set(stages
+        .filter((stage) => stage.writes.includes(zoneId))
+        .map((stage) => stage.id)));
+}
+export { COMPILED_ZONE_KINDS };

package/dist/lib/compiled-compile.d.ts

@@ -0,0 +1,52 @@
+import { type WorkflowExecutor } from "./executors.js";
+import { type CompiledWorkflowId, type WorkflowStageDefinition } from "./workflow-definitions.js";
+import { type WorkflowReporter, type WorkflowStageResult } from "./workflow-helpers.js";
+export interface CompiledStageExecutionDefinition extends WorkflowStageDefinition {
+}
+export interface CompiledSummarizeResult extends WorkflowStageResult {
+    skipped: boolean;
+    plan: {
+        sourceCount: number;
+        summaryCount: number;
+        targetCount: number;
+    };
+}
+export interface CompiledCompileResult {
+    ok: boolean;
+    stageResults: Record<string, WorkflowStageResult>;
+    failedStage: string | null;
+    summarize: CompiledSummarizeResult | null;
+    structure: WorkflowStageResult | null;
+    shape: WorkflowStageResult | null;
+    compile: WorkflowStageResult | null;
+}
+export type StageShellRetentionMode = "on-failure" | "always";
+export declare function resolveCompiledContext(compiledPath: string): {
+    compiledName: string;
+    sourcePath: string;
+    controlPath: string;
+    workflowId: CompiledWorkflowId;
+};
+export declare function compiledExecutionStages(workflowId: CompiledWorkflowId, compiledPath: string): CompiledStageExecutionDefinition[];
+export declare function runCompiledSummarize(options: {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    reporter?: WorkflowReporter;
+    reportSummary?: boolean;
+    reportStep?: boolean;
+    stageDefinition?: CompiledStageExecutionDefinition;
+    fullPass?: boolean;
+}): Promise<CompiledSummarizeResult>;
+export declare function runCompiledCompile(options: {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    reporter?: WorkflowReporter;
+    reportStep?: boolean;
+    preserveStageShells?: StageShellRetentionMode;
+}): Promise<WorkflowStageResult>;
+export declare function compileCompiled(options: {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    reporter?: WorkflowReporter;
+    preserveStageShells?: StageShellRetentionMode;
+}): Promise<CompiledCompileResult>;

package/dist/lib/compiled-compile.js

@@ -0,0 +1,274 @@
+import { join } from "node:path";
+import { createStageExecutionShell, freezeStageExecutionShell, pruneStageExecutionShells, syncStageExecutionShellWrites, } from "./agent-shells.js";
+import { readInterfConfig, refreshCompiledBootstrapGuidance, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, } from "./interf.js";
+import { reconcileCompiledStageRun, } from "./runtime-reconcile.js";
+import { refreshCompiledArtifacts, } from "./state.js";
+import { buildRuntimeStageContract, } from "./runtime.js";
+import { validateWorkflowPackage } from "./local-workflows.js";
+import { formatActiveCompiledWorkflowStageStep, getActiveCompiledStagePolicyNotes, getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig, resolveActiveCompiledStageAcceptance, } from "./workflow-definitions.js";
+import { validateCompiledStage, validateCompiledWorkflow, } from "./validate.js";
+import { buildLocalSkillContractExtension, buildStageInstructions, reportBlankLine, reportLine, reportValidationFailure, workflowCompileStageDirectory, } from "./workflow-helpers.js";
+import { executeValidatedStage, } from "./workflow-stage-runner.js";
+import { syncCompiledRawSnapshot } from "./compiled-raw.js";
+import { workflowPackagePathForCompiled, } from "./compiled-paths.js";
+import { compiledContractArtifactPathsForZoneIds, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { listFilesRecursive } from "./filesystem.js";
+export function resolveCompiledContext(compiledPath) {
+    const config = readInterfConfig(compiledPath);
+    const workflowId = resolveRequiredCompiledWorkflowFromConfig(config, `.interf/interf.json for ${compiledPath}`);
+    return {
+        compiledName: config?.name ?? "compiled",
+        sourcePath: resolveSourceFolderPath(compiledPath, config),
+        controlPath: resolveSourceControlPath(compiledPath),
+        workflowId,
+    };
+}
+export function compiledExecutionStages(workflowId, compiledPath) {
+    return getActiveCompiledWorkflow(compiledPath, workflowId)
+        .stages;
+}
+function zoneArtifactCount(compiledPath, zonePath, kind) {
+    const absolutePath = join(compiledPath, zonePath);
+    try {
+        if (kind === "file") {
+            return listFilesRecursive(absolutePath).length > 0 ? 1 : 0;
+        }
+    }
+    catch {
+        if (kind === "file")
+            return 0;
+    }
+    return listFilesRecursive(absolutePath).length;
+}
+function resolveStageContractArtifacts(compiledPath, stageDefinition) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema) {
+        throw new Error(`Missing compiled schema for stage "${stageDefinition.id}" at ${workflowPackagePathForCompiled(compiledPath)}.`);
+    }
+    return {
+        reads: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.reads),
+        writes: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.writes),
+    };
+}
+function buildStageCounts(compiledPath, stageDefinition) {
+    const context = resolveCompiledContext(compiledPath);
+    const sourceTotal = discoverSourceFiles(context.sourcePath, compiledPath).totalCount;
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    const zoneCounts = {};
+    if (schema) {
+        for (const zoneId of new Set([...stageDefinition.reads, ...stageDefinition.writes])) {
+            const zone = findCompiledSchemaZone(schema, zoneId);
+            if (!zone)
+                continue;
+            zoneCounts[zoneId] = zoneArtifactCount(compiledPath, zone.path, zone.kind);
+        }
+    }
+    return {
+        source_total: sourceTotal,
+        read_zone_total: stageDefinition.reads.length,
+        write_zone_total: stageDefinition.writes.length,
+        ...zoneCounts,
+    };
+}
+function buildStageContract(compiledPath, workflowId, stageDefinition) {
+    const config = readInterfConfig(compiledPath);
+    const localSkills = buildLocalSkillContractExtension(compiledPath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine this workflow stage while still honoring the declared reads, writes, and proof rules.");
+    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
+    const stageArtifacts = resolveStageContractArtifacts(compiledPath, stageDefinition);
+    return buildRuntimeStageContract({
+        compiledName: config?.name ?? "compiled",
+        stageId: stageDefinition.id,
+        stageLabel: stageDefinition.label,
+        counts: buildStageCounts(compiledPath, stageDefinition),
+        stageReadArtifacts: stageArtifacts.reads,
+        stageWriteArtifacts: stageArtifacts.writes,
+        workflowNotes: getActiveCompiledStagePolicyNotes(compiledPath, workflowId, stageDefinition.id),
+        localSkillDocs: localSkills.reads,
+        instructions,
+        acceptance: resolveActiveCompiledStageAcceptance(compiledPath, workflowId, stageDefinition.id),
+    });
+}
+async function runCompiledStage(options) {
+    const context = resolveCompiledContext(options.compiledPath);
+    const stageDefinition = options.stageDefinition;
+    const contract = buildStageContract(options.compiledPath, context.workflowId, stageDefinition);
+    const localSkills = buildLocalSkillContractExtension(options.compiledPath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine this workflow stage while still honoring the declared reads, writes, and proof rules.");
+    const instructions = buildStageInstructions(stageDefinition.skillDir, localSkills);
+    if (options.reportStep !== false) {
+        reportBlankLine(options.reporter);
+        reportLine(options.reporter, `${formatActiveCompiledWorkflowStageStep(options.compiledPath, context.workflowId, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
+    }
+    const shell = createStageExecutionShell(options.compiledPath, context.compiledName, context.workflowId, stageDefinition, contract.artifacts.writes);
+    try {
+        return await executeValidatedStage({
+            executor: options.executor,
+            compiledPath: options.compiledPath,
+            executionPath: shell.rootPath,
+            targetName: context.compiledName,
+            workflow: context.workflowId,
+            workflowSourcePath: options.compiledPath,
+            stageDefinition,
+            instructions,
+            summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
+            contract,
+            statusLines: [
+                `Emit exactly one startup line: STATUS: loaded ${stageDefinition.label.toLowerCase()} stage.`,
+                "Emit STATUS: reading declared inputs after you confirm the shell contract and local docs.",
+                "Emit STATUS: writing declared outputs after the stage starts updating the compiled zones.",
+                `Emit DONE: ${stageDefinition.id} complete when the declared outputs and proof are on disk.`,
+            ],
+            reporter: options.reporter,
+            completionCheck: () => validateCompiledStage(options.compiledPath, stageDefinition.id).ok,
+            syncWrites: () => syncStageExecutionShellWrites(options.compiledPath, shell.rootPath, stageDefinition, contract.artifacts.writes),
+            reconcile: () => reconcileCompiledStageRun(options.compiledPath, stageDefinition),
+            refreshArtifacts: () => refreshCompiledArtifacts(options.compiledPath, { ensureViewSpec: true }),
+            validate: () => validateCompiledStage(options.compiledPath, stageDefinition.id),
+        });
+    }
+    finally {
+        freezeStageExecutionShell(shell.rootPath);
+    }
+}
+export async function runCompiledSummarize(options) {
+    const context = resolveCompiledContext(options.compiledPath);
+    const stageDefinition = options.stageDefinition
+        ?? compiledExecutionStages(context.workflowId, options.compiledPath).find((stage) => stage.id === "summarize");
+    if (!stageDefinition) {
+        return {
+            ok: false,
+            code: 1,
+            skipped: true,
+            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
+            summary: "Workflow does not declare a summarize stage.",
+        };
+    }
+    const sourceCount = discoverSourceFiles(context.sourcePath, options.compiledPath).totalCount;
+    const result = await runCompiledStage({
+        executor: options.executor,
+        compiledPath: options.compiledPath,
+        reporter: options.reporter,
+        reportStep: options.reportStep,
+        stageDefinition,
+    });
+    return {
+        ...result,
+        skipped: false,
+        plan: {
+            sourceCount,
+            summaryCount: 0,
+            targetCount: sourceCount,
+        },
+    };
+}
+export async function runCompiledCompile(options) {
+    const preserveMode = options.preserveStageShells ?? "on-failure";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.compiledPath);
+    }
+    let lastResult = { ok: true, code: 0 };
+    try {
+        const context = resolveCompiledContext(options.compiledPath);
+        for (const stageDefinition of compiledExecutionStages(context.workflowId, options.compiledPath)) {
+            const result = await runCompiledStage({
+                executor: options.executor,
+                compiledPath: options.compiledPath,
+                reporter: options.reporter,
+                reportStep: options.reportStep,
+                stageDefinition,
+            });
+            lastResult = result;
+            if (!result.ok)
+                return result;
+        }
+        return lastResult;
+    }
+    finally {
+        if (preserveMode !== "always" && lastResult.ok) {
+            pruneStageExecutionShells(options.compiledPath);
+        }
+    }
+}
+export async function compileCompiled(options) {
+    const preserveMode = options.preserveStageShells ?? "on-failure";
+    if (preserveMode !== "always") {
+        pruneStageExecutionShells(options.compiledPath);
+    }
+    let result = {
+        ok: true,
+        stageResults: {},
+        failedStage: null,
+        summarize: null,
+        structure: null,
+        shape: null,
+        compile: null,
+    };
+    try {
+        const sourceInputPath = resolveSourceInputPath(options.compiledPath);
+        syncCompiledRawSnapshot(options.compiledPath, sourceInputPath);
+        refreshCompiledBootstrapGuidance(options.compiledPath);
+        const workflowValidation = validateWorkflowPackage(join(options.compiledPath, ".interf", "workflow"));
+        if (!workflowValidation.ok) {
+            reportValidationFailure(options.reporter, workflowValidation.summary, workflowValidation.errors);
+            return {
+                ...result,
+                ok: false,
+                failedStage: "workflow",
+                compile: {
+                    ok: false,
+                    code: 1,
+                    summary: workflowValidation.summary,
+                },
+            };
+        }
+        const context = resolveCompiledContext(options.compiledPath);
+        const stages = compiledExecutionStages(context.workflowId, options.compiledPath);
+        for (const stageDefinition of stages) {
+            const stageResult = await runCompiledStage({
+                executor: options.executor,
+                compiledPath: options.compiledPath,
+                reporter: options.reporter,
+                reportStep: true,
+                stageDefinition,
+            });
+            result.stageResults[stageDefinition.id] = stageResult;
+            if (stageDefinition.id === "summarize") {
+                result.summarize = {
+                    ...stageResult,
+                    skipped: false,
+                    plan: {
+                        sourceCount: discoverSourceFiles(context.sourcePath, options.compiledPath).totalCount,
+                        summaryCount: 0,
+                        targetCount: discoverSourceFiles(context.sourcePath, options.compiledPath).totalCount,
+                    },
+                };
+            }
+            else if (stageDefinition.id === "structure") {
+                result.structure = stageResult;
+            }
+            else if (stageDefinition.id === "shape") {
+                result.shape = stageResult;
+            }
+            if (!stageResult.ok) {
+                result.ok = false;
+                result.failedStage = stageDefinition.id;
+                result.compile = stageResult;
+                return result;
+            }
+        }
+        const workflowValidationResult = validateCompiledWorkflow(options.compiledPath);
+        result.ok = workflowValidationResult.ok;
+        result.failedStage = workflowValidationResult.ok ? null : workflowValidationResult.stage;
+        result.compile = {
+            ok: workflowValidationResult.ok,
+            code: workflowValidationResult.ok ? 0 : 1,
+            summary: workflowValidationResult.summary,
+        };
+        return result;
+    }
+    finally {
+        if (preserveMode !== "always" && result.ok) {
+            pruneStageExecutionShells(options.compiledPath);
+        }
+    }
+}

package/dist/lib/compiled-home.d.ts

@@ -0,0 +1,5 @@
+export declare const UNCOMPILED_COMPILED_HOME_NOTICE = "Not yet compiled. Run `interf compile` to build the compiled dataset.";
+export declare function renderUncompiledCompiledHome(compiledName: string, about?: string): string;
+export declare function compiledHomeHasCompilePlaceholder(content: string): boolean;
+export declare function readCompiledHomeContent(dirPath: string): string | null;
+export declare function compiledHomeIsShaped(dirPath: string): boolean;

package/dist/lib/compiled-home.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import { compiledHomePath } from "./compiled-schema.js";
+export const UNCOMPILED_COMPILED_HOME_NOTICE = "Not yet compiled. Run `interf compile` to build the compiled dataset.";
+export function renderUncompiledCompiledHome(compiledName, about) {
+    return [
+        `# ${compiledName} — Home`,
+        "",
+        UNCOMPILED_COMPILED_HOME_NOTICE,
+        ...(about ? ["", `About: ${about}`] : []),
+        "",
+    ].join("\n");
+}
+export function compiledHomeHasCompilePlaceholder(content) {
+    return content.includes(UNCOMPILED_COMPILED_HOME_NOTICE);
+}
+export function readCompiledHomeContent(dirPath) {
+    const homePath = compiledHomePath(dirPath);
+    if (!existsSync(homePath))
+        return null;
+    try {
+        return readFileSync(homePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function compiledHomeIsShaped(dirPath) {
+    const content = readCompiledHomeContent(dirPath);
+    if (content === null)
+        return false;
+    return !compiledHomeHasCompilePlaceholder(content);
+}