@adminiumjs/llm 0.1.0-rc.1

package/dist/response/errors.js

@@ -0,0 +1,101 @@
+/**
+ * Validation error model shared by the whole response pipeline
+ * (06-llm-assist.md §7.2). Every stage — extract, parse, version, Zod, locale,
+ * referential, run-binding — reports through the ONE {@link LlmValidationError}
+ * shape so the paste UI and the CLI `--dry-run` can render a single precise
+ * per-path list (§7.2).
+ *
+ * Two axes matter downstream:
+ *  - `code` — the machine code (§7.2/§7.3 tables), rendered verbatim.
+ *  - `severity` — how the pipeline reacts:
+ *      • `fatal`   → rejects the whole run (stays `awaiting_response` / `failed`).
+ *      • `item`    → drops only the offending suggestion; the rest applies
+ *                    (acceptance criterion 4 — a hallucinated table must not
+ *                    discard 200 good labels).
+ *      • `warning` → nothing dropped; surfaced as information (icon fallback,
+ *                    run-id mismatch).
+ *
+ * This module is pure data + string formatting: no Zod, no engine, no I/O — so
+ * it is safe for `@adminium/dashboard` (browser) to pull transitively.
+ */
+/** Every code the pipeline can emit (§7.2 stages + §7.3 referential list). */
+export const LLM_VALIDATION_CODES = [
+    // Stage 1–4 — fatal (reject the run)
+    'LLM_JSON_PARSE',
+    'LLM_TRUNCATED',
+    'LLM_VERSION_MISMATCH',
+    'LLM_MODEL_DECLINED',
+    'LLM_SCHEMA_INVALID',
+    // Stage 5 — per-item
+    'LLM_LOCALE_KEYS',
+    // Stage 6 — referential, per-item (§7.3)
+    'LLM_UNKNOWN_TABLE',
+    'LLM_UNKNOWN_COLUMN',
+    'LLM_BAD_DISPLAY_COLUMN',
+    'LLM_NOT_AN_ENUM',
+    'LLM_ENUM_VALUES',
+    'LLM_UNKNOWN_RELATION',
+    'LLM_RELATION_INVALID',
+    'LLM_UNKNOWN_TEMPLATE',
+    'LLM_UNKNOWN_WIDGET',
+    'LLM_WIDGET_BINDING',
+    'LLM_GROUP_INVALID',
+    // Warnings — nothing dropped
+    'LLM_UNKNOWN_ICON',
+    'LLM_RUN_MISMATCH',
+];
+const FATAL_CODES = new Set([
+    'LLM_JSON_PARSE',
+    'LLM_TRUNCATED',
+    'LLM_VERSION_MISMATCH',
+    'LLM_MODEL_DECLINED',
+    'LLM_SCHEMA_INVALID',
+]);
+const WARNING_CODES = new Set(['LLM_UNKNOWN_ICON', 'LLM_RUN_MISMATCH']);
+/** The fixed severity of a code (§7.2 "Failure class" column). */
+export function severityOf(code) {
+    if (FATAL_CODES.has(code))
+        return 'fatal';
+    if (WARNING_CODES.has(code))
+        return 'warning';
+    return 'item';
+}
+export function isFatal(error) {
+    return error.severity === 'fatal';
+}
+/**
+ * Render a Zod (or hand-built) path array as the pipeline's JSON-path string.
+ * Numeric segments become `[n]`; string segments join with `.`; the first
+ * segment carries no leading dot (`tables[3].table`, not `.tables[3].table`).
+ */
+export function formatJsonPath(segments) {
+    let out = '';
+    for (const seg of segments) {
+        if (typeof seg === 'number') {
+            out += `[${seg}]`;
+            continue;
+        }
+        const key = typeof seg === 'symbol' ? (seg.description ?? seg.toString()) : seg;
+        out += out === '' ? key : `.${key}`;
+    }
+    return out;
+}
+/**
+ * Build a validation error, stamping the code's fixed severity. `hint` /
+ * `suggestionId` are set only when provided (respects
+ * `exactOptionalPropertyTypes`).
+ */
+export function makeError(code, path, message, extra) {
+    const error = {
+        code,
+        severity: severityOf(code),
+        path,
+        message,
+    };
+    if (extra?.hint !== undefined)
+        error.hint = extra.hint;
+    if (extra?.suggestionId !== undefined)
+        error.suggestionId = extra.suggestionId;
+    return error;
+}
+//# sourceMappingURL=errors.js.map

