@specverse/engines 6.32.0 → 6.33.0

package/dist/realize/per-action-runner.js

@@ -0,0 +1,269 @@
+/**
+ * Per-action realize runner — Phase 3 of the L3 redesign.
+ *
+ * The orchestration glue between the spec walker (controllers + services
+ * + their actions/operations) and the per-action emitter. This is the
+ * call site that REPLACES the legacy `generateAiBehaviors` step in
+ * `realize/index.ts` when the per-action path is enabled.
+ *
+ * Responsibilities:
+ *   1. Walk the spec's controllers + services and collect every custom
+ *      action (controller actions + service operations) along with the
+ *      owning entity name + step list + spec metadata.
+ *   2. For each action, build an ActionSpec + RealizeContext and call
+ *      emitActionBody. The matcher (prisma / mongo-native / pg-native)
+ *      and conventions array are passed through as injected
+ *      dependencies — same shape the legacy ai-behaviors path uses.
+ *   3. Group results by owner and emit one `<Owner>.ai.ts` file per
+ *      owner, containing one exported async function per action with
+ *      the LLM-emitted (or stub-γ-emitted) body inline.
+ *
+ * Concurrency: the LLM call site (when a real LLM is configured) is
+ * sequential per owner — keeps surgical-retry's parse-error feedback
+ * clean and bounds the API spend in the worst case. A future Phase
+ * could parallelise across owners; not the default in V1.
+ *
+ * The legacy `<Owner>.ai.ts` emitted by `ai-behaviors-generator.ts`
+ * contains per-STEP helpers; the new file contains per-ACTION pure
+ * functions. DR2 says keep the filename, repurpose the content shape.
+ * Both shapes co-exist when this runner runs alongside the legacy
+ * generator (gated by env flag); the new file overwrites the legacy
+ * output when both are run for the same owner. The integration test
+ * pins the new shape; the env flag governs which runs in realize.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { emitActionBody, } from './per-action-emitter.js';
+/**
+ * Walk the spec, dispatch each custom action through the per-action
+ * emitter, and write per-owner `.ai.ts` files.
+ *
+ * Collection rules:
+ *   - Controllers: every entry under `controller.actions` becomes a
+ *     CollectedAction. CURVED ops (`controller.cured.{create,...}`)
+ *     are skipped — the L1 instance-factory templates handle those
+ *     deterministically.
+ *   - Services: every entry under `service.operations` becomes a
+ *     CollectedAction. Service operations don't have CURVED kinship.
+ *   - Model behaviours (`model.behaviors.<name>`) are NOT collected by
+ *     this runner — the controller / service is the realized surface;
+ *     model behaviours flow through controllers via the inference
+ *     pipeline before realize sees them. A future phase could collect
+ *     them directly if needed.
+ */
+export async function runPerActionEmission(opts) {
+    const collected = collectActions(opts.spec);
+    const ownerGroups = groupByOwner(collected);
+    const owners = [];
+    const filesWritten = [];
+    const totals = {
+        actionCount: 0,
+        ownerCount: 0,
+        stubCount: 0,
+        llmCount: 0,
+        fullyMatchedCount: 0,
+    };
+    for (const [ownerName, actions] of ownerGroups) {
+        const bodies = new Map();
+        const specs = new Map();
+        for (const collectedAction of actions) {
+            const realizeCtx = {
+                componentName: ownerName,
+                modelName: collectedAction.modelName,
+                matcher: opts.matcher,
+                conventions: opts.conventions,
+                aiArgsExpr: opts.aiArgsExpr,
+                llmEmit: opts.llmEmit,
+                canCallLLM: opts.canCallLLM,
+            };
+            const body = await emitActionBody(collectedAction.spec, realizeCtx);
+            bodies.set(collectedAction.actionName, body);
+            specs.set(collectedAction.actionName, collectedAction.spec);
+            totals.actionCount++;
+            // Heuristic counters — body shape tells us which branch fired.
+            if (body.includes('throw new Error(') && body.includes(': not implemented")')) {
+                totals.stubCount++;
+            }
+            else if (collectedAction.spec.steps.length > 0) {
+                // No way to distinguish LLM vs full-convention from here, but
+                // we can spot the "stub" branch above; everything else is a
+                // composed body.
+                totals.fullyMatchedCount++;
+            }
+        }
+        const result = { ownerName, bodies, specs };
+        owners.push(result);
+        totals.ownerCount++;
+        if (!opts.dryRun) {
+            const filePath = writeOwnerAiFile(opts.outputDir, result);
+            filesWritten.push(filePath);
+            if (!opts.silent) {
+                console.log(`   ✅ Per-action AI behaviors: ${ownerName}.ai.ts (${actions.length} action${actions.length === 1 ? '' : 's'})`);
+            }
+        }
+    }
+    return { owners, filesWritten, totals };
+}
+// ─── Spec walking ────────────────────────────────────────────────────
+/**
+ * Walk the spec and collect every custom controller action + service
+ * operation that has a non-empty `steps:` block. Without steps, the
+ * per-action emitter has no work to do — those actions stay as
+ * placeholder methods on the controller / service.
+ */
+export function collectActions(spec) {
+    const out = [];
+    // Controllers — accept either {Name: {...}} object or [{name, ...}] array.
+    // When keyed by name (the canonical spec shape), the entries don't
+    // necessarily carry a `name` field; we fall back to the map key.
+    const controllerEntries = Array.isArray(spec.controllers)
+        ? spec.controllers.map((c) => [c?.name ?? '', c])
+        : Object.entries(spec.controllers || {});
+    for (const [keyName, controller] of controllerEntries) {
+        if (!controller?.actions)
+            continue;
+        const ownerName = controller.name || keyName;
+        if (!ownerName)
+            continue;
+        const modelName = controller.model || controller.modelReference || ownerName.replace(/Controller$/, '');
+        for (const [actionName, actionRaw] of Object.entries(controller.actions)) {
+            const action = normalizeActionSpec(actionRaw, actionName);
+            if (action.steps.length === 0)
+                continue;
+            out.push({
+                ownerKind: 'controller',
+                ownerName,
+                modelName,
+                actionName,
+                spec: { ...action, ownerName, ownerKind: 'controller' },
+            });
+        }
+    }
+    // Services — accept either {Name: {...}} object or [{name, ...}] array.
+    const serviceEntries = Array.isArray(spec.services)
+        ? spec.services.map((s) => [s?.name ?? '', s])
+        : Object.entries(spec.services || {});
+    for (const [keyName, service] of serviceEntries) {
+        if (!service?.operations)
+            continue;
+        const ownerName = service.name || keyName;
+        if (!ownerName)
+            continue;
+        const modelName = ownerName.replace(/Service$/, '');
+        const operationEntries = Array.isArray(service.operations)
+            ? service.operations.map((op) => [op.name, op])
+            : Object.entries(service.operations);
+        for (const [actionName, opRaw] of operationEntries) {
+            const action = normalizeActionSpec(opRaw, actionName);
+            if (action.steps.length === 0)
+                continue;
+            out.push({
+                ownerKind: 'service',
+                ownerName,
+                modelName,
+                actionName,
+                spec: { ...action, ownerName, ownerKind: 'service' },
+            });
+        }
+    }
+    return out;
+}
+/** Coerce a raw action / operation spec object into the ActionSpec shape. */
+function normalizeActionSpec(raw, actionName) {
+    const stepsRaw = raw?.steps ?? raw?.implementation?.steps ?? [];
+    const steps = Array.isArray(stepsRaw)
+        ? stepsRaw.map((s) => (typeof s === 'string' ? s : s?.step)).filter((s) => typeof s === 'string')
+        : [];
+    return {
+        name: actionName,
+        ownerName: '', // filled in by caller
+        ownerKind: 'controller', // overwritten by caller
+        steps,
+        description: raw?.description,
+        parameters: raw?.parameters,
+        returns: typeof raw?.returns === 'string' ? raw.returns : raw?.returns ? JSON.stringify(raw.returns) : undefined,
+        requires: raw?.requires ?? raw?.preconditions,
+        ensures: raw?.ensures ?? raw?.postconditions,
+        publishes: raw?.publishes ?? raw?.events,
+    };
+}
+/** Group collected actions by owner so we emit one .ai.ts file per owner. */
+function groupByOwner(actions) {
+    const groups = new Map();
+    for (const a of actions) {
+        const list = groups.get(a.ownerName) ?? [];
+        list.push(a);
+        groups.set(a.ownerName, list);
+    }
+    return groups;
+}
+// ─── File emission ───────────────────────────────────────────────────
+/**
+ * Write a single owner's `.ai.ts` file to disk. Returns the file path.
+ *
+ * The file is structured as:
+ *   - Header docstring (DR2 framing — repurposed from per-step to per-action).
+ *   - One `export async function <actionName>(input): Promise<...>` per
+ *     action, with the body produced by emitActionBody.
+ *
+ * Signatures are intentionally loose (`input: any`) for V1; Phase 4 /
+ * 5 will tighten them using the spec's `parameters:` types. The per-step
+ * `.ai.ts` files used the same loose signature, so we don't regress.
+ */
+function writeOwnerAiFile(outputDir, owner) {
+    const filePath = join(outputDir, 'backend', 'src', 'behaviors', `${owner.ownerName}.ai.ts`);
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, renderOwnerAiFile(owner), 'utf-8');
+    return filePath;
+}
+/**
+ * Render the `.ai.ts` content for one owner. Exported so tests can
+ * assert on the produced shape without going to disk.
+ */
+export function renderOwnerAiFile(owner) {
+    const blocks = [];
+    blocks.push(`/**
+ * ${owner.ownerName} — Per-action AI behaviors (Realize L3 per-action emission).
+ *
+ * One exported async function per spec action / operation. Each body
+ * was emitted by the per-action realize pipeline:
+ *
+ *   - L2 convention matcher pre-baked deterministic snippets for known
+ *     step patterns. Those snippets are present verbatim in the body.
+ *   - The LLM (when available) wove the [WRITE]-step code around the
+ *     pre-baked snippets to produce one coherent method body per action.
+ *   - When neither convention nor LLM produced a coherent body, the
+ *     function throws a "not implemented" stub at runtime and preserves
+ *     the convention-matched scaffolding as a code-block comment for
+ *     reviewer context (DR4-γ shape).
+ *
+ * REVIEW SURFACE — anything in this file that ISN'T deterministic
+ * convention output came from an LLM. Inspect carefully before
+ * deploying production logic.
+ *
+ * Generated: ${new Date().toISOString().split('T')[0]}
+ */
+`);
+    for (const [actionName, spec] of owner.specs) {
+        const body = owner.bodies.get(actionName) ?? `    throw new Error('${actionName}: missing body');`;
+        blocks.push(renderActionFunction(actionName, spec, body));
+    }
+    return blocks.join('\n');
+}
+/** Render a single per-action `export async function ...` block. */
+function renderActionFunction(actionName, spec, body) {
+    const description = spec.description ? ` * ${spec.description}\n *` : '';
+    const stepsDoc = spec.steps.length > 0
+        ? ` *\n * Spec steps:\n${spec.steps.map((s) => ` *   - ${s}`).join('\n')}\n`
+        : '';
+    return `/**
+ * ${actionName}
+${description}${stepsDoc} */
+export async function ${actionName}(input: any): Promise<any> {
+${body}
+}
+`;
+}
+//# sourceMappingURL=per-action-runner.js.map

