@salsita-ai/sdk 0.50.0-develop.ae52227c7e → 0.50.0-develop.aec0f535bf

package/dist/domain/spec/runtime/expressions/expression-runtime.d.ts

@@ -0,0 +1,57 @@
+import { Branded } from '@salsita-ai/common/utils';
+import { type DomainEntity, type Expression as DomainExpression, type Invariant as DomainInvariant } from '../../../core/index.js';
+import { type ImplementationErrorCollector } from '../../errors/index.js';
+import { type Expressions } from '../../expressions/index.js';
+import { type ProjectModule } from '../../modules/index.js';
+import { type RuntimeModelVersion } from '../../runtime-spec/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+import type { SpecCodeMap } from '../spec-code/index.js';
+type RuntimeData = Record<string, unknown>;
+type RuntimeEntity = DomainEntity<string>;
+type AnyExpression = DomainExpression<RuntimeEntity, RuntimeEntity, RuntimeData, RuntimeData, RuntimeData, RuntimeEntity, unknown>;
+type SdkInvariant = DomainInvariant<RuntimeEntity, RuntimeEntity, RuntimeData, RuntimeData, RuntimeData, RuntimeEntity, string>;
+/**
+ * Flat, entity-keyed expression map stored in the runtime spec slice and derived into the
+ * memoized table returned by `DomainContextSelectors.getDomainExpressions()`.
+ */
+export type ExpressionImplementations = Record<DomainEntity<string>['type'], Record<string, AnyExpression>>;
+/** Invariant implementations keyed by their concrete entity type or alias declaration. */
+export type InvariantImplementations = Readonly<Record<string, readonly SdkInvariant[]>>;
+export type MissingExpression = {
+    readonly entityType: string;
+    readonly exprName: string;
+};
+export type ExpressionRuntime = Branded<'ExpressionRuntime', {
+    readonly merged: ExpressionImplementations;
+    readonly changed: boolean;
+}>;
+export type ExpressionRuntimeResult = {
+    readonly ok: true;
+    readonly runtime: ExpressionRuntime;
+} | {
+    readonly ok: false;
+    readonly missing: readonly MissingExpression[];
+};
+interface ExpressionRuntimeSpec {
+    readonly expressions: Expressions;
+    readonly latestModel: RuntimeModelVersion;
+}
+/**
+ * Runtime section that produces the single merged expression map for the registry.
+ *
+ * Dispatches on `expression.implementation.kind`:
+ * - `relation` / `violations` — calls the matching SDK factory with params + runtime context
+ * - `user` — uses the implementation of the project files `expressionModules` (`src/expressions/`,
+ *   or `src/admin/expressions/`), merged with the spec's aliases by `mergeExpressionModules`, or the
+ *   one `builtIn` holds
+ * - `value` — evaluates the parsed {@link MemoEvalPlan}; stabilized per
+ *   {@link canonicalEnhancedJsonValueKey} so identical values reuse the same
+ *   evaluator across rebuilds. Its `$eval` code comes from `code`, the domain's map of the generated
+ *   code module, when that holds it.
+ *
+ * A file that is wrong, or that defines an expression another file, the spec or `builtIn` already
+ * defines, is recorded in `errors` as an `ImplementationError` and left out. So is every declared
+ * expression without an implementation, which also makes the result an error.
+ */
+export declare const ExpressionRuntime: (spec: ExpressionRuntimeSpec, referenceStore: RuntimeReferenceStore, expressionModules: readonly ProjectModule[], referenceScopePrefix: string, invariantImplementations: InvariantImplementations | undefined, code: SpecCodeMap | undefined, errors: ImplementationErrorCollector, builtIn?: ExpressionImplementations) => ExpressionRuntimeResult;
+export {};

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

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{createRelationFactory as i}from"../../../core/index.js";import{canonicalEnhancedJsonValueKey as n}from"../../enhanced-json/index.js";import{ImplementationError as a}from"../../errors/index.js";import{isSdkExpressionImplementation as r}from"../../expressions/index.js";import{mergeExpressionModules as o}from"../../modules/index.js";import{specCodeExpressionKey as s}from"../../runtime-spec/index.js";import{generateMemoEvalPlanRuntime as l}from"./generate-memo-eval-plan-runtime.js";let p={},m=["0-1","1-1","0-N","1-N"],d={relation:(e,t)=>{let n=t[0];if(!("object"==typeof n&&null!==n&&"kind"in n&&"target"in n&&"string"==typeof n.target&&"cardinality"in n&&m.includes(n.cardinality)&&("allOfType"===n.kind||("direct"===n.kind||"indirect"===n.kind)&&"field"in n&&"string"==typeof n.field)))throw Error("Cannot create the relation expression because its parameter is not a relation declaration. The application spec is inconsistent; rebuild it from a valid relations declaration.");return i(e.aliasMap)(n)},violations:(e,t)=>{let i=t[0];if("object"!=typeof i||null===i||!("entityType"in i)||"string"!=typeof i.entityType)throw Error("Cannot create the violations expression because its entityType parameter is missing. The application spec is inconsistent; rebuild it from a valid invariants declaration.");let n=i.entityType,a=Object.entries(e.invariantImplementations).flatMap(([t,i])=>{let a=e.aliasMap[t];return t===n||a?.includes(n)?i:[]});return{origin:{name:"$violations",typeOrAlias:n},evaluate:(e,t,i)=>a.flatMap(n=>n.evaluate(e,t,i)),meta:{}}}},f=e=>{let t=l(e.plan,s(e.entityOrAlias,e.name),e.code);return{origin:{name:e.name,typeOrAlias:e.entityOrAlias},evaluate:(e,i,n)=>t(n.domain.get$Entity(e,i),i,n),meta:{}}},u=e=>({...(0,d[e.kind])({aliasMap:e.aliasMap,invariantImplementations:e.invariantImplementations},e.params),origin:{name:e.name,typeOrAlias:e.entityOrAlias}});export const ExpressionRuntime=(i,s,l,m,d=p,c,y,g={})=>{let x={};for(let[e,t]of i.latestModel.aliases)x[String(e)]=t.map(String);let v={...g};for(let[e,t]of Object.entries(o(l,x,y,((e,t,i)=>{let n=new Map,a=(e,t)=>{n.set(e,(n.get(e)??new Set).add(t))};for(let[i,n]of e.expressions.expressions)for(let[e,r]of n)if("user"!==r.implementation.kind)for(let n of t[String(i)]??[String(i)])a(n,String(e));for(let[e,t]of Object.entries(i))for(let i of Object.keys(t))a(e,i);return n})(i,x,g))))v[e]={...v[e],...t};let S=s.createBuilder(`${m}/sdk`,{build:u,getKey:e=>`sdk::${e.entityOrAlias}::${e.name}`,compare:(t,i)=>t.kind===i.kind&&e(t.params,i.params)&&e(t.aliasMap,i.aliasMap)&&("violations"!==i.kind||t.invariantImplementations===i.invariantImplementations)}),h=s.createBuilder(`${m}/user`,{build:e=>e.impl,getKey:e=>`user::${e.entityType}::${e.name}`,compare:(e,t)=>{let i,n;return(i=e.impl)===(n=t.impl)||i.evaluate===n.evaluate&&i.meta===n.meta&&i.origin.name===n.origin.name&&i.origin.typeOrAlias===n.origin.typeOrAlias}}),O=s.createBuilder(`${m}/value`,{build:f,getKey:e=>`value::${e.entityOrAlias}::${e.name}`,compare:(e,t)=>e.valueKey===t.valueKey&&e.code===t.code}),b={},j=!1,k=new Set,$=new Set,M=new Set;for(let[e,t]of i.expressions.expressions)for(let[,i]of t){let t=x[String(e)]??[String(e)];if(r(i.implementation)){let n={entityOrAlias:String(e),name:String(i.name),kind:i.implementation.kind,params:i.implementation.params,aliasMap:x,invariantImplementations:d},a=S.build(n);for(let e of(a.changed&&(j=!0),k.add(S.getKey(n)),t))b[e]||(b[e]={}),b[e][String(i.name)]=a.output;continue}if("value"===i.implementation.kind){let a=i.implementation.value,r={entityOrAlias:String(e),name:String(i.name),valueKey:n(a),plan:i.implementation.plan,code:c},o=O.build(r);for(let e of(o.changed&&(j=!0),M.add(O.getKey(r)),t))b[e]||(b[e]={}),b[e][String(i.name)]=o.output;continue}}for(let[e,t]of Object.entries(v))for(let[i,n]of Object.entries(t)){let t={entityType:e,name:i,impl:n},a=h.build(t);a.changed&&(j=!0),$.add(h.getKey(t)),b[e]||(b[e]={}),b[e][i]=a.output}S.cleanup(k)&&(j=!0),h.cleanup($)&&(j=!0),O.cleanup(M)&&(j=!0);let A=[];for(let[e,t]of i.expressions.entityExpressions)for(let n of t.shapeGroups){let t=i.expressions.expressions.get(n);if(t)for(let[i]of t)b[String(e)]?.[String(i)]||A.push({entityType:String(e),exprName:String(i)})}return A.length>0?(A.forEach(e=>y.add(new a({code:"MISSING_IMPLEMENTATION",origin:null,problem:`Missing implementation of expression ${e.entityType}.${e.exprName}`,fix:"The spec declares it without a value of its own ($eval, $msg or a read), so a project file implements it: a default export of phx.domain.implementCustomExpressions({ ... }) in src/expressions/, or of phx.domain.admin.implementCustomExpressions({ ... }) in src/admin/expressions/ for an admin entity type. Implement it, or remove the declaration from the spec."}))),{ok:!1,missing:A}):{ok:!0,runtime:t({merged:b,changed:j})}};

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