package/dist/response/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/response/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,qCAAqC;IACrC,gBAAgB;IAChB,eAAe;IACf,sBAAsB;IACtB,oBAAoB;IACpB,oBAAoB;IACpB,qBAAqB;IACrB,iBAAiB;IACjB,yCAAyC;IACzC,mBAAmB;IACnB,oBAAoB;IACpB,wBAAwB;IACxB,iBAAiB;IACjB,iBAAiB;IACjB,sBAAsB;IACtB,sBAAsB;IACtB,sBAAsB;IACtB,oBAAoB;IACpB,oBAAoB;IACpB,mBAAmB;IACnB,6BAA6B;IAC7B,kBAAkB;IAClB,kBAAkB;CACV,CAAC;AAwBX,MAAM,WAAW,GAAG,IAAI,GAAG,CAAoB;IAC7C,gBAAgB;IAChB,eAAe;IACf,sBAAsB;IACtB,oBAAoB;IACpB,oBAAoB;CACrB,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAoB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAE3F,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAyB;IAC/C,OAAO,KAAK,CAAC,QAAQ,KAAK,OAAO,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiD;IAC9E,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,GAAG,IAAI,IAAI,GAAG,GAAG,CAAC;YAClB,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAChF,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,IAAuB,EACvB,IAAY,EACZ,OAAe,EACf,KAAgD;IAEhD,MAAM,KAAK,GAAuB;QAChC,IAAI;QACJ,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC;QAC1B,IAAI;QACJ,OAAO;KACR,CAAC;IACF,IAAI,KAAK,EAAE,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACvD,IAAI,KAAK,EAAE,YAAY,KAAK,SAAS;QAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC/E,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/response/extract.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stage 1 — tolerant JSON extraction (06-llm-assist.md §7.2).
+ *
+ * Models wrap the single JSON object the prompt demands (§5 output rule 1) in
+ * things it did not ask for: a ```` ```json ```` fence, a "Here's the JSON:"
+ * preamble, a "Hope this helps!" epilogue. This recovers the object without a
+ * JSON parser: find the first `{`, then walk to the brace that closes it while
+ * ignoring braces inside strings. Everything before the first `{` and after its
+ * matching `}` — fences, prose — is discarded.
+ *
+ * The walk doubles as a truncation detector: if the opening brace never closes
+ * (or a string never terminates), the response was cut off mid-object, which is
+ * a distinct `LLM_TRUNCATED` failure (the direct-path runner retries it with a
+ * raised token ceiling before counting a repair attempt — §7.5).
+ *
+ * Pure string scanning: no `JSON.parse` here (that is stage 2), so a
+ * brace-balanced but otherwise malformed object (trailing comma, single quotes)
+ * is returned for stage 2 to reject as `LLM_JSON_PARSE`.
+ */
+import { type LlmValidationError } from './errors.js';
+export interface ExtractSuccess {
+    ok: true;
+    /** The recovered `{ … }` substring; hand this to `JSON.parse` (stage 2). */
+    json: string;
+}
+export interface ExtractFailure {
+    ok: false;
+    error: LlmValidationError;
+}
+export type ExtractResult = ExtractSuccess | ExtractFailure;
+/**
+ * Recover the single top-level JSON object from a raw model reply. Strips a
+ * wrapping code fence and any leading/trailing prose; reports `LLM_JSON_PARSE`
+ * when there is no object at all and `LLM_TRUNCATED` when one starts but never
+ * closes.
+ */
+export declare function extractJsonObject(raw: string): ExtractResult;
+//# sourceMappingURL=extract.d.ts.map

package/dist/response/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/response/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,KAAK,kBAAkB,EAAa,MAAM,aAAa,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAsD5D"}

package/dist/response/extract.js

@@ -0,0 +1,77 @@
+/**
+ * Stage 1 — tolerant JSON extraction (06-llm-assist.md §7.2).
+ *
+ * Models wrap the single JSON object the prompt demands (§5 output rule 1) in
+ * things it did not ask for: a ```` ```json ```` fence, a "Here's the JSON:"
+ * preamble, a "Hope this helps!" epilogue. This recovers the object without a
+ * JSON parser: find the first `{`, then walk to the brace that closes it while
+ * ignoring braces inside strings. Everything before the first `{` and after its
+ * matching `}` — fences, prose — is discarded.
+ *
+ * The walk doubles as a truncation detector: if the opening brace never closes
+ * (or a string never terminates), the response was cut off mid-object, which is
+ * a distinct `LLM_TRUNCATED` failure (the direct-path runner retries it with a
+ * raised token ceiling before counting a repair attempt — §7.5).
+ *
+ * Pure string scanning: no `JSON.parse` here (that is stage 2), so a
+ * brace-balanced but otherwise malformed object (trailing comma, single quotes)
+ * is returned for stage 2 to reject as `LLM_JSON_PARSE`.
+ */
+import { makeError } from './errors.js';
+/**
+ * Recover the single top-level JSON object from a raw model reply. Strips a
+ * wrapping code fence and any leading/trailing prose; reports `LLM_JSON_PARSE`
+ * when there is no object at all and `LLM_TRUNCATED` when one starts but never
+ * closes.
+ */
+export function extractJsonObject(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return fail('LLM_JSON_PARSE', 'The response was empty; expected a single JSON object.');
+    }
+    const start = trimmed.indexOf('{');
+    if (start === -1) {
+        return fail('LLM_JSON_PARSE', 'No JSON object was found in the response (no opening "{"). Expected a single JSON object.');
+    }
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    let end = -1;
+    for (let i = start; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth += 1;
+        }
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end === -1) {
+        return fail('LLM_TRUNCATED', 'The JSON object is unbalanced — an opening brace is never closed, so the response was likely truncated. Regenerate with a higher output-token limit.');
+    }
+    return { ok: true, json: trimmed.slice(start, end + 1) };
+}
+function fail(code, message) {
+    return { ok: false, error: makeError(code, '', message) };
+}
+//# sourceMappingURL=extract.js.map

