@salsita-ai/sdk 0.50.0-develop.dede205ab0 → 0.50.0-develop.e33c8d8711

package/dist/application-spec/generate-application/runtime/admin-runtime/admin-runtime.d.ts

@@ -1,8 +1,10 @@
 import { Branded } from '@salsita-ai/common/utils';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { FactoryDataRuntime } from '../factory-data/index.js';
+import { type MigrationModules, MigrationRuntime } from '../migrations/index.js';
 import { ComponentOptics } from '../sections/component-optic.js';
-import { type ExpressionImplementations, ExpressionRuntime, type MissingExpression } from '../sections/expression-runtime.js';
+import { type ExpressionImplementations, ExpressionRuntime, type InvariantImplementations, type MissingExpression } from '../sections/expression-runtime.js';
 import { PresetRuntime } from '../sections/preset-runtime.js';
 import { AdminModelRuntime } from './admin-model-runtime.js';
 import { AdminStatesRuntime } from './states-runtime.js';
@@ -12,6 +14,8 @@ export type AdminRuntime = Branded<'AdminRuntime', {
     readonly expressionRuntime: ExpressionRuntime;
     readonly presetRuntime: PresetRuntime;
     readonly statesRuntime: AdminStatesRuntime;
+    readonly migrationRuntime: MigrationRuntime;
+    readonly factoryDataRuntime: FactoryDataRuntime;
 }>;
 export type AdminRuntimeResult = {
     readonly ok: true;
@@ -20,4 +24,4 @@ export type AdminRuntimeResult = {
     readonly ok: false;
     readonly missingExpressions: readonly MissingExpression[];
 };
-export declare const AdminRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations?: ExpressionImplementations) => AdminRuntimeResult;
+export declare const AdminRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, invariantImplementations: InvariantImplementations, migrationModules: MigrationModules) => AdminRuntimeResult;

package/dist/application-spec/generate-application/runtime/admin-runtime/admin-runtime.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{Preset as t,PresetCategory as i,commonAdminCustomExpressions as r,commonAdminViolationExpressions as s}from"#package/domain";import{ComponentOptics as n}from"../sections/component-optic.js";import{ExpressionRuntime as m}from"../sections/expression-runtime.js";import{PresetRuntime as o}from"../sections/preset-runtime.js";import{AdminModelRuntime as a}from"./admin-model-runtime.js";import{AdminStatesRuntime as p}from"./states-runtime.js";let c={Preset:[{evaluate:(e,i,r)=>{let n=r.domain.get$Entity(e,i);return t.assert(n),s.Preset.nameNotEmpty(n)}}]},u={PresetCategory:{$isDraft:{origin:{name:"$isDraft",typeOrAlias:"PresetCategory"},evaluate:(e,t,s)=>{let n=s.domain.get$Entity(e,t);return i.assert(n),r.PresetCategory.$isDraft(n)},meta:{}}}};export const AdminRuntime=(t,i,r={})=>{let s={...u};for(let[e,t]of Object.entries(r))s[e]={...s[e],...t};let f=a(t.admin,t.configurator.dataSchemas,i),d=m(t.admin,i,s,"adminExpressionRuntime",c);return d.ok?{ok:!0,runtime:e({modelRuntime:f,componentOptics:n(i,{components:t.admin.components,referenceScope:"adminRuntime/componentOptics",modelRuntime:f}),expressionRuntime:d.runtime,presetRuntime:o(i,{referenceScope:"adminRuntime/presetRuntime",presets:t.admin.presets.presets}),statesRuntime:p(t,i)})}:{ok:!1,missingExpressions:d.missing}};
+import{Branded as e}from"@salsita-ai/common/utils";import{Preset as t,PresetCategory as i,commonAdminCustomExpressions as n,commonAdminViolationExpressions as r}from"#package/domain";import{FactoryDataRuntime as s}from"../factory-data/index.js";import{MigrationRuntime as o}from"../migrations/index.js";import{ComponentOptics as m}from"../sections/component-optic.js";import{ExpressionRuntime as a}from"../sections/expression-runtime.js";import{PresetRuntime as p}from"../sections/preset-runtime.js";import{AdminModelRuntime as f}from"./admin-model-runtime.js";import{AdminStatesRuntime as u}from"./states-runtime.js";let c={Preset:[{evaluate:(e,i,n)=>{let s=n.domain.get$Entity(e,i);return t.assert(s),r.Preset.nameNotEmpty(s)}}]},l={PresetCategory:{$isDraft:{origin:{name:"$isDraft",typeOrAlias:"PresetCategory"},evaluate:(e,t,r)=>{let s=r.domain.get$Entity(e,t);return i.assert(s),n.PresetCategory.$isDraft(s)},meta:{}}}},d=new WeakMap;export const AdminRuntime=(t,i,n,r,g)=>{let R={...l};for(let[e,t]of Object.entries(n))R[e]={...R[e],...t};let y=f(t.admin,t.configurator.dataSchemas,i),j=a(t.admin,i,R,"adminExpressionRuntime",((e,t)=>{if(0===Object.keys(e).length)return c;let i=d.get(t)??new WeakMap;d.set(t,i);let n=i.get(e);if(n)return n;let r={};for(let i of[c,e])for(let[e,n]of Object.entries(i))for(let i of t[e]??[e])r[i]=[...r[i]??[],...n];return i.set(e,r),r})(r,y.aliases));return j.ok?{ok:!0,runtime:e({modelRuntime:y,componentOptics:m(i,{components:t.admin.components,referenceScope:"adminRuntime/componentOptics",modelRuntime:y}),expressionRuntime:j.runtime,presetRuntime:p(i,{referenceScope:"adminRuntime/presetRuntime",presets:t.admin.presets.presets}),statesRuntime:u(t,i),migrationRuntime:o(i,{referenceScope:"adminRuntime/migrationRuntime",resolvedVersions:t.admin.resolvedVersions,latestEntities:y.entities,migrationModules:g}),factoryDataRuntime:s(i,{referenceScope:"adminRuntime/factoryDataRuntime",invariants:t.admin.invariants,defaults:t.admin.defaults,aliases:y.aliases,entities:y.entities})})}:{ok:!1,missingExpressions:j.missing}};

