@salsita-ai/sdk 0.50.0-develop.2331d4a6b7 → 0.50.0-develop.26a71cda28

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
@@ -68,6 +80,16 @@ export interface RawAssistantRecipes {
     readonly hints?: readonly AssistantHint[];
     readonly groups: Readonly<Record<string, RawAssistantRecipeGroup | null>>;
 }
+/**
+ * One entry of the assistant `actions` map, keyed by the name of an action declared under the
+ * top-level `actions` block: it exposes the action as a `Mutation` field named `as` (the action name
+ * by default) with `description` (the action's own by default). An empty entry (`movePartBy:` in
+ * YAML) exposes the action with its defaults.
+ */
+export interface RawAssistantAction {
+    readonly description?: string;
+    readonly as?: string;
+}
 /**
  * Experimental assistant manifest authored under the `assistant` root key. `entities` whitelists the
  * stored fields the generated GraphQL schema exposes, keyed by entity type or alias name and then by
@@ -77,8 +99,9 @@ export interface RawAssistantRecipes {
  * have to be exposed in `entities`. `childRecipes` names, per
  * entity type or alias, the `childEntityRecipes` groups whose recipes the agent may list and add
  * 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`. Nothing is
- * exposed without an entry.
+ * 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. `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
@@ -90,6 +113,8 @@ export interface RawAssistant {
     readonly writable?: Readonly<Record<string, Readonly<Record<string, RawAssistantWritableField | null>>>>;
     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(),m=`is required: declare provider (${e.join(", ")}), model (${o.join(", ")}) and reasoning (${i.join(", ")})`,d=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(),instructions:t.string().trim().min(1,"must not be empty; remove the key when there are no instructions").optional(),ai:d}).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.d.ts

@@ -2,6 +2,7 @@ import { Branded } from '@salsita-ai/common/utils';
 import { type EnhancedJsonObjectSchemaType, type ParseContext } from '../../core/index.js';
 import type { ParsedYamlFile } from './parse-yaml-spec-file.js';
 import { type RawAcl } from './raw-acl.js';
+import { type RawActions } from './raw-actions.js';
 import { type RawAdminPages } from './raw-admin-pages.js';
 import { type RawAssistant } from './raw-assistant.js';
 import { type RawBudgets } from './raw-budgets.js';
@@ -24,6 +25,7 @@ export interface RawSpecContent {
     readonly presets?: RawPresets;
     readonly $data?: RawDataSpec;
     readonly expressions?: RawExpressions;
+    readonly actions?: RawActions;
     readonly invariants?: RawInvariants;
     readonly relations?: RawRelations;
     readonly defaults?: RawDefaults;

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 r}from"../../errors/index.js";import{rawAclSchema as i}from"./raw-acl.js";import{rawAdminPagesSchema as s}from"./raw-admin-pages.js";import{rawAssistantSchema as l}from"./raw-assistant.js";import{rawBudgetsSchema as p}from"./raw-budgets.js";import{rawChunksSchema as m}from"./raw-chunks.js";import{rawComponentsSchema as c}from"./raw-components.js";import{rawConstantsSchema as f}from"./raw-constants.js";import{rawDataSpecSchema as d}from"./raw-data.js";import{rawDefaultsSchema as u}from"./raw-defaults.js";import{rawEnvSchema as j}from"./raw-env.js";import{rawExpressionsSchema as w}from"./raw-expressions.js";import{rawInvariantsSchema as b}from"./raw-invariants.js";import{rawModelSchema as g}from"./raw-model.js";import{rawPresetsSchema as S}from"./raw-presets.js";import{rawRelationsSchema as D}from"./raw-relations.js";import{rawResourcesConfigSchema as h,rawResourcesSchema as v}from"./raw-resources.js";import{rawStateValuesSchema as O}from"./raw-states.js";import{rawTransformersSchema as E}from"./raw-transformers.js";export const DATA_SCHEMA_KEYS=["publishedData","sessionData","frontendData","backendData","finalizeData","prefetchedFinalizeData","finalizeResult","callbackData"];let R=o.object({$admin:o.boolean().optional(),model:g.optional(),components:c.optional(),presets:S.optional(),$data:d.optional(),expressions:w.optional(),invariants:b.optional(),constants:f.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:O.optional(),viewStates:O.optional(),toolStates:O.optional(),exportStates:O.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:E.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:j.optional(),acl:i.optional(),resources:v.optional(),resourcesConfig:h.optional(),budgets:p.optional(),chunks:m.optional(),assistant:l.optional(),$adminPages:s.optional()}).strict();export const parseRawSpecFile=(o,t)=>{e(o.content,t);let i=R.safeParse(o.content);if(!i.success){for(let o of i.error.issues)t.error(n.SCHEMA_PARSE_ERROR,r.SCHEMA_PARSE_ERROR(o.path.join("."),o.message));return}let{constants:s,...l}=i.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,i]of Object.entries(o.constants))for(let[o,s]of(t[e]||(t[e]={}),Object.entries(i))){if(void 0!==t[e][o]){a.at("constants",e,o).error(n.CONSTANTS_EXPRESSION_CONFLICT,r[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})(i.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}})};

package/dist/application-spec/parse-application-files/resolve/resolve-import-modules.js

@@ -1 +1 @@
-import{mapSchema as e,resolveProjectFileImport as t,resolveProjectPath as r}from"../../core/index.js";import{DiagnosticCode as o,diagnosticMessages as s}from"../../errors/index.js";import{DATA_SCHEMA_KEYS as m}from"../raw-spec/index.js";let n=(m,n,p,i)=>e(m,(e,m)=>e.import?{...e,import:e.import.map((e,a)=>{if(!e.module.startsWith("."))return e;let c=r(n,e.module),O=i.at(...m,"import",String(a),"module");c.escapedProjectRoot?O.warning(o.IMPORT_MODULE_OUTSIDE_PROJECT,s[o.IMPORT_MODULE_OUTSIDE_PROJECT](e.module,c.path)):t(n,e.module,p)||O.error(o.IMPORT_MODULE_NOT_FOUND,s[o.IMPORT_MODULE_NOT_FOUND](e.module,c.path));let d=c.path.startsWith(".")?c.path:`./${c.path}`;return{...e,module:d}})}:e);export const resolveImportModules=(e,t,r)=>{let o=e.content.model?Object.fromEntries(Object.entries(e.content.model).map(([o,s])=>[o,{...s,...s.commonTypes?{commonTypes:Object.fromEntries(Object.entries(s.commonTypes).map(([s,m])=>[s,n(m,e.name,t,r.at("model",o,"commonTypes",s))]))}:{},...s.shapes?{shapes:Object.fromEntries(Object.entries(s.shapes).map(([s,m])=>[s,Object.fromEntries(Object.entries(m).map(([m,p])=>[m,n(p,e.name,t,r.at("model",o,"shapes",s,m))]))]))}:{}}])):void 0,s=e.content.expressions?Object.fromEntries(Object.entries(e.content.expressions).map(([o,s])=>[o,Object.fromEntries(Object.entries(s).map(([s,m])=>[s,{...m,schema:n(m.schema,e.name,t,r.at("expressions",o,s))}]))])):void 0,p=Object.fromEntries(m.flatMap(o=>{let s,m=e.content[o];return m?[[o,{...s=n(m,e.name,t,r.at(o)),type:"object",properties:s.properties??{},required:s.required??[],additionalProperties:!1}]]:[]}));return{...e.content,...o?{model:o}:{},...s?{expressions:s}:{},...p}};
+import{mapSchema as e,resolveProjectFileImport as t,resolveProjectPath as r}from"../../core/index.js";import{DiagnosticCode as o,diagnosticMessages as s}from"../../errors/index.js";import{DATA_SCHEMA_KEYS as n}from"../raw-spec/index.js";let m=(n,m,a,i)=>e(n,(e,n)=>e.import?{...e,import:e.import.map((e,p)=>{if(!e.module.startsWith("."))return e;let c=r(m,e.module),O=i.at(...n,"import",String(p),"module");c.escapedProjectRoot?O.warning(o.IMPORT_MODULE_OUTSIDE_PROJECT,s[o.IMPORT_MODULE_OUTSIDE_PROJECT](e.module,c.path)):t(m,e.module,a)||O.error(o.IMPORT_MODULE_NOT_FOUND,s[o.IMPORT_MODULE_NOT_FOUND](e.module,c.path));let l=c.path.startsWith(".")?c.path:`./${c.path}`;return{...e,module:l}})}:e);export const resolveImportModules=(e,t,r)=>{let o=e.content.model?Object.fromEntries(Object.entries(e.content.model).map(([o,s])=>[o,{...s,...s.commonTypes?{commonTypes:Object.fromEntries(Object.entries(s.commonTypes).map(([s,n])=>[s,m(n,e.name,t,r.at("model",o,"commonTypes",s))]))}:{},...s.shapes?{shapes:Object.fromEntries(Object.entries(s.shapes).map(([s,n])=>[s,Object.fromEntries(Object.entries(n).map(([n,a])=>[n,m(a,e.name,t,r.at("model",o,"shapes",s,n))]))]))}:{}}])):void 0,s=e.content.expressions?Object.fromEntries(Object.entries(e.content.expressions).map(([o,s])=>[o,Object.fromEntries(Object.entries(s).map(([s,n])=>[s,{...n,schema:m(n.schema,e.name,t,r.at("expressions",o,s))}]))])):void 0,a=e.content.actions?Object.fromEntries(Object.entries(e.content.actions).map(([o,s])=>{let n=(s,n)=>Object.fromEntries(Object.entries(s).map(([s,a])=>[s,m(a,e.name,t,r.at("actions",o,n,s))]));return[o,{...s,params:n(s.params,"params"),result:n(s.result,"result")}]})):void 0,i=Object.fromEntries(n.flatMap(o=>{let s,n=e.content[o];return n?[[o,{...s=m(n,e.name,t,r.at(o)),type:"object",properties:s.properties??{},required:s.required??[],additionalProperties:!1}]]:[]}));return{...e.content,...o?{model:o}:{},...s?{expressions:s}:{},...a?{actions:a}:{},...i}};

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

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as t,diagnosticMessages as s}from"../../../../errors/index.js";import{Components as n,UserComponents as r}from"../../components/index.js";import{Expressions as o}from"../../expressions/index.js";import{Invariants as i}from"../../invariants/index.js";import{ConfigurationSchema as a,Defaults as m,ModelVersion as l,Presets as p}from"../../model/index.js";import{Relations as d}from"../../relations/index.js";import{ResolvedVersions as f}from"../resolved-versions.js";import{AdminPages as S}from"./admin-pages.js";import{AdminStates as v}from"./states.js";export const AdminSpec=(g,x)=>{let{rawModel:u,rawPresets:I,rawExpressions:N,rawInvariants:T,rawRelations:_,rawDefaults:c,migrationFiles:j,rawComponents:A,rawAdminPages:C,dataSpec:E,phxDefinitions:M,evalExpressionParser:h,label:L,requireMigrationFiles:y}=g;if(0===Object.keys(u).length)return void x.at(L).error(t.MISSING_MODEL,s.MISSING_MODEL(L));u.latest||x.at(L).error(t.MISSING_LATEST,s.MISSING_LATEST(L));let G=new Map;for(let[e,t]of Object.entries(u)){let s=l(e,t,M,x.at(L,e));s&&G.set(s.versionKey,s)}if(x.hasErrors)return;let O=f(G,j,x,{requireMigrationFiles:y});if(!O)return;let D=O.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!D)return;let V=O.latestVersion,P=a(D,V),b=d(_,D,x),w=i({rawInvariants:T,rawExpressions:N,rawRelations:_,rawComponents:A},D,x),F=p(I,D,b,x),k=S(C,{latestModel:D,parsingContext:x.at(L,"$adminPages")},E);if(!k)return;let K=r(A,{allNames:D.allNames,resolvedShapes:D.resolvedShapes,parsingContext:x}),$=m(c,D,x.at(L,"defaults")),q=o({rawExpressions:N,inferredExpressions:[...b.expressions,...w.expressions,...K.expressions]},{latestModel:D,aliases:D.aliases,entityTypes:D.entityTypes,evalExpressionParser:h,parsingContext:x}),z=n({userComponents:K.components,generatedComponents:[...b.components,...k.components],invariantComponents:w.components},{aliases:D.aliases,parsingContext:x});if(void 0!==$&&void 0!==q&&void 0!==z)return e({latestModel:D,schemaVersion:V,resolvedVersions:O,components:z,configurationSchema:P,presets:F,expressions:q,invariants:w,defaults:$,states:v(((n,r,o)=>{if(0===r.length)return n;let i=1===n.navigationStates.length&&"Default"===n.navigationStates[0]?[]:n.navigationStates,a=i.filter(e=>r.includes(e));return a.length>0&&o.error(t.ADMIN_PAGES_NAV_STATE_CONFLICT,s.ADMIN_PAGES_NAV_STATE_CONFLICT(a)),e({...n,navigationStates:[...i,...r]})})(g.rawStates,k.navigationStates,x),x),adminPages:k})};
+import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as t,diagnosticMessages as s}from"../../../../errors/index.js";import{Components as n,UserComponents as r}from"../../components/index.js";import{Expressions as o}from"../../expressions/index.js";import{Invariants as i}from"../../invariants/index.js";import{ConfigurationSchema as a,Defaults as m,ModelVersion as l,Presets as p}from"../../model/index.js";import{Relations as d}from"../../relations/index.js";import{ResolvedVersions as f}from"../resolved-versions.js";import{AdminPages as S}from"./admin-pages.js";import{AdminStates as v}from"./states.js";export const AdminSpec=(g,x)=>{let{rawModel:u,rawPresets:I,rawExpressions:N,rawInvariants:T,rawRelations:_,rawDefaults:c,migrationFiles:j,rawComponents:A,rawAdminPages:C,dataSpec:E,phxDefinitions:M,evalExpressionParser:h,label:L,requireMigrationFiles:y}=g;if(0===Object.keys(u).length)return void x.at(L).error(t.MISSING_MODEL,s.MISSING_MODEL(L));u.latest||x.at(L).error(t.MISSING_LATEST,s.MISSING_LATEST(L));let G=new Map;for(let[e,t]of Object.entries(u)){let s=l(e,t,M,x.at(L,e));s&&G.set(s.versionKey,s)}if(x.hasErrors)return;let O=f(G,j,x,{requireMigrationFiles:y});if(!O)return;let D=O.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!D)return;let V=O.latestVersion,P=a(D,V),b=d(_,D,M,x),w=i({rawInvariants:T,rawExpressions:N,rawRelations:_,rawComponents:A},D,x),F=p(I,D,b,x),k=S(C,{latestModel:D,parsingContext:x.at(L,"$adminPages")},E);if(!k)return;let K=r(A,{allNames:D.allNames,resolvedShapes:D.resolvedShapes,parsingContext:x}),$=m(c,D,x.at(L,"defaults")),q=o({rawExpressions:N,inferredExpressions:[...b.expressions,...w.expressions,...K.expressions]},{latestModel:D,aliases:D.aliases,entityTypes:D.entityTypes,evalExpressionParser:h,parsingContext:x}),z=n({userComponents:K.components,generatedComponents:[...b.components,...k.components],invariantComponents:w.components},{aliases:D.aliases,parsingContext:x});if(void 0!==$&&void 0!==q&&void 0!==z)return e({latestModel:D,schemaVersion:V,resolvedVersions:O,components:z,configurationSchema:P,presets:F,expressions:q,invariants:w,defaults:$,states:v(((n,r,o)=>{if(0===r.length)return n;let i=1===n.navigationStates.length&&"Default"===n.navigationStates[0]?[]:n.navigationStates,a=i.filter(e=>r.includes(e));return a.length>0&&o.error(t.ADMIN_PAGES_NAV_STATE_CONFLICT,s.ADMIN_PAGES_NAV_STATE_CONFLICT(a)),e({...n,navigationStates:[...i,...r]})})(g.rawStates,k.navigationStates,x),x),adminPages:k})};

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

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{AppMetadata as s,BundleSizeBudgets as a,DataSpec as t,Infra as n}from"../sections/index.js";import{AdminSpec as r}from"./admin-spec/index.js";import{ConfiguratorSpec as o}from"./configurator-spec/index.js";export const ApplicationSpec=(i,l)=>{let{merged:m,migrationFiles:p,adminMigrationFiles:d,transformerFiles:c,phxDefinitions:u,evalExpressionParser:w}=i,f=s(m.appMetadata,l);if(!f)return;let S=t({mergedDataSpec:m.dataSpec,mergedChunks:m.chunks},l);if(!S||l.hasErrors)return;let g=l.startSpan("ConfiguratorSpec","ApplicationSpec"),h=o({rawModel:m.model,rawPresets:m.presets,rawExpressions:m.expressions,rawInvariants:m.invariants,rawRelations:m.relations,rawDefaults:m.defaults,dataSchemas:m.dataSchemas,dataSpec:S,appMetadata:f,rawTheme:m.theme,rawUi:m.ui,rawTransformers:m.transformers,rawAssistant:m.assistant,migrationFiles:p,transformerFiles:c,rawComponents:m.components,rawStates:m.configuratorStates,phxDefinitions:u,evalExpressionParser:w,label:"model"},l);if(g(),!h)return;let M=l.startSpan("AdminSpec","ApplicationSpec"),x=r({rawModel:m.adminModel,rawPresets:m.adminPresets,rawExpressions:m.adminExpressions,rawInvariants:m.adminInvariants,rawRelations:m.adminRelations,rawDefaults:m.adminDefaults,migrationFiles:d,rawComponents:m.adminComponents,rawAdminPages:m.adminPages,rawStates:m.adminStates,dataSpec:S,phxDefinitions:u,evalExpressionParser:w,label:"adminModel",requireMigrationFiles:!0},l);if(M(),!x)return;let v=n(m.infra,l);if(!v)return;let y=a(m.budgets);return l.count("entityTypes",h.latestModel.entityTypes.length),l.count("aliases",h.latestModel.aliases.size),l.count("commonTypes",h.latestModel.commonTypes.size),l.count("shapes",h.latestModel.shapes.size),l.count("components",h.components.length),l.count("modelVersions",h.resolvedVersions.versionedModels.length),l.count("presets",h.presets.presets.length),e({configurator:h,admin:x,appMetadata:f,infra:v,budgets:y,dataSpec:S})};
+import{Branded as e}from"@salsita-ai/common/utils";import{AppMetadata as s,BundleSizeBudgets as a,DataSpec as t,Infra as n}from"../sections/index.js";import{AdminSpec as r}from"./admin-spec/index.js";import{ConfiguratorSpec as o}from"./configurator-spec/index.js";export const ApplicationSpec=(i,l)=>{let{merged:m,migrationFiles:p,adminMigrationFiles:d,transformerFiles:c,phxDefinitions:u,evalExpressionParser:w}=i,f=s(m.appMetadata,l);if(!f)return;let S=t({mergedDataSpec:m.dataSpec,mergedChunks:m.chunks},l);if(!S||l.hasErrors)return;let g=l.startSpan("ConfiguratorSpec","ApplicationSpec"),h=o({rawModel:m.model,rawPresets:m.presets,rawExpressions:m.expressions,rawActions:m.actions,rawInvariants:m.invariants,rawRelations:m.relations,rawDefaults:m.defaults,dataSchemas:m.dataSchemas,dataSpec:S,appMetadata:f,rawTheme:m.theme,rawUi:m.ui,rawTransformers:m.transformers,rawAssistant:m.assistant,migrationFiles:p,transformerFiles:c,rawComponents:m.components,rawStates:m.configuratorStates,phxDefinitions:u,evalExpressionParser:w,label:"model"},l);if(g(),!h)return;let M=l.startSpan("AdminSpec","ApplicationSpec"),x=r({rawModel:m.adminModel,rawPresets:m.adminPresets,rawExpressions:m.adminExpressions,rawInvariants:m.adminInvariants,rawRelations:m.adminRelations,rawDefaults:m.adminDefaults,migrationFiles:d,rawComponents:m.adminComponents,rawAdminPages:m.adminPages,rawStates:m.adminStates,dataSpec:S,phxDefinitions:u,evalExpressionParser:w,label:"adminModel",requireMigrationFiles:!0},l);if(M(),!x)return;let A=n(m.infra,l);if(!A)return;let v=a(m.budgets);return l.count("entityTypes",h.latestModel.entityTypes.length),l.count("aliases",h.latestModel.aliases.size),l.count("commonTypes",h.latestModel.commonTypes.size),l.count("shapes",h.latestModel.shapes.size),l.count("components",h.components.length),l.count("modelVersions",h.resolvedVersions.versionedModels.length),l.count("presets",h.presets.presets.length),e({configurator:h,admin:x,appMetadata:f,infra:A,budgets:v,dataSpec:S})};

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

@@ -1,12 +1,12 @@
 import { Branded } from '@salsita-ai/common/utils';
 import { type EvalExpressionParser, type ParseContext, type PhoenixDefinitions } from '../../../../core/index.js';
 import type { CategorizedFile } from '../../../categorize/index.js';
-import type { MergedAssistant, MergedComponents, MergedConfiguratorStates, MergedDataSchemas, MergedDefaults, MergedExpressions, MergedInvariants, MergedModel, MergedPresets, MergedRelations, MergedTheme, MergedTransformers, MergedUi } from '../../../merge/index.js';
+import type { MergedActions, MergedAssistant, MergedComponents, MergedConfiguratorStates, MergedDataSchemas, MergedDefaults, MergedExpressions, MergedInvariants, MergedModel, MergedPresets, MergedRelations, MergedTheme, MergedTransformers, MergedUi } from '../../../merge/index.js';
 import { Components } from '../../components/index.js';
 import { Expressions } from '../../expressions/index.js';
 import { Invariants } from '../../invariants/index.js';
 import { ConfigurationSchema, DataSchemas, Defaults, ModelVersion, Presets } from '../../model/index.js';
-import { type AppMetadata, AssistantServerSettings, AssistantSpec, type DataSpec, Theme, Transformers, Ui } from '../../sections/index.js';
+import { Actions, type AppMetadata, AssistantServerSettings, AssistantSpec, type DataSpec, Theme, Transformers, Ui } from '../../sections/index.js';
 import { ResolvedVersions } from '../resolved-versions.js';
 import { ConfiguratorStates } from './states.js';
 export type ConfiguratorSpec = Branded<'ConfiguratorSpec', {
@@ -17,6 +17,7 @@ export type ConfiguratorSpec = Branded<'ConfiguratorSpec', {
     readonly configurationSchema: ConfigurationSchema;
     readonly presets: Presets;
     readonly expressions: Expressions;
+    readonly actions: Actions;
     readonly invariants: Invariants;
     readonly dataSchemas: DataSchemas;
     readonly defaults: Defaults;
@@ -31,6 +32,7 @@ interface ConfiguratorSpecProps {
     readonly rawModel: MergedModel;
     readonly rawPresets: MergedPresets;
     readonly rawExpressions: MergedExpressions;
+    readonly rawActions: MergedActions;
     readonly rawInvariants: MergedInvariants;
     readonly rawRelations: MergedRelations;
     readonly rawDefaults: MergedDefaults;

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

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as s,diagnosticMessages as t}from"../../../../errors/index.js";import{Components as r,UserComponents as o}from"../../components/index.js";import{Expressions as i}from"../../expressions/index.js";import{Invariants as n}from"../../invariants/index.js";import{ConfigurationSchema as a,DataSchemas as m,Defaults as p,ModelVersion as l,Presets as d}from"../../model/index.js";import{Relations as f}from"../../relations/index.js";import{AssistantServerSettings as x,AssistantSpec as S,Theme as v,Transformers as c,Ui as j}from"../../sections/index.js";import{ResolvedVersions as u}from"../resolved-versions.js";import{ConfiguratorStates as g}from"./states.js";export const ConfiguratorSpec=(C,I)=>{let{rawModel:M,rawPresets:h,rawExpressions:y,rawInvariants:E,rawRelations:N,rawDefaults:T,dataSchemas:L,dataSpec:G,appMetadata:O,rawTheme:_,rawUi:b,rawTransformers:w,rawAssistant:A,migrationFiles:D,transformerFiles:V,rawComponents:k,phxDefinitions:K,evalExpressionParser:q,label:z}=C;if(0===Object.keys(M).length)return void I.at(z).error(s.MISSING_MODEL,t.MISSING_MODEL(z));M.latest||I.at(z).error(s.MISSING_LATEST,t.MISSING_LATEST(z));let B=new Map;for(let[e,s]of Object.entries(M)){let t=l(e,s,K,I.at(z,e));t&&B.set(t.versionKey,t)}if(I.hasErrors)return;let F=u(B,D,I);if(!F)return;let H=F.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!H)return;let J=F.latestVersion,P=a(H,J),Q=f(N,H,I),R=n({rawInvariants:E,rawExpressions:y,rawRelations:N,rawComponents:k},H,I),U=d(h,H,Q,I),W=o(k,{allNames:H.allNames,resolvedShapes:H.resolvedShapes,parsingContext:I}),X=p(T,H,I.at(z,"defaults")),Y=c(w,V,I),Z=i({rawExpressions:y,inferredExpressions:[...Q.expressions,...R.expressions,...W.expressions]},{latestModel:H,aliases:H.aliases,entityTypes:H.entityTypes,evalExpressionParser:q,parsingContext:I}),$=r({userComponents:W.components,generatedComponents:Q.components,invariantComponents:R.components},{aliases:H.aliases,parsingContext:I}),ee=m({merged:L,dataSpec:G,appMetadata:O,phxDefinitions:K,parsingContext:I}),es=g(C.rawStates,I.at("states"));if(void 0!==X&&void 0!==Z&&void 0!==$&&void 0!==ee)return e({latestModel:H,schemaVersion:J,dataSchemas:ee,resolvedVersions:F,components:$,configurationSchema:P,presets:U,expressions:Z,invariants:R,defaults:X,states:es,theme:v(_),ui:j(b),transformers:Y,assistant:S(A,{model:H,states:es,phxDefinitions:K,expressions:Z,components:$},I),assistantServerSettings:x(A)})};
+import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as s,diagnosticMessages as t}from"../../../../errors/index.js";import{Components as o,UserComponents as r}from"../../components/index.js";import{Expressions as i}from"../../expressions/index.js";import{Invariants as n}from"../../invariants/index.js";import{ConfigurationSchema as a,DataSchemas as m,Defaults as p,ModelVersion as l,Presets as d}from"../../model/index.js";import{Relations as f}from"../../relations/index.js";import{Actions as x,AssistantServerSettings as S,AssistantSpec as v,Theme as c,Transformers as j,Ui as u}from"../../sections/index.js";import{ResolvedVersions as g}from"../resolved-versions.js";import{ConfiguratorStates as C}from"./states.js";export const ConfiguratorSpec=(I,M)=>{let{rawModel:h,rawPresets:y,rawExpressions:E,rawActions:N,rawInvariants:T,rawRelations:L,rawDefaults:G,dataSchemas:O,dataSpec:_,appMetadata:b,rawTheme:w,rawUi:A,rawTransformers:D,rawAssistant:V,migrationFiles:k,transformerFiles:K,rawComponents:q,phxDefinitions:z,evalExpressionParser:B,label:F}=I;if(0===Object.keys(h).length)return void M.at(F).error(s.MISSING_MODEL,t.MISSING_MODEL(F));h.latest||M.at(F).error(s.MISSING_LATEST,t.MISSING_LATEST(F));let H=new Map;for(let[e,s]of Object.entries(h)){let t=l(e,s,z,M.at(F,e));t&&H.set(t.versionKey,t)}if(M.hasErrors)return;let J=g(H,k,M);if(!J)return;let P=J.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!P)return;let Q=J.latestVersion,R=a(P,Q),U=f(L,P,z,M),W=n({rawInvariants:T,rawExpressions:E,rawRelations:L,rawComponents:q},P,M),X=d(y,P,U,M),Y=r(q,{allNames:P.allNames,resolvedShapes:P.resolvedShapes,parsingContext:M}),Z=p(G,P,M.at(F,"defaults")),$=j(D,K,M),ee=i({rawExpressions:E,inferredExpressions:[...U.expressions,...W.expressions,...Y.expressions]},{latestModel:P,aliases:P.aliases,entityTypes:P.entityTypes,evalExpressionParser:B,parsingContext:M}),es=o({userComponents:Y.components,generatedComponents:U.components,invariantComponents:W.components},{aliases:P.aliases,parsingContext:M}),et=m({merged:O,dataSpec:_,appMetadata:b,phxDefinitions:z,parsingContext:M}),eo=C(I.rawStates,M.at("states")),er=x(N,{latestModel:P,phxDefinitions:z},M.at("actions"));if(void 0!==Z&&void 0!==ee&&void 0!==er&&void 0!==es&&void 0!==et)return e({latestModel:P,schemaVersion:Q,dataSchemas:et,resolvedVersions:J,components:es,configurationSchema:R,presets:X,expressions:ee,actions:er,invariants:W,defaults:Z,states:eo,theme:c(w),ui:u(A),transformers:$,assistant:v(V,{model:P,states:eo,phxDefinitions:z,expressions:ee,components:es,actions:er},M),assistantServerSettings:S(V)})};

package/dist/application-spec/parse-application-files/spec/common/index.d.ts

@@ -1 +1,2 @@
+export * from './schema-ref-resolver.js';
 export * from './validate-schema-refs.js';

package/dist/application-spec/parse-application-files/spec/common/index.js

@@ -1 +1 @@
-export*from"./validate-schema-refs.js";
+export*from"./schema-ref-resolver.js";export*from"./validate-schema-refs.js";

package/dist/application-spec/parse-application-files/spec/common/schema-ref-resolver.d.ts

@@ -0,0 +1,23 @@
+import { type EnhancedJsonSchemaType, type PhoenixDefinitions } from '../../../core/index.js';
+/**
+ * Resolves a `$ref` to the schema it names, through phoenix definitions and common types.
+ * `undefined` for a ref that names nothing known.
+ */
+export type SchemaRefResolver = ($ref: string) => EnhancedJsonSchemaType | undefined;
+/** The name of the common type a `common:` or internal `#/model/{version}/commonTypes/{name}` ref names. */
+export declare const commonTypeRefName: ($ref: string) => string | undefined;
+/** The phoenix definition a ref names: full URL, `phx:`, or `#/definitions/` as used inside the definitions. */
+export declare const phxDefinitionRefName: ($ref: string) => string | undefined;
+/**
+ * Resolves refs to phoenix definitions (full URL, `phx:`, or `#/definitions/` as used inside the
+ * definitions themselves) and to common types (`common:` or internal path).
+ */
+export declare const createSchemaRefResolver: (commonTypes: ReadonlyMap<string, {
+    readonly schema: EnhancedJsonSchemaType;
+}>, phxDefinitions: PhoenixDefinitions) => SchemaRefResolver;
+/**
+ * Whether a value of the schema can be `null`: a `null` type, enum value or const, a nullable
+ * `anyOf`/`oneOf` member, or a ref to a nullable schema. A ref that cannot be resolved counts as
+ * nullable, since nothing proves otherwise; a ref cycle does not.
+ */
+export declare const isNullableSchema: (schema: EnhancedJsonSchemaType, resolveRef: SchemaRefResolver, visitedRefs?: ReadonlySet<string>) => boolean;

