@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/{local-service → engine}/client.js

@@ -1,4 +1,4 @@
-import { CompileRunCreateRequestSchema, CompileRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
+import { CompileRunCreateRequestSchema, CompileRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
 import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, preparationSubresourcePath, } from "./routes.js";
 import { readActiveConnection } from "./connection-config.js";
 async function connectOrNull(options = {}) {
@@ -8,8 +8,8 @@ async function connectOrNull(options = {}) {
     });
     if (!conn)
         return null;
-    // Probe the engine; we expose the LocalServiceHealth-shaped object the
-    // legacy callers expect so submitCompileRun et al. keep compiling.
+    // Probe the engine and surface a LocalServiceHealth object that
+    // submitCompileRun et al. consume.
     try {
         const headers = {};
         if (conn.auth_token)
@@ -102,13 +102,13 @@ export async function submitCompileRunToLocalService(options) {
         resource,
     };
 }
-export async function submitTestRunToLocalService(options) {
+export async function submitVerifyRunToLocalService(options) {
     const connection = await connectOrNull();
     if (!connection)
         return null;
-    const request = TestRunCreateRequestSchema.parse(options.request);
-    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "testRuns")}`;
-    const resource = TestRunResourceSchema.parse(await fetchJson(url, {
+    const request = VerifyRunCreateRequestSchema.parse(options.request);
+    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "verifyRuns")}`;
+    const resource = VerifyRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
         headers: authHeaders(connection.authToken),
@@ -235,19 +235,19 @@ export async function waitForLocalCompileRun(options) {
         }
     }
 }