package/dist/application-spec/generate-application/runtime/application-runtime.d.ts

@@ -4,9 +4,9 @@ import type { RuntimeReferenceStore } from '../../caching/index.js';
 import type { ApplicationSpec } from '../../parse-application-files/index.js';
 import { AdminRuntime } from './admin-runtime/admin-runtime.js';
 import { ConfiguratorRuntime } from './configurator-runtime/configurator-runtime.js';
+import type { MigrationModules } from './migrations/index.js';
 import { DataRuntime } from './sections/data-runtime.js';
 import type { ExpressionImplementations, InvariantImplementations, MissingExpression } from './sections/expression-runtime.js';
-type AnyImportedTransformer = ImportedTransformer<any, any, any, any, any, any, any>;
 /**
  * Runtime objects built from ApplicationSpec.
  * Domain-specific fields mirror ApplicationSpec configurator/admin nesting.
@@ -29,7 +29,12 @@ export type ApplicationRuntimeResult = {
  * section-level changes across rebuilds.
  * Each field on the result carries its own `changed` flag.
  *
+ * `adminInvariantImplementations` are the project's admin invariants (`src/admin/invariants/`); the
+ * admin domain checks them after the invariants every admin domain has. `migrationModules` are the
+ * project's migration modules of both domains (`src/migrations/`, `src/admin/migrations/`), keyed by
+ * project path; a migration they do not provide is listed in `missingMigrations` of the domain's
+ * `migrationRuntime`.
+ *
  * Returns an error result when declared expressions are missing implementations.
  */
-export declare const ApplicationRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly AnyImportedTransformer[], invariantImplementations?: InvariantImplementations, adminImplementations?: ExpressionImplementations) => ApplicationRuntimeResult;
-export {};
+export declare const ApplicationRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations?: InvariantImplementations, adminImplementations?: ExpressionImplementations, adminInvariantImplementations?: InvariantImplementations, migrationModules?: MigrationModules) => ApplicationRuntimeResult;

package/dist/application-spec/generate-application/runtime/application-runtime.js

@@ -1 +1 @@
-import{Branded as i}from"@salsita-ai/common/utils";import{AdminRuntime as r}from"./admin-runtime/admin-runtime.js";import{ConfiguratorRuntime as n}from"./configurator-runtime/configurator-runtime.js";import{DataRuntime as o}from"./sections/data-runtime.js";export const ApplicationRuntime=(s,t,m,e,u,a)=>{let p=n(s,t,m,e,u);if(!p.ok)return{ok:!1,missingExpressions:p.missingExpressions};let f=r(s,t,a);return f.ok?{ok:!0,runtime:i({configurator:p.runtime,admin:f.runtime,data:o(s,t)})}:{ok:!1,missingExpressions:f.missingExpressions}};
+import{Branded as i}from"@salsita-ai/common/utils";import{AdminRuntime as r}from"./admin-runtime/admin-runtime.js";import{ConfiguratorRuntime as n}from"./configurator-runtime/configurator-runtime.js";import{DataRuntime as o}from"./sections/data-runtime.js";export const ApplicationRuntime=(s,t,m,e,u,a={},p={},f={})=>{let c=n(s,t,m,e,u,f);if(!c.ok)return{ok:!1,missingExpressions:c.missingExpressions};let g=r(s,t,a,p,f);return g.ok?{ok:!0,runtime:i({configurator:c.runtime,admin:g.runtime,data:o(s,t)})}:{ok:!1,missingExpressions:g.missingExpressions}};

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.d.ts

@@ -2,6 +2,8 @@ import { Branded } from '@salsita-ai/common/utils';
 import type { ImportedTransformer } from '#package/domain';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { FactoryDataRuntime } from '../factory-data/index.js';
+import { type MigrationModules, MigrationRuntime } from '../migrations/index.js';
 import { ActionsRuntime } from '../sections/actions-runtime.js';
 import { AssistantRuntime } from '../sections/assistant-runtime.js';
 import { ComponentOptics } from '../sections/component-optic.js';
@@ -11,7 +13,6 @@ import { ThemeRuntime } from '../sections/theme-runtime.js';
 import { TransformersRuntime } from '../sections/transformers-runtime.js';
 import { ConfiguratorModelRuntime } from './configurator-model-runtime.js';
 import { ConfiguratorStatesRuntime } from './states-runtime.js';
-type AnyImportedTransformer = ImportedTransformer<any, any, any, any, any, any, any>;
 export type ConfiguratorRuntime = Branded<'ConfiguratorRuntime', {
     readonly modelRuntime: ConfiguratorModelRuntime;
     readonly componentOptics: ComponentOptics;
@@ -22,6 +23,8 @@ export type ConfiguratorRuntime = Branded<'ConfiguratorRuntime', {
     readonly transformersRuntime: TransformersRuntime;
     readonly assistantRuntime: AssistantRuntime;
     readonly actionsRuntime: ActionsRuntime;
+    readonly migrationRuntime: MigrationRuntime;
+    readonly factoryDataRuntime: FactoryDataRuntime;
 }>;
 export type ConfiguratorRuntimeResult = {
     readonly ok: true;
@@ -30,5 +33,4 @@ export type ConfiguratorRuntimeResult = {
     readonly ok: false;
     readonly missingExpressions: readonly MissingExpression[];
 };
-export declare const ConfiguratorRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly AnyImportedTransformer[], invariantImplementations?: InvariantImplementations) => ConfiguratorRuntimeResult;
-export {};
+export declare const ConfiguratorRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, implementations: ExpressionImplementations, importedTransformers: readonly ImportedTransformer[], invariantImplementations: InvariantImplementations | undefined, migrationModules: MigrationModules) => ConfiguratorRuntimeResult;

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.js

