@salsita-ai/sdk 0.50.0-develop.ae9a830ef0 → 0.50.0-develop.afbc5157e1

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

@@ -0,0 +1,21 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { RuntimeSpec } from '../runtime-spec/index.js';
+import { AdminSpecRuntime } from './admin-runtime/index.js';
+import { ConfiguratorSpecRuntime } from './configurator-runtime/index.js';
+import type { RuntimeReferenceStore } from './runtime-reference-store.js';
+import type { SpecCodeModule } from './spec-code/index.js';
+/**
+ * The sections of both domains that the spec alone determines, without a project module: each
+ * domain's model and the data of its `phx.domain` factories.
+ *
+ * An application is built in two steps in one reference store. This is the first: it runs before
+ * the project's modules load, because they call the `phx.domain` factories while they are evaluated.
+ * The second, `ApplicationRuntime` with the loaded modules, builds the same sections through the
+ * same functions, so it returns the same objects: `phx.domain.model.X` is the reflection the
+ * application's domain validates with.
+ */
+export type SpecRuntime = Branded<'SpecRuntime', {
+    readonly configurator: ConfiguratorSpecRuntime;
+    readonly admin: AdminSpecRuntime;
+}>;
+export declare const SpecRuntime: (spec: RuntimeSpec, referenceStore: RuntimeReferenceStore, specCode: SpecCodeModule | undefined) => SpecRuntime;

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

@@ -0,0 +1 @@
+import{Branded as i}from"@salsita-ai/common/utils";import{AdminSpecRuntime as o}from"./admin-runtime/index.js";import{ConfiguratorSpecRuntime as r}from"./configurator-runtime/index.js";export const SpecRuntime=(m,n,t)=>i({configurator:r(m,n,t?.configurator),admin:o(m,n,t?.admin)});

package/dist/domain/spec/runtime-spec/decode-runtime-spec.d.ts

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

package/dist/domain/spec/runtime-spec/decode-runtime-spec.js

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

package/dist/domain/spec/runtime-spec/encode-runtime-spec.d.ts

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

package/dist/domain/spec/runtime-spec/encode-runtime-spec.js

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

package/dist/domain/spec/runtime-spec/encoded-runtime-spec.d.ts

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

package/dist/domain/spec/runtime-spec/encoded-runtime-spec.js

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

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

@@ -0,0 +1,4 @@
+export { decodeRuntimeSpec } from './decode-runtime-spec.js';
+export { encodeRuntimeSpec } from './encode-runtime-spec.js';
+export { type RuntimeAdminSpec, type RuntimeAssistantSpec, type RuntimeConfiguratorSpec, type RuntimeDataSchemaEntry, type RuntimeDataSchemas, type RuntimeDataSpec, type RuntimeEntitySchema, type RuntimeInfra, type RuntimeLatestModelVersion, type RuntimeModelVersion, type RuntimeResolvedModelVersion, type RuntimeResolvedVersions, type RuntimeShapeSchema, type RuntimeSpec, toRuntimeSpec, } from './runtime-spec.js';
+export { type SpecCodeId, specCodeComponentKey, specCodeEvalIds, specCodeExpressionKey, specCodeFilterId, } from './spec-code-id.js';

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

@@ -0,0 +1 @@
+export{decodeRuntimeSpec}from"./decode-runtime-spec.js";export{encodeRuntimeSpec}from"./encode-runtime-spec.js";export{toRuntimeSpec}from"./runtime-spec.js";export{specCodeComponentKey,specCodeEvalIds,specCodeExpressionKey,specCodeFilterId}from"./spec-code-id.js";

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