-export async function getLocalTestRun(options) {
-    return TestRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/test-runs/${encodeURIComponent(options.runId)}`, {
+export async function getLocalVerifyRun(options) {
+    return VerifyRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/verify-runs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
         headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
     }));
 }
-export async function waitForLocalTestRun(options) {
+export async function waitForLocalVerifyRun(options) {
     // Same exponential backoff as `waitForLocalCompileRun`.
     const explicit = options.pollMs;
     let delay = explicit ?? 250;
     while (true) {
-        const resource = await getLocalTestRun({
+        const resource = await getLocalVerifyRun({
             serviceUrl: options.serviceUrl,
             runId: options.runId,
             authToken: options.authToken ?? null,

package/dist/packages/engine/cloud-seams.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 0.17 — interface seams for the future cloud variant.
+ *
+ * These types document the injection points a cloud variant of the
+ * engine slots into without forking. The local binary keeps its
+ * in-process implementations (private `Map` fields on the runtime,
+ * the per-instance bearer-token check in `server.ts`); cloud variants
+ * provide their own implementations and pass them through
+ * `startLocalService` / `LocalServiceRuntimeOptions`.
+ *
+ * Each seam below is paired with a `TODO(cloud)` marker at the
+ * concrete call site so the cloud variant has a clear "wire this
+ * through" landing pad. Local default behavior is unchanged in 0.17.
+ */
+/**
+ * **B4.1 — `IdempotencyStore` (E-1 in the 0.16 architecture audit).**
+ *
+ * Backs the `POST /v1/compile-runs` idempotency-key dedupe cache. The
+ * in-process `Map` cache works for one local engine; multi-replica
+ * cloud needs a shared store (Redis-shaped) so a retry that lands on
+ * a different replica hits the same dedupe entry.
+ *
+ * Local default: in-memory map on the runtime.
+ *
+ * Cloud injection: wrap a Redis client (or equivalent shared store).
+ */
+export interface IdempotencyStore {
+    get(scope: string, key: string): {
+        runId: string;
+        expiresAt: number;
+    } | null;
+    set(scope: string, key: string, value: {
+        runId: string;
+        expiresAt: number;
+    }): void;
+    delete(scope: string, key: string): void;
+    prune(now: number): void;
+    size(): number;
+}
+/**
+ * **B4.2 — `RunLeaseStore` (I-1 in the 0.16 architecture audit).**
+ *
+ * Tracks active compile runs so the engine can cancel them and reject
+ * concurrent run starts on the same preparation. The local default uses
+ * the runtime's `activeCompileRuns` map; multi-replica cloud needs a
+ * shared lease store with heartbeat so a replica can take over a run
+ * whose owning replica died.
+ *
+ * Local default: in-memory map on the runtime.
+ *
+ * Cloud injection: shared lease store with heartbeat (Redis lease,
+ * Cassandra LWT, etc.) plus a `listActive()` heartbeat scan.
+ */
+export interface RunLeaseStore {
+    acquire(runId: string, lease: RunLeaseEntry): void;
+    release(runId: string): void;
+    get(runId: string): RunLeaseEntry | null;
+    markCancelled(runId: string): void;
+    listActive(): Iterable<{
+        runId: string;
+        lease: RunLeaseEntry;
+    }>;
+}
+export interface RunLeaseEntry {
+    prepDataDir: string;
+    preparation: string;
+    cancelled: boolean;
+    cancelledAt?: string;
+}
+/**
+ * **B4.3 — `tokenValidator` (S-2 in the 0.16 architecture audit).**
+ *
+ * Local default: every accepted token is treated equivalently — the
+ * engine carries a single bearer token at startup, and any request
+ * presenting that token is authorized. Cloud needs a per-account
+ * token issuer + validator so the engine can attach an `account_id`
+ * to billing events (Phase F) and scope writes per-account.
+ *
+ * Local default: configured bearer or `null` (loopback).
+ *
+ * Cloud injection: validate against a token-issuer service, return
+ * the `account_id` so downstream code can attach it to runs and
+ * billing events.
+ */
+export type TokenValidator = (token: string) => TokenValidation | Promise<TokenValidation>;
+export interface TokenValidation {
+    ok: boolean;
+    account_id: string | null;
+    reason?: string;
+}
+export declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private buckets;
+    get(scope: string, key: string): {
+        runId: string;
+        expiresAt: number;
+    } | null;
+    set(scope: string, key: string, value: {
+        runId: string;
+        expiresAt: number;
+    }): void;
+    delete(scope: string, key: string): void;
+    prune(now: number): void;
+    size(): number;
+}
+export declare class InMemoryRunLeaseStore implements RunLeaseStore {
+    private leases;
+    acquire(runId: string, lease: RunLeaseEntry): void;
+    release(runId: string): void;
+    get(runId: string): RunLeaseEntry | null;
+    markCancelled(runId: string): void;
+    listActive(): Iterable<{
+        runId: string;
+        lease: RunLeaseEntry;
+    }>;
+}

package/dist/packages/engine/cloud-seams.js

@@ -0,0 +1,84 @@
+/**
+ * 0.17 — interface seams for the future cloud variant.
+ *
+ * These types document the injection points a cloud variant of the
+ * engine slots into without forking. The local binary keeps its
+ * in-process implementations (private `Map` fields on the runtime,
+ * the per-instance bearer-token check in `server.ts`); cloud variants
+ * provide their own implementations and pass them through
+ * `startLocalService` / `LocalServiceRuntimeOptions`.
+ *
+ * Each seam below is paired with a `TODO(cloud)` marker at the
+ * concrete call site so the cloud variant has a clear "wire this
+ * through" landing pad. Local default behavior is unchanged in 0.17.
+ */
+// ───────────────────────────────────────────────────────────────────────────
+// Local default implementations
+//
+// These wrap in-process Maps and satisfy the interfaces above so the
+// runtime can inject either a local default (current behavior) or a
+// cloud override (Redis-shaped store, shared lease, etc) without
+// branching on the deployment.
+// ───────────────────────────────────────────────────────────────────────────
+export class InMemoryIdempotencyStore {
+    buckets = new Map();
+    get(scope, key) {
+        return this.buckets.get(scope)?.get(key) ?? null;
+    }
+    set(scope, key, value) {
+        let bucket = this.buckets.get(scope);
+        if (!bucket) {
+            bucket = new Map();
+            this.buckets.set(scope, bucket);
+        }
+        bucket.set(key, value);
+    }
+    delete(scope, key) {
+        const bucket = this.buckets.get(scope);
+        if (!bucket)
+            return;
+        bucket.delete(key);
+        if (bucket.size === 0)
+            this.buckets.delete(scope);
+    }
+    prune(now) {
+        for (const [scope, bucket] of this.buckets) {
+            for (const [key, value] of bucket) {
+                if (value.expiresAt < now)
+                    bucket.delete(key);
+            }
+            if (bucket.size === 0)
+                this.buckets.delete(scope);
+        }
+    }
+    size() {
+        let total = 0;
+        for (const bucket of this.buckets.values())
+            total += bucket.size;
+        return total;
+    }
+}
+export class InMemoryRunLeaseStore {
+    leases = new Map();
+    acquire(runId, lease) {
+        this.leases.set(runId, lease);
+    }
+    release(runId) {
+        this.leases.delete(runId);
+    }
+    get(runId) {
+        return this.leases.get(runId) ?? null;
+    }
+    markCancelled(runId) {
+        const lease = this.leases.get(runId);
+        if (!lease)
+            return;
+        lease.cancelled = true;
+        lease.cancelledAt = new Date().toISOString();
+    }
+    *listActive() {
+        for (const [runId, lease] of this.leases) {
+            yield { runId, lease };
+        }
+    }
+}

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

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

package/dist/packages/{compiler → engine/compile}/artifact-counts.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { listFilesRecursive } from "../shared/filesystem.js";
-import { compiledZoneAbsolutePath } from "./compiled-schema.js";
+import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
+import { compiledArtifactAbsolutePath } from "./compiled-schema.js";
 const SCAFFOLD_PLACEHOLDER_SNIPPETS = [
     "Not yet compiled. Run `interf compile` to build the portable context.",
     "Not yet compiled. Run `interf compile` to build this portable context.",
@@ -16,8 +16,8 @@ function isScaffoldPlaceholderFile(filePath) {
         return false;
     }
 }
-export function countCompiledZoneArtifacts(compiledPath, zonePath, kind) {
-    const absolutePath = compiledZoneAbsolutePath(compiledPath, { path: zonePath });
+export function countCompiledArtifactsAtPath(compiledPath, artifactPath, kind) {
+    const absolutePath = compiledArtifactAbsolutePath(compiledPath, { path: artifactPath });
     if (!existsSync(absolutePath))
         return 0;
     if (kind === "file")

package/dist/packages/engine/compile/artifact-status.d.ts

@@ -0,0 +1,41 @@
+import type { ArtifactStatus } from "../../contracts/lib/schema.js";
+import type { MethodDefinition } from "../../methods/package/method-definitions.js";
+import type { StageRun } from "../execution/lib/schema.js";
+/**
+ * 0.17 — compute per-Artifact status for a compile run.
+ *
+ * Walks the Method'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 `compiledPath` 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 Method declaration when
+ *   present, otherwise inferred from stage `writes` that match the
+ *   artifact's path.
+ * - **proofs** carries structured evidence from the shared check
+ *   evaluator.
+ *
+ * Stage-failure short-circuit: if any stage has `status: "failed"`, all
+ * non-existent artifacts are marked `failed` instead of `not_ready` so
+ * the run record carries the real causal signal.
+ */
+export declare function computeArtifactStatuses(options: {
+    method: Pick<MethodDefinition<string>, "stages" | "contextInterface" | "schema">;
+    compiledPath: string;
+    stageRuns: StageRun[];
+    /**
+     * Optional runtime counts (e.g. `source_total`) passed to checks
+     * that compare against source. Threaded through from the compile
+     * runtime; absent for ad-hoc evaluations.
+     */
+    counts?: Record<string, number>;
+}): ArtifactStatus[];
+/**
+ * Aggregate verdict: any artifact in `not_ready | failed | skipped`
+ * makes the preparation `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/compile/artifact-status.js

@@ -0,0 +1,166 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { evaluateChecks } from "./check-evaluator.js";
+/**
+ * 0.17 — compute per-Artifact status for a compile run.
+ *
+ * Walks the Method'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 `compiledPath` 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 Method declaration when
+ *   present, otherwise inferred from stage `writes` that match the
+ *   artifact's path.
+ * - **proofs** carries structured evidence from the shared check
+ *   evaluator.
+ *
+ * Stage-failure short-circuit: if any stage has `status: "failed"`, all
+ * non-existent artifacts are marked `failed` instead of `not_ready` so
+ * the run record carries the real causal signal.
+ */
+export function computeArtifactStatuses(options) {
+    const schema = pickContextInterface(options.method);
+    const artifacts = schema?.artifacts ?? [];
+    if (artifacts.length === 0)
+        return [];
+    const stageWriteIndex = buildStageWriteIndex(options.method.stages);
+    const anyStageFailed = options.stageRuns.some((stage) => stage.status === "failed");
+    return artifacts.map((artifact) => buildArtifactStatus({
+        artifact,
+        compiledPath: options.compiledPath,
+        stageWriteIndex,
+        anyStageFailed,
+        counts: options.counts,
+    }));
+}
+function pickContextInterface(method) {
+    return method.contextInterface ?? method.schema;
+}
+function buildStageWriteIndex(stages) {
+    const index = new Map();
+    for (const stage of stages) {
+        for (const write of stage.writes ?? []) {
+            const owners = index.get(write) ?? [];
+            if (!owners.includes(stage.id))
+                owners.push(stage.id);
+            index.set(write, owners);
+        }
+    }
+    return index;
+}
+function buildArtifactStatus(options) {
+    const { artifact, compiledPath, stageWriteIndex, anyStageFailed, counts } = options;
+    const builtBy = artifact.built_by_stages.length > 0
+        ? artifact.built_by_stages
+        : inferBuiltByStages(artifact, stageWriteIndex);
+    const shapeStatus = resolveStatusValue({
+        artifact,
+        compiledPath,
+        anyStageFailed,
+    });
+    // Run the locked CheckKind evaluator against artifact.checks. Proofs
+    // 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).
+    const targetPath = artifact.shape.kind === "path" ? artifact.shape.path : undefined;
+    // `artifact.checks` is `default([])` in the schema, but raw objects
+    // (test fixtures, hand-edited Methods loaded without parsing) may
+    // omit the field entirely.
+    const declaredChecks = artifact.checks ?? [];
+    const checkResult = declaredChecks.length > 0
+        ? evaluateChecks(declaredChecks, {
+            rootPath: compiledPath,
+            targetPath,
+            counts,
+        })
+        : { proofs: [], ready: true, failures: [] };
+    const status = (() => {
+        if (shapeStatus !== "ready")
+            return shapeStatus;
+        if (checkResult.failures.length > 0)
+            return "failed";
+        return "ready";
+    })();
+    return {
+        artifact_id: artifact.id,
+        status,
+        built_by_stages: builtBy,
+        proofs: checkResult.proofs,
+        ...(buildSummary(artifact, status, checkResult.failures.length)),
+    };
+}
+function buildSummary(artifact, status, failedRequiredCount) {
+    if (status === "ready")
+        return { summary: `Artifact ${artifact.id} is ready.` };
+    if (status === "failed") {
+        if (failedRequiredCount > 0) {
+            return { summary: `Artifact ${artifact.id}: ${failedRequiredCount} required check(s) failed.` };
+        }
+        return { summary: `Artifact ${artifact.id} did not produce ${describeShape(artifact)}.` };
+    }
+    if (status === "not_ready")
+        return { summary: `Artifact ${artifact.id} has not been produced yet.` };
+    return { summary: `Artifact ${artifact.id} was skipped.` };
+}
+function inferBuiltByStages(artifact, stageWriteIndex) {
+    if (artifact.shape.kind !== "path")
+        return [];
+    const directOwners = stageWriteIndex.get(artifact.id);
+    if (directOwners && directOwners.length > 0)
+        return directOwners;
+    const pathOwners = stageWriteIndex.get(artifact.shape.path);
+    return pathOwners ?? [];
+}
+function resolveStatusValue(options) {
+    const { artifact, compiledPath, anyStageFailed } = options;
+    if (artifact.shape.kind !== "path")
+        return "skipped";
+    const compiledRoot = resolve(compiledPath);
+    const absolutePath = resolve(compiledRoot, artifact.shape.path);
+    // Defense in depth: the schema-level `isInterfRelativePath` refine
+    // already rejects `..` and absolute paths in `ArtifactPathShape.path`,
+    // but Method 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 portable-context root.
+    if (absolutePath !== compiledRoot && !absolutePath.startsWith(`${compiledRoot}/`)) {
+        return "failed";
+    }
+    if (!existsSync(absolutePath)) {
+        return anyStageFailed ? "failed" : "not_ready";
+    }
+    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";
+        if (artifact.shape.artifact_kind === "file" && info.isFile() && info.size > 0)
+            return "ready";
+        return anyStageFailed ? "failed" : "not_ready";
+    }
+    catch {
+        return anyStageFailed ? "failed" : "not_ready";
+    }
+}
+function describeShape(artifact) {
+    if (artifact.shape.kind === "path")
+        return `\`${artifact.shape.path}\``;
+    return `(${artifact.shape.kind})`;
+}
+/**
+ * Aggregate verdict: any artifact in `not_ready | failed | skipped`
+ * makes the preparation `not_ready`. Used by the readiness state view
+ * once Phase D lights up the per-artifact UI.
+ */
+export function aggregateArtifactVerdict(statuses) {
+    if (statuses.length === 0)
+        return "not_ready";
+    return statuses.every((status) => status.status === "ready") ? "ready" : "not_ready";
+}

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