package/dist/response/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/response/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAA2B,SAAS,EAAE,MAAM,aAAa,CAAC;AAejE;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,gBAAgB,EAAE,wDAAwD,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,OAAO,IAAI,CACT,gBAAgB,EAChB,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;IAEb,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;iBAAM,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBACvB,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;iBAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACtB,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,QAAQ,GAAG,IAAI,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,GAAG,GAAG,CAAC,CAAC;gBACR,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,OAAO,IAAI,CACT,eAAe,EACf,sJAAsJ,CACvJ,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,IAAI,CAAC,IAAwC,EAAE,OAAe;IACrE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;AAC5D,CAAC"}

package/dist/response/index.d.ts

@@ -0,0 +1,8 @@
+/** `@adminium/llm` response contract + validation barrel — 06-llm-assist.md §6, §7. */
+export * from './schema.js';
+export * from './errors.js';
+export * from './extract.js';
+export * from './referential.js';
+export * from './validate.js';
+export * from './merge.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/response/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/response/index.js

@@ -0,0 +1,8 @@
+/** `@adminium/llm` response contract + validation barrel — 06-llm-assist.md §6, §7. */
+export * from './schema.js';
+export * from './errors.js';
+export * from './extract.js';
+export * from './referential.js';
+export * from './validate.js';
+export * from './merge.js';
+//# sourceMappingURL=index.js.map

package/dist/response/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/response/merge.d.ts