@@ -1 +1 @@
-import{Branded as t}from"@salsita-ai/common/utils";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as r}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as i}from"../sections/preset-runtime.js";import{ThemeRuntime as n}from"../sections/theme-runtime.js";import{TransformersRuntime as m}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as u}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as c}from"./states-runtime.js";export const ConfiguratorRuntime=(p,a,f,g,R)=>{let j=u(p.configurator,a),x=s(p.configurator,a,f,"configuratorExpressionRuntime",R);return x.ok?{ok:!0,runtime:t({modelRuntime:j,componentOptics:r(a,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:j}),presetRuntime:i(a,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:c(p,a),expressionRuntime:x.runtime,themeRuntime:n(p,a),transformersRuntime:m(p,a,g),assistantRuntime:e(p,a),actionsRuntime:o(p.configurator.actions,a)})}:{ok:!1,missingExpressions:x.missing}};
+import{Branded as t}from"@salsita-ai/common/utils";import{FactoryDataRuntime as e}from"../factory-data/index.js";import{MigrationRuntime as i}from"../migrations/index.js";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as r}from"../sections/assistant-runtime.js";import{ComponentOptics as n}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as m}from"../sections/preset-runtime.js";import{ThemeRuntime as a}from"../sections/theme-runtime.js";import{TransformersRuntime as u}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as c}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as f}from"./states-runtime.js";export const ConfiguratorRuntime=(p,g,R,j,l,d)=>{let x=c(p.configurator,g),v=s(p.configurator,g,R,"configuratorExpressionRuntime",l);return v.ok?{ok:!0,runtime:t({modelRuntime:x,componentOptics:n(g,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:x}),presetRuntime:m(g,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:f(p,g),expressionRuntime:v.runtime,themeRuntime:a(p,g),transformersRuntime:u(p,g,j),assistantRuntime:r(p,g),actionsRuntime:o(p.configurator.actions,g),migrationRuntime:i(g,{referenceScope:"configuratorRuntime/migrationRuntime",resolvedVersions:p.configurator.resolvedVersions,latestEntities:x.entities,migrationModules:d}),factoryDataRuntime:e(g,{referenceScope:"configuratorRuntime/factoryDataRuntime",invariants:p.configurator.invariants,defaults:p.configurator.defaults,aliases:x.aliases,entities:x.entities})})}:{ok:!1,missingExpressions:v.missing}};

package/dist/application-spec/generate-application/runtime/factory-data/factory-data-runtime.d.ts

@@ -0,0 +1,43 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { AnyEntityReflections, DomainEntity, DomainEntityReflection } from '#package/domain';
+import type { RuntimeReferenceStore } from '../../../caching/index.js';
+import type { Defaults, Invariants } from '../../../parse-application-files/index.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/application-spec/generate-application/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/application-spec/generate-application/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/application-spec/generate-application/runtime/factory-data/index.js

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

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

@@ -0,0 +1,13 @@
+import type { Defaults } from '../../../parse-application-files/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/application-spec/generate-application/runtime/factory-data/recipe-defaults.js

@@ -0,0 +1 @@
+import{createMessageDescriptor as e,isEvalMarker as t,isMsgMarker as r}from"../../../core/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/application-spec/generate-application/runtime/factory-data/static-violations.d.ts

@@ -0,0 +1,16 @@
+import type { Violation } from '#package/domain';
+import type { Invariants } from '../../../parse-application-files/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/application-spec/generate-application/runtime/factory-data/static-violations.js

@@ -0,0 +1 @@
+import{createMessageDescriptor as t}from"../../../core/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/application-spec/generate-application/runtime/migrations/index.d.ts

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

package/dist/application-spec/generate-application/runtime/migrations/index.js

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

package/dist/application-spec/generate-application/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 '#package/domain';
+import type { RuntimeReferenceStore } from '../../../caching/index.js';
+import type { ResolvedVersions } from '../../../parse-application-files/index.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: ResolvedVersions;
+    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/application-spec/generate-application/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"#package/domain";let o=e=>"function"==typeof e,r=e=>`migrateToV${e}`,n=e=>{let{resolvedVersions:i,latestEntities:n,migrationModules:a}=e,l={},m={},d=[];for(let e of i.versionedModels){if(e.isLatest)l[e.version]=n;else{let i={};for(let s of e.modelVersion.entitySchemas)i[String(s.entityType)]=new t(String(s.entityType),[s.shapeSchema]);l[e.version]=i}if(void 0===e.migrationFile)continue;let i=r(e.version),s=a[e.migrationFile]?.[i];o(s)?m[e.version]=s:d.push(`${e.migrationFile}#${i}`)}return{modelVersions:l,migrations:m,migrate:s(l,i.latestVersion,m),missingMigrations:d}},a=e=>e.versionedModels.map(e=>({version:e.version,isLatest:e.isLatest,migrationFile:e.migrationFile,schemas:e.isLatest?[]:e.modelVersion.entitySchemas.map(e=>e.shapeSchema)})),l=(i,t)=>i.latestEntities===t.latestEntities&&i.resolvedVersions.latestVersion===t.resolvedVersions.latestVersion&&e(a(i.resolvedVersions),a(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:l}).build({resolvedVersions:t.resolvedVersions,latestEntities:t.latestEntities,migrationModules:t.migrationModules});return i({...s.output,changed:s.changed})};

package/dist/application-spec/generate-application/runtime/sections/build-sdk-optic.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentEntry, type ComponentImplementation } from '../../../parse-application-files/spec/index.js';
+import type { ComponentEntry, ComponentImplementation } from '../../../parse-application-files/spec/index.js';
 import type { AdminModelRuntime } from '../admin-runtime/admin-model-runtime.js';
 import type { ConfiguratorModelRuntime } from '../configurator-runtime/configurator-model-runtime.js';
 import type { ComponentOptic } from './component-optic.js';

