modelrig 0.0.1 → 0.2.0

package/dist/artifacts/content-uploader.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Managed content upload path — E2-C chunk A (spec §2.4).
+ *
+ * When a rig has opted a route into content custody, `save` records the metadata
+ * row (as always) and THEN hands the serialized bytes here. This module talks to
+ * modelrig-server's grant endpoint, receives a short-lived presigned PUT, and
+ * uploads the bytes straight to the object store — the bytes NEVER touch our
+ * control-plane database, only the customer-designated store.
+ *
+ * ── THE POISON LESSON, APPLIED ────────────────────────────────────────────
+ * A deterministic refusal (403 posture-off, 409 already has content, 413 too
+ * big, 422 malformed) is NOT retried — it will fail identically forever, and
+ * retrying a poison request is how a fail-closed refusal turns into a hot loop.
+ * Every refusal DEGRADES to metadata-only: the artifact still exists (its row
+ * was written before we were called), it simply has no stored content.
+ * Degradation is counted and warned, never thrown — this runs off the
+ * customer's hot path and must never surface as a failed run.
+ *
+ * ── THE 404-UNTIL-DURABLE RACE (E4 chunk 0, flag 2) ───────────────────────
+ * A 404 is the ONE 4xx that is NOT deterministic. The grant endpoint verifies
+ * the artifact metadata row exists (and belongs to the org — T11) before
+ * issuing a URL, but that row reaches the control plane on the exporter's NEXT
+ * flush — so a content upload fired during `save` races ahead of its own
+ * metadata and 404s until the row lands. TRANSIENT by nature: it clears once
+ * the metadata is durable. So a 404 returns a distinct `pending` outcome that
+ * the exporter's post-flush hook re-attempts (bounded: 2 retries, then a
+ * counted skip). A genuinely foreign/missing artifact 404s the same way and
+ * simply exhausts those retries into the metadata-only end state — delayed, but
+ * never a hot loop.
+ *
+ * ── C2 ────────────────────────────────────────────────────────────────────
+ * The api key rides in an Authorization header, never a URL. The presigned URL
+ * and the content hash are NEVER logged. Warnings name the artifact + a status,
+ * nothing else.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadArtifactContent = uploadArtifactContent;
+/** A 4xx is a deterministic refusal — the request will fail identically forever,
+ * so it must never be retried (the poison lesson) — with ONE exception: 404,
+ * the metadata-not-yet-durable race, handled separately as `pending`. */
+function isDeterministicRefusal(status) {
+    return status >= 400 && status < 500;
+}
+/**
+ * Upload one artifact's content. NEVER throws — every failure resolves to a
+ * `degraded` outcome the caller records as a metadata-only skip.
+ */
+async function uploadArtifactContent(input, config, fetchFn = fetch) {
+    // Client-side ceiling short-circuit: the server would 413 this; skip the trip.
+    if (input.body.byteLength > config.maxBytes) {
+        return {
+            kind: "degraded",
+            reason: `content is ${input.body.byteLength} bytes, over the ${config.maxBytes} ceiling`,
+            status: 413,
+        };
+    }
+    // 1) Request the grant. A 4xx is deterministic → degrade, no retry.
+    let grantRes;
+    try {
+        grantRes = await fetchFn(config.uploadsUrl, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({
+                artifact_id: input.artifactId,
+                content_type: input.contentType,
+                bytes: input.body.byteLength,
+                content_hash: input.contentHash,
+            }),
+        });
+    }
+    catch (err) {
+        // Transient (network) — degrade without retry this pass; the next save's
+        // upload is an independent attempt. We do NOT loop here.
+        return { kind: "degraded", reason: `grant request failed: ${errMsg(err)}`, status: null };
+    }
+    if (!grantRes.ok) {
+        // 404 is the metadata-not-yet-durable race (T11), the ONE transient 4xx: the
+        // row reaches the control plane on the exporter's next flush, so we hand back
+        // `pending` for the post-flush hook to re-attempt (bounded). Every other 4xx
+        // is a deterministic refusal and 5xx a server error — both degrade here, no
+        // retry this pass. The distinction is only in the reason we log.
+        if (grantRes.status === 404) {
+            return { kind: "pending", reason: "artifact metadata not yet durable (grant 404)", status: 404 };
+        }
+        const kind = isDeterministicRefusal(grantRes.status) ? "refused" : "unavailable";
+        return { kind: "degraded", reason: `grant ${kind} (status ${grantRes.status})`, status: grantRes.status };
+    }
+    let grant;
+    try {
+        grant = (await grantRes.json());
+    }
+    catch {
+        return { kind: "degraded", reason: "grant response was not JSON", status: grantRes.status };
+    }
+    if (typeof grant.upload_url !== "string" || typeof grant.content_ref !== "string") {
+        return { kind: "degraded", reason: "grant response missing upload_url/content_ref", status: grantRes.status };
+    }
+    const putHeaders = isStringRecord(grant.headers) ? grant.headers : {};
+    // 2) PUT the bytes straight to the store. Non-2xx or network → degrade.
+    let putRes;
+    try {
+        putRes = await fetchFn(grant.upload_url, { method: "PUT", headers: putHeaders, body: input.body });
+    }
+    catch (err) {
+        return { kind: "degraded", reason: `content PUT failed: ${errMsg(err)}`, status: null };
+    }
+    if (!putRes.ok) {
+        return { kind: "degraded", reason: `content PUT rejected (status ${putRes.status})`, status: putRes.status };
+    }
+    return { kind: "uploaded", contentRef: grant.content_ref };
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isStringRecord(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        Object.values(v).every((x) => typeof x === "string"));
+}

