@salsita-ai/sdk 0.50.0-develop.97a772d197 → 0.50.0-develop.996c9540be

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/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>;

package/dist/application-spec/parse-application-files/categorize/categorize-files.js

@@ -1 +1 @@
-import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as a}from"../../errors/index.js";import{findWebhookHandlerRegistration as i}from"./module-analysis.js";import{findWebhookSafetyViolation as t}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.actions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let r=e=>/\/_[^/]+\//.test(e),m=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/actions/",key:"actions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],l=new Set(["package.json",".gitignore","CLAUDE.md",".cursor/rules/phoenix.mdc"]),d=new Set(["migrations","adminMigrations"]),c=m.filter(({path:e,key:n})=>e.startsWith("src/")&&d.has(n)),p=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},h=/\.(ts|tsx|js|jsx)$/,f=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=i(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(i,d,g,u)=>{let k={spec:[],expressions:[],actions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},b=[];for(let e of i.files){if("text"!==e.kind)continue;if(r(e.name)){k.customCode.push({file:e,category:"customCode"});continue}if(l.has(e.name)){k.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of m)if(e.name.startsWith(s)){k[o].push({file:e,category:o}),n=!0;break}n||b.push(e.name)}for(let e of b)e.startsWith("src/")&&g.error(o.UNKNOWN_SRC_PATH,a.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of c)for(let s of k[n])p(s.file.name,e)&&g.error(o.INVALID_SUBDIRECTORY,a.INVALID_SUBDIRECTORY(s.file.name,e));if(k.webhooks.length>0&&!k.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name)&&g.error(o.MISSING_WEBHOOK_INDEX,a.MISSING_WEBHOOK_INDEX()),g.hasErrors)return;let C=[];for(let e of Object.values(k))for(let n of e)C.push(n.file.name);let v=s(i,C),{analyzer:x,logger:y}=u,E=d.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:x(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),I=new Set,w=e=>{if(!h.test(e.name))return;I.add(e.name);let n=E.build({name:e.name,content:e.content}).output;return void 0!==n.error?void g.error(o.MODULE_ANALYSIS_FAILED,a[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},S={},j={};for(let[e,s]of Object.entries(k)){let o=d.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),a=new Set;S[e]=s.map(e=>{let s=v[e.file.name]??{deps:[],hash:""},{changed:i}=o.build({name:e.file.name,depHash:s.hash});a.add(e.file.name);let t=w(e.file),r=void 0===t?void 0:f(e.category,t);return void 0!==r&&y.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:i,analysis:t,webhookMembership:r?.membership})}),j[e]=o.cleanup(a)}E.cleanup(I);let _=(e,n)=>n.some(e=>e.changed)||!0===j[e],F=d.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:i.envs}),M=n({spec:S.spec,specChanged:_("spec",S.spec),expressions:S.expressions,expressionsChanged:_("expressions",S.expressions),actions:S.actions,actionsChanged:_("actions",S.actions),handlers:S.handlers,handlersChanged:_("handlers",S.handlers),elements:S.elements,elementsChanged:_("elements",S.elements),transformers:S.transformers,transformersChanged:_("transformers",S.transformers),components:S.components,componentsChanged:_("components",S.components),invariants:S.invariants,invariantsChanged:_("invariants",S.invariants),migrations:S.migrations,migrationsChanged:_("migrations",S.migrations),adminMigrations:S.adminMigrations,adminMigrationsChanged:_("adminMigrations",S.adminMigrations),adminExpressions:S.adminExpressions,adminExpressionsChanged:_("adminExpressions",S.adminExpressions),adminInvariants:S.adminInvariants,adminInvariantsChanged:_("adminInvariants",S.adminInvariants),adminComponents:S.adminComponents,adminComponentsChanged:_("adminComponents",S.adminComponents),adminElements:S.adminElements,adminElementsChanged:_("adminElements",S.adminElements),webhooks:S.webhooks,webhooksChanged:_("webhooks",S.webhooks),locales:S.locales,localesChanged:_("locales",S.locales),mockTemplates:S.mockTemplates,mockTemplatesChanged:_("mockTemplates",S.mockTemplates),projectFiles:S.projectFiles,projectFilesChanged:_("projectFiles",S.projectFiles),customCode:S.customCode,customCodeChanged:_("customCode",S.customCode),envs:F.output,envsChanged:F.changed}),O=buildProjectFileIndex(M);for(let e of O.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=t(e,O);void 0!==n&&g.error(o.WEBHOOK_UNSAFE_IMPORT,a[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return M};
+import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as i}from"../../errors/index.js";import{isEarlierGeneratedTsconfig as a}from"./earlier-generated-tsconfig.js";import{findWebhookHandlerRegistration as t}from"./module-analysis.js";import{findWebhookSafetyViolation as r}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.actions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let m=e=>/\/_[^/]+\//.test(e),l=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/actions/",key:"actions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],d="tsconfig.json",c=new Set(["package.json",".gitignore",d,"CLAUDE.md",".cursor/rules/phoenix.mdc"]),p=new Set(["migrations","adminMigrations"]),h=l.filter(({path:e,key:n})=>e.startsWith("src/")&&p.has(n)),f=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},g=/\.(ts|tsx|js|jsx)$/,u=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=t(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(t,p,k,b)=>{let C={spec:[],expressions:[],actions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},v=[];for(let e of t.files){if("text"!==e.kind)continue;if(m(e.name)){C.customCode.push({file:e,category:"customCode"});continue}if(c.has(e.name)){C.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of l)if(e.name.startsWith(s)){C[o].push({file:e,category:o}),n=!0;break}n||v.push(e.name)}for(let e of v)e.startsWith("src/")&&k.error(o.UNKNOWN_SRC_PATH,i.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of h)for(let s of C[n])f(s.file.name,e)&&k.error(o.INVALID_SUBDIRECTORY,i.INVALID_SUBDIRECTORY(s.file.name,e));let x=C.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name);if(C.webhooks.length>0&&!x&&k.error(o.MISSING_WEBHOOK_INDEX,i.MISSING_WEBHOOK_INDEX()),k.hasErrors)return;let y=C.projectFiles.find(e=>e.file.name===d),E=void 0!==y&&a(y.file.content),I=[];for(let e of Object.values(C))for(let n of e)I.push(n.file.name);let w=s(t,I),{analyzer:S,logger:j}=b,F=p.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:S(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),_=new Set,M=e=>{if(!g.test(e.name))return;_.add(e.name);let n=F.build({name:e.name,content:e.content}).output;return void 0!==n.error?void k.error(o.MODULE_ANALYSIS_FAILED,i[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},O={},N={};for(let[e,s]of Object.entries(C)){let o=p.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),i=new Set;O[e]=s.map(e=>{let s=w[e.file.name]??{deps:[],hash:""},{changed:a}=o.build({name:e.file.name,depHash:s.hash});i.add(e.file.name);let t=M(e.file),r=void 0===t?void 0:u(e.category,t);return void 0!==r&&j.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:a,analysis:t,webhookMembership:r?.membership})}),N[e]=o.cleanup(i)}F.cleanup(_);let A=(e,n)=>n.some(e=>e.changed)||!0===N[e],T=p.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:t.envs}),D=n({spec:O.spec,specChanged:A("spec",O.spec),expressions:O.expressions,expressionsChanged:A("expressions",O.expressions),actions:O.actions,actionsChanged:A("actions",O.actions),handlers:O.handlers,handlersChanged:A("handlers",O.handlers),elements:O.elements,elementsChanged:A("elements",O.elements),transformers:O.transformers,transformersChanged:A("transformers",O.transformers),components:O.components,componentsChanged:A("components",O.components),invariants:O.invariants,invariantsChanged:A("invariants",O.invariants),migrations:O.migrations,migrationsChanged:A("migrations",O.migrations),adminMigrations:O.adminMigrations,adminMigrationsChanged:A("adminMigrations",O.adminMigrations),adminExpressions:O.adminExpressions,adminExpressionsChanged:A("adminExpressions",O.adminExpressions),adminInvariants:O.adminInvariants,adminInvariantsChanged:A("adminInvariants",O.adminInvariants),adminComponents:O.adminComponents,adminComponentsChanged:A("adminComponents",O.adminComponents),adminElements:O.adminElements,adminElementsChanged:A("adminElements",O.adminElements),webhooks:O.webhooks,webhooksChanged:A("webhooks",O.webhooks),hasWebhookEntry:x,locales:O.locales,localesChanged:A("locales",O.locales),mockTemplates:O.mockTemplates,mockTemplatesChanged:A("mockTemplates",O.mockTemplates),projectFiles:O.projectFiles,projectFilesChanged:A("projectFiles",O.projectFiles),hasEarlierGeneratedTsconfig:E,customCode:O.customCode,customCodeChanged:A("customCode",O.customCode),envs:T.output,envsChanged:T.changed}),W=buildProjectFileIndex(D);for(let e of W.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=r(e,W);void 0!==n&&k.error(o.WEBHOOK_UNSAFE_IMPORT,i[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return D};

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

