@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/engine/agents/lib/verifiable-context-bootstrap.d.ts

@@ -1,3 +0,0 @@
-import { renderClaudeBootstrap } from "./shells.js";
-export { renderClaudeBootstrap };
-export declare function refreshVerifiableContextBootstrapGuidance(dirPath: string): boolean;

package/dist/packages/engine/build/artifact-counts.d.ts

@@ -1 +0,0 @@
-export declare function countBuildArtifactsAtPath(verifiableContextPath: string, artifactPath: string, kind: "directory" | "file" | "runtime"): number;

package/dist/packages/engine/build/billing-events.d.ts

@@ -1,89 +0,0 @@
-import { z } from "zod";
-import type { ArtifactStatus } from "../../contracts/lib/schema.js";
-/**
- * 0.17 — per-Artifact billing event record.
- *
- * Emitted once per Artifact each time a Build run produces it.
- * `account_id` is `null` for loopback (no auth); the cloud variant
- * fills it from the `tokenValidator` (B4.3) result.
- *
- * `event_kind`:
- * - `fresh` — first-time build of this Artifact in this run
- * - `resync` — incremental rebuild (deferred to 0.18+; not emitted in 0.17)
- */
-export declare const BillingEventKindSchema: z.ZodEnum<{
-    fresh: "fresh";
-    resync: "resync";
-}>;
-export declare const CompilationEventSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"interf-compilation-event">;
-    version: z.ZodLiteral<1>;
-    timestamp: z.ZodString;
-    run_id: z.ZodString;
-    preparation: z.ZodString;
-    artifact_id: z.ZodString;
-    build_plan_id: z.ZodString;
-    account_id: z.ZodNullable<z.ZodString>;
-    event_kind: z.ZodEnum<{
-        fresh: "fresh";
-        resync: "resync";
-    }>;
-    size_class: z.ZodOptional<z.ZodEnum<{
-        small: "small";
-        medium: "medium";
-        large: "large";
-    }>>;
-    duration_ms: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
-export type CompilationEvent = z.infer<typeof CompilationEventSchema>;
-export type BillingEventKind = z.infer<typeof BillingEventKindSchema>;
-/**
- * Sink for billing events.
- *
- * **STUB FOR 0.17 — JSONL local default.** Production sink (Metronome
- * HTTP) wires in 0.18+ once the Stripe + Metronome accounts are
- * provisioned. The `<prep>/runs/<run-id>/billing-events.jsonl` file is
- * an **observability / dev fixture, NOT production billing data**.
- * Future readers must not treat it as authoritative — Stripe Billing
- * holds the books once 0.18 ships the HTTP sink.
- *
- * Cloud variants inject a remote sink via `startLocalService` options
- * (paired with the `BillingEventSink` injection point in B4-style
- * dependency injection); the engine treats either implementation
- * identically.
- */
-export interface BillingEventSink {
-    emit(event: CompilationEvent): void;
-}
-export declare class JsonlBillingEventSink implements BillingEventSink {
-    private readonly logPath;
-    constructor(logPath: string);
-    emit(event: CompilationEvent): void;
-}
-/**
- * Default sink path for a run. Each Build run gets its own JSONL
- * file alongside its other on-disk artifacts.
- */
-export declare function defaultBillingEventLogPath(options: {
-    preparationDataDir: string;
-    preparationName: string;
-    runId: string;
-}): string;
-/**
- * Convert a list of per-Artifact statuses into compilation events for
- * the run. Only `ready` and `failed` artifacts emit events — `skipped`
- * and `not_ready` represent work that didn't happen and shouldn't bill.
- *
- * 0.17 ships `event_kind: "fresh"` only. The resync optimization that
- * differentiates cached-vs-rebuilt artifacts lands in 0.18+.
- */
-export declare function buildCompilationEventsForRun(options: {
-    runId: string;
-    preparation: string;
-    buildPlanId: string;
-    accountId: string | null;
-    artifacts: readonly ArtifactStatus[];
-    startedAt?: string | null;
-    finishedAt?: string | null;
-    timestamp?: string;
-}): CompilationEvent[];