@@ -0,0 +1,33 @@
+import type { SelfAccessor } from '../../enhanced-json/index.js';
+import type { MemoEvalPlan } from '../../expressions/index.js';
+import { type SpecCodeMap } from '../spec-code/index.js';
+/**
+ * Runtime counterpart to
+ * {@link ../../code/templates/domain-spec/generate-memo-eval-plan-code#generateMemoEvalPlanCode | generateMemoEvalPlanCode}.
+ * Produces a `(self) => value` reader function that evaluates each dep against
+ * `self` and splices the resulting values into the plan's template tree:
+ *
+ * - Static (no deps): evaluates the template once and returns a `() => cached`
+ *   thunk — no allocation per call. (Codegen emits a zero-dep `memoEval` for the
+ *   same case so contextual typing reaches the body; the stability contract is
+ *   identical.)
+ * - With deps: wraps the per-dep resolution in `memoEval` so equal dep arrays
+ *   short-circuit to the cached body, matching codegen semantics exactly.
+ *
+ * Each `$eval` dep is the closure the generated code module holds under its spec code id
+ * (`<key>#<n>`, `key` naming the expression or component the plan belongs to), or its text
+ * compiled with `new Function` when there is no such closure; each `$target` dep reads
+ * `self[target]` verbatim. `$msg` markers inside the
+ * template lower to `{ id?, message }` descriptors for i18n consumers.
+ */
+type MemoEvalPlanRuntimeReader = (self: SelfAccessor, state?: unknown, ctx?: unknown) => unknown;
+export declare const generateMemoEvalPlanRuntime: (plan: MemoEvalPlan, key: string, code: SpecCodeMap | undefined) => MemoEvalPlanRuntimeReader;
+/**
+ * Runtime counterpart to
+ * {@link ../../code/templates/domain-spec/generate-static-value-code#generateStaticValueCode | generateStaticValueCode}:
+ * evaluates a self-free plan once to the plain value a module-level constant holds. Plans that read
+ * `self` need an entity instance and are rejected. `key` and `code` resolve its `$eval` code as in
+ * {@link generateMemoEvalPlanRuntime}.
+ */
+export declare const evaluateStaticMemoEvalPlan: (plan: MemoEvalPlan, key: string, code: SpecCodeMap | undefined) => unknown;
+export {};

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

@@ -0,0 +1 @@
+import{memoEval as e}from"../../../utils/index.js";import{createMessageDescriptor as t}from"../../markers/index.js";import{specCodeEvalIds as r}from"../../runtime-spec/index.js";import{resolveSpecCode as a}from"../spec-code/index.js";let n=(e,r)=>{if("literal"===e.kind)return e.value;if("slot"===e.kind)return r[e.depIndex];if("msg"===e.kind)return t(e.marker);if("array"===e.kind)return e.items.map(e=>n(e,r));let a={};for(let[t,l]of e.entries)a[t]=n(l,r);return a};export const generateMemoEvalPlanRuntime=(t,l,i)=>{if(0===t.deps.length){let e=n(t.template,[]);return()=>e}let s=r(t,l),o=t.deps.map((e,t)=>{let r=s[t];return"eval"===e.kind&&void 0!==r?a(i,r,e.code):void 0});return e(e=>t.deps.map((t,r)=>"eval"===t.kind?o[r](e):Reflect.get(e,t.target)),(...e)=>n(t.template,e))};export const evaluateStaticMemoEvalPlan=(e,t,l)=>{if(e.usesSelf)throw Error("Cannot evaluate a plan that uses self as a static value. Filter self-dependent plans before evaluating constants.");let i=r(e,t),s=e.deps.map((e,t)=>{if("read"===e.kind)throw Error(`Cannot evaluate the self-dependent read "${e.target}" as a static value. Filter self-dependent plans before evaluating constants.`);return a(l,i[t],e.code)()});return n(e.template,s)};

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

@@ -0,0 +1,3 @@
+export { ExpressionRuntime, type ExpressionImplementations, type InvariantImplementations, type MissingExpression, } from './expression-runtime.js';
+export { evaluateStaticMemoEvalPlan, generateMemoEvalPlanRuntime } from './generate-memo-eval-plan-runtime.js';
+export { evaluateReflectionConstants, findReflectionConstants } from './reflection-constants-runtime.js';

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

@@ -0,0 +1 @@
+export{ExpressionRuntime}from"./expression-runtime.js";export{evaluateStaticMemoEvalPlan,generateMemoEvalPlanRuntime}from"./generate-memo-eval-plan-runtime.js";export{evaluateReflectionConstants,findReflectionConstants}from"./reflection-constants-runtime.js";

package/dist/domain/spec/runtime/expressions/reflection-constants-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { Expressions, MemoEvalPlan } from '../../expressions/index.js';
+import type { ExpressionName } from '../../model/index.js';
+import type { SpecCodeMap } from '../spec-code/index.js';
+/** The self-free `constants:` plans declared on one entity or alias, or `undefined` when it has none. */
+export declare const findReflectionConstants: (expressions: Expressions, entityOrAlias: string) => ReadonlyMap<ExpressionName, MemoEvalPlan> | undefined;
+/**
+ * Runtime counterpart of the constants literal codegen passes to an enhanced reflection: the
+ * entity's or alias's self-free `constants:` values evaluated once to plain values, keyed by name.
+ * Their `$eval` code comes from `code` when the generated code module holds it.
+ */
+export declare const evaluateReflectionConstants: (expressions: Expressions, entityOrAlias: string, code: SpecCodeMap | undefined) => Readonly<Record<string, unknown>>;