@@ -0,0 +1,89 @@
+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 compile 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;
+    method_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 compile 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;
+    methodId: string;
+    accountId: string | null;
+    artifacts: readonly ArtifactStatus[];
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    timestamp?: string;
+}): CompilationEvent[];

package/dist/packages/engine/compile/billing-events.js

@@ -0,0 +1,74 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+/**
+ * 0.17 — per-Artifact billing event record.
+ *
+ * Emitted once per Artifact each time a compile 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 const BillingEventKindSchema = z.enum(["fresh", "resync"]);
+export const CompilationEventSchema = z.object({
+    kind: z.literal("interf-compilation-event"),
+    version: z.literal(1),
+    timestamp: z.string().min(1),
+    run_id: z.string().min(1),
+    preparation: z.string().min(1),
+    artifact_id: z.string().min(1),
+    method_id: z.string().min(1),
+    account_id: z.string().min(1).nullable(),
+    event_kind: BillingEventKindSchema,
+    size_class: z.enum(["small", "medium", "large"]).optional(),
+    duration_ms: z.number().nonnegative().optional(),
+}).strict();
+export class JsonlBillingEventSink {
+    logPath;
+    constructor(logPath) {
+        this.logPath = logPath;
+    }
+    emit(event) {
+        const validated = CompilationEventSchema.parse(event);
+        mkdirSync(dirname(this.logPath), { recursive: true });
+        appendFileSync(this.logPath, `${JSON.stringify(validated)}\n`);
+    }
+}
+/**
+ * Default sink path for a run. Each compile run gets its own JSONL
+ * file alongside its other on-disk artifacts.
+ */
+export function defaultBillingEventLogPath(options) {
+    return join(options.preparationDataDir, options.preparationName, "runs", options.runId, "billing-events.jsonl");
+}
+/**
+ * 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 function buildCompilationEventsForRun(options) {
+    const timestamp = options.timestamp ?? new Date().toISOString();
+    const durationMs = options.startedAt && options.finishedAt
+        ? Math.max(0, new Date(options.finishedAt).getTime() - new Date(options.startedAt).getTime())
+        : undefined;
+    return options.artifacts
+        .filter((status) => status.status === "ready" || status.status === "failed")
+        .map((status) => ({
+        kind: "interf-compilation-event",
+        version: 1,
+        timestamp,
+        run_id: options.runId,
+        preparation: options.preparation,
+        artifact_id: status.artifact_id,
+        method_id: options.methodId,
+        account_id: options.accountId,
+        event_kind: "fresh",
+        ...(durationMs !== undefined ? { duration_ms: durationMs } : {}),
+    }));
+}