package/dist/packages/engine/build/build-pipeline.js

@@ -1,175 +0,0 @@
-import { refreshVerifiableContextBootstrapGuidance, } from "../agents/lib/verifiable-context-bootstrap.js";
-import { validateBuildPlanPackage } from "../../build-plans/package/local-build-plans.js";
-import { reportValidationFailure, } from "../../build-plans/package/build-plan-helpers.js";
-import { validateVerifiableContext, } from "./validate.js";
-import { pruneStageExecutionShells, } from "../agents/lib/shells.js";
-import { resetBuildGeneratedState } from "./reset.js";
-import { buildExecutionStages, resolveBuildContext, } from "./build-target.js";
-import { discoverSourceFiles } from "./discovery.js";
-import { runBuildStage } from "./build-stage-runner.js";
-import { resolveSourceInputPath } from "../../project/interf-detect.js";
-import { buildPlanPackagePathForVerifiableContext } from "./verifiable-context-paths.js";
-import { writeBuildSourceRuntime } from "./source-files.js";
-function pickStageExecutor(fallback, stage, resolve) {
-    if (!resolve)
-        return fallback;
-    try {
-        return resolve(stage) ?? fallback;
-    }
-    catch {
-        return fallback;
-    }
-}
-export async function runBuildSummarize(options) {
-    const context = resolveBuildContext(options.verifiableContextPath);
-    const stageDefinition = options.stageDefinition
-        ?? buildExecutionStages(context.buildPlanId, options.verifiableContextPath).find((stage) => stage.id === "summarize");
-    if (!stageDefinition) {
-        return {
-            ok: false,
-            code: 1,
-            plan: { sourceCount: 0, summaryCount: 0, targetCount: 0 },
-            summary: "Build Plan does not declare a summarize stage.",
-        };
-    }
-    const sourceCount = discoverSourceFiles(context.sourcePath, options.verifiableContextPath).totalCount;
-    writeBuildSourceRuntime({
-        verifiableContextPath: options.verifiableContextPath,
-        buildPlanId: context.buildPlanId,
-        stageIds: [stageDefinition.id],
-        sourcePath: context.sourcePath,
-        runId: options.runId ?? null,
-    });
-    const result = await runBuildStage({
-        executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
-        verifiableContextPath: options.verifiableContextPath,
-        reporter: options.reporter,
-        reportStep: options.reportStep,
-        stageDefinition,
-        runId: options.runId,
-        events: options.events,
-    });
-    return {
-        ...result,
-        plan: {
-            sourceCount,
-            summaryCount: 0,
-            targetCount: sourceCount,
-        },
-    };
-}
-export async function runBuildStages(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
-    if (preserveMode !== "always") {
-        pruneStageExecutionShells(options.verifiableContextPath);
-    }
-    let lastResult = { ok: true, code: 0 };
-    try {
-        const context = resolveBuildContext(options.verifiableContextPath);
-        const stages = buildExecutionStages(context.buildPlanId, options.verifiableContextPath);
-        writeBuildSourceRuntime({
-            verifiableContextPath: options.verifiableContextPath,
-            buildPlanId: context.buildPlanId,
-            stageIds: stages.map((stage) => stage.id),
-            sourcePath: context.sourcePath,
-            runId: options.runId ?? null,
-        });
-        for (const [index, stageDefinition] of stages.entries()) {
-            const result = await runBuildStage({
-                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
-                verifiableContextPath: options.verifiableContextPath,
-                reporter: options.reporter,
-                reportStep: options.reportStep,
-                stageDefinition,
-                runId: options.runId,
-                events: options.events,
-                stageIndex: index,
-                stageTotal: stages.length,
-            });
-            lastResult = result;
-            if (!result.ok)
-                return result;
-        }
-        return lastResult;
-    }
-    finally {
-        if (preserveMode !== "always" && lastResult.ok) {
-            pruneStageExecutionShells(options.verifiableContextPath);
-        }
-    }
-}
-export async function buildVerifiableContext(options) {
-    const preserveMode = options.preserveStageShells ?? "on-failure";
-    resetBuildGeneratedState(options.verifiableContextPath, "build");
-    if (preserveMode !== "always") {
-        pruneStageExecutionShells(options.verifiableContextPath);
-    }
-    let result = {
-        ok: true,
-        stageResults: {},
-        failedStage: null,
-    };
-    try {
-        refreshVerifiableContextBootstrapGuidance(options.verifiableContextPath);
-        const buildPlanValidation = validateBuildPlanPackage(buildPlanPackagePathForVerifiableContext(options.verifiableContextPath));
-        if (!buildPlanValidation.ok) {
-            reportValidationFailure(options.reporter, buildPlanValidation.summary, buildPlanValidation.errors);
-            return {
-                ...result,
-                ok: false,
-                failedStage: "build-plan",
-                stageResults: {
-                    ...result.stageResults,
-                    "build-plan": {
-                        ok: false,
-                        code: 1,
-                        summary: buildPlanValidation.summary,
-                    },
-                },
-            };
-        }
-        const context = resolveBuildContext(options.verifiableContextPath);
-        const sourceInputPath = resolveSourceInputPath(options.verifiableContextPath);
-        const stages = buildExecutionStages(context.buildPlanId, options.verifiableContextPath);
-        writeBuildSourceRuntime({
-            verifiableContextPath: options.verifiableContextPath,
-            buildPlanId: context.buildPlanId,
-            stageIds: stages.map((stage) => stage.id),
-            sourcePath: sourceInputPath,
-            runId: options.runId ?? null,
-        });
-        for (const [index, stageDefinition] of stages.entries()) {
-            const stageResult = await runBuildStage({
-                executor: pickStageExecutor(options.executor, stageDefinition, options.resolveStageExecutor),
-                verifiableContextPath: options.verifiableContextPath,
-                reporter: options.reporter,
-                reportStep: true,
-                stageDefinition,
-                runId: options.runId,
-                events: options.events,
-                stageIndex: index,
-                stageTotal: stages.length,
-            });
-            result.stageResults[stageDefinition.id] = stageResult;
-            if (!stageResult.ok) {
-                result.ok = false;
-                result.failedStage = stageDefinition.id;
-                return result;
-            }
-        }
-        const buildPlanValidationResult = validateVerifiableContext(options.verifiableContextPath);
-        result.ok = buildPlanValidationResult.ok;
-        result.failedStage = buildPlanValidationResult.ok ? null : buildPlanValidationResult.stage;
-        result.stageResults["verifiable-context"] = {
-            ok: buildPlanValidationResult.ok,
-            code: buildPlanValidationResult.ok ? 0 : 1,
-            summary: buildPlanValidationResult.summary,
-        };
-        return result;
-    }
-    finally {
-        if (preserveMode !== "always" && result.ok) {
-            pruneStageExecutionShells(options.verifiableContextPath);
-        }
-    }
-}

