@skmtc/core 0.0.983 → 0.16.1

package/script/types/Enrichments.d.ts

@@ -1,210 +1,171 @@
 /**
- * @fileoverview Enrichment System for SKMTC Core
- *
- * This module provides comprehensive enrichment types and schemas for enhancing
- * OpenAPI operations with UI generation metadata. Enrichments allow generators
- * to create forms, tables, inputs, and other UI components with rich metadata
- * about how data should be presented and interacted with.
- *
- * The enrichment system supports a hierarchical structure:
- * Generator → Path → Method → Operation → Component Type (form/table/input)
- *
- * ## Key Features
- *
- * - **Form Enrichments**: Field definitions with inputs, labels, and validation
- * - **Table Enrichments**: Column definitions with formatters and headers
- * - **Input Enrichments**: Standalone input components with formatting
- * - **Hierarchical Organization**: Nested structure for easy lookup and management
- * - **Type Safety**: Comprehensive Valibot validation for all enrichment data
- *
- * @example Basic form enrichment
- * ```typescript
- * import type { FormItem } from '@skmtc/core/Enrichments';
- *
- * const userForm: FormItem = {
- *   title: 'User Registration',
- *   description: 'Create a new user account',
- *   fields: [
- *     {
- *       id: 'name',
- *       accessorPath: ['name'],
- *       input: { moduleName: 'TextInput', exportName: 'default' },
- *       label: 'Full Name',
- *       placeholder: 'Enter your full name'
- *     }
- *   ],
- *   submitLabel: 'Create Account'
- * };
- * ```
- *
- * @example Table enrichment with formatters
- * ```typescript
- * import type { TableItem } from '@skmtc/core/Enrichments';
- *
- * const userTable: TableItem = {
- *   title: 'User Directory',
- *   columns: [
- *     {
- *       id: 'email',
- *       accessorPath: ['email'],
- *       formatter: { moduleName: 'EmailFormatter', exportName: 'default' },
- *       label: 'Email Address'
- *     }
- *   ]
- * };
+ * @fileoverview Enrichment hierarchy for SKMTC Core.
+ *
+ * Core owns only the lookup *hierarchy* — the keys that locate an
+ * enrichment payload for a generator + operation/model:
+ *
+ *   - **Models** are keyed by name (component schema name in OAS;
+ *     registry-named type in GraphQL).
+ *   - **OAS operations** are keyed by HTTP path → method.
+ *   - **GraphQL operations** are keyed by root kind → field name.
+ *
+ * The leaf at the bottom of each hierarchy is opaque to core — its
+ * shape is owned by the generator that consumes it. Each generator
+ * declares its own enrichment schema via the `toEnrichmentSchema`
+ * configuration on its entry factory; the dispatcher parses the
+ * generator's slice of the enrichments record through that schema
+ * before handing typed enrichments to `transform`.
+ *
+ * This means **no leaf shapes live in core**. A generator adding a
+ * new enrichment field is a purely local change — no coordinated
+ * core update, no canonical schema to extend. Two generators with
+ * different needs at the same operation can declare different leaf
+ * shapes and they don't collide.
+ *
+ * @example A generator declaring its own leaf shape
+ * ```ts
+ * // gen-myform/src/enrichments.ts
+ * import * as v from 'valibot'
+ *
+ * const enrichmentSchema = v.optional(v.object({
+ *   title: v.optional(v.string()),
+ *   submitLabel: v.optional(v.string()),
+ *   fields: v.optional(v.array(v.object({
+ *     id: v.string(),
+ *     label: v.optional(v.string())
+ *   })))
+ * }))
+ *
+ * export type EnrichmentSchema = v.InferOutput<typeof enrichmentSchema>
+ * export const toEnrichmentSchema = () => enrichmentSchema
  * ```
  *
  * @module Enrichments
  */
