@salsita-ai/sdk 0.50.0-develop.ca5894b56c → 0.50.0-develop.cba048b0d7

package/dist/domain/spec/application/admin-pages-section.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `$adminPages` section of an admin spec file as it is written, which the parsed admin pages
+ * keep as their `spec`. `application-spec` exports it as `RawAdminPages`, and the application
+ * config takes it as `AdminPagesSpec`.
+ */
+export interface AdminPagesSection {
+    readonly presets?: boolean | {
+        readonly categoryNavigationState?: string;
+        readonly presetNavigationState?: string;
+    };
+    readonly recipes?: ReadonlyArray<{
+        readonly name: string;
+        readonly navigationState?: string;
+    }>;
+    readonly pages?: ReadonlyArray<{
+        readonly key: string;
+        readonly title: string;
+        readonly icon?: string;
+        readonly navigationState?: string;
+        readonly entity?: string;
+        readonly component?: string;
+        readonly actionsComponent?: string;
+        readonly connectedDataEntry?: string;
+        readonly sidebar?: {
+            readonly title: string;
+            readonly component: string;
+        };
+    }>;
+}

package/dist/domain/spec/application/admin-pages.d.ts

@@ -0,0 +1,26 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ComponentEntry } from '../components/index.js';
+import type { AdminPagesSection } from './admin-pages-section.js';
+/**
+ * The parsed admin pages of an admin spec: the `$adminPages` section as written, the components
+ * the pages attach, the items of the admin navigation and the navigation states the pages add.
+ */
+export type AdminPages = Branded<'AdminPages', {
+    readonly spec: AdminPagesSection;
+    readonly components: readonly ComponentEntry[];
+    readonly navigationItems: readonly AdminNavigationItem[];
+    readonly navigationStates: readonly string[];
+}>;
+interface AdminNavigationListItem {
+    readonly label: string;
+    readonly icon?: string;
+    readonly navigationStates: readonly string[];
+}
+interface AdminNestedNavigationListItem {
+    readonly label: string;
+    readonly icon?: string;
+    readonly items: ReadonlyArray<Omit<AdminNavigationListItem, 'icon'>>;
+}
+/** One item of the admin navigation: a list item, or a nested list of them. */
+export type AdminNavigationItem = AdminNavigationListItem | AdminNestedNavigationListItem;
+export {};

package/dist/domain/spec/application/admin-states.d.ts

@@ -0,0 +1,5 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { StateValue } from '../sections/index.js';
+export type AdminStates = Branded<'AdminStates', {
+    readonly navigationStates: readonly StateValue[];
+}>;

package/dist/domain/spec/application/admin-states.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/application/configurator-states.d.ts

@@ -0,0 +1,8 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { StateValue } from '../sections/index.js';
+export type ConfiguratorStates = Branded<'ConfiguratorStates', {
+    readonly navigationStates: readonly StateValue[];
+    readonly viewStates: readonly StateValue[];
+    readonly toolStates: readonly StateValue[];
+    readonly exportStates: readonly StateValue[];
+}>;

package/dist/domain/spec/application/configurator-states.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/application/index.d.ts

@@ -1 +1,5 @@
+export type * from './admin-pages.js';
+export type * from './admin-pages-section.js';
+export type * from './admin-states.js';
 export * from './application-instance.js';
+export type * from './configurator-states.js';

package/dist/domain/spec/components/bindings/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './read-binding.js';
+export type * from './write-binding.js';

package/dist/domain/spec/components/bindings/index.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/bindings/read-binding.d.ts

@@ -0,0 +1,13 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * A validated `$read` dependency found anywhere in the component props tree.
+ * Used for memoEval dependency tracking — the target becomes `self.target` in generated code.
+ * Field targets are validated against the entity shape; expression targets ($-prefixed)
+ * are accepted without validation (they may be inferred during Phase C).
+ */
+export type ComponentReadBinding = Branded<'ComponentReadBinding', {
+    /** The raw target string from `$read` (e.g. "height" or "$price"). */
+    readonly target: string;
+    /** Whether the target is an expression (starts with `$`) or a shape field. */
+    readonly isExpression: boolean;
+}>;

package/dist/domain/spec/components/bindings/read-binding.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/bindings/write-binding.d.ts

