@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/runtime/auth/workos-client.js

@@ -0,0 +1,87 @@
+/**
+ * WorkOS SDK wrapper.
+ *
+ * Reads config from env at lazy-init time. The engine and CLI never import
+ * `@workos-inc/node` directly — they go through `getWorkOS()` so the provider
+ * stays behind one seam.
+ *
+ * Two modes:
+ *   - **Public Client (CLI / desktop / loopback engine)**: only
+ *     `WORKOS_CLIENT_ID` required. PKCE replaces the missing client secret.
+ *     This is the path `interf auth login` drives.
+ *   - **Confidential Client (cloud control plane)**: both `WORKOS_API_KEY`
+ *     and `WORKOS_CLIENT_ID` required. Phase 2; not exercised by the local
+ *     engine.
+ *
+ * Optional `WORKOS_ISSUER` overrides the AuthKit base URL (defaults to the
+ * production WorkOS API). Used for the JWKS URL and for any direct HTTP
+ * call we make outside the SDK.
+ */
+import { WorkOS } from "@workos-inc/node";
+export class WorkOSConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkOSConfigError";
+    }
+}
+let cachedConfig = null;
+let cachedClient = null;
+/** Reset cached config + client. Test seam. */
+export function resetWorkOSCache() {
+    cachedConfig = null;
+    cachedClient = null;
+}
+/**
+ * Load + validate WorkOS config from the environment.
+ *
+ * `WORKOS_CLIENT_ID` is always required. `WORKOS_API_KEY` is optional —
+ * leave it unset for CLI/Public Client mode. Set it only on the cloud
+ * control plane.
+ *
+ * Throws WorkOSConfigError with an actionable message when the client id
+ * is missing.
+ */
+export function workosConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    const rawApiKey = (process.env.WORKOS_API_KEY ?? "").trim();
+    const clientId = (process.env.WORKOS_CLIENT_ID ?? "").trim();
+    const issuer = (process.env.WORKOS_ISSUER ?? "https://api.workos.com").replace(/\/$/, "");
+    if (!clientId) {
+        throw new WorkOSConfigError("Missing WORKOS_CLIENT_ID. Set it before running `interf auth login`, " +
+            "or use `interf auth login --dev-stub <email>` for local-only sessions.");
+    }
+    cachedConfig = {
+        apiKey: rawApiKey.length > 0 ? rawApiKey : null,
+        clientId,
+        issuer,
+    };
+    return cachedConfig;
+}
+/**
+ * Get a singleton WorkOS SDK client.
+ *
+ * Public Client Mode is the default when no API key is configured —
+ * matches the upstream SDK pattern for browser / mobile / CLI / desktop
+ * apps that cannot securely store a client secret.
+ */
+export function getWorkOS() {
+    if (cachedClient)
+        return cachedClient;
+    const cfg = workosConfig();
+    if (cfg.apiKey) {
+        cachedClient = new WorkOS(cfg.apiKey, { clientId: cfg.clientId });
+    }
+    else {
+        cachedClient = new WorkOS({ clientId: cfg.clientId });
+    }
+    return cachedClient;
+}
+/**
+ * Test seam — inject a stub `WorkOS` instance so tests can drive the
+ * auth flow without touching the live SDK or env. Pass `null` to
+ * restore lazy init.
+ */
+export function setWorkOSClientForTests(client) {
+    cachedClient = client;
+}

package/dist/packages/runtime/benchmark-question-draft.d.ts

@@ -0,0 +1,20 @@
+import type { AgentExecutor } from "./agents/lib/executors.js";
+import type { BenchmarkCheck } from "../projects/lib/schema.js";
+export declare function buildBenchmarkQuestionDraftPrompt(options: {
+    projectName: string;
+    sourceFolderPath: string;
+    intent?: string;
+    outputPath: string;
+    targetCount: number;
+}): string;
+export declare function draftBenchmarkQuestions(options: {
+    projectName: string;
+    sourceFolderPath: string;
+    intent?: string;
+    executor: AgentExecutor;
+    targetCount?: number;
+    onStatus?: (line: string) => void;
+}): Promise<{
+    checks: BenchmarkCheck[] | null;
+    error?: string;
+}>;

