@interf/compiler 0.4.0 → 0.5.0

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, resolveCompiledWorkflowFromConfig, 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 = resolveCompiledWorkflowFromConfig(config);
+    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);
+}

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

@@ -0,0 +1,2 @@
+export declare function normalizeLegacyCompiledLayout(compiledPath: string): boolean;
+export declare function compiledNeedsLegacyLayoutNormalization(compiledPath: string): boolean;

package/dist/lib/compiled-layout.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { COMPILED_CONFIG_FILE, COMPILED_INTERF_DIR, COMPILED_RUNTIME_DIR, COMPILED_TEST_DIR, COMPILED_WORKFLOW_DIR, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledInterfRoot, compiledRuntimeRoot, } from "./compiled-paths.js";
+const LEGACY_COMPILED_CONFIG_FILE = "interf.json";
+const LEGACY_WORKFLOW_DIR = "workflow";
+function movePathIfMissing(sourcePath, targetPath) {
+    if (!existsSync(sourcePath)) {
+        return false;
+    }
+    if (existsSync(targetPath)) {
+        return false;
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    renameSync(sourcePath, targetPath);
+    return true;
+}
+export function normalizeLegacyCompiledLayout(compiledPath) {
+    const interfRoot = compiledInterfRoot(compiledPath);
+    const runtimeRoot = compiledRuntimeRoot(compiledPath);
+    let changed = false;
+    changed = movePathIfMissing(join(compiledPath, LEGACY_COMPILED_CONFIG_FILE), compiledInterfConfigPath(compiledPath)) || changed;
+    changed = movePathIfMissing(join(compiledPath, LEGACY_WORKFLOW_DIR), workflowPackagePathForCompiled(compiledPath)) || changed;
+    if (!existsSync(interfRoot)) {
+        return changed;
+    }
+    for (const entry of readdirSync(interfRoot)) {
+        if (entry === COMPILED_RUNTIME_DIR ||
+            entry === COMPILED_TEST_DIR ||
+            entry === COMPILED_WORKFLOW_DIR ||
+            entry === COMPILED_CONFIG_FILE) {
+            continue;
+        }
+        changed = movePathIfMissing(join(interfRoot, entry), join(runtimeRoot, entry)) || changed;
+    }
+    return changed;
+}
+export function compiledNeedsLegacyLayoutNormalization(compiledPath) {
+    if (existsSync(join(compiledPath, LEGACY_COMPILED_CONFIG_FILE)) &&
+        !existsSync(compiledInterfConfigPath(compiledPath))) {
+        return true;
+    }
+    if (!existsSync(join(compiledPath, COMPILED_INTERF_DIR)))
+        return false;
+    if (existsSync(join(compiledPath, LEGACY_WORKFLOW_DIR)) &&
+        !existsSync(workflowPackagePathForCompiled(compiledPath))) {
+        return true;
+    }
+    for (const entry of readdirSync(join(compiledPath, COMPILED_INTERF_DIR))) {
+        if (entry === COMPILED_RUNTIME_DIR ||
+            entry === COMPILED_TEST_DIR ||
+            entry === COMPILED_WORKFLOW_DIR ||
+            entry === COMPILED_CONFIG_FILE) {
+            continue;
+        }
+        if (!existsSync(join(compiledRuntimeRoot(compiledPath), entry))) {
+            return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,41 @@
+export declare const COMPILED_INTERF_DIR = ".interf";
+export declare const COMPILED_CONFIG_FILE = "interf.json";
+export declare const COMPILED_WORKFLOW_DIR = "workflow";
+export declare const COMPILED_TEST_DIR = "tests";
+export declare const COMPILED_TEST_TARGETS_DIR = "targets";
+export declare const COMPILED_RUNTIME_DIR = "runtime";
+export declare const COMPILED_RUNTIME_STATE_FILE = "state.json";
+export declare const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
+export declare const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export declare const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export declare const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
+export declare const COMPILED_RUNTIME_RUN_FILE = "run.json";
+export declare const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export declare const COMPILED_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export declare function compiledRuntimeRoot(compiledPath: string): string;
+export declare function compiledRuntimeFilePath(compiledPath: string, fileName: string): string;
+export declare function compiledInterfRoot(compiledPath: string): string;
+export declare function compiledInterfConfigPath(compiledPath: string): string;
+export declare function workflowPackagePathForCompiled(compiledPath: string): string;
+export declare function testRootForCompiled(compiledPath: string): string;
+export declare function testRunsRootForCompiled(compiledPath: string): string;
+export declare function testTargetsRootForCompiled(compiledPath: string): string;
+export declare function latestTestComparisonPathForCompiled(compiledPath: string): string;
+export declare function stageExecutionShellsRoot(compiledPath: string): string;
+export declare function workflowImprovementLoopsRoot(compiledPath: string): string;
+export declare function workflowImprovementRunRoot(compiledPath: string, runId: string): string;
+export declare function workflowImprovementLoopRoot(compiledPath: string, runId: string, loopIndex: number): string;
+export declare function targetTestRunsRootForCompiled(compiledPath: string): string;
+export declare function targetTestSandboxesRootForCompiled(compiledPath: string): string;
+export declare function compiledRuntimeLogsRoot(compiledPath: string): string;
+export declare function compiledQueryAcceptanceRoot(compiledPath: string): string;
+export declare function compiledRuntimeStatePath(compiledPath: string): string;
+export declare function compiledRuntimeHealthPath(compiledPath: string): string;
+export declare function compiledRuntimeViewSpecPath(compiledPath: string): string;
+export declare function compiledRawSnapshotMetadataPath(compiledPath: string): string;
+export declare function compiledRuntimeInventoryPath(compiledPath: string): string;
+export declare function compiledRuntimeRunPath(compiledPath: string): string;
+export declare function compiledRuntimeRunHistoryPath(compiledPath: string): string;
+export declare function compiledRuntimeStageContractPath(compiledPath: string): string;
+export declare function resolveSourceControlPathForCompiled(compiledPath: string): string;
+export declare function defaultControlPathForCompiled(compiledPath: string): string;

package/dist/lib/compiled-paths.js

@@ -0,0 +1,111 @@
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+export const COMPILED_INTERF_DIR = ".interf";
+export const COMPILED_CONFIG_FILE = "interf.json";
+export const COMPILED_WORKFLOW_DIR = "workflow";
+export const COMPILED_TEST_DIR = "tests";
+export const COMPILED_TEST_TARGETS_DIR = "targets";
+export const COMPILED_RUNTIME_DIR = "runtime";
+export const COMPILED_RUNTIME_STATE_FILE = "state.json";
+export const COMPILED_RUNTIME_HEALTH_FILE = "health.json";
+export const COMPILED_RUNTIME_VIEW_SPEC_FILE = "view-spec.json";
+export const COMPILED_RUNTIME_RAW_SNAPSHOT_FILE = "raw-snapshot.json";
+export const COMPILED_RUNTIME_INVENTORY_FILE = "inventory.json";
+export const COMPILED_RUNTIME_RUN_FILE = "run.json";
+export const COMPILED_RUNTIME_RUN_HISTORY_FILE = "run-history.jsonl";
+export const COMPILED_RUNTIME_STAGE_CONTRACT_FILE = "stage-contract.json";
+export function compiledRuntimeRoot(compiledPath) {
+    return join(compiledPath, COMPILED_INTERF_DIR, COMPILED_RUNTIME_DIR);
+}
+export function compiledRuntimeFilePath(compiledPath, fileName) {
+    return join(compiledRuntimeRoot(compiledPath), fileName);
+}
+export function compiledInterfRoot(compiledPath) {
+    return join(compiledPath, COMPILED_INTERF_DIR);
+}
+export function compiledInterfConfigPath(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_CONFIG_FILE);
+}
+export function workflowPackagePathForCompiled(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_WORKFLOW_DIR);
+}
+export function testRootForCompiled(compiledPath) {
+    return join(compiledInterfRoot(compiledPath), COMPILED_TEST_DIR);
+}
+export function testRunsRootForCompiled(compiledPath) {
+    return join(testRootForCompiled(compiledPath), "runs");
+}
+export function testTargetsRootForCompiled(compiledPath) {
+    return join(testRootForCompiled(compiledPath), COMPILED_TEST_TARGETS_DIR);
+}
+export function latestTestComparisonPathForCompiled(compiledPath) {
+    return join(testRootForCompiled(compiledPath), "latest.json");
+}
+export function stageExecutionShellsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "execution-shells");
+}
+export function workflowImprovementLoopsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "improvement-loops");
+}
+export function workflowImprovementRunRoot(compiledPath, runId) {
+    return join(workflowImprovementLoopsRoot(compiledPath), runId);
+}
+export function workflowImprovementLoopRoot(compiledPath, runId, loopIndex) {
+    return join(workflowImprovementRunRoot(compiledPath, runId), `loop-${String(loopIndex).padStart(2, "0")}`);
+}
+export function targetTestRunsRootForCompiled(compiledPath) {
+    return join(testTargetsRootForCompiled(compiledPath), "runs");
+}
+export function targetTestSandboxesRootForCompiled(compiledPath) {
+    return join(testTargetsRootForCompiled(compiledPath), "sandboxes");
+}
+export function compiledRuntimeLogsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "logs");
+}
+export function compiledQueryAcceptanceRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "query-acceptance");
+}
+export function compiledRuntimeStatePath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_STATE_FILE);
+}
+export function compiledRuntimeHealthPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_HEALTH_FILE);
+}
+export function compiledRuntimeViewSpecPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_VIEW_SPEC_FILE);
+}
+export function compiledRawSnapshotMetadataPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RAW_SNAPSHOT_FILE);
+}
+export function compiledRuntimeInventoryPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_INVENTORY_FILE);
+}
+export function compiledRuntimeRunPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RUN_FILE);
+}
+export function compiledRuntimeRunHistoryPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_RUN_HISTORY_FILE);
+}
+export function compiledRuntimeStageContractPath(compiledPath) {
+    return compiledRuntimeFilePath(compiledPath, COMPILED_RUNTIME_STAGE_CONTRACT_FILE);
+}
+export function resolveSourceControlPathForCompiled(compiledPath) {
+    let cursor = resolve(compiledPath);
+    while (true) {
+        if (basename(cursor) === "compiled") {
+            const datasetRoot = dirname(cursor);
+            const interfRoot = dirname(datasetRoot);
+            if (basename(interfRoot) === "interf") {
+                return dirname(interfRoot);
+            }
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new Error(`Compiled dataset is not under the canonical project layout: ${compiledPath}`);
+}
+export function defaultControlPathForCompiled(compiledPath) {
+    const relativePath = relative(compiledPath, resolveSourceControlPathForCompiled(compiledPath));
+    return relativePath.length > 0 ? relativePath.split(sep).join("/") : ".";
+}

package/dist/lib/{workspace-raw.d.ts → compiled-raw.d.ts}

@@ -1,13 +1,13 @@
 import type { InterfConfig } from "./schema.js";
-export interface WorkspaceRawSyncResult {
+export interface CompiledRawSyncResult {
     sourceTotal: number;
     copied: number;
     removed: number;
 }
 type RawSnapshotMaterializeMode = "copy" | "link-or-copy";
-export declare function resolveWorkspaceRawPath(workspacePath: string, config?: {
+export declare function resolveCompiledRawPath(compiledPath: string, config?: {
     [x: string]: unknown;
-    type: "workspace";
+    type: "compiled";
     name: string;
     checks: {
         question: string;
@@ -25,6 +25,7 @@ export declare function resolveWorkspaceRawPath(workspacePath: string, config?:
     source: {
         path: string;
         control_path?: string | undefined;
+        dataset_path?: string | undefined;
     };
     about?: string | undefined;
     workflow?: string | undefined;
@@ -35,14 +36,14 @@ export declare function resolveWorkspaceRawPath(workspacePath: string, config?:
         local_draft?: boolean | undefined;
     } | undefined;
 } | null): string;
-export declare function syncWorkspaceRawSnapshot(workspacePath: string, sourcePath?: string): WorkspaceRawSyncResult;
-export declare function ensureWorkspaceRawBinding(workspacePath: string): InterfConfig | null;
+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;
-    workspacePath: string;
+    compiledPath: string;
     mode?: RawSnapshotMaterializeMode;
     prune?: boolean;
     preserveTimestamps?: boolean;
-}): WorkspaceRawSyncResult;
+}): CompiledRawSyncResult;
 export {};