@@ -0,0 +1,174 @@
+import type { AdminPages, AdminStates, ConfiguratorStates } from '../application/index.js';
+import type { Components } from '../components/index.js';
+import type { Expressions } from '../expressions/index.js';
+import type { Invariants } from '../invariants/index.js';
+import type { JsonSchema } from '../json-schema.js';
+import type { CommonTypes, Defaults, EntityOrAliasName, EntityTypeName, EntityTypes, ModelVersionKey, Presets, SpecAliases } from '../model/index.js';
+import type { Acl, Actions, AppMetadata, AssistantResolvedManifest, Chunks, ParsedDataSpecEntries, ResourceEntry, SpecResourcesConfig, SpecTransformers, Theme, Ui } from '../sections/index.js';
+/**
+ * The part of a parsed entity schema the runtime reads: the entity type and the schema of its
+ * shape, from which it builds the entity's reflection. The full schema with `id` and `type` is
+ * only registered with a deployment, and the compiled shape validators only check presets and
+ * defaults while parsing.
+ */
+export interface RuntimeEntitySchema {
+    readonly entityType: EntityTypeName;
+    readonly shapeSchema: JsonSchema;
+}
+/**
+ * The part of a parsed model version the runtime reads: the entity types, the aliases, the common
+ * types and the schema of every entity's shape. The shapes and the resolved shapes only serve the
+ * parser and the type generator, except the runtime schemas of the latest version's shapes (see
+ * `RuntimeLatestModelVersion`).
+ */
+export interface RuntimeModelVersion {
+    readonly versionKey: ModelVersionKey;
+    readonly entityTypes: EntityTypes;
+    /** Entity types allowed as preset root — members of the RootEntity alias, or all entity types if no RootEntity alias. */
+    readonly rootEntityTypes: readonly EntityTypeName[];
+    readonly aliases: SpecAliases;
+    readonly commonTypes: CommonTypes;
+    readonly entitySchemas: readonly RuntimeEntitySchema[];
+}
+/**
+ * The latest model version of a domain as the runtime reads it: a model version plus the runtime
+ * schema of every shape, which `phx.domain.model` reflects as `<Name>Shape`.
+ */
+export interface RuntimeLatestModelVersion extends RuntimeModelVersion {
+    readonly shapes: ReadonlyMap<EntityOrAliasName, RuntimeShapeSchema>;
+}
+/** The part of a parsed shape the runtime reads: its name and its runtime JSON schema. */
+export interface RuntimeShapeSchema {
+    readonly name: EntityOrAliasName;
+    readonly runtimeSchema: JsonSchema;
+}
+/**
+ * One model version of a domain as the runtime reads it, with the migration file that leads to it.
+ * `version` is the integer version number (1, 2, 3, …), `key` is always `v{N}`, never `latest`,
+ * `isLatest` marks the version of the `latest` model key, and `migrationFile` is the path of the
+ * migration file, present from v2 on.
+ */
+export interface RuntimeResolvedModelVersion {
+    readonly version: number;
+    readonly key: string;
+    readonly isLatest: boolean;
+    readonly modelVersion: RuntimeModelVersion;
+    readonly migrationFile: string | undefined;
+}
+/**
+ * Every model version of a domain as the runtime reads it; it builds the domain's migrations from
+ * them. `latestVersion` is the integer of the `latest` key, and `versionedModels` is sorted
+ * ascending by version number.
+ */
+export interface RuntimeResolvedVersions {
+    readonly latestVersion: number;
+    readonly versionedModels: readonly RuntimeResolvedModelVersion[];
+}
+/** The model of a domain as the runtime reads it: the latest version and every earlier one. */
+interface RuntimeDomainModel {
+    readonly latestModel: RuntimeLatestModelVersion;
+    readonly resolvedVersions: RuntimeResolvedVersions;
+}
+/** The part of a parsed data schema the runtime reads: the JSON schema it validates the data with. */
+export interface RuntimeDataSchemaEntry {
+    readonly runtimeSchema: JsonSchema;
+}
+/**
+ * The data schemas as the runtime reads them: the JSON schema of each kind of data and the hash of
+ * the published data. The enhanced schemas, with Phoenix references, only serve the type generator.
+ */
+export interface RuntimeDataSchemas {
+    readonly publishedData: RuntimeDataSchemaEntry;
+    readonly publishedDataHash: string;
+    readonly sessionData: RuntimeDataSchemaEntry;
+    readonly frontendData: RuntimeDataSchemaEntry;
+    readonly backendData: RuntimeDataSchemaEntry | undefined;
+    readonly finalizeData: RuntimeDataSchemaEntry;
+    readonly prefetchedFinalizeData: RuntimeDataSchemaEntry;
+    readonly finalizeResult: RuntimeDataSchemaEntry;
+    readonly callbackData: RuntimeDataSchemaEntry;
+}
+/**
+ * The assistant as the runtime reads it: its resolved manifest. The parsed assistant schema the
+ * manifest is resolved from only serves the parser.
+ */
+export type RuntimeAssistantSpec = {
+    readonly resolved: AssistantResolvedManifest;
+} | null;
+/**
+ * The data spec as the runtime reads it: the data entries and their chunks. The data entries and
+ * admin data pages the parser derives from them only serve the admin spec and the type generator.
+ */
+export interface RuntimeDataSpec {
+    /** Validated entries grouped by their source `$data` subsection for generated SDK config. */
+    readonly entries: ParsedDataSpecEntries;
+    /** Validated published-data chunks, including the auto-injected `system` chunk when needed. */
+    readonly chunks: Chunks;
+}
+/**
+ * The configurator part of the runtime spec. It leaves out the configuration schema and its
+ * version, which only a deployment registers, and the assistant's server settings (instructions
+ * and AI settings), which must never reach the browser of a customer.
+ */
+export interface RuntimeConfiguratorSpec extends RuntimeDomainModel {
+    readonly components: Components;
+    readonly presets: Presets;
+    readonly expressions: Expressions;
+    readonly actions: Actions;
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly states: ConfiguratorStates;
+    readonly theme: Theme;
+    readonly ui: Ui;
+    readonly transformers: SpecTransformers;
+    readonly dataSchemas: RuntimeDataSchemas;
+    readonly assistant: RuntimeAssistantSpec;
+}
+/**
+ * The admin part of the runtime spec. It leaves out the configuration schema and its version, which
+ * only a deployment registers.
+ */
+export interface RuntimeAdminSpec extends RuntimeDomainModel {
+    readonly components: Components;
+    readonly presets: Presets;
+    readonly expressions: Expressions;
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly states: AdminStates;
+    readonly adminPages: AdminPages;
+}
+/**
+ * The infrastructure settings the runtime reads: access control and resources. The environment
+ * variable declarations only drive the generated environment readers.
+ */
+export interface RuntimeInfra {
+    readonly acl: Acl;
+    readonly resources: readonly ResourceEntry[] | undefined;
+    readonly resourcesConfig: SpecResourcesConfig | undefined;
+}
+/**
+ * The parsed application spec as the runtime reads it: what `ApplicationRuntime` builds the
+ * configurator and admin runtimes from, and the sections an application needs besides its domains
+ * (data spec, app metadata, resources, access control, user interface settings, webhook data
+ * schemas, admin pages). `phoenix sync` and `phoenix build` write it to
+ * `.phoenix/application-spec.json` with `encodeRuntimeSpec`.
+ *
+ * Its sections are the spec data types of `domain`, the types the parser produces, so a parsed
+ * `ApplicationSpec` is assignable to it. It leaves out what only the parser, the type generator or
+ * a deployment use, and holds plain data, Maps and Sets only, so it can be encoded as JSON.
+ */
+export interface RuntimeSpec {
+    readonly appMetadata: AppMetadata;
+    readonly dataSpec: RuntimeDataSpec;
+    readonly configurator: RuntimeConfiguratorSpec;
+    readonly admin: RuntimeAdminSpec;
+    readonly infra: RuntimeInfra;
+}
+/**
+ * Takes from a parsed application spec the part the runtime reads. It reuses the sections it keeps
+ * whole, and builds trimmed copies of the model versions, data schemas, assistant and data spec
+ * without what the runtime does not read. It takes any `RuntimeSpec`, which a parsed
+ * `ApplicationSpec` is, and copies only what the type declares.
+ */
+export declare const toRuntimeSpec: (spec: RuntimeSpec) => RuntimeSpec;
+export {};

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

