modelrig 0.1.0 → 0.2.0

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);
+        }
+    }
+}

package/dist/artifacts/scrub.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Scrub v1 — deterministic PII/PHI detection over artifact content BEFORE upload
+ * (E2-C chunk B, spec §3.1 / Expansion spec §7.4).
+ *
+ * Four modes, per route (default `detect` when content custody is on):
+ *   off    — no scan; upload verbatim.
+ *   detect — scan; record FINDINGS as counts-by-type; upload verbatim. The
+ *            findings are metadata (how many SSNs, how many emails), NEVER the
+ *            matched values — recording the value would move the PII into the
+ *            control-plane DB, the exact thing custody is meant to contain.
+ *   redact — scan; upload a MASKED copy; the finding counts still travel.
+ *   block  — scan; if anything is found, REFUSE the upload (counted); the
+ *            artifact keeps its metadata + hash, it simply stores no content.
+ *
+ * ── DETERMINISTIC ≠ DLP (honest limits) ───────────────────────────────────
+ * These are regex/checksum detectors, not a model. They catch well-formed SSNs,
+ * Luhn-valid PANs, emails, E.164/US phones, and labelled MRNs. They WILL miss
+ * obfuscated or free-form PII (that is scrub v2, model-assisted, out of scope).
+ * The custody docs page states this plainly — a caller must not read a clean
+ * `detect` result as a guarantee of no PII.
+ *
+ * NEVER logs a matched value. Findings are `{type, count}` only.
+ */
+export type ScrubMode = "off" | "detect" | "redact" | "block";
+/** A finding is a COUNT by type — never a value (the load-bearing invariant). */
+export interface ScrubFinding {
+    readonly type: ScrubDetectorType;
+    readonly count: number;
+}
+export type ScrubDetectorType = "ssn" | "pan" | "email" | "phone" | "mrn";
+export interface ScrubResult {
+    /** Findings as counts-by-type, sorted by type. Empty when nothing matched. */
+    readonly findings: readonly ScrubFinding[];
+    /** The text to upload: identical to input for off/detect, masked for redact,
+     * and null for block-with-findings (nothing is uploaded). */
+    readonly text: string | null;
+    /** True when `block` mode refused because findings were present. */
+    readonly blocked: boolean;
+}
+/** The per-artifact scrub record persisted on `artifacts.scrub` (migration
+ * 00039). COUNTS ONLY — the `findings` are `{type,count}`, never a matched
+ * value (the load-bearing invariant, same as the SDK counters). `mode` records
+ * WHICH policy ran; `blocked` whether `block` mode refused the upload. */
+export interface ScrubSummary {
+    readonly mode: ScrubMode;
+    readonly blocked: boolean;
+    readonly findings: readonly ScrubFinding[];
+}
+/** Build the persisted summary from a scrub result. The only producer of the
+ * `artifacts.scrub` value, so the counts-not-values invariant lives in one
+ * place — it simply forwards `ScrubResult.findings`, which are already counts. */
+export declare function summarizeScrub(mode: ScrubMode, result: ScrubResult): ScrubSummary;
+/** Luhn checksum — the difference between "16 digits" and "a card number". */
+export declare function luhnValid(digits: string): boolean;
+/**
+ * Scan `text` and produce a scrub result for `mode`. Pure and deterministic.
+ * Never returns or logs a matched value.
+ */
+export declare function scrubContent(text: string, mode: ScrubMode): ScrubResult;
+//# sourceMappingURL=scrub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../src/artifacts/scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9D,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C;iEAC6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;0EAG0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED;;kFAEkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAEjF;AAWD,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAejD;AA0CD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA6CvE"}

