@interf/compiler 0.16.0 → 0.18.0

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

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

package/dist/packages/engine/compile/artifact-counts.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
-import { compiledZoneAbsolutePath } from "./compiled-schema.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 } : {}),
+    }));
+}

package/dist/packages/engine/compile/check-evaluator.d.ts

@@ -0,0 +1,66 @@
+import { type Check, type CheckKind, type Proof } from "../../contracts/lib/schema.js";
+/**
+ * 0.17 — Check evaluator for the locked verification vocabulary.
+ *
+ * One evaluator per `CheckKind` from `CHECK_KINDS`. The evaluator is
+ * scope-agnostic: it takes a Check, a target path, and optional
+ * runtime context (counts, source-file totals); it returns a Proof.
+ *
+ * The same evaluator serves stage-level checks, artifact-level checks,
+ * and (for `qa_match`) user-level checks. Methods and user-defined
+ * verification declare `Check[]`; the runtime invokes this evaluator
+ * to produce `Proof[]`.
+ *
+ * This evaluator is the source of truth for declared verification
+ * checks. Legacy stage-acceptance rules were retired after the
+ * artifact-first migration.
+ */
+export interface CheckEvaluationContext {
+    /**
+     * Filesystem root the check evaluates against. For artifact checks
+     * this is the portable-context root; the artifact's path is
+     * resolved relative to it. For stage checks this can be the same
+     * root or a stage-output sub-directory.
+     */
+    rootPath: string;
+    /**
+     * Optional: the path the check targets. For artifact-scoped checks
+     * this is the artifact's `shape.path`; for stage-scoped checks
+     * this is the stage's writes path. Some kinds (qa_match) ignore
+     * targetPath because they operate on agent answers, not files.
+     */
+    targetPath?: string;
+    /**
+     * Optional runtime-derived counts used by `min_file_count_matches_source`
+     * and similar rules. `source_total` is the canonical key for "how
+     * many source files were processed." Methods reference it in check
+     * params via `{ match: "source_total" }`.
+     */
+    counts?: Record<string, number>;
+    /**
+     * Optional: the agent's answer for a `qa_match` check. Provided by
+     * the verify-run flow, not relevant for compile-time evaluation.
+     */
+    agentAnswer?: string;
+}
+export type CheckEvaluator = (check: Check, context: CheckEvaluationContext) => Proof;
+/**
+ * Evaluate a single Check against a context, returning a Proof.
+ */
+export declare function evaluateCheck(check: Check, context: CheckEvaluationContext): Proof;
+/**
+ * Evaluate a list of checks. Aggregate ready/not_ready verdict over
+ * the proofs: `ready` if every required check passed, otherwise
+ * `not_ready`. Soft checks (required: false) that fail produce a
+ * proof but don't change the verdict.
+ */
+export declare function evaluateChecks(checks: readonly Check[], context: CheckEvaluationContext): {
+    proofs: Proof[];
+    ready: boolean;
+    failures: Proof[];
+};
+/**
+ * Type guard for the canonical CheckKinds. Useful at parse boundaries
+ * where a string came from on-disk JSON.
+ */
+export declare function isCheckKind(value: unknown): value is CheckKind;