@@ -0,0 +1 @@
+let e=e=>({versionKey:e.versionKey,entityTypes:e.entityTypes,rootEntityTypes:e.rootEntityTypes,aliases:e.aliases,commonTypes:e.commonTypes,entitySchemas:e.entitySchemas.map(e=>({entityType:e.entityType,shapeSchema:e.shapeSchema}))}),s=e=>({runtimeSchema:e.runtimeSchema}),a=s=>{let a;return{latestModel:{...e(a=s.latestModel),shapes:new Map([...a.shapes].map(([e,s])=>[e,{name:s.name,runtimeSchema:s.runtimeSchema}]))},resolvedVersions:{latestVersion:s.resolvedVersions.latestVersion,versionedModels:s.resolvedVersions.versionedModels.map(s=>({version:s.version,key:s.key,isLatest:s.isLatest,migrationFile:s.migrationFile,modelVersion:e(s.modelVersion)}))}}};export const toRuntimeSpec=e=>{let t,{configurator:n,admin:i,infra:r}=e;return{configurator:{components:n.components,presets:n.presets,expressions:n.expressions,actions:n.actions,invariants:n.invariants,dataSchemas:{publishedDataHash:(t=n.dataSchemas).publishedDataHash,publishedData:s(t.publishedData),sessionData:s(t.sessionData),frontendData:s(t.frontendData),backendData:t.backendData&&s(t.backendData),finalizeData:s(t.finalizeData),prefetchedFinalizeData:s(t.prefetchedFinalizeData),finalizeResult:s(t.finalizeResult),callbackData:s(t.callbackData)},defaults:n.defaults,states:n.states,theme:n.theme,ui:n.ui,transformers:n.transformers,assistant:n.assistant&&{resolved:n.assistant.resolved},...a(n)},admin:{components:i.components,presets:i.presets,expressions:i.expressions,invariants:i.invariants,defaults:i.defaults,states:i.states,adminPages:i.adminPages,...a(i)},appMetadata:e.appMetadata,infra:{acl:r.acl,resources:r.resources,resourcesConfig:r.resourcesConfig},dataSpec:{entries:e.dataSpec.entries,chunks:e.dataSpec.chunks}}};