package/dist/domain/spec/runtime/expressions/reflection-constants-runtime.js

@@ -0,0 +1 @@
+import{specCodeExpressionKey as t}from"../../runtime-spec/index.js";import{evaluateStaticMemoEvalPlan as n}from"./generate-memo-eval-plan-runtime.js";export const findReflectionConstants=(t,n)=>{for(let[e,o]of t.constants)if(String(e)===n)return o};export const evaluateReflectionConstants=(e,o,r)=>{let i=findReflectionConstants(e,o);return i?Object.fromEntries([...i].map(([e,i])=>[String(e),n(i,t(o,String(e)),r)])):{}};

package/dist/domain/spec/runtime/factory-data/factory-data-runtime.d.ts

@@ -0,0 +1,44 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { AnyEntityReflections, DomainEntity, DomainEntityReflection } from '../../../core/index.js';
+import type { Invariants } from '../../invariants/index.js';
+import type { Defaults } from '../../model/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+import { type RecipeDefaults } from './recipe-defaults.js';
+import { type StaticViolations } from './static-violations.js';
+interface FactoryDataRuntimeFields {
+    /**
+     * The member types of each alias: what `phx.domain.attachComponent` expands an alias with, and
+     * what `phx.domain.createRecipe` expands alias defaults with.
+     */
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    /** The entity reflections `phx.domain.createRecipe` validates the defaults with. */
+    readonly entityReflections: ReadonlyArray<DomainEntityReflection<DomainEntity<string>>>;
+    /** The violations `phx.domain.implementCustomInvariants` reports for a static invariant that fails. */
+    readonly staticViolations: StaticViolations;
+    /** The defaults `phx.domain.createRecipe` puts into a new recipe. */
+    readonly defaults: RecipeDefaults;
+    readonly changed: boolean;
+}
+/**
+ * The data the `phx.domain` factories of one domain carry, built from the parsed spec: the static
+ * violations of `implementCustomInvariants`, the aliases of `attachComponent`, and the aliases,
+ * entity reflections and defaults of `createRecipe`. Generated `domain-spec.ts` passes the same
+ * values to those factories as literals; with this section the factories can be built from the
+ * spec instead. The configurator and the admin domain each have one.
+ */
+export type FactoryDataRuntime = Branded<'FactoryDataRuntime', FactoryDataRuntimeFields>;
+interface FactoryDataRuntimeInput {
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    readonly entities: AnyEntityReflections;
+}
+interface FactoryDataRuntimeProps extends FactoryDataRuntimeInput {
+    readonly referenceScope: string;
+}
+/**
+ * Builds the factory data of one domain. The result keeps its reference while the invariants and
+ * defaults are equal and the model runtime's aliases and entity reflections are the same objects.
+ */
+export declare const FactoryDataRuntime: (referenceStore: RuntimeReferenceStore, props: FactoryDataRuntimeProps) => FactoryDataRuntime;
+export {};

package/dist/domain/spec/runtime/factory-data/factory-data-runtime.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{createRecipeDefaults as i}from"./recipe-defaults.js";import{createStaticViolations as s}from"./static-violations.js";let a=e=>({aliases:e.aliases,entityReflections:Object.values(e.entities),staticViolations:s(e.invariants),defaults:i(e.defaults)});export const FactoryDataRuntime=(i,s)=>{let n=i.createBuilder(s.referenceScope,{build:a,getKey:()=>"singleton",compare:(t,i)=>t.aliases===i.aliases&&t.entities===i.entities&&e(t.invariants.entries,i.invariants.entries)&&e(t.defaults.entries,i.defaults.entries)}).build({invariants:s.invariants,defaults:s.defaults,aliases:s.aliases,entities:s.entities});return t({...n.output,changed:n.changed})};

package/dist/domain/spec/runtime/factory-data/index.d.ts

@@ -0,0 +1,3 @@
+export { FactoryDataRuntime } from './factory-data-runtime.js';
+export type { RecipeDefaults } from './recipe-defaults.js';
+export type { StaticViolations } from './static-violations.js';

package/dist/domain/spec/runtime/factory-data/index.js

@@ -0,0 +1 @@
+export{FactoryDataRuntime}from"./factory-data-runtime.js";

package/dist/domain/spec/runtime/factory-data/recipe-defaults.d.ts

@@ -0,0 +1,13 @@
+import type { Defaults } from '../../model/index.js';
+/**
+ * The default property values of each entity type, keyed by entity type: what
+ * `phx.domain.createRecipe` puts into a new recipe before the caller's overrides. Alias entries are
+ * already expanded to their member types by the parser.
+ */
+export type RecipeDefaults = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * The runtime counterpart of the `defaults` literal the generated `domain-spec.ts` passes to
+ * `createRecipeFactory`: the parsed per-entity defaults with every `$msg` lowered to the descriptor
+ * the `msg` macro produces.
+ */
+export declare const createRecipeDefaults: (defaults: Defaults) => RecipeDefaults;

package/dist/domain/spec/runtime/factory-data/recipe-defaults.js

@@ -0,0 +1 @@
+import{createMessageDescriptor as e,isEvalMarker as t,isMsgMarker as r}from"../../markers/index.js";let s=(a,i)=>{if(null===a||"object"!=typeof a)return a;if(r(a))return e(a);if(t(a))throw Error(`The default at ${i} is an $eval expression. Defaults are static values; the parser rejects $eval in them, so the spec given to the runtime was not produced by it. Parse the spec again and pass the result.`);return Array.isArray(a)?a.map((e,t)=>s(e,`${i}[${t}]`)):Object.fromEntries(Object.entries(a).map(([e,t])=>[e,s(t,`${i}.${e}`)]))};export const createRecipeDefaults=e=>Object.fromEntries(Object.entries(e.entries).map(([e,t])=>[e,Object.fromEntries(Object.entries(t).map(([t,r])=>[t,s(r,`${e}.${t}`)]))]));

package/dist/domain/spec/runtime/factory-data/static-violations.d.ts

@@ -0,0 +1,16 @@
+import type { Violation } from '../../../core/index.js';
+import type { Invariants } from '../../invariants/index.js';
+/**
+ * The violation each static invariant of a domain reports when its implementation returns `false`,
+ * by entity type or alias and by invariant name. `phx.domain.implementCustomInvariants` closes over
+ * it: a project implements a static invariant as a boolean and the factory turns `false` into this
+ * violation.
+ */
+export type StaticViolations = Readonly<Record<string, Readonly<Record<string, Violation<string>>>>>;
+/**
+ * The runtime counterpart of the `staticViolations` literal the generated `domain-spec.ts` passes
+ * to `createCustomInvariantFactory`: one entry per static invariant, keyed as the spec declares it,
+ * with a `$msg` message lowered to the descriptor the `msg` macro produces. Types and aliases
+ * without a static invariant have no entry.
+ */
+export declare const createStaticViolations: (invariants: Invariants) => StaticViolations;

package/dist/domain/spec/runtime/factory-data/static-violations.js