package/dist/artifacts/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Artifact / execution-graph namespace (Expansion E2) — the public barrel.
+ *
+ * Lives here (not spread through `index.ts`) so the SDK entrypoint stays under
+ * the LOC cap and the run/artifact surface has one home. Chunk A ships the run
+ * lifecycle + `@step`; chunk B adds the artifact primitives (save/load/evaluate).
+ */
+import type { ArtifactBuffer, RunNamespace } from "./run-context";
+import type { ArtifactApi, ArtifactContentDeps } from "./artifact";
+import type { ArtifactContentConfig, ArtifactsConfig } from "../config";
+import type { ArtifactStore } from "../telemetry/artifact-store";
+export { getActiveRunContext, createRunNamespace } from "./run-context";
+export type { RunNamespace, RunHandle, RunStartOptions, RunEvaluateOptions, RunStatus, ActiveRunContext, ArtifactBuffer, GroundTruthStepInput, } from "./run-context";
+export { step } from "./step";
+export { createArtifactApi } from "./artifact";
+export { openArtifactStore } from "../telemetry/artifact-store";
+export type { ArtifactStore } from "../telemetry/artifact-store";
+export type { ArtifactApi, ArtifactHandle, ArtifactSaveOptions, ArtifactEvaluateOptions, ArtifactPromoteOptions, ArtifactContentDeps, ArtifactContentUploader, } from "./artifact";
+export { uploadArtifactContent } from "./content-uploader";
+export type { ContentUploadConfig, ContentUploadInput, ContentUploadOutcome, } from "./content-uploader";
+export { scrubContent, luhnValid } from "./scrub";
+export type { ScrubMode, ScrubFinding, ScrubResult, ScrubDetectorType } from "./scrub";
+export { computeDownstreamClosure, TAINT_DEFAULT_MAX_DEPTH, TAINT_DEFAULT_CAP, } from "./taint";
+export type { TaintEdge, Supersession, TaintNode, TaintClosure, TaintOptions, } from "./taint";
+export type { RunRow, StepRow, ArtifactRow, ArtifactEdgeRow, ArtifactEvaluationRow, EvalCaseRow, EvalCaseOrigin, } from "../types/telemetry";
+/** The rig-bound artifact surface exposed as `rig.artifacts`: the run lifecycle
+ * (chunk A) + the artifact primitives (chunk B). */
+export interface ArtifactNamespace {
+    readonly run: RunNamespace;
+    readonly artifact: ArtifactApi;
+}
+/** Build the rig-bound artifact namespace AND the exporter's post-flush retry
+ * hook from resolved config (E4 chunk 0, flag 2). Lives here so the SDK
+ * entrypoint stays under the LOC cap. The hook is present only when content
+ * custody is configured; otherwise it would be a no-op. */
+export declare function wireRigArtifacts(deps: {
+    readonly buffer: ArtifactBuffer;
+    readonly enabled: boolean;
+    readonly artifactStore: ArtifactStore | null;
+    readonly artifacts?: ArtifactsConfig;
+}): {
+    readonly namespace: ArtifactNamespace;
+    readonly onArtifactsFlushed?: () => Promise<void>;
+};
+/**
+ * Build the content-custody deps (E2-C) from resolved config, or undefined when
+ * custody is off. Kept here (not in the SDK entrypoint) so index.ts stays under
+ * the LOC cap (P1) and the content wiring lives beside the namespace it feeds.
+ */
+export declare function buildArtifactContentDeps(content: ArtifactContentConfig | undefined): ArtifactContentDeps | undefined;
+/** Build the rig-bound artifact namespace. Disabled ⇒ every entry is inert
+ * (run.start is a no-op, save returns null, no rows written) — spec §1.4. The
+ * artifact store is present only when enabled (index.ts opens it then). */
+export declare function createArtifactNamespace(deps: {
+    readonly buffer: ArtifactBuffer;
+    readonly artifactStore?: ArtifactStore;
+    readonly enabled: boolean;
+    /** Content-custody config (E2-C). Absent = metadata + hash only; the upload
+     * deps are built here (buildArtifactContentDeps) so the SDK entrypoint stays
+     * under the LOC cap. */
+    readonly content?: ArtifactContentConfig;
+}): ArtifactNamespace;
+//# sourceMappingURL=index.d.ts.map