package/dist/application-spec/generate-application/runtime/sections/build-sdk-optic.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{DomainComponentOpticBuilder as t,adminSidebarComponent as a,attributeSelectionComponent as i,componentsByName as r,composedOfComponent as n,navigationPageComponent as o,navigationPanelListComponent as d,referenceComponent as c}from"#package/domain";import*as m from"#package/domain";import{FILTER_CRITERION_KEYS as s,isSdkCodeRef as l}from"../../../parse-application-files/spec/index.js";let g=new Map([["reference",c],["composedOf",n],["adminSidebar",a],["attributeSelection",i],["navigationPage",o],["navigationPanelList",d]]),p={createAdminCustomPageRead:m.createAdminCustomPageRead,createAdminCustomSidebarRead:m.createAdminCustomSidebarRead,createAdminDataPageRead:m.createAdminDataPageRead,createAdminDataTableSidebarRead:m.createAdminDataTableSidebarRead,createAdminNavigationPanelRead:m.createAdminNavigationPanelRead,createAdminPresetCategoryPageRead:m.createAdminPresetCategoryPageRead,createAdminPresetCategorySelectionRead:m.createAdminPresetCategorySelectionRead,createAdminPresetCategorySelectionWrite:m.createAdminPresetCategorySelectionWrite,createAdminPresetCategorySidebarRead:m.createAdminPresetCategorySidebarRead,createAdminPresetListPageRead:m.createAdminPresetListPageRead,createAdminPresetSidebarRead:m.createAdminPresetSidebarRead,createAdminRecipeCollectionPageRead:m.createAdminRecipeCollectionPageRead,createAdminRecipeSidebarRead:m.createAdminRecipeSidebarRead},R=(e,t)=>{let a=p[e.sdkFunction]??m[e.sdkFunction];if("function"!=typeof a)throw Error(`SDK factory function "${e.sdkFunction}" not found. Make sure it is exported from the package.`);return a(...e.params.map(e=>{if(l(e)){let a=t.entities[e.$codeRef]??t.aliasReflections[e.$codeRef];if(!a)throw Error(`Reflection "${e.$codeRef}" not found in ModelRuntime. This is a bug — the target was validated at parse time.`);return a}return e}))};export const buildSdkOptic=(a,i,n,o)=>{let d=t.from(n),c=r.get(a.componentName)??g.get(a.componentName);if(!c)throw Error(`SDK component "${a.componentName}" not found. This is a bug — the component was validated at parse time.`);let m=d.withComponent(c,a.instanceName,!0),l=a.isAlias?m.withAlias(String(a.typeOrAlias)):m.withEntity(String(a.typeOrAlias));for(let e of i.filters.items){if("root"===e.kind){let t=e.target,a=e=>e[t];l=l.withFilter(a);continue}let t={};for(let a of s){let i=e[a];void 0!==i&&("dynamic"===i.kind?t[a]=e=>e[i.target]:"eval"===i.kind?t[a]=Function("self",`return (${i.code})`):t[a]=i.value)}l=l.withGradualFilter(t)}let p=R(i.readFactory,o),f=R(i.writeFactory,o),A=l.attach(p,f);return e({typeOrAlias:String(a.typeOrAlias),componentName:a.componentName,instanceName:String(a.instanceName),optic:A})};
+import{Branded as e}from"@salsita-ai/common/utils";import{DomainComponentOpticBuilder as t,adminSidebarComponent as a,attributeSelectionComponent as i,componentsByName as r,composedOfComponent as n,navigationPageComponent as o,navigationPanelListComponent as d,referenceComponent as c}from"#package/domain";import*as m from"#package/domain";import{FILTER_CRITERION_KEYS as s,isSdkCodeRef as l}from"../../../core/index.js";let g=new Map([["reference",c],["composedOf",n],["adminSidebar",a],["attributeSelection",i],["navigationPage",o],["navigationPanelList",d]]),R={createAdminCustomPageRead:m.createAdminCustomPageRead,createAdminCustomSidebarRead:m.createAdminCustomSidebarRead,createAdminDataPageRead:m.createAdminDataPageRead,createAdminDataTableSidebarRead:m.createAdminDataTableSidebarRead,createAdminNavigationPanelRead:m.createAdminNavigationPanelRead,createAdminPresetCategoryPageRead:m.createAdminPresetCategoryPageRead,createAdminPresetCategorySelectionRead:m.createAdminPresetCategorySelectionRead,createAdminPresetCategorySelectionWrite:m.createAdminPresetCategorySelectionWrite,createAdminPresetCategorySidebarRead:m.createAdminPresetCategorySidebarRead,createAdminPresetListPageRead:m.createAdminPresetListPageRead,createAdminPresetSidebarRead:m.createAdminPresetSidebarRead,createAdminRecipeCollectionPageRead:m.createAdminRecipeCollectionPageRead,createAdminRecipeSidebarRead:m.createAdminRecipeSidebarRead},p=(e,t)=>{let a=R[e.sdkFunction]??m[e.sdkFunction];if("function"!=typeof a)throw Error(`SDK factory function "${e.sdkFunction}" not found. Make sure it is exported from the package.`);return a(...e.params.map(e=>{if(l(e)){let a=t.entities[e.$codeRef]??t.aliasReflections[e.$codeRef];if(!a)throw Error(`Reflection "${e.$codeRef}" not found in ModelRuntime. This is a bug — the target was validated at parse time.`);return a}return e}))};export const buildSdkOptic=(a,i,n,o)=>{let d=t.from(n),c=r.get(a.componentName)??g.get(a.componentName);if(!c)throw Error(`SDK component "${a.componentName}" not found. This is a bug — the component was validated at parse time.`);let m=d.withComponent(c,a.instanceName,!0),l=a.isAlias?m.withAlias(String(a.typeOrAlias)):m.withEntity(String(a.typeOrAlias));for(let e of i.filters.items){if("root"===e.kind){let t=e.target,a=e=>e[t];l=l.withFilter(a);continue}let t={};for(let a of s){let i=e[a];void 0!==i&&("dynamic"===i.kind?t[a]=e=>e[i.target]:"eval"===i.kind?t[a]=Function("self",`return (${i.code})`):t[a]=i.value)}l=l.withGradualFilter(t)}let R=p(i.readFactory,o),A=p(i.writeFactory,o),f=l.attach(R,A);return e({typeOrAlias:String(a.typeOrAlias),componentName:a.componentName,instanceName:String(a.instanceName),optic:f})};