@@ -0,0 +1,9 @@
+/**
+ * One-time migration, see the top of this module: true only before a checkout's first sync with this SDK.
+ *
+ * Whether the content of a project's root `tsconfig.json` is the file earlier SDK versions generated.
+ * The comparison is by meaning: comments, formatting and key order do not count, so a generated
+ * file that an editor or formatter rewrote is still recognised. Content that does not parse, or that
+ * differs in any setting, is the project's own.
+ */
+export declare const isEarlierGeneratedTsconfig: (content: string) => boolean;

package/dist/application-spec/parse-application-files/categorize/earlier-generated-tsconfig.js

@@ -0,0 +1 @@
+import e from"lodash-es/isEqual.js";let l={compilerOptions:{noEmit:!0,module:"ESNext",moduleResolution:"Bundler",lib:["ES2022","DOM"],esModuleInterop:!0,isolatedModules:!0,resolveJsonModule:!0,allowJs:!1,skipLibCheck:!0,strict:!0,noImplicitOverride:!0,noImplicitReturns:!0,noPropertyAccessFromIndexSignature:!0,noUncheckedIndexedAccess:!0,allowUnreachableCode:!1,allowUnusedLabels:!1,noFallthroughCasesInSwitch:!0,noUnusedLocals:!0,noUnusedParameters:!0,useDefineForClassFields:!0,jsx:"react-jsx",paths:{}},include:["src",".phoenix","prettier.config.js","eslint.config.js","./.phoenix/globals.d.ts"]},s=(e,l)=>{let s=l+1;for(;s<e.length&&'"'!==e[s];)s+="\\"===e[s]?2:1;return s+1};export const isEarlierGeneratedTsconfig=t=>e((e=>{try{return JSON.parse((e=>{let l="",t=0;for(;t<e.length;){let n=e[t];if('"'===n){let n=s(e,t);l+=e.slice(t,n),t=n;continue}","===n&&/^\s*[}\]]/.test(e.slice(t+1))||(l+=n),t++}return l})((e=>{let l="",t=0;for(;t<e.length;){let n=e[t],o=e[t+1];if('"'===n){let n=s(e,t);l+=e.slice(t,n),t=n}else if("/"===n&&"/"===o){let l=e.indexOf("\n",t);t=-1===l?e.length:l}else if("/"===n&&"*"===o){let l=e.indexOf("*/",t+2);t=-1===l?e.length:l+2}else l+=n,t++}return l})(e)))}catch{return}})(t),l);

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