package/dist/packages/engine/build/build-plan-runs.d.ts

@@ -1,14 +0,0 @@
-import { type InterfConfig } from "../../project/interf-detect.js";
-export type { BuildPlanReporter } from "../../build-plans/package/build-plan-helpers.js";
-export type BuildCheck = "verifiable-context" | "stage";
-export interface DetectedInterfTarget {
-    path: string;
-    kind: "verifiable-context";
-    engineType: "build";
-    config: InterfConfig;
-}
-export declare function detectVerifiableContext(cwd: string): DetectedInterfTarget | null;
-export declare function createVerifiableContext(name: string, sourcePath: string, buildPlanId: string | undefined, about: string | undefined, sourceFolderPath: string): string;
-export declare function verifyBuildCheck(check: BuildCheck, verifiableContextPath: string): import("./validate-verifiable-context.js").VerifiableContextValidation;
-export { runBuildSummarize, runBuildStages, buildVerifiableContext, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";
-export type { BuildSummarizeResult, BuildResult, BuildStageExecutionDefinition, StageShellRetentionMode, ResolveStageExecutor, } from "./build-execution.js";

package/dist/packages/engine/build/build-plan-runs.js

@@ -1,31 +0,0 @@
-import { createVerifiableContext as createVerifiableContextScaffold, } from "../../project/interf-scaffold.js";
-import { detectInterf } from "../../project/interf-detect.js";
-import { validateBuildOutput, } from "./validate.js";
-import { DEFAULT_BUILD_PLAN_ID } from "../../build-plans/build-plan-resolution.js";
-export function detectVerifiableContext(cwd) {
-    const detected = detectInterf(cwd);
-    if (!detected)
-        return null;
-    return {
-        path: detected.path,
-        kind: "verifiable-context",
-        engineType: "build",
-        config: detected.config,
-    };
-}
-export function createVerifiableContext(name, sourcePath, buildPlanId, about, sourceFolderPath) {
-    return createVerifiableContextScaffold(name, sourcePath, buildPlanId ?? DEFAULT_BUILD_PLAN_ID, about, sourceFolderPath);
-}
-export function verifyBuildCheck(check, verifiableContextPath) {
-    switch (check) {
-        case "verifiable-context":
-            return validateBuildOutput(verifiableContextPath);
-        case "stage":
-            return validateBuildOutput(verifiableContextPath);
-        default: {
-            const exhaustiveCheck = check;
-            throw new Error(`Unknown build check: ${exhaustiveCheck}`);
-        }
-    }
-}
-export { runBuildSummarize, runBuildStages, buildVerifiableContext, resolveBuildContext, buildExecutionStages, } from "./build-execution.js";

package/dist/packages/engine/build/build-stage-plan.d.ts

@@ -1,16 +0,0 @@
-import { type RuntimeStageContractDraft } from "./runtime.js";
-import { type BuildPlanStageDefinition } from "../../build-plans/package/build-plan-definitions.js";
-import { resolveBuildContext, type BuildStageExecutionDefinition } from "./build-target.js";
-import type { RuntimeStageInstructions } from "./lib/schema.js";
-export declare function resolveStageContractArtifacts(verifiableContextPath: string, stageDefinition: Pick<BuildPlanStageDefinition, "id" | "reads" | "writes">): {
-    reads: string[];
-    writes: string[];
-    writeContracts: RuntimeStageContractDraft["artifacts"]["write_contracts"];
-};
-export declare function buildStageCounts(verifiableContextPath: string, stageDefinition: BuildPlanStageDefinition): Record<string, number>;
-export declare function buildStageContract(verifiableContextPath: string, stageDefinition: BuildPlanStageDefinition, instructions: RuntimeStageInstructions): RuntimeStageContractDraft;
-export declare function buildBuildStageExecutionPlan(verifiableContextPath: string, stageDefinition: BuildStageExecutionDefinition): {
-    context: ReturnType<typeof resolveBuildContext>;
-    contract: RuntimeStageContractDraft;
-    instructions: RuntimeStageInstructions;
-};

package/dist/packages/engine/build/build-stage-runner.js

@@ -1,94 +0,0 @@
-import { createStageExecutionShell, freezeStageExecutionShell, syncStageExecutionShellWrites, } from "../agents/lib/shells.js";
-import { reconcileBuildStageRun } from "./runtime-reconcile.js";
-import { refreshVerifiableContextArtifacts } from "./state.js";
-import { validateBuildStage } from "./validate.js";
-import { executeValidatedStage, } from "../../build-plans/package/build-plan-stage-runner.js";
-import { formatActiveBuildPlanStageLabel, } from "../../build-plans/package/build-plan-definitions.js";
-import { reportBlankLine, reportLine, } from "../../build-plans/package/build-plan-helpers.js";
-import { buildBuildStageExecutionPlan, } from "./build-stage-plan.js";
-import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
-async function emitRunEvent(sink, event) {
-    await sink?.emit(event);
-}
-export async function runBuildStage(options) {
-    const stageDefinition = options.stageDefinition;
-    const plan = buildBuildStageExecutionPlan(options.verifiableContextPath, stageDefinition);
-    if (options.reportStep !== false) {
-        reportBlankLine(options.reporter);
-        reportLine(options.reporter, `${formatActiveBuildPlanStageLabel(options.verifiableContextPath, stageDefinition.id)} (${stageDefinition.description.toLowerCase()})`);
-    }
-    const shell = createStageExecutionShell(options.verifiableContextPath, plan.context.verifiableContextName, plan.context.buildPlanId, stageDefinition, plan.contract.artifacts.writes);
-    try {
-        if (options.runId && options.events) {
-            await emitRunEvent(options.events, {
-                type: "stage.started",
-                event_id: createRunEventId("event"),
-                run_id: options.runId,
-                timestamp: createRunEventTimestamp(),
-                stage_id: stageDefinition.id,
-                ...(typeof options.stageIndex === "number" ? { stage_index: options.stageIndex } : {}),
-                ...(typeof options.stageTotal === "number" ? { stage_total: options.stageTotal } : {}),
-            });
-        }
-        const result = await executeValidatedStage({
-            executor: options.executor,
-            verifiableContextPath: options.verifiableContextPath,
-            executionPath: shell.rootPath,
-            targetName: plan.context.verifiableContextName,
-            buildPlan: plan.context.buildPlanId,
-            buildPlanSourcePath: options.verifiableContextPath,
-            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 built Artifacts.",
-                `Emit DONE: ${stageDefinition.id} complete when the declared outputs and proof are on disk.`,
-            ],
-            reporter: options.reporter,
-            completionCheck: () => validateBuildStage(options.verifiableContextPath, stageDefinition.id).ok,
-            onStatus: options.runId && options.events
-                ? (line) => {
-                    void options.events?.emit({
-                        type: "log.appended",
-                        event_id: createRunEventId("event"),
-                        run_id: options.runId,
-                        timestamp: createRunEventTimestamp(),
-                        stage_id: stageDefinition.id,
-                        stream: "status",
-                        message: line,
-                    });
-                }
-                : undefined,
-            syncWrites: () => syncStageExecutionShellWrites(options.verifiableContextPath, shell.rootPath, stageDefinition, plan.contract.artifacts.writes),
-            reconcile: () => reconcileBuildStageRun(options.verifiableContextPath, stageDefinition),
-            refreshArtifacts: () => refreshVerifiableContextArtifacts(options.verifiableContextPath, { ensureViewSpec: true }),
-            validate: () => validateBuildStage(options.verifiableContextPath, stageDefinition.id),
-        });
-        if (options.runId && options.events) {
-            await emitRunEvent(options.events, result.ok
-                ? {
-                    type: "stage.passed",
-                    event_id: createRunEventId("event"),
-                    run_id: options.runId,
-                    timestamp: createRunEventTimestamp(),
-                    stage_id: stageDefinition.id,
-                    summary: result.summary ?? `${stageDefinition.label} completed.`,
-                }
-                : {
-                    type: "stage.failed",
-                    event_id: createRunEventId("event"),
-                    run_id: options.runId,
-                    timestamp: createRunEventTimestamp(),
-                    stage_id: stageDefinition.id,
-                    error: result.summary ?? `${stageDefinition.label} failed.`,
-                });
-        }
-        return result;
-    }
-    finally {
-        freezeStageExecutionShell(shell.rootPath);
-    }
-}

package/dist/packages/engine/build/build-target.js

@@ -1,16 +0,0 @@
-import { getActiveBuildPlan, resolveRequiredBuildPlanFromConfig, } from "../../build-plans/package/build-plan-definitions.js";
-import { readInterfConfig, resolveSourceFolderPath, resolveSourceControlPath, } from "../../project/interf-detect.js";
-export function resolveBuildContext(verifiableContextPath) {
-    const config = readInterfConfig(verifiableContextPath);
-    const buildPlanId = resolveRequiredBuildPlanFromConfig(config, `.interf/interf.json for ${verifiableContextPath}`);
-    return {
-        verifiableContextName: config?.name ?? "verifiable-context",
-        sourcePath: resolveSourceFolderPath(verifiableContextPath, config),
-        prepDataDir: resolveSourceControlPath(verifiableContextPath),
-        buildPlanId,
-    };
-}
-export function buildExecutionStages(_buildPlanId, verifiableContextPath) {
-    return getActiveBuildPlan(verifiableContextPath)
-        .stages;
-}