@@ -0,0 +1 @@
+import{createMessageDescriptor as t}from"../../markers/index.js";export const createStaticViolations=e=>{let i={};for(let[o,r]of Object.entries(e.entries))for(let e of Object.values(r)){if("static"!==e.kind)continue;let r={type:String(e.violationType),severity:e.severity,message:"string"==typeof e.message?e.message:t(e.message),...void 0===e.controlViolationPriority?{}:{controlViolationPriority:e.controlViolationPriority}};i[o]={...i[o],[String(e.name)]:r}}return i};

package/dist/domain/spec/runtime/generate-runtime-instance.d.ts

@@ -0,0 +1,2 @@
+import { ApplicationInstance } from '../application/index.js';
+export declare const generateRuntimeInstance: (applicationInstance: ApplicationInstance) => ApplicationInstance;

package/dist/domain/spec/runtime/generate-runtime-instance.js

@@ -0,0 +1 @@
+import{ApplicationInstance as n}from"../application/index.js";export const generateRuntimeInstance=e=>n(e.applicationVersion);

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

@@ -0,0 +1,13 @@
+export { ApplicationRuntime, type ApplicationRuntimeResult } from './application-runtime.js';
+export { applicationSpecSlice, type ApplicationSpecSliceModules } from './application-spec-slice.js';
+export { type ApplicationModules, createApplication } from './create-application.js';
+export { generateRuntimeInstance } from './generate-runtime-instance.js';
+export { SpecRuntime } from './spec-runtime.js';
+export * from './expressions/index.js';
+export * from './factory-data/index.js';
+export * from './migrations/index.js';
+export * from './model/index.js';
+export * from './optics/index.js';
+export * from './runtime-reference-store.js';
+export * from './sections/index.js';
+export * from './spec-code/index.js';

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

@@ -0,0 +1 @@
+export{ApplicationRuntime}from"./application-runtime.js";export{applicationSpecSlice}from"./application-spec-slice.js";export{createApplication}from"./create-application.js";export{generateRuntimeInstance}from"./generate-runtime-instance.js";export{SpecRuntime}from"./spec-runtime.js";export*from"./expressions/index.js";export*from"./factory-data/index.js";export*from"./migrations/index.js";export*from"./model/index.js";export*from"./optics/index.js";export*from"./runtime-reference-store.js";export*from"./sections/index.js";export*from"./spec-code/index.js";

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

@@ -0,0 +1 @@
+export { MigrationRuntime, type MigrationModules } from './migration-runtime.js';

package/dist/domain/spec/runtime/migrations/index.js

@@ -0,0 +1 @@
+export{MigrationRuntime}from"./migration-runtime.js";

package/dist/domain/spec/runtime/migrations/migration-runtime.d.ts

@@ -0,0 +1,53 @@
+import { Branded } from '@salsita-ai/common/utils';
+import { type AnyEntityReflections, type DomainEntity, type MigrateFunction, type Migration } from '../../../core/index.js';
+import type { RuntimeResolvedVersions } from '../../runtime-spec/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+type AnyEntity = DomainEntity<string>;
+type AnyMigration = Migration<AnyEntity, AnyEntity>;
+/**
+ * The project's migration modules, keyed by the project path the parser records for each model
+ * version (`src/migrations/v2.ts`, `src/admin/migrations/v2.ts`), each holding the module's exports.
+ * The module of version `N` exports the migration to that version as `migrateToV<N>`, the name the
+ * generated `domain.ts` imports.
+ */
+export type MigrationModules = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+interface MigrationRuntimeFields {
+    /** The entity reflections of each model version, keyed by version; the latest is the domain's own. */
+    readonly modelVersions: Readonly<Record<number, AnyEntityReflections>>;
+    /** The migration to each version, keyed by the version it yields. */
+    readonly migrations: Readonly<Record<number, AnyMigration>>;
+    readonly migrate: MigrateFunction<AnyEntity>;
+    /**
+     * The migrations the spec declares but the migration modules do not provide, as
+     * `<migration file>#migrateToV<N>`. A state that needs one fails to load with a
+     * `StateMigrationError` naming the missing step.
+     */
+    readonly missingMigrations: readonly string[];
+    readonly changed: boolean;
+}
+/**
+ * How a domain migrates a stored state of any of its model versions to the latest one: the entity
+ * reflections of every version, the project's migration to each version above the first, and the
+ * migrate function built from both, which `DomainBuilder.withMigrate` takes.
+ *
+ * The configurator and the admin domain each have one. The admin domain's factory first applies the
+ * SDK's own migration of the common admin entities (`migrateCommonAdminDomain`) and then this one.
+ */
+export type MigrationRuntime = Branded<'MigrationRuntime', MigrationRuntimeFields>;
+interface MigrationRuntimeInput {
+    readonly resolvedVersions: RuntimeResolvedVersions;
+    readonly latestEntities: AnyEntityReflections;
+    readonly migrationModules: MigrationModules;
+}
+interface MigrationRuntimeProps extends MigrationRuntimeInput {
+    readonly referenceScope: string;
+}
+/**
+ * Builds a domain's migrations from its resolved model versions and the project's migration
+ * modules: the runtime counterpart of the `modelVersions` literal of the generated `domain-spec.ts`
+ * and the `createMigrateFunction(...)` call of the generated `domain.ts`. The latest version uses the
+ * domain's own entity reflections, as generated code does. The result keeps its reference while
+ * the versions, the latest reflections and the migration modules stay the same.
+ */
+export declare const MigrationRuntime: (referenceStore: RuntimeReferenceStore, props: MigrationRuntimeProps) => MigrationRuntime;
+export {};

package/dist/domain/spec/runtime/migrations/migration-runtime.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as i}from"@salsita-ai/common/utils";import{DomainEntityReflection as t,createMigrateFunction as s}from"../../../core/index.js";let o=e=>"function"==typeof e,r=e=>`migrateToV${e}`,n=e=>{let{resolvedVersions:i,latestEntities:n,migrationModules:l}=e,a={},m={},d=[];for(let e of i.versionedModels){if(e.isLatest)a[e.version]=n;else{let i={};for(let s of e.modelVersion.entitySchemas)i[String(s.entityType)]=new t(String(s.entityType),[s.shapeSchema]);a[e.version]=i}if(void 0===e.migrationFile)continue;let i=r(e.version),s=l[e.migrationFile]?.[i];o(s)?m[e.version]=s:d.push(`${e.migrationFile}#${i}`)}return{modelVersions:a,migrations:m,migrate:s(a,i.latestVersion,m),missingMigrations:d}},l=e=>e.versionedModels.map(e=>({version:e.version,isLatest:e.isLatest,migrationFile:e.migrationFile,schemas:e.isLatest?[]:e.modelVersion.entitySchemas.map(e=>e.shapeSchema)})),a=(i,t)=>i.latestEntities===t.latestEntities&&i.resolvedVersions.latestVersion===t.resolvedVersions.latestVersion&&e(l(i.resolvedVersions),l(t.resolvedVersions))&&i.resolvedVersions.versionedModels.every(e=>void 0===e.migrationFile||i.migrationModules[e.migrationFile]===t.migrationModules[e.migrationFile]);export const MigrationRuntime=(e,t)=>{let s=e.createBuilder(t.referenceScope,{build:n,getKey:()=>"singleton",compare:a}).build({resolvedVersions:t.resolvedVersions,latestEntities:t.latestEntities,migrationModules:t.migrationModules});return i({...s.output,changed:s.changed})};

package/dist/domain/spec/runtime/model/admin-model-runtime.d.ts