package/dist/application-spec/generate-application/runtime/sections/component-optic.d.ts

@@ -4,7 +4,8 @@ import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ComponentEntry } from '../../../parse-application-files/spec/index.js';
 import type { AdminModelRuntime } from '../admin-runtime/admin-model-runtime.js';
 import type { ConfiguratorModelRuntime } from '../configurator-runtime/configurator-model-runtime.js';
-type AnyComponentOptic = DomainComponentOptic<any, any, any, any, any, any, SystemComponentTypeConstraint>;
+/** 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;

package/dist/application-spec/generate-application/runtime/sections/expression-runtime.js

@@ -1 +1 @@
-import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{createRelationFactory as i}from"#package/domain";import{canonicalEnhancedJsonValueKey as a}from"../../../core/index.js";import{isSdkExpressionImplementation as n}from"../../../parse-application-files/spec/index.js";import{generateMemoEvalPlanRuntime as r}from"./generate-memo-eval-plan-runtime.js";let l={},o={relation:(e,t)=>i(e.aliasMap)(t[0]),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 a=i.entityType,n=Object.entries(e.invariantImplementations).flatMap(([t,i])=>{let n=e.aliasMap[t];return t===a||n?.includes(a)?i:[]});return{origin:{name:"$violations",typeOrAlias:a},evaluate:(e,t,i)=>n.flatMap(a=>a.evaluate(e,t,i)),meta:{}}}},s=e=>{let t=r(e.plan);return{origin:{name:e.name,typeOrAlias:e.entityOrAlias},evaluate:(e,i,a)=>t(a.domain.get$Entity(e,i),i,a),meta:{}}},p=e=>({...(0,o[e.kind])({aliasMap:e.aliasMap,invariantImplementations:e.invariantImplementations},e.params),origin:{name:e.name,typeOrAlias:e.entityOrAlias}});export const ExpressionRuntime=(i,r,o,m,u=l)=>{let d={};for(let[e,t]of i.latestModel.aliases)d[String(e)]=t.map(String);let f=r.createBuilder(`${m}/sdk`,{build:p,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)}),y=r.createBuilder(`${m}/user`,{build:e=>e.impl,getKey:e=>`user::${e.entityType}::${e.name}`,compare:(e,t)=>e.impl===t.impl}),g=r.createBuilder(`${m}/value`,{build:s,getKey:e=>`value::${e.entityOrAlias}::${e.name}`,compare:(e,t)=>e.valueKey===t.valueKey}),c={},v=!1,S=new Set,b=new Set,k=new Set;for(let[e,t]of i.expressions.expressions)for(let[,i]of t){let t=d[String(e)]??[String(e)];if(n(i.implementation)){let a={entityOrAlias:String(e),name:String(i.name),kind:i.implementation.kind,params:i.implementation.params,aliasMap:d,invariantImplementations:u},n=f.build(a);for(let e of(n.changed&&(v=!0),S.add(f.getKey(a)),t))c[e]||(c[e]={}),c[e][String(i.name)]=n.output;continue}if("value"===i.implementation.kind){let n=i.implementation.value,r={entityOrAlias:String(e),name:String(i.name),valueKey:a(n),plan:i.implementation.plan},l=g.build(r);for(let e of(l.changed&&(v=!0),k.add(g.getKey(r)),t))c[e]||(c[e]={}),c[e][String(i.name)]=l.output;continue}}for(let[e,t]of Object.entries(o))for(let[i,a]of Object.entries(t)){let t={entityType:e,name:i,impl:a},n=y.build(t);n.changed&&(v=!0),b.add(y.getKey(t)),c[e]||(c[e]={}),c[e][i]=n.output}f.cleanup(S)&&(v=!0),y.cleanup(b)&&(v=!0),g.cleanup(k)&&(v=!0);let x=[];for(let[e,t]of i.expressions.entityExpressions)for(let a of t.shapeGroups){let t=i.expressions.expressions.get(a);if(t)for(let[i]of t)c[String(e)]?.[String(i)]||x.push({entityType:String(e),exprName:String(i)})}return x.length>0?{ok:!1,missing:x}:{ok:!0,runtime:t({merged:c,changed:v})}};
+import e from"lodash-es/isEqual.js";import{Branded as t}from"@salsita-ai/common/utils";import{createRelationFactory as i}from"#package/domain";import{canonicalEnhancedJsonValueKey as n,isSdkExpressionImplementation as a}from"../../../core/index.js";import{generateMemoEvalPlanRuntime as r}from"./generate-memo-eval-plan-runtime.js";let l={},o=["0-1","1-1","0-N","1-N"],s={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&&o.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:{}}}},p=e=>{let t=r(e.plan);return{origin:{name:e.name,typeOrAlias:e.entityOrAlias},evaluate:(e,i,n)=>t(n.domain.get$Entity(e,i),i,n),meta:{}}},m=e=>({...(0,s[e.kind])({aliasMap:e.aliasMap,invariantImplementations:e.invariantImplementations},e.params),origin:{name:e.name,typeOrAlias:e.entityOrAlias}});export const ExpressionRuntime=(i,r,o,s,u=l)=>{let d={};for(let[e,t]of i.latestModel.aliases)d[String(e)]=t.map(String);let c=r.createBuilder(`${s}/sdk`,{build:m,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)}),f=r.createBuilder(`${s}/user`,{build:e=>e.impl,getKey:e=>`user::${e.entityType}::${e.name}`,compare:(e,t)=>e.impl===t.impl}),y=r.createBuilder(`${s}/value`,{build:p,getKey:e=>`value::${e.entityOrAlias}::${e.name}`,compare:(e,t)=>e.valueKey===t.valueKey}),g={},v=!1,S=new Set,k=new Set,b=new Set;for(let[e,t]of i.expressions.expressions)for(let[,i]of t){let t=d[String(e)]??[String(e)];if(a(i.implementation)){let n={entityOrAlias:String(e),name:String(i.name),kind:i.implementation.kind,params:i.implementation.params,aliasMap:d,invariantImplementations:u},a=c.build(n);for(let e of(a.changed&&(v=!0),S.add(c.getKey(n)),t))g[e]||(g[e]={}),g[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},l=y.build(r);for(let e of(l.changed&&(v=!0),b.add(y.getKey(r)),t))g[e]||(g[e]={}),g[e][String(i.name)]=l.output;continue}}for(let[e,t]of Object.entries(o))for(let[i,n]of Object.entries(t)){let t={entityType:e,name:i,impl:n},a=f.build(t);a.changed&&(v=!0),k.add(f.getKey(t)),g[e]||(g[e]={}),g[e][i]=a.output}c.cleanup(S)&&(v=!0),f.cleanup(k)&&(v=!0),y.cleanup(b)&&(v=!0);let h=[];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)g[String(e)]?.[String(i)]||h.push({entityType:String(e),exprName:String(i)})}return h.length>0?{ok:!1,missing:h}:{ok:!0,runtime:t({merged:g,changed:v})}};

package/dist/application-spec/generate-application/runtime/sections/transformers-runtime.d.ts

@@ -2,7 +2,6 @@ import { Branded } from '@salsita-ai/common/utils';
 import type { ImportedTransformer } from '#package/domain';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
-type AnyImportedTransformer = ImportedTransformer<any, any, any, any, any, any, any>;
 /**
  * Runtime section for transformers. Combines two sources of truth:
  * - `importedTransformers` — factory functions from src/transformers/*.ts
@@ -13,9 +12,8 @@ type AnyImportedTransformer = ImportedTransformer<any, any, any, any, any, any,
  * decide whether to push a fresh `createTransformers` factory into the registry.
  */
 export type TransformersRuntime = Branded<'TransformersRuntime', {
-    readonly importedTransformers: readonly AnyImportedTransformer[];
+    readonly importedTransformers: readonly ImportedTransformer[];
     readonly specTransformers: ApplicationSpec['configurator']['transformers'];
     readonly changed: boolean;
 }>;