package/dist/domain/spec/runtime-spec/spec-code-id.d.ts

@@ -0,0 +1,40 @@
+import type { MemoEvalPlan } from '../expressions/index.js';
+/**
+ * The id under which the generated `.phoenix/spec-code.ts` holds one piece of code written in YAML,
+ * and under which the runtime looks it up. Ids are unique within one domain; the configurator and
+ * the admin domain each have their own map.
+ *
+ * An id is computed from what the runtime spec already carries, by the functions of this file, on
+ * both sides: the generator that writes the closures and the runtime that reads them. It names the
+ * entity or alias that owns the code, the expression or the component instance, the position of the
+ * code inside that one value, and a hash of the code's text. So it stays the same when anything
+ * else in the spec changes, and it changes whenever the code itself changes: a module generated from
+ * another version of the spec does not hold it, and the runtime compiles the text instead of running
+ * the wrong closure.
+ */
+export type SpecCodeId = string;
+/**
+ * The part of an id that names a value expression: `KitchenRange.$maxWidth`. Its constant, when it
+ * is one, shares the plan and so the ids.
+ */
+export declare const specCodeExpressionKey: (typeOrAlias: string, expressionName: string) => string;
+/**
+ * The part of an id that names a component instance: `KitchenRange.main:detail`. The component
+ * belongs to it because an instance name is unique per component, not per entity: one entity can
+ * attach `main` of several components.
+ */
+export declare const specCodeComponentKey: (typeOrAlias: string, instanceName: string, componentName: string) => string;
+/**
+ * The id of each dependency of a plan, by dependency index: `<key>#<n>@<hash>` for the `n`-th
+ * `$eval` dependency, `undefined` for a read. `key` is the expression or component key of the value
+ * the plan builds. The ordinal counts the plan's `$eval` dependencies only, so a `$read` added to
+ * the same value does not renumber them.
+ */
+export declare const specCodeEvalIds: (plan: MemoEvalPlan, key: string) => ReadonlyArray<SpecCodeId | undefined>;
+/**
+ * Id of the `$eval` of one filter criterion of a component instance:
+ * `KitchenRange.label:textValue#filter0.active@<hash>`. `componentKey` comes from
+ * {@link specCodeComponentKey}; `branch` is the index of the filter among the `$or` alternatives,
+ * 0 when the filter has none; `code` is the criterion's code.
+ */
+export declare const specCodeFilterId: (componentKey: string, branch: number, criterion: string, code: string) => SpecCodeId;

package/dist/domain/spec/runtime-spec/spec-code-id.js

@@ -0,0 +1 @@
+let e=e=>{let t=e.trim(),o=0x811c9dc5;for(let e=0;e<t.length;e++)o^=t.charCodeAt(e),o=Math.imul(o,0x1000193)>>>0;return o.toString(16).padStart(8,"0")};export const specCodeExpressionKey=(e,t)=>`${e}.${t}`;export const specCodeComponentKey=(e,t,o)=>`${e}.${t}:${o}`;export const specCodeEvalIds=(t,o)=>{let r=0;return t.deps.map(t=>"eval"===t.kind?`${o}#${r++}@${e(t.code)}`:void 0)};export const specCodeFilterId=(t,o,r,d)=>`${t}#filter${o}.${r}@${e(d)}`;

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