package/dist/application-spec/parse-application-files/spec/common/schema-ref-resolver.js

@@ -0,0 +1 @@
+import{isArray as e}from"@salsita-ai/common/utils";import{COMMON_SHORT_PREFIX as t,DEFINITION_REF_PATTERN as n,INTERNAL_REF_PATTERN as o,extractPhxDefName as l}from"../../../core/index.js";export const commonTypeRefName=e=>e.startsWith(t)?e.slice(t.length):o.exec(e)?.[2];export const phxDefinitionRefName=e=>l(e)??n.exec(e)?.[1];export const createSchemaRefResolver=(e,t)=>n=>{let o=phxDefinitionRefName(n);if(void 0!==o)return t[o]?.schema;let l=commonTypeRefName(n);return void 0===l?void 0:e.get(l)?.schema};export const isNullableSchema=(t,n,o=new Set)=>{if(t.$ref){if(o.has(t.$ref))return!1;let e=n(t.$ref);return void 0===e||isNullableSchema(e,n,new Set([...o,t.$ref]))}let l=[...t.anyOf??[],...t.oneOf??[]];return"null"===t.type||e(t.type)&&t.type.includes("null")||t.enum?.includes(null)===!0||null===t.const||l.some(e=>isNullableSchema(e,n,o))};