package/dist/realize/per-action-runner.js.map

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

package/dist/realize/structural-validator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Structural validator for per-action LLM output (DR3 of the L3 proposal).
+ *
+ * The L2 convention matcher produces deterministic TypeScript snippets
+ * for spec steps it can match. Those pre-baked snippets are passed to the
+ * LLM as scaffolding (DR3-A). The LLM emits a coherent method body that
+ * weaves the pre-baked snippets together with [WRITE]-step code it
+ * authors itself.
+ *
+ * The structural validator is the trust-but-verify counterpart to that
+ * pattern: after the LLM emits, we diff the output against the pre-baked
+ * snippets. Every pre-baked snippet must appear in the LLM's body
+ * verbatim (modulo whitespace + trailing punctuation). If a snippet is
+ * missing — i.e. the LLM rewrote a deterministic piece — the realize
+ * pipeline fails loudly with a diff showing what was preserved + what
+ * was dropped.
+ *
+ * Why "verbatim modulo whitespace": pre-baked snippets are already
+ * idiomatic TS. Letting the LLM reformat them silently undermines
+ * "deterministic" — we'd lose reproducibility across runs. But forcing
+ * exact byte-for-byte match would fail on innocuous LLM behaviours
+ * (re-indenting a single line of pre-baked code to match the surrounding
+ * indentation it adopted). We compare on the canonical form: the
+ * snippet's "code essence" stripped of leading whitespace and trailing
+ * comment-only lines.
+ *
+ * This validator is orthogonal to the parse-check (esbuild) and the
+ * tsc-check (per-action-llm-emit's surgical retry loop). All three
+ * gates compose: parse-fail → surgical retry; structural-fail → loud
+ * fail (LLM rewrote a deterministic piece); tsc-fail → fall through to
+ * γ stub.
+ */
+/** A single pre-baked snippet to verify is preserved in the LLM output. */
+export interface PrebakedSnippet {
+    /** Step number (1-indexed) the snippet came from — for error messages. */
+    stepNum: number;
+    /** Human-readable step text — for error messages. */
+    stepText: string;
+    /** The pre-baked TypeScript snippet. The matcher's `.call` string. */
+    snippet: string;
+}
+/** Outcome of the structural-preservation check. */
+export type StructuralValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    missing: MissingSnippet[];
+    reason: string;
+};
+/** Per-snippet failure detail. */
+export interface MissingSnippet {
+    stepNum: number;
+    stepText: string;
+    /** The original pre-baked snippet (canonicalised). */
+    expected: string;
+    /** The closest match found in the LLM body, or null when no near-match. */
+    closestMatch: string | null;
+}
+/**
+ * Validate that every pre-baked snippet appears in the LLM-emitted body.
+ *
+ * The check is substring containment on the canonical form (whitespace +
+ * leading-comment normalised). For each missing snippet we surface the
+ * step number, step text, and the closest near-match found in the body
+ * (or `null` if there's no token-overlap candidate).
+ *
+ * Empty `prebakedSnippets` is a vacuous pass — when no convention
+ * matched, there's nothing to preserve.
+ */
+export declare function validateLlmOutputPreservesConventions(llmBody: string, prebakedSnippets: PrebakedSnippet[]): StructuralValidationResult;
+//# sourceMappingURL=structural-validator.d.ts.map

