modelrig 0.11.0 → 0.12.0

package/dist/telemetry/ingest-protocol.js

@@ -34,8 +34,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_INGEST_URL = exports.INGEST_PROTOCOL_VERSION_V1 = exports.INGEST_PROTOCOL_VERSION = exports.INGEST_PATH = exports.foreignOrgGrades = void 0;
 exports.stampBatch = stampBatch;
+exports.stepTaskRegistration = stepTaskRegistration;
 const fingerprint_1 = require("../registry/fingerprint");
 const grade_mappers_1 = require("./grade-mappers");
+const uniform_rows_1 = require("./uniform-rows");
+const grade_task_1 = require("./grade-task");
 var grade_mappers_2 = require("./grade-mappers");
 Object.defineProperty(exports, "foreignOrgGrades", { enumerable: true, get: function () { return grade_mappers_2.foreignOrgGrades; } });
 /** The path the api sink posts to. Spelled once. */
@@ -88,14 +91,13 @@ function stampBatch(batch, tenancy, opts = {}) {
             }
             taskRows.push(taskRow);
         }
-        writes.push({
-            // merge=true: a task row is a mutable projection of the latest sync, like
-            // the routes mirror, unlike inferences. onConflict on the PK (S5).
-            table: "tasks",
-            onConflict: "org_id,task",
-            merge: true,
-            rows: taskRows,
-        });
+        // merge=true: a task row is a mutable projection of the latest sync, like
+        // the routes mirror, unlike inferences. onConflict on the PK (S5). Split by
+        // key set (COV-1c, PGRST102): a bundle-less task row must neither fail nor
+        // null out its bundled neighbours' schema columns.
+        for (const group of (0, uniform_rows_1.splitByKeySet)(taskRows)) {
+            writes.push({ table: "tasks", onConflict: "org_id,task", merge: true, rows: group });
+        }
         const routeRow = (r) => ({
             org_id: tenancy.org_id,
             route: r.route,
@@ -130,31 +132,31 @@ function stampBatch(batch, tenancy, opts = {}) {
         }
     }
     if (batch.runs !== undefined && batch.runs.length > 0) {
-        writes.push({
-            // runs are a mutable projection (start → end): merge=true on the PK (S5).
-            table: "runs",
-            onConflict: "org_id,id",
-            merge: true,
-            rows: batch.runs.map((r) => ({
-                // Field-by-field from the principal's tenancy — org_id and source_id are
-                // NEVER carried on the wire (T3). source_id identifies the rig instance,
-                // exactly like inferences.
-                org_id: tenancy.org_id,
-                id: r.id,
-                source_id: tenancy.source_id,
-                pipeline: r.pipeline,
-                pipeline_version: r.pipeline_version,
-                environment: r.environment,
-                episode_key: r.episode_key,
-                started_at: r.started_at,
-                ended_at: r.ended_at,
-                status: r.status,
-                updated_at: now,
-                // WI-1 (spec §3): the run metadata envelope. spread-iff-present (the
-                // 00027 pattern) — a run without `meta` leaves runs.meta untouched.
-                ...(r.meta !== undefined && r.meta !== null ? { meta: r.meta } : {}),
-            })),
-        });
+        const runRows = batch.runs.map((r) => ({
+            // Field-by-field from the principal's tenancy — org_id and source_id are
+            // NEVER carried on the wire (T3). source_id identifies the rig instance,
+            // exactly like inferences.
+            org_id: tenancy.org_id,
+            id: r.id,
+            source_id: tenancy.source_id,
+            pipeline: r.pipeline,
+            pipeline_version: r.pipeline_version,
+            environment: r.environment,
+            episode_key: r.episode_key,
+            started_at: r.started_at,
+            ended_at: r.ended_at,
+            status: r.status,
+            updated_at: now,
+            // WI-1 (spec §3): the run metadata envelope. spread-iff-present (the
+            // 00027 pattern) — a run without `meta` leaves runs.meta untouched.
+            ...(r.meta !== undefined && r.meta !== null ? { meta: r.meta } : {}),
+        }));
+        // runs are a mutable projection (start → end): merge=true on the PK (S5).
+        // Split by key set (COV-1c, PGRST102): a meta-less run row must not fail,
+        // or null out, a neighbour's meta.
+        for (const group of (0, uniform_rows_1.splitByKeySet)(runRows)) {
+            writes.push({ table: "runs", onConflict: "org_id,id", merge: true, rows: group });
+        }
     }
     if (batch.steps !== undefined && batch.steps.length > 0) {
         writes.push({
@@ -163,7 +165,8 @@ function stampBatch(batch, tenancy, opts = {}) {
             table: "steps",
             onConflict: "org_id,run_id,step_key,attempt_no",
             merge: false,
-            rows: batch.steps.map((s) => ({
+            // fillNulls (COV-1c, PGRST102): merge=false, so a null never rewrites a row.
+            rows: (0, uniform_rows_1.fillNulls)(batch.steps.map((s) => ({
                 org_id: tenancy.org_id,
                 run_id: s.run_id,
                 step_key: s.step_key,
@@ -185,7 +188,7 @@ function stampBatch(batch, tenancy, opts = {}) {
                 // ground-truth step carries no `attested`, so the column stays null and
                 // the 00038 CHECK holds. An SDK batch never sets it → byte-identical.
                 ...(s.attested !== undefined ? { attested: s.attested } : {}),
-            })),
+            })), ["attested"]),
         });
     }
     if (batch.artifacts !== undefined && batch.artifacts.length > 0) {
@@ -193,7 +196,7 @@ function stampBatch(batch, tenancy, opts = {}) {
             table: "artifacts",
             onConflict: "org_id,id",
             merge: false, // an artifact metadata row is a fact; a retry must not rewrite it
-            rows: batch.artifacts.map((a) => ({
+            rows: (0, uniform_rows_1.fillNulls)(batch.artifacts.map((a) => ({
                 org_id: tenancy.org_id,
                 id: a.id,
                 run_id: a.run_id,
@@ -214,7 +217,7 @@ function stampBatch(batch, tenancy, opts = {}) {
                 // spread-iff-present (00027 pattern): a batch without `scrub` (older SDK,
                 // custody off) leaves the column null rather than overwriting it.
                 ...(a.scrub !== undefined ? { scrub: a.scrub } : {}),
-            })),
+            })), ["scrub"]),
         });
     }
     if (batch.artifact_edges !== undefined && batch.artifact_edges.length > 0) {
@@ -280,12 +283,11 @@ function stampBatch(batch, tenancy, opts = {}) {
             // An inference is a fact that happened. A retry must not be able to
             // rewrite it — idempotent by doing nothing, not by overwriting.
             merge: false,
-            rows: batch.inferences.map((row) => ({
-                org_id: tenancy.org_id,
-                project_id: tenancy.project_id,
-                source_id: tenancy.source_id,
-                ...row,
-            })),
+            // ONE key set for every row (COV-1c): a PostgREST bulk insert 400s with
+            // PGRST102 when keys differ — a web-search surcharge row (meta: null)
+            // beside metered rows (meta set) used to drop the whole batch. merge=false
+            // makes writing absent columns as their defaults safe.
+            rows: batch.inferences.map((row) => (0, uniform_rows_1.normalizeInferenceRow)(row, tenancy)),
         });
     }
     if (batch.watermarkAt !== undefined) {
@@ -329,3 +331,30 @@ function stampBatch(batch, tenancy, opts = {}) {
     }
     return writes;
 }
+/**
+ * GRADE-RAW (grade-ux-plan §1 item 1): the step-task registration write for a
+ * batch — a raw-lane or recorded call that names a step (`tags.step`) registers
+ * that step as a task, so a grading guide can be written for it. Or null when
+ * the batch names no step.
+ *
+ * DELIBERATELY NOT part of `stampBatch` (architect S2-1): it is a BEST-EFFORT
+ * write both sinks issue only AFTER the batch's rows are confirmed, with any
+ * error swallowed — a refused registration must never turn a batch of
+ * inferences into a poison-skipped 422. merge=false (ignore-duplicates on the
+ * PK): it never rewrites an existing row (a route-synced task, or a step's
+ * settings/guide); a retry is a no-op. Tenant from the PRINCIPAL only (T3).
+ * Capped per batch (registrableStepTasks).
+ */
+function stepTaskRegistration(batch, tenancy) {
+    if (batch.inferences === undefined || batch.inferences.length === 0)
+        return null;
+    const steps = (0, grade_task_1.registrableStepTasks)(batch.inferences);
+    if (steps.length === 0)
+        return null;
+    return {
+        table: "tasks",
+        onConflict: "org_id,task",
+        merge: false,
+        rows: steps.map((task) => ({ org_id: tenancy.org_id, task, source: "registered" })),
+    };
+}

package/dist/telemetry/otel-content.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ARC-6 / ARC-D6 — OTLP content extraction, GATED. M14 is UNRULED, so this
+ * ships OFF: the server calls it ONLY when its feature gate is on AND the org's
+ * capture posture is `managed` (modelrig-server otlp-content.ts). With the gate
+ * off nothing here runs, and the normalizer (otel-normalize.ts) keeps its STOP
+ * invariant: zero content read.
+ *
+ * When it does run: for each GENERATION span (operation class `generation`) it
+ * reads the gen_ai input/output message attributes as TEXT — string-valued
+ * only (kvlist/bytes are never decoded) — across the vintages:
+ *   input:  gen_ai.input.messages · gen_ai.prompt (deprecated) ·
+ *           ai.prompt.messages · ai.prompt (Vercel AI SDK)
+ *   output: gen_ai.output.messages · gen_ai.completion (deprecated) ·
+ *           ai.response.text (Vercel AI SDK)
+ * The first present attribute per role wins. Pure; scrub + custody are the
+ * server's (the same scrub the import path uses, then the custody store).
+ */
+export declare const CONTENT_INPUT_CHAIN: readonly ["gen_ai.input.messages", "gen_ai.prompt", "ai.prompt.messages", "ai.prompt"];
+export declare const CONTENT_OUTPUT_CHAIN: readonly ["gen_ai.output.messages", "gen_ai.completion", "ai.response.text"];
+export interface ExtractedContent {
+    /** Lowercase hex trace + span id (the attested step's identity). */
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly role: "input" | "output";
+    /** Which attribute it came from. */
+    readonly attribute: string;
+    readonly text: string;
+}
+/** Extract generation-span message text from a decoded TracesData body. */
+export declare function extractGenerationContent(data: unknown): ExtractedContent[];
+//# sourceMappingURL=otel-content.d.ts.map

package/dist/telemetry/otel-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-content.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,eAAO,MAAM,mBAAmB,wFAAyF,CAAC;AAC1H,eAAO,MAAM,oBAAoB,8EAA+E,CAAC;AAEjH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA+CD,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAwB1E"}

package/dist/telemetry/otel-content.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * ARC-6 / ARC-D6 — OTLP content extraction, GATED. M14 is UNRULED, so this
+ * ships OFF: the server calls it ONLY when its feature gate is on AND the org's
+ * capture posture is `managed` (modelrig-server otlp-content.ts). With the gate
+ * off nothing here runs, and the normalizer (otel-normalize.ts) keeps its STOP
+ * invariant: zero content read.
+ *
+ * When it does run: for each GENERATION span (operation class `generation`) it
+ * reads the gen_ai input/output message attributes as TEXT — string-valued
+ * only (kvlist/bytes are never decoded) — across the vintages:
+ *   input:  gen_ai.input.messages · gen_ai.prompt (deprecated) ·
+ *           ai.prompt.messages · ai.prompt (Vercel AI SDK)
+ *   output: gen_ai.output.messages · gen_ai.completion (deprecated) ·
+ *           ai.response.text (Vercel AI SDK)
+ * The first present attribute per role wins. Pure; scrub + custody are the
+ * server's (the same scrub the import path uses, then the custody store).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTENT_OUTPUT_CHAIN = exports.CONTENT_INPUT_CHAIN = void 0;
+exports.extractGenerationContent = extractGenerationContent;
+const otel_hierarchy_1 = require("./otel-hierarchy");
+exports.CONTENT_INPUT_CHAIN = ["gen_ai.input.messages", "gen_ai.prompt", "ai.prompt.messages", "ai.prompt"];
+exports.CONTENT_OUTPUT_CHAIN = ["gen_ai.output.messages", "gen_ai.completion", "ai.response.text"];
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const HEX = /^[0-9a-fA-F]+$/;
+function hexId(v, bytes) {
+    if (typeof v === "string" && HEX.test(v) && v.length === bytes * 2 && !/^0+$/.test(v))
+        return v.toLowerCase();
+    if (typeof v === "string" && /^[A-Za-z0-9+/]+={0,2}$/.test(v)) {
+        const hex = Buffer.from(v, "base64").toString("hex");
+        if (hex.length === bytes * 2 && !/^0+$/.test(hex))
+            return hex;
+    }
+    return null;
+}
+/** String attributes only — content shapes (kvlist/bytes) are never decoded. */
+function stringAttrs(attributes) {
+    const out = new Map();
+    for (const kv of Array.isArray(attributes) ? attributes : []) {
+        if (!isRec(kv) || typeof kv.key !== "string" || !isRec(kv.value))
+            continue;
+        const s = kv.value.stringValue;
+        if (typeof s === "string" && s !== "")
+            out.set(kv.key, s);
+    }
+    return out;
+}
+/** The raw operation the normalizer would classify — the same priority. */
+function operationOf(attrs) {
+    const oi = attrs.get("openinference.span.kind");
+    if (oi !== undefined)
+        return oi.toLowerCase();
+    const op = attrs.get("gen_ai.operation.name");
+    if (op !== undefined)
+        return op;
+    if (attrs.has("gen_ai.tool.name") || attrs.has("tool.name"))
+        return "execute_tool";
+    for (const k of ["gen_ai.response.model", "ai.model.id", "gen_ai.request.model", "llm.response.model", "llm.model_name", "model"]) {
+        if (attrs.has(k))
+            return "chat";
+    }
+    return "span";
+}
+function first(attrs, chain) {
+    for (const k of chain) {
+        const v = attrs.get(k);
+        if (v !== undefined)
+            return [k, v];
+    }
+    return null;
+}
+/** Extract generation-span message text from a decoded TracesData body. */
+function extractGenerationContent(data) {
+    const out = [];
+    if (!isRec(data))
+        return out;
+    const rsList = data.resourceSpans ?? data.resource_spans;
+    for (const rs of Array.isArray(rsList) ? rsList : []) {
+        if (!isRec(rs))
+            continue;
+        const ssList = rs.scopeSpans ?? rs.scope_spans;
+        for (const ss of Array.isArray(ssList) ? ssList : []) {
+            if (!isRec(ss))
+                continue;
+            for (const span of Array.isArray(ss.spans) ? ss.spans : []) {
+                if (!isRec(span))
+                    continue;
+                const traceId = hexId(span.traceId ?? span.trace_id, 16);
+                const spanId = hexId(span.spanId ?? span.span_id, 8);
+                if (traceId === null || spanId === null)
+                    continue;
+                const attrs = stringAttrs(span.attributes);
+                if ((0, otel_hierarchy_1.operationClassOf)(operationOf(attrs)) !== "generation")
+                    continue;
+                const input = first(attrs, exports.CONTENT_INPUT_CHAIN);
+                const output = first(attrs, exports.CONTENT_OUTPUT_CHAIN);
+                if (input !== null)
+                    out.push({ traceId, spanId, role: "input", attribute: input[0], text: input[1] });
+                if (output !== null)
+                    out.push({ traceId, spanId, role: "output", attribute: output[0], text: output[1] });
+            }
+        }
+    }
+    return out;
+}

package/dist/telemetry/otel-hierarchy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OTLP-in — the trace HIERARCHY half of the normalizer, extracted from
+ * otel-normalize.ts (ARC-γ: the normalizer sat at 662 LOC, near the 700 cap).
+ * PURE: span identity → run/step identity, and step ordering within a run.
+ * No attribute is read here and no content ever reaches this module.
+ */
+import type { WireStep } from "./ingest-protocol";
+/** ARC-6: the classified operation kept in the attested envelope — the five
+ * classes OTLP-in v1 uses (turn numbering + tool counts), or `span` for
+ * anything else (honest: never guessed into a class). */
+export type OperationClass = "generation" | "tool" | "agent" | "retriever" | "embedding" | "span";
+/** Map the normalizer's raw operation string to its class. */
+export declare function operationClassOf(operation: string): OperationClass;
+/** span name → step_key: trimmed, whitespace-collapsed, length-capped, never
+ * empty (the step PK forbids it). */
+export declare function toStepKey(name: unknown): string;
+/** 32-hex trace id → canonical UUID string (runs.id is uuid; 16 bytes ≡ a UUID).
+ * A trace id that is not 16 bytes gets a deterministic UUID derived from it. */
+export declare function traceIdToRunUuid(traceHex: string): string;
+/** The structural identity of the span a pending step came from (ARC-6). */
+export interface SpanShape {
+    readonly id: string;
+    readonly parent: string | null;
+    /** The normalizer's raw operation (`invoke_agent`, `chat`, …). */
+    readonly operation: string;
+    readonly operationClass: OperationClass;
+}
+/** One normalized span awaiting its attempt number. */
+export interface PendingStep {
+    readonly step: WireStep;
+    readonly stepKey: string;
+    readonly startMs: number;
+    readonly span?: SpanShape;
+}
+/**
+ * Assign attempt_no per (run, step_key): repeated same-named spans become
+ * attempts in start-time (then span-id) order — deterministic within a trace.
+ * v0 limitation: a trace split across batches is not deduped (no seen-store);
+ * one trace = one batch is the common, correct case.
+ */
+export declare function assignAttempts(pending: readonly PendingStep[]): WireStep[];
+/**
+ * ARC-6 turn numbering for ONE trace that is a conversation (it carries
+ * `gen_ai.conversation.id` and has `invoke_agent` spans). Each TOP-LEVEL
+ * `invoke_agent` span (no `invoke_agent` ancestor), in start order, is turn n;
+ * every generation span under it (any depth) becomes step `turn:<n>.<k>` in
+ * start order — ARC-α's step-key convention exactly (`turnStepKey`; a repeated
+ * key would read as a retry). The turn number and, on the agent span, the
+ * count of tool spans in that turn ride the attested envelope (`turn`,
+ * `turn_tool_calls`, `turn_generations`). Spans outside every turn are left
+ * as they were. Returns the rewritten list and the number of turns.
+ */
+export declare function numberTurns(pending: readonly PendingStep[]): {
+    pending: PendingStep[];
+    turns: number;
+};
+//# sourceMappingURL=otel-hierarchy.d.ts.map

package/dist/telemetry/otel-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-hierarchy.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel-hierarchy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;yDAEyD;AACzD,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;AAuBlG,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAElE;AAID;qCACqC;AACrC,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAI/C;AAED;gFACgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,QAAQ,EAAE,CAmB1E;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgDtG"}

package/dist/telemetry/otel-hierarchy.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * OTLP-in — the trace HIERARCHY half of the normalizer, extracted from
+ * otel-normalize.ts (ARC-γ: the normalizer sat at 662 LOC, near the 700 cap).
+ * PURE: span identity → run/step identity, and step ordering within a run.
+ * No attribute is read here and no content ever reaches this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operationClassOf = operationClassOf;
+exports.toStepKey = toStepKey;
+exports.traceIdToRunUuid = traceIdToRunUuid;
+exports.assignAttempts = assignAttempts;
+exports.numberTurns = numberTurns;
+const node_crypto_1 = require("node:crypto");
+const conversation_1 = require("../artifacts/conversation");
+const OPERATION_CLASSES = {
+    // gen_ai.operation.name (semconv) + the normalizer's model-presence fallback
+    chat: "generation",
+    text_completion: "generation",
+    generate_content: "generation",
+    completion: "generation",
+    // openinference.span.kind (lower-cased by the normalizer)
+    llm: "generation",
+    generation: "generation",
+    execute_tool: "tool",
+    tool: "tool",
+    invoke_agent: "agent",
+    create_agent: "agent",
+    agent_step: "agent",
+    agent: "agent",
+    retriever: "retriever",
+    retrieval: "retriever",
+    embeddings: "embedding",
+    embedding: "embedding",
+};
+/** Map the normalizer's raw operation string to its class. */
+function operationClassOf(operation) {
+    return OPERATION_CLASSES[operation] ?? "span";
+}
+const WS_RE = /\s+/g;
+/** span name → step_key: trimmed, whitespace-collapsed, length-capped, never
+ * empty (the step PK forbids it). */
+function toStepKey(name) {
+    const raw = typeof name === "string" ? name.trim().replace(WS_RE, " ") : "";
+    if (raw === "")
+        return "span";
+    return raw.slice(0, 200);
+}
+/** 32-hex trace id → canonical UUID string (runs.id is uuid; 16 bytes ≡ a UUID).
+ * A trace id that is not 16 bytes gets a deterministic UUID derived from it. */
+function traceIdToRunUuid(traceHex) {
+    const hex = traceHex.length === 32 ? traceHex : (0, node_crypto_1.createHash)("sha256").update(traceHex).digest("hex").slice(0, 32);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+/**
+ * Assign attempt_no per (run, step_key): repeated same-named spans become
+ * attempts in start-time (then span-id) order — deterministic within a trace.
+ * v0 limitation: a trace split across batches is not deduped (no seen-store);
+ * one trace = one batch is the common, correct case.
+ */
+function assignAttempts(pending) {
+    const out = [];
+    const perKey = new Map();
+    for (const p of pending) {
+        const list = perKey.get(p.stepKey) ?? [];
+        list.push({ step: p.step, startMs: p.startMs });
+        perKey.set(p.stepKey, list);
+    }
+    for (const list of perKey.values()) {
+        list.sort((a, b) => a.startMs !== b.startMs
+            ? a.startMs - b.startMs
+            : (a.step.span_id ?? "") < (b.step.span_id ?? "")
+                ? -1
+                : 1);
+        list.forEach(({ step }, i) => out.push({ ...step, attempt_no: i + 1 }));
+    }
+    return out;
+}
+/** Parent-chain walk bound (a malformed trace can carry a cycle). */
+const MAX_DEPTH = 64;
+function byStart(a, b) {
+    if (a.startMs !== b.startMs)
+        return a.startMs - b.startMs;
+    return (a.span?.id ?? "") < (b.span?.id ?? "") ? -1 : 1;
+}
+/**
+ * ARC-6 turn numbering for ONE trace that is a conversation (it carries
+ * `gen_ai.conversation.id` and has `invoke_agent` spans). Each TOP-LEVEL
+ * `invoke_agent` span (no `invoke_agent` ancestor), in start order, is turn n;
+ * every generation span under it (any depth) becomes step `turn:<n>.<k>` in
+ * start order — ARC-α's step-key convention exactly (`turnStepKey`; a repeated
+ * key would read as a retry). The turn number and, on the agent span, the
+ * count of tool spans in that turn ride the attested envelope (`turn`,
+ * `turn_tool_calls`, `turn_generations`). Spans outside every turn are left
+ * as they were. Returns the rewritten list and the number of turns.
+ */
+function numberTurns(pending) {
+    const byId = new Map();
+    for (const p of pending)
+        if (p.span !== undefined)
+            byId.set(p.span.id, p);
+    const isAgent = (p) => p?.span?.operation === "invoke_agent";
+    /** The top-level invoke_agent ancestor of a span (itself when it is one), or null. */
+    const topAgentOf = (p) => {
+        let top = isAgent(p) ? p : null;
+        let cur = p.span?.parent != null ? byId.get(p.span.parent) : undefined;
+        const seen = new Set([p.span?.id ?? ""]);
+        for (let d = 0; cur !== undefined && d < MAX_DEPTH; d++) {
+            const id = cur.span?.id ?? "";
+            if (seen.has(id))
+                break;
+            seen.add(id);
+            if (isAgent(cur))
+                top = cur;
+            cur = cur.span?.parent != null ? byId.get(cur.span.parent) : undefined;
+        }
+        return top;
+    };
+    const agents = pending.filter((p) => isAgent(p) && topAgentOf(p) === p).sort(byStart);
+    if (agents.length === 0)
+        return { pending: [...pending], turns: 0 };
+    const turnOf = new Map(agents.map((a, i) => [a, i + 1]));
+    const generations = new Map();
+    const tools = new Map();
+    const turnBySpan = new Map();
+    for (const p of pending) {
+        const top = topAgentOf(p);
+        const n = top !== null ? turnOf.get(top) : undefined;
+        if (n === undefined)
+            continue;
+        turnBySpan.set(p, n);
+        if (p.span?.operationClass === "generation")
+            generations.set(n, [...(generations.get(n) ?? []), p]);
+        if (p.span?.operationClass === "tool")
+            tools.set(n, (tools.get(n) ?? 0) + 1);
+    }
+    const keyOf = new Map();
+    for (const [n, list] of generations)
+        list.sort(byStart).forEach((p, i) => keyOf.set(p, (0, conversation_1.turnStepKey)(n, i + 1)));
+    const out = pending.map((p) => {
+        const n = turnBySpan.get(p);
+        if (n === undefined)
+            return p;
+        const env = (typeof p.step.attested === "object" && p.step.attested !== null ? p.step.attested : {});
+        const isTop = turnOf.has(p);
+        const attested = {
+            ...env,
+            turn: n,
+            ...(isTop ? { turn_tool_calls: tools.get(n) ?? 0, turn_generations: generations.get(n)?.length ?? 0 } : {}),
+        };
+        const stepKey = keyOf.get(p) ?? p.stepKey;
+        return { ...p, stepKey, step: { ...p.step, step_key: stepKey, attested } };
+    });
+    return { pending: out, turns: agents.length };
+}

package/dist/telemetry/otel-normalize.d.ts

@@ -23,6 +23,7 @@
  * pattern per §5.3 — implemented fresh here, no bodies copied).
  */
 import type { WireRun, WireStep } from "./ingest-protocol";
+import { type OperationClass } from "./otel-hierarchy";
 export interface AttestedUsage {
     /** Non-cached input tokens (cache buckets subtracted, floored 0). */
     readonly input?: number;
@@ -41,8 +42,21 @@ export interface AttestedEnvelope {
     readonly model: string | null;
     /** Resolved provider — honest, ending at "unknown", NEVER guessed. */
     readonly provider: string;
-    /** Classified operation (generation/tool/agent/retriever/embedding/span). */
+    /** The classifier's raw operation (`invoke_agent`, `chat`, `retriever`, …). */
     readonly operation: string;
+    /** ARC-6: the operation's class — generation | tool | agent | retriever |
+     * embedding, or `span` (unclassified). Additive. */
+    readonly operation_class?: OperationClass;
+    /** ARC-6: the parent span id (lowercase hex), or null for a root span.
+     * Kept for turn numbering + per-turn tool counts only — never rendered as a
+     * tree (spec §9). Additive. */
+    readonly parent_span_id?: string | null;
+    /** ARC-6: in a conversation trace, the turn this span belongs to. */
+    readonly turn?: number;
+    /** ARC-6: on a turn's top-level `invoke_agent` span — tool / generation
+     * spans counted in that turn. */
+    readonly turn_tool_calls?: number;
+    readonly turn_generations?: number;
     /** De-double-counted usage; omitted entirely on agent-aggregate spans. */
     readonly usage?: AttestedUsage;
     /** The emitting instrumentation scope (name + optional version). */

package/dist/telemetry/otel-normalize.d.ts.map

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