package/dist/application-spec/parse-application-files/spec/components/component-entry.d.ts

@@ -1,4 +1,5 @@
 import type { Branded } from '@salsita-ai/common/utils';
+import type { SdkCodeRef } from '../../../core/index.js';
 import type { MemoEvalPlan, MemoEvalPlanInput } from '../expressions/memo-eval-plan.js';
 import type { EntityOrAliasName, InstanceName } from '../model/index.js';
 import type { ComponentReadBinding, ComponentWriteBinding } from './bindings/index.js';
@@ -46,15 +47,6 @@ interface UserBoundImplementation {
     readonly plan: MemoEvalPlan;
     readonly implementation: RootReadImplementation | CompositeImplementation;
 }
-/**
- * A parameter that should be emitted as an unquoted code reference in codegen
- * (e.g. an entity reflection variable like `Top`).
- * At runtime, the string value is resolved to the actual object (e.g. entity reflection).
- */
-export interface SdkCodeRef {
-    readonly $codeRef: string;
-}
-export declare const isSdkCodeRef: (value: unknown) => value is SdkCodeRef;
 export type SdkFactoryParam = SdkCodeRef | string | number | boolean | null | readonly SdkFactoryParam[] | {
     readonly [key: string]: SdkFactoryParam;
 };

package/dist/application-spec/parse-application-files/spec/components/component-entry.js