@@ -0,0 +1,31 @@
+import { Branded } from '@salsita-ai/common/utils';
+import { type $DomainEntity, $DomainEntityReflection, type DomainEntity, DomainEntityReflection, RawAliasReflection, SchemaReflection } from '../../../core/index.js';
+import { DomainBuilder } from '../../../domain-builder/index.js';
+import type { Expressions } from '../../expressions/index.js';
+import type { RuntimeDataSchemas, RuntimeModelVersion, RuntimeResolvedVersions } from '../../runtime-spec/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+import type { SpecCodeMap } from '../spec-code/index.js';
+type AnyEntity = DomainEntity<string>;
+type AnyAliases = Record<string, AnyEntity>;
+type AnyData = Record<string, unknown>;
+type Any$Map = Record<AnyEntity['type'], $DomainEntity<AnyEntity>>;
+type AnyDomainBuilder = DomainBuilder<AnyEntity, AnyEntity, AnyAliases, Any$Map, AnyData, AnyData, AnyData>;
+interface AdminModelRuntimeSpec {
+    readonly expressions: Expressions;
+    readonly latestModel: RuntimeModelVersion;
+    readonly resolvedVersions: RuntimeResolvedVersions;
+}
+interface AdminModelRuntimeFields {
+    readonly entities: Record<string, DomainEntityReflection<AnyEntity>>;
+    readonly aliasReflections: Record<string, RawAliasReflection<AnyEntity>>;
+    readonly commonTypeReflections: Record<string, SchemaReflection<unknown>>;
+    readonly aliases: Record<string, readonly string[]>;
+    readonly $entityReflections: Record<string, $DomainEntityReflection<$DomainEntity<AnyEntity>>>;
+    readonly rootEntityTypes: readonly string[];
+    readonly modelVersion: number;
+    readonly domainBuilder: AnyDomainBuilder;
+    readonly schemaChanged: boolean;
+}
+export type AdminModelRuntime = Branded<'AdminModelRuntime', AdminModelRuntimeFields>;
+export declare const AdminModelRuntime: (domainSpec: AdminModelRuntimeSpec, dataSchemas: RuntimeDataSchemas, referenceStore: RuntimeReferenceStore, code: SpecCodeMap | undefined) => AdminModelRuntime;
+export {};

package/dist/domain/spec/runtime/model/admin-model-runtime.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{$DomainEntityReflection as s,DomainEntityReflection as a,RawAliasReflection as i,SchemaReflection as n}from"../../../core/index.js";import{DomainBuilder as o}from"../../../domain-builder/index.js";import{evaluateReflectionConstants as r,findReflectionConstants as m}from"../expressions/index.js";let l=e=>({latestVersion:e.resolvedVersions.latestVersion,versionedModels:e.resolvedVersions.versionedModels.map(e=>({version:e.version,key:e.key,isLatest:e.isLatest,migrationFile:e.migrationFile}))}),p=e=>{let t=[];for(let[s,a]of e.expressions.entityExpressions)t.push({entityType:String(s),shapeGroups:a.shapeGroups.map(String),expressionNamesByGroup:a.shapeGroups.map(t=>{let s=e.expressions.expressions.get(t);return{group:String(t),names:s?[...s.keys()].map(String):[]}}),constants:[...m(e.expressions,String(s))??[]].map(([e,t])=>[String(e),t])});return t},d=(t,s)=>{let a,i;return t.code===s.code&&(a=t.domainSpec,i=s.domainSpec,e(a.latestModel.entitySchemas.map(e=>e.shapeSchema),i.latestModel.entitySchemas.map(e=>e.shapeSchema))&&e([...a.latestModel.aliases],[...i.latestModel.aliases])&&e([...a.latestModel.commonTypes],[...i.latestModel.commonTypes])&&e(l(a),l(i))&&e(p(a),p(i)))&&e(t.dataSchemas.publishedData.runtimeSchema,s.dataSchemas.publishedData.runtimeSchema)&&e(t.dataSchemas.sessionData.runtimeSchema,s.dataSchemas.sessionData.runtimeSchema)&&e(t.dataSchemas.frontendData.runtimeSchema,s.dataSchemas.frontendData.runtimeSchema)},S=e=>{let{latestModel:t,resolvedVersions:m,expressions:l}=e.domainSpec,p={};for(let e of t.entitySchemas)p[String(e.entityType)]=new a(String(e.entityType),[e.shapeSchema]);let d={};for(let[e,s]of t.commonTypes){let t=s.runtimeSchema;d[String(e)]=new n(String(e),t)}let S=[...t.aliases],c={},h={};for(let[e,t]of S){let s=t.map(e=>p[String(e)]),a=new i(String(e),s);c[String(e)]=a,h[String(e)]=a.types}let u={};for(let a of t.entityTypes){let t=String(a),i=l.entityExpressions.get(a),n=[];if(i)for(let e of i.shapeGroups){let t=l.expressions.get(e);t&&n.push(...t.keys())}u[t]=new s(t,n,r(l,t,e.code))}let y=S.map(([e])=>String(e)).includes("RootEntity")?"RootEntity":"AnyDomainEntity",g=c[y]?.types??[],f=m.latestVersion,x=e.dataSchemas.publishedData.runtimeSchema,D=e.dataSchemas.sessionData.runtimeSchema,M=e.dataSchemas.frontendData.runtimeSchema,v=o.from(p,h,u,g,f,x,D,M,void 0,!0);return{entities:p,aliasReflections:c,commonTypeReflections:d,aliases:h,$entityReflections:u,rootEntityTypes:g,modelVersion:f,domainBuilder:v}};export const AdminModelRuntime=(e,s,a,i)=>{let n=a.createBuilder("modelRuntime:admin",{build:S,getKey:()=>"singleton",compare:d}).build({domainSpec:e,dataSchemas:s,code:i});return t({...n.output,schemaChanged:n.changed})};

package/dist/domain/spec/runtime/model/configurator-model-runtime.d.ts

@@ -0,0 +1,33 @@
+import { Branded } from '@salsita-ai/common/utils';
+import { type $DomainEntity, $DomainEntityReflection, type DomainEntity, DomainEntityReflection, RawAliasReflection, SchemaReflection } from '../../../core/index.js';
+import { DomainBuilder } from '../../../domain-builder/index.js';
+import type { Expressions } from '../../expressions/index.js';
+import type { RuntimeDataSchemas, RuntimeModelVersion, RuntimeResolvedVersions } from '../../runtime-spec/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+import type { SpecCodeMap } from '../spec-code/index.js';
+type AnyEntity = DomainEntity<string>;
+type AnyAliases = Record<string, AnyEntity>;
+type AnyData = Record<string, unknown>;
+type Any$Map = Record<AnyEntity['type'], $DomainEntity<AnyEntity>>;
+type AnyDomainBuilder = DomainBuilder<AnyEntity, AnyEntity, AnyAliases, Any$Map, AnyData, AnyData, AnyData>;
+interface ConfiguratorModelRuntimeSpec {
+    readonly dataSchemas: RuntimeDataSchemas;
+    readonly expressions: Expressions;
+    readonly latestModel: RuntimeModelVersion;
+    readonly resolvedVersions: RuntimeResolvedVersions;
+}
+interface ConfiguratorModelRuntimeFields {
+    readonly entities: Record<string, DomainEntityReflection<AnyEntity>>;
+    readonly aliasReflections: Record<string, RawAliasReflection<AnyEntity>>;
+    readonly commonTypeReflections: Record<string, SchemaReflection<unknown>>;
+    readonly aliases: Record<string, readonly string[]>;
+    readonly $entityReflections: Record<string, $DomainEntityReflection<$DomainEntity<AnyEntity>>>;
+    readonly rootEntityTypes: readonly string[];
+    readonly modelVersion: number;
+    readonly domainBuilder: AnyDomainBuilder;
+    readonly schemaChanged: boolean;
+}
+export type ConfiguratorModelRuntime = Branded<'ConfiguratorModelRuntime', ConfiguratorModelRuntimeFields>;
+export declare const isConfiguratorModelSchemaCompatible: (prev: ConfiguratorModelRuntimeSpec, curr: ConfiguratorModelRuntimeSpec) => boolean;
+export declare const ConfiguratorModelRuntime: (domainSpec: ConfiguratorModelRuntimeSpec, referenceStore: RuntimeReferenceStore, code: SpecCodeMap | undefined) => ConfiguratorModelRuntime;
+export {};

