ai-database 2.1.3 → 2.3.0

package/dist/cascade-orchestrator.js

@@ -0,0 +1,828 @@
+/**
+ * Cascade Orchestrator — the moat work
+ *
+ * This module is the canonical, real cascade-generation engine for
+ * `ai-database`. It replaces the placeholder generator (`schema/cascade.ts`'s
+ * `PlaceholderValueGenerator`) for the SVO-shaped cascade surface and absorbs
+ * the algorithmic patterns proven by the
+ * `2026-05-06-cascade-via-ai-database-poc` (sibling-parallel `[->Type]`
+ * expansion, pre-derived child ids for backref correctness, rubric-style
+ * `$validate` with four verdict policies, embed-on-write) — but rebuilt on
+ * the canonical SVO foundation:
+ *
+ * - LLM calls go through `generate()` from `ai-functions` (auto-routed via
+ *   `ai-providers`), wrapped with the per-model `ModelPolicy` from
+ *   `language-models` (`RetryPolicy.forModel` + `FallbackChain.forModel`)
+ *   so retry/circuit-breaker/fallback behaviour is consistent with the rest
+ *   of the platform.
+ * - Generated entities are recorded as **Things** via the canonical
+ *   `DBProvider` surface; relations are recorded as **Actions** with proper
+ *   Frame role assignments (`subject`, `object`, plus optional Frame-role
+ *   slots) per the `digital-objects` SVO ontology.
+ * - Verbs auto-register via `provider.defineVerb(...)` on first use when
+ *   the adapter exposes the Verb registry surface.
+ * - Sharded writes flow through {@link CascadeWriteStrategy} so per-cascade
+ *   DO isolation (Stack B) and partitioned-by-tenant Postgres (Stack A) get
+ *   the right shape without leaking the choice into orchestrator code.
+ * - Read-back-during-traversal goes through {@link CascadeWriteStrategy.readShardLocal}
+ *   so cascade reads land on the same shard that received the write.
+ *
+ * ## What's deliberately NOT in this module
+ *
+ * - **Pipelines → Iceberg dual-write.** That's bead `aip-0ypt`; the
+ *   orchestrator surfaces an `analyticalEmitter` on the underlying
+ *   {@link CascadeWriteStrategy} which `aip-0ypt` will wire later.
+ * - **CLI / Worker entrypoint.** The library function {@link generateCascade}
+ *   is the surface; deployment shapes live downstream.
+ * - **Observability beyond debug logging.** Telemetry / tracing is its own
+ *   bead.
+ * - **The schema-DSL cascade engine** (`schema/cascade.ts`). That module
+ *   drives generation from the parsed `[->Type]` / `<-Type` schema syntax;
+ *   this orchestrator drives generation from a {@link CascadeSpec} at the
+ *   SVO level. Both can coexist; this is the canonical moat path.
+ *
+ * @see {@link ../docs/adr/0003-storage-strategy-pg-clickhouse-default.md}
+ * @see {@link ../docs/reviews/2026-05-05-cascade-poc-evaluation.md}
+ * @see {@link ../docs/plans/2026-05-05-cascade-storage-execution-implementation.md}
+ * @packageDocumentation
+ */
+import { hasActionRecording, hasVerbRegistry } from './db-provider-port.js';
+import { CascadeWriteStrategy, createCascadeWriteStrategy, } from './cascade-write-strategy.js';
+/**
+ * Thrown when a rubric verdict is `'escalate'` — the caller must catch
+ * this and decide whether to fail the cascade or recover.
+ */
+export class CascadeValidationEscalation extends Error {
+    noun;
+    data;
+    scores;
+    path;
+    constructor(input) {
+        super(`Cascade validation escalated for ${input.noun} at ${input.path.join('/')}: ${input.feedback ?? 'rubric verdict was "escalate"'}`);
+        this.name = 'CascadeValidationEscalation';
+        this.noun = input.noun;
+        this.data = input.data;
+        this.scores = input.scores;
+        this.path = input.path;
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Run a cascade generation against an adapter.
+ *
+ * @example
+ * ```ts
+ * import { generateCascade, createMemoryProvider } from 'ai-database'
+ *
+ * const result = await generateCascade({
+ *   adapter: createMemoryProvider(),
+ *   rootNoun: 'Customer',
+ *   rootHints: { industry: 'B2B SaaS', size: 'enterprise' },
+ *   children: [
+ *     {
+ *       noun: 'Order',
+ *       count: 5,
+ *       verb: 'placedBy',
+ *       hints: { stage: 'closed-won' },
+ *       children: [
+ *         { noun: 'OrderItem', count: [2, 5], verb: 'partOf' },
+ *       ],
+ *     },
+ *   ],
+ *   model: 'sonnet',
+ * })
+ *
+ * console.log(result.root.$id)        // root Customer id
+ * console.log(result.stats.written)   // 1 + 5 + (2..5)*5
+ * ```
+ */
+export async function generateCascade(options) {
+    const startedAt = Date.now();
+    const model = options.model ?? 'sonnet';
+    const validationModel = options.validationModel ?? model;
+    const maxDepth = options.maxDepth ?? 5;
+    const maxRegenerationAttempts = options.maxRegenerationAttempts ?? 2;
+    const debug = options.debug ?? (() => { });
+    // Stable cascade id — caller-supplied wins; otherwise content-hash the spec.
+    const cascadeId = options.cascadeId ??
+        contentHashId('cascade', {
+            rootNoun: options.rootNoun,
+            rootHints: options.rootHints ?? {},
+            children: options.children ?? [],
+        });
+    // Build the write strategy (caller-supplied wins).
+    const strategy = options.strategy ??
+        createCascadeWriteStrategy({
+            adapter: options.adapter,
+            ...(options.sharding !== undefined && { sharding: options.sharding }),
+            defaultCascadeId: cascadeId,
+            ...(options.tenantId !== undefined && { defaultTenantId: options.tenantId }),
+            ...(options.analyticalEmitter !== undefined && {
+                analyticalEmitter: options.analyticalEmitter,
+            }),
+        });
+    const shard = strategy.pickShard({
+        cascadeId,
+        ...(options.tenantId !== undefined && { tenantId: options.tenantId }),
+        rootEntity: { $id: '__pending__', $type: options.rootNoun },
+    });
+    // LLM hooks — defaults call ai-functions; tests pass mocks.
+    const generator = options.generator ?? defaultGenerator;
+    const validator = options.validator ?? defaultValidator;
+    // State accumulators.
+    const thingsById = new Map();
+    const actions = [];
+    const rejected = [];
+    let regenerationAttempts = 0;
+    let embedded = 0;
+    // Verb registry — auto-define on first use.
+    const definedVerbs = new Set();
+    const ensureVerb = async (verb) => {
+        if (definedVerbs.has(verb))
+            return;
+        definedVerbs.add(verb);
+        if (hasVerbRegistry(options.adapter)) {
+            try {
+                await options.adapter.defineVerb({ name: verb });
+            }
+            catch {
+                // Verb may already exist; ignore.
+            }
+        }
+    };
+    // ---------------------------------------------------------------------------
+    // Generate root.
+    // ---------------------------------------------------------------------------
+    debug('cascade:start', { cascadeId, rootNoun: options.rootNoun });
+    const rootGen = await generateAndValidate({
+        noun: options.rootNoun,
+        hints: options.rootHints ?? {},
+        rootNoun: options.rootNoun,
+        cascadeId,
+        path: [options.rootNoun],
+        parentKey: cascadeId,
+        rubric: options.validate,
+        generator,
+        validator,
+        model,
+        validationModel,
+        maxRegenerationAttempts,
+        debug,
+        onRegenerate: () => {
+            regenerationAttempts += 1;
+        },
+    });
+    if (rootGen.outcome === 'rejected') {
+        rejected.push({
+            noun: options.rootNoun,
+            data: rootGen.data,
+            scores: rootGen.scores,
+            ...(rootGen.feedback !== undefined && { feedback: rootGen.feedback }),
+            path: [options.rootNoun],
+        });
+        return finishResult({
+            cascadeId,
+            root: undefined,
+            thingsById,
+            actions,
+            rejected,
+            regenerationAttempts,
+            embedded,
+            startedAt,
+        });
+    }
+    // Embed before write so reads-back-during-traversal see the embedding.
+    if (options.embedder) {
+        const text = buildEmbedText(rootGen.data);
+        if (text) {
+            try {
+                const vec = await options.embedder(text);
+                rootGen.data['$embedding'] = vec;
+                embedded += 1;
+            }
+            catch (err) {
+                debug('cascade:embed:fail', { noun: options.rootNoun, error: errorMessage(err) });
+            }
+        }
+    }
+    const rootId = deriveEntityId(options.rootNoun, rootGen.data, cascadeId, [options.rootNoun]);
+    const rootEntity = {
+        $id: rootId,
+        $type: options.rootNoun,
+        data: rootGen.data,
+        path: [options.rootNoun],
+        ...(rootGen.scores && Object.keys(rootGen.scores).length > 0
+            ? { validationScores: rootGen.scores }
+            : {}),
+    };
+    thingsById.set(rootId, rootEntity);
+    // Write the root via the strategy fast path.
+    await strategy.writeBatch(shard, {
+        things: [{ id: rootId, type: options.rootNoun, data: rootGen.data }],
+    });
+    debug('cascade:root:written', { id: rootId, noun: options.rootNoun });
+    // ---------------------------------------------------------------------------
+    // Descend into children — sibling-parallel within each spec.
+    // ---------------------------------------------------------------------------
+    if (options.children && options.children.length > 0 && maxDepth > 1) {
+        await descendChildren({
+            parent: rootEntity,
+            childSpecs: options.children,
+            depth: 1,
+            maxDepth,
+            cascadeId,
+            strategy,
+            shard,
+            generator,
+            validator,
+            model,
+            validationModel,
+            maxRegenerationAttempts,
+            embedder: options.embedder,
+            debug,
+            thingsById,
+            actions,
+            rejected,
+            ensureVerb,
+            initiator: options.initiator,
+            onRegenerate: () => {
+                regenerationAttempts += 1;
+            },
+            onEmbed: () => {
+                embedded += 1;
+            },
+        });
+    }
+    return finishResult({
+        cascadeId,
+        root: rootEntity,
+        thingsById,
+        actions,
+        rejected,
+        regenerationAttempts,
+        embedded,
+        startedAt,
+    });
+}
+async function descendChildren(args) {
+    if (args.depth >= args.maxDepth) {
+        args.debug('cascade:max-depth-reached', { depth: args.depth, parent: args.parent.$id });
+        return;
+    }
+    // Pre-derive child ids per spec so grandchildren backrefs land cleanly,
+    // and so the rubric-rejected children don't leak ids into the cascade.
+    for (const spec of args.childSpecs) {
+        await args.ensureVerb(spec.verb);
+        const count = resolveCount(spec.count);
+        if (count <= 0)
+            continue;
+        args.debug('cascade:children:start', {
+            parent: args.parent.$id,
+            noun: spec.noun,
+            count,
+            verb: spec.verb,
+        });
+        // Sibling-parallel fan-out — every sibling generated concurrently.
+        const siblingPromises = Array.from({ length: count }, (_, siblingIndex) => generateOneSibling({
+            spec,
+            siblingIndex,
+            siblingCount: count,
+            parent: args.parent,
+            cascadeId: args.cascadeId,
+            generator: args.generator,
+            validator: args.validator,
+            model: args.model,
+            validationModel: args.validationModel,
+            maxRegenerationAttempts: args.maxRegenerationAttempts,
+            embedder: args.embedder,
+            rootData: args.thingsById.get(args.parent.path[0] ?? args.parent.$id)?.data,
+            rootNoun: args.parent.path[0] ?? args.parent.$type,
+            debug: args.debug,
+            onRegenerate: args.onRegenerate,
+            onEmbed: args.onEmbed,
+        }));
+        const siblingResults = await Promise.all(siblingPromises);
+        // Collect accepted siblings; queue Things + Actions for the batch commit.
+        const things = [];
+        const cascadeActions = [];
+        const acceptedSiblings = [];
+        for (const result of siblingResults) {
+            if (result.outcome === 'rejected') {
+                args.rejected.push({
+                    noun: spec.noun,
+                    data: result.data,
+                    scores: result.scores,
+                    ...(result.feedback !== undefined && { feedback: result.feedback }),
+                    path: result.path,
+                    parentId: args.parent.$id,
+                });
+                continue;
+            }
+            const childEntity = {
+                $id: result.id,
+                $type: spec.noun,
+                data: result.data,
+                path: result.path,
+                parentId: args.parent.$id,
+                ...(result.scores && Object.keys(result.scores).length > 0
+                    ? { validationScores: result.scores }
+                    : {}),
+            };
+            args.thingsById.set(result.id, childEntity);
+            acceptedSiblings.push(childEntity);
+            things.push({ id: result.id, type: spec.noun, data: result.data });
+            // Build the Action with proper Frame role assignment. Subject is the
+            // child (it acts via the verb); object is the parent. Tokens
+            // `'$parent'`/`'$root'` in `spec.roles` get resolved.
+            const resolvedRoles = resolveRoleTokens(spec.roles, args.parent, args.thingsById);
+            cascadeActions.push({
+                verb: spec.verb,
+                subject: result.id,
+                object: args.parent.$id,
+                ...(args.initiator !== undefined && {
+                    roles: { ...resolvedRoles, source: args.initiator },
+                }),
+                ...(args.initiator === undefined && Object.keys(resolvedRoles).length > 0
+                    ? { roles: resolvedRoles }
+                    : {}),
+                status: 'completed',
+            });
+            args.actions.push({
+                verb: spec.verb,
+                subject: result.id,
+                object: args.parent.$id,
+                ...(Object.keys(resolvedRoles).length > 0 ? { roles: resolvedRoles } : {}),
+            });
+        }
+        // Single batch commit per child spec — Things + Actions in one round-trip
+        // through the strategy's fast path (CTE jsonb-bulk for PG).
+        if (things.length > 0 || cascadeActions.length > 0) {
+            await args.strategy.writeBatch(args.shard, { things, actions: cascadeActions });
+        }
+        args.debug('cascade:children:written', {
+            parent: args.parent.$id,
+            noun: spec.noun,
+            accepted: acceptedSiblings.length,
+            rejected: count - acceptedSiblings.length,
+        });
+        // Recurse into grandchildren — sequentially per accepted sibling so that
+        // the cascade tree builds depth-first within each branch. Sibling-level
+        // parallelism is preserved at the same level (we just generated all
+        // siblings concurrently).
+        if (spec.children && spec.children.length > 0 && args.depth + 1 < args.maxDepth) {
+            for (const sibling of acceptedSiblings) {
+                await descendChildren({
+                    ...args,
+                    parent: sibling,
+                    childSpecs: spec.children,
+                    depth: args.depth + 1,
+                });
+            }
+        }
+    }
+}
+async function generateAndValidate(args) {
+    let attempt = 0;
+    let feedback;
+    while (true) {
+        const data = await args.generator({
+            noun: args.noun,
+            hints: args.hints,
+            ...(args.parentNoun !== undefined && { parentNoun: args.parentNoun }),
+            ...(args.parentData !== undefined && { parentData: args.parentData }),
+            rootNoun: args.rootNoun,
+            ...(args.rootData !== undefined && { rootData: args.rootData }),
+            cascadeId: args.cascadeId,
+            path: args.path,
+            ...(args.siblingIndex !== undefined && { siblingIndex: args.siblingIndex }),
+            ...(args.siblingCount !== undefined && { siblingCount: args.siblingCount }),
+            ...(feedback !== undefined && { feedback }),
+            model: args.model,
+        });
+        // No rubric → accept verbatim.
+        if (!args.rubric) {
+            return { outcome: 'accepted', data, scores: {} };
+        }
+        const verdict = await args.validator({
+            noun: args.noun,
+            data,
+            rubric: args.rubric,
+            model: args.validationModel,
+            ...(args.parentData !== undefined && { parentData: args.parentData }),
+        });
+        const passed = applyRubricPolicy(args.rubric, verdict.scores);
+        args.debug('cascade:validate', {
+            noun: args.noun,
+            path: args.path,
+            passed,
+            attempt,
+            scores: verdict.scores,
+        });
+        if (passed) {
+            return {
+                outcome: 'accepted',
+                data,
+                scores: verdict.scores,
+                ...(verdict.feedback !== undefined && { feedback: verdict.feedback }),
+            };
+        }
+        // Failed verdict — apply onFail policy.
+        const onFail = args.rubric.onFail ?? 'reject';
+        if (onFail === 'escalate') {
+            throw new CascadeValidationEscalation({
+                noun: args.noun,
+                data,
+                scores: verdict.scores,
+                path: args.path,
+                ...(verdict.feedback !== undefined && { feedback: verdict.feedback }),
+            });
+        }
+        if (onFail === 'regenerate' && attempt < args.maxRegenerationAttempts) {
+            attempt += 1;
+            args.onRegenerate();
+            feedback =
+                verdict.feedback ??
+                    `Previous attempt failed validation: ${JSON.stringify(verdict.scores)}. Improve.`;
+            continue;
+        }
+        // reject (or regenerate exhausted) → return rejected.
+        return {
+            outcome: 'rejected',
+            data,
+            scores: verdict.scores,
+            ...(verdict.feedback !== undefined && { feedback: verdict.feedback }),
+        };
+    }
+}
+async function generateOneSibling(args) {
+    const path = [...args.parent.path, `${args.spec.noun}:${args.siblingIndex}`];
+    const result = await generateAndValidate({
+        noun: args.spec.noun,
+        hints: args.spec.hints ?? {},
+        rootNoun: args.rootNoun,
+        cascadeId: args.cascadeId,
+        path,
+        parentKey: args.parent.$id,
+        parentNoun: args.parent.$type,
+        parentData: args.parent.data,
+        ...(args.rootData !== undefined && { rootData: args.rootData }),
+        siblingIndex: args.siblingIndex,
+        siblingCount: args.siblingCount,
+        ...(args.spec.validate !== undefined && { rubric: args.spec.validate }),
+        rubric: args.spec.validate,
+        generator: args.generator,
+        validator: args.validator,
+        model: args.model,
+        validationModel: args.validationModel,
+        maxRegenerationAttempts: args.maxRegenerationAttempts,
+        debug: args.debug,
+        onRegenerate: args.onRegenerate,
+    });
+    if (result.outcome === 'rejected') {
+        return {
+            outcome: 'rejected',
+            id: '',
+            data: result.data,
+            scores: result.scores,
+            ...(result.feedback !== undefined && { feedback: result.feedback }),
+            path,
+        };
+    }
+    // Embed BEFORE write so the embedding lands in the same write as the data.
+    if (args.embedder) {
+        const text = buildEmbedText(result.data);
+        if (text) {
+            try {
+                const vec = await args.embedder(text);
+                result.data['$embedding'] = vec;
+                args.onEmbed();
+            }
+            catch (err) {
+                args.debug('cascade:embed:fail', { noun: args.spec.noun, error: errorMessage(err) });
+            }
+        }
+    }
+    const id = deriveEntityId(args.spec.noun, result.data, args.parent.$id, path);
+    return {
+        outcome: 'accepted',
+        id,
+        data: result.data,
+        scores: result.scores,
+        ...(result.feedback !== undefined && { feedback: result.feedback }),
+        path,
+    };
+}
+// =============================================================================
+// Internal — id derivation, content hashing, role token resolution
+// =============================================================================
+/**
+ * Derive a stable entity id from (parentKey + noun + path + sortable data).
+ *
+ * This is the lineage-key discipline from `cf-substrate/tierA-cascade`:
+ * every child's id includes the parent's full idempotency key, so sibling
+ * children at the same position across two cascade runs cannot collide.
+ *
+ * Same inputs → same id → idempotency on the write path
+ * (`ON CONFLICT DO NOTHING`).
+ */
+function deriveEntityId(noun, data, parentKey, path) {
+    return `${noun.toLowerCase()}-${contentHashId(noun, {
+        parentKey,
+        path: [...path],
+        data: stableData(data),
+    })}`;
+}
+/**
+ * Content-hash an object to a short stable string. FNV-1a 32-bit, hex, 8 chars.
+ */
+function contentHashId(prefix, value) {
+    const json = stableStringify(value);
+    let h = 0x811c9dc5;
+    for (let i = 0; i < json.length; i++) {
+        h ^= json.charCodeAt(i);
+        h = (h * 0x01000193) >>> 0;
+    }
+    // 32 bits of stable hash → 8 hex chars. Combine with a second pass for
+    // a 16-char id (still short, much lower collision risk than 8).
+    const second = (h ^ 0xdeadbeef) >>> 0;
+    let h2 = 0x811c9dc5;
+    for (let i = 0; i < json.length; i++) {
+        h2 ^= json.charCodeAt((i * 7) % json.length) ^ ((second >>> i % 32) & 0xff);
+        h2 = (h2 * 0x01000193) >>> 0;
+    }
+    const a = h.toString(16).padStart(8, '0');
+    const b = h2.toString(16).padStart(8, '0');
+    return `${prefix.toLowerCase().replace(/[^a-z0-9]/g, '')}-${a}${b}`;
+}
+/**
+ * Stable JSON stringify — keys sorted recursively. Required because object
+ * key order isn't guaranteed across runs / engines, which would yield
+ * different content hashes for "the same" data.
+ */
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val === null || typeof val !== 'object' || Array.isArray(val))
+            return val;
+        const sortedKeys = Object.keys(val).sort();
+        const result = {};
+        for (const k of sortedKeys) {
+            result[k] = val[k];
+        }
+        return result;
+    });
+}
+/**
+ * Strip transient fields (timestamps, embeddings, internal `$_` fields)
+ * before hashing — id stability shouldn't depend on volatile data.
+ */
+function stableData(data) {
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (k === 'createdAt' || k === 'updatedAt' || k === '$embedding')
+            continue;
+        if (k.startsWith('_'))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * Resolve `'$parent'`/`'$root'` tokens in role assignments.
+ */
+function resolveRoleTokens(roles, parent, thingsById) {
+    if (!roles)
+        return {};
+    const out = {};
+    for (const [role, value] of Object.entries(roles)) {
+        if (typeof value !== 'string')
+            continue;
+        if (value === '$parent') {
+            out[role] = parent.$id;
+        }
+        else if (value === '$root') {
+            // Find the root by walking parent.path (root is path[0]); thingsById's
+            // first entry is the root in our orchestrator order.
+            const rootEntry = thingsById.values().next().value;
+            if (rootEntry)
+                out[role] = rootEntry.$id;
+        }
+        else {
+            out[role] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a `count` spec to an integer: literal, or randomized between
+ * `[min, max]` (deterministic via the cascade content hash, but for now
+ * we use Math.random — the LLM honours hints and the count is a soft
+ * target).
+ */
+function resolveCount(spec) {
+    if (typeof spec === 'number')
+        return Math.max(0, Math.floor(spec));
+    const [min, max] = spec;
+    if (min < 0 || max < min)
+        return 0;
+    if (min === max)
+        return min;
+    return Math.floor(min + Math.random() * (max - min + 1));
+}
+// =============================================================================
+// Internal — rubric policy evaluation
+// =============================================================================
+function applyRubricPolicy(rubric, scores) {
+    const threshold = rubric.threshold ?? 0.7;
+    switch (rubric.policy) {
+        case 'all-pass': {
+            for (const c of rubric.criteria) {
+                const s = scores[c.name];
+                if (s === undefined || s < (rubric.threshold ?? 1))
+                    return false;
+            }
+            return true;
+        }
+        case 'all-load-bearing-pass': {
+            for (const c of rubric.criteria) {
+                if (!c.loadBearing)
+                    continue;
+                const s = scores[c.name];
+                if (s === undefined || s < (rubric.threshold ?? 1))
+                    return false;
+            }
+            return true;
+        }
+        case 'mean-ge-threshold': {
+            const values = [];
+            for (const c of rubric.criteria) {
+                const s = scores[c.name];
+                if (s === undefined)
+                    return false;
+                values.push(s);
+            }
+            if (values.length === 0)
+                return false;
+            const mean = values.reduce((a, b) => a + b, 0) / values.length;
+            return mean >= threshold;
+        }
+        case 'weighted-ge-threshold': {
+            let weightedSum = 0;
+            let weightTotal = 0;
+            for (const c of rubric.criteria) {
+                const s = scores[c.name];
+                if (s === undefined)
+                    return false;
+                const w = c.weight ?? 1;
+                weightedSum += s * w;
+                weightTotal += w;
+            }
+            if (weightTotal === 0)
+                return false;
+            return weightedSum / weightTotal >= threshold;
+        }
+    }
+}
+// =============================================================================
+// Internal — embed-text builder
+// =============================================================================
+/**
+ * Build the embedding text from a Thing's data, preferring human-readable
+ * fields per the POC's `embedTextFor`. Falls back to JSON if no preferred
+ * fields exist.
+ */
+export function buildEmbedText(data) {
+    const preferred = ['name', 'label', 'title', 'description', 'tagline', 'summary', 'rationale'];
+    const parts = [];
+    for (const key of preferred) {
+        const v = data[key];
+        if (typeof v === 'string' && v.trim().length > 0) {
+            parts.push(v.trim());
+        }
+    }
+    if (parts.length > 0)
+        return parts.join(' — ');
+    // Fallback: JSON-stringify scalar fields.
+    const scalars = [];
+    for (const [k, v] of Object.entries(data)) {
+        if (k.startsWith('$') || k.startsWith('_'))
+            continue;
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+            scalars.push(`${k}: ${String(v)}`);
+        }
+    }
+    return scalars.join(' | ');
+}
+// =============================================================================
+// Internal — default LLM hooks (lazy import; tests pass mocks)
+// =============================================================================
+const defaultGenerator = async (input) => {
+    // Lazy import so tests / non-LLM environments don't pay the dep cost.
+    const { generateObject } = await import('ai-functions');
+    // Compose a simple schema: every hint key becomes a string field; the LLM
+    // fills in additional fields. Callers wanting strict schemas should pass a
+    // custom generator.
+    const schema = {};
+    for (const [k, v] of Object.entries(input.hints)) {
+        schema[k] = typeof v === 'string' ? v : `Generate a ${k}`;
+    }
+    // Default-fill at least one field so generateObject has work to do.
+    if (Object.keys(schema).length === 0) {
+        schema['name'] = `Generate a name for the ${input.noun}`;
+        schema['description'] = `Generate a description for the ${input.noun}`;
+    }
+    const promptParts = [`Generate a ${input.noun} entity for cascade ${input.cascadeId}.`];
+    if (input.parentNoun) {
+        promptParts.push(`Parent: ${input.parentNoun}${input.parentData ? ` — ${stableStringify(stableData(input.parentData))}` : ''}`);
+    }
+    if (input.siblingCount && input.siblingCount > 1 && input.siblingIndex !== undefined) {
+        promptParts.push(`This is sibling ${input.siblingIndex + 1} of ${input.siblingCount}; vary from siblings.`);
+    }
+    if (input.feedback) {
+        promptParts.push(`Reviewer feedback to address: ${input.feedback}`);
+    }
+    // Wrap the call with model policy (retry + fallback). Failures bubble.
+    let policy = null;
+    try {
+        const { RetryPolicy } = await import('ai-functions');
+        policy = RetryPolicy.forModel(input.model);
+    }
+    catch {
+        // language-models / retry not available — call generateObject directly.
+    }
+    const call = async () => {
+        const { object } = await generateObject({
+            model: input.model,
+            schema,
+            prompt: promptParts.join('\n'),
+        });
+        return object;
+    };
+    if (policy) {
+        return policy.execute(() => call());
+    }
+    return call();
+};
+const defaultValidator = async (input) => {
+    const { generateObject } = await import('ai-functions');
+    // Build a schema that asks for one score per criterion, plus optional feedback.
+    const schema = { feedback: 'Brief feedback on what to improve.' };
+    for (const c of input.rubric.criteria) {
+        schema[c.name] = `Score 0-1 for: ${c.description}`;
+    }
+    const prompt = [
+        `Evaluate this ${input.noun} against the rubric. Return a numeric score 0..1 for each criterion, and brief feedback.`,
+        `Entity: ${stableStringify(stableData(input.data))}`,
+        input.parentData ? `Parent context: ${stableStringify(stableData(input.parentData))}` : '',
+        `Criteria: ${input.rubric.criteria.map((c) => `- ${c.name}: ${c.description}`).join('\n')}`,
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    const { object } = await generateObject({
+        model: input.model,
+        schema,
+        prompt,
+    });
+    const obj = object;
+    const scores = {};
+    for (const c of input.rubric.criteria) {
+        const v = obj[c.name];
+        scores[c.name] = typeof v === 'number' ? Math.max(0, Math.min(1, v)) : 0;
+    }
+    return {
+        scores,
+        ...(typeof obj['feedback'] === 'string' && { feedback: obj['feedback'] }),
+    };
+};
+function finishResult(args) {
+    return {
+        cascadeId: args.cascadeId,
+        root: args.root ?? {
+            $id: '',
+            $type: '',
+            data: {},
+            path: [],
+        },
+        thingsById: args.thingsById,
+        actions: args.actions,
+        rejected: args.rejected,
+        stats: {
+            generated: args.thingsById.size + args.rejected.length,
+            written: args.thingsById.size,
+            actionsRecorded: args.actions.length,
+            rejectedCount: args.rejected.length,
+            regenerationAttempts: args.regenerationAttempts,
+            embedded: args.embedded,
+            durationMs: Date.now() - args.startedAt,
+        },
+    };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// Mark the orchestrator's awareness that hasActionRecording is available
+// (callers may invoke it directly on the adapter for ad-hoc Action recording
+// outside the cascade — the orchestrator itself goes through CascadeWriteStrategy).
+export { hasActionRecording };
+//# sourceMappingURL=cascade-orchestrator.js.map