fix(ai): thread redaction through generated record<Entity>/call<Entity> + doc nits

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

Author: dmealing

server/typescript/packages/codegen-ts/src/generator-registry.ts

@@ -164,7 +164,7 @@ export const generatorRegistry: Record<string, GeneratorRegistryEntry> = {
 
   "trace-helper": {
     name: "trace-helper",
-    description: "Per-entity typed record<Entity> helper wrapping recordLlmCall (LlmCallBase-derived entities only).",
+    description: "Per-entity typed record<Entity>/call<Entity> trace helpers (extract + buildLlmCallRow + persist; LlmCallBase-derived entities only).",
     tier: "native",
     factory: () => traceHelperFile(),
     options: "outDir?, target?",

server/typescript/packages/codegen-ts/src/generators/trace-helper-file.ts

@@ -45,7 +45,7 @@ export interface TraceHelperOpts {
   target?: string;
 }
 
-/** Walk the super chain looking for a node whose name matches `baseName`. */
+/** Walk the super chain looking for a node named LLM_CALL_BASE. */
 function extendsBase(obj: MetaObject): boolean {
   let cur = obj.superResolved;
   while (cur !== undefined) {
@@ -124,6 +124,9 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
       // that renders the prompt text, calls the LLM, then parses + persists a trace row.
       const textRef = prompt.ownAttr(TEMPLATE_ATTR_TEXT_REF);
       const renderable = typeof textRef === "string";
+      // Same @format attr, two intentionally different shapes: extract() takes the
+      // Format enum (formatLiteral, above → Format.XML/Format.JSON), render() takes the
+      // raw format string (renderFormat, here → e.g. "json"/"xml", default "text").
       const renderFormat = typeof promptFormat === "string" ? promptFormat : "text";
 
       // Build the import block — all imports MUST stay at the top of the emitted file.
@@ -139,6 +142,7 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
         `  extractSchemaFor,`,
         `  Format,`,
         `  type LlmCallInput,`,
+        `  type LlmCallRow,`,
         `} from "@metaobjectsdev/runtime-ts";`,
         renderable
           ? `import { extract, render, type Provider } from "@metaobjectsdev/render";`
@@ -191,11 +195,15 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
         ` *                     Passed explicitly because ObjectManager does not expose`,
         ` *                     its loaded metadata root.`,
         ` * @param input      - LLM call inputs; type \`llmRequest\` as \`${requestType}\`.`,
+        ` * @param opts       - Optional \`redact\` hook applied to the row before persist`,
+        ` *                     (scrub PII/secrets on the typed path, same as the generic`,
+        ` *                     recordLlmCall/callLlm helpers).`,
         ` */`,
         `export async function ${fnName}(`,
         `  om: ObjectManager,`,
         `  responseMo: MetaObject,`,
         `  input: Omit<LlmCallInput, ${recordInputOmit}> & { llmRequest: ${requestType} },`,
+        `  opts?: { redact?: (row: LlmCallRow) => LlmCallRow },`,
         `): Promise<${entityName}TraceResult> {`,
         `  const schema = extractSchemaFor(responseMo, ${formatLiteral});`,
         `  const outcome = extract(input.llmResponseText, schema);`,
@@ -204,7 +212,7 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
         '  const errorDetail = failed ? `lost required: ${outcome.report.lostRequired().join(", ")}` : null;',
         `  const base = buildLlmCallRow(${recordBuildArg});`,
         `  const row = { ...base, voRequest: input.llmRequest, voResponse: failed ? null : outcome.data };`,
-        `  await persistLlmCallRow(new LlmCallDbRecorder(om, "${entityName}"), row);`,
+        `  await persistLlmCallRow(new LlmCallDbRecorder(om, "${entityName}"), row, opts?.redact ? { redact: opts.redact } : undefined);`,
         `  return { status, errorDetail, voResponse: failed ? null : (outcome.data as ${responseRef}) };`,
         `}`,
         ``,
@@ -231,6 +239,8 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
           `  traceId?: string;`,
           `  parentSpanId?: string;`,
           `  sessionId?: string;`,
+          `  /** Optional row-redaction hook applied before persist (scrub PII/secrets). */`,
+          `  redact?: (row: LlmCallRow) => LlmCallRow;`,
           `}`,
           ``,
           `/**`,
@@ -270,7 +280,7 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
           `    }`,
           `  }`,
           `  const row = { ...buildLlmCallRow({ ...recInput, status, errorDetail }), voRequest: payload, voResponse };`,
-          `  await persistLlmCallRow(new LlmCallDbRecorder(deps.om, ${JSON.stringify(entityName)}), row);`,
+          `  await persistLlmCallRow(new LlmCallDbRecorder(deps.om, ${JSON.stringify(entityName)}), row, deps.redact ? { redact: deps.redact } : undefined);`,
           `  return { status, errorDetail, voResponse };`,
           `}`,
         );

server/typescript/packages/codegen-ts/test/ai-trace-sti.test.ts

@@ -66,6 +66,24 @@ describe("ai-trace #1c — STI callType stamping", () => {
   });
 });
 
+describe("ai-trace — redaction threaded through the generated typed path", () => {
+  test("record<Entity> exposes an opts.redact param and threads it to persist", async () => {
+    const { classify } = await genTrace();
+    // The emitted file must import the LlmCallRow type used by the redact callback.
+    expect(classify).toContain("type LlmCallRow,");
+    // Optional 4th param exposing redact.
+    expect(classify).toContain("opts?: { redact?: (row: LlmCallRow) => LlmCallRow }");
+    // Threaded into persistLlmCallRow (exactOptionalPropertyTypes-safe guard).
+    expect(classify).toContain("opts?.redact ? { redact: opts.redact } : undefined");
+  });
+
+  test("call<Entity> exposes redact on CallDeps and threads it to persist", async () => {
+    const { summarize } = await genTrace();
+    expect(summarize).toContain("redact?: (row: LlmCallRow) => LlmCallRow;");
+    expect(summarize).toContain("deps.redact ? { redact: deps.redact } : undefined");
+  });
+});
+
 describe("ai-trace #1c — STI table collapse", () => {
   test("N trace subtypes collapse to one prompt_llm_call table", async () => {
     const dir = mkdtempSync(join(tmpdir(), "ai1c-schema-"));

server/typescript/packages/codegen-ts/test/derive-trace-fields.test.ts

@@ -65,7 +65,7 @@ describe("derive trace fields", () => {
     expect(h).toContain("buildLlmCallRow(");
     expect(h).toContain("voRequest: input.llmRequest");
     expect(h).toContain("voResponse:");
-    expect(h).toContain('persistLlmCallRow(new LlmCallDbRecorder(om, "ClassifyCall"), row)');
+    expect(h).toContain('persistLlmCallRow(new LlmCallDbRecorder(om, "ClassifyCall"), row, opts?.redact ? { redact: opts.redact } : undefined)');
     // stale generic-path entry point must be gone.
     expect(h).not.toContain("recordLlmCall(");
     // non-STI invariant: a trace entity that is NOT a TPH subtype keeps callType