@@ -1 +1 @@
-export const isSdkCodeRef=e=>"object"==typeof e&&null!==e&&"$codeRef"in e&&"string"==typeof e.$codeRef;
+export{};

package/dist/application-spec/parse-application-files/spec/components/component-filter.d.ts

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

package/dist/application-spec/parse-application-files/spec/components/component-filter.js

@@ -1 +1 @@
-import{Branded as t}from"@salsita-ai/common/utils";import{FILTER_OR_KEY as e,READ_MARKER_KEY as r,isEnhancedJsonObject as i,isEvalMarker as s,isRawReadMarker as a}from"../../../core/index.js";export const FILTER_CRITERION_KEYS=["navigationStates","viewStates","toolStates","exportStates","modes","roles","selectedEntityIds","hoveredEntityIds","draggedEntityIds","exportedEntityIds","active","fullscreen","debug","viewports"];let o={tsType:"IdOrWithId | readonly IdOrWithId[]",import:[{module:"@salsita-ai/sdk/domain",member:"IdOrWithId"}]};export const FILTER_CRITERION_SCHEMAS={navigationStates:{type:"array",items:{type:"string"}},viewStates:{type:"array",items:{type:"string"}},toolStates:{type:"array",items:{type:"string"}},exportStates:{type:"array",items:{type:"string"}},modes:{type:"array",items:{type:"string"}},roles:{type:"array",items:{type:"string"}},selectedEntityIds:o,hoveredEntityIds:o,draggedEntityIds:o,exportedEntityIds:o,active:{type:"boolean"},fullscreen:{type:"boolean"},debug:{type:"boolean"},viewports:{type:"array",items:{type:"string"},tsType:"readonly Viewport[]",import:[{module:"@salsita-ai/sdk/domain",member:"Viewport"}]}};let n=new Set(FILTER_CRITERION_KEYS),d=t=>a(t)?{kind:"dynamic",target:t[r]}:s(t)?{kind:"eval",code:t.$eval}:{kind:"static",value:t},y=t=>{let e=t[r];if("string"==typeof e&&!Object.keys(t).some(t=>n.has(t)))return{kind:"root",target:e};let i={};for(let[e,r]of Object.entries(t))n.has(e)&&void 0!==r&&(i[e]=d(r));return{kind:"gradual",...i}};export const ComponentFilters=r=>{if(void 0===r||!i(r))return t({items:[]});let s=r[e];return Array.isArray(s)?t({items:s.filter(i).map(y)}):t({items:[y(r)]})};
+import{Branded as t}from"@salsita-ai/common/utils";import{FILTER_CRITERION_KEYS as e,FILTER_OR_KEY as r,READ_MARKER_KEY as i,isEnhancedJsonObject as s,isEvalMarker as a,isRawReadMarker as o}from"../../../core/index.js";let n={tsType:"IdOrWithId | readonly IdOrWithId[]",import:[{module:"@salsita-ai/sdk/domain",member:"IdOrWithId"}]};export const FILTER_CRITERION_SCHEMAS={navigationStates:{type:"array",items:{type:"string"}},viewStates:{type:"array",items:{type:"string"}},toolStates:{type:"array",items:{type:"string"}},exportStates:{type:"array",items:{type:"string"}},modes:{type:"array",items:{type:"string"}},roles:{type:"array",items:{type:"string"}},selectedEntityIds:n,hoveredEntityIds:n,draggedEntityIds:n,exportedEntityIds:n,active:{type:"boolean"},fullscreen:{type:"boolean"},debug:{type:"boolean"},viewports:{type:"array",items:{type:"string"},tsType:"readonly Viewport[]",import:[{module:"@salsita-ai/sdk/domain",member:"Viewport"}]}};let y=new Set(e),d=t=>o(t)?{kind:"dynamic",target:t[i]}:a(t)?{kind:"eval",code:t.$eval}:{kind:"static",value:t},p=t=>{let e=t[i];if("string"==typeof e&&!Object.keys(t).some(t=>y.has(t)))return{kind:"root",target:e};let r={};for(let[e,i]of Object.entries(t))y.has(e)&&void 0!==i&&(r[e]=d(i));return{kind:"gradual",...r}};export const ComponentFilters=e=>{if(void 0===e||!s(e))return t({items:[]});let i=e[r];return Array.isArray(i)?t({items:i.filter(s).map(p)}):t({items:[p(e)]})};

