feat(ai): generic recordLlmCall writes base row (raw I/O); buildLlmCallRow + persistLlmCallRow; system field

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/runtime-ts/src/index.ts

@@ -37,5 +37,5 @@ export {
 // Format is re-exported here so callers of recordLlmCall can import it from a
 // single location rather than reaching into @metaobjectsdev/render directly.
 export { Format } from "@metaobjectsdev/render";
-export { LlmCallDbRecorder, NullRecorder, recordLlmCall } from "./llm-recorder.js";
+export { LlmCallDbRecorder, NullRecorder, recordLlmCall, buildLlmCallRow, persistLlmCallRow } from "./llm-recorder.js";
 export type { LlmRecorder, LlmCallRow, LlmCallInput, RecordLlmCallOptions, RecordLlmCallResult } from "./llm-recorder.js";

server/typescript/packages/runtime-ts/src/llm-recorder.ts

@@ -1,20 +1,18 @@
-// LLM call recorder seam + parse-then-persist helper.
+// LLM call recorder seam + base-row factory + shared persist helper.
 //
 // LlmRecorder is a thin write-side interface for persisting LLM call rows.
 // LlmCallDbRecorder writes via ObjectManager.create (using an entity declared
 // in the caller's own metadata).  NullRecorder is the no-op implementation
 // used in unit tests or when tracing is disabled.
 //
-// recordLlmCall combines the extract step (LLM response text → typed VO via
-// the FR-010 extractObject engine) with the persist step in a single
-// failure-resilient transaction: a lost-required field still writes a row
-// (status="error") so every call is observable.
+// recordLlmCall is the GENERIC trace path: it builds the base trace row (the
+// envelope + the raw `llmRequest`/`llmResponse` columns declared on the shipped
+// `LlmCallBase`) and persists it.  It does NOT parse the response into a typed
+// VO — that extract step + the typed voRequest/voResponse columns live on the
+// generated typed helper (a later layer), so this generic path only ever writes
+// the base field set.
 
 import type { ObjectManager } from "./object-manager.js";
-import { extractSchemaFor } from "./extract-object.js";
-import { Format, extract } from "@metaobjectsdev/render";
-import type { ExtractOptions } from "@metaobjectsdev/render";
-import type { MetaObject } from "@metaobjectsdev/metadata";
 
 // =============================================================================
 // Public types
@@ -55,7 +53,7 @@ export class LlmCallDbRecorder implements LlmRecorder {
 }
 
 // =============================================================================
-// recordLlmCall — parse-then-persist
+// recordLlmCall — generic base-row persist
 // =============================================================================
 
 export interface LlmCallInput {
@@ -66,9 +64,12 @@ export interface LlmCallInput {
   /** Logical session/conversation id (gen_ai session grouping). */
   sessionId?: string;
   callType: string;
+  /** gen_ai.system — provider name, caller-supplied. */
+  system?: string;
   /** ISO 8601 timestamp, supplied by the caller before the LLM call was made. */
   startedAt: string;
   llmRequest: unknown;
+  /** Raw response text/body — stored as the raw `llmResponse` column. */
   llmResponseText: string;
   requestModel?: string;
   /** gen_ai.response.model — the model the provider actually used. */
@@ -78,70 +79,68 @@ export interface LlmCallInput {
   costMinor?: number;
   latencyMs?: number;
   finishReason?: string;
+  /** Call outcome, caller-supplied (provider/parse failure → "error"). */
+  status: "ok" | "error";
+  /** Failure detail (null on success). */
+  errorDetail: string | null;
 }
 
 export interface RecordLlmCallOptions {
   recorder: LlmRecorder;
-  responseMo: MetaObject;
-  format?: Format;
-  extractOpts?: Partial<ExtractOptions>;
+  /** Optional scrub/cap applied immediately before persist (PII/secrets). */
+  redact?: (row: LlmCallRow) => LlmCallRow;
 }
 
 export interface RecordLlmCallResult {
-  voResponse: Record<string, unknown> | null;
   status: "ok" | "error";
   errorDetail: string | null;
 }
 
-/**
- * Parse `input.llmResponseText` into a typed VO, then persist a trace row via
- * `opts.recorder` regardless of whether parsing succeeded.
- *
- * Contract:
- * - A lost-required field → status "error", voResponse null, errorDetail set,
- *   row STILL persisted.
- * - A successful parse → status "ok", voResponse is the plain-object form,
- *   row persisted with voResponse populated.
- * - DB errors propagate (never swallowed).
- */
-export async function recordLlmCall(
-  input: LlmCallInput,
-  opts: RecordLlmCallOptions,
-): Promise<RecordLlmCallResult> {
-  // Use the lower-level extract() to get a plain Record (no cyclic back-ref).
-  // extractSchemaFor builds the field descriptors; extract() runs the engine.
-  const schema = extractSchemaFor(opts.responseMo, opts.format ?? Format.JSON);
-  const outcome = extract(input.llmResponseText, schema, opts.extractOpts);
-
-  const failed = outcome.report.hasLostRequired();
-  const status: "ok" | "error" = failed ? "error" : "ok";
-  const errorDetail: string | null = failed
-    ? `lost required: ${outcome.report.lostRequired().join(", ")}`
-    : null;
-  // outcome.data is already a plain Record<string,unknown> — safe to store.
-  const voResponse: Record<string, unknown> | null = failed ? null : outcome.data;
-
-  const row: LlmCallRow = {
-    spanId: input.spanId,
+/** Build the base trace row (envelope + raw llmRequest/llmResponse) — key set
+ *  is exactly LlmCallBase's fields. Typed voRequest/voResponse are added by the
+ *  generated typed helper, never here. */
+export function buildLlmCallRow(input: LlmCallInput): LlmCallRow {
+  return {
     traceId: input.traceId,
+    spanId: input.spanId,
     parentSpanId: input.parentSpanId ?? null,
     sessionId: input.sessionId ?? null,
     callType: input.callType,
+    system: input.system ?? null,
     requestModel: input.requestModel ?? null,
     responseModel: input.responseModel ?? null,
     inputTokens: input.inputTokens ?? null,
     outputTokens: input.outputTokens ?? null,
     costMinor: input.costMinor ?? null,
     latencyMs: input.latencyMs ?? null,
     finishReason: input.finishReason ?? null,
-    status,
-    errorDetail,
+    status: input.status,
+    errorDetail: input.errorDetail,
     startedAt: input.startedAt,
     llmRequest: JSON.stringify(input.llmRequest),
-    voResponse,
+    llmResponse: JSON.stringify(input.llmResponseText),
   };
+}
 
-  await opts.recorder.record(row);
+/** Shared persist step: redact then record. Used by recordLlmCall AND (later) the
+ *  generated typed helper, so redaction applies on both paths. */
+export async function persistLlmCallRow(
+  recorder: LlmRecorder,
+  row: LlmCallRow,
+  opts?: { redact?: (row: LlmCallRow) => LlmCallRow },
+): Promise<void> {
+  await recorder.record(opts?.redact ? opts.redact(row) : row);
+}
 
-  return { voResponse, status, errorDetail };
+/** Persist one base trace row (envelope + raw I/O). Generic — does not extract. */
+export async function recordLlmCall(
+  input: LlmCallInput,
+  opts: RecordLlmCallOptions,
+): Promise<RecordLlmCallResult> {
+  await persistLlmCallRow(
+    opts.recorder,
+    buildLlmCallRow(input),
+    opts.redact ? { redact: opts.redact } : undefined,
+  );
+  return { status: input.status, errorDetail: input.errorDetail };
 }

server/typescript/packages/runtime-ts/test/llm-recorder.test.ts

@@ -1,14 +1,15 @@
 import { describe, test, expect } from "bun:test";
 import { MetaDataLoader } from "@metaobjectsdev/metadata";
-import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
-import { Format } from "@metaobjectsdev/render";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
 import { ObjectManager } from "../src/object-manager.js";
 import { inMemoryDriver } from "../src/drivers/in-memory-driver.js";
 import {
   NullRecorder,
   LlmCallDbRecorder,
   recordLlmCall,
+  buildLlmCallRow,
   type LlmCallRow,
+  type LlmCallInput,
 } from "../src/llm-recorder.js";
 
 // =============================================================================
@@ -36,6 +37,7 @@ const META_JSON = {
             { "field.string": { name: "parentSpanId" } },
             { "field.string": { name: "sessionId" } },
             { "field.string": { name: "callType" } },
+            { "field.string": { name: "system" } },
             { "field.string": { name: "requestModel" } },
             { "field.string": { name: "responseModel" } },
             { "field.long": { name: "inputTokens" } },
@@ -50,6 +52,8 @@ const META_JSON = {
             // ObjectManager writes the JSON.stringify'd string; in-memory driver
             // keeps it as a string on read-back.
             { "field.string": { name: "llmRequest", "@dbColumnType": "jsonb" } },
+            // llmResponse: raw response body as jsonb string (matches LlmCallBase).
+            { "field.string": { name: "llmResponse", "@dbColumnType": "jsonb" } },
             // voResponse: typed VO stored as jsonb via @objectRef + @storage.
             // ObjectManager validates the object against VerdictResponse and stores it.
             { "field.object": { name: "voResponse", "@objectRef": "VerdictResponse", "@storage": "jsonb" } },
@@ -133,13 +137,11 @@ describe("LlmCallDbRecorder", () => {
 // Task 2 — recordLlmCall
 // =============================================================================
 
-describe("recordLlmCall", () => {
-  test("good response → status ok, voResponse populated, row persisted", async () => {
+describe("recordLlmCall (generic base-row path)", () => {
+  test("status ok → base row persisted (raw llmRequest/llmResponse, no voResponse)", async () => {
     const root = await loadFixture();
     const om = makeOm(root);
     const recorder = new LlmCallDbRecorder(om, "TraceCall");
-    const verdictMo = root.findObject("VerdictResponse") as MetaObject;
-    expect(verdictMo).toBeDefined();
 
     const result = await recordLlmCall(
       {
@@ -149,29 +151,34 @@ describe("recordLlmCall", () => {
         startedAt: "2026-01-01T00:00:00Z",
         llmRequest: { prompt: "hello" },
         llmResponseText: '{"verdict":"approve","score":90}',
+        status: "ok",
+        errorDetail: null,
       },
-      { recorder, responseMo: verdictMo, format: Format.JSON },
+      { recorder },
     );
 
+    // recordLlmCall echoes the caller-supplied outcome; it does not extract.
     expect(result.status).toBe("ok");
     expect(result.errorDetail).toBeNull();
-    expect(result.voResponse).toEqual({ verdict: "approve", score: 90 });
 
-    // Row must have been persisted
+    // Row must have been persisted with the raw envelope + I/O.
     const row = await om.findById("TraceCall", 1);
     expect(row).not.toBeNull();
     expect(row!.spanId).toBe("span-ok");
     expect(row!.status).toBe("ok");
-    expect(row!.voResponse).toEqual({ verdict: "approve", score: 90 });
+    // The generic path never writes voResponse — TraceCall declares it nullable,
+    // so it stays absent/null in the stored row.
+    expect(row!.voResponse ?? null).toBeNull();
     // In-memory driver stores llmRequest as the JSON string (field.string + @dbColumnType jsonb).
     expect(JSON.parse(row!.llmRequest as string)).toEqual({ prompt: "hello" });
+    // llmResponse stores the JSON-encoded raw response text.
+    expect(JSON.parse(row!.llmResponse as string)).toBe('{"verdict":"approve","score":90}');
   });
 
-  test("bad response (missing required verdict) → status error, voResponse null, row still persisted", async () => {
+  test("caller-supplied error outcome is threaded onto the persisted row", async () => {
     const root = await loadFixture();
     const om = makeOm(root);
     const recorder = new LlmCallDbRecorder(om, "TraceCall");
-    const verdictMo = root.findObject("VerdictResponse") as MetaObject;
 
     const result = await recordLlmCall(
       {
@@ -181,45 +188,28 @@ describe("recordLlmCall", () => {
         startedAt: "2026-01-01T00:00:00Z",
         llmRequest: { prompt: "hello" },
         llmResponseText: '{"score":50}',
+        status: "error",
+        errorDetail: "lost required: verdict",
       },
-      { recorder, responseMo: verdictMo, format: Format.JSON },
+      { recorder },
     );
 
     expect(result.status).toBe("error");
-    expect(result.voResponse).toBeNull();
-    expect(typeof result.errorDetail).toBe("string");
-    expect(result.errorDetail).toContain("verdict");
+    expect(result.errorDetail).toBe("lost required: verdict");
 
-    // Row must STILL have been persisted (failure-resilient contract)
+    // Row must STILL have been persisted (every call is observable).
     const row = await om.findById("TraceCall", 1);
     expect(row).not.toBeNull();
     expect(row!.spanId).toBe("span-bad");
     expect(row!.status).toBe("error");
-    expect(row!.voResponse).toBeNull();
-    expect(typeof row!.errorDetail).toBe("string");
+    expect(row!.errorDetail).toBe("lost required: verdict");
   });
 });
 
 // =============================================================================
 // Task 4 — parentSpanId + sessionId envelope fields
 // =============================================================================
 
-// Minimal metadata: a value object with one required string field.
-// Mirrors the VerdictResponse shape used in the integration test.
-const ENVELOPE_META = JSON.stringify({
-  "metadata.root": {
-    package: "test::ai",
-    children: [
-      {
-        "object.value": {
-          name: "Resp",
-          children: [{ "field.string": { name: "verdict", "@required": true } }],
-        },
-      },
-    ],
-  },
-});
-
 // A capturing recorder that stores the last row written by recordLlmCall.
 class CaptureRecorder extends NullRecorder {
   last: LlmCallRow | null = null;
@@ -228,16 +218,9 @@ class CaptureRecorder extends NullRecorder {
   }
 }
 
-async function loadRespMo() {
-  const res = await MetaDataLoader.fromString(ENVELOPE_META, "json");
-  expect(res.errors).toEqual([]);
-  return res.root.findObject("Resp")!;
-}
-
 describe("recordLlmCall envelope fields — parentSpanId + sessionId", () => {
   test("threads parentSpanId + sessionId into the persisted row", async () => {
     const rec = new CaptureRecorder();
-    const responseMo = await loadRespMo();
     await recordLlmCall(
       {
         spanId: "s1",
@@ -248,16 +231,17 @@ describe("recordLlmCall envelope fields — parentSpanId + sessionId", () => {
         startedAt: "2026-06-05T00:00:00Z",
         llmRequest: { a: 1 },
         llmResponseText: JSON.stringify({ verdict: "ok" }),
+        status: "ok",
+        errorDetail: null,
       },
-      { recorder: rec, responseMo },
+      { recorder: rec },
     );
     expect(rec.last?.parentSpanId).toBe("p1");
     expect(rec.last?.sessionId).toBe("sess1");
   });
 
   test("omitted parentSpanId + sessionId default to null in the row", async () => {
     const rec = new CaptureRecorder();
-    const responseMo = await loadRespMo();
     await recordLlmCall(
       {
         spanId: "s2",
@@ -266,10 +250,36 @@ describe("recordLlmCall envelope fields — parentSpanId + sessionId", () => {
         startedAt: "2026-06-05T00:00:00Z",
         llmRequest: {},
         llmResponseText: JSON.stringify({ verdict: "ok" }),
+        status: "ok",
+        errorDetail: null,
       },
-      { recorder: rec, responseMo },
+      { recorder: rec },
     );
     expect(rec.last?.parentSpanId).toBeNull();
     expect(rec.last?.sessionId).toBeNull();
   });
 });
+
+// =============================================================================
+// Task 1 (P0) — buildLlmCallRow: base-row factory (exactly LlmCallBase fields)
+// =============================================================================
+
+const BASE_INPUT: LlmCallInput = {
+  spanId: "s", traceId: "t", callType: "X",
+  startedAt: "2026-06-06T00:00:00Z",
+  llmRequest: { q: 1 }, llmResponseText: '{"a":1}',
+  status: "ok", errorDetail: null,
+};
+
+describe("buildLlmCallRow", () => {
+  test("row keys exactly match LlmCallBase's 18 fields (no voResponse; with llmResponse + system)", () => {
+    const row = buildLlmCallRow({ ...BASE_INPUT, system: "anthropic" });
+    const base = ["traceId","spanId","parentSpanId","sessionId","callType","system",
+      "requestModel","responseModel","inputTokens","outputTokens","costMinor",
+      "latencyMs","finishReason","status","errorDetail","startedAt","llmRequest","llmResponse"];
+    expect(Object.keys(row).sort()).toEqual([...base].sort());
+    expect("voResponse" in row).toBe(false);
+    expect(row.system).toBe("anthropic");
+    expect(row.llmRequest).toBe('{"q":1}');
+  });
+});