package/dist/artifacts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,YAAY,EACZ,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,YAAY,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,SAAS,EACT,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B;oDACoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED;;;2DAG2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAY/F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,mBAAmB,GAAG,SAAS,CAWjC;AAED;;2EAE2E;AAC3E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;4BAEwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAC1C,GAAG,iBAAiB,CAYpB"}

package/dist/artifacts/index.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Artifact / execution-graph namespace (Expansion E2) — the public barrel.
+ *
+ * Lives here (not spread through `index.ts`) so the SDK entrypoint stays under
+ * the LOC cap and the run/artifact surface has one home. Chunk A ships the run
+ * lifecycle + `@step`; chunk B adds the artifact primitives (save/load/evaluate).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAINT_DEFAULT_CAP = exports.TAINT_DEFAULT_MAX_DEPTH = exports.computeDownstreamClosure = exports.luhnValid = exports.scrubContent = exports.uploadArtifactContent = exports.openArtifactStore = exports.createArtifactApi = exports.step = exports.createRunNamespace = exports.getActiveRunContext = void 0;
+exports.wireRigArtifacts = wireRigArtifacts;
+exports.buildArtifactContentDeps = buildArtifactContentDeps;
+exports.createArtifactNamespace = createArtifactNamespace;
+const run_context_1 = require("./run-context");
+const artifact_1 = require("./artifact");
+const content_uploader_1 = require("./content-uploader");
+var run_context_2 = require("./run-context");
+Object.defineProperty(exports, "getActiveRunContext", { enumerable: true, get: function () { return run_context_2.getActiveRunContext; } });
+Object.defineProperty(exports, "createRunNamespace", { enumerable: true, get: function () { return run_context_2.createRunNamespace; } });
+var step_1 = require("./step");
+Object.defineProperty(exports, "step", { enumerable: true, get: function () { return step_1.step; } });
+var artifact_2 = require("./artifact");
+Object.defineProperty(exports, "createArtifactApi", { enumerable: true, get: function () { return artifact_2.createArtifactApi; } });
+var artifact_store_1 = require("../telemetry/artifact-store");
+Object.defineProperty(exports, "openArtifactStore", { enumerable: true, get: function () { return artifact_store_1.openArtifactStore; } });
+var content_uploader_2 = require("./content-uploader");
+Object.defineProperty(exports, "uploadArtifactContent", { enumerable: true, get: function () { return content_uploader_2.uploadArtifactContent; } });
+var scrub_1 = require("./scrub");
+Object.defineProperty(exports, "scrubContent", { enumerable: true, get: function () { return scrub_1.scrubContent; } });
+Object.defineProperty(exports, "luhnValid", { enumerable: true, get: function () { return scrub_1.luhnValid; } });
+var taint_1 = require("./taint");
+Object.defineProperty(exports, "computeDownstreamClosure", { enumerable: true, get: function () { return taint_1.computeDownstreamClosure; } });
+Object.defineProperty(exports, "TAINT_DEFAULT_MAX_DEPTH", { enumerable: true, get: function () { return taint_1.TAINT_DEFAULT_MAX_DEPTH; } });
+Object.defineProperty(exports, "TAINT_DEFAULT_CAP", { enumerable: true, get: function () { return taint_1.TAINT_DEFAULT_CAP; } });
+/** Build the rig-bound artifact namespace AND the exporter's post-flush retry
+ * hook from resolved config (E4 chunk 0, flag 2). Lives here so the SDK
+ * entrypoint stays under the LOC cap. The hook is present only when content
+ * custody is configured; otherwise it would be a no-op. */
+function wireRigArtifacts(deps) {
+    const namespace = createArtifactNamespace({
+        buffer: deps.buffer,
+        enabled: deps.enabled,
+        ...(deps.artifactStore !== null ? { artifactStore: deps.artifactStore } : {}),
+        ...(deps.artifacts?.content !== undefined ? { content: deps.artifacts.content } : {}),
+    });
+    const hookOn = deps.enabled && deps.artifacts?.content !== undefined;
+    return {
+        namespace,
+        ...(hookOn ? { onArtifactsFlushed: () => namespace.artifact.retryPendingContent() } : {}),
+    };
+}
+/**
+ * Build the content-custody deps (E2-C) from resolved config, or undefined when
+ * custody is off. Kept here (not in the SDK entrypoint) so index.ts stays under
+ * the LOC cap (P1) and the content wiring lives beside the namespace it feeds.
+ */
+function buildArtifactContentDeps(content) {
+    if (content === undefined)
+        return undefined;
+    return {
+        scrub: content.scrub,
+        upload: (input) => (0, content_uploader_1.uploadArtifactContent)(input, { uploadsUrl: content.uploadsUrl, apiKey: content.apiKey, maxBytes: content.maxBytes }, fetch),
+    };
+}
+/** Build the rig-bound artifact namespace. Disabled ⇒ every entry is inert
+ * (run.start is a no-op, save returns null, no rows written) — spec §1.4. The
+ * artifact store is present only when enabled (index.ts opens it then). */
+function createArtifactNamespace(deps) {
+    const contentDeps = deps.enabled ? buildArtifactContentDeps(deps.content) : undefined;
+    return {
+        run: (0, run_context_1.createRunNamespace)(deps),
+        artifact: (0, artifact_1.createArtifactApi)({
+            // A disabled namespace never opens a store; createArtifactApi(enabled:false)
+            // ignores the store and returns an inert api, so the cast is never reached.
+            store: deps.artifactStore,
+            enabled: deps.enabled && deps.artifactStore !== undefined,
+            ...(contentDeps !== undefined ? { content: contentDeps } : {}),
+        }),
+    };
+}