@@ -0,0 +1,53 @@
+import { LlmResponseV1 } from './schema.js';
+import type { DashboardSuggestion, NavGroupSuggestion } from './schema.js';
+/**
+ * Consolidate nav-group proposals from every chunk into one coherent set where
+ * **each table appears in exactly one group** (§4.5). Same-id groups union their
+ * tables; a table proposed under several groups is assigned to the group with
+ * the highest confidence (ties by id) and removed from the rest; empty groups
+ * drop out. If more than 7 groups survive, the lowest-priority groups' tables
+ * fold into the last kept group so the cap holds without orphaning any table.
+ */
+export declare function consolidateNavGroups(groups: readonly NavGroupSuggestion[]): NavGroupSuggestion[];
+/**
+ * Consolidate dashboard proposals: same-id dashboards union tables and widgets
+ * (widgets dedupe by binding, keeping the highest confidence), widgets are
+ * re-ranked by confidence and capped at 8, and the dashboards themselves are
+ * ranked by total widget confidence and capped at 6. Fully deterministic.
+ */
+export declare function consolidateDashboards(dashboards: readonly DashboardSuggestion[]): DashboardSuggestion[];
+/**
+ * Reduce per-chunk `LlmResponseV1` results into one validated response. Purely
+ * deterministic and independent of the order of `responses`. Responses that the
+ * model declined (an `error` key set) contribute nothing; if every response
+ * declined, the first declared error propagates.
+ */
+export declare function mergeChunkResponses(responses: readonly LlmResponseV1[]): LlmResponseV1;
+export interface MergePromptOptions {
+    /** Full qualified table-name list for the whole schema, injected into the prompt (§4.5). */
+    allTableNames: readonly string[];
+}
+export interface MergePromptArtifact {
+    system: string;
+    user: string;
+    /** BYO flattening (`=== SYSTEM ===` / `=== USER ===`), same as map-phase prompts. */
+    byo: string;
+    tokenEstimate: number;
+    /** Chunk count injected as `{{TOTAL}}`. */
+    total: number;
+}
+/**
+ * Build the `PROMPT_MERGE_V1` reduce prompt (§4.5): it embeds only each chunk's
+ * partial `navGroups`/`dashboards` and the full table-name list, reusing the v1
+ * system section verbatim. Used only for the optional LLM consolidation of the
+ * global sections when a run was chunked.
+ */
+export declare function buildMergePrompt(responses: readonly LlmResponseV1[], options: MergePromptOptions): MergePromptArtifact;
+/**
+ * Fold an LLM merge-prompt response's consolidated global sections onto the
+ * deterministic per-table merge, re-running the deterministic global
+ * consolidation defensively (so the output still guarantees one group per table
+ * and honors the caps even if the model drifted).
+ */
+export declare function applyGlobalMerge(merged: LlmResponseV1, mergeResponse: LlmResponseV1): LlmResponseV1;
+//# sourceMappingURL=merge.d.ts.map

package/dist/response/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/response/merge.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAEV,mBAAmB,EAGnB,kBAAkB,EAGnB,MAAM,aAAa,CAAC;AA+HrB;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAwEhG;AA0BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAwDvG;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,CAqBtF;AAID,MAAM,WAAW,kBAAkB;IACjC,4FAA4F;IAC5F,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,OAAO,EAAE,kBAAkB,GAC1B,mBAAmB,CAgBrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,GAAG,aAAa,CAMnG"}

package/dist/response/merge.js