@@ -43,6 +43,6 @@ export declare const analyzeParsedModule: (module: Module) => ModuleAnalysis;
 /** The explicit webhook classification of one authored file. */
 export type WebhookMembership = 'pinned' | 'named-handler' | 'frontend';
 /** Handler registrations that keep implicit webhook membership for legacy-CLI parity. */
-export declare const WEBHOOK_HANDLER_REGISTRATIONS: readonly ['createMapPublishedRevisionDataHandler', 'createMapPublishedChunkedDataHandler', 'createDataRowValidatorHandler', 'createSheetValidatorHandler'];
+export declare const WEBHOOK_HANDLER_REGISTRATIONS: readonly ['phx.domain.createAssistantSetupHandler', 'phx.domain.admin.createMapPublishedRevisionDataHandler', 'phx.domain.admin.createMapPublishedChunkedDataHandler', 'phx.domain.admin.createDataRowValidatorHandler', 'phx.domain.admin.createSheetValidatorHandler'];
 /** Returns the named webhook handler registration a handler module calls, if any. */
 export declare const findWebhookHandlerRegistration: (analysis: ModuleAnalysis) => string | undefined;

package/dist/application-spec/parse-application-files/categorize/module-analysis.js

@@ -1 +1 @@
-import{Visitor as e}from"@swc/core/Visitor.js";export const getModuleParseOptions=()=>({syntax:"typescript",tsx:!0,target:"es2022"});let t=e=>{if("Identifier"===e.type)return e.value;if("ParenthesisExpression"===e.type)return t(e.expression);if("MemberExpression"!==e.type||"Identifier"!==e.property.type)return;let r=t(e.object);return void 0===r?void 0:`${r}.${e.property.value}`},r=e=>e.length>0&&e.every(e=>"isTypeOnly"in e&&!0===e.isTypeOnly),i=class ProjectSourceVisitor extends e{imports=[];calledMemberPaths=new Set;visitTsType(e){return e}visitImportDeclaration(e){return this.imports.push({specifier:e.source.value,typeOnly:e.typeOnly||r(e.specifiers)}),e}visitExportNamedDeclaration(e){return null!=e.source&&this.imports.push({specifier:e.source.value,typeOnly:e.typeOnly||r(e.specifiers)}),super.visitExportNamedDeclaration(e)}visitExportAllDeclaration(e){return this.imports.push({specifier:e.source.value,typeOnly:"typeOnly"in e&&!0===e.typeOnly}),e}visitCallExpression(e){var r;let i=(r=e.arguments[0]?.expression,r?.type==="StringLiteral"?r.value:r?.type==="TemplateLiteral"&&0===r.expressions.length?r.quasis[0]?.cooked??r.quasis[0]?.raw:void 0);if("Import"===e.callee.type&&void 0!==i)this.imports.push({specifier:i,typeOnly:!1});else if("Super"!==e.callee.type&&"Import"!==e.callee.type){let r=t(e.callee);void 0!==r&&this.calledMemberPaths.add(r),"require"===r&&void 0!==i&&this.imports.push({specifier:i,typeOnly:!1})}return super.visitCallExpression(e)}};export const analyzeParsedModule=e=>{let t=new i;t.visitModule(e);let r=e.body[0];return{imports:t.imports,calledMemberPaths:[...t.calledMemberPaths].sort(),hasUseWebhookDirective:r?.type==="ExpressionStatement"&&"StringLiteral"===r.expression.type&&"use webhook"===r.expression.value}};export const WEBHOOK_HANDLER_REGISTRATIONS=["createMapPublishedRevisionDataHandler","createMapPublishedChunkedDataHandler","createDataRowValidatorHandler","createSheetValidatorHandler"];export const findWebhookHandlerRegistration=e=>WEBHOOK_HANDLER_REGISTRATIONS.find(t=>e.calledMemberPaths.includes(`phx.domain.admin.${t}`));
+import{Visitor as e}from"@swc/core/Visitor.js";export const getModuleParseOptions=()=>({syntax:"typescript",tsx:!0,target:"es2022"});let t=e=>{if("Identifier"===e.type)return e.value;if("ParenthesisExpression"===e.type)return t(e.expression);if("MemberExpression"!==e.type||"Identifier"!==e.property.type)return;let r=t(e.object);return void 0===r?void 0:`${r}.${e.property.value}`},r=e=>e.length>0&&e.every(e=>"isTypeOnly"in e&&!0===e.isTypeOnly),i=class ProjectSourceVisitor extends e{imports=[];calledMemberPaths=new Set;visitTsType(e){return e}visitImportDeclaration(e){return this.imports.push({specifier:e.source.value,typeOnly:e.typeOnly||r(e.specifiers)}),e}visitExportNamedDeclaration(e){return null!=e.source&&this.imports.push({specifier:e.source.value,typeOnly:e.typeOnly||r(e.specifiers)}),super.visitExportNamedDeclaration(e)}visitExportAllDeclaration(e){return this.imports.push({specifier:e.source.value,typeOnly:"typeOnly"in e&&!0===e.typeOnly}),e}visitCallExpression(e){var r;let i=(r=e.arguments[0]?.expression,r?.type==="StringLiteral"?r.value:r?.type==="TemplateLiteral"&&0===r.expressions.length?r.quasis[0]?.cooked??r.quasis[0]?.raw:void 0);if("Import"===e.callee.type&&void 0!==i)this.imports.push({specifier:i,typeOnly:!1});else if("Super"!==e.callee.type&&"Import"!==e.callee.type){let r=t(e.callee);void 0!==r&&this.calledMemberPaths.add(r),"require"===r&&void 0!==i&&this.imports.push({specifier:i,typeOnly:!1})}return super.visitCallExpression(e)}};export const analyzeParsedModule=e=>{let t=new i;t.visitModule(e);let r=e.body[0];return{imports:t.imports,calledMemberPaths:[...t.calledMemberPaths].sort(),hasUseWebhookDirective:r?.type==="ExpressionStatement"&&"StringLiteral"===r.expression.type&&"use webhook"===r.expression.value}};export const WEBHOOK_HANDLER_REGISTRATIONS=["phx.domain.createAssistantSetupHandler","phx.domain.admin.createMapPublishedRevisionDataHandler","phx.domain.admin.createMapPublishedChunkedDataHandler","phx.domain.admin.createDataRowValidatorHandler","phx.domain.admin.createSheetValidatorHandler"];export const findWebhookHandlerRegistration=e=>WEBHOOK_HANDLER_REGISTRATIONS.find(t=>e.calledMemberPaths.includes(t));