package/dist/application-spec/parse-application-files/spec/components/index.d.ts

@@ -1,5 +1,5 @@
 export * from './bindings/index.js';
-export * from './component-entry.js';
+export type * from './component-entry.js';
 export * from './component-filter.js';
 export * from './component-prop-target.js';
 export * from './components.js';

package/dist/application-spec/parse-application-files/spec/components/index.js

@@ -1 +1 @@
-export*from"./bindings/index.js";export*from"./component-entry.js";export*from"./component-filter.js";export*from"./component-prop-target.js";export*from"./components.js";export*from"./sdk-component-entry.js";export*from"./user-component-entry.js";export*from"./user-components.js";
+export*from"./bindings/index.js";export*from"./component-filter.js";export*from"./component-prop-target.js";export*from"./components.js";export*from"./sdk-component-entry.js";export*from"./user-component-entry.js";export*from"./user-components.js";

package/dist/application-spec/parse-application-files/spec/expressions/memo-eval-plan.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{evalCodeUsesSelf as r}from"../../../core/eval-code-uses-self.js";import{isEvalMarker as t,isMsgMarker as n}from"../../../core/index.js";import{isComponentPropTarget as o}from"../components/component-prop-target.js";let l=(e,r)=>0===r.length?e:`${e}.${r.join(".")}`,i=(r,a,u,d)=>{if(void 0===r)throw Error(`MemoEvalPlan: found undefined at ${l(u,d)}, undefined cannot be generated, remove the property or use null.`);if(t(r)){let t=((r,t,n)=>{let o=t.trim();for(let e=0;e<r.length;e++){let t=r[e];if("eval"===t.kind&&t.code===o)return e}return r.push(e({kind:"eval",code:o,label:n})),r.length-1})(a,r.$eval,u);return e({kind:"slot",depIndex:t})}if(o(r)){let t=((r,t)=>{for(let e=0;e<r.length;e++){let n=r[e];if("read"===n.kind&&n.target===t)return e}return r.push(e({kind:"read",target:t})),r.length-1})(a,r.$target);return e({kind:"slot",depIndex:t})}if(n(r))return e({kind:"msg",marker:r});if(null===r||"object"!=typeof r)return e({kind:"literal",value:r});if(Array.isArray(r))return e({kind:"array",items:r.map((e,r)=>i(e,a,u,[...d,String(r)]))});if("object"!=typeof r||null===r)throw Error(`MemoEvalPlan: found unsupported value at ${l(u,d)}, remove it or use null.`);let f=[];for(let e in r){let t=r[e];f.push([e,i(t,a,u,[...d,e])])}return e({kind:"object",entries:f})};export const MemoEvalPlan=(t,n)=>{let o=[],l=i(t,o,n,[]),a=o.some(e=>"read"===e.kind||r(e.code));return e({deps:o,template:l,usesSelf:a})};
+import{Branded as e}from"@salsita-ai/common/utils";import{isEvalMarker as r,isMsgMarker as t}from"../../../core/index.js";import{evalCodeUsesSelf as n}from"../../../enhanced-json/eval-code-uses-self.js";import{isComponentPropTarget as o}from"../components/component-prop-target.js";let l=(e,r)=>0===r.length?e:`${e}.${r.join(".")}`,i=(n,a,d,u)=>{if(void 0===n)throw Error(`MemoEvalPlan: found undefined at ${l(d,u)}, undefined cannot be generated, remove the property or use null.`);if(r(n)){let r=((r,t,n)=>{let o=t.trim();for(let e=0;e<r.length;e++){let t=r[e];if("eval"===t.kind&&t.code===o)return e}return r.push(e({kind:"eval",code:o,label:n})),r.length-1})(a,n.$eval,d);return e({kind:"slot",depIndex:r})}if(o(n)){let r=((r,t)=>{for(let e=0;e<r.length;e++){let n=r[e];if("read"===n.kind&&n.target===t)return e}return r.push(e({kind:"read",target:t})),r.length-1})(a,n.$target);return e({kind:"slot",depIndex:r})}if(t(n))return e({kind:"msg",marker:n});if(null===n||"object"!=typeof n)return e({kind:"literal",value:n});if(Array.isArray(n))return e({kind:"array",items:n.map((e,r)=>i(e,a,d,[...u,String(r)]))});if("object"!=typeof n||null===n)throw Error(`MemoEvalPlan: found unsupported value at ${l(d,u)}, remove it or use null.`);let s=[];for(let e in n){let r=n[e];s.push([e,i(r,a,d,[...u,e])])}return e({kind:"object",entries:s})};export const MemoEvalPlan=(r,t)=>{let o=[],l=i(r,o,t,[]),a=o.some(e=>"read"===e.kind||n(e.code));return e({deps:o,template:l,usesSelf:a})};

