@interf/compiler 0.6.3 → 0.6.4

package/dist/packages/compiler/compiled-pipeline.d.ts

@@ -0,0 +1,39 @@
+import { type WorkflowExecutor } from "../agents/lib/executors.js";
+import { type WorkflowReporter, type WorkflowStageResult } from "../workflow-package/workflow-helpers.js";
+import { type CompiledStageExecutionDefinition } from "./compiled-target.js";
+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;
+}
+export type StageShellRetentionMode = "on-failure" | "always";
+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/packages/compiler/compiled-pipeline.js

@@ -0,0 +1,134 @@
+import { join } from "node:path";
+import { refreshCompiledBootstrapGuidance, } from "../agents/lib/compiled-bootstrap.js";
+import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
+import { reportValidationFailure, } from "../workflow-package/workflow-helpers.js";
+import { validateCompiledWorkflow, } from "./validate.js";
+import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
+import { syncCompiledRawSnapshot } from "./raw-snapshot.js";
+import { compiledExecutionStages, resolveCompiledContext, } from "./compiled-target.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { runCompiledStage } from "./compiled-stage-runner.js";
+import { resolveSourceInputPath } from "../project-model/interf-detect.js";
+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,
+    };
+    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",
+                stageResults: {
+                    ...result.stageResults,
+                    workflow: {
+                        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 (!stageResult.ok) {
+                result.ok = false;
+                result.failedStage = stageDefinition.id;
+                return result;
+            }
+        }
+        const workflowValidationResult = validateCompiledWorkflow(options.compiledPath);
+        result.ok = workflowValidationResult.ok;
+        result.failedStage = workflowValidationResult.ok ? null : workflowValidationResult.stage;
+        result.stageResults.compiled = {
+            ok: workflowValidationResult.ok,
+            code: workflowValidationResult.ok ? 0 : 1,
+            summary: workflowValidationResult.summary,
+        };
+        return result;
+    }
+    finally {
+        if (preserveMode !== "always" && result.ok) {
+            pruneStageExecutionShells(options.compiledPath);
+        }
+    }
+}

package/dist/packages/compiler/compiled-schema.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { warnInterf } from "../../lib/logger.js";
-import { readJsonFileUnchecked } from "../../lib/parse.js";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked } from "../shared/parse.js";
 import { BUILTIN_COMPILED_ZONE_IDS, listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "../workflow-package/builtin-compiled-workflow.js";
 import { WorkflowCompiledSchemaSchema, } from "./lib/schema.js";
 export { BUILTIN_COMPILED_ZONE_IDS } from "../workflow-package/builtin-compiled-workflow.js";

package/dist/packages/compiler/compiled-stage-plan.d.ts

@@ -0,0 +1,15 @@
+import { type RuntimeStageContractDraft } from "./runtime.js";
+import { type CompiledWorkflowId, type WorkflowStageDefinition } from "../workflow-package/workflow-definitions.js";
+import { resolveCompiledContext, type CompiledStageExecutionDefinition } from "./compiled-target.js";
+import type { RuntimeStageInstructions } from "./lib/schema.js";
+export declare function resolveStageContractArtifacts(compiledPath: string, stageDefinition: Pick<WorkflowStageDefinition, "id" | "reads" | "writes">): {
+    reads: string[];
+    writes: string[];
+};
+export declare function buildStageCounts(compiledPath: string, stageDefinition: WorkflowStageDefinition): Record<string, number>;
+export declare function buildStageContract(compiledPath: string, workflowId: CompiledWorkflowId, stageDefinition: WorkflowStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
+export declare function buildCompiledStageExecutionPlan(compiledPath: string, stageDefinition: CompiledStageExecutionDefinition): {
+    context: ReturnType<typeof resolveCompiledContext>;
+    contract: RuntimeStageContractDraft;
+    instructions: RuntimeStageInstructions;
+};

package/dist/packages/compiler/compiled-stage-plan.js

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { buildRuntimeStageContract, } from "./runtime.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { listFilesRecursive } from "../shared/filesystem.js";
+import { compiledContractArtifactPathsForZoneIds, findCompiledSchemaZone, readCompiledSchemaFile, } from "./compiled-schema.js";
+import { buildLocalSkillContractExtension, buildStageInstructions, workflowCompileStageDirectory, } from "../workflow-package/workflow-helpers.js";
+import { getActiveCompiledStagePolicyNotes, resolveActiveCompiledStageAcceptance, } from "../workflow-package/workflow-definitions.js";
+import { workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { readInterfConfig } from "../project-model/interf-detect.js";
+import { resolveCompiledContext, } from "./compiled-target.js";
+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;
+}
+export function resolveStageContractArtifacts(compiledPath, stageDefinition) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema) {
+        throw new Error(`Missing workflow schema for stage "${stageDefinition.id}" at ${workflowPackagePathForCompiled(compiledPath)}.`);
+    }
+    return {
+        reads: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.reads),
+        writes: compiledContractArtifactPathsForZoneIds(schema, stageDefinition.writes),
+    };
+}
+export 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,
+    };
+}
+export function buildStageContract(compiledPath, workflowId, stageDefinition, instructions) {
+    const config = readInterfConfig(compiledPath);
+    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: instructions.local_docs,
+        instructions,
+        acceptance: resolveActiveCompiledStageAcceptance(compiledPath, workflowId, stageDefinition.id),
+    });
+}
+export function buildCompiledStageExecutionPlan(compiledPath, stageDefinition) {
+    const context = resolveCompiledContext(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);
+    return {
+        context,
+        instructions,
+        contract: buildStageContract(compiledPath, context.workflowId, stageDefinition, instructions),
+    };
+}

