@interf/compiler 0.6.1 → 0.6.3

package/dist/packages/testing/test-types.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/testing/test.d.ts

@@ -0,0 +1,4 @@
+export type { TestCaseExpect, TestCase, TestSpec, TestCheckResult, TestCaseResult, TestTargetResult, TestTargetRun, TestTargetType, LoadedTestSpec, TestTargetCandidate, } from "./test-types.js";
+export { listTestSpecs, loadTestSpec, loadTestSpecFromFile, writeTestSpec, } from "./test-specs.js";
+export { createRawTestTarget, createCompiledTestTarget, listCompiledTestTargets, listTestTargets, } from "./test-targets.js";
+export { runTargetTests, runTargetTestsWithJudge, runTargetTestsAuto, saveTargetTestRun, } from "./test-execution.js";

package/dist/packages/testing/test.js

@@ -0,0 +1,3 @@
+export { listTestSpecs, loadTestSpec, loadTestSpecFromFile, writeTestSpec, } from "./test-specs.js";
+export { createRawTestTarget, createCompiledTestTarget, listCompiledTestTargets, listTestTargets, } from "./test-targets.js";
+export { runTargetTests, runTargetTestsWithJudge, runTargetTestsAuto, saveTargetTestRun, } from "./test-execution.js";

package/dist/packages/workflow-authoring/index.d.ts

@@ -0,0 +1,4 @@
+export * as authoring from "./workflow-authoring.js";
+export * as editSession from "./workflow-edit-session.js";
+export * as editUtils from "./lib/workflow-edit-utils.js";
+export * as improvement from "./workflow-improvement.js";

package/dist/packages/workflow-authoring/index.js

@@ -0,0 +1,4 @@
+export * as authoring from "./workflow-authoring.js";
+export * as editSession from "./workflow-edit-session.js";
+export * as editUtils from "./lib/workflow-edit-utils.js";
+export * as improvement from "./workflow-improvement.js";

package/dist/packages/workflow-authoring/lib/workflow-edit-utils.d.ts

@@ -0,0 +1,10 @@
+export declare function copyDirectory(sourcePath: string, targetPath: string): void;
+export declare function directoriesMatch(leftPath: string, rightPath: string): boolean;
+export interface WorkflowEditShellArtifacts {
+    rootPath: string;
+    workflowBeforePath: string;
+    workflowAfterPath: string;
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+}

package/dist/packages/workflow-authoring/lib/workflow-edit-utils.js