package/dist/application-spec/parse-application-files/spec/expressions/user-expressions.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{schemaFromValue as t}from"../../../core/index.js";import{DiagnosticCode as r,diagnosticMessages as s}from"../../../errors/index.js";import{ExpressionName as o}from"../model/index.js";import{MemoEvalPlan as a}from"./memo-eval-plan.js";let i=(e,r,s,o)=>{if("user"===e.kind)return{schema:e.schema,implementation:{kind:"user"}};let i=a(e.value,r),m={kind:"value",constant:e.constant,value:e.value,plan:i};if(Object.keys(e.schema).length>0)return{schema:e.schema,implementation:m};let n=t(e.value,s,o);if(void 0!==n)return{schema:n,implementation:m}};export const UserExpressions=(t,a)=>{let{latestModel:m,evalExpressionParser:n,parsingContext:l}=a,{allNames:c}=m,f=[...c].map(String),h=[];for(let[a,m]of Object.entries(t)){c.has(a)||l.error(r.EXPRESSION_UNKNOWN_ENTITY_KEY,s.EXPRESSION_UNKNOWN_ENTITY_KEY(a,f));let t=e(a);for(let[r,s]of Object.entries(m)){let m=l.at(a),c=o(r,m);if(!c)continue;let f=i(s,`${a}.${r}`,m.at(r),n);f&&h.push(e({entityKey:t,name:c,schema:f.schema,declaredSchema:f.schema,implementation:f.implementation}))}}if(!l.hasErrors)return h};
+import{Branded as e}from"@salsita-ai/common/utils";import{schemaFromValue as t}from"../../../enhanced-json/index.js";import{DiagnosticCode as r,diagnosticMessages as n}from"../../../errors/index.js";import{ExpressionName as s}from"../model/index.js";import{MemoEvalPlan as a}from"./memo-eval-plan.js";let o=(e,r,n,s)=>{if("user"===e.kind)return{schema:e.schema,implementation:{kind:"user"}};let o=a(e.value,r),i={kind:"value",constant:e.constant,value:e.value,plan:o};if(Object.keys(e.schema).length>0)return{schema:e.schema,implementation:i};let m=t(e.value,n,s);if(void 0!==m)return{schema:m,implementation:i}};export const UserExpressions=(t,a)=>{let{latestModel:i,evalExpressionParser:m,parsingContext:l}=a,{allNames:c}=i,h=[...c].map(String),f=[];for(let[a,i]of Object.entries(t)){c.has(a)||l.error(r.EXPRESSION_UNKNOWN_ENTITY_KEY,n.EXPRESSION_UNKNOWN_ENTITY_KEY(a,h));let t=e(a);for(let[r,n]of Object.entries(i)){let i=l.at(a),c=s(r,i);if(!c)continue;let h=o(n,`${a}.${r}`,i.at(r),m);h&&f.push(e({entityKey:t,name:c,schema:h.schema,declaredSchema:h.schema,implementation:h.implementation}))}}if(!l.hasErrors)return f};

package/dist/application-spec/parse-application-files/spec/model/defaults.d.ts

