@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/dist/generators/template-source-annotate.js

@@ -0,0 +1,184 @@
+// Annotated-template IR (linked-template-source-docs, Task 1).
+//
+// annotateTemplate parses a Mustache template into an ordered TplToken[] where
+// every {{variable}} / {{#section}} is resolved to the payload field it
+// references plus that field's doc link. It tokenizes with the SAME parser
+// verify walks (`parseTemplate` from @metaobjectsdev/render) and resolves each
+// path with verify's EXPORTED `resolveTemplateVariable` — so the annotator and
+// the build-time drift gate share ONE resolution and can never disagree (a
+// later conformance gate asserts exactly that).
+//
+// Reuse, not reimplementation:
+//   • parseTemplate          — the render verify engine's Mustache.parse.
+//   • resolveTemplateVariable — verify's context-stack walk (sections push the
+//                               nested subtree; dotted paths descend). Generic
+//                               over the node, so an ENRICHED tree (carrying
+//                               owner/type/required) resolves identically.
+//
+// The annotator is a pure function over an enriched payload tree + the source —
+// no metadata import, no I/O — so it is unit-testable and golden-pinnable.
+import { parseTemplate, resolveTemplateVariable, } from "@metaobjectsdev/render";
+import { fieldAnchorSlug } from "./field-anchor.js";
+/** The doc-page href for a resolved field: `./<OwnerVO>.md#field-<name>`. The
+ *  anchor slug comes from the SHARED `fieldAnchorSlug()` (prefixed — avoids
+ *  colliding with other page anchors), the SAME helper the entity page uses to
+ *  emit its per-field `<a id="field-<name>">` anchor, so the link and the anchor
+ *  can never drift. */
+function fieldHref(owner, name) {
+    return `./${owner}.md#${fieldAnchorSlug(name)}`;
+}
+function toResolvedField(f) {
+    return { owner: f.owner, name: f.name, type: f.type, required: f.required };
+}
+/**
+ * Parse `source` into an annotated IR, resolving each variable/section against
+ * the enriched `payload` tree using verify's shared resolution.
+ */
+export function annotateTemplate(source, payload, opts) {
+    const root = payload;
+    const out = [];
+    let cursor = 0;
+    // How a resolved field's href is built: the injected layout-aware resolver
+    // when provided, else the flat default (byte-identical to today's output).
+    const buildFieldHref = opts.fieldHref ?? fieldHref;
+    // Emit verbatim source between `cursor` and `to` as a text token, advancing
+    // the cursor. This recovers literal text AND any span Mustache trimmed as
+    // standalone (e.g. the newline after a standalone partial/section), so the
+    // concatenated tokens reproduce the source byte-for-byte.
+    function emitTextUpTo(to) {
+        if (to > cursor) {
+            out.push({ kind: "text", text: source.slice(cursor, to) });
+            cursor = to;
+        }
+    }
+    function resolveAt(stack, path) {
+        const hit = resolveTemplateVariable(stack, path);
+        if (!hit)
+            return undefined;
+        const field = toResolvedField(hit);
+        return { field, href: buildFieldHref(field.owner, field.name) };
+    }
+    // Build a variable token ({{x}} or {{&x}}/{{{x}}}). The implicit iterator
+    // `.` is always valid against the current context; any other path resolves
+    // against the enriched tree (carrying field + href when found).
+    function makeVarToken(kind, raw, value, stack) {
+        if (value === ".")
+            return { kind, raw, path: value, valid: true };
+        const r = resolveAt(stack, value);
+        return r
+            ? { kind, raw, path: value, field: r.field, href: r.href, valid: true }
+            : { kind, raw, path: value, valid: false };
+    }
+    function walk(tokens, stack) {
+        for (const tok of tokens) {
+            const type = tok[0];
+            const value = tok[1];
+            const start = tok[2];
+            const end = tok[3];
+            // Recover any source between the previous token and this tag (literal
+            // text, or trimmed standalone whitespace).
+            emitTextUpTo(start);
+            switch (type) {
+                case "text": {
+                    out.push({ kind: "text", text: source.slice(start, end) });
+                    cursor = end;
+                    break;
+                }
+                case "name": {
+                    // {{x}} — escaped variable.
+                    const raw = source.slice(start, end);
+                    cursor = end;
+                    out.push(makeVarToken("var", raw, value, stack));
+                    break;
+                }
+                case "&":
+                case "{": {
+                    // {{&x}} / {{{x}}} — unescaped variable (mustache.js emits "&" for both).
+                    const raw = source.slice(start, end);
+                    cursor = end;
+                    out.push(makeVarToken("unescaped", raw, value, stack));
+                    break;
+                }
+                case "#":
+                case "^": {
+                    // {{#x}}…{{/x}} (section) / {{^x}}…{{/x}} (inverted). `end` is the end
+                    // of the OPENING tag; subTokens at [4]; [5] is where the closing tag
+                    // begins. Emit the open tag, recurse the body in the pushed context,
+                    // then emit the close tag.
+                    const sub = Array.isArray(tok[4]) ? tok[4] : [];
+                    const closeStart = tok[5];
+                    const openRaw = source.slice(start, end);
+                    cursor = end;
+                    const isImplicit = value === ".";
+                    const r = isImplicit ? undefined : resolveAt(stack, value);
+                    const kind = type === "#" ? "section" : "inverted";
+                    out.push(r
+                        ? {
+                            kind,
+                            raw: openRaw,
+                            path: value,
+                            field: r.field,
+                            href: r.href,
+                        }
+                        : { kind, raw: openRaw, path: value });
+                    // `#` over a container pushes its element fields; `^` (and `#` over a
+                    // scalar conditional) keep the current context — EXACTLY verify's rule.
+                    const hit = isImplicit
+                        ? undefined
+                        : resolveTemplateVariable(stack, value);
+                    const nested = type === "#" ? hit?.fields : undefined;
+                    const childStack = nested !== undefined ? [...stack, nested] : stack;
+                    walk(sub, childStack);
+                    // The closing tag `{{/value}}` runs from closeStart to the end of the
+                    // section. Recover any body remainder Mustache trimmed, then emit close.
+                    emitTextUpTo(closeStart);
+                    // The close tag's exact end isn't in the token; derive it from the
+                    // literal `{{/…}}` form starting at closeStart so the raw is verbatim.
+                    const closeRaw = readCloseTag(source, closeStart, value);
+                    out.push({ kind: "close", raw: closeRaw, path: value });
+                    cursor = closeStart + closeRaw.length;
+                    break;
+                }
+                case ">": {
+                    // {{>ref}} — partial.
+                    const raw = source.slice(start, end);
+                    cursor = end;
+                    const href = opts.resolvePartialHref?.(value);
+                    out.push(href !== undefined
+                        ? { kind: "partial", raw, ref: value, href }
+                        : { kind: "partial", raw, ref: value });
+                    break;
+                }
+                case "!": {
+                    // {{! comment }}.
+                    out.push({ kind: "comment", raw: source.slice(start, end) });
+                    cursor = end;
+                    break;
+                }
+                default: {
+                    // set-delimiter (=) or any other: preserve verbatim as text.
+                    if (Number.isFinite(end) && end > start) {
+                        out.push({ kind: "text", text: source.slice(start, end) });
+                        cursor = end;
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    walk(parseTemplate(source), [root]);
+    // Any trailing source after the last token (e.g. a standalone-trimmed final
+    // newline) is recovered as text.
+    emitTextUpTo(source.length);
+    return out;
+}
+// Read the verbatim closing tag `{{/name}}` (with any inner whitespace the
+// author wrote) starting at `from`. Mustache only gives the close-tag start, so
+// we locate the terminating `}}` from there to recover the exact source span.
+function readCloseTag(source, from, _name) {
+    const close = source.indexOf("}}", from);
+    if (close === -1)
+        return source.slice(from);
+    return source.slice(from, close + 2);
+}
+//# sourceMappingURL=template-source-annotate.js.map

package/dist/generators/template-source-annotate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-source-annotate.js","sourceRoot":"","sources":["../../src/generators/template-source-annotate.ts"],"names":[],"mappings":"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"}

package/dist/generators/template-source-render.d.ts

@@ -0,0 +1,24 @@
+import type { TplToken } from "./template-source-annotate.js";
+/**
+ * Reconstruct the verbatim template source from the tokens and wrap it in a
+ * ```mustache fenced block. Concatenating `text` (text tokens) / `raw` (tag
+ * tokens) round-trips the original source byte-for-byte (the annotator pins
+ * this), so the fence body is the clean, highlightable source.
+ */
+export declare function renderSourceBlock(tokens: TplToken[]): string;
+/**
+ * A Markdown table of the unique referenced variables. Resolved variables link
+ * to their field doc (`[owner.name](href)`); unresolved ones are em-dashed and
+ * carry a "not on payload" note in the Type cell. Returns "" when there are no
+ * variables (keeps the page clean).
+ */
+export declare function renderVariablesTable(tokens: TplToken[]): string;
+/**
+ * The collapsed <details> "Linked view": a <pre> reproducing the template where
+ * each token is an inline-styled <span> (color by kind) and each resolved
+ * variable/section is additionally wrapped in a clickable <a href>. Whitespace
+ * and newlines are preserved inside the <pre>. Collapsed by default (no `open`)
+ * so the plain/agent view stays clean; a human expands it for the clickable vars.
+ */
+export declare function renderRichLinkedHtml(tokens: TplToken[]): string;
+//# sourceMappingURL=template-source-render.d.ts.map

package/dist/generators/template-source-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-source-render.d.ts","sourceRoot":"","sources":["../../src/generators/template-source-render.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAI9D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAG5D;AAoDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAsB/D;AAsCD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAyC/D"}

package/dist/generators/template-source-render.js

@@ -0,0 +1,175 @@
+// Template-source renderers (linked-template-source-docs, Task 3).
+//
+// ONE annotated IR (the TplToken[] from annotateTemplate), THREE doc forms — no
+// re-derivation, no second parse. All three are pure functions over the tokens:
+//
+//   • renderSourceBlock     — the verbatim template inside a ```mustache fence.
+//                             The annotator round-trips the source via text/raw,
+//                             so the fenced body equals the original byte-for-byte
+//                             and any viewer/site highlighter colors it.
+//   • renderVariablesTable  — a Markdown table of the UNIQUE referenced variables
+//                             (vars + sections that resolve to a field), each a
+//                             Markdown-native `[owner.name](href)` link (or flagged
+//                             "not on payload" when unresolved). Agent-clean.
+//   • renderRichLinkedHtml  — a collapsed <details> whose <pre> reproduces the
+//                             template with each token in a SELF-CONTAINED
+//                             inline-styled <span> (color per kind) and each
+//                             resolved variable/section wrapped in a clickable
+//                             <a href>. Inline styles only (no external CSS) so it
+//                             renders identically on GitHub and a static site.
+//
+// Color (block + rich view), links (table + rich view), agent-cleanliness (block
+// + table) — all from the same source of truth.
+// ── 1. Source block ────────────────────────────────────────────────────────
+/**
+ * Reconstruct the verbatim template source from the tokens and wrap it in a
+ * ```mustache fenced block. Concatenating `text` (text tokens) / `raw` (tag
+ * tokens) round-trips the original source byte-for-byte (the annotator pins
+ * this), so the fence body is the clean, highlightable source.
+ */
+export function renderSourceBlock(tokens) {
+    const source = reconstructSource(tokens);
+    return "```mustache\n" + source + "\n```";
+}
+/** Concatenate the verbatim span of every token (text or tag raw). */
+function reconstructSource(tokens) {
+    let out = "";
+    for (const t of tokens)
+        out += t.kind === "text" ? t.text : t.raw;
+    return out;
+}
+/** Collect the unique referenced variables (vars/unescaped + sections/inverted
+ *  that carry a path), deduped by path, in first-seen order. Implicit-iterator
+ *  `.` tokens and close tokens are not "variables" and are skipped. */
+function collectVarRows(tokens) {
+    const seen = new Set();
+    const rows = [];
+    for (const t of tokens) {
+        const isRef = t.kind === "var" ||
+            t.kind === "unescaped" ||
+            t.kind === "section" ||
+            t.kind === "inverted";
+        if (!isRef)
+            continue;
+        if (t.path === "." || seen.has(t.path))
+            continue;
+        seen.add(t.path);
+        rows.push({
+            path: t.path,
+            owner: t.field?.owner,
+            name: t.field?.name,
+            type: t.field?.type,
+            required: t.field?.required,
+            href: t.href,
+        });
+    }
+    return rows;
+}
+/** Markdown-escape a table cell whose text may contain a `|`. */
+function mdCell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/**
+ * A Markdown table of the unique referenced variables. Resolved variables link
+ * to their field doc (`[owner.name](href)`); unresolved ones are em-dashed and
+ * carry a "not on payload" note in the Type cell. Returns "" when there are no
+ * variables (keeps the page clean).
+ */
+export function renderVariablesTable(tokens) {
+    const rows = collectVarRows(tokens);
+    if (rows.length === 0)
+        return "";
+    const lines = [
+        "| Variable | Field | Type | Required |",
+        "| --- | --- | --- | --- |",
+    ];
+    for (const r of rows) {
+        const variable = `\`{{${mdCell(r.path)}}}\``;
+        if (r.href && r.owner && r.name) {
+            const field = `[${r.owner}.${r.name}](${r.href})`;
+            const type = r.type ? mdCell(r.type) : "—";
+            const required = r.required ? "yes" : "no";
+            lines.push(`| ${variable} | ${field} | ${type} | ${required} |`);
+        }
+        else {
+            // Unresolved: no field/type/required. Keep the 4-column shape; flag it
+            // "not on payload" in the Field cell, em-dash the rest.
+            lines.push(`| ${variable} | — (not on payload) | — | — |`);
+        }
+    }
+    return lines.join("\n");
+}
+// ── 3. Rich linked HTML ────────────────────────────────────────────────────
+// Per-kind inline color (self-contained — no external CSS, no classes). Chosen
+// for legibility on both GitHub's light/dark Markdown and a generic docs site.
+const STYLE_VAR = "color:#0969da"; // blue — escaped/unescaped variable
+const STYLE_SECTION = "color:#8250df"; // purple — section / inverted / close
+const STYLE_PARTIAL = "color:#1a7f7a"; // teal — partial reference
+const STYLE_COMMENT = "color:#6e7781;font-style:italic"; // gray italic — comment
+/** HTML-escape literal text so `<`, `>`, `&`, `"` in the template don't break
+ *  the surrounding HTML. Quotes are escaped too so token raw is safe in any
+ *  attribute-adjacent position. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** An inline-styled span for a token kind, escaping the inner verbatim text. */
+function styledSpan(style, inner) {
+    return `<span style="${style}">${inner}</span>`;
+}
+/** A styled span for a token kind, wrapped in a clickable `<a href>` when the
+ *  token resolved to a link (else the bare span). The raw text is HTML-escaped. */
+function linkSpan(style, raw, href) {
+    const span = styledSpan(style, escapeHtml(raw));
+    return href ? `<a href="${escapeHtml(href)}">${span}</a>` : span;
+}
+/**
+ * The collapsed <details> "Linked view": a <pre> reproducing the template where
+ * each token is an inline-styled <span> (color by kind) and each resolved
+ * variable/section is additionally wrapped in a clickable <a href>. Whitespace
+ * and newlines are preserved inside the <pre>. Collapsed by default (no `open`)
+ * so the plain/agent view stays clean; a human expands it for the clickable vars.
+ */
+export function renderRichLinkedHtml(tokens) {
+    let pre = "";
+    for (const t of tokens) {
+        switch (t.kind) {
+            case "text": {
+                // Default color; escape literal text verbatim (preserves newlines).
+                pre += escapeHtml(t.text);
+                break;
+            }
+            case "var":
+            case "unescaped": {
+                pre += linkSpan(STYLE_VAR, t.raw, t.href);
+                break;
+            }
+            case "section":
+            case "inverted":
+            case "close": {
+                // Only open tags (section/inverted) carry an href; close tags don't.
+                const href = "href" in t ? t.href : undefined;
+                pre += linkSpan(STYLE_SECTION, t.raw, href);
+                break;
+            }
+            case "partial": {
+                pre += linkSpan(STYLE_PARTIAL, t.raw, t.href);
+                break;
+            }
+            case "comment": {
+                pre += styledSpan(STYLE_COMMENT, escapeHtml(t.raw));
+                break;
+            }
+        }
+    }
+    return ("<details>\n" +
+        "<summary>Linked view</summary>\n\n" +
+        '<pre style="white-space:pre-wrap;word-break:break-word">' +
+        pre +
+        "</pre>\n\n" +
+        "</details>");
+}
+//# sourceMappingURL=template-source-render.js.map

package/dist/generators/template-source-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-source-render.js","sourceRoot":"","sources":["../../src/generators/template-source-render.ts"],"names":[],"mappings":"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"}

package/dist/generators/trace-helper-file.d.ts

@@ -0,0 +1,9 @@
+import { type GeneratorFactory } from "../generator.js";
+export interface TraceHelperOpts {
+    /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+    outDir?: string;
+    /** Optional named output target (registry key). Defaults to "default". */
+    target?: string;
+}
+export declare const traceHelperFile: GeneratorFactory<TraceHelperOpts>;
+//# sourceMappingURL=trace-helper-file.d.ts.map

package/dist/generators/trace-helper-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-helper-file.d.ts","sourceRoot":"","sources":["../../src/generators/trace-helper-file.ts"],"names":[],"mappings":"AA6BA,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAQzB,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiBD,eAAO,MAAM,eAAe,EA4OvB,gBAAgB,CAAC,eAAe,CAAC,CAAC"}

package/dist/generators/trace-helper-file.js

@@ -0,0 +1,196 @@
+// server/typescript/packages/codegen-ts/src/generators/trace-helper-file.ts
+//
+// Stock generator that emits one <Entity>.trace.ts helper file for each concrete
+// entity that (a) extends LlmCallBase (directly or transitively) and (b) nests a
+// template.prompt with @payloadRef and/or @responseRef.
+//
+// The emitted helper exports an async function `record<Entity>(om, responseMo, input)`
+// that EXTRACTS the typed response VO itself and persists ONE row = base envelope +
+// raw I/O (via buildLlmCallRow) PLUS the typed voRequest/voResponse columns. The
+// helper is typed against the generated payload interfaces (request + response VOs)
+// so call-sites get compile-time checks.
+//
+// NOTE: ObjectManager does not expose its loaded metadata root, so the caller must
+// pass the resolved `responseMo: MetaObject` explicitly.  The generated helper
+// documents this in its JSDoc.
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., entityFile(), queriesFile(), traceHelperFile(), barrel()]
+import { TYPE_OBJECT, TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF, TEMPLATE_ATTR_FORMAT, TEMPLATE_ATTR_TEXT_REF, } from "@metaobjectsdev/metadata";
+import { perEntity, } from "../generator.js";
+import { generatePayloadInterfacesBatch } from "../payload-codegen.js";
+import { GENERATED_HEADER } from "../constants.js";
+import { tphDiscriminatorPin } from "../templates/zod-validators.js";
+/** Short name of the shipped abstract base every trace entity extends. */
+const LLM_CALL_BASE = "LlmCallBase";
+/** Walk the super chain looking for a node named LLM_CALL_BASE. */
+function extendsBase(obj) {
+    let cur = obj.superResolved;
+    while (cur !== undefined) {
+        if (cur.name === LLM_CALL_BASE)
+            return true;
+        cur = cur.superResolved;
+    }
+    return false;
+}
+/** Capitalise the first character. */
+function pascal(s) {
+    return s.length > 0 ? s[0].toUpperCase() + s.slice(1) : s;
+}
+export const traceHelperFile = function traceHelperFile(opts) {
+    const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+    const generator = {
+        name: "trace-helper",
+        generate: perEntity((entity, ctx) => {
+            // Only concrete entities derived from LlmCallBase.
+            if (entity.isAbstract)
+                return [];
+            if (!extendsBase(entity))
+                return [];
+            // Find the nested template.prompt.
+            const prompt = entity.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
+            if (prompt === undefined)
+                return [];
+            const payloadRef = prompt.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+            const responseRef = prompt.ownAttr(TEMPLATE_ATTR_RESPONSE_REF);
+            // @responseRef types the result; @payloadRef types the request. Both gate
+            // the helper: the entity must declare voRequest/voResponse field.object
+            // columns (authored) for these writes to land, and the prompt's refs name
+            // the VOs to render/extract into.
+            if (typeof responseRef !== "string")
+                return [];
+            if (typeof payloadRef !== "string")
+                return [];
+            const entityName = entity.name;
+            const fnName = `record${pascal(entityName)}`;
+            // STI: a trace entity that is a TPH subtype stamps its declared
+            // discriminator value as callType and drops callType from the caller input
+            // (industry-standard STI — the discriminator is framework-managed).
+            const tphPin = tphDiscriminatorPin(entity);
+            const sti = tphPin !== undefined;
+            const callTypeValue = sti ? tphPin.value : entityName;
+            // Emitted record<Entity> fragments. The caller never supplies the derived
+            // status/errorDetail (the helper computes them from extraction), and an STI
+            // subtype additionally drops the framework-managed callType discriminator.
+            const recordInputOmit = sti
+                ? `"llmRequest" | "status" | "errorDetail" | "callType"`
+                : `"llmRequest" | "status" | "errorDetail"`;
+            // The object spread passed to buildLlmCallRow: STI subtypes stamp their
+            // discriminator value, all helpers fold in the derived status/errorDetail.
+            const recordBuildArg = sti
+                ? `{ ...input, callType: ${JSON.stringify(callTypeValue)}, status, errorDetail }`
+                : `{ ...input, status, errorDetail }`;
+            // Derive the parse format from the prompt's @format attr.
+            // "xml" → Format.XML; absent or any other value → Format.JSON.
+            const promptFormat = prompt.ownAttr(TEMPLATE_ATTR_FORMAT);
+            const formatLiteral = typeof promptFormat === "string" && promptFormat.toLowerCase() === "xml"
+                ? "Format.XML"
+                : "Format.JSON";
+            // Collect VO names for interface emission (dedupe via batch emitter).
+            // Both refs are guaranteed strings by the guards above.
+            const interfaces = generatePayloadInterfacesBatch(ctx.loadedRoot, [payloadRef, responseRef]);
+            const requestType = payloadRef;
+            // A renderable prompt (carries @textRef) gets an additional call<Entity> helper
+            // 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.
+            // `extract` + `render` both live in @metaobjectsdev/render: import them together
+            // (one de-duplicated statement) when the prompt is renderable, else import only
+            // `extract`.
+            const importLines = [
+                `import type { ObjectManager } from "@metaobjectsdev/runtime-ts";`,
+                `import {`,
+                `  LlmCallDbRecorder,`,
+                `  buildLlmCallRow,`,
+                `  persistLlmCallRow,`,
+                `  extractSchemaFor,`,
+                `  Format,`,
+                `  type LlmCallInput,`,
+                `  type LlmCallRow,`,
+                `} from "@metaobjectsdev/runtime-ts";`,
+                renderable
+                    ? `import { extract, render, type Provider } from "@metaobjectsdev/render";`
+                    : `import { extract } from "@metaobjectsdev/render";`,
+                `import type { MetaObject } from "@metaobjectsdev/metadata";`,
+            ];
+            if (renderable) {
+                importLines.push(`import {`, `  runLlmCall,`, `  type RunLlmCallInput,`, `  type RunLlmCallDeps,`, `  type LlmClient,`, `  type LlmRequest,`, `  type CostFn,`, `  type Clock,`, `  type IdGen,`, `} from "@metaobjectsdev/ai-runtime";`);
+            }
+            const lines = [
+                `// ${GENERATED_HEADER} — DO NOT EDIT.`,
+                ``,
+                ...importLines,
+                ``,
+                `// ---- Payload interfaces (inlined) ------------------------------------------`,
+                ``,
+                interfaces.trimEnd(),
+                ``,
+                `// ---- Typed result -----------------------------------------------------------`,
+                ``,
+                `export interface ${entityName}TraceResult {`,
+                `  status: "ok" | "error";`,
+                `  errorDetail: string | null;`,
+                `  /** Parsed response VO, or null when extraction reported a lost-required field. */`,
+                `  /** Note: voResponse is the plain extracted record typed as the response shape (structural, not an instance). */`,
+                `  voResponse: ${responseRef} | null;`,
+                `}`,
+                ``,
+                `// ---- Record helper ----------------------------------------------------------`,
+                ``,
+                `/**`,
+                ` * Record a single ${entityName} LLM call: extract the response VO and persist a`,
+                ` * trace row via ObjectManager regardless of whether extraction succeeded.`,
+                ` *`,
+                ` * @param om         - ObjectManager wired to the application database.`,
+                ` * @param responseMo - MetaObject for \`${responseRef}\` (resolve via the loaded`,
+                ` *                     metadata root: \`root.findObject("${responseRef}")\`).`,
+                ` *                     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);`,
+                `  const failed = outcome.report.hasLostRequired();`,
+                `  const status = failed ? ("error" as const) : ("ok" as const);`,
+                '  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, opts?.redact ? { redact: opts.redact } : undefined);`,
+                `  return { status, errorDetail, voResponse: failed ? null : (outcome.data as ${responseRef}) };`,
+                `}`,
+                ``,
+            ];
+            if (renderable) {
+                const callFn = `call${pascal(entityName)}`;
+                lines.push(``, `// ---- Call helper (GENERATE -> CALL -> record) -------------------------------`, ``, `export interface ${entityName}CallDeps {`, `  om: ObjectManager;`, `  responseMo: MetaObject;`, `  client: LlmClient;`, `  /** Prompt-TEXT resolver for render() (NOT the LLM client). */`, `  provider: Provider;`, `  model: string;`, `  system?: string;`, `  params?: Record<string, unknown>;`, `  cost?: CostFn;`, `  clock?: Clock;`, `  ids?: IdGen;`, `  traceId?: string;`, `  parentSpanId?: string;`, `  sessionId?: string;`, `  /** Optional row-redaction hook applied before persist (scrub PII/secrets). */`, `  redact?: (row: LlmCallRow) => LlmCallRow;`, `}`, ``, `/**`, ` * Render the ${entityName} prompt, call the LLM, then parse + persist a trace`, ` * row (finally-style: a call/parse failure still writes a row).`, ` */`, `export async function ${callFn}(`, `  payload: ${requestType},`, `  deps: ${entityName}CallDeps,`, `): Promise<${entityName}TraceResult> {`, `  const prompt = render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(renderFormat)}, provider: deps.provider });`, 
+                // Build request/input/deps conditionally so that an absent optional (T |
+                // undefined) is never assigned to an optional T? property — required for
+                // exactOptionalPropertyTypes-strict consumer projects.
+                `  const request: LlmRequest = { prompt, model: deps.model };`, `  if (deps.system !== undefined) request.system = deps.system;`, `  if (deps.params !== undefined) request.params = deps.params;`, `  const runInput: RunLlmCallInput = { callType: ${JSON.stringify(callTypeValue)}, request };`, `  if (deps.traceId !== undefined) runInput.traceId = deps.traceId;`, `  if (deps.parentSpanId !== undefined) runInput.parentSpanId = deps.parentSpanId;`, `  if (deps.sessionId !== undefined) runInput.sessionId = deps.sessionId;`, `  const runDeps: RunLlmCallDeps = { client: deps.client };`, `  if (deps.cost !== undefined) runDeps.cost = deps.cost;`, `  if (deps.clock !== undefined) runDeps.clock = deps.clock;`, `  if (deps.ids !== undefined) runDeps.ids = deps.ids;`, `  const { input: recInput, completion } = await runLlmCall(runInput, runDeps);`, `  let voResponse: ${responseRef} | null = null;`, `  let status = recInput.status;`, `  let errorDetail = recInput.errorDetail;`, `  if (completion !== undefined) {`, `    const outcome = extract(completion.body, extractSchemaFor(deps.responseMo, ${formatLiteral}));`, `    if (outcome.report.hasLostRequired()) {`, `      status = "error";`, '      errorDetail = `lost required: ${outcome.report.lostRequired().join(", ")}`;', `    } else {`, `      voResponse = outcome.data as ${responseRef};`, `    }`, `  }`, `  const row = { ...buildLlmCallRow({ ...recInput, status, errorDetail }), voRequest: payload, voResponse };`, `  await persistLlmCallRow(new LlmCallDbRecorder(deps.om, ${JSON.stringify(entityName)}), row, deps.redact ? { redact: deps.redact } : undefined);`, `  return { status, errorDetail, voResponse };`, `}`);
+            }
+            return [{
+                    path: `${dirPrefix}${entityName}.trace.ts`,
+                    content: lines.join("\n"),
+                }];
+        }),
+    };
+    if (opts?.target) {
+        generator.target = opts.target;
+    }
+    return generator;
+};
+//# sourceMappingURL=trace-helper-file.js.map

package/dist/generators/trace-helper-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-helper-file.js","sourceRoot":"","sources":["../../src/generators/trace-helper-file.ts"],"names":[],"mappings":"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"}