package/dist/domain/spec/runtime/model/configurator-model-runtime.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{$DomainEntityReflection as s,DomainEntityReflection as o,RawAliasReflection as i,SchemaReflection as n}from"../../../core/index.js";import{DomainBuilder as r}from"../../../domain-builder/index.js";import{evaluateReflectionConstants as a,findReflectionConstants as m}from"../expressions/index.js";let l=e=>({latestVersion:e.resolvedVersions.latestVersion,versionedModels:e.resolvedVersions.versionedModels.map(e=>({version:e.version,key:e.key,isLatest:e.isLatest,migrationFile:e.migrationFile}))}),p=e=>{let t=[];for(let[s,o]of e.expressions.entityExpressions)t.push({entityType:String(s),shapeGroups:o.shapeGroups.map(String),expressionNamesByGroup:o.shapeGroups.map(t=>{let s=e.expressions.expressions.get(t);return{group:String(t),names:s?[...s.keys()].map(String):[]}}),constants:[...m(e.expressions,String(s))??[]].map(([e,t])=>[String(e),t])});return t};export const isConfiguratorModelSchemaCompatible=(t,s)=>e(t.latestModel.entitySchemas.map(e=>e.shapeSchema),s.latestModel.entitySchemas.map(e=>e.shapeSchema))&&e([...t.latestModel.aliases],[...s.latestModel.aliases])&&e([...t.latestModel.commonTypes],[...s.latestModel.commonTypes])&&e(l(t),l(s))&&e(p(t),p(s))&&e(t.dataSchemas,s.dataSchemas);let d=e=>{let{latestModel:t,resolvedVersions:m,dataSchemas:l,expressions:p}=e.domainSpec,d={};for(let e of t.entitySchemas)d[String(e.entityType)]=new o(String(e.entityType),[e.shapeSchema]);let c={};for(let[e,s]of t.commonTypes){let t=s.runtimeSchema;c[String(e)]=new n(String(e),t)}let S=[...t.aliases],u={},g={};for(let[e,t]of S){let s=t.map(e=>d[String(e)]),o=new i(String(e),s);u[String(e)]=o,g[String(e)]=o.types}let h={};for(let o of t.entityTypes){let t=String(o),i=p.entityExpressions.get(o),n=[];if(i)for(let e of i.shapeGroups){let t=p.expressions.get(e);t&&n.push(...t.keys())}h[t]=new s(t,n,a(p,t,e.code))}let y=S.map(([e])=>String(e)).includes("RootEntity")?"RootEntity":"AnyDomainEntity",f=u[y]?.types??[],x=m.latestVersion,M=l.publishedData.runtimeSchema,b=l.sessionData.runtimeSchema,T=l.frontendData.runtimeSchema,v=l.backendData?.runtimeSchema,C=r.from(d,g,h,f,x,M,b,T,v,!1);return{entities:d,aliasReflections:u,commonTypeReflections:c,aliases:g,$entityReflections:h,rootEntityTypes:f,modelVersion:x,domainBuilder:C}};export const ConfiguratorModelRuntime=(e,s,o)=>{let i=s.createBuilder("modelRuntime:configurator",{build:d,getKey:()=>"singleton",compare:(e,t)=>e.code===t.code&&isConfiguratorModelSchemaCompatible(e.domainSpec,t.domainSpec)}).build({domainSpec:e,code:o});return t({...i.output,schemaChanged:i.changed})};

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

@@ -0,0 +1,2 @@
+export { AdminModelRuntime } from './admin-model-runtime.js';
+export { ConfiguratorModelRuntime, isConfiguratorModelSchemaCompatible } from './configurator-model-runtime.js';

package/dist/domain/spec/runtime/model/index.js

@@ -0,0 +1 @@
+export{AdminModelRuntime}from"./admin-model-runtime.js";export{ConfiguratorModelRuntime,isConfiguratorModelSchemaCompatible}from"./configurator-model-runtime.js";

package/dist/domain/spec/runtime/optics/build-sdk-optic.d.ts

@@ -0,0 +1,7 @@
+import { type ComponentEntry, type ComponentImplementation } from '../../components/index.js';
+import type { AdminModelRuntime, ConfiguratorModelRuntime } from '../model/index.js';
+import { type SpecCodeMap } from '../spec-code/index.js';
+import type { ComponentOptic } from './built-component-optic.js';
+export declare const buildSdkOptic: (entry: ComponentEntry, impl: ComponentImplementation & {
+    readonly kind: 'sdk';
+}, aliasMap: Record<string, readonly string[]>, configuratorModel: AdminModelRuntime | ConfiguratorModelRuntime, code: SpecCodeMap | undefined) => ComponentOptic;

package/dist/domain/spec/runtime/optics/build-sdk-optic.js