@@ -7,8 +7,8 @@ import { ShapePropertyName } from './names/shape-property-name.js';
 /**
  * A map of shape property names to their default values inside a single entity block.
  * Raw YAML values — markers intact — keyed by a validated {@link ShapePropertyName}.
- * Codegen emits these as-is via `stringifyEnhancedJsonValue`; runtime consumers
- * (`RecipeFactoryBuilder`) consume the generated `createRecipe` factory.
+ * Codegen emits these as-is via `stringifyEnhancedJsonValue`; at run time
+ * `createRecipeFactory` makes the generated `createRecipe` factory from them.
  */
 export type DefaultEntries = Readonly<Record<ShapePropertyName, EnhancedJsonValue>>;
 /**
@@ -19,6 +19,11 @@ export type DefaultEntries = Readonly<Record<ShapePropertyName, EnhancedJsonValu
  * flattened here to concrete entity entries so downstream codegen only serialises
  * a runtime-ready per-entity map.
  *
+ * A source key may state part of a shape, but the flattened entry of a concrete
+ * entity type states every property of its shape: `createRecipeFactory` validates
+ * each entry as a whole entity when the generated module loads. An entity type
+ * with no entry has no defaults and is not checked.
+ *
  * Values are raw `EnhancedJsonValue` so codegen can emit them via
  * `stringifyEnhancedJsonValue` with `$msg` markers preserved.
  *

package/dist/application-spec/parse-application-files/spec/model/defaults.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{CONSTANT_CAPS as t,resolveEnhancedJsonValue as r}from"../../../core/index.js";import{DiagnosticCode as o,diagnosticMessages as i}from"../../../errors/index.js";import{ShapePropertyName as n}from"./names/shape-property-name.js";let s=(e,t,r,n,s)=>{for(let l of r.validatePartialShape(t).errors){let t=l.instancePath?l.instancePath:"(root)",r=l.instancePath.split("/").filter(Boolean)[0]??"";n.error(o.DEFAULTS_SCHEMA_VIOLATION,i[o.DEFAULTS_SCHEMA_VIOLATION](e,r,t,l.message,s))}};export const Defaults=(l,a,f)=>{let E=a.allNames,T=[...E].map(String),N=new Map,S=new Map;for(let e of a.entitySchemas)N.set(e.entityType,new Set(Object.keys(e.shapeProperties))),S.set(e.entityType,e);let _={};for(let[e,O]of Object.entries(l)){let l=f.at(e);if(!E.has(e)){f.error(o.DEFAULTS_UNKNOWN_ENTITY_KEY,i[o.DEFAULTS_UNKNOWN_ENTITY_KEY](e,T));continue}let p=a.aliases.get(e),c=void 0!==p,g={};for(let[t,r]of Object.entries(O)){let s=n(t,l);if(s){if(c){let t=[];for(let e of p){let r=N.get(e);r&&r.has(s)||t.push(String(e))}if(t.length>0){let r=p[0],n=r?[...N.get(r)??[]]:[];f.error(o.DEFAULTS_UNKNOWN_PROPERTY,i[o.DEFAULTS_UNKNOWN_PROPERTY](e,s,n,t));continue}}else{let t=N.get(e);if(!t||!t.has(s)){let r=t?[...t]:[];f.error(o.DEFAULTS_UNKNOWN_PROPERTY,i[o.DEFAULTS_UNKNOWN_PROPERTY](e,s,r));continue}}g[s]=r}}if(0===Object.keys(g).length)continue;let m=r(g,void 0,t,l);if(void 0!==m){if(c)for(let t of p){let r=S.get(t);r&&s(e,m,r,l,String(t))}else{let t=S.get(e);t&&s(e,m,t,l)}for(let t of p??[e])_[String(t)]={..._[String(t)],...g}}}if(Object.keys(l).length>0&&f.warning(o.DEFAULTS_DEPRECATED,i[o.DEFAULTS_DEPRECATED]()),!f.hasErrors)return e({entries:_})};
+import{Branded as e}from"@salsita-ai/common/utils";import{CONSTANT_CAPS as t}from"../../../core/index.js";import{resolveEnhancedJsonValue as r}from"../../../enhanced-json/index.js";import{DiagnosticCode as i,diagnosticMessages as n}from"../../../errors/index.js";import{ShapePropertyName as o}from"./names/shape-property-name.js";let s=(e,t,r,o,s)=>{for(let l of r.validatePartialShape(t).errors){let t=l.instancePath?l.instancePath:"(root)",r=l.instancePath.split("/").filter(Boolean)[0]??"";o.error(i.DEFAULTS_SCHEMA_VIOLATION,n[i.DEFAULTS_SCHEMA_VIOLATION](e,r,t,l.message,s))}};export const Defaults=(l,a,f)=>{let E=a.allNames,T=[...E].map(String),S=new Map,N=new Map;for(let e of a.entitySchemas)S.set(e.entityType,new Set(Object.keys(e.shapeProperties))),N.set(e.entityType,e);let g={},O=new Map;for(let[e,_]of Object.entries(l)){let l=f.at(e);if(!E.has(e)){f.error(i.DEFAULTS_UNKNOWN_ENTITY_KEY,n[i.DEFAULTS_UNKNOWN_ENTITY_KEY](e,T));continue}let c=a.aliases.get(e),p=void 0!==c,h={};for(let[t,r]of Object.entries(_)){let s=o(t,l);if(s){if(p){let t=[];for(let e of c){let r=S.get(e);r&&r.has(s)||t.push(String(e))}if(t.length>0){let r=c[0],o=r?[...S.get(r)??[]]:[];f.error(i.DEFAULTS_UNKNOWN_PROPERTY,n[i.DEFAULTS_UNKNOWN_PROPERTY](e,s,o,t));continue}}else{let t=S.get(e);if(!t||!t.has(s)){let r=t?[...t]:[];f.error(i.DEFAULTS_UNKNOWN_PROPERTY,n[i.DEFAULTS_UNKNOWN_PROPERTY](e,s,r));continue}}h[s]=r}}if(0===Object.keys(h).length)continue;let m=r(h,void 0,t,l);if(void 0!==m){if(p)for(let t of c){let r=N.get(t);r&&s(e,m,r,l,String(t))}else{let t=N.get(e);t&&s(e,m,t,l)}for(let t of c??[e])g[String(t)]={...g[String(t)],...h},O.set(t,[...O.get(t)??[],e])}}for(let[e,t]of O){let r=g[String(e)]??{},o=(N.get(e)?.shapeSchema.required??[]).filter(e=>!Object.hasOwn(r,e));if(0===o.length)continue;let s=t.includes(String(e))?String(e):t.at(-1);f.at(s).error(i.DEFAULTS_INCOMPLETE,n[i.DEFAULTS_INCOMPLETE](String(e),o,t))}if(Object.keys(l).length>0&&f.warning(i.DEFAULTS_DEPRECATED,n[i.DEFAULTS_DEPRECATED]()),!f.hasErrors)return e({entries:g})};

package/dist/application-spec/parse-application-files/spec/model/names/action-name.d.ts

@@ -0,0 +1,10 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ParseContext } from '../../../../core/index.js';
+/**
+ * Branded action name: camelCase without a prefix (e.g. "movePartBy", "swapCabinets"). An action is
+ * a named domain operation, so its name doubles as the key of its implementation and of its
+ * generated types.
+ */
+export type ActionName = Branded<'ActionName', string>;
+/** Validates that a name follows the action naming convention (camelCase, no prefix). */
+export declare const ActionName: (name: string, ctx: ParseContext) => ActionName | undefined;

package/dist/application-spec/parse-application-files/spec/model/names/action-name.js

@@ -0,0 +1 @@
+import{Branded as o}from"@salsita-ai/common/utils";import{DiagnosticCode as r,diagnosticMessages as t}from"../../../../errors/index.js";let i=/^[a-z][A-Za-z0-9]*$/;export const ActionName=(A,e)=>i.test(A)?o(A):void e.error(r.INVALID_ACTION_NAME,t.INVALID_ACTION_NAME(A));

package/dist/application-spec/parse-application-files/spec/model/names/index.d.ts

@@ -1,3 +1,4 @@
+export * from './action-name.js';
 export * from './alias-name.js';
 export * from './entity-or-alias-name.js';
 export * from './entity-type-name.js';

package/dist/application-spec/parse-application-files/spec/model/names/index.js

@@ -1 +1 @@
-export*from"./alias-name.js";export*from"./entity-or-alias-name.js";export*from"./entity-type-name.js";export*from"./expression-name.js";export*from"./instance-name.js";export*from"./invariant-name.js";export*from"./relation-name.js";export*from"./shape-property-name.js";export*from"./violation-type-name.js";
+export*from"./action-name.js";export*from"./alias-name.js";export*from"./entity-or-alias-name.js";export*from"./entity-type-name.js";export*from"./expression-name.js";export*from"./instance-name.js";export*from"./invariant-name.js";export*from"./relation-name.js";export*from"./shape-property-name.js";export*from"./violation-type-name.js";

package/dist/application-spec/parse-application-files/spec/relations/reference-field-type.d.ts