@@ -0,0 +1,23 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { EnhancedJsonSchemaType } from '../../core/index.js';
+import type { JsonSchema } from '../json-schema.js';
+import type { ActionName } from '../model/index.js';
+/** One parameter of an action: its declared schema, and whether a call has to pass it (a nullable param is optional). */
+export interface ActionParam {
+    readonly schema: EnhancedJsonSchemaType;
+    readonly required: boolean;
+}
+/**
+ * One validated action declaration. `params` and `result` keep the enhanced schemas for codegen and
+ * for consumers that expose the action; `paramsSchema` is the AJV-ready object schema of the parameters, with the
+ * refs resolved into `$defs`, which the action system validates the arguments of a call against.
+ */
+export type Action = Branded<'Action', {
+    readonly name: ActionName;
+    readonly description?: string;
+    readonly params: Readonly<Record<string, ActionParam>>;
+    readonly result: Readonly<Record<string, EnhancedJsonSchemaType>>;
+    readonly paramsSchema: JsonSchema;
+}>;
+/** The validated `actions` section: every declared action by name, in declaration order; empty when the spec declares none. */
+export type Actions = Branded<'Actions', ReadonlyMap<ActionName, Action>>;

package/dist/domain/spec/sections/actions.js

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

package/dist/domain/spec/sections/app-metadata.d.ts

@@ -0,0 +1,18 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ApplicationVersion } from './application-version.js';
+/**
+ * Validated application metadata — version, auth, infrastructure settings.
+ * Used by codegen for ApplicationVersion export and builder chain methods.
+ */
+export type AppMetadata = Branded<'AppMetadata', {
+    readonly applicationVersion: ApplicationVersion;
+    readonly workspace: boolean;
+    readonly webComponentTag: string | undefined;
+    readonly pageTitle: string | undefined;
+    readonly useAuthHook: boolean;
+    readonly useClerk: boolean;
+    readonly enableAdminRelease: boolean;
+    readonly jsonSchemaValidator: 'ajv' | 'csp-compatible';
+    readonly gltfDecoder: 'js' | 'wasm';
+    readonly collectFinalizeData: boolean;
+}>;

package/dist/domain/spec/sections/app-metadata.js

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

package/dist/domain/spec/sections/application-version.d.ts

@@ -0,0 +1,7 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Branded semantic version (x.y.z) of the application.
+ * Exported by codegen as the `ApplicationVersion` constant and stored as
+ * `applicationVersion` on the deployment record.
+ */
+export type ApplicationVersion = Branded<'ApplicationVersion', string>;

package/dist/domain/spec/sections/application-version.js

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

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