@@ -0,0 +1,39 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, } from "node:fs";
+import { join, relative } from "node:path";
+export function copyDirectory(sourcePath, targetPath) {
+    rmSync(targetPath, { recursive: true, force: true });
+    mkdirSync(targetPath, { recursive: true });
+    cpSync(sourcePath, targetPath, { recursive: true });
+}
+function listFileSnapshot(dirPath) {
+    const snapshot = new Map();
+    if (!existsSync(dirPath))
+        return snapshot;
+    const collect = (currentPath) => {
+        for (const entry of readdirSync(currentPath)) {
+            const fullPath = join(currentPath, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                collect(fullPath);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            snapshot.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
+        }
+    };
+    collect(dirPath);
+    return snapshot;
+}
+export function directoriesMatch(leftPath, rightPath) {
+    const left = listFileSnapshot(leftPath);
+    const right = listFileSnapshot(rightPath);
+    if (left.size !== right.size)
+        return false;
+    for (const [relativePath, content] of left.entries()) {
+        if (right.get(relativePath) !== content) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/packages/workflow-authoring/workflow-authoring.d.ts

@@ -0,0 +1,26 @@
+import type { WorkflowExecutor } from "../agents/lib/executors.js";
+import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
+import { type WorkflowReporter } from "../compiler/workflows.js";
+import type { SourceTruthCheck } from "../project-model/lib/schema.js";
+export interface WorkflowAuthoringRunResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    summary: string;
+    validation: ReturnType<typeof validateWorkflowPackage> | null;
+    workflowPath: string;
+    shellPath: string;
+}
+export declare function runWorkflowAuthoringDraft(options: {
+    sourcePath: string;
+    datasetPath: string;
+    baseWorkflowId: string;
+    workflowId: string;
+    label: string;
+    hint: string;
+    taskPrompt: string;
+    checks?: SourceTruthCheck[];
+    executor: WorkflowExecutor;
+    preparePreview?: boolean;
+    previewReporter?: WorkflowReporter | null;
+}): Promise<WorkflowAuthoringRunResult>;
+export declare function resolveWorkflowDraftPath(sourcePath: string, workflowId: string): string;

package/dist/packages/workflow-authoring/workflow-authoring.js

@@ -0,0 +1,120 @@
+import { mkdtempSync, rmSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createWorkflowAuthoringShell } from "../agents/lib/shells.js";
+import { WORKFLOW_SCHEMA_FILE } from "../compiler/compiled-schema.js";
+import { seedLocalWorkflowPackageFromBase } from "../workflow-package/interf-workflow-package.js";
+import { validateWorkflowPackage, workflowDefinitionPath } from "../workflow-package/local-workflows.js";
+import { createCompiled, compileCompiled } from "../compiler/workflows.js";
+import { projectRawSnapshot } from "../project-model/compiled-raw.js";
+import { runWorkflowEditSession } from "./workflow-edit-session.js";
+import { copyDirectory } from "./lib/workflow-edit-utils.js";
+function buildWorkflowAuthoringPrompt() {
+    return [
+        "This is an automated Interf workflow-authoring run, not an open-ended chat session.",
+        "Execute it now.",
+        "Create one standalone workflow for the files and checks in this source folder.",
+        "Read `runtime/authoring-context.json` first.",
+        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\`.`,
+        "Review `artifacts/source-dataset/raw/` and any `artifacts/preview-compiled/` notes before editing the package.",
+        "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
+        "Edit only files under `workflow/`.",
+        "Keep the workflow valid for the current compiler API and workflow schema.",
+        "Make the package materially more specific to this dataset task than the seeded base workflow. A no-op copy is not acceptable.",
+        "Prefer explicit stage-doc, stage-policy, purpose, and zone-contract edits over vague rewrites.",
+        "Do not introduce wikilinks unless the workflow also creates the target note by exact basename or explicit relative path.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
+        "Do not make one stage point at files or notes that are only created later by another stage.",
+        "Prefer conservative retrieval routing over speculative note sprawl.",
+        "Do not narrate plans or ask follow-up questions.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "As soon as the workflow edits are complete, stop.",
+    ].join("\n");
+}
+async function prepareWorkflowAuthoringPreview(options) {
+    const tempRoot = mkdtempSync(join(tmpdir(), "interf-workflow-preview-"));
+    projectRawSnapshot({
+        sourcePath: options.datasetPath,
+        destinationPath: tempRoot,
+        compiledPath: tempRoot,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+    copyDirectory(options.workflowPath, workflowDefinitionPath(tempRoot, options.workflowId));
+    const compiledPath = createCompiled("preview", tempRoot, options.workflowId, options.about, tempRoot);
+    const result = await compileCompiled({
+        executor: options.executor,
+        compiledPath,
+        ...(options.reporter ? { reporter: options.reporter } : {}),
+        preserveStageShells: "on-failure",
+    });
+    return {
+        tempRoot,
+        compiledPath,
+        compileResult: {
+            ok: result.ok,
+            failedStage: result.failedStage,
+        },
+    };
+}
+export async function runWorkflowAuthoringDraft(options) {
+    const workflowPath = seedLocalWorkflowPackageFromBase({
+        sourcePath: options.sourcePath,
+        baseWorkflowId: options.baseWorkflowId,
+        workflowId: options.workflowId,
+        label: options.label,
+        hint: options.hint,
+    });
+    let preview = null;
+    try {
+        if (options.preparePreview !== false) {
+            preview = await prepareWorkflowAuthoringPreview({
+                datasetPath: options.datasetPath,
+                about: options.taskPrompt,
+                workflowId: options.workflowId,
+                workflowPath,
+                executor: options.executor,
+                reporter: options.previewReporter ?? null,
+            });
+        }
+        const shell = createWorkflowAuthoringShell({
+            workflowPath,
+            workflowId: options.workflowId,
+            label: options.label,
+            baseWorkflowId: options.baseWorkflowId,
+            datasetPath: options.datasetPath,
+            taskPrompt: options.taskPrompt,
+            checks: options.checks ?? [],
+            preview,
+        });
+        if (preview) {
+            rmSync(preview.tempRoot, { recursive: true, force: true });
+            preview = null;
+        }
+        const session = await runWorkflowEditSession({
+            executor: options.executor,
+            workflowPath,
+            shell,
+            prompt: buildWorkflowAuthoringPrompt(),
+            validate: validateWorkflowPackage,
+        });
+        return {
+            status: session.status,
+            changed: session.changed,
+            summary: session.summary,
+            validation: session.validation,
+            workflowPath,
+            shellPath: shell.rootPath,
+        };
+    }
+    finally {
+        if (preview) {
+            rmSync(preview.tempRoot, { recursive: true, force: true });
+        }
+    }
+}
+export function resolveWorkflowDraftPath(sourcePath, workflowId) {
+    return workflowDefinitionPath(sourcePath, workflowId);
+}

package/dist/packages/workflow-authoring/workflow-edit-session.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowExecutor } from "../agents/lib/executors.js";
+import type { WorkflowValidationResult } from "../workflow-package/local-workflows.js";
+import { type WorkflowEditShellArtifacts } from "./lib/workflow-edit-utils.js";
+export interface WorkflowEditSessionResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: WorkflowValidationResult | null;
+    summary: string;
+}
+export declare function runWorkflowEditSession(options: {
+    executor: WorkflowExecutor;
+    workflowPath: string;
+    shell: WorkflowEditShellArtifacts;
+    prompt: string;
+    validate: (workflowPath: string) => WorkflowValidationResult;
+}): Promise<WorkflowEditSessionResult>;

package/dist/packages/workflow-authoring/workflow-edit-session.js

@@ -0,0 +1,57 @@
+import { writeFileSync } from "node:fs";
+import { copyDirectory, directoriesMatch, } from "./lib/workflow-edit-utils.js";
+export async function runWorkflowEditSession(options) {
+    copyDirectory(options.workflowPath, options.shell.workflowBeforePath);
+    writeFileSync(options.shell.promptLogPath, `${options.prompt}\n`);
+    let code = 1;
+    let executeError = null;
+    try {
+        code = await options.executor.execute(options.shell.rootPath, options.prompt, {
+            eventLogPath: options.shell.eventLogPath,
+            statusLogPath: options.shell.statusLogPath,
+        });
+    }
+    catch (error) {
+        executeError = error instanceof Error ? error.message : String(error);
+    }
+    copyDirectory(options.workflowPath, options.shell.workflowAfterPath);
+    const changed = !directoriesMatch(options.shell.workflowBeforePath, options.shell.workflowAfterPath);
+    if (executeError) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "executor-failed",
+            changed,
+            validation: null,
+            summary: `Workflow editor failed before completing: ${executeError}`,
+        };
+    }
+    if (code !== 0) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "executor-failed",
+            changed,
+            validation: null,
+            summary: `Workflow editor exited with code ${code}.`,
+        };
+    }
+    const validation = options.validate(options.workflowPath);
+    if (!validation.ok) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "invalid",
+            changed,
+            validation,
+            summary: changed
+                ? `Workflow package failed validation: ${validation.summary}`
+                : `Workflow package is invalid without any workflow edits: ${validation.summary}`,
+        };
+    }
+    return {
+        status: changed ? "updated" : "no-change",
+        changed,
+        validation,
+        summary: changed
+            ? "Workflow package updated and validated."
+            : "Workflow package is valid without additional edits.",
+    };
+}