@@ -0,0 +1 @@
+import{Branded as t}from"@salsita-ai/common/utils";import{createAdminCustomPageRead as e,createAdminCustomSidebarRead as o,createAdminDataPageRead as i,createAdminDataTableSidebarRead as n,createAdminNavigationPanelRead as a,createAdminPresetCategoryPageRead as r,createAdminPresetCategorySelectionRead as s,createAdminPresetCategorySelectionWrite as m,createAdminPresetCategorySidebarRead as c,createAdminPresetListPageRead as p,createAdminPresetSidebarRead as d,createAdminRecipeCollectionPageRead as l,createAdminRecipeSidebarRead as f}from"../../../application/index.js";import{componentsByName as u}from"../../../available-system-components/index.js";import{DomainComponentOpticBuilder as h,composedOfComponent as g,createEmptyWrite as y,createMultipleCompositionRead as w,createMultipleReferenceRead as S,createMultipleReferenceWrite as N,createSingleCompositionRead as v,createSingleReferenceRead as x,createSingleReferenceWrite as A,referenceComponent as b}from"../../../core/index.js";import{adminSidebarComponent as j,attributeSelectionComponent as k,navigationPageComponent as O,navigationPanelListComponent as F}from"../../../system-components/index.js";import{FILTER_CRITERION_KEYS as R,isSdkCodeRef as $}from"../../components/index.js";import{specCodeComponentKey as E,specCodeFilterId as T}from"../../runtime-spec/index.js";import{resolveSpecCode as D}from"../spec-code/index.js";let K=new Map([["reference",b],["composedOf",g],["adminSidebar",j],["attributeSelection",k],["navigationPage",O],["navigationPanelList",F]]),M={createAdminCustomPageRead:e,createAdminCustomSidebarRead:o,createAdminDataPageRead:i,createAdminDataTableSidebarRead:n,createAdminNavigationPanelRead:a,createAdminPresetCategoryPageRead:r,createAdminPresetCategorySelectionRead:s,createAdminPresetCategorySelectionWrite:m,createAdminPresetCategorySidebarRead:c,createAdminPresetListPageRead:p,createAdminPresetSidebarRead:d,createAdminRecipeCollectionPageRead:l,createAdminRecipeSidebarRead:f,createEmptyWrite:y,createMultipleCompositionRead:w,createMultipleReferenceRead:S,createMultipleReferenceWrite:N,createSingleCompositionRead:v,createSingleReferenceRead:x,createSingleReferenceWrite:A},P=(t,e)=>{let o=M[t.sdkFunction];if("function"!=typeof o)throw Error(`SDK factory function "${t.sdkFunction}" not found. The spec names a factory that the factory map of build-sdk-optic.ts does not list. Add the factory to that map.`);return o(...t.params.map(t=>{if($(t)){let o=e.entities[t.$codeRef]??e.aliasReflections[t.$codeRef];if(!o)throw Error(`Reflection "${t.$codeRef}" not found in ModelRuntime. This is a bug — the target was validated at parse time.`);return o}return t}))};export const buildSdkOptic=(e,o,i,n,a)=>{let r=h.from(i),s=u.get(e.componentName)??K.get(e.componentName);if(!s)throw Error(`SDK component "${e.componentName}" not found. This is a bug — the component was validated at parse time.`);let m=r.withComponent(s,e.instanceName,!0),c=e.isAlias?m.withAlias(String(e.typeOrAlias)):m.withEntity(String(e.typeOrAlias)),p=E(String(e.typeOrAlias),String(e.instanceName),e.componentName);for(let[t,e]of o.filters.items.entries()){if("root"===e.kind){let t=e.target,o=e=>e[t];c=c.withFilter(o);continue}let o={};for(let i of R){let n=e[i];void 0!==n&&("dynamic"===n.kind?o[i]=t=>t[n.target]:"eval"===n.kind?o[i]=D(a,T(p,t,i,n.code),n.code):o[i]=n.value)}c=c.withGradualFilter(o)}let d=P(o.readFactory,n),l=P(o.writeFactory,n),f=c.attach(d,l);return t({typeOrAlias:String(e.typeOrAlias),componentName:e.componentName,instanceName:String(e.instanceName),optic:f})};

package/dist/domain/spec/runtime/optics/build-user-bound-optic.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentEntry, ComponentImplementation } from '../../components/index.js';
+import type { AdminModelRuntime, ConfiguratorModelRuntime } from '../model/index.js';
+import { type SpecCodeMap } from '../spec-code/index.js';
+import type { ComponentOptic } from './built-component-optic.js';
+export declare const buildUserBoundOptic: (entry: ComponentEntry, impl: ComponentImplementation & {
+    readonly kind: 'userBound';
+}, model: AdminModelRuntime | ConfiguratorModelRuntime, code: SpecCodeMap | undefined) => ComponentOptic | undefined;

package/dist/domain/spec/runtime/optics/build-user-bound-optic.js

@@ -0,0 +1 @@
+import{match as e}from"ts-pattern";import{Branded as t}from"@salsita-ai/common/utils";import{componentsByName as i}from"../../../available-system-components/index.js";import{DomainComponentOpticBuilder as n,assertBoolean as r,assertNumber as o,assertString as a}from"../../../core/index.js";import{specCodeComponentKey as s,specCodeFilterId as l}from"../../runtime-spec/index.js";import{generateMemoEvalPlanRuntime as m}from"../expressions/index.js";import{resolveSpecCode as d}from"../spec-code/index.js";let p=(e,t,i)=>{if("dynamic"===e.kind){let t=e.target;return e=>e[t]}if("eval"===e.kind){let n=l(i.componentKey,i.branch,t,e.code);return d(i.code,n,e.code)}return e.value},c=(e,t)=>{let i={};for(let[n,r]of Object.entries(e))"kind"!==n&&void 0!==r&&(i[n]=p(r,n,t));return i},f={assertString:a,assertNumber:o,assertBoolean:r},h=(e,t)=>{let i=t.commonTypeReflections[e]??t.entities[e]??t.aliasReflections[e];if(!i)throw Error(`Reflection "${e}" not found in ModelRuntime for write assertion. This is a bug — the type was resolved at parse time.`);return i},u=(e,t)=>{let i=t.entities[e]??t.aliasReflections[e];if(!i)throw Error(`Entity reflection "${e}" not found in ModelRuntime for write assertion. This is a bug — the type was resolved at parse time.`);return i},w=(t,i,n)=>e(t).with({kind:"primitive"},({assertFn:e})=>typeof i==("assertNumber"===e?"number":"assertBoolean"===e?"boolean":"string")).with({kind:"declaredType"},({typeName:e})=>h(e,n).is(i)).with({kind:"declaredTypeId"},({referencedType:e})=>u(e,n).isId(i)).with({kind:"literal"},({value:e})=>i===e).with({kind:"anyOf"},({assertions:e})=>e.some(e=>w(e,i,n))).with({kind:"none"},()=>!0).exhaustive(),y=(t,i,n)=>{e(t).with({kind:"primitive"},({assertFn:e})=>{f[e](i)}).with({kind:"declaredType"},({typeName:e})=>{h(e,n).assert(i)}).with({kind:"declaredTypeId"},({referencedType:e})=>{u(e,n).assertId(i)}).with({kind:"literal"},e=>{if(!w(e,i,n))throw Error(`Expected value to match its declared schema but got ${i}`)}).with({kind:"anyOf"},e=>{if(!w(e,i,n))throw Error(`Expected value to match one of its declared schemas but got ${i}`)}).with({kind:"none"},()=>{}).exhaustive()};export const buildUserBoundOptic=(e,r,o,a)=>{let l,d=(l=o.aliases,n.from(l)),p=i.get(e.componentName);if(!p)return void console.warn(`[ComponentOptic] Unknown component: ${e.componentName}`);let f=d.withComponent(p,e.instanceName,!0),h=e.isAlias?f.withAlias(String(e.typeOrAlias)):f.withEntity(String(e.typeOrAlias)),u=s(String(e.typeOrAlias),String(e.instanceName),e.componentName);for(let[e,t]of r.filters.items.entries()){if("root"===t.kind){let e=t.target,i=t=>t[e];h=h.withFilter(i);continue}h=h.withGradualFilter(c(t,{componentKey:u,branch:e,code:a}))}let w=m(r.plan,u,a),k="composite"===r.implementation.kind?r.implementation.writeBindings:[],g=k.length>0?e=>{let t={};for(let i of k)y(i.assertion,e[i.propKey],o),t[i.entityField]=e[i.propKey];return t}:()=>({}),v=h.attach(w,g);return t({typeOrAlias:String(e.typeOrAlias),componentName:e.componentName,instanceName:String(e.instanceName),optic:v})};

package/dist/domain/spec/runtime/optics/built-component-optic.d.ts

@@ -0,0 +1,11 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { DomainComponentOptic, SystemComponentTypeConstraint } from '../../../core/index.js';
+/** A component optic of any project, for any component type. */
+export type AnyComponentOptic = DomainComponentOptic<any, any, any, any, any, any, SystemComponentTypeConstraint>;
+/** A single built component optic with its identifying metadata. */
+export type ComponentOptic = Branded<'ComponentOptic', {
+    readonly typeOrAlias: string;
+    readonly componentName: string;
+    readonly instanceName: string;
+    readonly optic: AnyComponentOptic;
+}>;