-export declare const TransformersRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, importedTransformers: readonly AnyImportedTransformer[]) => TransformersRuntime;
-export {};
+export declare const TransformersRuntime: (spec: ApplicationSpec, referenceStore: RuntimeReferenceStore, importedTransformers: readonly ImportedTransformer[]) => TransformersRuntime;

package/dist/application-spec/generate-application/runtime-spec/decode-runtime-spec.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeSpec } from './runtime-spec.js';
+/**
+ * Reads the JSON text of `.phoenix/application-spec.json` back into the runtime spec that
+ * `encodeRuntimeSpec` wrote: one `JSON.parse`, then each listed array back into its Map or Set.
+ *
+ * Throws when the text is not a runtime spec artifact, or when it was written in another format
+ * version than this SDK reads; `phoenix sync` writes the artifact again in the right one.
+ */
+export declare const decodeRuntimeSpec: (text: string) => RuntimeSpec;

package/dist/application-spec/generate-application/runtime-spec/decode-runtime-spec.js

@@ -0,0 +1 @@
+import{RUNTIME_SPEC_FORMAT_VERSION as e}from"./encoded-runtime-spec.js";let t="Run `phoenix sync` to write it again with the SDK the project uses.",r=e=>"object"==typeof e&&null!==e,i=e=>Error(`Cannot read .phoenix/application-spec.json: its ${e.kind} at ${JSON.stringify(e.path)} is not where the file says it is, so the file was changed after it was written. ${t}`),o=(e,t)=>{let o=e,n="spec";for(let e of t.path)o=r(o)?o[n]:void 0,n=e;let s=r(o)?o[n]:void 0;if(!r(o)||!Array.isArray(s))throw i(t);o[n]="Map"===t.kind?new Map(s.map(e=>{if(!Array.isArray(e)||2!==e.length)throw i(t);return[e[0],e[1]]})):new Set(s)};export const decodeRuntimeSpec=i=>{let n=JSON.parse(i);if(!(r(n)&&"number"==typeof n.format&&Array.isArray(n.collections)&&"spec"in n))throw Error(`Cannot read .phoenix/application-spec.json: it is not a runtime spec written by \`phoenix sync\` or \`phoenix build\`. ${t}`);if(n.format!==e)throw Error(`Cannot read .phoenix/application-spec.json: it is written in format version ${n.format}, and this SDK reads format version ${e}, so it was written by another version of the SDK. ${t}`);let s={spec:n.spec};for(let e of n.collections)o(s,e);return s.spec};

package/dist/application-spec/generate-application/runtime-spec/encode-runtime-spec.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeSpec } from './runtime-spec.js';
+/**
+ * Writes a runtime spec as the JSON text of `.phoenix/application-spec.json`, which
+ * `decodeRuntimeSpec` reads back. Maps and Sets become arrays listed in `collections`, properties
+ * whose value is `undefined` are left out, and the document carries the format version. The text
+ * is the same for the same spec, so an unchanged spec leaves the file unchanged.
+ */
+export declare const encodeRuntimeSpec: (spec: RuntimeSpec) => string;

package/dist/application-spec/generate-application/runtime-spec/encode-runtime-spec.js

