@adminiumjs/llm 0.1.0-rc.1

package/dist/response/schema.js

@@ -0,0 +1,191 @@
+/**
+ * `LlmResponseV1` — the one response contract shared by the direct-API and BYO
+ * paths (06-llm-assist.md §1, §6.1). Shipped verbatim from §6.1: field names
+ * and shapes are load-bearing — the golden fixtures in §6.3 and every
+ * downstream consumer (validate.ts, normalize.ts, diff.ts) depend on them.
+ *
+ * ONE intentional adaptation to Zod 4 is marked below (`L10n`): the doc's
+ * `z.record(LocaleCode, …)` cannot be used literally — in Zod 3 an enum-keyed
+ * record was partial, but in Zod 4 it is exhaustive (every enum key required),
+ * which would reject a 2-locale response (§6.3). Nor may the key be a strict
+ * enum: §7.2 stage 5 (`LLM_LOCALE_KEYS`) is the SOLE owner of locale-key
+ * validation, and it must be per-item — a single stray/non-canonical key (a
+ * BCP-47 'en-US', an unrequested 'pt_BR') must drop only that one suggestion,
+ * not fail the whole run at Zod (stage 4, fatal). So the key is typed
+ * `z.string()`: any string key parses here, and validate.ts checks the exact
+ * requested-locale set contextually (Zod alone can't know the run's locale list).
+ *
+ * Version negotiation (§4.3) is appended after the verbatim schema.
+ */
+import { z } from 'zod';
+export const SCHEMA_VERSION = 'adminium.llm/v1';
+export const SUPPORTED_SCHEMA_VERSIONS = [SCHEMA_VERSION];
+export const LOCALES = ['en_US', 'de_DE', 'ar_EG', 'zh_CN', 'zh_TW', 'cs_CZ', 'da_DK', 'fr_FR'];
+export const LocaleCode = z.enum(LOCALES);
+/** Localized text: keys must be exactly the run's requested locales — enforced
+ *  contextually in validate.ts stage 5 (Zod alone can't know the run's locale
+ *  list). The key schema is `z.string()`, NOT `LocaleCode`: a stray or
+ *  non-canonical locale key must be a per-item `LLM_LOCALE_KEYS` drop (stage 5),
+ *  never a fatal `LLM_SCHEMA_INVALID` at Zod (stage 4) that discards the whole
+ *  run. The value still enforces a non-empty string. */
+export const L10n = z.record(z.string(), z.string().min(1));
+export const Confidence = z.number().min(0).max(1);
+export const Tone = z.enum(['pos', 'warn', 'danger', 'accent', 'muted']);
+export const PiiKind = z.enum(['email', 'phone', 'name', 'address', 'gov-id', 'dob',
+    'financial', 'credentials', 'health', 'ip', 'location', 'other']);
+export const Masking = z.enum(['mask-email', 'mask-partial', 'last4', 'redact', 'hash', 'none']);
+export const Agg = z.enum(['count', 'sum', 'avg', 'min', 'max']);
+export const RelationKind = z.enum(['many-to-one', 'one-to-one', 'many-to-many-via']);
+const LucideIcon = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'kebab-case lucide icon name');
+const Slug = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+const Reason = z.string().min(1).max(200);
+export const PiiSuggestion = z.object({
+    kind: PiiKind, masking: Masking, reason: Reason, confidence: Confidence,
+});
+export const ColumnSuggestion = z.object({
+    column: z.string().min(1),
+    label: L10n,
+    description: L10n.optional(),
+    pii: PiiSuggestion.nullable().default(null),
+});
+export const PageTemplateSuggestion = z.object({
+    template: z.string().min(1), // membership in LLM_ALLOWED_TEMPLATES checked referentially
+    rank: z.number().int().min(1),
+    triggers: z.array(z.string()).min(1),
+    reason: Reason,
+    confidence: Confidence,
+});
+export const Microcopy = z.object({
+    emptyState: z.object({ headline: L10n, guidance: L10n }),
+    pageSubtitle: L10n,
+});
+export const TableSuggestion = z.object({
+    table: z.string().min(1), // qualified "schema.table"
+    confidence: Confidence,
+    label: L10n,
+    description: L10n,
+    icon: LucideIcon,
+    displayColumn: z.string().nullable(),
+    naturalKey: z.array(z.string().min(1)).min(1).nullable(),
+    pageTemplates: z.array(PageTemplateSuggestion).max(3).default([]),
+    microcopy: Microcopy.optional(),
+    columns: z.array(ColumnSuggestion).default([]),
+});
+export const EnumSuggestion = z.object({
+    table: z.string().min(1),
+    column: z.string().min(1),
+    kind: z.enum(['workflow', 'category']),
+    order: z.array(z.string()).nullable(), // permutation-checked referentially
+    terminal: z.array(z.string()).optional(),
+    tones: z.record(z.string(), Tone),
+    reason: Reason,
+    confidence: Confidence,
+});
+export const ConfirmedRelation = z.object({
+    fromTable: z.string(), fromColumns: z.array(z.string()).min(1),
+    toTable: z.string(), toColumns: z.array(z.string()).min(1),
+    semantics: z.string().max(120),
+    correct: z.boolean(),
+    confidence: Confidence,
+});
+export const InferredRelation = z.object({
+    fromTable: z.string(), fromColumns: z.array(z.string()).min(1),
+    toTable: z.string(), toColumns: z.array(z.string()).min(1),
+    kind: RelationKind,
+    viaTable: z.string().optional(),
+    evidence: Reason,
+    confidence: Confidence,
+});
+export const NavGroupSuggestion = z.object({
+    id: Slug,
+    label: L10n,
+    icon: LucideIcon,
+    order: z.number().int().min(0),
+    tables: z.array(z.string()).min(1),
+    confidence: Confidence,
+});
+export const WidgetSuggestion = z.object({
+    widget: z.string().min(1), // membership in LLM_ALLOWED_WIDGETS checked referentially
+    rank: z.number().int().min(1),
+    span: z.union([z.literal(3), z.literal(4), z.literal(6), z.literal(8), z.literal(12)]),
+    table: z.string().min(1),
+    metricColumn: z.string().optional(),
+    dimensionColumn: z.string().optional(),
+    timeColumn: z.string().optional(),
+    agg: Agg.optional(),
+    titleEn: z.string().max(60),
+    reason: Reason,
+    confidence: Confidence,
+});
+export const DashboardSuggestion = z.object({
+    id: Slug,
+    domain: z.string().max(40),
+    label: L10n,
+    order: z.number().int().min(0),
+    tables: z.array(z.string()).min(1),
+    widgets: z.array(WidgetSuggestion).max(8),
+});
+export const LlmResponseV1 = z.object({
+    schema_version: z.literal(SCHEMA_VERSION),
+    run_id: z.string().optional(),
+    error: z.string().optional(), // model-declared inability; if set, all else ignored
+    tables: z.array(TableSuggestion).default([]),
+    enums: z.array(EnumSuggestion).default([]),
+    relations: z.object({
+        confirmed: z.array(ConfirmedRelation).default([]),
+        inferred: z.array(InferredRelation).default([]),
+    }).default({ confirmed: [], inferred: [] }),
+    navGroups: z.array(NavGroupSuggestion).max(7).default([]),
+    dashboards: z.array(DashboardSuggestion).max(6).default([]),
+    notes: z.array(z.string().max(300)).max(5).optional(),
+}).strict();
+// ─── Version negotiation (§4.3) ──────────────────────────────────────────────
+/**
+ * Prompt-contract version. §4.3 colocates the authoritative constant in
+ * prompt/templates/v1.ts (06-T03); it is mirrored here so the response contract
+ * and its version negotiation are self-contained and need no cross-subdir
+ * import. Both must stay equal to `'adminium.prompt/v1.1'`.
+ *
+ * v1 → v1.1: the trigger-taxonomy `page-builder` row was removed from the §5.2
+ * user template (page-builder is `recommendable: false` and absent from
+ * `LLM_ALLOWED_TEMPLATES`; the taxonomy now matches the injected allowed list) —
+ * see prompt/templates/v1.ts. Wording-only; the response contract
+ * (`adminium.llm/v1`) is unchanged.
+ */
+export const PROMPT_VERSION = 'adminium.prompt/v1.1';
+/** Fatal code raised by stage 3 of the pipeline (§7.2) on an unknown contract. */
+export const VERSION_MISMATCH_CODE = 'LLM_VERSION_MISMATCH';
+/** Rendered verbatim in the paste UI when a response targets an unknown contract (§4.3). */
+export const VERSION_MISMATCH_HINT = 'Regenerate the prompt in Studio (Settings → AI) — this response was produced for an unsupported contract version.';
+/**
+ * Predicate: is `version` a contract version this build still validates?
+ *
+ * When v2 ships, v1 stays in {@link SUPPORTED_SCHEMA_VERSIONS} and keeps
+ * validating against the frozen v1 schema (§4.3) — a user may paste a response
+ * generated from a prompt downloaded weeks earlier. `supported` is injectable so
+ * that forward-compatibility (a supported-but-older version) is testable today.
+ */
+export function isSupportedSchemaVersion(version, supported = SUPPORTED_SCHEMA_VERSIONS) {
+    return typeof version === 'string' && supported.includes(version);
+}
+/**
+ * Negotiate a response's declared `schema_version` (§4.3): a supported version
+ * (including a supported-but-older one) resolves `ok`; anything else is a fatal
+ * rejection carrying `LLM_VERSION_MISMATCH` and the regeneration hint.
+ */
+export function negotiateSchemaVersion(version, supported = SUPPORTED_SCHEMA_VERSIONS) {
+    if (isSupportedSchemaVersion(version, supported)) {
+        return { ok: true, version };
+    }
+    const found = typeof version === 'string'
+        ? `"${version}"`
+        : 'a missing or non-string schema_version';
+    return {
+        ok: false,
+        code: VERSION_MISMATCH_CODE,
+        found: version,
+        message: `Unsupported schema_version (${found}). ${VERSION_MISMATCH_HINT}`,
+        hint: VERSION_MISMATCH_HINT,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/response/schema.js.map

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

package/dist/response/validate.d.ts

@@ -0,0 +1,29 @@
+import { type LlmValidationError } from './errors.js';
+import { type ReferentialContext } from './referential.js';
+import { LlmResponseV1 } from './schema.js';
+/**
+ * Everything {@link validateResponse} needs: the referential context (snapshot,
+ * locales, registry allow-lists) plus the stage-3 supported-version list and the
+ * stage-7 expected run id.
+ */
+export interface ValidationContext extends ReferentialContext {
+    /** Expected run id (the ULID embedded in the prompt). Enables the §7.2 stage-7 warning. */
+    runId?: string;
+    /** Override for `SUPPORTED_SCHEMA_VERSIONS` (testable forward-compat, §4.3). */
+    supportedVersions?: readonly string[];
+}
+export interface ValidationResult {
+    /** The cleaned, validated response — absent iff a fatal error stopped the run. */
+    response?: LlmResponseV1;
+    /** Fatal + per-item errors, most-actionable first within each stage. */
+    errors: LlmValidationError[];
+    /** Non-blocking notices (icon fallback, run-id mismatch). */
+    warnings: LlmValidationError[];
+}
+/**
+ * Validate a raw model reply against the run's snapshot and registries. Runs the
+ * full §7.2 pipeline; returns the cleaned response plus every error/warning with
+ * a precise JSON path. Never throws.
+ */
+export declare function validateResponse(rawText: string, ctx: ValidationContext): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/response/validate.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAkB,KAAK,kBAAkB,EAAa,MAAM,aAAa,CAAC;AACjF,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAA0B,MAAM,aAAa,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,wEAAwE;IACxE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAkF1F"}

package/dist/response/validate.js

@@ -0,0 +1,167 @@
+/**
+ * The staged validation pipeline (06-llm-assist.md §7.2).
+ *
+ *   1 extract   → recover the JSON object (fences/prose stripped, truncation
+ *                 detected)                                     — fatal
+ *   2 parse     → `JSON.parse`                                  — fatal
+ *   3 version   → `schema_version` supported; model-declared `error` key
+ *                                                               — fatal
+ *   4 zod       → `LlmResponseV1.safeParse`, issues mapped to paths — fatal
+ *   5 locale    → every localized object has exactly the run's locales — per-item
+ *   6 referential → §7.3 cross-checks vs the snapshot + registries — per-item
+ *   7 run-bind  → `run_id` present and ≠ ctx.runId                — warning
+ *
+ * Fatal errors reject the whole run (`response` is absent). Per-item errors drop
+ * only the offending suggestion (and its dependents) and let the rest through —
+ * `response` is the cleaned result. Warnings drop nothing.
+ *
+ * Browser-safe: only Zod + type-only engine imports flow through here.
+ */
+import { extractJsonObject } from './extract.js';
+import { formatJsonPath, makeError } from './errors.js';
+import { applyPrunes, createPrunes, mergePrunes, runReferentialChecks, } from './referential.js';
+import { LlmResponseV1, negotiateSchemaVersion } from './schema.js';
+/**
+ * Validate a raw model reply against the run's snapshot and registries. Runs the
+ * full §7.2 pipeline; returns the cleaned response plus every error/warning with
+ * a precise JSON path. Never throws.
+ */
+export function validateResponse(rawText, ctx) {
+    const warnings = [];
+    // ── Stage 1 — extract ──────────────────────────────────────────────────────
+    const extracted = extractJsonObject(rawText);
+    if (!extracted.ok)
+        return { errors: [extracted.error], warnings };
+    // ── Stage 2 — parse ────────────────────────────────────────────────────────
+    let parsed;
+    try {
+        parsed = JSON.parse(extracted.json);
+    }
+    catch (error) {
+        return {
+            errors: [makeError('LLM_JSON_PARSE', '', `The response is not valid JSON: ${messageOf(error)}`)],
+            warnings,
+        };
+    }
+    const record = typeof parsed === 'object' && parsed !== null ? parsed : {};
+    // ── Stage 3 — version + model-declared error ───────────────────────────────
+    const negotiation = negotiateSchemaVersion(record.schema_version, ctx.supportedVersions);
+    if (!negotiation.ok) {
+        return {
+            errors: [
+                makeError('LLM_VERSION_MISMATCH', 'schema_version', negotiation.message, {
+                    hint: negotiation.hint,
+                }),
+            ],
+            warnings,
+        };
+    }
+    if (typeof record.error === 'string' && record.error.length > 0) {
+        return {
+            errors: [
+                makeError('LLM_MODEL_DECLINED', 'error', `The model declined to produce enrichment: ${record.error}`),
+            ],
+            warnings,
+        };
+    }
+    // ── Stage 4 — Zod ──────────────────────────────────────────────────────────
+    const zod = LlmResponseV1.safeParse(parsed);
+    if (!zod.success) {
+        const errors = zod.error.issues.map((issue) => makeError('LLM_SCHEMA_INVALID', formatJsonPath(issue.path), issue.message));
+        return { errors, warnings };
+    }
+    const response = zod.data;
+    // ── Stage 5 — locale keys (per-item) ───────────────────────────────────────
+    const locale = checkLocales(response, ctx.locales);
+    // ── Stage 6 — referential (per-item) ───────────────────────────────────────
+    const referential = runReferentialChecks(response, ctx);
+    warnings.push(...referential.warnings);
+    const errors = [...locale.errors, ...referential.errors];
+    const cleaned = applyPrunes(response, mergePrunes(locale.prunes, referential.prunes));
+    // ── Stage 7 — run binding (warning) ────────────────────────────────────────
+    if (ctx.runId !== undefined &&
+        typeof cleaned.run_id === 'string' &&
+        cleaned.run_id !== ctx.runId) {
+        warnings.push(makeError('LLM_RUN_MISMATCH', 'run_id', 'This response looks like it was generated from a different prompt export.'));
+    }
+    return { response: cleaned, errors, warnings };
+}
+function localeKeysMatch(obj, expected) {
+    if (obj === undefined)
+        return true;
+    const keys = Object.keys(obj);
+    if (keys.length !== expected.size)
+        return false;
+    return keys.every((key) => expected.has(key));
+}
+function checkLocales(response, locales) {
+    const expected = new Set(locales);
+    const errors = [];
+    const prunes = createPrunes();
+    const localeMessage = (obj) => {
+        const found = Object.keys(obj);
+        return `Localized text must use exactly the requested locales [${[...expected].join(', ')}]; found [${found.join(', ')}]. The suggestion was discarded.`;
+    };
+    response.tables.forEach((table, i) => {
+        if (!localeKeysMatch(table.label, expected)) {
+            errors.push(makeError('LLM_LOCALE_KEYS', `tables[${i}].label`, localeMessage(table.label)));
+            prunes.tables.add(i);
+            return;
+        }
+        if (!localeKeysMatch(table.description, expected)) {
+            errors.push(makeError('LLM_LOCALE_KEYS', `tables[${i}].description`, localeMessage(table.description)));
+            prunes.tables.add(i);
+            return;
+        }
+        table.columns.forEach((column, j) => {
+            if (!localeKeysMatch(column.label, expected)) {
+                errors.push(makeError('LLM_LOCALE_KEYS', `tables[${i}].columns[${j}].label`, localeMessage(column.label)));
+                addColumnDrop(prunes, i, j);
+                return;
+            }
+            if (column.description !== undefined && !localeKeysMatch(column.description, expected)) {
+                errors.push(makeError('LLM_LOCALE_KEYS', `tables[${i}].columns[${j}].description`, localeMessage(column.description)));
+                addColumnDrop(prunes, i, j);
+            }
+        });
+        const microcopy = table.microcopy;
+        if (microcopy) {
+            const micro = [
+                [microcopy.emptyState.headline, `tables[${i}].microcopy.emptyState.headline`],
+                [microcopy.emptyState.guidance, `tables[${i}].microcopy.emptyState.guidance`],
+                [microcopy.pageSubtitle, `tables[${i}].microcopy.pageSubtitle`],
+            ];
+            for (const [obj, path] of micro) {
+                if (!localeKeysMatch(obj, expected)) {
+                    errors.push(makeError('LLM_LOCALE_KEYS', path, localeMessage(obj)));
+                    prunes.dropMicrocopy.add(i);
+                    break;
+                }
+            }
+        }
+    });
+    response.navGroups.forEach((group, i) => {
+        if (!localeKeysMatch(group.label, expected)) {
+            errors.push(makeError('LLM_LOCALE_KEYS', `navGroups[${i}].label`, localeMessage(group.label)));
+            prunes.navGroups.add(i);
+        }
+    });
+    response.dashboards.forEach((dashboard, i) => {
+        if (!localeKeysMatch(dashboard.label, expected)) {
+            errors.push(makeError('LLM_LOCALE_KEYS', `dashboards[${i}].label`, localeMessage(dashboard.label)));
+            prunes.dashboards.add(i);
+        }
+    });
+    return { errors, prunes };
+}
+function addColumnDrop(prunes, tableIndex, columnIndex) {
+    const set = prunes.columns.get(tableIndex);
+    if (set)
+        set.add(columnIndex);
+    else
+        prunes.columns.set(tableIndex, new Set([columnIndex]));
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=validate.js.map

package/dist/response/validate.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared `@adminium/llm` contract types (06-llm-assist.md §2, §7.1): the
+ * normalized `EnrichmentSet` both paths reduce to, the provider identifiers, and
+ * the run status machine.
+ *
+ * Browser-safe: this module imports only pure-Zod / pure-TS types. The engine
+ * reference is a type-only re-export (erased at build time) so no DB-driver code
+ * can reach `@adminium/dashboard` through here.
+ */
+import { z } from 'zod';
+import type { ConfirmedRelation, DashboardSuggestion, EnumSuggestion, InferredRelation, LocaleCode, Microcopy, NavGroupSuggestion, PiiSuggestion } from './response/schema.js';
+/**
+ * The classified schema IR a run is built, validated and normalized against
+ * (05-introspection-engine.md). Re-exported here so every `@adminium/llm`
+ * module names the model from one place; the referential checks (§7.3) and the
+ * heuristic→EnrichmentSet normalizer both consume it. Type-only: no runtime edge
+ * to `@adminium/engine`, keeping this package browser-safe.
+ */
+export type { DatabaseModel } from '@adminium/engine';
+export declare const PROVIDER_IDS: readonly ["anthropic", "openai", "openai-compatible", "ollama", "adminium-managed"];
+export declare const providerIdSchema: z.ZodEnum<{
+    anthropic: "anthropic";
+    openai: "openai";
+    "openai-compatible": "openai-compatible";
+    ollama: "ollama";
+    "adminium-managed": "adminium-managed";
+}>;
+export type ProviderId = z.infer<typeof providerIdSchema>;
+/**
+ * `adminium_llm_runs.status` states. Transitions (§7.4):
+ *   draft → running | awaiting_response
+ *   running | awaiting_response → validated | failed | discarded
+ *   validated → applied | partially_applied | discarded
+ *   applied | partially_applied | failed | discarded → (terminal)
+ */
+export declare const LLM_RUN_STATUSES: readonly ["draft", "running", "awaiting_response", "validated", "applied", "partially_applied", "failed", "discarded"];
+export declare const llmRunStatusSchema: z.ZodEnum<{
+    draft: "draft";
+    running: "running";
+    awaiting_response: "awaiting_response";
+    validated: "validated";
+    applied: "applied";
+    partially_applied: "partially_applied";
+    failed: "failed";
+    discarded: "discarded";
+}>;
+export type LlmRunStatus = z.infer<typeof llmRunStatusSchema>;
+/** States a run can never leave (§7.4: "Runs are immutable after `applied`"). */
+export declare const TERMINAL_LLM_RUN_STATUSES: readonly ["applied", "partially_applied", "failed", "discarded"];
+export declare function isTerminalRunStatus(status: LlmRunStatus): boolean;
+/** One table's normalized enrichment (labels, keys, templates, micro-copy, per-column). */
+export interface EnrichmentTable {
+    label: Partial<Record<LocaleCode, string>>;
+    description?: Partial<Record<LocaleCode, string>>;
+    icon?: string;
+    displayColumn?: string | null;
+    naturalKey?: string[] | null;
+    templates: {
+        template: string;
+        rank: number;
+        reason?: string;
+        confidence: number;
+    }[];
+    microcopy?: Microcopy;
+    columns: Record<string, {
+        label: Partial<Record<LocaleCode, string>>;
+        description?: Partial<Record<LocaleCode, string>>;
+        pii?: PiiSuggestion | null;
+    }>;
+    /** heuristic entries use fixed 0.5. */
+    confidence: number;
+}
+/**
+ * The normalized enrichment both the heuristic baseline (from `@adminium/engine`)
+ * and a validated `LlmResponseV1` reduce to, so they diff field-by-field (§7.1).
+ * `tables` is keyed by `"schema.table"`; `enums` by `"schema.table.column"`.
+ */
+export interface EnrichmentSet {
+    source: 'heuristic' | 'llm';
+    llmRunId?: string;
+    tables: Record<string, EnrichmentTable>;
+    enums: Record<string, EnumSuggestion>;
+    inferredRelations: InferredRelation[];
+    /**
+     * Confirmed relations the LLM REJECTS (`correct: false`) — a declared FK it
+     * wants suppressed (§8.3 `relation_suppressed`). Carried so the diff can raise
+     * a `rejects-heuristic` row a human must confirm (§8.2, acceptance criterion
+     * 12); an accepted one never enters a confidence-gated bulk set. The heuristic
+     * baseline never populates this (it accepts every declared FK).
+     */
+    suppressedRelations: ConfirmedRelation[];
+    navGroups: NavGroupSuggestion[];
+    dashboards: DashboardSuggestion[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,eAAO,MAAM,YAAY,qFAMf,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;;;EAAuB,CAAC;AACrD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,wHASnB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;;;;EAA2B,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,kEAKM,CAAC;AAE7C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEjE;AAID,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;QACE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QAC3C,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,GAAG,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;KAC5B,CACF,CAAC;IACF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,GAAG,KAAK,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,mBAAmB,EAAE,iBAAiB,EAAE,CAAC;IACzC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,49 @@
+/**
+ * Shared `@adminium/llm` contract types (06-llm-assist.md §2, §7.1): the
+ * normalized `EnrichmentSet` both paths reduce to, the provider identifiers, and
+ * the run status machine.
+ *
+ * Browser-safe: this module imports only pure-Zod / pure-TS types. The engine
+ * reference is a type-only re-export (erased at build time) so no DB-driver code
+ * can reach `@adminium/dashboard` through here.
+ */
+import { z } from 'zod';
+// ─── Provider identity (§3.1) ────────────────────────────────────────────────
+export const PROVIDER_IDS = [
+    'anthropic',
+    'openai',
+    'openai-compatible',
+    'ollama',
+    'adminium-managed',
+];
+export const providerIdSchema = z.enum(PROVIDER_IDS);
+// ─── Run status machine (§7.4) ───────────────────────────────────────────────
+/**
+ * `adminium_llm_runs.status` states. Transitions (§7.4):
+ *   draft → running | awaiting_response
+ *   running | awaiting_response → validated | failed | discarded
+ *   validated → applied | partially_applied | discarded
+ *   applied | partially_applied | failed | discarded → (terminal)
+ */
+export const LLM_RUN_STATUSES = [
+    'draft',
+    'running',
+    'awaiting_response',
+    'validated',
+    'applied',
+    'partially_applied',
+    'failed',
+    'discarded',
+];
+export const llmRunStatusSchema = z.enum(LLM_RUN_STATUSES);
+/** States a run can never leave (§7.4: "Runs are immutable after `applied`"). */
+export const TERMINAL_LLM_RUN_STATUSES = [
+    'applied',
+    'partially_applied',
+    'failed',
+    'discarded',
+];
+export function isTerminalRunStatus(status) {
+    return TERMINAL_LLM_RUN_STATUSES.includes(status);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW;IACX,QAAQ;IACR,mBAAmB;IACnB,QAAQ;IACR,kBAAkB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAGrD,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,SAAS;IACT,mBAAmB;IACnB,WAAW;IACX,SAAS;IACT,mBAAmB;IACnB,QAAQ;IACR,WAAW;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AAG3D,iFAAiF;AACjF,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS;IACT,mBAAmB;IACnB,QAAQ;IACR,WAAW;CAC+B,CAAC;AAE7C,MAAM,UAAU,mBAAmB,CAAC,MAAoB;IACtD,OAAQ,yBAAqD,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjF,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@adminiumjs/llm",
+  "version": "0.1.0-rc.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoSofi/Adminium.git",
+    "directory": "packages/llm"
+  },
+  "homepage": "https://adminium.dev",
+  "bugs": "https://github.com/MoSofi/Adminium/issues",
+  "type": "module",
+  "description": "LLM assist: provider clients, prompt builder, BYO round-trip",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@adminium/engine": "npm:@adminiumjs/engine@0.1.0-rc.1",
+    "@adminium/widgets": "npm:@adminiumjs/widgets@0.1.0-rc.1",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "dist"
+  ]
+}