@adminiumjs/llm 0.1.0-rc.1

package/dist/apply/suggestion-id.js.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AES-256-GCM secret-at-rest for the encrypted `llm.apiKey` setting
+ * (06-llm-assist.md §3.2; 01-architecture.md §7.1). The LLM key is protected with
+ * the SAME mechanism connection strings use: an HKDF-SHA256 key derived from
+ * `ADMINIUM_SECRET`, purpose-scoped by salt, producing `enc:v1:` GCM tokens
+ * (`apps/server/src/config/secrets.ts` + `apps/server/src/connections/crypto.ts`).
+ *
+ * ⚠️ BLOCKER (see this track's followUps): those primitives currently live ONLY
+ * in the server tree. `@adminium/llm` is consumed by the browser dashboard, so it
+ * cannot import server code, and a package→app edge is impossible anyway. Until
+ * the AES-256-GCM helper is extracted into a shared, browser-safe leaf, this
+ * module ships the crypto CONTRACT and the LLM purpose-scoped wiring, taking the
+ * primitives by INJECTION. M6 Wave 2 (server) supplies the real `node:crypto`
+ * implementation; unit tests inject a fake. No `node:*` import here keeps the
+ * package browser-safe.
+ */
+/** Purpose scope for the LLM API-key encryption key (mirror of `DSN_KEY_SALT`). */
+export declare const LLM_KEY_SALT: "adminium:llm-key:v1";
+/**
+ * The AES-256-GCM primitives this module wires together — the exact shape of
+ * `apps/server/src/config/secrets.ts`. Injected so the browser-safe `@adminium/llm`
+ * never has to import the `node:crypto`-backed implementation directly.
+ */
+export interface SecretCryptoHelpers {
+    /** HKDF-SHA256 → 32-byte key, purpose-scoped by `salt` (+ optional `info`). */
+    deriveKey(secret: string, salt: string | Uint8Array, info?: string): Uint8Array;
+    /** UTF-8 plaintext → `enc:v1:` GCM token with a fresh random IV. */
+    encryptSecret(plaintext: string, key: Uint8Array): string;
+    /** `enc:v1:` token → UTF-8 plaintext; throws on tamper / wrong key. */
+    decryptSecret(token: string, key: Uint8Array): string;
+}
+/**
+ * Encrypt/decrypt closures scoped to the LLM API-key purpose — the exact shape of
+ * `@adminium/meta`'s `DsnCrypto`, so the meta store stays crypto-agnostic and the
+ * server can hand the LLM-config repo these closures the same way it does for DSNs.
+ */
+export interface LlmKeyCrypto {
+    encrypt(plaintext: string): string;
+    decrypt(token: string): string;
+}
+/**
+ * Builds the LLM-key crypto closures from the master secret and injected
+ * primitives (mirror of `dsnCryptoFromSecret`). The `ADMINIUM_SECRET`-derived key
+ * is scoped by {@link LLM_KEY_SALT} so LLM-key, DSN, TOTP, and session keys never
+ * coincide even for the same master secret.
+ */
+export declare function llmKeyCryptoFromSecret(masterSecret: string, helpers: SecretCryptoHelpers): LlmKeyCrypto;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,mFAAmF;AACnF,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAChF,oEAAoE;IACpE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1D,uEAAuE;IACvE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CASd"}

package/dist/crypto.js

@@ -0,0 +1,35 @@
+/**
+ * AES-256-GCM secret-at-rest for the encrypted `llm.apiKey` setting
+ * (06-llm-assist.md §3.2; 01-architecture.md §7.1). The LLM key is protected with
+ * the SAME mechanism connection strings use: an HKDF-SHA256 key derived from
+ * `ADMINIUM_SECRET`, purpose-scoped by salt, producing `enc:v1:` GCM tokens
+ * (`apps/server/src/config/secrets.ts` + `apps/server/src/connections/crypto.ts`).
+ *
+ * ⚠️ BLOCKER (see this track's followUps): those primitives currently live ONLY
+ * in the server tree. `@adminium/llm` is consumed by the browser dashboard, so it
+ * cannot import server code, and a package→app edge is impossible anyway. Until
+ * the AES-256-GCM helper is extracted into a shared, browser-safe leaf, this
+ * module ships the crypto CONTRACT and the LLM purpose-scoped wiring, taking the
+ * primitives by INJECTION. M6 Wave 2 (server) supplies the real `node:crypto`
+ * implementation; unit tests inject a fake. No `node:*` import here keeps the
+ * package browser-safe.
+ */
+/** Purpose scope for the LLM API-key encryption key (mirror of `DSN_KEY_SALT`). */
+export const LLM_KEY_SALT = 'adminium:llm-key:v1';
+/**
+ * Builds the LLM-key crypto closures from the master secret and injected
+ * primitives (mirror of `dsnCryptoFromSecret`). The `ADMINIUM_SECRET`-derived key
+ * is scoped by {@link LLM_KEY_SALT} so LLM-key, DSN, TOTP, and session keys never
+ * coincide even for the same master secret.
+ */
+export function llmKeyCryptoFromSecret(masterSecret, helpers) {
+    if (masterSecret.length === 0) {
+        throw new Error('cannot derive an LLM key-crypto closure from an empty secret');
+    }
+    const key = helpers.deriveKey(masterSecret, LLM_KEY_SALT);
+    return {
+        encrypt: (plaintext) => helpers.encryptSecret(plaintext, key),
+        decrypt: (token) => helpers.decryptSecret(token, key),
+    };
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,qBAA8B,CAAC;AA0B3D;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAAoB,EACpB,OAA4B;IAE5B,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAC1D,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC;QAC7D,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@adminium/llm` — headless LLM-assist: provider clients, prompt builder,
+ * response contract + validation, EnrichmentSet normalization/diff, and the
+ * BYO round-trip. Browser-safe (pure Zod / pure TS + global `fetch`); consumed
+ * by both `@adminium/server` and `@adminium/dashboard`. See 06-llm-assist.md.
+ *
+ * This is the single top-level barrel: it re-exports every subdir barrel. The
+ * tracks own their own subdir barrels; this file stitches them together.
+ */
+export declare const PACKAGE_NAME = "@adminium/llm";
+export * from './types.js';
+export * from './crypto.js';
+export * from './response/index.js';
+export * from './prompt/index.js';
+export * from './providers/index.js';
+export * from './apply/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAG5C,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAG5B,cAAc,qBAAqB,CAAC;AAGpC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@adminium/llm` — headless LLM-assist: provider clients, prompt builder,
+ * response contract + validation, EnrichmentSet normalization/diff, and the
+ * BYO round-trip. Browser-safe (pure Zod / pure TS + global `fetch`); consumed
+ * by both `@adminium/server` and `@adminium/dashboard`. See 06-llm-assist.md.
+ *
+ * This is the single top-level barrel: it re-exports every subdir barrel. The
+ * tracks own their own subdir barrels; this file stitches them together.
+ */
+export const PACKAGE_NAME = '@adminium/llm';
+// Shared contract types (§2, §7.1) + the encrypted-key crypto contract (§3.2).
+export * from './types.js';
+export * from './crypto.js';
+// Response contract + validation pipeline (§6, §7).
+export * from './response/index.js';
+// Prompt builder + chunker (§4, §5).
+export * from './prompt/index.js';
+// Direct-API provider clients (§3).
+export * from './providers/index.js';
+// Apply: EnrichmentSet normalization + field-by-field diff (§8).
+export * from './apply/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC;AAE5C,+EAA+E;AAC/E,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,oDAAoD;AACpD,cAAc,qBAAqB,CAAC;AAEpC,qCAAqC;AACrC,cAAc,mBAAmB,CAAC;AAElC,oCAAoC;AACpC,cAAc,sBAAsB,CAAC;AAErC,iEAAiE;AACjE,cAAc,kBAAkB,CAAC"}

package/dist/prompt/builder.d.ts

@@ -0,0 +1,27 @@
+import { type BuildPromptOptions, type PromptArtifact, type PromptChunkInfo, type PromptInput, type RequestedSection } from './types.js';
+/** BYO flattening dividers (§1 invariant 1, §5). */
+export declare const BYO_SYSTEM_MARKER = "=== SYSTEM ===";
+export declare const BYO_USER_MARKER = "=== USER ===";
+/**
+ * Flatten a system/user pair into the single copyable BYO document. The bytes
+ * between the markers equal `system` and `user` exactly, so a response produced
+ * from this document is indistinguishable from a direct-path response.
+ */
+export declare function flattenByo(system: string, user: string): string;
+/** Build the enrichment prompt for one (possibly chunked) input. */
+export declare function buildPrompt(input: PromptInput, options: BuildPromptOptions): PromptArtifact;
+/** Dedupe + canonically order the requested sections; empty ⇒ all (§4.4). */
+export declare function normalizeSections(requested: readonly RequestedSection[]): readonly RequestedSection[];
+/**
+ * Apply the section toggles to the user template (§4.4): remove BOTH the numbered
+ * decision blocks AND the embedded response-schema keys of deselected sections
+ * (per the §5 builder note "the builder deletes the numbered instruction blocks
+ * (and schema keys) of deselected sections"). Kept decision blocks retain their
+ * original numbers (gaps are fine) so the template's "for decision 6" / "Skip
+ * decisions 2 and 7" references stay valid. With all sections active the template
+ * is returned unchanged (verbatim — acceptance criterion 2).
+ */
+export declare function applySectionToggles(template: string, sections: readonly RequestedSection[]): string;
+/** The `{{CHUNK_INFO}}` sentence for a chunked run; empty otherwise (§4.5, §5.2). */
+export declare function renderChunkInfo(chunk: PromptChunkInfo | undefined): string;
+//# sourceMappingURL=builder.d.ts.map

package/dist/prompt/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/prompt/builder.ts"],"names":[],"mappings":"AA2BA,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAClD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAuB3F;AAID,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,SAAS,gBAAgB,EAAE,CAI7B;AAUD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,MAAM,CAkBR;AA4KD,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAQ1E"}

package/dist/prompt/builder.js

@@ -0,0 +1,263 @@
+/**
+ * `buildPrompt(input, opts)` — the ONLY producer of prompt text (06-llm-assist.md
+ * §1 invariant 1, §4, §5).
+ *
+ * It renders the verbatim {@link PROMPT_V1} templates into a
+ * {@link PromptArtifact}: the direct path sends `system`/`user` as separate
+ * messages; the BYO path copies `byo`, the two flattened between
+ * `=== SYSTEM ===` / `=== USER ===` dividers. The content between the dividers is
+ * byte-identical to `system` + `user` (acceptance criterion 1).
+ *
+ * Responsibilities:
+ *  - section toggles (§4.4): drop deselected numbered decision blocks, keeping
+ *    the original numbering so the template's "decision N" cross-references stay
+ *    valid;
+ *  - locale injection (§5.2): the requested OUTPUT locales are injected as data;
+ *    the prompt TEXT itself is always English (Open decision 3);
+ *  - allow-list bounds (§5 builder notes): the injected page-template / widget
+ *    vocabularies come from `opts.allowed`;
+ *  - sample-free serialization by default (§4.2), delegated to `serializer.ts`.
+ *
+ * Determinism: pure string assembly, no `Date.now`/`Math.random`; string-literal
+ * token replacement uses function replacers so a `$` in injected JSON is never
+ * interpreted as a replacement pattern.
+ */
+import { serializeSampling, serializeSchemaIr, serializeStats, toPromptJson } from './serializer.js';
+import { PROMPT_V1_SYSTEM, PROMPT_V1_USER } from './templates/v1.js';
+import { estimateTokens } from './token-estimate.js';
+import { ALL_SECTIONS, DEFAULT_TOKEN_BUDGET, REQUESTED_SECTIONS, SECTION_DECISION_NUMBER, } from './types.js';
+/** BYO flattening dividers (§1 invariant 1, §5). */
+export const BYO_SYSTEM_MARKER = '=== SYSTEM ===';
+export const BYO_USER_MARKER = '=== USER ===';
+/**
+ * Flatten a system/user pair into the single copyable BYO document. The bytes
+ * between the markers equal `system` and `user` exactly, so a response produced
+ * from this document is indistinguishable from a direct-path response.
+ */
+export function flattenByo(system, user) {
+    return `${BYO_SYSTEM_MARKER}\n${system}\n\n${BYO_USER_MARKER}\n${user}`;
+}
+/** Build the enrichment prompt for one (possibly chunked) input. */
+export function buildPrompt(input, options) {
+    requireEnUs(input.locales);
+    const sections = normalizeSections(input.sections);
+    const tokenBudget = options.tokenBudget ?? DEFAULT_TOKEN_BUDGET;
+    const system = PROMPT_V1_SYSTEM;
+    const user = renderUserSection(input, options, sections);
+    const byo = flattenByo(system, user);
+    const tokenEstimate = estimateTokens(byo);
+    const overBudget = estimateTokens(user) > tokenBudget;
+    const chunk = {
+        index: input.chunk?.index ?? 1,
+        total: input.chunk?.total ?? 1,
+        system,
+        user,
+        byo,
+        tokenEstimate,
+    };
+    return { system, user, byo, chunks: [chunk], tokenEstimate, overBudget, sections };
+}
+// ─── Section normalization + block removal (§4.4) ────────────────────────────
+/** Dedupe + canonically order the requested sections; empty ⇒ all (§4.4). */
+export function normalizeSections(requested) {
+    const set = new Set(requested);
+    const ordered = REQUESTED_SECTIONS.filter((section) => set.has(section));
+    return ordered.length > 0 ? ordered : ALL_SECTIONS;
+}
+const DECISIONS_START = '{{REQUESTED_SECTIONS_LIST}}\n\n';
+const DECISIONS_END = '\n\n=== TRIGGER TAXONOMY (for decision 6) ===';
+/**
+ * Apply the section toggles to the user template (§4.4): remove BOTH the numbered
+ * decision blocks AND the embedded response-schema keys of deselected sections
+ * (per the §5 builder note "the builder deletes the numbered instruction blocks
+ * (and schema keys) of deselected sections"). Kept decision blocks retain their
+ * original numbers (gaps are fine) so the template's "for decision 6" / "Skip
+ * decisions 2 and 7" references stay valid. With all sections active the template
+ * is returned unchanged (verbatim — acceptance criterion 2).
+ */
+export function applySectionToggles(template, sections) {
+    if (sections.length === REQUESTED_SECTIONS.length)
+        return template;
+    const startIndex = template.indexOf(DECISIONS_START);
+    const endIndex = template.indexOf(DECISIONS_END);
+    if (startIndex < 0 || endIndex < 0)
+        return template;
+    const bodyStart = startIndex + DECISIONS_START.length;
+    const body = template.slice(bodyStart, endIndex);
+    const activeNumbers = new Set(sections.map((section) => SECTION_DECISION_NUMBER[section]));
+    const kept = splitDecisionBlocks(body)
+        .filter((block) => activeNumbers.has(block.num))
+        .map((block) => block.text)
+        .join('\n\n');
+    const withDecisions = template.slice(0, bodyStart) + kept + template.slice(endIndex);
+    return pruneResponseSchema(withDecisions, new Set(sections));
+}
+// ─── Response-schema key removal (§4.4, §5 builder note) ──────────────────────
+/** Anchors bounding the embedded `=== RESPONSE SCHEMA … ===` object notation. */
+const SCHEMA_OBJECT_START = '{\n  schema_version: "adminium.llm/v1",';
+const SCHEMA_OBJECT_END = '\n\n=== INPUT: DATABASE SCHEMA ===';
+/**
+ * Whole-line splice: drop every line from the one containing `startAnchor`
+ * through the one containing `endAnchor` (searched AFTER the start), replacing the
+ * span with `replacement`. Anchor-based (not whitespace-hardcoded) so it tracks
+ * the verbatim template even if its indentation is later re-flowed. A missing
+ * anchor is a no-op — the schema stays intact rather than being corrupted.
+ */
+function spliceLines(block, startAnchor, endAnchor, replacement) {
+    const s = block.indexOf(startAnchor);
+    if (s < 0)
+        return block;
+    const e = block.indexOf(endAnchor, s);
+    if (e < 0)
+        return block;
+    const lineStart = block.lastIndexOf('\n', s) + 1;
+    const afterEnd = block.indexOf('\n', e + endAnchor.length);
+    const lineEnd = afterEnd < 0 ? block.length : afterEnd + 1;
+    return block.slice(0, lineStart) + replacement + block.slice(lineEnd);
+}
+function cutLines(block, startAnchor, endAnchor) {
+    return spliceLines(block, startAnchor, endAnchor, '');
+}
+/** Leading whitespace of the line containing `anchor` (for indent-preserving splices). */
+function indentOf(block, anchor) {
+    const i = block.indexOf(anchor);
+    if (i < 0)
+        return '';
+    return block.slice(block.lastIndexOf('\n', i) + 1, i);
+}
+/**
+ * Single-section schema-key removals keyed by the section deselected. Each entry
+ * is a `[startAnchor, endAnchor]` pair identifying the line span to delete.
+ * `groups`, `widgets` and the nav-group icon are handled separately below because
+ * they share the `navGroups` / `dashboards` structures.
+ */
+const SCHEMA_KEY_CUTS = {
+    labels: [
+        ['label: L10n, description: L10n,', 'label: L10n, description: L10n,'],
+        ['label: L10n, description?: L10n,', 'label: L10n, description?: L10n,'],
+    ],
+    keys: [
+        ['displayColumn: string | null,', 'displayColumn: string | null,'],
+        ['naturalKey: string[] | null,', 'naturalKey: string[] | null,'],
+    ],
+    templates: [['pageTemplates: [{', 'confidence: number }],']],
+    microcopy: [['microcopy: {', 'pageSubtitle: L10n }']],
+    pii: [['pii: null | {', 'confidence: number }']],
+    enums: [['enums: [{', 'confidence: number }],']],
+    relations: [['relations: {', '  },']],
+    icons: [['// lucide kebab-case', '// lucide kebab-case']],
+};
+/**
+ * Remove the response-schema keys of deselected sections from the embedded
+ * RESPONSE SCHEMA block (§4.4: deselected keys are "omitted from … the embedded
+ * response schema"), so a scoped run's schema reflects only the requested
+ * decisions and the model does not emit — and pay output tokens for — keys the
+ * run neither asked for nor validates.
+ */
+function pruneResponseSchema(template, active) {
+    const startIdx = template.indexOf(SCHEMA_OBJECT_START);
+    const endIdx = template.indexOf(SCHEMA_OBJECT_END);
+    if (startIdx < 0 || endIdx < 0 || endIdx < startIdx)
+        return template;
+    let block = template.slice(startIdx, endIdx);
+    // Single-section, self-contained key spans.
+    for (const [section, cuts] of Object.entries(SCHEMA_KEY_CUTS)) {
+        if (active.has(section))
+            continue;
+        for (const [start, end] of cuts)
+            block = cutLines(block, start, end);
+    }
+    // navGroups (owned by `groups`) + dashboards (`groups` → domain, `widgets` →
+    // widgets) share structure, so resolve them together — BEFORE the nav-group
+    // icon strip, which expects the navGroups line to still exist.
+    const groupsOff = !active.has('groups');
+    const widgetsOff = !active.has('widgets');
+    if (groupsOff) {
+        block = cutLines(block, 'navGroups: [{', 'tables: string[], confidence: number }],');
+    }
+    if (groupsOff && widgetsOff) {
+        block = cutLines(block, 'dashboards: [{', 'confidence: number }] }],');
+    }
+    else if (groupsOff) {
+        block = block.split('domain: string, ').join(''); // dashboards kept for its widgets
+    }
+    else if (widgetsOff) {
+        // The dashboards `tables: string[],` is the only one directly followed by a
+        // newline (the navGroups one is `tables: string[], confidence …`), so the
+        // trailing `\n` disambiguates it. Remove the widgets sub-block and drop the
+        // now-dangling comma so the dashboards object still closes.
+        const anchor = 'tables: string[],\n';
+        const indent = indentOf(block, anchor);
+        block = spliceLines(block, anchor, 'confidence: number }] }],', `${indent}tables: string[] }],\n`);
+    }
+    // navGroups icon (owned by `icons`) — only when navGroups is still present.
+    if (!active.has('icons') && !groupsOff) {
+        block = block
+            .split('label: L10n, icon: string, order: number,')
+            .join('label: L10n, order: number,');
+    }
+    return template.slice(0, startIdx) + block + template.slice(endIdx);
+}
+/**
+ * Split the decisions body into numbered blocks. A segment beginning `N.` starts
+ * a new block; any following non-numbered segment (defensive — the verbatim
+ * template has none) reattaches to the current block so an internal blank line
+ * would survive intact.
+ */
+function splitDecisionBlocks(body) {
+    const blocks = [];
+    for (const segment of body.split('\n\n')) {
+        const match = /^(\d+)\./.exec(segment);
+        if (match?.[1] !== undefined) {
+            blocks.push({ num: Number(match[1]), text: segment });
+            continue;
+        }
+        const last = blocks.at(-1);
+        if (last !== undefined)
+            last.text = `${last.text}\n\n${segment}`;
+    }
+    return blocks;
+}
+// ─── User-section rendering ──────────────────────────────────────────────────
+function renderUserSection(input, options, sections) {
+    const stubTables = new Set(input.chunk?.stubTables ?? []);
+    const schemaIr = serializeSchemaIr(input.schemaIr, { stubTables, stats: input.stats });
+    const statsJson = serializeStats(input.stats, { defaultSchema: input.schemaIr.defaultSchema });
+    const samplingBlock = serializeSampling(input.schemaIr, input.stats, input.sampling);
+    const chunkInfo = renderChunkInfo(input.chunk);
+    let user = applySectionToggles(PROMPT_V1_USER, sections);
+    user = replaceOnce(user, '{{RUN_ID}}', input.runId);
+    user = chunkInfo === '' ? user.replace('{{CHUNK_INFO}}\n', '') : replaceOnce(user, '{{CHUNK_INFO}}', chunkInfo);
+    user = replaceOnce(user, '{{REQUESTED_SECTIONS_LIST}}', `Requested: ${sections.join(', ')}`);
+    user = replaceOnce(user, '{{ALLOWED_PAGE_TEMPLATE_IDS_JSON}}', toPromptJson(options.allowed.templates));
+    user = replaceOnce(user, '{{ALLOWED_WIDGET_IDS_JSON}}', toPromptJson(options.allowed.widgets));
+    user = replaceOnce(user, '{{LOCALES_JSON}}', toPromptJson(input.locales));
+    user = replaceOnce(user, '{{SCHEMA_IR_JSON}}', toPromptJson(schemaIr));
+    user = replaceOnce(user, '{{STATS_JSON}}', toPromptJson(statsJson));
+    user = replaceOnce(user, '{{SAMPLING_BLOCK}}', samplingBlock);
+    return user;
+}
+/**
+ * Replace the first (and only) occurrence of `token` with a literal value. A
+ * function replacer is used so `$`-sequences inside injected JSON (`$&`, `$1`, …)
+ * are never interpreted as replacement patterns.
+ */
+function replaceOnce(text, token, value) {
+    return text.replace(token, () => value);
+}
+/** The `{{CHUNK_INFO}}` sentence for a chunked run; empty otherwise (§4.5, §5.2). */
+export function renderChunkInfo(chunk) {
+    if (chunk === undefined)
+        return '';
+    return (`This is chunk ${chunk.index} of ${chunk.total} of a larger schema. ` +
+        `Tables marked "stub": true belong to other chunks — use them as relation ` +
+        `context only. Skip decisions 2 and 7 unless this is chunk 1; a separate ` +
+        `merge step consolidates them.`);
+}
+// ─── Guards ──────────────────────────────────────────────────────────────────
+function requireEnUs(locales) {
+    if (!locales.includes('en_US')) {
+        throw new Error('buildPrompt: locales must include "en_US" (06-llm-assist.md §4.1).');
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/prompt/builder.js.map

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

package/dist/prompt/chunker.d.ts

@@ -0,0 +1,89 @@
+import type { DatabaseModel } from '@adminium/engine';
+import type { BuildPromptOptions, PromptChunk, PromptInput, RequestedSection } from './types.js';
+/** Per-chunk token ceiling (§4.5: "chunks of ≤ 45,000 tokens"). */
+export declare const DEFAULT_CHUNK_TOKEN_BUDGET = 45000;
+export interface ChunkPromptOptions extends BuildPromptOptions {
+    /** Per-chunk estimated-token ceiling (§4.5). Default {@link DEFAULT_CHUNK_TOKEN_BUDGET}. */
+    chunkTokenBudget?: number;
+}
+/** One planned chunk: which tables it owns in full and which it stubs (§4.5). */
+export interface SchemaChunk {
+    /** 1-based position. */
+    index: number;
+    /** Total chunk count for this plan. */
+    total: number;
+    /** Qualified ids of the tables this chunk owns in full, in model order. */
+    tableIds: string[];
+    /** Qualified ids of out-of-chunk FK targets rendered as `"stub": true`, sorted. */
+    stubTables: string[];
+}
+/**
+ * Result of {@link buildChunkedPrompts}: one {@link PromptChunk} per chunk plus
+ * the parallel {@link SchemaChunk} plan. `chunked` is `false` when the whole
+ * schema fit in a single prompt (one chunk, no stubs, no chunk-info sentence).
+ */
+export interface ChunkedPromptArtifact {
+    chunked: boolean;
+    chunks: PromptChunk[];
+    plan: SchemaChunk[];
+    sections: readonly RequestedSection[];
+}
+/**
+ * Partition the model's tables into FK-connected components. The graph is
+ * undirected over declared + inferred relations (both endpoints, and the join
+ * table for m2m) and column FK mirrors. Tables touched by no relation are
+ * singleton components. Each component is returned id-sorted, and the outer list
+ * is sorted by smallest member id — fully deterministic.
+ */
+export declare function clusterTables(model: DatabaseModel): string[][];
+/**
+ * Estimated token contribution of each full table to a prompt: its serialized
+ * schema-IR entry + any enum-column entries + declared relations it owns + its
+ * statistics entry + (opt-in) its sampling entry. Measured off the real
+ * serializers so it tracks the actual prompt bytes; a couple of tokens per
+ * fragment cover the surrounding commas.
+ */
+export declare function computeTableWeights(input: PromptInput): Map<string, number>;
+/** Estimated token cost of rendering a table as a names-only stub (§4.5). */
+export declare function computeStubWeights(model: DatabaseModel): Map<string, number>;
+/**
+ * The fixed per-chunk overhead (system section + full instruction template +
+ * allow-lists + locales + the chunk-info sentence + the empty structural JSON
+ * wrappers), measured by rendering a prompt for a table-less model. Every chunk
+ * repeats this cost regardless of how many tables it carries.
+ */
+export declare function computeOverheadTokens(input: PromptInput, options: ChunkPromptOptions): number;
+/**
+ * The out-of-chunk FK targets a chunk's full tables reference: the `to` (and
+ * join `through`) tables of every relation the chunk owns (relation `from` side
+ * is in the chunk), plus every column FK-mirror target — restricted to tables
+ * not in the chunk. These become the chunk's stub entries so no rendered
+ * relation or `references` points at a missing table.
+ */
+export declare function computeStubsForChunk(model: DatabaseModel, fullTables: ReadonlySet<string>): Set<string>;
+/**
+ * Partition a schema into map-phase chunks. FFD-packs whole FK clusters into
+ * chunks of ≤ `chunkTokenBudget`; any cluster too big for one chunk is split by
+ * table row-count descending. Every chunk records the out-of-chunk FK targets it
+ * must stub. Deterministic for a given (model, stats, options).
+ */
+export declare function planSchemaChunks(input: PromptInput, options: ChunkPromptOptions): SchemaChunk[];
+/**
+ * Build a self-contained sub-model for one chunk: its full tables plus its stub
+ * tables (rendered names-only by the serializer via the chunk's `stubTables`
+ * set), with enums narrowed to those the full tables reference and relations
+ * narrowed to those the chunk owns (`from` in the chunk, `to`/`through` present
+ * as full or stub).
+ */
+export declare function subModelForChunk(model: DatabaseModel, fullTables: ReadonlySet<string>, stubTables: ReadonlySet<string>): DatabaseModel;
+/**
+ * Build the map-phase prompt(s) for a schema. Split ONLY when the assembled user
+ * section exceeds the per-prompt `tokenBudget` (default 60,000 — §4.5); a schema
+ * that fits in one prompt is returned unchunked (no stubs, no chunk-info
+ * sentence) even when it is larger than the 45,000-token per-chunk packing
+ * ceiling. When it does not fit, it is chunked per {@link planSchemaChunks}, each
+ * chunk a self-contained prompt with correct FK stubs and each within
+ * `chunkTokenBudget`.
+ */
+export declare function buildChunkedPrompts(input: PromptInput, options: ChunkPromptOptions): ChunkedPromptArtifact;
+//# sourceMappingURL=chunker.d.ts.map

package/dist/prompt/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/prompt/chunker.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,kBAAkB,CAAC;AAUnE,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAqBjD,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACvC;AAaD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,EAAE,CA8C9D;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAyB3E;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAO5E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAc7F;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAkBvG;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,GAAG,WAAW,EAAE,CAsF/F;AAoBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,aAAa,CAuBf;AAUD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,kBAAkB,GAC1B,qBAAqB,CA8CvB"}