@@ -0,0 +1 @@
+import{RUNTIME_SPEC_FORMAT_VERSION as t}from"./encoded-runtime-spec.js";let e=(t,e)=>Error(`Cannot write .phoenix/application-spec.json: the parsed spec holds ${e} at ${JSON.stringify(t.path)}, which the runtime spec cannot hold. The runtime spec holds only plain data, Maps and Sets, so the parser produced a value it should not have. Report this to the Phoenix team with the YAML that declares this value.`),o=(t,e,o)=>{t.path.push(e);let n=r(t,o);return t.path.pop(),n},r=(t,r)=>{let n;if(null===r||"string"==typeof r||"boolean"==typeof r)return r;if("number"==typeof r){if(!Number.isFinite(r))throw e(t,`the number ${r}`);return r}if("object"!=typeof r)throw e(t,`a value of type ${typeof r}`);if(r instanceof Map){let e=[...r].map(([e,r],n)=>{t.path.push(n);let p=[o(t,0,e),o(t,1,r)];return t.path.pop(),p});return t.collections.push({kind:"Map",path:[...t.path]}),e}if(r instanceof Set){let e=[...r].map((e,r)=>o(t,r,e));return t.collections.push({kind:"Set",path:[...t.path]}),e}if(Array.isArray(r))return r.map((r,n)=>{if(void 0===r)throw e(t,`undefined as item ${n} of an array`);return o(t,n,r)});if((n=Object.getPrototypeOf(r))!==Object.prototype&&null!==n)throw e(t,`an instance of ${r.constructor.name}`);let p={};for(let[e,n]of Object.entries(r))void 0!==n&&(p[e]=o(t,e,n));return p};export const encodeRuntimeSpec=e=>{let o={path:[],collections:[]},n=r(o,e);return JSON.stringify({format:t,collections:o.collections,spec:n})};

package/dist/application-spec/generate-application/runtime-spec/encoded-runtime-spec.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The version of the JSON format `encodeRuntimeSpec` writes. Raise it with every change to the
+ * format or to the shape of `RuntimeSpec`, so that `decodeRuntimeSpec` refuses an artifact an older
+ * or newer SDK wrote instead of building a runtime from data it does not understand.
+ */
+export declare const RUNTIME_SPEC_FORMAT_VERSION = 1;
+/** One step from a value into a part of it: an object key or an array index. */
+export type RuntimeSpecPathSegment = string | number;
+/**
+ * A Map or Set of the runtime spec, which JSON cannot hold: it is written as an array (a Map as its
+ * `[key, value]` entries), and `path` leads from the spec to that array. Paths into a Map run
+ * through its entries, so `[..., 2, 1]` is the value of its third entry.
+ */
+export interface EncodedCollection {
+    readonly kind: 'Map' | 'Set';
+    readonly path: readonly RuntimeSpecPathSegment[];
+}
+/**
+ * The JSON document of `.phoenix/application-spec.json`. `spec` is the runtime spec with every Map
+ * and Set written as an array, and `collections` lists those arrays, inner ones before the ones
+ * that hold them, so a decoder turns them back in that order without walking the whole spec.
+ */
+export interface EncodedRuntimeSpec {
+    readonly format: number;
+    readonly collections: readonly EncodedCollection[];
+    readonly spec: unknown;
+}

package/dist/application-spec/generate-application/runtime-spec/encoded-runtime-spec.js

@@ -0,0 +1 @@
+export const RUNTIME_SPEC_FORMAT_VERSION=1;

package/dist/application-spec/generate-application/runtime-spec/index.d.ts

@@ -0,0 +1,4 @@
+export * from './runtime-spec.js';
+export * from './encoded-runtime-spec.js';
+export * from './encode-runtime-spec.js';
+export * from './decode-runtime-spec.js';

package/dist/application-spec/generate-application/runtime-spec/index.js

@@ -0,0 +1 @@
+export*from"./runtime-spec.js";export*from"./encoded-runtime-spec.js";export*from"./encode-runtime-spec.js";export*from"./decode-runtime-spec.js";

package/dist/application-spec/generate-application/runtime-spec/runtime-spec.d.ts

@@ -0,0 +1,68 @@
+import type { AdminSpec, ApplicationSpec, ConfiguratorSpec, EntitySchema, Infra, ModelVersion, ResolvedModelVersion, ResolvedVersions } from '../../parse-application-files/index.js';
+/**
+ * The part of a parsed entity schema the runtime reads: the entity type and the schema of its
+ * shape, from which it builds the entity's reflection. The full schema with `id` and `type` is
+ * only registered with a deployment, and the compiled shape validators only check presets and
+ * defaults while parsing.
+ */
+export type RuntimeEntitySchema = Pick<EntitySchema, 'entityType' | 'shapeSchema'>;
+/**
+ * The part of a parsed model version the runtime reads: the entity types, the aliases, the common
+ * types and the schema of every entity's shape. The raw shapes and resolved shapes only serve the
+ * parser and the type generator.
+ */
+export type RuntimeModelVersion = Pick<ModelVersion, 'versionKey' | 'entityTypes' | 'rootEntityTypes' | 'aliases' | 'commonTypes'> & {
+    readonly entitySchemas: readonly RuntimeEntitySchema[];
+};
+/** One model version of a domain as the runtime reads it, with the migration file that leads to it. */
+export type RuntimeResolvedModelVersion = Omit<ResolvedModelVersion, 'modelVersion'> & {
+    readonly modelVersion: RuntimeModelVersion;
+};
+/** Every model version of a domain as the runtime reads it; it builds the domain's migrations from them. */
+export type RuntimeResolvedVersions = Pick<ResolvedVersions, 'latestVersion'> & {
+    readonly versionedModels: readonly RuntimeResolvedModelVersion[];
+};
+/** The model of a domain as the runtime reads it: the latest version and every earlier one. */
+interface RuntimeDomainModel {
+    readonly latestModel: RuntimeModelVersion;
+    readonly resolvedVersions: RuntimeResolvedVersions;
+}
+/**
+ * The configurator part of the runtime spec. It leaves out the configuration schema and its
+ * version, which only a deployment registers, and the assistant's server settings (instructions
+ * and AI settings), which must never reach the browser of a customer.
+ */
+export type RuntimeConfiguratorSpec = Pick<ConfiguratorSpec, 'components' | 'presets' | 'expressions' | 'actions' | 'invariants' | 'dataSchemas' | 'defaults' | 'states' | 'theme' | 'ui' | 'transformers' | 'assistant'> & RuntimeDomainModel;
+/**
+ * The admin part of the runtime spec. It leaves out the configuration schema and its version, which
+ * only a deployment registers.
+ */
+export type RuntimeAdminSpec = Pick<AdminSpec, 'components' | 'presets' | 'expressions' | 'invariants' | 'defaults' | 'states' | 'adminPages'> & RuntimeDomainModel;
+/**
+ * The infrastructure settings the runtime reads: access control and resources. The environment
+ * variable declarations only drive the generated environment readers.
+ */
+export type RuntimeInfra = Pick<Infra, 'acl' | 'resources' | 'resourcesConfig'>;
+/**
+ * The parsed application spec as the runtime reads it: what `ApplicationRuntime` builds the
+ * configurator and admin runtimes from, and the sections an application needs besides its domains
+ * (data spec, app metadata, resources, access control, user interface settings, webhook data
+ * schemas, admin pages). `phoenix sync` and `phoenix build` write it to
+ * `.phoenix/application-spec.json` with `encodeRuntimeSpec`.
+ *
+ * It is derived from the parsed types, so a section the runtime reads keeps the parser's type. It
+ * leaves out what only the parser, the type generator or a deployment use, and holds plain data,
+ * Maps and Sets only, so it can be encoded as JSON.
+ */
+export interface RuntimeSpec extends Pick<ApplicationSpec, 'appMetadata' | 'dataSpec'> {
+    readonly configurator: RuntimeConfiguratorSpec;
+    readonly admin: RuntimeAdminSpec;
+    readonly infra: RuntimeInfra;
+}
+/**
+ * Takes from a parsed application spec the part the runtime reads. The sections it keeps are the
+ * parsed values themselves, not copies; only the model versions are rebuilt without what the
+ * runtime does not read.
+ */
+export declare const toRuntimeSpec: (spec: ApplicationSpec) => RuntimeSpec;
+export {};