-import { type ModuleExport } from './ModuleExport.js';
+import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 /**
- * Valibot schema for form field items.
- *
- * Validates individual form field configurations including input components,
- * labels, placeholders, and data access paths.
+ * Generator-owned enrichment payload at a hierarchy leaf. Core treats
+ * it as opaque; the consuming generator parses it through its own
+ * `toEnrichmentSchema()`.
  */
-export declare const formFieldItem: v.GenericSchema<FormFieldItem>;
+export type EnrichmentLeaf = unknown;
 /**
- * Configuration for a single form field.
+ * Model enrichments: schema name → leaf payload.
  *
- * Defines how a form field should be rendered, including its input component,
- * label text, data binding path, and optional placeholder text.
+ * Used by `toModelEntry`-shaped generators (TS types, Zod validators,
+ * mappers, etc.).
  */
-export type FormFieldItem = {
-    id: string;
-    accessorPath: string[];
-    input: ModuleExport;
-    label: string;
-    placeholder?: string;
-};
+export type ModelEnrichments = Record<string, EnrichmentLeaf>;
+export declare const modelEnrichments: v.GenericSchema<ModelEnrichments>;
 /**
- * Valibot schema for form configurations.
- *
- * Validates complete form definitions including title, description,
- * field configurations, and submit button labels.
+ * OAS method enrichments: HTTP method (`get`, `post`, ...) → leaf payload.
  */
-export declare const formItem: v.GenericSchema<FormItem>;
+export type OasMethodEnrichments = Record<string, EnrichmentLeaf>;
+export declare const oasMethodEnrichments: v.GenericSchema<OasMethodEnrichments>;
 /**
- * Configuration for a complete form.
- *
- * Represents a form with optional title, description, field definitions,
- * and customizable submit button label.
+ * OAS path enrichments: path template → method enrichments.
  */
-export type FormItem = {
-    title?: string;
-    description?: string;
-    fields?: FormFieldItem[];
-    submitLabel?: string;
-};
+export type OasPathEnrichments = Record<string, OasMethodEnrichments>;
+export declare const oasPathEnrichments: v.GenericSchema<OasPathEnrichments>;
 /**
- * Valibot schema for table column items.
- *
- * Validates table column configurations including formatter components,
- * labels, and data access paths.
+ * GraphQL field enrichments: root field name → leaf payload.
  */
-export declare const tableColumnItem: v.GenericSchema<TableColumnItem>;
+export type GqlFieldEnrichments = Record<string, EnrichmentLeaf>;
+export declare const gqlFieldEnrichments: v.GenericSchema<GqlFieldEnrichments>;
 /**
- * Configuration for a single table column.
- *
- * Defines how a table column should be rendered, including its formatter
- * component, display label, and data binding path.
+ * GraphQL root-kind enrichments: `query` / `mutation` / `subscription`
+ * → field enrichments.
  */
-export type TableColumnItem = {
-    id: string;
-    accessorPath: string[];
-    formatter: ModuleExport;
-    label: string;
-};
+export type GqlRootKindEnrichments = Record<string, GqlFieldEnrichments>;
+export declare const gqlRootKindEnrichments: v.GenericSchema<GqlRootKindEnrichments>;
 /**
- * Valibot schema for table configurations.
- *
- * Validates complete table definitions including title, description,
- * and column configurations.
+ * Reserved enrichment key for the **stack** scope. Lives at the top
+ * level of the enrichments record (a sibling of the generator-id keys);
+ * its value is a single leaf shared across every generator in the
+ * composition. Read via `toStackEnrichment(context, schema)`.
  */
-export declare const tableItem: v.GenericSchema<TableItem>;
+export declare const STACK_ENRICHMENT_KEY = "_stack";
 /**
- * Configuration for a complete table.
- *
- * Represents a table with optional title, description, and column definitions.
+ * Reserved enrichment key for the **generator** scope. Lives inside a
+ * generator's slot (a sibling of the subject keys); its value is a
+ * run-constant leaf for that one generator. Read via
+ * `toGeneratorEnrichment(context, id, schema)`.
  */