@@ -0,0 +1,32 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Runtime type assertion to emit in the write callback.
+ * Resolved from the target entity field's schema during parsing.
+ */
+export type AssertionKind = {
+    readonly kind: 'declaredType';
+    readonly typeName: string;
+} | {
+    readonly kind: 'declaredTypeId';
+    readonly referencedType: string;
+} | {
+    readonly kind: 'primitive';
+    readonly assertFn: 'assertString' | 'assertNumber' | 'assertBoolean';
+} | {
+    readonly kind: 'literal';
+    readonly value: null;
+} | {
+    readonly kind: 'anyOf';
+    readonly assertions: readonly AssertionKind[];
+} | {
+    readonly kind: 'none';
+};
+/**
+ * A validated `$write` or `$bind` mapping from a component state key to an entity field.
+ * Includes the resolved assertion kind for runtime type checking in the write callback.
+ */
+export type ComponentWriteBinding = Branded<'ComponentWriteBinding', {
+    readonly propKey: string;
+    readonly entityField: string;
+    readonly assertion: AssertionKind;
+}>;

package/dist/domain/spec/components/bindings/write-binding.js

@@ -0,0 +1 @@
+export{};

package/dist/{application-spec/parse-application-files → domain}/spec/components/component-entry.d.ts

@@ -1,9 +1,9 @@
 import type { Branded } from '@salsita-ai/common/utils';
-import type { SdkCodeRef } from '../../../core/index.js';
-import type { MemoEvalPlan, MemoEvalPlanInput } from '../expressions/memo-eval-plan.js';
+import type { MemoEvalPlan, MemoEvalPlanInput } from '../expressions/index.js';
 import type { EntityOrAliasName, InstanceName } from '../model/index.js';
 import type { ComponentReadBinding, ComponentWriteBinding } from './bindings/index.js';
-import type { ComponentFilters } from './component-filter.js';
+import type { ComponentFilters } from './component-filters.js';
+import type { SdkCodeRef } from './sdk-code-ref.js';
 /**
  * Root-level `$read` variant — the entire instance state is driven by a single
  * `$read` at the root (components.md §"Root-Level $read"). No `resolvedProps`

package/dist/domain/spec/components/component-entry.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/component-filters.d.ts

@@ -0,0 +1,10 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { SpecComponentFilter } from './component-filter.js';
+/**
+ * Validated set of `$filter` entries on a user-bound component instance. Each
+ * {@link SpecComponentFilter} represents one alternative filter condition; multiple
+ * entries arise from `$or`. Empty `items` means no filter is applied.
+ */
+export type ComponentFilters = Branded<'ComponentFilters', {
+    readonly items: readonly SpecComponentFilter[];
+}>;

package/dist/domain/spec/components/component-filters.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/components.d.ts

@@ -0,0 +1,4 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ComponentEntry } from './component-entry.js';
+/** Final merged components for a domain, including SDK/spec-derived entries. */
+export type Components = Branded<'Components', readonly ComponentEntry[]>;

package/dist/domain/spec/components/components.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/index.d.ts

@@ -1,2 +1,6 @@
+export type * from './bindings/index.js';
+export type * from './component-entry.js';
 export * from './component-filter.js';
+export type * from './component-filters.js';
+export type * from './components.js';
 export * from './sdk-code-ref.js';

package/dist/domain/spec/{enhanced-json-value.d.ts → enhanced-json/enhanced-json-value.d.ts}