package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.d.ts

@@ -1,13 +1,26 @@
 import { z } from 'zod';
 import { type AssistantAiSettings } from '@salsita-ai/contracts/assistant';
+import { ASSISTANT_HINTS } from '#package/domain';
 /**
  * One whitelisted field in the assistant manifest. `description` overrides the JSON Schema
- * description of the shape property; `as` exposes the field under a different GraphQL name. An empty
+ * description of the shape property; `as` exposes the field under a different GraphQL name; `lenses`
+ * names the lenses declared under `assistant.lenses` whose selection includes the field. An empty
  * entry (`length:` in YAML) whitelists the field with its defaults.
  */
 export interface RawAssistantField {
     readonly description?: string;
     readonly as?: string;
+    readonly lenses?: readonly string[];
+}
+/**
+ * One lens of the assistant `lenses` map, keyed by the name the agent spreads it by: a named
+ * selection made of the `entities` entries tagged with that name. `description` tells the agent when
+ * to use the lens; `maxDepth` is how many levels of tagged relations carry the same selection before
+ * they reduce to `id`, 1 by default.
+ */
+export interface RawAssistantLens {
+    readonly description: string;
+    readonly maxDepth?: number;
 }
 /**
  * One entry of the assistant `deletable` map. It takes no options yet; an empty entry (`Cabinet:` in
@@ -23,7 +36,6 @@ export type AssistantOptionComponentType = (typeof ASSISTANT_OPTION_COMPONENT_TY
  * does not change during a session. A hint only adds a sentence to a generated description; nothing
  * verifies it.
  */