-export type TableItem = {
-    title?: string;
-    description?: string;
-    columns?: TableColumnItem[];
-};
+export declare const GENERATOR_ENRICHMENT_KEY = "_generator";
 /**
- * Valibot schema for input items.
- *
- * Validates input component configurations including formatter components
- * and data access paths.
+ * Whether an enrichment key is **engine-reserved** rather than
+ * customer-defined. Every reserved key is `_`-prefixed; customer keys
+ * (generator ids, subject names) must not be. This single predicate is
+ * the source of truth for every iteration site that must skip reserved
+ * keys — generators never iterate enrichments themselves (they read by
+ * known key through the typed helpers), so the segregation is a core /
+ * migration concern only.
  */
-export declare const inputItem: v.GenericSchema<InputItem>;
+export declare const isReservedEnrichmentKey: (key: string) => boolean;
 /**
- * Configuration for a single input component.
+ * Top-level enrichments: generator id → hierarchy, plus the reserved
+ * `_stack` key (stack-scoped leaf). Each generator's slot is one of
+ * three structurally-distinct hierarchies depending on the generator's
+ * entry kind:
+ *  - `ModelEnrichments` for `toModelEntry`
+ *  - `OasPathEnrichments` for `toOasOperationEntry`
+ *  - `GqlRootKindEnrichments` for `toGqlOperationEntry`
  *
- * Defines how an input should be rendered, including its formatter
- * component and data binding path.
- */
-export type InputItem = {
-    id: string;
-    accessorPath: string[];
-    formatter: ModuleExport;
-};
-/**
- * Valibot schema for operation-level enrichments.
+ * Each slot may additionally carry the reserved `_generator` key
+ * (generator-scoped leaf) alongside its subject keys. The dispatcher
+ * knows which hierarchy applies from the generator's declared entry
+ * type; the union is the wire format.
  *
- * Validates enrichment configurations that can be applied to OpenAPI operations,
- * including table, form, and input component definitions.
+ * **Reserved-key rule** (enforced by {@link generatorEnrichments}):
+ * customer keys — generator ids at the top level, subject names inside a
+ * slot — must not start with `_`. The only reserved keys are
+ * {@link STACK_ENRICHMENT_KEY} (top level) and
+ * {@link GENERATOR_ENRICHMENT_KEY} (per-generator slot).
  */