package/dist/packages/workflow-authoring/workflow-improvement.d.ts

@@ -0,0 +1,23 @@
+import type { WorkflowExecutor } from "../agents/lib/executors.js";
+import { type WorkflowValidationResult } from "../workflow-package/local-workflows.js";
+import type { SourceDatasetConfig } from "../project-model/lib/schema.js";
+import type { WorkflowImprovementLoopSummary } from "../compiler/lib/schema.js";
+export interface WorkflowImprovementRunResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: WorkflowValidationResult | null;
+    summary: string;
+    shellPath: string;
+    loopRootPath: string;
+}
+export declare function runWorkflowImprovementLoop(options: {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    workflowId: string;
+    compiledConfig: Pick<SourceDatasetConfig, "checks">;
+    runId: string;
+    loopIndex: number;
+    maxLoops: number;
+    maxAttempts: number;
+    previousVariations: WorkflowImprovementLoopSummary[];
+}): Promise<WorkflowImprovementRunResult>;

package/dist/packages/workflow-authoring/workflow-improvement.js

@@ -0,0 +1,209 @@
+import { appendFileSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { createWorkflowImprovementShell, freezeWorkflowImprovementShell, } from "../agents/lib/shells.js";
+import { WORKFLOW_SCHEMA_FILE } from "../compiler/compiled-schema.js";
+import { validateWorkflowPackage } from "../workflow-package/local-workflows.js";
+import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { resolveWorkflowImprovementReviewPaths } from "../workflow-package/workflow-review-paths.js";
+import { targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, workflowImprovementRunRoot, workflowPackagePathForCompiled, } from "../project-model/compiled-paths.js";
+import { readInterfConfig } from "../project-model/interf.js";
+import { saveCompiledInterfConfig } from "../project-model/source-config.js";
+import { WorkflowImprovementRunLedgerSchema, } from "../compiler/lib/schema.js";
+import { runWorkflowEditSession } from "./workflow-edit-session.js";
+function toShellArtifactPath(absolutePath, sourceRoot, shellRoot) {
+    if (!absolutePath)
+        return null;
+    const normalizedSourceRoot = `${sourceRoot}/`;
+    if (absolutePath !== sourceRoot && !absolutePath.startsWith(normalizedSourceRoot)) {
+        return null;
+    }
+    const relativePath = relative(sourceRoot, absolutePath);
+    return join(shellRoot, relativePath);
+}
+function mapLoopSummaryForShell(summary, compiledPath) {
+    const shellTestRunsRoot = "artifacts/test-runs";
+    const shellTestSandboxesRoot = "artifacts/test-sandboxes";
+    return {
+        ...summary,
+        test_run_path: toShellArtifactPath(summary.test_run_path, targetTestRunsRootForCompiled(compiledPath), shellTestRunsRoot) ?? summary.test_run_path ?? null,
+        test_sandbox_path: toShellArtifactPath(summary.test_sandbox_path, targetTestSandboxesRootForCompiled(compiledPath), shellTestSandboxesRoot) ?? summary.test_sandbox_path ?? null,
+    };
+}
+function buildLoopContext(options) {
+    const previousVariations = options.previousVariations.map((summary) => mapLoopSummaryForShell(summary, options.compiledPath));
+    const latestFailure = previousVariations.at(-1) ?? null;
+    return {
+        kind: "interf-workflow-improvement-loop",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        target_name: readInterfConfig(options.compiledPath)?.name ?? "compiled",
+        workflow_id: options.workflowId,
+        loop_index: options.loopIndex,
+        max_loops: options.maxLoops,
+        max_attempts: options.maxAttempts,
+        review_paths: resolveWorkflowImprovementReviewPaths(options.compiledPath),
+        truth_checks: {
+            count: options.compiledConfig.checks.length,
+            questions: options.compiledConfig.checks.map((check, index) => ({
+                id: check.id ?? `check-${index + 1}`,
+                question: check.question,
+            })),
+        },
+        previous_variations: previousVariations,
+        latest_failure: latestFailure,
+    };
+}
+function buildWorkflowImprovementPrompt() {
+    return [
+        "This is an automated Interf workflow-improvement run, not an open-ended chat session.",
+        "The user already invoked this through `interf compile` with self-improving loops enabled. Execute it now.",
+        "Read `runtime/loop-context.json` first.",
+        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, \`workflow/${WORKFLOW_SCHEMA_FILE}\`, and \`workflow/improve/SKILL.md\` if it exists.`,
+        "Review preserved evidence from earlier failures under `artifacts/` before you edit the workflow.",
+        "Treat `workflow/improve/SKILL.md` as guidance for how to improve the workflow, not as the default file to edit.",
+        "Prefer editing the stage docs, workflow contract, or schema ownership that actually change compiled outputs.",
+        "Edit only files under `workflow/`.",
+        "Do not edit checks, test specs, raw dataset files, or generated compiled outputs.",
+        "Keep the workflow valid for the current compiler API and workflow schema.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
+        "Do not make one stage point at files or notes that are only created later by another stage.",
+        "Prefer small, defensible changes to workflow docs, stage docs, stage policies, or schema ownership over random churn.",
+        "Do not narrate plans or ask follow-up questions.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "As soon as the workflow edits are complete, stop.",
+    ].join("\n");
+}
+function updateCompiledWorkflowOrigin(options) {
+    const current = readInterfConfig(options.compiledPath);
+    if (!current)
+        return;
+    const nextConfig = {
+        ...current,
+        workflow: current.workflow ?? options.selectedWorkflowId,
+        workflow_origin: {
+            selected: options.selectedWorkflowId,
+            ...(options.localDraft ? { local_draft: true } : {}),
+        },
+    };
+    saveCompiledInterfConfig(options.compiledPath, nextConfig);
+}
+function workflowImprovementRunLedgerPath(compiledPath, runId) {
+    return join(workflowImprovementRunRoot(compiledPath, runId), "run.json");
+}
+function workflowImprovementLoopHistoryPath(compiledPath, runId) {
+    return join(workflowImprovementRunRoot(compiledPath, runId), "loop-history.jsonl");
+}
+function workflowImprovementLoopRecordPath(loopRootPath) {
+    return join(loopRootPath, "loop.json");
+}
+function readWorkflowImprovementRunLedger(compiledPath, runId) {
+    const ledgerPath = workflowImprovementRunLedgerPath(compiledPath, runId);
+    if (!existsSync(ledgerPath))
+        return null;
+    return readJsonFileWithSchema(ledgerPath, "workflow improvement run ledger", WorkflowImprovementRunLedgerSchema);
+}
+function writeWorkflowImprovementRunLedger(compiledPath, runId, record, options) {
+    const runRoot = workflowImprovementRunRoot(compiledPath, runId);
+    mkdirSync(runRoot, { recursive: true });
+    const existing = readWorkflowImprovementRunLedger(compiledPath, runId);
+    const generatedAt = existing?.generated_at ?? new Date().toISOString();
+    const ledger = {
+        kind: "interf-workflow-improvement-run",
+        version: 1,
+        generated_at: generatedAt,
+        updated_at: new Date().toISOString(),
+        run_id: runId,
+        target_name: options.targetName,
+        workflow_id: options.workflowId,
+        max_loops: options.maxLoops,
+        max_attempts: options.maxAttempts,
+        loops: [...(existing?.loops ?? []), record],
+    };
+    writeFileSync(workflowImprovementRunLedgerPath(compiledPath, runId), `${JSON.stringify(ledger, null, 2)}\n`);
+    writeFileSync(workflowImprovementLoopRecordPath(record.loop_root_path), `${JSON.stringify(record, null, 2)}\n`);
+    appendFileSync(workflowImprovementLoopHistoryPath(compiledPath, runId), `${JSON.stringify(record)}\n`);
+}
+function buildWorkflowImprovementLoopRecord(options) {
+    return {
+        kind: "interf-workflow-improvement-loop-record",
+        version: 1,
+        recorded_at: new Date().toISOString(),
+        run_id: options.runId,
+        loop_index: options.loopIndex,
+        target_name: options.targetName,
+        workflow_id: options.workflowId,
+        result: options.result,
+        changed: options.changed,
+        applied: options.result === "updated",
+        summary: options.summary,
+        shell_path: options.shellPath,
+        loop_root_path: options.loopRootPath,
+        context_path: join(options.shellPath, "runtime", "loop-context.json"),
+        workflow_before_path: options.workflowBeforePath,
+        workflow_after_path: options.workflowAfterPath,
+        prompt_log_path: options.promptLogPath,
+        event_log_path: options.eventLogPath,
+        status_log_path: options.statusLogPath,
+        preserved_shell_manifest_path: options.preservedShellManifestPath,
+        validation: options.validation,
+    };
+}
+export async function runWorkflowImprovementLoop(options) {
+    const compiledName = readInterfConfig(options.compiledPath)?.name ?? "compiled";
+    const context = buildLoopContext(options);
+    const shell = createWorkflowImprovementShell({
+        compiledPath: options.compiledPath,
+        compiledName,
+        workflowId: options.workflowId,
+        runId: options.runId,
+        loopIndex: options.loopIndex,
+        context,
+    });
+    const workflowRoot = workflowPackagePathForCompiled(options.compiledPath);
+    const session = await runWorkflowEditSession({
+        executor: options.executor,
+        workflowPath: workflowRoot,
+        shell,
+        prompt: buildWorkflowImprovementPrompt(),
+        validate: validateWorkflowPackage,
+    });
+    const preservedShellManifestPath = freezeWorkflowImprovementShell(shell.rootPath);
+    writeWorkflowImprovementRunLedger(options.compiledPath, options.runId, buildWorkflowImprovementLoopRecord({
+        targetName: compiledName,
+        workflowId: options.workflowId,
+        runId: options.runId,
+        loopIndex: options.loopIndex,
+        shellPath: shell.rootPath,
+        loopRootPath: shell.loopRootPath,
+        workflowBeforePath: shell.workflowBeforePath,
+        workflowAfterPath: shell.workflowAfterPath,
+        promptLogPath: shell.promptLogPath,
+        eventLogPath: shell.eventLogPath,
+        statusLogPath: shell.statusLogPath,
+        preservedShellManifestPath,
+        changed: session.changed,
+        validation: session.validation,
+        result: session.status,
+        summary: session.summary,
+    }), {
+        targetName: compiledName,
+        workflowId: options.workflowId,
+        maxLoops: options.maxLoops,
+        maxAttempts: options.maxAttempts,
+    });
+    if (session.status === "updated") {
+        updateCompiledWorkflowOrigin({
+            compiledPath: options.compiledPath,
+            selectedWorkflowId: options.workflowId,
+            localDraft: true,
+        });
+    }
+    return {
+        status: session.status,
+        changed: session.changed,
+        validation: session.validation,
+        summary: session.summary,
+        shellPath: shell.rootPath,
+        loopRootPath: shell.loopRootPath,
+    };
+}

package/dist/packages/workflow-package/builtin-compiled-workflow.d.ts

@@ -0,0 +1,38 @@
+import { COMPILED_ZONE_KINDS, type CompiledZoneKind } from "../compiler/workflow-primitives.js";
+export declare const BUILTIN_COMPILED_STAGE_IDS: {
+    readonly SUMMARIZE: "summarize";
+    readonly STRUCTURE: "structure";
+    readonly SHAPE: "shape";
+};
+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";
+    readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
+    readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
+    readonly HOME: "home";
+    readonly RUNTIME: "runtime";
+};
+export type BuiltinCompiledZoneId = typeof BUILTIN_COMPILED_ZONE_IDS[keyof typeof BUILTIN_COMPILED_ZONE_IDS];
+export interface BuiltinCompiledZoneSpec {
+    id: BuiltinCompiledZoneId;
+    role: "input" | "working" | "output" | "runtime";
+    path: string;
+    kind: CompiledZoneKind;
+    required: boolean;
+    description: string;
+}
+export interface BuiltinCompiledStageAccessPattern {
+    id: BuiltinCompiledStageId;
+    contract_type: string;
+    reads: BuiltinCompiledZoneId[];
+    writes: BuiltinCompiledZoneId[];
+}
+export declare function listBuiltinCompiledZoneSpecs(): BuiltinCompiledZoneSpec[];
+export declare function listBuiltinCompiledFallbackStages(): BuiltinCompiledStageAccessPattern[];
+export declare function requiredCompiledZoneOwners<TStage extends {
+    id: string;
+    writes: readonly string[];
+}>(stages: readonly TStage[], zoneId: BuiltinCompiledZoneId): string[];
+export { COMPILED_ZONE_KINDS };

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

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { readJsonFileWithSchema } from "../../lib/parse.js";
+import { COMPILED_ZONE_KINDS } from "../compiler/workflow-primitives.js";
+import { WorkflowCompiledSchemaSchema } from "../compiler/lib/schema.js";
+import { PACKAGE_ROOT } from "./lib/package-root.js";
+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",
+};
+const BUILTIN_ZONE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_ZONE_IDS));
+const BUILTIN_STAGE_ID_SET = new Set(Object.values(BUILTIN_COMPILED_STAGE_IDS));
+const BuiltinWorkflowStageSchema = z.object({
+    id: z.string(),
+    contract_type: z.string(),
+    reads: z.array(z.string()).min(1),
+    writes: z.array(z.string()).min(1),
+});
+const BuiltinWorkflowPackageSchema = z.object({
+    stages: z.array(BuiltinWorkflowStageSchema).min(1),
+});
+let builtinCompiledContractCache = null;
+function builtinWorkflowRootPath() {
+    return join(PACKAGE_ROOT, "builtin-workflows", "interf");
+}
+function builtinWorkflowPath(relativePath) {
+    return join(builtinWorkflowRootPath(), relativePath);
+}
+function assertBuiltinZoneId(value) {
+    if (!BUILTIN_ZONE_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf workflow schema declares unsupported zone id "${value}".`);
+    }
+    return value;
+}
+function assertBuiltinStageId(value) {
+    if (!BUILTIN_STAGE_ID_SET.has(value)) {
+        throw new Error(`Built-in Interf workflow package declares unsupported stage id "${value}".`);
+    }
+    return value;
+}
+function loadBuiltinCompiledContract() {
+    if (builtinCompiledContractCache)
+        return builtinCompiledContractCache;
+    const schema = readJsonFileWithSchema(builtinWorkflowPath("workflow.schema.json"), "built-in Interf workflow schema", WorkflowCompiledSchemaSchema);
+    if (!schema) {
+        throw new Error(`Missing or invalid built-in workflow schema at ${builtinWorkflowPath("workflow.schema.json")}.`);
+    }
+    const workflow = readJsonFileWithSchema(builtinWorkflowPath("workflow.json"), "built-in Interf workflow package", BuiltinWorkflowPackageSchema);
+    if (!workflow) {
+        throw new Error(`Missing or invalid built-in workflow package at ${builtinWorkflowPath("workflow.json")}.`);
+    }
+    const zones = schema.zones.map((zone) => ({
+        id: assertBuiltinZoneId(zone.id),
+        role: zone.role,
+        path: zone.path,
+        kind: zone.kind,
+        required: zone.required,
+        description: zone.description,
+    }));
+    const stages = workflow.stages.map((stage) => ({
+        id: assertBuiltinStageId(stage.id),
+        contract_type: stage.contract_type,
+        reads: stage.reads.map(assertBuiltinZoneId),
+        writes: stage.writes.map(assertBuiltinZoneId),
+    }));
+    builtinCompiledContractCache = { zones, stages };
+    return builtinCompiledContractCache;
+}
+export function listBuiltinCompiledZoneSpecs() {
+    return loadBuiltinCompiledContract().zones.map((zone) => ({ ...zone }));
+}
+export function listBuiltinCompiledFallbackStages() {
+    return loadBuiltinCompiledContract().stages.map((stage) => ({
+        ...stage,
+        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 };