package/dist/domain/spec/runtime/optics/built-component-optic.js

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

package/dist/domain/spec/runtime/optics/component-optic.d.ts

@@ -0,0 +1,26 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ComponentEntry } from '../../components/index.js';
+import type { AdminModelRuntime, ConfiguratorModelRuntime } from '../model/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+import type { SpecCodeMap } from '../spec-code/index.js';
+import type { ComponentOptic } from './built-component-optic.js';
+/** Collection of built component optics with change tracking. */
+export type ComponentOptics = Branded<'ComponentOptics', {
+    readonly optics: readonly ComponentOptic[];
+    readonly changed: boolean;
+}>;
+interface ComponentOpticsProps {
+    readonly referenceScope: string;
+    readonly components: readonly ComponentEntry[];
+    readonly modelRuntime: AdminModelRuntime | ConfiguratorModelRuntime;
+    /** The domain's map of the generated code module, which holds the entries' `$eval` code. */
+    readonly code: SpecCodeMap | undefined;
+}
+/**
+ * Builds component optics from the unified ComponentEntry[] on ApplicationSpec.
+ * Dispatches on `entry.implementation.kind` — userBound (YAML) or sdk (factory-based).
+ * Uses RuntimeReferenceStore to preserve each optic reference by
+ * `typeOrAlias::componentName::instanceName`.
+ */
+export declare const ComponentOptics: (referenceStore: RuntimeReferenceStore, props: ComponentOpticsProps) => ComponentOptics;
+export {};

package/dist/domain/spec/runtime/optics/component-optic.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";import{match as t}from"ts-pattern";import{Branded as o}from"@salsita-ai/common/utils";import{buildSdkOptic as i}from"./build-sdk-optic.js";import{buildUserBoundOptic as n}from"./build-user-bound-optic.js";export const ComponentOptics=(t,i)=>{let n=t.createBuilder(i.referenceScope,{build:({entry:e,modelRuntime:t,code:o})=>m(e,t,o),getKey:({entry:e})=>`${e.implementation.kind}::${e.typeOrAlias}::${e.componentName}::${e.instanceName}`,compare:(t,o)=>t.modelRuntime.domainBuilder===o.modelRuntime.domainBuilder&&t.code===o.code&&e(t.entry.implementation,o.entry.implementation)}),d=[],r=new Set,l=!1;for(let e of i.components){let t={entry:e,modelRuntime:i.modelRuntime,code:i.code},o=n.build(t);o.output&&d.push(o.output),r.add(n.getKey(t)),o.changed&&(l=!0)}return n.cleanup(r)&&(l=!0),o({optics:d,changed:l})};let m=(e,o,m)=>t(e.implementation).with({kind:"userBound"},t=>n(e,t,o,m)).with({kind:"sdk"},t=>i(e,t,o.aliases,o,m)).exhaustive();

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

@@ -0,0 +1,2 @@
+export type { ComponentOptic } from './built-component-optic.js';
+export { ComponentOptics } from './component-optic.js';

package/dist/domain/spec/runtime/optics/index.js

@@ -0,0 +1 @@
+export{ComponentOptics}from"./component-optic.js";

package/dist/domain/spec/runtime/runtime-reference-store.d.ts

@@ -0,0 +1,46 @@
+interface BuilderOptions<T, R> {
+    readonly build: (input: T) => R;
+    readonly getKey: (input: T) => string;
+    readonly compare: (previous: T, current: T) => boolean;
+}
+/**
+ * A scoped builder that stabilizes the outputs for one application-spec concern.
+ * Builds individual items, reusing the previous output when its input is equivalent.
+ * Call `cleanup()` after processing all items to remove references that are no longer active.
+ */
+export interface ScopedBuilder<T, R> {
+    /** Build or retrieve a stable item. Returns the output and whether its reference changed. */
+    readonly build: (input: T) => {
+        readonly output: R;
+        readonly changed: boolean;
+    };
+    /** Remove references for keys not in the provided set. Returns true if any were removed. */
+    readonly cleanup: (activeKeys: ReadonlySet<string>) => boolean;
+    /** Extract the store key for an input (same function as provided in options). */
+    readonly getKey: (input: T) => string;
+}
+/**
+ * Preserves generated object references between sequential application-spec builds.
+ * Each named scope owns the previous inputs and outputs for one parsing or runtime concern.
+ * Equivalent inputs reuse the previous output reference; changed inputs replace it and report
+ * `changed: true` so consumers can reconcile only the affected runtime registrations.
+ *
+ * Thread one `RuntimeReferenceStore` through the full parse and runtime-generation pipeline.
+ * The store is stateful pipeline infrastructure, not an optional performance cache.
+ */
+export declare class RuntimeReferenceStore {
+    private readonly scopes;
+    /**
+     * Creates a builder for one reference-stability scope.
+     * Calling with the same scope name returns a builder backed by the same stored references.
+     *
+     * @param scope - Unique scope name (for example `componentOptics` or `transformers`)
+     * @param options.build - Builds a single output from an input
+     * @param options.getKey - Extracts the stable identity of an input within the scope
+     * @param options.compare - Returns true when the previous output reference can be reused
+     */
+    createBuilder<T, R>(scope: string, options: BuilderOptions<T, R>): ScopedBuilder<T, R>;
+    /** Clears all stored references. Use when the pipeline must force a complete rebuild. */
+    clear(): void;
+}
+export {};

package/dist/domain/spec/runtime/runtime-reference-store.js

@@ -0,0 +1 @@
+export class RuntimeReferenceStore{scopes=new Map;createBuilder(e,t){let{build:s,getKey:r,compare:l}=t;this.scopes.has(e)||this.scopes.set(e,new Map);let u=this.scopes.get(e);return{build:e=>{let t=r(e),c=u.get(t);if(c&&l(c.input,e))return{output:c.output,changed:!1};let o=s(e);return u.set(t,{input:e,output:o}),{output:o,changed:!0}},cleanup:e=>{let t=!1;for(let s of u.keys())e.has(s)||(u.delete(s),t=!0);return t},getKey:r}}clear(){for(let e of this.scopes.values())e.clear()}}

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

@@ -0,0 +1,14 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ActionDefinitions } from '../../../core/index.js';
+import type { Actions } from '../../sections/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+/**
+ * The declared actions as the runtime spec slice holds them, with change tracking: the definitions
+ * are rebuilt only when their declaration changes, so a hot reload of an unrelated section keeps
+ * the action system's compiled validators.
+ */
+export type ActionsRuntime = Branded<'ActionsRuntime', {
+    readonly definitions: ActionDefinitions;
+    readonly changed: boolean;
+}>;
+export declare const ActionsRuntime: (actions: Actions, referenceStore: RuntimeReferenceStore) => ActionsRuntime;

package/dist/domain/spec/runtime/sections/assistant-runtime.d.ts

@@ -0,0 +1,10 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { RuntimeSpec } from '../../runtime-spec/index.js';
+import type { AssistantResolvedManifest } from '../../sections/index.js';
+import type { RuntimeReferenceStore } from '../runtime-reference-store.js';
+/** Resolved assistant manifest with change tracking, carried to the runtime spec on hot reload. */
+export type AssistantRuntime = Branded<'AssistantRuntime', {
+    readonly assistant: AssistantResolvedManifest | null;
+    readonly changed: boolean;
+}>;
+export declare const AssistantRuntime: (spec: RuntimeSpec, referenceStore: RuntimeReferenceStore) => AssistantRuntime;