@@ -1,4 +1,4 @@
-import type { EvalMarker, MsgMarker } from './markers/index.js';
+import type { EvalMarker, MsgMarker } from '../markers/index.js';
 /**
  * A JSON-serialisable value augmented with Phoenix structural markers:
  * `$msg` (i18n) and `$eval` (self-scoped code).

package/dist/domain/spec/enhanced-json/index.d.ts

@@ -0,0 +1 @@
+export * from './enhanced-json-value.js';

package/dist/domain/spec/enhanced-json/index.js

@@ -0,0 +1 @@
+export*from"./enhanced-json-value.js";

package/dist/{application-spec/parse-application-files → domain}/spec/expressions/expression.d.ts

@@ -1,7 +1,9 @@
 import type { Branded } from '@salsita-ai/common/utils';
-import type { EnhancedJsonSchemaType, EnhancedJsonValue, SdkExpressionImplementation } from '../../../core/index.js';
+import type { EnhancedJsonSchemaType } from '../../core/index.js';
+import type { EnhancedJsonValue } from '../enhanced-json/index.js';
 import type { EntityOrAliasName, ExpressionName } from '../model/index.js';
 import type { MemoEvalPlan } from './memo-eval-plan.js';
+import type { SdkExpressionImplementation } from './sdk-expression-implementation.js';
 /**
  * How an expression's runtime implementation is provided.
  * - `user`: implementation from `src/expressions/*.ts` (dynamic import)
@@ -22,8 +24,12 @@ export type ExpressionImplementation = {
     readonly value: EnhancedJsonValue;
     readonly plan: MemoEvalPlan;
 };
-/** A single parsed expression declaration. */
-export type Expression = Branded<'Expression', {
+/**
+ * A single parsed expression declaration of the application spec: the entity or alias it belongs
+ * to, its name, its schemas and how its implementation is provided. `application-spec` exports it
+ * as `Expression`.
+ */
+export type SpecExpression = Branded<'Expression', {
     readonly entityKey: EntityOrAliasName;
     readonly name: ExpressionName;
     /**

package/dist/domain/spec/expressions/expression.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/expressions/expressions.d.ts

@@ -0,0 +1,27 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { EntityOrAliasName, EntityTypeName, ExpressionName } from '../model/index.js';
+import type { SpecExpression } from './expression.js';
+import type { MemoEvalPlan } from './memo-eval-plan.js';
+/**
+ * Resolved expressions for a single entity type. Holds the ordered list of
+ * shape source keys (entity itself + aliases it belongs to) — codegen appends
+ * `"Expressions"` to each key to reference the typed expression group.
+ */
+export type EntityExpressions = Branded<'EntityExpressions', {
+    /** Entity/alias keys whose expressions this entity inherits. Codegen appends "Expressions" suffix. */
+    readonly shapeGroups: readonly EntityOrAliasName[];
+}>;
+/**
+ * Final merged expressions for a domain — user-declared + inferred.
+ * The internal `expressions` map groups by entity/alias for codegen/runtime lookups.
+ * `entityExpressions` provides per-entity alias expansion.
+ * `constants` projects the self-free `constants:` values, grouped like `expressions`;
+ * codegen passes them to the enhanced entity/alias reflections so they are readable at
+ * module level (`phx.domain.enhancedModel.$Wall.$maxWidth`). A constant whose plan uses
+ * `self` needs an instance, so it stays an ordinary value expression and is absent here.
+ */
+export type Expressions = Branded<'Expressions', {
+    readonly expressions: ReadonlyMap<EntityOrAliasName, ReadonlyMap<ExpressionName, SpecExpression>>;
+    readonly entityExpressions: ReadonlyMap<EntityTypeName, EntityExpressions>;
+    readonly constants: ReadonlyMap<EntityOrAliasName, ReadonlyMap<ExpressionName, MemoEvalPlan>>;
+}>;

package/dist/domain/spec/expressions/expressions.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/expressions/index.d.ts

@@ -1,2 +1,5 @@
+export type * from './expression.js';
+export type * from './expressions.js';
+export type * from './memo-eval-plan.js';
 export type * from './relation-expression-params.js';
 export * from './sdk-expression-implementation.js';

package/dist/domain/spec/expressions/memo-eval-plan.d.ts

@@ -0,0 +1,70 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ComponentPropTarget, EvalMarker, MsgMarker } from '../markers/index.js';
+export type MemoEvalLiteral = string | number | boolean | null;
+/**
+ * A single entry in the memoEval deps array.
+ *
+ * - `'eval'` — a `$eval` code fragment. At deps-build time the fragment is
+ *   evaluated under `self` (`new Function('self', …)` at runtime, spliced
+ *   verbatim under `self => [...]` in codegen). `label` annotates codegen
+ *   output (e.g. `/* $eval: Entity.instance *\/`).
+ * - `'read'` — a read binding that resolves to `self[target]` at deps-build
+ *   time.
+ */
+export type MemoEvalDep = Branded<'MemoEvalDep', {
+    readonly kind: 'eval';
+    readonly code: string;
+    readonly label: string;
+} | {
+    readonly kind: 'read';
+    readonly target: string;
+}>;
+/**
+ * Tree of values with slots referencing entries in the plan's `deps` array.
+ * Generated by codegen as a JS literal with params spliced in, or by runtime
+ * by walking and substituting from the `deps`-materialised values array.
+ */
+export type MemoEvalTemplate = Branded<'MemoEvalTemplate', {
+    readonly kind: 'literal';
+    readonly value: MemoEvalLiteral;
+} | {
+    readonly kind: 'msg';
+    readonly marker: MsgMarker;
+} | {
+    readonly kind: 'slot';
+    readonly depIndex: number;
+} | {
+    readonly kind: 'array';
+    readonly items: readonly MemoEvalTemplate[];
+} | {
+    readonly kind: 'object';
+    readonly entries: ReadonlyArray<readonly [string, MemoEvalTemplate]>;
+}>;
+export type MemoEvalPlanInput = MemoEvalLiteral | EvalMarker | MsgMarker | ComponentPropTarget | MemoEvalPlanInputArray | MemoEvalPlanInputObject;
+export interface MemoEvalPlanInputArray extends ReadonlyArray<MemoEvalPlanInput> {
+}
+export interface MemoEvalPlanInputObject {
+    readonly [key: string]: MemoEvalPlanInput;
+}
+/**
+ * Normalized plan for producing a memoized reader from a tree containing
+ * `$eval`, `$target`, `$msg`, and literal nodes. Built once during spec
+ * parsing; codegen + runtime both generate from the same plan so their outputs
+ * cannot drift.
+ *
+ * - `deps` — ordered evaluation slots in first-seen walk order. Each slot
+ *   dedupes (`$eval` by trimmed code, `$target` by name) so a repeated marker
+ *   shares one dep.
+ * - `template` — rebuilt value tree with `slot { depIndex }` nodes in place
+ *   of the consumed markers.
+ * - `usesSelf` — true when deps collection must receive `self`, either
+ *   because a read dep exists or because an eval dep references `self`.
+ *
+ * When `deps` is empty the tree is fully static — generators cache
+ * non-primitive templates and keep primitive literals as bare thunks.
+ */
+export type MemoEvalPlan = Branded<'MemoEvalPlan', {
+    readonly deps: readonly MemoEvalDep[];
+    readonly template: MemoEvalTemplate;
+    readonly usesSelf: boolean;
+}>;

package/dist/domain/spec/expressions/memo-eval-plan.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/index.d.ts

@@ -1,7 +1,9 @@
 export * from './application/index.js';
 export * from './components/index.js';
-export * from './enhanced-json-value.js';
+export * from './enhanced-json/index.js';
 export * from './expressions/index.js';
+export type * from './invariants/index.js';
 export type * from './json-schema.js';
 export * from './markers/index.js';
 export type * from './model/index.js';
+export * from './sections/index.js';

package/dist/domain/spec/index.js

@@ -1 +1 @@
-export*from"./application/index.js";export*from"./components/index.js";export*from"./enhanced-json-value.js";export*from"./expressions/index.js";export*from"./markers/index.js";
+export*from"./application/index.js";export*from"./components/index.js";export*from"./enhanced-json/index.js";export*from"./expressions/index.js";export*from"./markers/index.js";export*from"./sections/index.js";

package/dist/domain/spec/invariants/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './invariant.js';
+export type * from './invariants.js';

package/dist/domain/spec/invariants/index.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/invariants/invariant.d.ts

@@ -0,0 +1,24 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { MsgMarker } from '../markers/index.js';
+import type { InvariantName, ViolationTypeName } from '../model/index.js';
+export type InvariantSeverity = 'fatal' | 'fixable' | 'warning' | 'notice';
+/** A YAML invariant whose violation metadata is fully declared in the application spec. */
+export type StaticInvariant = Branded<'StaticInvariant', {
+    readonly kind: 'static';
+    readonly name: InvariantName;
+    readonly violationType: ViolationTypeName;
+    readonly severity: InvariantSeverity;
+    readonly message: string | MsgMarker;
+    readonly controlViolationPriority?: number;
+}>;
+/** A YAML invariant whose implementation may return any of the declared violation types. */
+export type DynamicInvariant = Branded<'DynamicInvariant', {
+    readonly kind: 'dynamic';
+    readonly name: InvariantName;
+    readonly violationTypes: readonly ViolationTypeName[];
+}>;
+/**
+ * A validated static or dynamic invariant declaration of the application spec. `application-spec`
+ * exports it as `Invariant`.
+ */
+export type SpecInvariant = StaticInvariant | DynamicInvariant;

package/dist/domain/spec/invariants/invariant.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/invariants/invariants.d.ts

@@ -0,0 +1,14 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ComponentEntry } from '../components/index.js';
+import type { SpecExpression } from '../expressions/index.js';
+import type { EntityOrAliasName, InvariantName } from '../model/index.js';
+import type { SpecInvariant } from './invariant.js';
+/**
+ * Validated invariants and the expressions/components they contribute to the application spec.
+ * Entries retain their entity-or-alias declaration keys while artifacts expand to concrete entity types.
+ */
+export type Invariants = Branded<'Invariants', {
+    readonly entries: Readonly<Record<EntityOrAliasName, Readonly<Record<InvariantName, SpecInvariant>>>>;
+    readonly expressions: readonly SpecExpression[];
+    readonly components: readonly ComponentEntry[];
+}>;