package/dist/artifacts/scrub.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Scrub v1 — deterministic PII/PHI detection over artifact content BEFORE upload
+ * (E2-C chunk B, spec §3.1 / Expansion spec §7.4).
+ *
+ * Four modes, per route (default `detect` when content custody is on):
+ *   off    — no scan; upload verbatim.
+ *   detect — scan; record FINDINGS as counts-by-type; upload verbatim. The
+ *            findings are metadata (how many SSNs, how many emails), NEVER the
+ *            matched values — recording the value would move the PII into the
+ *            control-plane DB, the exact thing custody is meant to contain.
+ *   redact — scan; upload a MASKED copy; the finding counts still travel.
+ *   block  — scan; if anything is found, REFUSE the upload (counted); the
+ *            artifact keeps its metadata + hash, it simply stores no content.
+ *
+ * ── DETERMINISTIC ≠ DLP (honest limits) ───────────────────────────────────
+ * These are regex/checksum detectors, not a model. They catch well-formed SSNs,
+ * Luhn-valid PANs, emails, E.164/US phones, and labelled MRNs. They WILL miss
+ * obfuscated or free-form PII (that is scrub v2, model-assisted, out of scope).
+ * The custody docs page states this plainly — a caller must not read a clean
+ * `detect` result as a guarantee of no PII.
+ *
+ * NEVER logs a matched value. Findings are `{type, count}` only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeScrub = summarizeScrub;
+exports.luhnValid = luhnValid;
+exports.scrubContent = scrubContent;
+/** Build the persisted summary from a scrub result. The only producer of the
+ * `artifacts.scrub` value, so the counts-not-values invariant lives in one
+ * place — it simply forwards `ScrubResult.findings`, which are already counts. */
+function summarizeScrub(mode, result) {
+    return { mode, blocked: result.blocked, findings: result.findings };
+}
+/** Luhn checksum — the difference between "16 digits" and "a card number". */
+function luhnValid(digits) {
+    const only = digits.replace(/\D/g, "");
+    if (only.length < 13 || only.length > 19)
+        return false;
+    let sum = 0;
+    let dbl = false;
+    for (let i = only.length - 1; i >= 0; i--) {
+        let d = only.charCodeAt(i) - 48;
+        if (dbl) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        dbl = !dbl;
+    }
+    return sum % 10 === 0;
+}
+// Order matters: PAN before phone/SSN so a 16-digit run is claimed as a card,
+// not split. Each pattern is intentionally conservative — a false positive that
+// masks a non-secret is cheaper than a false negative, but a pattern loose
+// enough to match ordinary prose would make `block` unusable.
+const DETECTORS = [
+    {
+        // PAN: 13–16 digits, optionally split by spaces/dashes in 4s, Luhn-valid.
+        type: "pan",
+        re: /\b(?:\d[ -]?){12,18}\d\b/g,
+        accept: luhnValid,
+        mask: "[REDACTED-PAN]",
+    },
+    {
+        // US SSN: AAA-GG-SSSS with dashes (the delimited form; bare 9-digit runs are
+        // too ambiguous to claim without a false-positive flood).
+        type: "ssn",
+        re: /\b\d{3}-\d{2}-\d{4}\b/g,
+        mask: "[REDACTED-SSN]",
+    },
+    {
+        type: "email",
+        re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+        mask: "[REDACTED-EMAIL]",
+    },
+    {
+        // Phone: E.164 (+1…) or US formats (parens/dashes/dots/spaces). Requires a
+        // grouping delimiter or leading + so bare 10-digit ids don't all match.
+        type: "phone",
+        re: /(?:\+\d{1,3}[ -]?)?(?:\(\d{3}\)|\d{3})[ .-]\d{3}[ .-]\d{4}\b/g,
+        mask: "[REDACTED-PHONE]",
+    },
+    {
+        // MRN-ish: an explicit label followed by an id. A heuristic by nature — the
+        // label is what makes it claimable without a false-positive flood.
+        type: "mrn",
+        re: /\bMRN\b\s*[:#]?\s*[A-Za-z0-9-]{4,}/gi,
+        mask: "[REDACTED-MRN]",
+    },
+];
+/**
+ * Scan `text` and produce a scrub result for `mode`. Pure and deterministic.
+ * Never returns or logs a matched value.
+ */
+function scrubContent(text, mode) {
+    if (mode === "off") {
+        return { findings: [], text, blocked: false };
+    }
+    const counts = new Map();
+    let masked = text;
+    for (const det of DETECTORS) {
+        // Fresh regex state per pass (global flag carries lastIndex otherwise).
+        const re = new RegExp(det.re.source, det.re.flags);
+        let count = 0;
+        const matched = [];
+        for (const m of text.matchAll(re)) {
+            const value = m[0];
+            if (det.accept && !det.accept(value))
+                continue;
+            count += 1;
+            if (mode === "redact")
+                matched.push(value);
+        }
+        if (count > 0) {
+            counts.set(det.type, count);
+            if (mode === "redact") {
+                for (const value of matched) {
+                    // Replace literal occurrences with the mask. split/join avoids
+                    // regex-escaping the value AND avoids putting it in any log.
+                    masked = masked.split(value).join(det.mask);
+                }
+            }
+        }
+    }
+    const findings = [...counts.entries()]
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+    const hasFindings = findings.length > 0;
+    if (mode === "block" && hasFindings) {
+        return { findings, text: null, blocked: true };
+    }
+    if (mode === "redact") {
+        return { findings, text: masked, blocked: false };
+    }
+    // detect (or block with no findings): upload verbatim, report counts.
+    return { findings, text, blocked: false };
+}

package/dist/artifacts/step.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@step` / `step()` — execution scope for NON-LLM stages (spec §1.4, §9).
+ *
+ * A step is an execution operation ("what happened"). For LLM calls `rig.run()`
+ * auto-creates a ground-truth step (its inference row already exists); this
+ * wrapper is for the OTHER stages — retrieval, transforms, tool calls, external
+ * APIs — which have no inference row.
+ *
+ * ── WHY THIS WRITES NO STEP ROW THIS MISSION ──────────────────────────────
+ * The `steps` CHECK requires EXACTLY ONE reference: ground-truth (an inference)
+ * XOR attested (a foreign OTLP span). A pure non-LLM stage has neither — its
+ * span reference arrives with OTLP INGEST (E3), and nothing writes `attested`
+ * rows this mission. So `step()` establishes a NAMED execution scope inside the
+ * active run context (chunk B attributes artifact save/load lineage to it) and
+ * runs the body; it does not persist a row until it has a valid reference.
+ *
+ * Instrumentation never changes the wrapped function's return value, and never
+ * throws into it — a disabled or absent run context just runs the body.
+ */
+/**
+ * Run `fn` as a named execution step within the active run context. Returns the
+ * body's value unchanged (a promise if the body is async). Outside a run context
+ * (namespace disabled, or no run.start on this path) it simply runs the body.
+ */
+export declare function step<T>(key: string, fn: () => T): T;
+//# sourceMappingURL=step.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/artifacts/step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOnD"}