@@ -0,0 +1,348 @@
+/**
+ * `merge.ts` — deterministic chunk reduce + the `PROMPT_MERGE_V1` orchestration
+ * (06-llm-assist.md §4.5, acceptance criterion 7).
+ *
+ * The map phase (see `prompt/chunker.ts`) produces one `LlmResponseV1` per chunk.
+ * This module reduces them back to one:
+ *
+ * 1. **Deterministic code reduce** ({@link mergeChunkResponses}). Per-table
+ *    sections (`tables`, `enums`, per-column `pii`, `microcopy`, `relations`) are
+ *    disjoint by table across chunks and merged by key. Duplicate inferred
+ *    relations (both endpoints stubbed in one chunk, real in another) dedupe by
+ *    endpoints keeping the highest confidence. Global sections (`navGroups`,
+ *    `dashboards`) are consolidated so **every table lands in exactly one nav
+ *    group** and no group/dashboard cap is exceeded. Every tie-break is
+ *    content-derived, so the result is invariant under the order of the input
+ *    responses (acceptance criterion 7: "order-independent").
+ *
+ * 2. **LLM reduce prompt** ({@link buildMergePrompt}). For a richer cross-chunk
+ *    grouping, `PROMPT_MERGE_V1` (§4.5, shipped verbatim in `prompt/templates`)
+ *    receives only the per-chunk `navGroups`/`dashboards` plus the full
+ *    table-name list and returns one consolidated global result;
+ *    {@link applyGlobalMerge} folds that back onto the deterministic per-table
+ *    merge (re-running the deterministic global consolidation defensively).
+ *
+ * Determinism: no `Date.now`/`Math.random`; canonical (sorted-key) JSON drives
+ * every tie-break. Browser-safe: only pure-TS/Zod imports.
+ */
+import { flattenByo } from '../prompt/builder.js';
+import { toPromptJson } from '../prompt/serializer.js';
+import { PROMPT_MERGE_V1 } from '../prompt/templates/v1.js';
+import { estimateTokens } from '../prompt/token-estimate.js';
+import { LlmResponseV1, SCHEMA_VERSION } from './schema.js';
+const KEY_SEP = '\x00';
+// ─── Canonical serialization for content-derived tie-breaks ──────────────────
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        const out = {};
+        for (const key of Object.keys(record).sort())
+            out[key] = sortKeys(record[key]);
+        return out;
+    }
+    return value;
+}
+/** Order-independent canonical JSON (keys sorted recursively) for tie-breaking. */
+function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+/**
+ * True when `candidate` should win over `incumbent`: higher confidence, else the
+ * lexicographically smaller canonical form. A total order → the same winner
+ * regardless of which response was seen first.
+ */
+function outranks(candidateConfidence, incumbentConfidence, candidate, incumbent) {
+    if (candidateConfidence !== incumbentConfidence)
+        return candidateConfidence > incumbentConfidence;
+    return canonicalJson(candidate) < canonicalJson(incumbent);
+}
+// ─── Per-table sections (disjoint by key) ────────────────────────────────────
+function mergeTables(responses) {
+    const byTable = new Map();
+    for (const response of responses) {
+        for (const table of response.tables) {
+            const incumbent = byTable.get(table.table);
+            if (incumbent === undefined || outranks(table.confidence, incumbent.confidence, table, incumbent)) {
+                byTable.set(table.table, table);
+            }
+        }
+    }
+    return [...byTable.values()].sort((a, b) => a.table.localeCompare(b.table));
+}
+function mergeEnums(responses) {
+    const byColumn = new Map();
+    for (const response of responses) {
+        for (const suggestion of response.enums) {
+            const key = `${suggestion.table}${KEY_SEP}${suggestion.column}`;
+            const incumbent = byColumn.get(key);
+            if (incumbent === undefined || outranks(suggestion.confidence, incumbent.confidence, suggestion, incumbent)) {
+                byColumn.set(key, suggestion);
+            }
+        }
+    }
+    return [...byColumn.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([, value]) => value);
+}
+function endpointKey(relation) {
+    return [
+        relation.fromTable,
+        relation.fromColumns.join(','),
+        relation.toTable,
+        relation.toColumns.join(','),
+    ].join(KEY_SEP);
+}
+function mergeConfirmed(responses) {
+    const byEndpoints = new Map();
+    for (const response of responses) {
+        for (const relation of response.relations.confirmed) {
+            const key = endpointKey(relation);
+            const incumbent = byEndpoints.get(key);
+            if (incumbent === undefined || outranks(relation.confidence, incumbent.confidence, relation, incumbent)) {
+                byEndpoints.set(key, relation);
+            }
+        }
+    }
+    return [...byEndpoints.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([, value]) => value);
+}
+function mergeInferred(responses) {
+    const byEndpoints = new Map();
+    for (const response of responses) {
+        for (const relation of response.relations.inferred) {
+            const key = endpointKey(relation);
+            const incumbent = byEndpoints.get(key);
+            if (incumbent === undefined || outranks(relation.confidence, incumbent.confidence, relation, incumbent)) {
+                byEndpoints.set(key, relation);
+            }
+        }
+    }
+    return [...byEndpoints.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([, value]) => value);
+}
+function mergeNotes(responses) {
+    const notes = new Set();
+    for (const response of responses) {
+        for (const note of response.notes ?? [])
+            notes.add(note);
+    }
+    return [...notes].sort((a, b) => a.localeCompare(b)).slice(0, 5);
+}
+/** Max nav groups allowed by the response schema (§6.1: `navGroups.max(7)`). */
+const MAX_NAV_GROUPS = 7;
+/**
+ * Consolidate nav-group proposals from every chunk into one coherent set where
+ * **each table appears in exactly one group** (§4.5). Same-id groups union their
+ * tables; a table proposed under several groups is assigned to the group with
+ * the highest confidence (ties by id) and removed from the rest; empty groups
+ * drop out. If more than 7 groups survive, the lowest-priority groups' tables
+ * fold into the last kept group so the cap holds without orphaning any table.
+ */
+export function consolidateNavGroups(groups) {
+    const byId = new Map();
+    for (const group of groups) {
+        const incumbent = byId.get(group.id);
+        if (incumbent === undefined) {
+            byId.set(group.id, {
+                id: group.id,
+                label: group.label,
+                icon: group.icon,
+                confidence: group.confidence,
+                tables: new Set(group.tables),
+            });
+            continue;
+        }
+        for (const table of group.tables)
+            incumbent.tables.add(table);
+        const swapLabel = outranks(group.confidence, incumbent.confidence, { label: group.label, icon: group.icon }, { label: incumbent.label, icon: incumbent.icon });
+        if (swapLabel) {
+            incumbent.label = group.label;
+            incumbent.icon = group.icon;
+        }
+        incumbent.confidence = Math.max(incumbent.confidence, group.confidence);
+    }
+    const accs = [...byId.values()];
+    // One group per table: pick the best owning group deterministically.
+    const owner = new Map();
+    for (const acc of accs) {
+        for (const table of acc.tables) {
+            const current = owner.get(table);
+            if (current === undefined) {
+                owner.set(table, acc);
+                continue;
+            }
+            const better = acc.confidence > current.confidence ||
+                (acc.confidence === current.confidence && acc.id.localeCompare(current.id) < 0);
+            if (better)
+                owner.set(table, acc);
+        }
+    }
+    for (const acc of accs) {
+        acc.tables = new Set([...acc.tables].filter((table) => owner.get(table) === acc));
+    }
+    let ranked = accs
+        .filter((acc) => acc.tables.size > 0)
+        .sort((a, b) => b.confidence - a.confidence || a.id.localeCompare(b.id));
+    if (ranked.length > MAX_NAV_GROUPS) {
+        const kept = ranked.slice(0, MAX_NAV_GROUPS);
+        const sink = kept[kept.length - 1];
+        if (sink !== undefined) {
+            for (const acc of ranked.slice(MAX_NAV_GROUPS)) {
+                for (const table of acc.tables)
+                    sink.tables.add(table);
+            }
+        }
+        ranked = kept;
+    }
+    return ranked.map((acc, index) => ({
+        id: acc.id,
+        label: acc.label,
+        icon: acc.icon,
+        order: index,
+        tables: [...acc.tables].sort((a, b) => a.localeCompare(b)),
+        confidence: acc.confidence,
+    }));
+}
+/** Max dashboards / widgets-per-dashboard allowed by the schema (§6.1). */
+const MAX_DASHBOARDS = 6;
+const MAX_WIDGETS = 8;
+function widgetKey(widget) {
+    return [
+        widget.widget,
+        widget.table,
+        widget.metricColumn ?? '',
+        widget.dimensionColumn ?? '',
+        widget.timeColumn ?? '',
+        widget.agg ?? '',
+    ].join(KEY_SEP);
+}
+/**
+ * Consolidate dashboard proposals: same-id dashboards union tables and widgets
+ * (widgets dedupe by binding, keeping the highest confidence), widgets are
+ * re-ranked by confidence and capped at 8, and the dashboards themselves are
+ * ranked by total widget confidence and capped at 6. Fully deterministic.
+ */
+export function consolidateDashboards(dashboards) {
+    const byId = new Map();
+    for (const dashboard of dashboards) {
+        const metaKey = canonicalJson({ domain: dashboard.domain, label: dashboard.label });
+        let acc = byId.get(dashboard.id);
+        if (acc === undefined) {
+            acc = {
+                id: dashboard.id,
+                domain: dashboard.domain,
+                label: dashboard.label,
+                metaKey,
+                tables: new Set(),
+                widgets: new Map(),
+            };
+            byId.set(dashboard.id, acc);
+        }
+        else if (metaKey < acc.metaKey) {
+            acc.domain = dashboard.domain;
+            acc.label = dashboard.label;
+            acc.metaKey = metaKey;
+        }
+        for (const table of dashboard.tables)
+            acc.tables.add(table);
+        for (const widget of dashboard.widgets) {
+            const key = widgetKey(widget);
+            const incumbent = acc.widgets.get(key);
+            if (incumbent === undefined || outranks(widget.confidence, incumbent.confidence, widget, incumbent)) {
+                acc.widgets.set(key, widget);
+            }
+        }
+    }
+    const built = [...byId.values()].map((acc) => {
+        const widgets = [...acc.widgets.values()]
+            .sort((a, b) => b.confidence - a.confidence ||
+            a.widget.localeCompare(b.widget) ||
+            a.table.localeCompare(b.table) ||
+            widgetKey(a).localeCompare(widgetKey(b)))
+            .slice(0, MAX_WIDGETS)
+            .map((widget, index) => ({ ...widget, rank: index + 1 }));
+        const score = widgets.reduce((sum, widget) => sum + widget.confidence, 0);
+        return { acc, widgets, score };
+    });
+    return built
+        .sort((a, b) => b.score - a.score || a.acc.id.localeCompare(b.acc.id))
+        .slice(0, MAX_DASHBOARDS)
+        .map(({ acc, widgets }, index) => ({
+        id: acc.id,
+        domain: acc.domain,
+        label: acc.label,
+        order: index,
+        tables: [...acc.tables].sort((a, b) => a.localeCompare(b)),
+        widgets,
+    }));
+}
+// ─── Deterministic reduce (public) ───────────────────────────────────────────
+/**
+ * Reduce per-chunk `LlmResponseV1` results into one validated response. Purely
+ * deterministic and independent of the order of `responses`. Responses that the
+ * model declined (an `error` key set) contribute nothing; if every response
+ * declined, the first declared error propagates.
+ */
+export function mergeChunkResponses(responses) {
+    const active = responses.filter((response) => response.error === undefined);
+    if (active.length === 0) {
+        const declined = responses.find((response) => response.error !== undefined);
+        if (declined?.error !== undefined) {
+            return LlmResponseV1.parse({ schema_version: SCHEMA_VERSION, error: declined.error });
+        }
+        return LlmResponseV1.parse({ schema_version: SCHEMA_VERSION });
+    }
+    const notes = mergeNotes(active);
+    const base = {
+        schema_version: SCHEMA_VERSION,
+        tables: mergeTables(active),
+        enums: mergeEnums(active),
+        relations: { confirmed: mergeConfirmed(active), inferred: mergeInferred(active) },
+        navGroups: consolidateNavGroups(active.flatMap((response) => response.navGroups)),
+        dashboards: consolidateDashboards(active.flatMap((response) => response.dashboards)),
+    };
+    return LlmResponseV1.parse(notes.length > 0 ? { ...base, notes } : base);
+}
+function fillToken(text, token, value) {
+    // Function replacer so a `$` inside injected JSON is never a replacement pattern.
+    return text.replace(token, () => value);
+}
+/**
+ * Build the `PROMPT_MERGE_V1` reduce prompt (§4.5): it embeds only each chunk's
+ * partial `navGroups`/`dashboards` and the full table-name list, reusing the v1
+ * system section verbatim. Used only for the optional LLM consolidation of the
+ * global sections when a run was chunked.
+ */
+export function buildMergePrompt(responses, options) {
+    const total = responses.length;
+    const partials = responses.map((response) => ({
+        navGroups: response.navGroups,
+        dashboards: response.dashboards,
+    }));
+    const tableNames = [...new Set(options.allTableNames)].sort((a, b) => a.localeCompare(b));
+    const system = PROMPT_MERGE_V1.system;
+    let user = PROMPT_MERGE_V1.user;
+    user = fillToken(user, '{{TOTAL}}', String(total));
+    user = fillToken(user, '{{ALL_TABLE_NAMES_JSON}}', toPromptJson(tableNames));
+    user = fillToken(user, '{{PARTIAL_GROUPS_AND_DASHBOARDS_JSON}}', toPromptJson(partials));
+    const byo = flattenByo(system, user);
+    return { system, user, byo, tokenEstimate: estimateTokens(byo), total };
+}
+/**
+ * Fold an LLM merge-prompt response's consolidated global sections onto the
+ * deterministic per-table merge, re-running the deterministic global
+ * consolidation defensively (so the output still guarantees one group per table
+ * and honors the caps even if the model drifted).
+ */
+export function applyGlobalMerge(merged, mergeResponse) {
+    return LlmResponseV1.parse({
+        ...merged,
+        navGroups: consolidateNavGroups(mergeResponse.navGroups),
+        dashboards: consolidateDashboards(mergeResponse.dashboards),
+    });
+}
+//# sourceMappingURL=merge.js.map