package/dist/application-spec/generate-application/runtime-spec/runtime-spec.js

@@ -0,0 +1 @@
+let e=e=>({versionKey:e.versionKey,entityTypes:e.entityTypes,rootEntityTypes:e.rootEntityTypes,aliases:e.aliases,commonTypes:e.commonTypes,entitySchemas:e.entitySchemas.map(e=>({entityType:e.entityType,shapeSchema:e.shapeSchema}))}),s=s=>({latestModel:e(s.latestModel),resolvedVersions:{latestVersion:s.resolvedVersions.latestVersion,versionedModels:s.resolvedVersions.versionedModels.map(s=>({version:s.version,key:s.key,isLatest:s.isLatest,migrationFile:s.migrationFile,modelVersion:e(s.modelVersion)}))}});export const toRuntimeSpec=e=>{let{configurator:t,admin:a,infra:n}=e;return{configurator:{components:t.components,presets:t.presets,expressions:t.expressions,actions:t.actions,invariants:t.invariants,dataSchemas:t.dataSchemas,defaults:t.defaults,states:t.states,theme:t.theme,ui:t.ui,transformers:t.transformers,assistant:t.assistant,...s(t)},admin:{components:a.components,presets:a.presets,expressions:a.expressions,invariants:a.invariants,defaults:a.defaults,states:a.states,adminPages:a.adminPages,...s(a)},appMetadata:e.appMetadata,infra:{acl:n.acl,resources:n.resources,resourcesConfig:n.resourcesConfig},dataSpec:e.dataSpec}};

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

@@ -1,4 +1,5 @@
 export * from './core/index.js';
+export * from './enhanced-json/index.js';
 export * from './caching/index.js';
 export * from './errors/index.js';
 export * from './generate-application/index.js';

package/dist/application-spec/index.js

@@ -1 +1 @@
-export*from"./core/index.js";export*from"./caching/index.js";export*from"./errors/index.js";export*from"./generate-application/index.js";export*from"./parse-application-files/index.js";export*from"./webhook-boundary.js";
+export*from"./core/index.js";export*from"./enhanced-json/index.js";export*from"./caching/index.js";export*from"./errors/index.js";export*from"./generate-application/index.js";export*from"./parse-application-files/index.js";export*from"./webhook-boundary.js";

package/dist/application-spec/parse-application-files/categorize/categorize-files.d.ts

@@ -58,12 +58,28 @@ export type CategorizedFiles = Branded<'CategorizedFiles', {
     readonly adminElementsChanged: boolean;
     readonly webhooks: readonly CategorizedFile[];
     readonly webhooksChanged: boolean;
+    /**
+     * Whether the project has its webhook entry, `src/webhooks/index.ts`, whose default export is the
+     * project's webhook. Generation reads it to decide the generated webhook entry: without it the
+     * entry holds the built-in inert webhook.
+     */
+    readonly hasWebhookEntry: boolean;
     readonly locales: readonly CategorizedFile[];
     readonly localesChanged: boolean;
     readonly mockTemplates: readonly CategorizedFile[];
     readonly mockTemplatesChanged: boolean;
     readonly projectFiles: readonly CategorizedFile[];
     readonly projectFilesChanged: boolean;
+    /**
+     * One-time migration: true only on a checkout's first sync with an SDK that contains this field;
+     * delete it once projects have synced with such an SDK.
+     *
+     * Whether the project's root `tsconfig.json` is the full file earlier SDK versions generated on
+     * every sync, before the TypeScript settings moved to `.phoenix/tsconfig.json`. Generation reads
+     * it to replace that file with the one-line `tsconfig.json` that extends `.phoenix/tsconfig.json`;
+     * any other root `tsconfig.json` is the project's own and is left as it is.
+     */
+    readonly hasEarlierGeneratedTsconfig: boolean;
     readonly customCode: readonly CategorizedFile[];
     readonly customCodeChanged: boolean;
     readonly envs: Record<string, unknown>;