package/dist/packages/runtime/benchmark-question-draft.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+const DraftBenchmarkQuestionSchema = z.object({
+    question: z.string().min(1),
+    answer: z.string().min(1),
+}).strict();
+const DraftBenchmarkQuestionsSchema = z.array(DraftBenchmarkQuestionSchema).min(1).max(8);
+export function buildBenchmarkQuestionDraftPrompt(options) {
+    const normalizedIntent = options.intent?.trim();
+    const taskLines = normalizedIntent
+        ? [
+            `Primary agent task: ${normalizedIntent}`,
+            "Draft benchmark questions that directly measure whether a local agent can recover the task-critical facts from the source files.",
+            "Prefer questions that would make a human confident the Context Graph is useful for that exact job.",
+        ]
+        : [
+            "No primary agent task was provided.",
+            "Prefer broad, representative benchmark questions that reflect the facts a human would verify from this Source.",
+        ];
+    return [
+        "You are drafting Interf benchmark questions for a local Source.",
+        "Read `runtime/source-locator.json`, then inspect the Source through your own available tools.",
+        "Draft a small set of Q&A / fact-check questions that a human can verify from the source files.",
+        "Do not ask follow-up questions.",
+        "Keep the questions concrete, explicit, and useful for measuring whether an agent can reason correctly over the files in this Source.",
+        "",
+        `Project id: ${options.projectName}`,
+        `Source locator: ${options.sourceFolderPath}`,
+        ...taskLines,
+        "",
+        `Write exactly one JSON array to ${JSON.stringify(options.outputPath)}.`,
+        `Draft ${options.targetCount} benchmark questions unless the Source is too small; in that case write fewer.`,
+        "Each array item must be an object with exactly these keys:",
+        '- "question": a plain-English question answerable from this Source',
+        '- "answer": the expected correct answer in plain English',
+        "",
+        "Quality bar:",
+        "- If a primary task was provided, make most questions directly relevant to that task.",
+        "- Prefer facts, comparisons, or small derived calculations with clear expected answers.",
+        "- Prefer values that are easy for a human to cross-check in the source files.",
+        "- Prefer explicit chart labels, table cells, headings, totals, and directly stated comparisons.",
+        "- Avoid unstable superlatives unless the source itself clearly states the ranking in one place.",
+        "- Avoid questions where the expected answer depends on scanning many pages for a hidden exception or a larger outlier.",
+        "- Avoid vague essay questions, open-ended opinions, or anything requiring outside knowledge.",
+        "- Avoid duplicate questions that cover the same fact in slightly different words.",
+        "",
+        "Output rules:",
+        "- JSON only in the output file.",
+        "- No markdown fences.",
+        "- Do not print the JSON to stdout.",
+        "- Stop after writing the file.",
+    ].join("\n");
+}
+export async function draftBenchmarkQuestions(options) {
+    const tempDir = mkdtempSync(join(tmpdir(), "interf-benchmark-question-draft-"));
+    mkdirSync(join(tempDir, "runtime"), { recursive: true });
+    const outputPath = join(tempDir, "questions.json");
+    const promptPath = join(tempDir, "prompt.txt");
+    writeFileSync(join(tempDir, "runtime", "source-locator.json"), `${JSON.stringify({
+        kind: "interf-source-locator",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        project: options.projectName,
+        source: {
+            kind: "local-folder",
+            locator: options.sourceFolderPath,
+        },
+        note: "Interf does not pre-scan Source files for benchmark drafting. The drafting agent inspects this locator through its own Source access.",
+    }, null, 2)}\n`);
+    const prompt = buildBenchmarkQuestionDraftPrompt({
+        projectName: options.projectName,
+        sourceFolderPath: options.sourceFolderPath,
+        intent: options.intent,
+        outputPath,
+        targetCount: options.targetCount ?? 4,
+    });
+    writeFileSync(promptPath, `${prompt}\n`);
+    try {
+        const code = await options.executor.execute(tempDir, prompt, {
+            completionCheck: () => existsSync(outputPath),
+            onStatus: options.onStatus,
+        });
+        if (!existsSync(outputPath)) {
+            return {
+                checks: null,
+                error: code === 0
+                    ? "The local agent finished without writing draft benchmark questions."
+                    : "The local agent did not produce draft benchmark questions.",
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(outputPath, "utf8"));
+        }
+        catch (error) {
+            return {
+                checks: null,
+                error: `Draft benchmark questions were not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        const validated = DraftBenchmarkQuestionsSchema.safeParse(parsed);
+        if (!validated.success) {
+            const detail = validated.error.issues[0]?.message ?? "invalid draft benchmark questions";
+            return {
+                checks: null,
+                error: `Draft benchmark questions did not match the required shape: ${detail}`,
+            };
+        }
+        return {
+            checks: validated.data,
+        };
+    }
+    catch (error) {
+        return {
+            checks: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}

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

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

package/dist/packages/{engine → runtime}/build/artifact-counts.js

@@ -1,11 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
-import { verifiableContextArtifactAbsolutePath } from "./verifiable-context-schema.js";
+import { contextGraphArtifactAbsolutePath } from "./context-graph-schema.js";
 const SCAFFOLD_PLACEHOLDER_SNIPPETS = [
-    "Not yet built. Run `interf build` to build the verifiable context.",
-    "Not yet built. Run `interf build` to build this verifiable context.",
-    "Not yet built. Run `interf build` to build the verifiable context.",
-    "Not yet built. Run `interf build` to build this verifiable context.",
+    "Not yet built. Run `interf build` to build the Context Graph.",
+    "Not yet built. Run `interf build` to build this Context Graph.",
 ];
 function isScaffoldPlaceholderFile(filePath) {
     try {
@@ -16,14 +14,12 @@ function isScaffoldPlaceholderFile(filePath) {
         return false;
     }
 }
-export function countBuildArtifactsAtPath(verifiableContextPath, artifactPath, kind) {
-    const absolutePath = verifiableContextArtifactAbsolutePath(verifiableContextPath, { path: artifactPath });
+export function countBuildArtifactsAtPath(contextGraphPath, artifactPath, kind) {
+    const absolutePath = contextGraphArtifactAbsolutePath(contextGraphPath, { path: artifactPath });
     if (!existsSync(absolutePath))
         return 0;
     if (kind === "file")
         return isScaffoldPlaceholderFile(absolutePath) ? 0 : 1;
-    if (kind === "runtime")
-        return listFilesRecursive(absolutePath).length;
     return listFilesRecursive(absolutePath)
         .filter((filePath) => !isScaffoldPlaceholderFile(filePath))
         .length;

package/dist/packages/{engine → runtime}/build/artifact-status.d.ts

@@ -2,20 +2,20 @@ import type { ArtifactStatus } from "../../contracts/lib/schema.js";
 import type { BuildPlanDefinition } from "../../build-plans/package/build-plan-definitions.js";
 import type { StageRun } from "../execution/lib/schema.js";
 /**
- * 0.17 — compute per-Artifact status for a Build run.
+ * compute per-Artifact status for a Build run.
  *
  * Walks the Build Plan's declared `artifacts[]` and decides
  * `ready | not_ready | failed | skipped` for each.
  *
  * Mapping rules:
  * - **shape kind = "path"**: the artifact is `ready` when the declared
- *   path exists inside `verifiableContextPath` with the declared artifact kind,
+ *   path exists inside `contextGraphPath` with the declared artifact kind,
  *   `not_ready` otherwise. Future shape kinds (value, remote-handle,
  *   confirmation) slot in here.
  * - **`built_by_stages`** is preserved from the Build Plan declaration when
  *   present, otherwise inferred from stage `writes` that match the
  *   artifact's path.
- * - **proofs** carries structured evidence from the shared check
+ * - **check_results** carries structured evidence from the shared check
  *   evaluator.
  *
  * Stage-failure short-circuit: if any stage has `status: "failed"`, all
@@ -24,7 +24,7 @@ import type { StageRun } from "../execution/lib/schema.js";
  */
 export declare function computeArtifactStatuses(options: {
     buildPlan: Pick<BuildPlanDefinition<string>, "stages" | "contextInterface" | "schema">;
-    verifiableContextPath: string;
+    contextGraphPath: string;
     stageRuns: StageRun[];
     /**
      * Optional runtime counts (e.g. `source_total`) passed to checks
@@ -35,7 +35,7 @@ export declare function computeArtifactStatuses(options: {
 }): ArtifactStatus[];
 /**
  * Aggregate verdict: any artifact in `not_ready | failed | skipped`
- * makes the preparation `not_ready`. Used by the readiness state view
+ * makes the project `not_ready`. Used by the readiness state view
  * once Phase D lights up the per-artifact UI.
  */
 export declare function aggregateArtifactVerdict(statuses: readonly ArtifactStatus[]): "ready" | "not_ready";

package/dist/packages/{engine → runtime}/build/artifact-status.js

@@ -1,21 +1,22 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
 import { evaluateChecks } from "./check-evaluator.js";
 /**
- * 0.17 — compute per-Artifact status for a Build run.
+ * compute per-Artifact status for a Build run.
  *
  * Walks the Build Plan's declared `artifacts[]` and decides
  * `ready | not_ready | failed | skipped` for each.
  *
  * Mapping rules:
  * - **shape kind = "path"**: the artifact is `ready` when the declared
- *   path exists inside `verifiableContextPath` with the declared artifact kind,
+ *   path exists inside `contextGraphPath` with the declared artifact kind,
  *   `not_ready` otherwise. Future shape kinds (value, remote-handle,
  *   confirmation) slot in here.
  * - **`built_by_stages`** is preserved from the Build Plan declaration when
  *   present, otherwise inferred from stage `writes` that match the
  *   artifact's path.
- * - **proofs** carries structured evidence from the shared check
+ * - **check_results** carries structured evidence from the shared check
  *   evaluator.
  *
  * Stage-failure short-circuit: if any stage has `status: "failed"`, all
@@ -31,7 +32,7 @@ export function computeArtifactStatuses(options) {
     const anyStageFailed = options.stageRuns.some((stage) => stage.status === "failed");
     return artifacts.map((artifact) => buildArtifactStatus({
         artifact,
-        verifiableContextPath: options.verifiableContextPath,
+        contextGraphPath: options.contextGraphPath,
         stageWriteIndex,
         anyStageFailed,
         counts: options.counts,
@@ -53,16 +54,16 @@ function buildStageWriteIndex(stages) {
     return index;
 }
 function buildArtifactStatus(options) {
-    const { artifact, verifiableContextPath, stageWriteIndex, anyStageFailed, counts } = options;
+    const { artifact, contextGraphPath, stageWriteIndex, anyStageFailed, counts } = options;
     const builtBy = artifact.built_by_stages.length > 0
         ? artifact.built_by_stages
         : inferBuiltByStages(artifact, stageWriteIndex);
     const shapeStatus = resolveStatusValue({
         artifact,
-        verifiableContextPath,
+        contextGraphPath,
         anyStageFailed,
     });
-    // Run the locked CheckKind evaluator against artifact.checks. Proofs
+    // Run the locked CheckKind evaluator against artifact.checks. CheckResults
     // are surfaced for each declared check; if any required check fails,
     // the artifact's status is forced to failed (or not_ready if the
     // shape itself isn't built yet).
@@ -73,11 +74,11 @@ function buildArtifactStatus(options) {
     const declaredChecks = artifact.checks ?? [];
     const checkResult = declaredChecks.length > 0
         ? evaluateChecks(declaredChecks, {
-            rootPath: verifiableContextPath,
+            rootPath: contextGraphPath,
             targetPath,
             counts,
         })
-        : { proofs: [], ready: true, failures: [] };
+        : { check_results: [], ready: true, failures: [] };
     const status = (() => {
         if (shapeStatus !== "ready")
             return shapeStatus;
@@ -89,7 +90,7 @@ function buildArtifactStatus(options) {
         artifact_id: artifact.id,
         status,
         built_by_stages: builtBy,
-        proofs: checkResult.proofs,
+        check_results: checkResult.check_results,
         ...(buildSummary(artifact, status, checkResult.failures.length)),
     };
 }
@@ -116,17 +117,17 @@ function inferBuiltByStages(artifact, stageWriteIndex) {
     return pathOwners ?? [];
 }
 function resolveStatusValue(options) {
-    const { artifact, verifiableContextPath, anyStageFailed } = options;
+    const { artifact, contextGraphPath, anyStageFailed } = options;
     if (artifact.shape.kind !== "path")
         return "skipped";
-    const verifiableContextRoot = resolve(verifiableContextPath);
-    const absolutePath = resolve(verifiableContextRoot, artifact.shape.path);
+    const contextGraphRoot = resolve(contextGraphPath);
+    const absolutePath = resolve(contextGraphRoot, artifact.shape.path);
     // Defense in depth: the schema-level `isInterfRelativePath` refine
     // already rejects `..` and absolute paths in `ArtifactPathShape.path`,
     // but Build Plan packages can land on disk before the schema validates
     // (hand-edited drafts can still bypass normal package validation).
-    // Reject any resolved path that escapes the verifiable-context root.
-    if (absolutePath !== verifiableContextRoot && !absolutePath.startsWith(`${verifiableContextRoot}/`)) {
+    // Reject any resolved path that escapes the context-graph root.
+    if (absolutePath !== contextGraphRoot && !absolutePath.startsWith(`${contextGraphRoot}/`)) {
         return "failed";
     }
     if (!existsSync(absolutePath)) {
@@ -134,13 +135,14 @@ function resolveStatusValue(options) {
     }
     try {
         const info = statSync(absolutePath);
-        // For directory artifacts, ready means the directory exists; the
-        // directory may be empty during early stages, but content-shape
-        // checks live in artifact `checks[]`, not here. For file artifacts,
-        // the file must have non-zero bytes —
-        // an empty placeholder is not_ready.
-        if (artifact.shape.artifact_kind === "directory" && info.isDirectory())
-            return "ready";
+        // Directory artifacts must contain at least one real file. A bare
+        // directory is only a placeholder and should not make a mandatory
+        // graph layer look ready.
+        if (artifact.shape.artifact_kind === "directory" && info.isDirectory()) {
+            return listFilesRecursive(absolutePath, () => true).length > 0
+                ? "ready"
+                : anyStageFailed ? "failed" : "not_ready";
+        }
         if (artifact.shape.artifact_kind === "file" && info.isFile() && info.size > 0)
             return "ready";
         return anyStageFailed ? "failed" : "not_ready";
@@ -156,7 +158,7 @@ function describeShape(artifact) {
 }
 /**
  * Aggregate verdict: any artifact in `not_ready | failed | skipped`
- * makes the preparation `not_ready`. Used by the readiness state view
+ * makes the project `not_ready`. Used by the readiness state view
  * once Phase D lights up the per-artifact UI.
  */
 export function aggregateArtifactVerdict(statuses) {

package/dist/packages/runtime/build/atomic-fs.d.ts

@@ -0,0 +1,3 @@
+export declare function writeFileAtomic(path: string, data: string | Buffer, mode?: number): void;
+export declare function writeJsonAtomic(path: string, value: unknown): void;
+export declare function appendJsonlAtomic(path: string, record: unknown): void;

package/dist/packages/runtime/build/atomic-fs.js

@@ -0,0 +1,95 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, truncateSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname } from "node:path";
+function removeTempFile(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Best-effort cleanup. Preserve the original write error.
+    }
+}
+function replaceWithTempFile(tmpPath, targetPath) {
+    try {
+        renameSync(tmpPath, targetPath);
+        return;
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        if (process.platform === "win32" && (code === "EEXIST" || code === "EPERM")) {
+            rmSync(targetPath, { force: true });
+            renameSync(tmpPath, targetPath);
+            return;
+        }
+        throw error;
+    }
+}
+function fsyncDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    let fd = null;
+    try {
+        fd = openSync(path, "r");
+        fsyncSync(fd);
+    }
+    catch {
+        // Directory fsync is best-effort across filesystems. The temp-file fsync
+        // above still protects readers from torn file contents.
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function repairJsonlTail(path) {
+    if (!existsSync(path))
+        return;
+    const content = readFileSync(path, "utf8");
+    if (content.length === 0 || content.endsWith("\n"))
+        return;
+    const lastNewline = content.lastIndexOf("\n");
+    const completePrefix = lastNewline === -1 ? "" : content.slice(0, lastNewline + 1);
+    truncateSync(path, Buffer.byteLength(completePrefix, "utf8"));
+}
+export function writeFileAtomic(path, data, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    let fd = null;
+    try {
+        fd = openSync(tmpPath, "w", mode);
+        writeFileSync(fd, data);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = null;
+        replaceWithTempFile(tmpPath, path);
+        fsyncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Preserve the original write/rename error.
+            }
+        }
+        removeTempFile(tmpPath);
+        throw error;
+    }
+}
+export function writeJsonAtomic(path, value) {
+    writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function appendJsonlAtomic(path, record) {
+    mkdirSync(dirname(path), { recursive: true });
+    repairJsonlTail(path);
+    const fd = openSync(path, "a");
+    try {
+        writeSync(fd, `${JSON.stringify(record)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import type { ArtifactStatus } from "../../contracts/lib/schema.js";
+/**
+ * Per-Artifact billing event record.
+ *
+ * Emitted once per Artifact each time a Build run produces it.
+ * `account_id` is `null` for loopback engines; hosted variants can fill it
+ * from the service auth layer.
+ */
+export declare const BillingEventKindSchema: z.ZodEnum<{
+    fresh: "fresh";
+    resync: "resync";
+}>;
+export declare const BuildBillingEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-build-billing-event">;
+    version: z.ZodLiteral<1>;
+    timestamp: z.ZodString;
+    run_id: z.ZodString;
+    project: 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 BuildBillingEvent = z.infer<typeof BuildBillingEventSchema>;
+export type BillingEventKind = z.infer<typeof BillingEventKindSchema>;
+/**
+ * Sink for billing events.
+ *
+ * The local default writes an observability fixture at
+ * `.interf/runtime/billing-events/<run-id>/billing-events.jsonl`. Hosted
+ * variants can inject a remote sink through `startLocalService` options; the
+ * engine treats either implementation identically.
+ */
+export interface BillingEventSink {
+    emit(event: BuildBillingEvent): void;
+}
+export declare class JsonlBillingEventSink implements BillingEventSink {
+    private readonly logPath;
+    constructor(logPath: string);
+    emit(event: BuildBillingEvent): void;
+}
+/**
+ * Default sink path for a run. Each Build run gets its own JSONL
+ * file under hidden runtime metadata, not beside agent-facing Artifacts.
+ */
+export declare function defaultBillingEventLogPath(options: {
+    projectDataDir: string;
+    projectName: string;
+    runId: string;
+}): string;
+/**
+ * Convert a list of per-Artifact statuses into build 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.
+ *
+ * Local builds currently emit `event_kind: "fresh"` only. The `resync` value is
+ * reserved for incremental rebuilds.
+ */
+export declare function buildBillingEventsForRun(options: {
+    runId: string;
+    project: string;
+    buildPlanId: string;
+    accountId: string | null;
+    artifacts: readonly ArtifactStatus[];
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    timestamp?: string;
+}): BuildBillingEvent[];