package/dist/domain/spec/invariants/invariants.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/markers/index.d.ts

@@ -1,2 +1,3 @@
+export * from './component-prop-target.js';
 export * from './eval-marker.js';
 export * from './msg-marker.js';

package/dist/domain/spec/markers/index.js

@@ -1 +1 @@
-export*from"./eval-marker.js";export*from"./msg-marker.js";
+export*from"./component-prop-target.js";export*from"./eval-marker.js";export*from"./msg-marker.js";

package/dist/domain/spec/model/defaults.d.ts

@@ -1,5 +1,5 @@
 import type { Branded } from '@salsita-ai/common/utils';
-import type { EnhancedJsonValue } from '../enhanced-json-value.js';
+import type { EnhancedJsonValue } from '../enhanced-json/index.js';
 import type { EntityTypeName, ShapePropertyName } from './names/index.js';
 /**
  * A map of shape property names to their default values inside a single entity block.

package/dist/domain/spec/sections/actions.d.ts

@@ -0,0 +1,23 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { EnhancedJsonSchemaType } from '../../core/index.js';
+import type { JsonSchema } from '../json-schema.js';
+import type { ActionName } from '../model/index.js';
+/** One parameter of an action: its declared schema, and whether a call has to pass it (a nullable param is optional). */
+export interface ActionParam {
+    readonly schema: EnhancedJsonSchemaType;
+    readonly required: boolean;
+}
+/**
+ * One validated action declaration. `params` and `result` keep the enhanced schemas for codegen and
+ * for consumers that expose the action; `paramsSchema` is the AJV-ready object schema of the parameters, with the
+ * refs resolved into `$defs`, which the action system validates the arguments of a call against.
+ */
+export type Action = Branded<'Action', {
+    readonly name: ActionName;
+    readonly description?: string;
+    readonly params: Readonly<Record<string, ActionParam>>;
+    readonly result: Readonly<Record<string, EnhancedJsonSchemaType>>;
+    readonly paramsSchema: JsonSchema;
+}>;
+/** The validated `actions` section: every declared action by name, in declaration order; empty when the spec declares none. */
+export type Actions = Branded<'Actions', ReadonlyMap<ActionName, Action>>;