package/dist/packages/compiler/compiled-stage-runner.d.ts

@@ -0,0 +1,10 @@
+import { type WorkflowExecutor } from "../agents/lib/executors.js";
+import { type WorkflowReporter, type WorkflowStageResult } from "../workflow-package/workflow-helpers.js";
+import { type CompiledStageExecutionDefinition } from "./compiled-target.js";
+export declare function runCompiledStage(options: {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    reporter?: WorkflowReporter;
+    reportStep?: boolean;
+    stageDefinition: CompiledStageExecutionDefinition;
+}): Promise<WorkflowStageResult>;

package/dist/packages/compiler/compiled-stage-runner.js

@@ -0,0 +1,46 @@
+import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutionShellWrites, } from "../agents/lib/shells.js";
+import { reconcileCompiledStageRun } from "./runtime-reconcile.js";
+import { refreshCompiledArtifacts } from "./state.js";
+import { validateCompiledStage } from "./validate.js";
+import { executeValidatedStage, } from "../workflow-package/workflow-stage-runner.js";
+import { formatActiveCompiledWorkflowStageStep, } from "../workflow-package/workflow-definitions.js";
+import { reportBlankLine, reportLine, } from "../workflow-package/workflow-helpers.js";
+import { buildCompiledStageExecutionPlan, } from "./compiled-stage-plan.js";
+export async function runCompiledStage(options) {
+    const stageDefinition = options.stageDefinition;
+    const plan = buildCompiledStageExecutionPlan(options.compiledPath, stageDefinition);
+    if (options.reportStep !== false) {
+        reportBlankLine(options.reporter);
+        reportLine(options.reporter, `${formatActiveCompiledWorkflowStageStep(options.compiledPath, plan.context.workflowId, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
+    }
+    const shell = createStageExecutionShell(options.compiledPath, plan.context.compiledName, plan.context.workflowId, stageDefinition, plan.contract.artifacts.writes);
+    try {
+        return await executeValidatedStage({
+            executor: options.executor,
+            compiledPath: options.compiledPath,
+            executionPath: shell.rootPath,
+            targetName: plan.context.compiledName,
+            workflow: plan.context.workflowId,
+            workflowSourcePath: options.compiledPath,
+            stageDefinition,
+            instructions: plan.instructions,
+            summary: `Executing ${stageDefinition.label.toLowerCase()}.`,
+            contract: plan.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, plan.contract.artifacts.writes),
+            reconcile: () => reconcileCompiledStageRun(options.compiledPath, stageDefinition),
+            refreshArtifacts: () => refreshCompiledArtifacts(options.compiledPath, { ensureViewSpec: true }),
+            validate: () => validateCompiledStage(options.compiledPath, stageDefinition.id),
+        });
+    }
+    finally {
+        freezeStageExecutionShell(shell.rootPath);
+    }
+}

package/dist/packages/compiler/compiled-target.d.ts

@@ -0,0 +1,11 @@
+import { type WorkflowStageDefinition } from "../workflow-package/workflow-definitions.js";
+import { type CompiledWorkflowId } from "../workflow-package/workflow-definitions.js";
+export interface CompiledStageExecutionDefinition extends WorkflowStageDefinition {
+}
+export declare function resolveCompiledContext(compiledPath: string): {
+    compiledName: string;
+    sourcePath: string;
+    controlPath: string;
+    workflowId: CompiledWorkflowId;
+};
+export declare function compiledExecutionStages(workflowId: CompiledWorkflowId, compiledPath: string): CompiledStageExecutionDefinition[];

package/dist/packages/compiler/compiled-target.js

@@ -0,0 +1,16 @@
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig, } from "../workflow-package/workflow-definitions.js";
+import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../project-model/interf-detect.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;
+}

package/dist/packages/compiler/discovery.d.ts

@@ -0,0 +1,7 @@
+export interface DiscoveryResult {
+    sourceFiles: string[];
+    totalCount: number;
+    ignoredCount: number;
+}
+export declare function discoverSourceFiles(sourcePath: string, compiledPath: string): DiscoveryResult;
+export declare function loadIgnorePatterns(compiledPath: string): string[];

package/dist/packages/compiler/discovery.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { listFilesRecursive } from "../shared/filesystem.js";
+const DEFAULT_IGNORE_DIRS = new Set([
+    "interf",
+    ".interf",
+    ".git",
+    ".obsidian",
+    ".claude",
+    "node_modules",
+]);
+const DEFAULT_IGNORE_FILES = new Set([
+    "interf.json",
+]);
+export function discoverSourceFiles(sourcePath, compiledPath) {
+    const userPatterns = loadIgnorePatterns(compiledPath);
+    let ignoredCount = 0;
+    const allFiles = listFilesRecursive(sourcePath, (filePath) => {
+        const rel = relative(sourcePath, filePath);
+        if (isIgnored(rel)) {
+            ignoredCount++;
+            return false;
+        }
+        if (userPatterns.length > 0 && matchesUserPattern(rel, userPatterns)) {
+            ignoredCount++;
+            return false;
+        }
+        return true;
+    });
+    const sourceFiles = allFiles
+        .map((f) => relative(sourcePath, f))
+        .sort((a, b) => a.localeCompare(b));
+    return {
+        sourceFiles,
+        totalCount: sourceFiles.length,
+        ignoredCount,
+    };
+}
+export function loadIgnorePatterns(compiledPath) {
+    const ignorePath = join(compiledPath, ".interfignore");
+    if (!existsSync(ignorePath))
+        return [];
+    return readFileSync(ignorePath, "utf-8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+function isIgnored(relativePath) {
+    if (DEFAULT_IGNORE_FILES.has(relativePath))
+        return true;
+    const segments = relativePath.split("/");
+    for (const segment of segments) {
+        if (segment.startsWith("."))
+            return true;
+        if (DEFAULT_IGNORE_DIRS.has(segment))
+            return true;
+    }
+    return false;
+}
+function matchesUserPattern(relativePath, patterns) {
+    for (const pattern of patterns) {
+        if (matchGlob(relativePath, pattern))
+            return true;
+    }
+    return false;
+}
+function matchGlob(path, pattern) {
+    if (pattern.endsWith("/")) {
+        const dir = pattern.slice(0, -1);
+        return path === dir || path.startsWith(dir + "/") || path.includes("/" + dir + "/");
+    }
+    if (pattern.startsWith("*.")) {
+        return path.endsWith(pattern.slice(1));
+    }
+    if (!pattern.includes("/") && !pattern.includes("*")) {
+        const filename = path.split("/").pop() ?? "";
+        return filename === pattern;
+    }
+    return path === pattern || path.startsWith(pattern + "/");
+}

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

@@ -109,6 +109,8 @@ export const WorkflowZoneSchema = z.object({
     description: z.string().min(1),
 });
 export const WorkflowCompiledZoneSchema = WorkflowZoneSchema;
+// Persisted schema for the workflow-defined context interface that one
+// compiled context must implement on disk.
 export const WorkflowSchemaSchema = z.object({
     kind: z.literal("workflow-schema"),
     version: z.literal(1),

package/dist/packages/compiler/raw-snapshot.d.ts

@@ -0,0 +1,49 @@
+import type { InterfConfig } from "../project-model/lib/schema.js";
+export interface CompiledRawSyncResult {
+    sourceTotal: number;
+    copied: number;
+    removed: number;
+}
+type RawSnapshotMaterializeMode = "copy" | "link-or-copy";
+export declare function resolveCompiledRawPath(compiledPath: string, config?: {
+    [x: string]: unknown;
+    type: "compiled";
+    name: string;
+    workflow: string;
+    checks: {
+        question: string;
+        id?: string | undefined;
+        answer?: string | undefined;
+        expect?: {
+            must_include?: string[] | undefined;
+            must_include_one_of?: string[][] | undefined;
+            must_not_include?: string[] | undefined;
+            min_words?: number | undefined;
+            max_words?: number | undefined;
+        } | undefined;
+        strictness?: string | undefined;
+    }[];
+    source: {
+        path: string;
+        dataset_path: string;
+        control_path?: string | undefined;
+    };
+    about?: string | undefined;
+    max_attempts?: number | undefined;
+    max_loops?: number | undefined;
+    workflow_origin?: {
+        selected: string;
+        local_draft?: boolean | undefined;
+    } | undefined;
+} | null): string;
+export declare function syncCompiledRawSnapshot(compiledPath: string, sourcePath?: string): CompiledRawSyncResult;
+export declare function ensureCompiledRawBinding(compiledPath: string): InterfConfig | null;
+export declare function projectRawSnapshot(options: {
+    sourcePath: string;
+    destinationPath: string;
+    compiledPath: string;
+    mode?: RawSnapshotMaterializeMode;
+    prune?: boolean;
+    preserveTimestamps?: boolean;
+}): CompiledRawSyncResult;
+export {};

package/dist/packages/compiler/raw-snapshot.js

@@ -0,0 +1,102 @@
+import { cpSync, existsSync, linkSync, mkdirSync, rmSync, statSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { listFilesRecursive } from "../shared/filesystem.js";
+import { assertPathWithinRoot } from "../shared/path-guards.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { defaultControlPathForCompiled } from "./compiled-paths.js";
+import { readInterfConfig, resolveSourceInputPath, } from "../project-model/interf-detect.js";
+import { saveCompiledInterfConfig } from "../project-model/source-config.js";
+export function resolveCompiledRawPath(compiledPath, config = readInterfConfig(compiledPath)) {
+    const configuredPath = typeof config?.source?.path === "string" && config.source.path.length > 0
+        ? config.source.path
+        : "raw";
+    return assertPathWithinRoot(compiledPath, resolve(compiledPath, configuredPath), "Compiled raw path");
+}
+export function syncCompiledRawSnapshot(compiledPath, sourcePath = resolveSourceInputPath(compiledPath)) {
+    ensureCompiledRawBinding(compiledPath);
+    const rawPath = resolveCompiledRawPath(compiledPath);
+    return projectRawSnapshot({
+        sourcePath,
+        destinationPath: rawPath,
+        compiledPath,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+}
+export function ensureCompiledRawBinding(compiledPath) {
+    const config = readInterfConfig(compiledPath);
+    if (!config)
+        return null;
+    if (config.source?.path === "./raw")
+        return config;
+    const nextConfig = {
+        ...config,
+        source: {
+            ...(config.source ?? {}),
+            path: "./raw",
+            control_path: config.source?.control_path ?? defaultControlPathForCompiled(compiledPath),
+            ...(config.source?.dataset_path ? { dataset_path: config.source.dataset_path } : {}),
+        },
+    };
+    return saveCompiledInterfConfig(compiledPath, nextConfig);
+}
+function filesMatch(sourcePath, targetPath) {
+    if (!existsSync(targetPath))
+        return false;
+    try {
+        const sourceStat = statSync(sourcePath);
+        const targetStat = statSync(targetPath);
+        return sourceStat.size === targetStat.size && sourceStat.mtimeMs === targetStat.mtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
+function materializeRawSnapshotFile(sourcePath, targetPath, options) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    rmSync(targetPath, { force: true });
+    if (options.mode === "link-or-copy") {
+        try {
+            linkSync(sourcePath, targetPath);
+            return;
+        }
+        catch {
+            // fall through to copy
+        }
+    }
+    cpSync(sourcePath, targetPath, { preserveTimestamps: options.preserveTimestamps });
+}
+export function projectRawSnapshot(options) {
+    const discovery = discoverSourceFiles(options.sourcePath, options.compiledPath);
+    const expectedFiles = new Set(discovery.sourceFiles);
+    mkdirSync(options.destinationPath, { recursive: true });
+    let removed = 0;
+    if (options.prune !== false) {
+        for (const existingPath of listFilesRecursive(options.destinationPath)) {
+            const relativePath = relative(options.destinationPath, existingPath);
+            if (expectedFiles.has(relativePath))
+                continue;
+            rmSync(existingPath, { force: true });
+            removed += 1;
+        }
+    }
+    let copied = 0;
+    for (const relativePath of discovery.sourceFiles) {
+        const sourceFilePath = join(options.sourcePath, relativePath);
+        const targetFilePath = join(options.destinationPath, relativePath);
+        if (filesMatch(sourceFilePath, targetFilePath)) {
+            continue;
+        }
+        materializeRawSnapshotFile(sourceFilePath, targetFilePath, {
+            mode: options.mode ?? "copy",
+            preserveTimestamps: options.preserveTimestamps ?? true,
+        });
+        copied += 1;
+    }
+    return {
+        sourceTotal: discovery.totalCount,
+        copied,
+        removed,
+    };
+}

package/dist/packages/compiler/reset.d.ts

@@ -0,0 +1,2 @@
+export declare function clearCompiledRuntimeDerivedArtifacts(compiledPath: string): void;
+export declare function resetCompiledGeneratedState(compiledPath: string, scope?: "compile" | "all"): void;