-export declare const operationEnrichments: v.GenericSchema<OperationEnrichments>;
+export type GeneratorEnrichments = Record<string, ModelEnrichments | OasPathEnrichments | GqlRootKindEnrichments>;
+export declare const generatorEnrichments: v.GenericSchema<GeneratorEnrichments>;
 /**
- * Enrichment configurations for a single OpenAPI operation.
- *
- * Contains optional table, form, and input configurations that can enhance
- * how an operation is presented and interacted with in generated UIs.
- */
-export type OperationEnrichments = {
-    table?: TableItem;
-    form?: FormItem;
-    input?: InputItem;
+ * The structural CONSTRAINT a generator's enrichment umbrella type must
+ * satisfy: the three scopes, each optional and opaque to core. Used to
+ * constrain the projection chain's single `EnrichmentType` generic
+ * (`EnrichmentType extends EnrichmentScopes`) wherever a member scope is
+ * indexed (`EnrichmentType['subject']`). `ContentSettings` / `Inserted` stay
+ * unconstrained — they only carry the umbrella, never index it.
+ */
+export type EnrichmentScopes = {
+    subject?: unknown;
+    generator?: unknown;
+    stack?: unknown;
 };
 /**
- * Valibot schema for HTTP method-level enrichments.
- *
- * Maps HTTP methods (GET, POST, etc.) to their operation enrichment configurations.
- */
-export declare const methodEnrichments: v.GenericSchema<MethodEnrichments>;
-/**
- * HTTP method to operation enrichments mapping.
- *
- * Associates HTTP methods with their corresponding operation enrichment configurations.
- */
-export type MethodEnrichments = Record<string, OperationEnrichments>;
-/**
- * Valibot schema for API path-level enrichments.
- *
- * Maps API paths to their method enrichment configurations.
- */
-export declare const pathEnrichments: v.GenericSchema<PathEnrichments>;
-/**
- * API path to method enrichments mapping.
- *
- * Associates API paths with their corresponding method enrichment configurations.
- */
-export type PathEnrichments = Record<string, MethodEnrichments>;
-/**
- * Valibot schema for generator-level enrichments.
- *
- * Maps generator IDs to their path enrichment configurations,
- * creating a complete hierarchy of enrichment data.
- */
-export declare const generatorEnrichments: v.GenericSchema<GeneratorEnrichments>;
+ * The `{ subject, generator, stack }` umbrella carried on
+ * `ContentSettings.enrichments`. Each member is the generator-owned leaf for
+ * that scope at a different key-depth in `client.json#settings.enrichments`:
+ *
+ *  - **subject** — `[id][subject][variant]`, resolved per item (the original
+ *    per-subject enrichment).
+ *  - **generator** — `[id]._generator`, a run-constant for one generator.
+ *  - **stack** — `._stack`, a run-constant shared across every generator.
+ *
+ * A member is `undefined` when the generator declares nothing for that scope.
+ * Assembled by `static toEnrichments` (raw from the three storage spots, then
+ * parsed through the generator's composite `toEnrichmentSchema`). The single
+ * `EnrichmentType` generic on the projection chain now *means* this umbrella —
+ * no new type parameters; the chain stays single-param.
+ */
+export type Enrichments<Subject = undefined, Generator = undefined, Stack = undefined> = {
+    subject: Subject;
+    generator: Generator;
+    stack: Stack;
+};
 /**
- * Generator ID to path enrichments mapping.
- *
- * Top-level enrichment structure that organizes enrichment data by generator,
- * then by path, then by HTTP method, providing complete enrichment hierarchies.
+ * The composite enrichment schema a generator with NO enrichments at any scope
+ * declares (`toEnrichmentSchema: () => emptyEnrichmentSchema`). Every member is
+ * `v.undefined()` — strict: a no-enrichment generator that somehow receives a
+ * value fails loud (fail-open at the call site) rather than silently swallowing
+ * it.
  */
-export type GeneratorEnrichments = Record<string, PathEnrichments>;
+export declare const emptyEnrichmentSchema: v.GenericSchema<Enrichments<undefined, undefined, undefined>>;
+export type EmptyEnrichments = v.InferOutput<typeof emptyEnrichmentSchema>;
 //# sourceMappingURL=Enrichments.d.ts.map

package/script/types/Enrichments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Enrichments.d.ts","sourceRoot":"","sources":["../../src/types/Enrichments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAMvD,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,KAAK,EAAE,YAAY,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,CAAC,aAAa,CAAC,QAAQ,CAK7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,aAAa,CAAC,eAAe,CAK3D,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,SAAS,EAAE,YAAY,CAAA;IACvB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAI/C,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;CAC5B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAI/C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,SAAS,EAAE,YAAY,CAAA;CACxB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,aAAa,CAAC,oBAAoB,CAIrE,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAA8C,CAAA;AAE/G;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,aAAa,CAAC,eAAe,CAA2C,CAAA;AAExG;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,aAAa,CAAC,oBAAoB,CAAyC,CAAA;AAEhH;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA"}
+{"version":3,"file":"Enrichments.d.ts","sourceRoot":"","sources":["../../src/types/Enrichments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;AAE7D,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,aAAa,CAAC,gBAAgB,CAAqC,CAAA;AAEpG;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;AAEjE,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,aAAa,CAAC,oBAAoB,CAGtE,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;AAErE,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,aAAa,CAAC,kBAAkB,CAGlE,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;AAEhE,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,aAAa,CAAC,mBAAmB,CAGpE,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;AAExE,eAAO,MAAM,sBAAsB,EAAE,CAAC,CAAC,aAAa,CAAC,sBAAsB,CAG1E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAA;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,KAAG,OAA8B,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CACvC,MAAM,EACN,gBAAgB,GAAG,kBAAkB,GAAG,sBAAsB,CAC/D,CAAA;AAED,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,aAAa,CAAC,oBAAoB,CAiCtE,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,GAAG,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,KAAK,GAAG,SAAS,IAAI;IACvF,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAK5F,CAAA;AAEJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA"}

package/script/types/Enrichments.js

@@ -1,62 +1,4 @@
 "use strict";
-/**
- * @fileoverview Enrichment System for SKMTC Core
- *
- * This module provides comprehensive enrichment types and schemas for enhancing
- * OpenAPI operations with UI generation metadata. Enrichments allow generators
- * to create forms, tables, inputs, and other UI components with rich metadata
- * about how data should be presented and interacted with.
- *
- * The enrichment system supports a hierarchical structure:
- * Generator → Path → Method → Operation → Component Type (form/table/input)
- *
- * ## Key Features
- *
- * - **Form Enrichments**: Field definitions with inputs, labels, and validation
- * - **Table Enrichments**: Column definitions with formatters and headers
- * - **Input Enrichments**: Standalone input components with formatting
- * - **Hierarchical Organization**: Nested structure for easy lookup and management
- * - **Type Safety**: Comprehensive Valibot validation for all enrichment data
- *
- * @example Basic form enrichment
- * ```typescript
- * import type { FormItem } from '@skmtc/core/Enrichments';
- *
- * const userForm: FormItem = {
- *   title: 'User Registration',
- *   description: 'Create a new user account',
- *   fields: [
- *     {
- *       id: 'name',
- *       accessorPath: ['name'],
- *       input: { moduleName: 'TextInput', exportName: 'default' },
- *       label: 'Full Name',
- *       placeholder: 'Enter your full name'
- *     }
- *   ],
- *   submitLabel: 'Create Account'
- * };
- * ```
- *
- * @example Table enrichment with formatters
- * ```typescript
- * import type { TableItem } from '@skmtc/core/Enrichments';
- *
- * const userTable: TableItem = {
- *   title: 'User Directory',
- *   columns: [
- *     {
- *       id: 'email',
- *       accessorPath: ['email'],
- *       formatter: { moduleName: 'EmailFormatter', exportName: 'default' },
- *       label: 'Email Address'
- *     }
- *   ]
- * };
- * ```
- *
- * @module Enrichments
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -91,95 +33,120 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generatorEnrichments = exports.pathEnrichments = exports.methodEnrichments = exports.operationEnrichments = exports.inputItem = exports.tableItem = exports.tableColumnItem = exports.formItem = exports.formFieldItem = void 0;
-const ModuleExport_js_1 = require("./ModuleExport.js");
-const v = __importStar(require("valibot"));
-/**
- * Valibot schema for form field items.
- *
- * Validates individual form field configurations including input components,
- * labels, placeholders, and data access paths.
- */
-exports.formFieldItem = v.object({
-    id: v.string(),
-    accessorPath: v.array(v.string()),
-    input: ModuleExport_js_1.moduleExport,
-    label: v.string(),
-    placeholder: v.optional(v.string())
-});
+exports.emptyEnrichmentSchema = exports.generatorEnrichments = exports.isReservedEnrichmentKey = exports.GENERATOR_ENRICHMENT_KEY = exports.STACK_ENRICHMENT_KEY = exports.gqlRootKindEnrichments = exports.gqlFieldEnrichments = exports.oasPathEnrichments = exports.oasMethodEnrichments = exports.modelEnrichments = void 0;
 /**
- * Valibot schema for form configurations.
+ * @fileoverview Enrichment hierarchy for SKMTC Core.
+ *
+ * Core owns only the lookup *hierarchy* — the keys that locate an
+ * enrichment payload for a generator + operation/model:
+ *
+ *   - **Models** are keyed by name (component schema name in OAS;
+ *     registry-named type in GraphQL).
+ *   - **OAS operations** are keyed by HTTP path → method.
+ *   - **GraphQL operations** are keyed by root kind → field name.
+ *
+ * The leaf at the bottom of each hierarchy is opaque to core — its
+ * shape is owned by the generator that consumes it. Each generator
+ * declares its own enrichment schema via the `toEnrichmentSchema`
+ * configuration on its entry factory; the dispatcher parses the
+ * generator's slice of the enrichments record through that schema
+ * before handing typed enrichments to `transform`.
+ *
+ * This means **no leaf shapes live in core**. A generator adding a
+ * new enrichment field is a purely local change — no coordinated
+ * core update, no canonical schema to extend. Two generators with
+ * different needs at the same operation can declare different leaf
+ * shapes and they don't collide.
+ *
+ * @example A generator declaring its own leaf shape
+ * ```ts
+ * // gen-myform/src/enrichments.ts
+ * import * as v from 'valibot'
+ *
+ * const enrichmentSchema = v.optional(v.object({
+ *   title: v.optional(v.string()),
+ *   submitLabel: v.optional(v.string()),
+ *   fields: v.optional(v.array(v.object({
+ *     id: v.string(),
+ *     label: v.optional(v.string())
+ *   })))
+ * }))
+ *
+ * export type EnrichmentSchema = v.InferOutput<typeof enrichmentSchema>
+ * export const toEnrichmentSchema = () => enrichmentSchema
+ * ```
  *
- * Validates complete form definitions including title, description,
- * field configurations, and submit button labels.
+ * @module Enrichments
  */
-exports.formItem = v.object({
-    title: v.optional(v.string()),
-    description: v.optional(v.string()),
-    fields: v.optional(v.array(exports.formFieldItem)),
-    submitLabel: v.optional(v.string())
-});
+require("../_dnt.polyfills.js");
+const v = __importStar(require("valibot"));
+exports.modelEnrichments = v.record(v.string(), v.unknown());
+exports.oasMethodEnrichments = v.record(v.string(), v.unknown());
+exports.oasPathEnrichments = v.record(v.string(), exports.oasMethodEnrichments);
+exports.gqlFieldEnrichments = v.record(v.string(), v.unknown());
+exports.gqlRootKindEnrichments = v.record(v.string(), exports.gqlFieldEnrichments);
 /**
- * Valibot schema for table column items.
- *
- * Validates table column configurations including formatter components,
- * labels, and data access paths.
+ * Reserved enrichment key for the **stack** scope. Lives at the top
+ * level of the enrichments record (a sibling of the generator-id keys);
+ * its value is a single leaf shared across every generator in the
+ * composition. Read via `toStackEnrichment(context, schema)`.
  */
-exports.tableColumnItem = v.object({
-    id: v.string(),
-    accessorPath: v.array(v.string()),
-    formatter: ModuleExport_js_1.moduleExport,
-    label: v.string()
-});
+exports.STACK_ENRICHMENT_KEY = '_stack';
 /**
- * Valibot schema for table configurations.
- *
- * Validates complete table definitions including title, description,
- * and column configurations.
+ * Reserved enrichment key for the **generator** scope. Lives inside a
+ * generator's slot (a sibling of the subject keys); its value is a
+ * run-constant leaf for that one generator. Read via
+ * `toGeneratorEnrichment(context, id, schema)`.
  */
-exports.tableItem = v.object({
-    title: v.optional(v.string()),
-    description: v.optional(v.string()),
-    columns: v.optional(v.array(exports.tableColumnItem))
-});
+exports.GENERATOR_ENRICHMENT_KEY = '_generator';
 /**
- * Valibot schema for input items.
- *
- * Validates input component configurations including formatter components
- * and data access paths.
+ * Whether an enrichment key is **engine-reserved** rather than
+ * customer-defined. Every reserved key is `_`-prefixed; customer keys
+ * (generator ids, subject names) must not be. This single predicate is
+ * the source of truth for every iteration site that must skip reserved
+ * keys — generators never iterate enrichments themselves (they read by
+ * known key through the typed helpers), so the segregation is a core /
+ * migration concern only.
  */
-exports.inputItem = v.object({
-    id: v.string(),
-    accessorPath: v.array(v.string()),
-    formatter: ModuleExport_js_1.moduleExport
-});
+const isReservedEnrichmentKey = (key) => key.startsWith('_');
+exports.isReservedEnrichmentKey = isReservedEnrichmentKey;
+exports.generatorEnrichments = v.pipe(v.record(v.string(), v.union([exports.modelEnrichments, exports.oasPathEnrichments, exports.gqlRootKindEnrichments])), v.rawCheck(({ dataset, addIssue }) => {
+    if (!dataset.typed)
+        return;
+    for (const [topKey, slot] of Object.entries(dataset.value)) {
+        if ((0, exports.isReservedEnrichmentKey)(topKey)) {
+            if (topKey !== exports.STACK_ENRICHMENT_KEY) {
+                addIssue({
+                    message: `Enrichment key '${topKey}' starts with '_' but is not a recognised reserved key. ` +
+                        `The only reserved top-level key is '${exports.STACK_ENRICHMENT_KEY}' (stack enrichment); ` +
+                        `generator ids must not start with '_'.`
+                });
+            }
+            // `_stack`'s value is a leaf — nothing to validate inside it.
+            continue;
+        }
+        if (typeof slot !== 'object' || slot === null)
+            continue;
+        for (const slotKey of Object.keys(slot)) {
+            if ((0, exports.isReservedEnrichmentKey)(slotKey) && slotKey !== exports.GENERATOR_ENRICHMENT_KEY) {
+                addIssue({
+                    message: `Enrichment key '${slotKey}' under generator '${topKey}' starts with '_' but is not ` +
+                        `a recognised reserved key. The only reserved per-generator key is ` +
+                        `'${exports.GENERATOR_ENRICHMENT_KEY}' (generator enrichment); subject keys must not start with '_'.`
+                });
+            }
+        }
+    }
+}));
 /**
- * Valibot schema for operation-level enrichments.
- *
- * Validates enrichment configurations that can be applied to OpenAPI operations,
- * including table, form, and input component definitions.
+ * The composite enrichment schema a generator with NO enrichments at any scope
+ * declares (`toEnrichmentSchema: () => emptyEnrichmentSchema`). Every member is
+ * `v.undefined()` — strict: a no-enrichment generator that somehow receives a
+ * value fails loud (fail-open at the call site) rather than silently swallowing
+ * it.
  */
-exports.operationEnrichments = v.object({
-    table: v.optional(exports.tableItem),
-    form: v.optional(exports.formItem),
-    input: v.optional(exports.inputItem)
+exports.emptyEnrichmentSchema = v.object({
+    subject: v.undefined(),
+    generator: v.undefined(),
+    stack: v.undefined()
 });
-/**
- * Valibot schema for HTTP method-level enrichments.
- *
- * Maps HTTP methods (GET, POST, etc.) to their operation enrichment configurations.
- */
-exports.methodEnrichments = v.record(v.string(), exports.operationEnrichments);
-/**
- * Valibot schema for API path-level enrichments.
- *
- * Maps API paths to their method enrichment configurations.
- */
-exports.pathEnrichments = v.record(v.string(), exports.methodEnrichments);
-/**
- * Valibot schema for generator-level enrichments.
- *
- * Maps generator IDs to their path enrichment configurations,
- * creating a complete hierarchy of enrichment data.
- */
-exports.generatorEnrichments = v.record(v.string(), exports.pathEnrichments);