@salsita-ai/sdk 0.50.0-develop.ea458ea381 → 0.50.0-develop.ecda3c6152

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-section.js

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

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-pages.js

@@ -0,0 +1 @@
+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

@@ -0,0 +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/application/index.js

@@ -0,0 +1 @@
+export*from"./application-instance.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/domain/spec/components/component-entry.d.ts

@@ -0,0 +1,90 @@
+import type { Branded } from '@salsita-ai/common/utils';
+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-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`
+ * tree, no write bindings; the single validated `readBinding` carries the
+ * target name and codegen emits `.attach(self => self.${readBinding.target}, …)`
+ * without `memoEval`.
+ */
+export interface RootReadImplementation {
+    readonly kind: 'rootRead';
+    readonly readBinding: ComponentReadBinding;
+}
+/**
+ * Composite variant — per-property reads with optional writes. `resolvedProps`
+ * is the instance props tree with `$read`/`$bind` lowered to
+ * {@link ComponentPropTarget} structs; each entry in `readBindings` corresponds
+ * to one target referenced from the tree. Codegen walks the tree and emits
+ * `memoEval(self => [deps], (…params) => body)` when the tree has no inline
+ * code, or `self => (body)` when it does. `writeBindings` carry per-prop write
+ * targets — only valid on this variant (root-read never has writes).
+ */
+export interface CompositeImplementation {
+    readonly kind: 'composite';
+    readonly resolvedProps: Readonly<Record<string, MemoEvalPlanInput>>;
+    readonly readBindings: readonly ComponentReadBinding[];
+    readonly writeBindings: readonly ComponentWriteBinding[];
+}
+/**
+ * User-bound component — filters apply uniformly, read/write behavior is
+ * carried in the discriminated {@link RootReadImplementation} |
+ * {@link CompositeImplementation} union under `implementation`.
+ * Root-read instances cannot carry write bindings by construction.
+ *
+ * `plan` is the shared {@link MemoEvalPlan} consumed by both codegen and
+ * runtime to emit a `memoEval(…)` reader or a cached static reader. It
+ * subsumes the old rootRead special case — a rootRead
+ * instance is simply a plan with a single read dep + slot template.
+ */
+interface UserBoundImplementation {
+    readonly kind: 'userBound';
+    readonly filters: ComponentFilters;
+    readonly plan: MemoEvalPlan;
+    readonly implementation: RootReadImplementation | CompositeImplementation;
+}
+export type SdkFactoryParam = SdkCodeRef | string | number | boolean | null | readonly SdkFactoryParam[] | {
+    readonly [key: string]: SdkFactoryParam;
+};
+/**
+ * An SDK factory call — codegen emits the function name with params inlined,
+ * runtime calls the function with resolved params (e.g. entity reflections).
+ */
+export interface SdkFactory {
+    /** SDK function name to import and call (e.g. "createSingleReferenceRead"). */
+    readonly sdkFunction: string;
+    /** Positional params — string/number are quoted, SdkCodeRef emitted as variable references. */
+    readonly params: readonly SdkFactoryParam[];
+}
+/**
+ * SDK-provided component — generic factory-based attachment.
+ * The SDK provides read + write factory functions; codegen imports and calls them with params.
+ * The component type itself comes from `ComponentEntry.componentName`.
+ * Used for relation-derived components (reference, composition) and extensible for future SDK types.
+ */
+interface SdkImplementation {
+    readonly kind: 'sdk';
+    readonly filters: ComponentFilters;
+    /** Factory that produces the read function for `.attach(readFn, writeFn)`. */
+    readonly readFactory: SdkFactory;
+    /** Factory that produces the write function for `.attach(readFn, writeFn)`. */
+    readonly writeFactory: SdkFactory;
+}
+/** Discriminated union — each variant carries the concrete typed params its builder needs. */
+export type ComponentImplementation = UserBoundImplementation | SdkImplementation;
+/**
+ * A single component attachment on the domain spec.
+ * Shared structure for user-declared and SDK-provided (relation-derived) components.
+ */
+export type ComponentEntry = Branded<'ComponentEntry', {
+    readonly typeOrAlias: EntityOrAliasName;
+    readonly instanceName: InstanceName;
+    readonly isAlias: boolean;
+    readonly componentName: string;
+    readonly implementation: ComponentImplementation;
+}>;
+export {};

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * A single filter criterion — static value, dynamic `$read` reference, or
+ * inline `$eval` expression evaluated against `self` at runtime.
+ *
+ * The `target` field on the `'dynamic'` variant is a bare name (matches the
+ * same pattern as prop-level reads); codegen emits `self.target`, runtime
+ * reads `self[target]`.
+ */
+export type FilterCriterion<T> = {
+    readonly kind: 'static';
+    readonly value: T;
+} | {
+    readonly kind: 'dynamic';
+    readonly target: string;
+} | {
+    readonly kind: 'eval';
+    readonly code: string;
+};
+/**
+ * Parsed component filter controlling when the component is active, as the application spec
+ * declares it under `$filter`; `application-spec` exports it as `ComponentFilter`. Two
+ * mutually-exclusive shapes:
+ *
+ * - `'gradual'` — zero or more per-criterion fields; compiles to one entry per
+ *   set key inside `.withGradualFilter({…})`. The preferred form.
+ * - `'root'` — the entire filter is a single `$read` at the root (legacy
+ *   form `$filter: { $read: '$x' }`); compiles to `.withFilter(self => (self.target))`.
+ *   Distinct codegen because the SDK's `withFilter` and `withGradualFilter`
+ *   methods have different evaluation semantics (whole-closure vs per-key).
+ *
+ * See `components.md §"Simple expression filter"` / `§"Declarative filter"`.
+ */
+export type SpecComponentFilter = {
+    readonly kind: 'gradual';
+    readonly navigationStates?: FilterCriterion<readonly string[]>;
+    readonly viewStates?: FilterCriterion<readonly string[]>;
+    readonly toolStates?: FilterCriterion<readonly string[]>;
+    readonly exportStates?: FilterCriterion<readonly string[]>;
+    readonly modes?: FilterCriterion<readonly string[]>;
+    readonly roles?: FilterCriterion<readonly string[]>;
+    readonly selectedEntityIds?: FilterCriterion<unknown>;
+    readonly hoveredEntityIds?: FilterCriterion<unknown>;
+    readonly draggedEntityIds?: FilterCriterion<unknown>;
+    readonly exportedEntityIds?: FilterCriterion<unknown>;
+    readonly active?: FilterCriterion<boolean>;
+    readonly fullscreen?: FilterCriterion<boolean>;
+    readonly debug?: FilterCriterion<boolean>;
+    readonly viewports?: FilterCriterion<unknown>;
+} | {
+    readonly kind: 'root';
+    readonly target: string;
+};
+/** Criterion field names on the gradual variant — used for parse and iteration. */
+export declare const FILTER_CRITERION_KEYS: readonly ["navigationStates", "viewStates", "toolStates", "exportStates", "modes", "roles", "selectedEntityIds", "hoveredEntityIds", "draggedEntityIds", "exportedEntityIds", "active", "fullscreen", "debug", "viewports"];

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

@@ -0,0 +1 @@
+export const FILTER_CRITERION_KEYS=["navigationStates","viewStates","toolStates","exportStates","modes","roles","selectedEntityIds","hoveredEntityIds","draggedEntityIds","exportedEntityIds","active","fullscreen","debug","viewports"];

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

@@ -0,0 +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/components/index.js

@@ -0,0 +1 @@
+export*from"./component-filter.js";export*from"./sdk-code-ref.js";

package/dist/domain/spec/components/sdk-code-ref.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A parameter that should be emitted as an unquoted code reference in codegen
+ * (e.g. an entity reflection variable like `Top`).
+ * At runtime, the string value is resolved to the actual object (e.g. entity reflection).
+ */
+export interface SdkCodeRef {
+    readonly $codeRef: string;
+}
+export declare const isSdkCodeRef: (value: unknown) => value is SdkCodeRef;

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

@@ -0,0 +1,30 @@
+import type { EvalMarker, MsgMarker } from '../markers/index.js';
+/**
+ * A JSON-serialisable value augmented with Phoenix structural markers:
+ * `$msg` (i18n) and `$eval` (self-scoped code).
+ *
+ * Single shared shape across components, expressions, and defaults — lowered
+ * either to TypeScript source via `stringifyEnhancedJsonValue` or to a
+ * runtime value via `resolveEnhancedJsonValue`, both of `application-spec`.
+ *
+ * Which markers are allowed at a given slot is controlled by
+ * `EnhancedJsonValueCaps` of `application-spec`, not by the type — all markers parse
+ * identically, capability checks kick in at lowering time.
+ */
+export type EnhancedJsonValue = string | number | boolean | null | MsgMarker | EvalMarker | EnhancedJsonArray | EnhancedJsonObject;
+/** Array form of {@link EnhancedJsonValue} — extracted as a named interface so `z.lazy` can close the recursion. */
+export interface EnhancedJsonArray extends ReadonlyArray<EnhancedJsonValue> {
+}
+/** Object form of {@link EnhancedJsonValue} — extracted for the same reason as {@link EnhancedJsonArray}. */
+export interface EnhancedJsonObject {
+    readonly [key: string]: EnhancedJsonValue;
+}
+/** Runtime `self` accessor — shape-agnostic entity state. */
+export type SelfAccessor = object;
+/**
+ * Deterministic string key for a value — sorted object keys, JSON-encoded.
+ * Used by the expression runtime's reference store to preserve an evaluator when the
+ * underlying value is structurally unchanged (mirrors the content-hash pattern
+ * used for components).
+ */
+export declare const canonicalEnhancedJsonValueKey: (value: EnhancedJsonValue) => string;

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

@@ -0,0 +1 @@
+export const canonicalEnhancedJsonValueKey=r=>{let e=r=>{if(null===r||"object"!=typeof r)return r;if(Array.isArray(r))return r.map(e);let t={};for(let n of Object.keys(r).sort())t[n]=e(r[n]);return t};return JSON.stringify(e(r))};

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/domain/spec/expressions/expression.d.ts

@@ -0,0 +1,49 @@
+import type { Branded } from '@salsita-ai/common/utils';
+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)
+ * - `relation` / `violations`: built by an SDK factory with positional params — see {@link SdkExpressionImplementation}
+ * - `value`: inline implementation declared in YAML — `value` carries raw
+ *   `$msg` / `$eval` / literal markers for schema inference and reference comparison keys.
+ *   `plan` is the shared {@link MemoEvalPlan} built at parse time and consumed
+ *   by both codegen and runtime — emits a `memoEval(…)` reader (dep-ful, or
+ *   zero-dep in codegen for static aggregates) or a cached/bare static reader.
+ *   `value` is retained alongside `plan` for schema inference and for
+ *   `canonicalEnhancedJsonValueKey` comparison keys at runtime.
+ */
+export type ExpressionImplementation = {
+    readonly kind: 'user';
+} | SdkExpressionImplementation | {
+    readonly kind: 'value';
+    readonly constant: boolean;
+    readonly value: EnhancedJsonValue;
+    readonly plan: MemoEvalPlan;
+};
+/**
+ * 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;
+    /**
+     * The expression's full schema: the declared one intersected (`allOf`) with every schema inferred
+     * from component `$read`s of it, or only the inferred ones when nothing declares it. Codegen types
+     * the expression by it.
+     */
+    readonly schema: EnhancedJsonSchemaType;
+    /**
+     * The schema as declared, without anything inferred from `$read`: authored in `expressions:` or
+     * `constants:`, inferred from the inline value, or synthesized for a relation or `$violations`.
+     * Absent on an expression that only `$read` inference defines. The assistant schema whitelists and
+     * types expressions by it.
+     */
+    readonly declaredSchema?: EnhancedJsonSchemaType;
+    readonly implementation: ExpressionImplementation;
+}>;

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

@@ -0,0 +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/index.js

@@ -0,0 +1 @@
+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/expressions/relation-expression-params.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The relation factory's single positional param: the relation's kind, the entity type or alias it
+ * points to and its cardinality, plus the id field for `direct` and `indirect` relations. The
+ * assistant schema reads `target` and `cardinality` to type a relation edge.
+ */
+export interface RelationExpressionParams {
+    readonly kind: 'direct' | 'indirect' | 'allOfType';
+    readonly target: string;
+    readonly cardinality: '0-1' | '1-1' | '0-N' | '1-N';
+    readonly field?: string;
+}

package/dist/domain/spec/expressions/relation-expression-params.js

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

package/dist/domain/spec/expressions/sdk-expression-implementation.d.ts

@@ -0,0 +1,24 @@
+import type { RelationExpressionParams } from './relation-expression-params.js';
+/**
+ * An expression implementation built by an SDK factory at runtime. The kind is the
+ * semantic source of the expression, declared by the section that generated it —
+ * codegen and runtime dispatch on it instead of inspecting factory-function names.
+ * - `relation`: generated from a `relations:` declaration
+ * - `violations`: generated from `invariants:` declarations (the `$violations` expression)
+ */
+export type SdkExpressionImplementation = {
+    readonly kind: 'relation';
+    readonly params: readonly [RelationExpressionParams];
+} | {
+    readonly kind: 'violations';
+    readonly params: readonly unknown[];
+};
+/**
+ * Narrows to implementations that are built by an SDK expression factory at runtime. It checks
+ * `kind` only, so it narrows to the members of the caller's own type that are SDK implementations,
+ * such as those of the parser's `ExpressionImplementation`, and never adds the `params` a value
+ * of another type does not have.
+ */
+export declare const isSdkExpressionImplementation: <IMPLEMENTATION extends {
+    readonly kind: string;
+}>(implementation: IMPLEMENTATION) => implementation is Extract<IMPLEMENTATION, SdkExpressionImplementation>;

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

@@ -0,0 +1,9 @@
+export * from './application/index.js';
+export * from './components/index.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

@@ -0,0 +1 @@
+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{};