package/dist/artifacts/run-context.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Run context — Expansion E2 chunk A (spec §1.4, §9).
+ *
+ * A RUN is one execution of a customer pipeline; instrumentation hangs off an
+ * ambient run context held in an `AsyncLocalStorage` (a Node builtin — NO new
+ * npm dependency). `run.start()` mints the context and `run.end()` closes it;
+ * everything that happens in between — `rig.run()` auto-steps, `@step` scopes,
+ * and (chunk B) artifact save/load lineage — reads the SAME ambient context.
+ *
+ * ── FAIL-OPEN, ALWAYS ─────────────────────────────────────────────────────
+ * Instrumentation NEVER changes return values and NEVER throws into customer
+ * code (the exporter's swallow-and-log doctrine, extended). A telemetry-buffer
+ * write that fails is logged and dropped; the customer's pipeline is untouched.
+ *
+ * ── GATING ────────────────────────────────────────────────────────────────
+ * The namespace is inert unless the rig enabled it (`MODELRIG_ARTIFACTS=1`).
+ * A disabled namespace's `run.start()` sets NO context, so `getActiveRunContext`
+ * returns null everywhere and the run loop's auto-step is never reached —
+ * v1 wire, zero new rows, zero behaviour change (spec §1.4).
+ */
+import type { ArtifactEvaluationRow, RunRow, StepRow } from "../types/telemetry";
+/** The narrow buffer the run/artifact namespace writes through — the local
+ * telemetry store satisfies it. Kept narrow so this module depends on the row
+ * shapes, not the whole store surface (and cannot reach captures). */
+export interface ArtifactBuffer {
+    recordRun(row: RunRow): void;
+    recordStep(row: StepRow): void;
+}
+export type RunStatus = RunRow["status"];
+export interface RunStartOptions {
+    /** Customer's pipeline name — the run's semantic identity. */
+    readonly pipeline: string;
+    readonly pipelineVersion?: string;
+    readonly environment?: string;
+    /** Bridges feedback.episode_key (run-level verdicts). Optional. */
+    readonly episodeKey?: string;
+    /** W3C traceparent for cross-service correlation (spec §1.4). When present the
+     * run adopts its trace id, so artifacts crossing a service boundary (chunk B)
+     * can be tied back to this run. Never changes the (uuid) run id. */
+    readonly traceparent?: string;
+    /** Zero-retention run (chunk B, ratified invariant): NO artifact rows of any
+     * kind are emitted — artifact.save refuses fail-closed at the SDK gate with a
+     * counted, logged skip. Set by the caller or derived from a route's
+     * `require: zero_retention`. */
+    readonly zeroRetention?: boolean;
+}
+/** One ground-truth step attempt the run loop asks the context to record. The
+ * context assigns `attempt_no` per step key so the caller need not track it. */
+export interface GroundTruthStepInput {
+    readonly stepKey: string;
+    readonly task: string | null;
+    readonly inferenceId: string;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly failureClass: string | null;
+}
+export interface ActiveRunContext {
+    readonly runId: string;
+    /** Trace id adopted from a traceparent at run.start, if any (chunk B use). */
+    readonly traceId: string | null;
+    /** Zero-retention gate (chunk B): true ⇒ artifact.save refuses fail-closed. */
+    readonly zeroRetention: boolean;
+    /** Record that an artifact was loaded in the current run (chunk B lineage). */
+    noteLoad(artifactId: string): void;
+    /** Return AND clear the loaded-artifact ids — the set a subsequent save
+     * derives `derived_from` edges to (loads "consumed" by that save). v0
+     * lineage: run-scoped, cleared on each save; coverage measured, never promised. */
+    takeLoadedIds(): string[];
+    /** Mint a unique step key for ONE rig.run()/@step invocation. Retries of that
+     * invocation reuse the returned key (attempt_no distinguishes them); a later
+     * invocation gets a fresh key, so two calls never collapse into one step. */
+    nextStepKey(label: string): string;
+    /** Record one ground-truth step attempt (the rig.run auto-step). attempt_no is
+     * assigned here, per step key. Fail-open — a buffer error is logged, dropped,
+     * and never thrown into the run loop. */
+    emitGroundTruthStep(input: GroundTruthStepInput): void;
+}
+/** The active run context, or null when none is set (namespace disabled, or no
+ * run.start on this async path). Read by the run loop's auto-step seam. */
+export declare function getActiveRunContext(): ActiveRunContext | null;
+/** A run-level evaluation the caller attaches (E5 chunk V.2) — the run-subject
+ * mirror of ArtifactEvaluateOptions. The subject is the run, so there is no ref. */
+export interface RunEvaluateOptions {
+    readonly evaluator: string;
+    readonly kind: "deterministic" | "model-judge" | "human";
+    readonly score?: number;
+    readonly passed?: boolean;
+    readonly label?: string;
+    readonly explanation?: string;
+}
+/** A handle a caller holds to end a run it started. */
+export interface RunHandle {
+    readonly runId: string;
+    end(status?: RunStatus): void;
+    /** Attach a run-level evaluation to THIS run (E5 V.2). Works after end() —
+     * verdicts are often post-hoc. Fail-open + inert when the namespace is off. */
+    evaluate(opts: RunEvaluateOptions): void;
+}
+/** The `run` namespace, bound to one rig's buffer + gate. Disabled ⇒ inert. */
+export interface RunNamespace {
+    /** Begin a run via the imperative handle API. Uses `AsyncLocalStorage.enterWith`,
+     * which has NO lexical exit — safe for one run at a time on a request/async
+     * path, but CONCURRENT overlapping `start()` calls (e.g. `Promise.all` over
+     * items) clobber each other's ambient context and cross-attribute steps.
+     * For concurrent runs use `scope()`. Disabled ⇒ no-op inert handle. */
+    start(opts: RunStartOptions): RunHandle;
+    /** End the active run with a terminal status (default "succeeded"). */
+    end(status?: RunStatus): void;
+    /** Attach a run-level evaluation to the ACTIVE run (E5 V.2) — the run-subject
+     * mirror of `artifact.evaluate`. No active run ⇒ a warned no-op (fail-open). */
+    evaluate(opts: RunEvaluateOptions): void;
+    /** Concurrency-safe run scope. Runs `fn` inside `AsyncLocalStorage.run`, so
+     * overlapping `scope()` calls each keep their OWN ambient run context — the
+     * correct primitive for `Promise.all` over items. Ends the run "succeeded" on
+     * return, "failed" if `fn` throws (then rethrows). Disabled ⇒ runs `fn` with
+     * no context. */
+    scope<T>(opts: RunStartOptions, fn: () => Promise<T>): Promise<T>;
+}
+export declare function createRunNamespace(deps: {
+    readonly buffer: ArtifactBuffer;
+    readonly enabled: boolean;
+    /** The evaluation writer (E5 V.2) — the artifact store's recordArtifactEvaluation.
+     * Absent (disabled / no store) ⇒ run.evaluate is inert. Kept OFF the narrow
+     * ArtifactBuffer so that contract stays "cannot reach anything but run/step". */
+    readonly artifactStore?: {
+        recordArtifactEvaluation(row: ArtifactEvaluationRow): void;
+    };
+}): RunNamespace;
+//# sourceMappingURL=run-context.d.ts.map

package/dist/artifacts/run-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.d.ts","sourceRoot":"","sources":["../../src/artifacts/run-context.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/run-context.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Run context — Expansion E2 chunk A (spec §1.4, §9).
+ *
+ * A RUN is one execution of a customer pipeline; instrumentation hangs off an
+ * ambient run context held in an `AsyncLocalStorage` (a Node builtin — NO new
+ * npm dependency). `run.start()` mints the context and `run.end()` closes it;
+ * everything that happens in between — `rig.run()` auto-steps, `@step` scopes,
+ * and (chunk B) artifact save/load lineage — reads the SAME ambient context.
+ *
+ * ── FAIL-OPEN, ALWAYS ─────────────────────────────────────────────────────
+ * Instrumentation NEVER changes return values and NEVER throws into customer
+ * code (the exporter's swallow-and-log doctrine, extended). A telemetry-buffer
+ * write that fails is logged and dropped; the customer's pipeline is untouched.
+ *
+ * ── GATING ────────────────────────────────────────────────────────────────
+ * The namespace is inert unless the rig enabled it (`MODELRIG_ARTIFACTS=1`).
+ * A disabled namespace's `run.start()` sets NO context, so `getActiveRunContext`
+ * returns null everywhere and the run loop's auto-step is never reached —
+ * v1 wire, zero new rows, zero behaviour change (spec §1.4).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActiveRunContext = getActiveRunContext;
+exports.createRunNamespace = createRunNamespace;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const otel_map_1 = require("../telemetry/otel-map");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** The active run context, or null when none is set (namespace disabled, or no
+ * run.start on this async path). Read by the run loop's auto-step seam. */
+function getActiveRunContext() {
+    const ctx = storage.getStore();
+    return ctx !== undefined && !ctx.ended ? ctx : null;
+}
+function warnOnce(scope, err) {
+    console.warn(`[modelrig artifacts] ${scope} buffer write failed (dropped, run unaffected): ` +
+        `${err instanceof Error ? err.message : String(err)}`);
+}
+function createRunNamespace(deps) {
+    const { buffer, enabled } = deps;
+    const evalStore = deps.artifactStore;
+    /** Write ONE run-subject evaluation (artifactId null, runId set). Fail-open. */
+    function writeRunEvaluation(runId, opts) {
+        if (!enabled || evalStore === undefined || runId === "")
+            return;
+        try {
+            evalStore.recordArtifactEvaluation({
+                id: (0, node_crypto_1.randomUUID)(),
+                artifactId: null,
+                runId,
+                evaluator: opts.evaluator,
+                evaluatorKind: opts.kind,
+                score: opts.score ?? null,
+                passed: opts.passed ?? null,
+                label: opts.label ?? null,
+                explanation: opts.explanation ?? null,
+                createdBy: null,
+            });
+        }
+        catch (err) {
+            warnOnce("run.evaluate", err);
+        }
+    }
+    const inertHandle = { runId: "", end() { }, evaluate() { } };
+    function buildContext(startRow, traceId, zeroRetention) {
+        const runId = startRow.id;
+        const attemptByStep = new Map();
+        const loaded = new Set();
+        let stepSeq = 0;
+        return {
+            runId,
+            traceId,
+            zeroRetention,
+            ended: false,
+            buffer,
+            startRow,
+            noteLoad(artifactId) {
+                loaded.add(artifactId);
+            },
+            takeLoadedIds() {
+                const ids = [...loaded];
+                loaded.clear();
+                return ids;
+            },
+            nextStepKey(label) {
+                stepSeq += 1;
+                return `${label}#${stepSeq}`;
+            },
+            emitGroundTruthStep(input) {
+                const attemptNo = (attemptByStep.get(input.stepKey) ?? 0) + 1;
+                attemptByStep.set(input.stepKey, attemptNo);
+                try {
+                    buffer.recordStep({
+                        runId,
+                        stepKey: input.stepKey,
+                        attemptNo,
+                        task: input.task,
+                        provenance: "ground-truth",
+                        inferenceId: input.inferenceId,
+                        spanTraceId: null,
+                        spanId: null,
+                        startedAt: input.startedAt,
+                        endedAt: input.endedAt,
+                        failureClass: input.failureClass,
+                    });
+                }
+                catch (err) {
+                    warnOnce("step", err);
+                }
+            },
+        };
+    }
+    /** Build the context + record the `running` row. Shared by start() and
+     * scope() so the two entry points agree on identity + buffering. */
+    function newRun(opts) {
+        const startRow = {
+            id: (0, node_crypto_1.randomUUID)(),
+            pipeline: opts.pipeline,
+            pipelineVersion: opts.pipelineVersion ?? null,
+            environment: opts.environment ?? null,
+            episodeKey: opts.episodeKey ?? null,
+            startedAt: new Date().toISOString(),
+            endedAt: null,
+            status: "running",
+        };
+        const traceId = opts.traceparent !== undefined
+            ? ((0, otel_map_1.parseTraceparent)(opts.traceparent)?.traceId ?? null)
+            : null;
+        const ctx = buildContext(startRow, traceId, opts.zeroRetention === true);
+        try {
+            buffer.recordRun(startRow);
+        }
+        catch (err) {
+            warnOnce("run", err);
+        }
+        return ctx;
+    }
+    return {
+        start(opts) {
+            if (!enabled)
+                return inertHandle;
+            const ctx = newRun(opts);
+            storage.enterWith(ctx);
+            return {
+                runId: ctx.runId,
+                end: (status) => endContext(ctx, status),
+                evaluate: (opts2) => writeRunEvaluation(ctx.runId, opts2),
+            };
+        },
+        end(status) {
+            const ctx = storage.getStore();
+            if (ctx !== undefined)
+                endContext(ctx, status);
+        },
+        evaluate(opts) {
+            const ctx = storage.getStore();
+            // `ended` counts as gone — same rule as getActiveRunContext. `enterWith`
+            // has no lexical exit, so an ended run's context stays ambient on this
+            // async path; without this check ns.evaluate re-attributes verdicts to
+            // the ended run (post-end verdicts belong to the HANDLE, which closes
+            // over its runId — that path is unaffected).
+            if (ctx === undefined || ctx.ended) {
+                console.warn("[modelrig artifacts] run.evaluate() with no active run — dropped");
+                return;
+            }
+            writeRunEvaluation(ctx.runId, opts);
+        },
+        async scope(opts, fn) {
+            if (!enabled)
+                return fn();
+            const ctx = newRun(opts);
+            // storage.run gives THIS run its own ambient context for the whole of fn,
+            // isolated from any sibling scope() running concurrently — no enterWith
+            // cross-attribution. End on the way out, success or failure.
+            return storage.run(ctx, async () => {
+                try {
+                    const result = await fn();
+                    endContext(ctx, "succeeded");
+                    return result;
+                }
+                catch (err) {
+                    endContext(ctx, "failed");
+                    throw err;
+                }
+            });
+        },
+    };
+    function endContext(ctx, status) {
+        if (ctx.ended)
+            return;
+        ctx.ended = true;
+        // Update the projection in place: same identity as the start row, now with
+        // an ended_at and a terminal status. recordRun bumps export_seq so this
+        // terminal state re-exports past the `:runs` watermark. Emitting the full
+        // row (not a sparse one) is required — the server upsert overwrites every
+        // column it carries, so a blank pipeline here would clobber the real one.
+        try {
+            buffer.recordRun({
+                ...ctx.startRow,
+                endedAt: new Date().toISOString(),
+                status: status ?? "succeeded",
+            });
+        }
+        catch (err) {
+            warnOnce("run", err);
+        }
+    }
+}