-export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
 export type AssistantHint = (typeof ASSISTANT_HINTS)[number];
 /**
  * The component that holds the choices of a writable field: the instance `instanceName` of the
@@ -89,7 +101,7 @@ export interface RawAssistantAction {
  * with `addChild`. `replaceRecipes` names, per entity type or alias, the `replaceEntityRecipes`
  * groups whose recipes the agent may list and replace the entity by with `replaceEntity`. `actions`
  * names the declared actions the agent may run as custom mutations. Nothing is exposed without an
- * entry.
+ * entry. `lenses` declares the named selections that `entities` entries are tagged with.
  *
  * `ai` and `instructions` are for the server only: the provider, model tier and reasoning level the
  * deployment's assistant runs with, and the integrator's own guidance for it, appended to the system
@@ -102,6 +114,7 @@ export interface RawAssistant {
     readonly childRecipes?: Readonly<Record<string, RawAssistantRecipes>>;
     readonly replaceRecipes?: Readonly<Record<string, RawAssistantRecipes>>;
     readonly actions?: Readonly<Record<string, RawAssistantAction | null>>;
+    readonly lenses?: Readonly<Record<string, RawAssistantLens>>;
     readonly instructions?: string;
     readonly ai: AssistantAiSettings;
 }

package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.js

@@ -1 +1 @@
-import{z as t}from"zod";import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as o,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";export const ASSISTANT_OPTION_COMPONENT_TYPES=["materialSwatch","attributeSelection","distanceDimensionSelect"];export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];let n=t.string().regex(/^(?!__)[_A-Za-z][_0-9A-Za-z]*$/,'must be a GraphQL name: letters, digits and "_", not starting with a digit or "__"'),r=e=>t.enum(e,{errorMap:()=>({message:`must be one of: ${e.join(", ")}`})}),s=t.object({description:t.string().optional(),as:n.optional()}).strict(),a=t.array(r(ASSISTANT_HINTS)),c=t.object({options:t.object({componentType:r(ASSISTANT_OPTION_COMPONENT_TYPES),instanceName:t.string().min(1,"must not be empty; name the component instance that holds the choices"),as:n.optional(),validate:t.boolean().optional(),allowDryRuns:t.boolean().optional(),hints:a.optional()}).strict().optional()}).strict(),l=t.object({as:t.string().trim().min(1,"must not be empty; remove the key to use the instance name").optional(),description:t.string().optional(),allowDryRuns:t.boolean().optional()}).strict(),p=e=>t.object({hints:a.optional(),groups:t.record(t.string(),l.nullable(),{required_error:`is required: the recipe groups of the type go under "groups", keyed by the instance name of a "${e}" component`})}).strict(),d=t.object({description:t.string().optional(),as:n.optional()}).strict(),m=`is required: declare provider (${e.join(", ")}), model (${o.join(", ")}) and reasoning (${i.join(", ")})`,g=t.object({provider:r(e),model:r(o),reasoning:r(i)},{required_error:m,invalid_type_error:m}).strict();export const rawAssistantSchema=t.object({entities:t.record(t.string(),t.record(t.string(),s.nullable())).optional(),deletable:t.record(t.string(),t.object({}).strict().nullable()).optional(),writable:t.record(t.string(),t.record(t.string(),c.nullable())).optional(),childRecipes:t.record(t.string(),p("childEntityRecipes")).optional(),replaceRecipes:t.record(t.string(),p("replaceEntityRecipes")).optional(),actions:t.record(t.string(),d.nullable()).optional(),instructions:t.string().trim().min(1,"must not be empty; remove the key when there are no instructions").optional(),ai:g}).strict();
+import{z as e}from"zod";import{ASSISTANT_AI_PROVIDERS as t,ASSISTANT_MODEL_TIERS as o,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";import{ASSISTANT_HINTS as n}from"#package/domain";export const ASSISTANT_OPTION_COMPONENT_TYPES=["materialSwatch","attributeSelection","distanceDimensionSelect"];let r=e.string().regex(/^(?!__)[_A-Za-z][_0-9A-Za-z]*$/,'must be a GraphQL name: letters, digits and "_", not starting with a digit or "__"'),s=t=>e.enum(t,{errorMap:()=>({message:`must be one of: ${t.join(", ")}`})}),a=e.object({description:e.string().optional(),as:r.optional(),lenses:e.array(e.string()).optional()}).strict(),l="must be a whole number of at least 1; remove the key to nest tagged relations one level",c=e.object({description:e.string().trim().min(1,"must not be empty; say when the agent should use the lens"),maxDepth:e.number({invalid_type_error:l}).int(l).min(1,l).optional()}).strict(),p=r.refine(e=>!e.includes("__"),'must not contain "__", which names the generated copies of a lens'),m=e.array(s(n)),d=e.object({options:e.object({componentType:s(ASSISTANT_OPTION_COMPONENT_TYPES),instanceName:e.string().min(1,"must not be empty; name the component instance that holds the choices"),as:r.optional(),validate:e.boolean().optional(),allowDryRuns:e.boolean().optional(),hints:m.optional()}).strict().optional()}).strict(),u=e.object({as:e.string().trim().min(1,"must not be empty; remove the key to use the instance name").optional(),description:e.string().optional(),allowDryRuns:e.boolean().optional()}).strict(),h=t=>e.object({hints:m.optional(),groups:e.record(e.string(),u.nullable(),{required_error:`is required: the recipe groups of the type go under "groups", keyed by the instance name of a "${t}" component`})}).strict(),b=e.object({description:e.string().optional(),as:r.optional()}).strict(),g=`is required: declare provider (${t.join(", ")}), model (${o.join(", ")}) and reasoning (${i.join(", ")})`,_="must be a positive whole number of input tokens; remove the key to use the default of the server",y=e.object({provider:s(t),model:s(o),reasoning:s(i),maxThreadSize:e.number({invalid_type_error:_}).int(_).positive(_).optional()},{required_error:g,invalid_type_error:g}).strict();export const rawAssistantSchema=e.object({entities:e.record(e.string(),e.record(e.string(),a.nullable())).optional(),deletable:e.record(e.string(),e.object({}).strict().nullable()).optional(),writable:e.record(e.string(),e.record(e.string(),d.nullable())).optional(),childRecipes:e.record(e.string(),h("childEntityRecipes")).optional(),replaceRecipes:e.record(e.string(),h("replaceEntityRecipes")).optional(),actions:e.record(e.string(),b.nullable()).optional(),lenses:e.record(p,c).optional(),instructions:e.string().trim().min(1,"must not be empty; remove the key when there are no instructions").optional(),ai:y}).strict();

package/dist/application-spec/parse-application-files/raw-spec/raw-spec-file.js

@@ -1 +1 @@
-import{z as o}from"zod";import{Branded as a}from"@salsita-ai/common/utils";import{enhancedJsonObjectSchema as t,validateNoLegacyCodeRef as e}from"../../core/index.js";import{DiagnosticCode as n,diagnosticMessages as i}from"../../errors/index.js";import{rawAclSchema as r}from"./raw-acl.js";import{rawActionsSchema as s}from"./raw-actions.js";import{rawAdminPagesSchema as l}from"./raw-admin-pages.js";import{rawAssistantSchema as p}from"./raw-assistant.js";import{rawBudgetsSchema as m}from"./raw-budgets.js";import{rawChunksSchema as c}from"./raw-chunks.js";import{rawComponentsSchema as f}from"./raw-components.js";import{rawConstantsSchema as d}from"./raw-constants.js";import{rawDataSpecSchema as u}from"./raw-data.js";import{rawDefaultsSchema as j}from"./raw-defaults.js";import{rawEnvSchema as w}from"./raw-env.js";import{rawExpressionsSchema as b}from"./raw-expressions.js";import{rawInvariantsSchema as g}from"./raw-invariants.js";import{rawModelSchema as S}from"./raw-model.js";import{rawPresetsSchema as D}from"./raw-presets.js";import{rawRelationsSchema as h}from"./raw-relations.js";import{rawResourcesConfigSchema as v,rawResourcesSchema as O}from"./raw-resources.js";import{rawStateValuesSchema as E}from"./raw-states.js";import{rawTransformersSchema as R}from"./raw-transformers.js";export const DATA_SCHEMA_KEYS=["publishedData","sessionData","frontendData","backendData","finalizeData","prefetchedFinalizeData","finalizeResult","callbackData"];let k=o.object({$admin:o.boolean().optional(),model:S.optional(),components:f.optional(),presets:D.optional(),$data:u.optional(),expressions:b.optional(),actions:s.optional(),invariants:g.optional(),constants:d.optional(),relations:h.optional(),defaults:j.optional(),publishedData:t.optional(),sessionData:t.optional(),frontendData:t.optional(),backendData:t.optional(),finalizeData:t.optional(),prefetchedFinalizeData:t.optional(),finalizeResult:t.optional(),callbackData:t.optional(),navigationStates:E.optional(),viewStates:E.optional(),toolStates:E.optional(),exportStates:E.optional(),themePreset:o.string().optional(),themeOptions:o.record(o.unknown()).optional(),preview:o.enum(["always","never","auto","hide"]).optional(),alwaysExpand:o.boolean().optional(),availableLocales:o.array(o.string()).optional(),textLanguages:o.array(o.string()).optional(),transformers:R.optional(),project:o.string().regex(/^[a-z0-9-]{3,}$/,"must be a project slug (lowercase letters, digits and dashes, at least 3) or `default`").optional(),applicationVersion:o.string().optional(),workspace:o.boolean().optional(),webComponentTag:o.string().optional(),pageTitle:o.string().optional(),useAuthHook:o.boolean().optional(),useClerk:o.boolean().optional(),enableAdminRelease:o.boolean().optional(),jsonSchemaValidator:o.enum(["ajv","csp-compatible"]).optional(),gltfDecoder:o.enum(["js","wasm"]).optional(),appLoader:o.enum(["legacy","universal"]).optional(),collectFinalizeData:o.boolean().optional(),env:w.optional(),acl:r.optional(),resources:O.optional(),resourcesConfig:v.optional(),budgets:m.optional(),chunks:c.optional(),assistant:p.optional(),$adminPages:l.optional()}).strict();export const parseRawSpecFile=(o,t)=>{e(o.content,t);let r=k.safeParse(o.content);if(!r.success){for(let o of r.error.issues)t.error(n.SCHEMA_PARSE_ERROR,i.SCHEMA_PARSE_ERROR(o.path.join("."),o.message));return}let{constants:s,...l}=r.data,p=((o,a)=>{let t=Object.fromEntries(Object.entries(o.expressions??{}).map(([o,a])=>[o,{...a}]));if(void 0===o.constants)return Object.keys(t).length>0?t:void 0;for(let[e,r]of Object.entries(o.constants))for(let[o,s]of(t[e]||(t[e]={}),Object.entries(r))){if(void 0!==t[e][o]){a.at("constants",e,o).error(n.CONSTANTS_EXPRESSION_CONFLICT,i[n.CONSTANTS_EXPRESSION_CONFLICT](e,o));continue}t[e][o]={kind:"value",constant:!0,value:s,schema:{}}}return Object.keys(t).length>0?t:void 0})(r.data,t);return a({name:o.name,content:{...l,expressions:p}})};
+import{z as o}from"zod";import{Branded as a}from"@salsita-ai/common/utils";import{enhancedJsonObjectSchema as t}from"../../core/index.js";import{validateNoLegacyCodeRef as e}from"../../enhanced-json/index.js";import{DiagnosticCode as n,diagnosticMessages as i}from"../../errors/index.js";import{rawAclSchema as r}from"./raw-acl.js";import{rawActionsSchema as s}from"./raw-actions.js";import{rawAdminPagesSchema as l}from"./raw-admin-pages.js";import{rawAssistantSchema as p}from"./raw-assistant.js";import{rawBudgetsSchema as m}from"./raw-budgets.js";import{rawChunksSchema as c}from"./raw-chunks.js";import{rawComponentsSchema as f}from"./raw-components.js";import{rawConstantsSchema as d}from"./raw-constants.js";import{rawDataSpecSchema as j}from"./raw-data.js";import{rawDefaultsSchema as u}from"./raw-defaults.js";import{rawEnvSchema as w}from"./raw-env.js";import{rawExpressionsSchema as b}from"./raw-expressions.js";import{rawInvariantsSchema as g}from"./raw-invariants.js";import{rawModelSchema as S}from"./raw-model.js";import{rawPresetsSchema as h}from"./raw-presets.js";import{rawRelationsSchema as D}from"./raw-relations.js";import{rawResourcesConfigSchema as v,rawResourcesSchema as O}from"./raw-resources.js";import{rawStateValuesSchema as E}from"./raw-states.js";import{rawTransformersSchema as R}from"./raw-transformers.js";export const DATA_SCHEMA_KEYS=["publishedData","sessionData","frontendData","backendData","finalizeData","prefetchedFinalizeData","finalizeResult","callbackData"];let k=o.object({$admin:o.boolean().optional(),model:S.optional(),components:f.optional(),presets:h.optional(),$data:j.optional(),expressions:b.optional(),actions:s.optional(),invariants:g.optional(),constants:d.optional(),relations:D.optional(),defaults:u.optional(),publishedData:t.optional(),sessionData:t.optional(),frontendData:t.optional(),backendData:t.optional(),finalizeData:t.optional(),prefetchedFinalizeData:t.optional(),finalizeResult:t.optional(),callbackData:t.optional(),navigationStates:E.optional(),viewStates:E.optional(),toolStates:E.optional(),exportStates:E.optional(),themePreset:o.string().optional(),themeOptions:o.record(o.unknown()).optional(),preview:o.enum(["always","never","auto","hide"]).optional(),alwaysExpand:o.boolean().optional(),availableLocales:o.array(o.string()).optional(),textLanguages:o.array(o.string()).optional(),transformers:R.optional(),project:o.string().regex(/^[a-z0-9-]{3,}$/,"must be a project slug (lowercase letters, digits and dashes, at least 3) or `default`").optional(),applicationVersion:o.string().optional(),workspace:o.boolean().optional(),webComponentTag:o.string().optional(),pageTitle:o.string().optional(),useAuthHook:o.boolean().optional(),useClerk:o.boolean().optional(),enableAdminRelease:o.boolean().optional(),jsonSchemaValidator:o.enum(["ajv","csp-compatible"]).optional(),gltfDecoder:o.enum(["js","wasm"]).optional(),appLoader:o.enum(["legacy","universal"]).optional(),collectFinalizeData:o.boolean().optional(),env:w.optional(),acl:r.optional(),resources:O.optional(),resourcesConfig:v.optional(),budgets:m.optional(),chunks:c.optional(),assistant:p.optional(),$adminPages:l.optional()}).strict();export const parseRawSpecFile=(o,t)=>{e(o.content,t);let r=k.safeParse(o.content);if(!r.success){for(let o of r.error.issues)t.error(n.SCHEMA_PARSE_ERROR,i.SCHEMA_PARSE_ERROR(o.path.join("."),o.message));return}let{constants:s,...l}=r.data,p=((o,a)=>{let t=Object.fromEntries(Object.entries(o.expressions??{}).map(([o,a])=>[o,{...a}]));if(void 0===o.constants)return Object.keys(t).length>0?t:void 0;for(let[e,r]of Object.entries(o.constants))for(let[o,s]of(t[e]||(t[e]={}),Object.entries(r))){if(void 0!==t[e][o]){a.at("constants",e,o).error(n.CONSTANTS_EXPRESSION_CONFLICT,i[n.CONSTANTS_EXPRESSION_CONFLICT](e,o));continue}t[e][o]={kind:"value",constant:!0,value:s,schema:{}}}return Object.keys(t).length>0?t:void 0})(r.data,t);return a({name:o.name,content:{...l,expressions:p}})};