@@ -0,0 +1,25 @@
+import { type EnhancedJsonSchemaType, type PhoenixDefinitions } from '../../../core/index.js';
+import type { ModelVersion } from '../model/index.js';
+/**
+ * What the type of a shape field means to a relation that reads its related entities from it.
+ *
+ * - `single`: the id of one entity of `entityTypes`, or `null` when `nullable`.
+ * - `array`: an array of ids of entities of `entityTypes`.
+ * - `other`: anything else, such as a string, an id without `references`, or a mix of the above.
+ * - `unknown`: the schema does not say, because it states its type as TypeScript text (`tsType`)
+ *   or combines schemas with `allOf`.
+ */
+export type ReferenceFieldType = {
+    readonly kind: 'single';
+    readonly entityTypes: ReadonlySet<string>;
+    readonly nullable: boolean;
+} | {
+    readonly kind: 'array';
+    readonly entityTypes: ReadonlySet<string>;
+} | {
+    readonly kind: 'other';
+} | {
+    readonly kind: 'unknown';
+};
+/** Classifies the schema of a shape field of the latest model by the reference it holds. */
+export declare const referenceFieldType: (schema: EnhancedJsonSchemaType, latestModel: ModelVersion, phxDefinitions: PhoenixDefinitions) => ReferenceFieldType;

package/dist/application-spec/parse-application-files/spec/relations/reference-field-type.js

@@ -0,0 +1 @@
+import{COMMON_SHORT_PREFIX as e,INTERNAL_REF_PATTERN as t,extractPhxDefName as n}from"../../../core/index.js";let r={entityTypes:new Set,hasNull:!1,arrays:[],hasOther:!1,hasUnknown:!1},s={...r,hasNull:!0},a={...r,hasOther:!0},y={...r,hasUnknown:!0},i=e=>({entityTypes:new Set(e.flatMap(e=>[...e.entityTypes])),hasNull:e.some(e=>e.hasNull),arrays:e.flatMap(e=>e.arrays),hasOther:e.some(e=>e.hasOther),hasUnknown:e.some(e=>e.hasUnknown)}),l=(o,p)=>{if(o.tsType)return y;if(o.$ref){let s,i=n(o.$ref);if(void 0!==i)return p.phxDefinitions[i]?.tsType==="DomainEntityId"&&o.references?{...r,entityTypes:new Set(((e,t)=>{for(let[n,r]of t.aliases)if(String(n)===e)return r.map(String);return[e]})(o.references,p.latestModel))}:a;let h=(s=o.$ref).startsWith(e)?s.slice(e.length):t.exec(s)?.[2];if(void 0===h)return a;let u=p.latestModel.commonTypes.get(h);return!u||p.openCommonTypes.has(h)?y:l(u.schema,{...p,openCommonTypes:new Set([...p.openCommonTypes,h])})}if(o.enum)return i(o.enum.map(e=>null===e?s:a));let h=o.anyOf??o.oneOf;if(h)return i(h.map(e=>l(e,p)));if(o.allOf)return y;let u=e=>"array"===e?(()=>{let{items:e}=o;return!e||Array.isArray(e)?a:{...r,arrays:[l(e,p)]}})():"null"===e?s:a;return"string"==typeof o.type?u(o.type):Array.isArray(o.type)?i(o.type.map(u)):a};export const referenceFieldType=(e,t,n)=>(e=>{if(e.hasUnknown||e.arrays.some(e=>e.hasUnknown))return{kind:"unknown"};if(e.hasOther)return{kind:"other"};let[t,...n]=e.arrays;if(!t)return e.entityTypes.size>0?{kind:"single",entityTypes:e.entityTypes,nullable:e.hasNull}:{kind:"other"};let r=e=>e.entityTypes.size>0&&!e.hasNull&&!e.hasOther&&0===e.arrays.length;return 0===e.entityTypes.size&&!e.hasNull&&r(t)&&n.every(e=>{let n,s;return r(e)&&(n=e.entityTypes,s=t.entityTypes,n.size===s.size&&[...n].every(e=>s.has(e)))})?{kind:"array",entityTypes:t.entityTypes}:{kind:"other"}})(l(e,{latestModel:t,phxDefinitions:n,openCommonTypes:new Set}));

package/dist/application-spec/parse-application-files/spec/relations/relation-field-mismatch.d.ts

@@ -0,0 +1,46 @@
+import type { ReferenceFieldType } from './reference-field-type.js';
+type Cardinality = '0-1' | '1-1' | '0-N' | '1-N';
+/** How a field holds its reference: one id, one id or `null`, or an array of ids. */
+export type ReferenceFieldShape = 'single' | 'nullableSingle' | 'array';
+/**
+ * Why a relation cannot read its related entities from its field.
+ *
+ * - `notReference`: the field does not hold entity ids.
+ * - `otherEntityTypes`: the field holds ids of other entity types than the relation relates to.
+ * - `cardinality`: the field of a direct relation holds its ids in another shape than the
+ *   cardinality of the relation needs.
+ */
+export type RelationFieldMismatch = {
+    readonly kind: 'notReference';
+} | {
+    readonly kind: 'otherEntityTypes';
+    readonly referenced: readonly string[];
+} | {
+    readonly kind: 'cardinality';
+    readonly shape: ReferenceFieldShape;
+    readonly required: ReferenceFieldShape;
+};
+interface RelationReadingField {
+    readonly kind: 'direct' | 'indirect';
+    readonly cardinality: Cardinality;
+}
+/**
+ * Checks the field of a direct or indirect relation against what the relation reads from it.
+ *
+ * The field must reference exactly `relatedEntityTypes`: for a direct relation the entity types of
+ * its target, for an indirect relation the entity types it is declared on, because there the field
+ * belongs to the target and points back. A direct relation also fixes the shape of the field by
+ * its cardinality. An indirect relation reads every shape, since its cardinality counts the
+ * entities that point back and not the ids in the field.
+ *
+ * When an alias holds the field, the field can have another type in each entity type of the alias.
+ * The relation is accepted when the field fits in at least one of them. Requiring all of them
+ * would be the stricter reading, but projects whose specs type-check rely on the looser one, so
+ * it would reject working projects.
+ *
+ * @param fieldTypes The type of the field in each entity type that holds it.
+ * @returns The mismatch of the first entity type, or `undefined` when the field fits in one of
+ *   them or its type there is unknown.
+ */
+export declare const relationFieldMismatch: (relation: RelationReadingField, fieldTypes: readonly ReferenceFieldType[], relatedEntityTypes: readonly string[]) => RelationFieldMismatch | undefined;
+export {};

package/dist/application-spec/parse-application-files/spec/relations/relation-field-mismatch.js

@@ -0,0 +1 @@
+let e={"0-1":"nullableSingle","1-1":"single","0-N":"array","1-N":"array"};export const relationFieldMismatch=(n,i,r)=>{let t=i.map(i=>((n,i,r)=>{if("unknown"===i.kind)return;if("other"===i.kind)return{kind:"notReference"};let t=i.entityTypes;if(!(t.size===new Set(r).size&&r.every(e=>t.has(e))))return{kind:"otherEntityTypes",referenced:[...t]};if("indirect"===n.kind)return;let l="array"===i.kind?"array":i.nullable?"nullableSingle":"single",a=e[n.cardinality];return l===a?void 0:{kind:"cardinality",shape:l,required:a}})(n,i,r));return t.includes(void 0)?void 0:t[0]};

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

@@ -1,5 +1,5 @@
 import { Branded } from '@salsita-ai/common/utils';
-import type { ParseContext } from '../../../core/index.js';
+import type { ParseContext, PhoenixDefinitions } from '../../../core/index.js';
 import type { MergedRelations } from '../../merge/index.js';
 import type { ComponentEntry } from '../components/index.js';
 import type { Expression } from '../expressions/index.js';
@@ -19,7 +19,8 @@ export type Relations = Branded<'Relations', {
  * Validates merged relations against the latest model, then expands into components + expressions.
  *
  * Each relation is individually constructed via `Relation()` which builds its own expression
- * and component entries. This factory validates cross-relation concerns (counterpart pairing,
+ * and component entries. This factory validates the field a direct or indirect relation reads
+ * against the shape that holds it, validates cross-relation concerns (counterpart pairing,
  * composition tree reachability) and aggregates the per-relation artifacts.
  */
-export declare const Relations: (rawRelations: MergedRelations, latestModel: ModelVersion, ctx: ParseContext) => Relations;
+export declare const Relations: (rawRelations: MergedRelations, latestModel: ModelVersion, phxDefinitions: PhoenixDefinitions, ctx: ParseContext) => Relations;