package/dist/realize/structural-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-validator.d.ts","sourceRoot":"","sources":["../../src/realize/structural-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,eAAe,EAAE,GAClC,0BAA0B,CAiD5B"}

package/dist/realize/structural-validator.js

@@ -0,0 +1,167 @@
+/**
+ * Structural validator for per-action LLM output (DR3 of the L3 proposal).
+ *
+ * The L2 convention matcher produces deterministic TypeScript snippets
+ * for spec steps it can match. Those pre-baked snippets are passed to the
+ * LLM as scaffolding (DR3-A). The LLM emits a coherent method body that
+ * weaves the pre-baked snippets together with [WRITE]-step code it
+ * authors itself.
+ *
+ * The structural validator is the trust-but-verify counterpart to that
+ * pattern: after the LLM emits, we diff the output against the pre-baked
+ * snippets. Every pre-baked snippet must appear in the LLM's body
+ * verbatim (modulo whitespace + trailing punctuation). If a snippet is
+ * missing — i.e. the LLM rewrote a deterministic piece — the realize
+ * pipeline fails loudly with a diff showing what was preserved + what
+ * was dropped.
+ *
+ * Why "verbatim modulo whitespace": pre-baked snippets are already
+ * idiomatic TS. Letting the LLM reformat them silently undermines
+ * "deterministic" — we'd lose reproducibility across runs. But forcing
+ * exact byte-for-byte match would fail on innocuous LLM behaviours
+ * (re-indenting a single line of pre-baked code to match the surrounding
+ * indentation it adopted). We compare on the canonical form: the
+ * snippet's "code essence" stripped of leading whitespace and trailing
+ * comment-only lines.
+ *
+ * This validator is orthogonal to the parse-check (esbuild) and the
+ * tsc-check (per-action-llm-emit's surgical retry loop). All three
+ * gates compose: parse-fail → surgical retry; structural-fail → loud
+ * fail (LLM rewrote a deterministic piece); tsc-fail → fall through to
+ * γ stub.
+ */
+/**
+ * Canonicalise a code chunk for comparison: strip leading whitespace per
+ * line, drop pure-comment lines (the matcher prepends `// Step N: ...`
+ * markers that the LLM is allowed to reword or absorb into prose), and
+ * collapse internal whitespace runs to a single space.
+ *
+ * The result is a fingerprint of the snippet's executable shape — enough
+ * to spot rewrites (different identifier, different control flow) but
+ * loose enough to tolerate harmless reformatting (alignment, spacing
+ * around operators).
+ */
+function canonicalise(code) {
+    return code
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('//'))
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Validate that every pre-baked snippet appears in the LLM-emitted body.
+ *
+ * The check is substring containment on the canonical form (whitespace +
+ * leading-comment normalised). For each missing snippet we surface the
+ * step number, step text, and the closest near-match found in the body
+ * (or `null` if there's no token-overlap candidate).
+ *
+ * Empty `prebakedSnippets` is a vacuous pass — when no convention
+ * matched, there's nothing to preserve.
+ */
+export function validateLlmOutputPreservesConventions(llmBody, prebakedSnippets) {
+    if (prebakedSnippets.length === 0) {
+        return { ok: true };
+    }
+    const llmCanonical = canonicalise(llmBody);
+    const missing = [];
+    for (const snippet of prebakedSnippets) {
+        const expected = canonicalise(snippet.snippet);
+        if (expected.length === 0)
+            continue; // skip comment-only snippets
+        if (llmCanonical.includes(expected)) {
+            continue;
+        }
+        // Near-match heuristic: extract a list of progressively-shorter
+        // dotted tokens from the snippet (e.g. `prisma.customer.findUnique`,
+        // `prisma.customer`, `prisma`) and search the LLM body for any of
+        // them. Surfaces the closest line to the reviewer — so when the LLM
+        // rewrote `findUnique` to `findFirst` (kept the `prisma.customer`
+        // prefix), we find the rewritten line rather than reporting "no
+        // near-match found".
+        const distinctiveTokens = extractDistinctiveTokens(snippet.snippet);
+        let closestMatch = null;
+        for (const tok of distinctiveTokens) {
+            for (const line of llmBody.split('\n')) {
+                if (line.includes(tok)) {
+                    closestMatch = line.trim();
+                    break;
+                }
+            }
+            if (closestMatch)
+                break;
+        }
+        missing.push({
+            stepNum: snippet.stepNum,
+            stepText: snippet.stepText,
+            expected: snippet.snippet.trim(),
+            closestMatch,
+        });
+    }
+    if (missing.length === 0) {
+        return { ok: true };
+    }
+    const reason = formatMissingReport(missing);
+    return { ok: false, missing, reason };
+}
+/**
+ * Extract a list of progressively-shorter distinctive identifier
+ * tokens from a snippet, ordered most-specific first. Used by the
+ * closest-match heuristic to surface a rewritten line even when the
+ * LLM changed the trailing call shape (e.g. `findUnique → findFirst`)
+ * but kept the prefix.
+ *
+ * Returns the empty array when the snippet has no dotted identifiers.
+ */
+function extractDistinctiveTokens(snippet) {
+    // Collect every dotted identifier (foo.bar, prisma.order.create, etc.)
+    const rawMatches = snippet.match(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+/g);
+    const matches = rawMatches ? Array.from(rawMatches) : [];
+    if (matches.length === 0)
+        return [];
+    const out = [];
+    // Start with the longest dotted identifier, then walk back along
+    // its prefix segments (one fewer dot each step) so we have a series
+    // of fall-back queries to match against the LLM body.
+    matches.sort((a, b) => b.length - a.length);
+    const longest = matches[0];
+    out.push(longest);
+    const segments = longest.split('.');
+    for (let i = segments.length - 1; i >= 2; i--) {
+        out.push(segments.slice(0, i).join('.'));
+    }
+    // Add any other dotted identifiers from the snippet, in case the
+    // longest one was a transient (e.g. variable assignment) and the
+    // distinguishing call sits later.
+    for (const m of matches.slice(1)) {
+        if (!out.includes(m))
+            out.push(m);
+    }
+    return out;
+}
+/**
+ * Format a human-readable diff report for the realize pipeline to print
+ * when the structural validator rejects an LLM output.
+ */
+function formatMissingReport(missing) {
+    const lines = [];
+    lines.push(`LLM output dropped or rewrote ${missing.length} pre-baked convention snippet${missing.length === 1 ? '' : 's'}:`);
+    for (const m of missing) {
+        lines.push('');
+        lines.push(`  Step ${m.stepNum}: ${m.stepText}`);
+        lines.push(`    Expected (verbatim): ${m.expected.replace(/\n/g, '\n      ')}`);
+        if (m.closestMatch) {
+            lines.push(`    Closest in LLM body: ${m.closestMatch}`);
+        }
+        else {
+            lines.push(`    Closest in LLM body: (no near-match found)`);
+        }
+    }
+    lines.push('');
+    lines.push('The convention matcher is deterministic; pre-baked snippets must be preserved verbatim. ' +
+        'If you believe the matcher is wrong for this case, fix the convention pattern in step-conventions.ts.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=structural-validator.js.map

package/dist/realize/structural-validator.js.map

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