package/dist/domain/spec/sections/actions.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/app-metadata.d.ts

@@ -0,0 +1,18 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ApplicationVersion } from './application-version.js';
+/**
+ * Validated application metadata — version, auth, infrastructure settings.
+ * Used by codegen for ApplicationVersion export and builder chain methods.
+ */
+export type AppMetadata = Branded<'AppMetadata', {
+    readonly applicationVersion: ApplicationVersion;
+    readonly workspace: boolean;
+    readonly webComponentTag: string | undefined;
+    readonly pageTitle: string | undefined;
+    readonly useAuthHook: boolean;
+    readonly useClerk: boolean;
+    readonly enableAdminRelease: boolean;
+    readonly jsonSchemaValidator: 'ajv' | 'csp-compatible';
+    readonly gltfDecoder: 'js' | 'wasm';
+    readonly collectFinalizeData: boolean;
+}>;

package/dist/domain/spec/sections/app-metadata.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/application-version.d.ts

@@ -0,0 +1,7 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Branded semantic version (x.y.z) of the application.
+ * Exported by codegen as the `ApplicationVersion` constant and stored as
+ * `applicationVersion` on the deployment record.
+ */
+export type ApplicationVersion = Branded<'ApplicationVersion', string>;

package/dist/domain/spec/sections/application-version.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/chunks.d.ts