@@ -0,0 +1,96 @@
+import type { AssistantFormElementDescriptor } from './form/index.js';
+/**
+ * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
+ * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
+ * string in the current locale.
+ */
+export interface AssistantFieldSource {
+    readonly source: string;
+    readonly localized?: true;
+}
+/**
+ * What the integrator promises about a list of choices, so the agent can read it once and reuse it:
+ * `sameForAllInstances` when every entity of the type gets the same list, `constantDuringSession`
+ * when the list does not change during a session. A hint only adds a sentence to the description of
+ * the recipe group or options edge it is declared on; nothing verifies it.
+ */
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
+/**
+ * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
+ * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
+ * name of its field on `<Type>ChildRecipes` or `<Type>ReplaceRecipes` and the id the agent passes to
+ * `addChild` or `replaceEntity`, `instanceName` the component instance it reads, `description` the
+ * manifest's text for that field, `dryRuns` whether the recipes of the group can be dry-run, and
+ * `hints` the sentences of the field's description saying when the agent can reuse what it read.
+ */
+export interface AssistantRecipeGroup {
+    readonly groupId: string;
+    readonly instanceName: string;
+    readonly description?: string;
+    readonly dryRuns: boolean;
+    readonly hints: readonly AssistantResolvedHint[];
+}
+/**
+ * The options edge of one writable field the assistant manifest links to its component. `field` is
+ * the delta field of `modify<Type>` the choices are for, `edgeName` the field of `<Type>Meta` that
+ * lists them, `componentType` and `instanceName` the component instance they are read from, and
+ * `validate` whether `modify<Type>` rejects a value that is not among them, and `dryRuns` whether
+ * the choices can be dry-run.
+ */
+export interface AssistantFieldOptions {
+    readonly field: string;
+    readonly edgeName: string;
+    readonly componentType: 'materialSwatch' | 'attributeSelection' | 'distanceDimensionSelect';
+    readonly instanceName: string;
+    readonly validate: boolean;
+    readonly dryRuns: boolean;
+}
+/**
+ * One view the assistant manifest lets the agent take a screenshot of an entity from: `view` is the
+ * value of the `<Type>ScreenshotView` enum the agent asks for it by, `instanceName` the
+ * `agentScreenshot` component instance that renders it, and `description` what the view shows.
+ */
+export interface AssistantScreenshotView {
+    readonly view: string;
+    readonly instanceName: string;
+    readonly description: string;
+}
+/**
+ * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
+ * the GraphQL schema text rebuilt from the resolved manifest; `fields` maps each GraphQL object type's exposed
+ * fields (type name → GraphQL field name) to the stored field or expression its resolvers read;
+ * `deletableTypes` lists the entity types the `deleteEntity` mutation may delete, with aliases
+ * already expanded, and absent means none; `writableFields` maps, per entity type with a
+ * `modify<Type>` mutation, each field of its delta input to the stored property it writes, and
+ * absent means no entity type is writable; `childRecipes` lists, per entity type with a `meta` field,
+ * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
+ * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
+ * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
+ * writable fields, and absent means none; `screenshots` lists, per entity type, the views
+ * `meta { screenshot }` renders, and absent means none; `actions` maps each custom `Mutation` field to the
+ * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
+ * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
+ * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
+ * spreads a lens, with the copies that unroll each lens to its depth. Consumed by the configurator
+ * GraphQL system.
+ */
+export interface AssistantManifest {
+    readonly sdl: string;
+    /** Navigation state fields exposed by the schema; absent means none. Values stay in the SDL. */
+    readonly navigationFields?: ReadonlyArray<'navigationState' | 'viewState' | 'toolState'>;
+    readonly fields: Readonly<Record<string, Readonly<Record<string, AssistantFieldSource>>>>;
+    readonly deletableTypes?: readonly string[];
+    readonly writableFields?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
+    readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
+    readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly screenshots?: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
+    readonly actions?: Readonly<Record<string, string>>;
+    readonly lenses?: {
+        readonly declarations: string;
+        readonly definitions: string;
+    };
+    /** The project's own form elements, in YAML order; absent means none. */
+    readonly formElements?: readonly AssistantFormElementDescriptor[];
+}

package/dist/domain/spec/sections/assistant/assistant-resolved-manifest.d.ts