@@ -0,0 +1,23 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Validated published-data chunk name.
+ * Chunk names identify top-level partitions in generated `publishedData`. Data
+ * entries point to these names through their `chunk` field, and the parser adds
+ * the reserved `system` chunk when user chunks exist.
+ */
+export type ChunkName = Branded<'ChunkName', string>;
+/**
+ * A named partition of published data with a scope.
+ * `scope` is typically `'project'` (per-project data) or `'public'` (shared).
+ */
+export interface ChunkDefinition {
+    /** Visibility/storage scope used by runtime data publishing for this chunk. */
+    readonly scope: string;
+}
+/**
+ * Validated chunk definitions, keyed by chunk name.
+ * When any user-defined chunks are present, the reserved `system` chunk is
+ * auto-injected with `scope: 'public'` to carry admin presets/recipes schemas.
+ * When the input is empty, no system injection happens (mirrors domain-spec behavior).
+ */
+export type Chunks = Readonly<Record<ChunkName, ChunkDefinition>>;

package/dist/domain/spec/sections/data-spec/chunks.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/custom-data-spec-entry.d.ts

@@ -0,0 +1,16 @@
+import type { DataCellValue, DataSchema } from '../../../core/index.js';
+/** Parsed `$data.custom` entry with validated definition and normalized row values. */
+export interface CustomDataSpecEntry {
+    /** Column/property schema for a custom data row, used by admin pages and published-data schemas. */
+    readonly definition: DataSchema;
+    /** Optional published-data chunk that receives this entry as an array property. */
+    readonly chunk?: string;
+    /** Ownership mode deciding whether data is manual, externally connected, or admin-generated. */
+    readonly kind: 'manual' | 'connected' | 'generated';
+    /** Optional human-readable label used by inferred admin pages and connected-data UI. */
+    readonly title?: string;
+    /** Optional icon name used in inferred admin navigation. */
+    readonly icon?: string;
+    /** Default rows normalized to the same column order as `definition`. */
+    readonly values?: ReadonlyArray<readonly DataCellValue[]>;
+}

package/dist/domain/spec/sections/data-spec/custom-data-spec-entry.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/data-entry-key.d.ts

@@ -0,0 +1,9 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Validated `$data` entry key.
+ * This is the stable identifier for a data collection declared under `$data.custom`
+ * or `$data.swatchOptions`. The same key is used when extending published data,
+ * wiring connected/generated admin pages, and linking explicit admin pages through
+ * `connectedDataEntry`.
+ */
+export type DataEntryKey = Branded<'DataEntryKey', string>;

package/dist/domain/spec/sections/data-spec/data-entry-key.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './chunks.js';
+export type * from './custom-data-spec-entry.js';
+export type * from './data-entry-key.js';
+export type * from './parsed-data-spec-entries.js';
+export type * from './swatch-data-spec-entry.js';

package/dist/domain/spec/sections/data-spec/index.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/parsed-data-spec-entries.d.ts

@@ -0,0 +1,10 @@
+import type { CustomDataSpecEntry } from './custom-data-spec-entry.js';
+import type { DataEntryKey } from './data-entry-key.js';
+import type { SwatchDataSpecEntry } from './swatch-data-spec-entry.js';
+/** Validated `$data` entries grouped by their source section. */
+export interface ParsedDataSpecEntries {
+    /** Custom data entries with user-declared schemas. */
+    readonly custom: Readonly<Record<DataEntryKey, CustomDataSpecEntry>>;
+    /** Swatch data entries with the built-in swatch schema. */
+    readonly swatchOptions: Readonly<Record<DataEntryKey, SwatchDataSpecEntry>>;
+}

package/dist/domain/spec/sections/data-spec/parsed-data-spec-entries.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/swatch-data-spec-entry.d.ts

@@ -0,0 +1,14 @@
+import type { CellValue } from '@salsita-ai/contracts/webhook';
+/** Parsed `$data.swatchOptions` entry using the fixed swatch data shape. */
+export interface SwatchDataSpecEntry {
+    /** Optional published-data chunk that receives this swatch entry as an array property. */
+    readonly chunk?: string;
+    /** Ownership mode deciding whether swatches are manual, externally connected, or admin-generated. */
+    readonly kind: 'manual' | 'connected' | 'generated';
+    /** Optional human-readable label used by inferred admin pages and connected-data UI. */
+    readonly title?: string;
+    /** Optional icon name used in inferred admin navigation. */
+    readonly icon?: string;
+    /** Default swatch rows normalized to `SWATCH_DEFINITION` column order. */
+    readonly values?: ReadonlyArray<readonly CellValue[]>;
+}

package/dist/domain/spec/sections/data-spec/swatch-data-spec-entry.js

@@ -0,0 +1 @@
+export{};