@@ -0,0 +1,135 @@
+import type { AssistantFieldOptions, AssistantRecipeGroup, AssistantResolvedHint, AssistantScreenshotView } from './assistant-manifest.js';
+import type { AssistantFormElementDescriptor } from './form/index.js';
+/** JSON description of a scalar or recursively nested list, including nullability at each level. */
+export type AssistantValueType = {
+    readonly kind: 'scalar';
+    readonly name: 'Int' | 'Float' | 'String' | 'Boolean' | 'ID' | 'JSON';
+    readonly nonNull: boolean;
+} | {
+    readonly kind: 'list';
+    readonly item: AssistantValueType;
+    readonly nonNull: boolean;
+};
+/**
+ * An entity edge resolved at parse time, linked to GraphQL types only during building: a relation,
+ * an entity-returning expression or an action result member. `target` is an entity type or alias,
+ * `list` makes it `[Target!]` and `nullable` drops the outer non-null.
+ */
+export interface AssistantEdgeType {
+    readonly kind: 'edge';
+    readonly target: string;
+    readonly list: boolean;
+    readonly nullable: boolean;
+}
+/**
+ * A field's source and resolved type, carried in the application bundle without GraphQL instances.
+ * `lenses` names the lenses the field's own declaration on this alias or type tags it with; a field
+ * only inherited from an alias carries none here, since the alias already selects it.
+ */
+export interface AssistantResolvedField {
+    readonly name: string;
+    readonly source: string;
+    readonly type: {
+        readonly kind: 'value';
+        readonly type: AssistantValueType;
+    } | AssistantEdgeType;
+    readonly localized: boolean;
+    readonly description?: string;
+    readonly lenses?: readonly string[];
+}
+/** Declared UI state values used to describe the navigation query. */
+export interface AssistantStates {
+    readonly navigationStates: readonly string[];
+    readonly viewStates: readonly string[];
+    readonly toolStates: readonly string[];
+}
+/** Serializable resolved whitelist from which the browser or backend constructs the assistant schema. */
+export interface AssistantResolvedManifest {
+    readonly declarations: AssistantDeclarations;
+    readonly entityTypes: readonly string[];
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    readonly exampleType?: string;
+    readonly fields: Readonly<Record<string, readonly AssistantResolvedField[]>>;
+    readonly states: AssistantStates;
+    readonly deletableTypes: readonly string[];
+    readonly writableTypes: readonly AssistantWritableType[];
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
+    /** The screenshot views of each entity type with at least one, aliases expanded, in manifest order. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
+    readonly actionFields: readonly AssistantResolvedAction[];
+    /** The entity types that declare invariants, whose `meta` lists the warnings and notices they hold. */
+    readonly invariantTypes: readonly string[];
+    /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
+    readonly lenses: Readonly<Record<string, {
+        readonly description: string;
+        readonly maxDepth: number;
+    }>>;
+    /** The project's own form elements, in YAML order, which the prompt lists after the built-ins and the panel renders with their registered components. */
+    readonly formElements: readonly AssistantFormElementDescriptor[];
+}
+/** Optional mutation input for one stored field, using its exposed name. */
+export interface AssistantWritableField {
+    readonly name: string;
+    readonly property: string;
+    readonly type: AssistantValueType;
+    readonly description?: string;
+}
+/** One entity type's writable fields, in manifest order. */
+export interface AssistantWritableType {
+    readonly entityType: string;
+    readonly fields: readonly AssistantWritableField[];
+}
+/** The recipe groups of one kind on one entity type or alias key, in manifest order, each with its own hints. */
+export type AssistantResolvedRecipes = readonly AssistantRecipeGroup[];
+/** One options edge, carrying the write-validation contract and schema description hints. */
+export interface AssistantResolvedOptionsEdge {
+    readonly options: AssistantFieldOptions;
+    readonly hints: readonly AssistantResolvedHint[];
+}
+/** An action result field, either an entity edge or a plain JSON-described value. */
+export type AssistantResolvedActionResult = (AssistantEdgeType & {
+    readonly description?: string;
+}) | {
+    readonly kind: 'value';
+    readonly type: AssistantValueType;
+    readonly description?: string;
+};
+/** A custom mutation resolved against the declared action, independent of its implementation. */
+export interface AssistantResolvedAction {
+    readonly fieldName: string;
+    readonly actionName: string;
+    readonly description?: string;
+    readonly args: Readonly<Record<string, {
+        readonly type: AssistantValueType;
+        readonly description?: string;
+    }>>;
+    readonly result: Readonly<Record<string, AssistantResolvedActionResult>>;
+}
+/** Immutable, validated declaration bindings retained before alias expansion for session narrowing. */
+export interface AssistantDeclarations {
+    readonly entities: Readonly<Record<string, readonly AssistantDeclaredField[]>>;
+    readonly enumValues: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    readonly deletable: readonly string[];
+    readonly writable: Readonly<Record<string, Readonly<Record<string, AssistantDeclaredWrite>>>>;
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    /** The screenshot views under the entity type or alias key that declares them. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
+}
+/** An original field declaration, including metadata needed to reapply inheritance and enum descriptions. */
+export interface AssistantDeclaredField extends AssistantResolvedField {
+    readonly describedByManifest: boolean;
+    readonly enumValues?: readonly string[];
+    readonly valueDescription?: string;
+}
+/** Stored-property types and component bindings, resolved separately for each concrete member. */
+export interface AssistantDeclaredWrite {
+    readonly members: Readonly<Record<string, {
+        readonly exposedDescription?: string;
+        readonly field: AssistantWritableField;
+        readonly options?: AssistantResolvedOptionsEdge;
+    }>>;
+    readonly defaultOptionsName: boolean;
+}

package/dist/domain/spec/sections/assistant/assistant-resolved-manifest.js

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

package/dist/domain/spec/sections/assistant/form/assistant-form-element-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shape of a form element's tag, and of its attributes' names: the panel reads form markup
+ * with lowercase tag and attribute names, so a name with an upper-case letter would never match.
+ */
+export declare const ASSISTANT_FORM_NAME_PATTERN: RegExp;
+/**
+ * Whether a tag is an HTML element name, which no form element may take, so that markup in a form
+ * is never mistaken for HTML. The spec rejects a project's element by it and the panel's registry
+ * refuses one, so both read the same list.
+ */
+export declare const isHtmlElementName: (name: string) => boolean;