@salsita-ai/sdk 0.50.0-develop.9ed52379e9 → 0.50.0-develop.a49722158a

package/dist/docs/phoenix/webhooks.mdx

@@ -34,6 +34,23 @@ Phoenix provides domain-aware builders through the global `phx.webhooks` namespa
 
 ### Webhook Entry Point
 
+Your webhook is the default export of `src/webhooks/index.ts`. With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the file is yours to create; sync does not write it. A project without it gets a built-in webhook, so it builds and deploys with no webhook code. The built-in webhook has one handler, an anonymous auth handler, which the platform calls only when `spec/application.yaml` sets `useAuthHook`. The legacy pipeline writes the file with that webhook on the first sync.
+
+Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session. A project that sets `useAuthHook` or `useClerk` needs its own auth handler, because the built-in one answers only anonymous requests. The smallest file is the built-in webhook itself:
+
+```ts
+// src/webhooks/index.ts
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withAnonymousHandler(async () => ({ success: true, data: {}, role: 'anonymous' }))
+  .build()
+
+export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
+```
+
+The next `phoenix sync` or `phoenix build`, or the rebuild of a running `phoenix dev`, uses the file; deleting it brings the built-in webhook back. A webhook needs at least one handler, and a project with any other file in `src/webhooks/` must have `index.ts`.
+
+A webhook with more handlers:
+
 ```ts
 // src/webhooks/index.ts
 import { authHandler } from './handlers/auth-handler.js'
@@ -148,7 +165,7 @@ resources:
     s3Key: clientImage
 ```
 
-These resources are automatically made available as typed properties in task handlers via the `resources` parameter.
+These resources are automatically made available as typed properties in task handlers via the `resources` parameter. Two static resources with the same name are an error: `phoenix check` and `phoenix build` report the second entry (`DUPLICATE_RESOURCE_NAME`).
 
 #### Task Payload
 
@@ -991,7 +1008,7 @@ Save the same OAuth client ID, client secret, and base URL in the customer's **C
 JWT_SECRET_BASE64=<base64 of a long random key>
 ```
 
-For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
+For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm phoenix deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
 
 #### Clerk organization
 

package/dist/domain/admin-domain/implementation/common-admin-expressions.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntity, DomainState, OpenExpressionContext, Violation } from '../../core/index.js';
+import type { DomainEntity, MigrateFunction, Violation } from '../../core/index.js';
 import type { ChildEntitySelectionOption } from '../../system-components/child-entity-selection.js';
 import type { RecipeListItem } from '../../system-components/index.js';
 import type { SwatchOptionMap } from '../../system-components/material-swatch.js';
@@ -17,11 +17,23 @@ export declare const commonAdminCustomExpressions: {
         readonly $isDraft: (self: PresetCategory) => boolean;
     };
 };
+/**
+ * An expression of this file. It reads nothing of the entity or of the state, and of the context
+ * only `CONTEXT`, so it is written against that part alone: it fits every entity of every project
+ * whose expression context has that part, because the project's own entity view, state and context
+ * are assignable to these parameters.
+ */
+type CommonAdminExpression<CONTEXT, T> = (self: unknown, state: unknown, ctx: CONTEXT) => T;
+/** The part of the expression context a recipe expression reads. */
+interface RecipeExpressionContext<PUBLISHED_DATA> {
+    readonly publishedData: PUBLISHED_DATA;
+    readonly migrate: MigrateFunction<DomainEntity<string>>;
+}
 export declare const CommonAdminExpressionBuilder: {
-    createConstantSwatchExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(swatches: SwatchOptionMap) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap);
-    createConstantRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(recipes: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
-    createConstantChildEntitySelectionExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(entities: ChildEntitySelectionOption[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => ChildEntitySelectionOption[]);
-    createRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends CommonAdminPublishedData, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(collection: string, defaults: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
+    createConstantSwatchExpression: (swatches: SwatchOptionMap) => (() => SwatchOptionMap);
+    createConstantRecipeExpression: (recipes: RecipeListItem[]) => (() => RecipeListItem[]);
+    createConstantChildEntitySelectionExpression: (entities: ChildEntitySelectionOption[]) => (() => ChildEntitySelectionOption[]);
+    createRecipeExpression: (collection: string, defaults: RecipeListItem[]) => CommonAdminExpression<RecipeExpressionContext<CommonAdminPublishedData>, RecipeListItem[]>;
 };
 /**
  * Expression helpers for projects with chunked published data.
@@ -30,13 +42,16 @@ export declare const CommonAdminExpressionBuilder: {
  * Use {@link CommonAdminExpressionBuilder} for projects with flat published data.
  */
 export declare const ChunkedCommonAdminExpressionBuilder: {
-    createConstantSwatchExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(swatches: SwatchOptionMap) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap);
-    createConstantRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(recipes: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
-    createConstantChildEntitySelectionExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(entities: ChildEntitySelectionOption[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => ChildEntitySelectionOption[]);
-    createRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends {
+    createConstantSwatchExpression: (swatches: SwatchOptionMap) => (() => SwatchOptionMap);
+    createConstantRecipeExpression: (recipes: RecipeListItem[]) => (() => RecipeListItem[]);
+    createConstantChildEntitySelectionExpression: (entities: ChildEntitySelectionOption[]) => (() => ChildEntitySelectionOption[]);
+    createRecipeExpression: (collection: string, defaults: RecipeListItem[]) => CommonAdminExpression<RecipeExpressionContext<{
         readonly system?: CommonAdminPublishedData;
-    }, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(collection: string, defaults: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
+    }>, RecipeListItem[]>;
 };
 export declare const createDataSwatchMap: (tableName: string, chunkKey?: string) => {
-    bind: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>() => (_self: SELF, _state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap;
+    bind: () => CommonAdminExpression<{
+        readonly publishedData: Record<string, unknown>;
+    }, SwatchOptionMap>;
 };
+export {};

package/dist/domain/admin-domain/implementation/common-admin-publish.d.ts

@@ -1,6 +1,5 @@
 import type { DomainEntity } from '../../core/index.js';
 import type { PublishedData } from '../__generated/application-types.js';
-import { type AnyDomainEntity } from '../__generated/model/index.js';
 export type CommonAdminPublishedData = PublishedData;
 export declare const CommonAdminPublishedDataSchema: {
     type: "object";
@@ -182,4 +181,4 @@ export declare const CommonAdminPublishedDataSchema: {
     additionalProperties: false;
     required: never[];
 };
-export declare const mapCommonAdminPublishedData: <ENTITIES extends DomainEntity<string>>(entities: ReadonlyArray<ENTITIES | AnyDomainEntity>) => CommonAdminPublishedData;
+export declare const mapCommonAdminPublishedData: (entities: ReadonlyArray<DomainEntity<string>>) => CommonAdminPublishedData;

package/dist/domain/admin-domain/index.js

@@ -1 +1 @@
-import{DomainComponentOpticBuilder as o,RecipeFactoryBuilder as e}from"../core/index.js";import{attributeSelectionComponent as n}from"../system-components/index.js";import{AnyDomainEntity as m,PresetCategory as t,aliases as i}from"./__generated/model/index.js";import{DraftId as a}from"./implementation/common-admin-expressions.js";export{migrateCommonAdminDomain}from"./implementation/common-admin-migrations.js";export*from"./__generated/model/index.js";export*from"./implementation/common-admin-expressions.js";export*from"./implementation/common-admin-publish.js";export*from"./schema/index.js";export const createCommonAdminRecipe=e.forAliases(i).forEntities(m.reflections).withDefaults({}).build();export const attachCommonAdminDomainComponent=o.from(i);export const commonAdminComponents=[attachCommonAdminDomainComponent.withEntity("Preset").withComponent(n,"category").attach((o,e)=>{let n=e.entities.filter(t.is);return null===o.categoryId?{value:a,options:n.map(o=>({value:o.id,label:o.name})).concat([{value:a,label:{$lang:{en:"Draft"}}}])}:{value:o.categoryId,options:n.map(o=>({value:o.id,label:o.name}))}},o=>({categoryId:o.value===a?null:o.value}))];export const configuratorBuilder=null;
+import{DomainComponentOpticBuilder as o,createRecipeFactory as e}from"../core/index.js";import{attributeSelectionComponent as n}from"../system-components/index.js";import{AnyDomainEntity as m,PresetCategory as t,aliases as i}from"./__generated/model/index.js";import{DraftId as a}from"./implementation/common-admin-expressions.js";export{migrateCommonAdminDomain}from"./implementation/common-admin-migrations.js";export*from"./__generated/model/index.js";export*from"./implementation/common-admin-expressions.js";export*from"./implementation/common-admin-publish.js";export*from"./schema/index.js";export const createCommonAdminRecipe=e(i,m.reflections,{});export const attachCommonAdminDomainComponent=o.from(i);export const commonAdminComponents=[attachCommonAdminDomainComponent.withEntity("Preset").withComponent(n,"category").attach((o,e)=>{let n=e.entities.filter(t.is);return null===o.categoryId?{value:a,options:n.map(o=>({value:o.id,label:o.name})).concat([{value:a,label:{$lang:{en:"Draft"}}}])}:{value:o.categoryId,options:n.map(o=>({value:o.id,label:o.name}))}},o=>({categoryId:o.value===a?null:o.value}))];export const configuratorBuilder=null;

package/dist/domain/application/GetApplicationWrapperHandler.d.ts

@@ -3,5 +3,5 @@ import type { $DomainEntity, DomainEntity } from '../core/index.js';
 import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
 import type { ApplicationConfig } from './application-config.js';
 export declare const createGetApplicationWrapperHandler: (fn: (ctx: ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>) => ComponentType) => SystemPhoenixHandlerRegistration<ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>, ComponentType>;
-export type CreateGetApplicationWrapperHandler<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, CHAT_CONTEXT extends Record<string, unknown>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ADMIN_ENTITIES extends DomainEntity<string>, ADMIN_ALLOWED_ROOT_ENTITIES extends ADMIN_ENTITIES, ADMIN_$MAP extends Record<ADMIN_ENTITIES['type'], $DomainEntity<ADMIN_ENTITIES>>, ADMIN_NAVIGATION_STATES extends string, ADMIN_VIEW_STATES extends string> = (fn: (ctx: ApplicationConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>) => ComponentType) => SystemPhoenixHandlerRegistration<ApplicationConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>, ComponentType>;
+export type CreateGetApplicationWrapperHandler = typeof createGetApplicationWrapperHandler;
 export declare const isGetApplicationWrapperHandler: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, CHAT_CONTEXT extends Record<string, unknown>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ADMIN_ENTITIES extends DomainEntity<string>, ADMIN_ALLOWED_ROOT_ENTITIES extends ADMIN_ENTITIES, ADMIN_$MAP extends Record<ADMIN_ENTITIES['type'], $DomainEntity<ADMIN_ENTITIES>>, ADMIN_NAVIGATION_STATES extends string, ADMIN_VIEW_STATES extends string>(handler: HandlerRegistration<ApplicationConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>, ComponentType>) => handler is SystemPhoenixHandlerRegistration<ApplicationConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>, ComponentType>;

package/dist/domain/application/application-config.d.ts

@@ -8,13 +8,15 @@ import type { CellValue } from '@salsita-ai/contracts/webhook';
 import type { AdminIntegrationService } from '#package/react-sdk';
 import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
 import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
-import type { ProjectModule } from '../domain-runtime/index.js';
+import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
 import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
-export type ImportedTransformer<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> = {
+type TransformerExport = ReturnType<TransformerFactory<any, any, any, any, any, any, any>> | RegistrableTransformer<any, any, any, any, any, any, any>;
+/** The transformers one `src/transformers/` file exports, under the name of the file. */
+export type ImportedTransformer = {
     name: string;
-    transformer: ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES> | ReadonlyArray<ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>>;
+    transformer: TransformerExport | ReadonlyArray<TransformerExport>;
 };
 export type SpecTransformer = {
     name: string;
@@ -290,6 +292,8 @@ export interface ApplicationConfig<ENTITIES extends DomainEntity<string>, ALLOWE
     /** The `src/handlers/` and `src/elements/` files as project modules; the runtime spec validates and flattens both. */
     readonly handlers: readonly ProjectModule[];
     readonly elements: readonly ProjectModule[];
+    /** The SDK's default element registrations; a project element with the same name replaces one. */
+    readonly defaultElements?: readonly ElementRegistration[];
     readonly mount: MountConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>;
 }
 export {};

package/dist/domain/application/assistant/assistant-fields.d.ts

@@ -0,0 +1,12 @@
+import type { AssistantDeclaredField, AssistantResolvedField } from './assistant-resolved-manifest.js';
+/** Combines the effective description with allowed string values. */
+export declare const describeAssistantValues: (description: string | undefined, values: readonly string[] | undefined) => string | undefined;
+/** Applies GraphQL field inheritance identically at parse time and after session narrowing. */
+export declare const mergeAssistantFields: (inherited: ReadonlyArray<readonly AssistantDeclaredField[]>, own: readonly AssistantDeclaredField[], ownEnumValues: (source: string) => readonly string[] | undefined, conflict: (name: string, first: string, second: string) => void) => readonly AssistantDeclaredField[];
+/**
+ * The serializable form of a merged field of one alias or type. Merging keeps the inherited entry of
+ * a field declared twice, so the lens tags are taken from `own`, the declarations of that alias or
+ * type itself: each lens condition then comes from its own declaration, at parse time and after
+ * session narrowing alike.
+ */
+export declare const resolveAssistantField: (field: AssistantDeclaredField, own: readonly AssistantDeclaredField[]) => AssistantResolvedField;

package/dist/domain/application/assistant/assistant-fields.js

@@ -0,0 +1 @@
+export const describeAssistantValues=(e,s)=>{if(!s?.length)return e;let t=`One of: ${s.map(e=>`"${e}"`).join(", ")}.`;return e?`${e}${/[.!?]$/.test(e)?"":"."} ${t}`:t};export const mergeAssistantFields=(e,s,t,n)=>{let r=new Map,i=new Set(s);for(let t of[...e.flat(),...s]){let e=r.get(t.name);e?e.source!==t.source?n(t.name,e.source,t.source):r.set(t.name,{...e,...i.has(t)&&t.describedByManifest?{description:t.description,describedByManifest:!0,valueDescription:t.valueDescription}:{}}):r.set(t.name,t)}return[...r.values()].map(e=>{let s=e.enumValues&&t(e.source);return s?{...e,enumValues:s,description:describeAssistantValues(e.valueDescription,s)}:e})};export const resolveAssistantField=(e,s)=>{let t=s.find(s=>s.name===e.name&&s.source===e.source)?.lenses;return{name:e.name,source:e.source,localized:e.localized,type:e.type,...void 0===e.description?{}:{description:e.description},...t?.length?{lenses:t}:{}}};

package/dist/domain/application/assistant/assistant-manifest.d.ts

@@ -47,7 +47,11 @@ export interface AssistantFieldOptions {
  * 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; `actions` maps each custom `Mutation` field to the
- * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
+ * 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;
@@ -60,4 +64,8 @@ export interface AssistantManifest {
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
     readonly actions?: Readonly<Record<string, string>>;
+    readonly lenses?: {
+        readonly declarations: string;
+        readonly definitions: string;
+    };
 }

package/dist/domain/application/assistant/assistant-resolved-manifest.d.ts

@@ -15,7 +15,11 @@ export interface AssistantRelationType {
     readonly target: string;
     readonly cardinality: '1-1' | '0-1' | '0-N' | '1-N';
 }
-/** A field's source and resolved type, carried in the application bundle without GraphQL instances. */
+/**
+ * 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;
@@ -25,6 +29,7 @@ export interface AssistantResolvedField {
     } | AssistantRelationType;
     readonly localized: boolean;
     readonly description?: string;
+    readonly lenses?: readonly string[];
 }
 /** Declared UI state values used to describe the navigation query. */
 export interface AssistantStates {
@@ -34,6 +39,7 @@ export interface AssistantStates {
 }
 /** 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;
@@ -45,6 +51,11 @@ export interface AssistantResolvedManifest {
     readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
     readonly actionFields: readonly AssistantResolvedAction[];
+    /** 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;
+    }>>;
 }
 /** Optional mutation input for one stored field, using its exposed name. */
 export interface AssistantWritableField {
@@ -59,7 +70,8 @@ export interface AssistantWritableType {
     readonly fields: readonly AssistantWritableField[];
 }
 /** Description hints resolved from recipe/option entries; no parse context is retained. */
-export type AssistantResolvedHint = 'sameForAllInstances' | 'constantDuringSession';
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /** Recipe groups and their description hints for one entity type. */
 export interface AssistantResolvedRecipes {
     readonly groups: readonly AssistantRecipeGroup[];
@@ -93,3 +105,27 @@ export interface AssistantResolvedAction {
     }>>;
     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>>;
+}
+/** 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/application/assistant/assistant-resolved-manifest.js

@@ -1 +1 @@
-export{};
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];

package/dist/domain/application/assistant/build-assistant-lenses.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLSchema } from 'graphql';
+import type { AssistantManifest } from './assistant-manifest.js';
+import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+/**
+ * Generates the lens fragments of a resolved manifest for the execution schema compiled from it. A
+ * declared lens becomes one fragment on `AnyDomainEntity`; one that session narrowing left without a
+ * tagged field is dropped, so the agent is never offered a lens that selects nothing. A built-in lens
+ * is present only when the schema has its type. A tagged relation spreads the lens itself in the
+ * declarations, which GraphQL forbids, so the definitions unroll it into copies down to `maxDepth`,
+ * where relations select only `id`. The definitions are checked here against the execution schema,
+ * with every declared lens spread on one entity, so a fault in them fails the build and not the
+ * operations that spread them.
+ */
+export declare const buildAssistantLenses: (resolved: AssistantResolvedManifest, schema: GraphQLSchema) => NonNullable<AssistantManifest['lenses']>;

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -0,0 +1,5 @@
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
+${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
+
+{ ${s} }`),i.filter(t=>t!==e));if(r.length>0)throw Error(`The lens fragments generated from "assistant.lenses" are not valid GraphQL: ${[...new Set(r.map(e=>e.message))].join(" ")}`)}return{declarations:h,definitions:u}};

package/dist/domain/application/assistant/build-assistant-manifest.js

@@ -1 +1 @@
-import{GraphQLBoolean as e,GraphQLID as t,GraphQLInputObjectType as n,GraphQLInterfaceType as i,GraphQLList as r,GraphQLNonNull as s,GraphQLObjectType as o,GraphQLSchema as a,GraphQLString as p,printSchema as d,validateSchema as c}from"graphql";import{GraphQLJSON as l,createAssistantValueType as h}from"./assistant-value-type.js";let y="AnyDomainEntity",w="RootEntity",u=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],g={section:"childRecipes",mutation:"addChild"},f={section:"replaceRecipes",mutation:"replaceEntity"},m=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],b=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},v=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new s(i);case"0-1":return i;case"0-N":case"1-N":return new s(new r(new s(i)))}},j=(e,n,i)=>{let r={id:{type:new s(t),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new s(p),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let t of e)r[t.name]={type:"edge"===t.type.kind?v(t.type,n):h(t.type.type),description:t.description};return r},$=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),O={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},E={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},R=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),k=({section:e},{groups:t,hints:n},{entityType:i,purpose:o,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new s(new r(new s(a))),description:`The recipe groups for ${o} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${R(n,O,i)}`}}},I=({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},{recipeGroup:a,fieldOption:p})=>new o({name:`${e}Meta`,fields:Object.assign(k(g,t,{entityType:e,purpose:"adding children to",recipeGroup:a}),k(f,n,{entityType:e,purpose:"replacing",recipeGroup:a}),...i.map(({options:{edgeName:t,field:n,validate:i,dryRuns:o},hints:a})=>({[t]:{type:new r(new s(p)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${o?"":" Cannot be dry-run."}${R(a,E,e)}`}})))}),T=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=v=>{var O,E,R,k,N;let A,S,D,M,{entityTypes:F,aliases:W,exampleType:C,fields:q,states:x,deletableTypes:G,writableTypes:U,actionFields:K,optionsEdges:P}=v,V=Object.fromEntries(Object.entries(v.childRecipes).map(([e,t])=>[e,t.groups])),z=Object.fromEntries(Object.entries(v.replaceRecipes).map(([e,t])=>[e,t.groups])),Q=new Map,B=new Map,H=new Map,J=e=>{let[t,...n]=Object.entries(W).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?B.get(t):void 0)??H.get(e)??X},L=e=>B.get(e)??J(e),X=new i({name:y,description:"Every entity of the configuration.",fields:()=>j(q[y]??[],L,C)});for(let e of(H.set(y,X),Object.keys(W)))e!==y&&H.set(e,new i({name:e,interfaces:[X],fields:()=>j(q[e]??[],L)}));let Y={};for(let e of F){let t=[y,...Object.entries(W).filter(([t,n])=>t!==y&&n.includes(e)).map(([e])=>e)],n=q[e]??[];Y[e]=$(n),B.set(e,new o({name:e,interfaces:t.flatMap(e=>H.get(e)??[]),fields:()=>{let t=Q.get(e);return{...j(n,L),...t?{meta:{type:new s(t),description:"What can be done to this entity right now."}}:{}}}}))}let Z=(O=()=>J(H.has(w)?w:y),E=()=>J(y),A=new o({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new s(p),description:"Kind of the problem."},entityId:{type:t,description:"The entity the problem is on, when it is on one."},message:{type:p,description:"The problem as the user would be told it."}}}),new o({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new s(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:O(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new s(new r(new s(E()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new s(new r(new s(t))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new s(new r(new s(p))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new s(new r(new s(A))),description:"Why the change cannot be made; empty when ok is true."}})})),_={recipeGroup:(R=[...Object.keys(V).length>0?[g.mutation]:[],...Object.keys(z).length>0?[f.mutation]:[]],S=R.join(" or "),D=new o({name:"Recipe",description:`${R.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${R.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new s(p),description:`Pass to ${S} as recipeKey. Valid only for the listing it came from.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Thumbnail shown to the user."},dryRun:{type:Z,description:"What using this recipe would do. Null when it cannot be tried."}}}),new o({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new s(p),description:`Pass to ${S} as recipeGroupId.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},recipes:{type:new s(new r(new s(D)))}}})),fieldOption:new o({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new s(l),description:"The value to write to the field."},name:{type:p,description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Image shown to the user."},color:{type:p,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:Z,description:"What writing this value would do. Null when it cannot be tried."}}})};for(let e of F){let t=m(v.childRecipes,e)??{groups:[],hints:[]},n=m(v.replaceRecipes,e)??{groups:[],hints:[]},i=m(P,e)??[];(t.groups.length>0||n.groups.length>0||i.length>0)&&Q.set(e,I({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i.map(t=>({...t,hints:(W[w]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints}))},_))}let ee=new a({query:(k=J(H.has(w)?w:y),N=J(y),M=(e=>{let t={};for(let[n,i,r]of u){let o=e[r];o.length>1&&(t[n]={type:new s(p),description:b(i,o)})}if(0!==Object.keys(t).length)return new o({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(x),new o({name:"Query",fields:{root:{type:new s(k),description:"The root entity of the configuration."},entities:{type:new s(new r(N)),args:{ids:{type:new r(new s(t))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new s(N),description:"The selected entity, or the root entity when nothing is selected."},...M?{navigation:{type:new s(M)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:i,childRecipes:a,replaceRecipes:d,actionFields:c,objectTypes:l,anyDomainEntity:y,targetOutputType:w})=>{let u,g;if(0!==e.length||0!==i.length||0!==Object.keys(a).length||0!==Object.keys(d).length||0!==c.length)return new o({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new s(new r(new s(t))),args:{id:{type:new s(t)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=T(a)).length?{}:{addChild:{type:new s(new r(new s(y))),args:{parentId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(g=T(d)).length?{}:{replaceEntity:{type:new s(new r(new s(y))),args:{entityId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${g.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...i.flatMap(e=>{let i=l.get(e.entityType);return i?[(({entityType:e,fields:i},r)=>{let o=Object.fromEntries(i.map(({name:e,type:t,description:n})=>[e,{type:h(t),description:n}]));return{[`modify${e}`]:{type:r,args:{id:{type:new s(t)},delta:{type:new s(new n({name:`${e}Delta`,fields:o}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,i)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new s(new o({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let o=t?new r(new s(i(e))):i(e);return n?o:new s(o)})(t,w):h(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:h(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:G,writableTypes:U,childRecipes:V,replaceRecipes:z,actionFields:K,objectTypes:B,anyDomainEntity:J(y),targetOutputType:L}),types:[...H.values(),...B.values()]}),et=c(ee);if(et.length>0)throw Error(et.map(e=>e.message).join(" "));return{sdl:d(ee),navigationFields:u.filter(([,,e])=>x[e].length>1).map(([e])=>e),fields:Y,deletableTypes:G,writableFields:Object.fromEntries(U.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:V,replaceRecipes:z,fieldOptions:Object.fromEntries(F.flatMap(e=>{let t=m(P,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),actions:Object.fromEntries(K.map(({fieldName:e,actionName:t})=>[e,t]))}};
+import{GraphQLBoolean as e,GraphQLID as t,GraphQLInputObjectType as n,GraphQLInterfaceType as i,GraphQLList as r,GraphQLNonNull as s,GraphQLObjectType as o,GraphQLSchema as a,GraphQLString as p,printSchema as d,validateSchema as c}from"graphql";import{GraphQLJSON as l,createAssistantValueType as h}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as w}from"./create-assistant-execution-schema.js";let u="AnyDomainEntity",m="RootEntity",f=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],g={section:"childRecipes",mutation:"addChild"},b={section:"replaceRecipes",mutation:"replaceEntity"},j=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],v=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},$=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new s(i);case"0-1":return i;case"0-N":case"1-N":return new s(new r(new s(i)))}},O=(e,n,i)=>{let r={id:{type:new s(t),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new s(p),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let t of e)r[t.name]={type:"edge"===t.type.kind?$(t.type,n):h(t.type.type),description:t.description};return r},E=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),R={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},k={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},I=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),T=({section:e},{groups:t,hints:n},{entityType:i,purpose:o,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new s(new r(new s(a))),description:`The recipe groups for ${o} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${I(n,R,i)}`}}},N=({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},{recipeGroup:a,fieldOption:p})=>new o({name:`${e}Meta`,fields:Object.assign(T(g,t,{entityType:e,purpose:"adding children to",recipeGroup:a}),T(b,n,{entityType:e,purpose:"replacing",recipeGroup:a}),...i.map(({options:{edgeName:t,field:n,validate:i,dryRuns:o},hints:a})=>({[t]:{type:new r(new s(p)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${o?"":" Cannot be dry-run."}${I(a,k,e)}`}})))}),A=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=$=>{var R,k,I,T,S;let D,M,F,W,{entityTypes:x,aliases:C,exampleType:q,fields:G,states:U,deletableTypes:K,writableTypes:P,actionFields:V,optionsEdges:z}=$,Q=Object.fromEntries(Object.entries($.childRecipes).map(([e,t])=>[e,t.groups])),B=Object.fromEntries(Object.entries($.replaceRecipes).map(([e,t])=>[e,t.groups])),H=new Map,J=new Map,L=new Map,X=e=>{let[t,...n]=Object.entries(C).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?J.get(t):void 0)??L.get(e)??Z},Y=e=>J.get(e)??X(e),Z=new i({name:u,description:"Every entity of the configuration.",fields:()=>O(G[u]??[],Y,q)});for(let e of(L.set(u,Z),Object.keys(C)))e!==u&&L.set(e,new i({name:e,interfaces:[Z],fields:()=>O(G[e]??[],Y)}));let _={};for(let e of x){let t=[u,...Object.entries(C).filter(([t,n])=>t!==u&&n.includes(e)).map(([e])=>e)],n=G[e]??[];_[e]=E(n),J.set(e,new o({name:e,interfaces:t.flatMap(e=>L.get(e)??[]),fields:()=>{let t=H.get(e);return{...O(n,Y),...t?{meta:{type:new s(t),description:"What can be done to this entity right now."}}:{}}}}))}let ee=(R=()=>X(L.has(m)?m:u),k=()=>X(u),D=new o({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new s(p),description:"Kind of the problem."},entityId:{type:t,description:"The entity the problem is on, when it is on one."},message:{type:p,description:"The problem as the user would be told it."}}}),new o({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new s(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:R(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new s(new r(new s(k()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new s(new r(new s(t))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new s(new r(new s(p))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new s(new r(new s(D))),description:"Why the change cannot be made; empty when ok is true."}})})),et={recipeGroup:(I=[...Object.keys(Q).length>0?[g.mutation]:[],...Object.keys(B).length>0?[b.mutation]:[]],M=I.join(" or "),F=new o({name:"Recipe",description:`${I.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${I.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new s(p),description:`Pass to ${M} as recipeKey. Valid only for the listing it came from.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Thumbnail shown to the user."},dryRun:{type:ee,description:"What using this recipe would do. Null when it cannot be tried."}}}),new o({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new s(p),description:`Pass to ${M} as recipeGroupId.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},recipes:{type:new s(new r(new s(F)))}}})),fieldOption:new o({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new s(l),description:"The value to write to the field."},name:{type:p,description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Image shown to the user."},color:{type:p,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:ee,description:"What writing this value would do. Null when it cannot be tried."}}})};for(let e of x){let t=j($.childRecipes,e)??{groups:[],hints:[]},n=j($.replaceRecipes,e)??{groups:[],hints:[]},i=j(z,e)??[];(t.groups.length>0||n.groups.length>0||i.length>0)&&H.set(e,N({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i.map(t=>({...t,hints:(C[m]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints}))},et))}let en=new a({query:(T=X(L.has(m)?m:u),S=X(u),W=(e=>{let t={};for(let[n,i,r]of f){let o=e[r];o.length>1&&(t[n]={type:new s(p),description:v(i,o)})}if(0!==Object.keys(t).length)return new o({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(U),new o({name:"Query",fields:{root:{type:new s(T),description:"The root entity of the configuration."},entities:{type:new s(new r(S)),args:{ids:{type:new r(new s(t))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new s(S),description:"The selected entity, or the root entity when nothing is selected."},...W?{navigation:{type:new s(W)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:i,childRecipes:a,replaceRecipes:d,actionFields:c,objectTypes:l,anyDomainEntity:y,targetOutputType:w})=>{let u,m;if(0!==e.length||0!==i.length||0!==Object.keys(a).length||0!==Object.keys(d).length||0!==c.length)return new o({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new s(new r(new s(t))),args:{id:{type:new s(t)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=A(a)).length?{}:{addChild:{type:new s(new r(new s(y))),args:{parentId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(m=A(d)).length?{}:{replaceEntity:{type:new s(new r(new s(y))),args:{entityId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${m.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...i.flatMap(e=>{let i=l.get(e.entityType);return i?[(({entityType:e,fields:i},r)=>{let o=Object.fromEntries(i.map(({name:e,type:t,description:n})=>[e,{type:h(t),description:n}]));return{[`modify${e}`]:{type:r,args:{id:{type:new s(t)},delta:{type:new s(new n({name:`${e}Delta`,fields:o}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,i)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new s(new o({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let o=t?new r(new s(i(e))):i(e);return n?o:new s(o)})(t,w):h(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:h(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:P,childRecipes:Q,replaceRecipes:B,actionFields:V,objectTypes:J,anyDomainEntity:X(u),targetOutputType:Y}),types:[...L.values(),...J.values()]}),ei=c(en);if(ei.length>0)throw Error(ei.map(e=>e.message).join(" "));let er=d(en);return{sdl:er,navigationFields:f.filter(([,,e])=>U[e].length>1).map(([e])=>e),fields:_,deletableTypes:K,writableFields:Object.fromEntries(P.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:Q,replaceRecipes:B,fieldOptions:Object.fromEntries(x.flatMap(e=>{let t=j(z,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),actions:Object.fromEntries(V.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y($,w(er))}};

package/dist/domain/application/assistant/create-assistant-execution-schema.d.ts

@@ -0,0 +1,32 @@
+import { type GraphQLSchema } from 'graphql';
+/** One entity type or alias exposing a field, with the field's type as the assistant schema prints it. */
+export interface AssistantFieldExposure {
+    readonly typeName: string;
+    readonly type: string;
+}
+/**
+ * Entity types or aliases expose one field name in shapes no selection can hold together: a single
+ * entity, a list of entities and a plain value cannot share a name. GraphQL rejects every operation
+ * that selects the field on both, and no common type exists to widen them to. `exposures` lists the
+ * aliases and types that declare the field, without the members that only repeat an alias's field.
+ */
+export declare class AssistantFieldClashError extends Error {
+    readonly fieldName: string;
+    readonly exposures: readonly AssistantFieldExposure[];
+    constructor(fieldName: string, exposures: readonly AssistantFieldExposure[]);
+}
+/**
+ * Compiles the schema operations are validated and executed against from the assistant SDL the agent
+ * reads. GraphQL requires fields selected under one name to have the same type, nullability included,
+ * even on entity types that can never be the same entity, so a lens or a hand-written selection that
+ * reaches such a field on two types would be rejected although its result is unambiguous. The
+ * execution schema therefore widens the type of every field name that entity types and aliases
+ * expose with different types, and leaves everything else as it is. It accepts every operation the
+ * SDL accepts and some the SDL would reject; the SDL stays the precise description of the data.
+ * Accepted: a widened field no longer enforces its SDL type on the value it resolves to. A null in a
+ * field the SDL declares non-null is returned as null instead of failing the operation, and a field
+ * widened to `JSON` is returned as it is, without the coercion of its scalar. Values that match their
+ * SDL type, which is every value a valid configuration holds, give the same result. Throws
+ * {@link AssistantFieldClashError} for the shapes nothing can widen.
+ */
+export declare const createAssistantExecutionSchema: (sdl: string) => GraphQLSchema;

package/dist/domain/application/assistant/create-assistant-execution-schema.js

@@ -0,0 +1 @@
+import{Kind as e,buildASTSchema as t,parse as n,print as a}from"graphql";let i="AnyDomainEntity",l="JSON",s=new Set(["Int","Float","String","Boolean","ID",l]);export class AssistantFieldClashError extends Error{fieldName;exposures;constructor(e,t){super(`The field "${e}" cannot be selected on every entity type that has it: ${t.map(({typeName:t,type:n})=>`${t}.${e} is ${n}`).join(", ")}.`),this.fieldName=e,this.exposures=t,this.name="AssistantFieldClashError"}}let r=t=>(t.kind===e.OBJECT_TYPE_DEFINITION||t.kind===e.INTERFACE_TYPE_DEFINITION)&&(t.name.value===i||(t.interfaces??[]).some(({name:e})=>e.value===i)),o=t=>t.kind===e.NON_NULL_TYPE?t.type:t,m=t=>t.kind===e.NAMED_TYPE?t.name.value:m(t.type),u=e=>a(e).replace(m(e),""),p={kind:e.NAMED_TYPE,name:{kind:e.NAME,value:l}},d=(t,n)=>{let i=n.map(({type:e})=>e);if(1===new Set(i.map(e=>a(e))).size)return;let l=i.map(e=>s.has(m(e)));if(l.every(Boolean))return 1===new Set(i.map(e=>a(o(e)))).size?"nullable":"json";if(!l.some(Boolean)){if(1===new Set(i.map(u)).size)return;if(i.every(t=>o(t).kind===e.NAMED_TYPE))return"nullable"}throw new AssistantFieldClashError(t,n.filter(({inherited:e})=>!e).map(({typeName:e,type:t})=>({typeName:e,type:a(t)})))};export const createAssistantExecutionSchema=a=>t((t=>{let n=t.definitions.filter(r),a=(e,t)=>n.some(n=>n.name.value===e&&(n.fields??[]).some(e=>e.name.value===t)),i=new Map;for(let e of n)for(let t of e.fields??[])i.set(t.name.value,[...i.get(t.name.value)??[],{typeName:e.name.value,type:t.type,inherited:(e.interfaces??[]).some(({name:e})=>a(e.value,t.name.value))}]);let s=new Map;for(let[e,t]of i){let n=d(e,t);n&&s.set(e,n)}let m=e=>{let t=s.get(e.name.value);return t?{...e,type:"json"===t?p:o(e.type)}:e},u=t.definitions.map(e=>r(e)?{...e,fields:e.fields?.map(m)}:e),f=u.some(t=>t.kind===e.SCALAR_TYPE_DEFINITION&&t.name.value===l),E=[...s.values()].includes("json");return{...t,definitions:E&&!f?[...u,{kind:e.SCALAR_TYPE_DEFINITION,name:{kind:e.NAME,value:l}}]:u}})(n(a)));

package/dist/domain/application/assistant/generate-assistant-prompt.js

@@ -1 +1 @@
-export const generateAssistantPrompt=e=>{let t=Object.values(e.childRecipes??{}).some(e=>e.length>0),a=Object.values(e.replaceRecipes??{}).some(e=>e.length>0),n=Object.values(e.fieldOptions??{}).some(e=>e.length>0),s=Object.keys(e.actions??{}).length>0,i=(e.deletableTypes?.length??0)>0||Object.values(e.writableFields??{}).some(e=>Object.keys(e).length>0)||t||a||s,o=t||a||n,h=[...t?["`childRecipes` is what can be added to it"]:[],...a?["`replaceRecipes` what it can be replaced with"]:[],...n?["`<field>Options` the values a field accepts"]:[]],r=["`selected`",...(e.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...i?[`- Use a mutation inside \`query\` to answer a what-if about a change ${o?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...i?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...s?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...o?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${h.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...t||a?["recipes"]:[],...n?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${r} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...i?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(e.deletableTypes?.length??0)>0||a?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${i?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."]].map(e=>e.join("\n")).join("\n\n")};
+export const generateAssistantPrompt=e=>{let t=Object.values(e.childRecipes??{}).some(e=>e.length>0),a=Object.values(e.replaceRecipes??{}).some(e=>e.length>0),n=Object.values(e.fieldOptions??{}).some(e=>e.length>0),s=Object.keys(e.actions??{}).length>0,i=(e.deletableTypes?.length??0)>0||Object.values(e.writableFields??{}).some(e=>Object.keys(e).length>0)||t||a||s,o=t||a||n,r=[...t?["`childRecipes` is what can be added to it"]:[],...a?["`replaceRecipes` what it can be replaced with"]:[],...n?["`<field>Options` the values a field accepts"]:[]],h=["`selected`",...(e.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...i?[`- Use a mutation inside \`query\` to answer a what-if about a change ${o?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...i?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...s?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...o?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${r.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...t||a?["recipes"]:[],...n?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${h} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...i?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(e.deletableTypes?.length??0)>0||a?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${i?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Entity links","- When you name an entity the user may want to find, write it as a Markdown link whose target is `entity:` and its id: `[the corner cabinet](entity:<id>)`. The user sees only the text; the id is never shown.","- Link only entities that exist in the configuration now, never one created only inside `query`."],...e.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",e.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};

package/dist/domain/application/assistant/index.d.ts

@@ -1,4 +1,9 @@
-export type { AssistantResolvedManifest, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
+export { ASSISTANT_HINTS } from './assistant-resolved-manifest.js';
+export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
 export { buildAssistantManifest } from './build-assistant-manifest.js';
+export type { AssistantFieldExposure } from './create-assistant-execution-schema.js';
+export { AssistantFieldClashError, createAssistantExecutionSchema } from './create-assistant-execution-schema.js';
 export type { AssistantFieldSource, AssistantRecipeGroup, AssistantFieldOptions, AssistantManifest, } from './assistant-manifest.js';
 export { generateAssistantPrompt } from './generate-assistant-prompt.js';
+export * from './session-setup/index.js';
+export { describeAssistantValues, mergeAssistantFields, resolveAssistantField } from './assistant-fields.js';

package/dist/domain/application/assistant/index.js

@@ -1 +1 @@
-export{buildAssistantManifest}from"./build-assistant-manifest.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";
+export{ASSISTANT_HINTS}from"./assistant-resolved-manifest.js";export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";

package/dist/domain/application/assistant/session-setup/AssistantSetupHandler.d.ts

@@ -0,0 +1,20 @@
+import type { AccessLevel, SessionRole } from '@salsita-ai/contracts/api';
+import type { $DomainEntity, ActionTypes, DomainEntity } from '../../../core/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../../../domain-runtime/index.js';
+import type { AssistantSetupManifest } from './assistant-setup-manifest.js';
+/** Project-defined session inputs used by browser execution and the assistant setup webhook. */
+export interface AssistantSetupInputs<SESSION_DATA> {
+    readonly role: SessionRole;
+    readonly sessionData: SESSION_DATA;
+    readonly access: AccessLevel;
+}
+/** Arguments carried by the standard single-props system-handler registration. */
+export interface AssistantSetupHandlerProps<SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> {
+    readonly manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>;
+    readonly inputs: AssistantSetupInputs<SESSION_DATA>;
+}
+/** A project setup handler is synchronous, pure and deterministic. Return null to disable the assistant. */
+export type TypedCreateAssistantSetupHandler<SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> = (fn: (manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>, inputs: AssistantSetupInputs<SESSION_DATA>) => AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null) => SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<SESSION_DATA, ENTITIES, $MAP, ACTIONS>, AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null>;
+export declare const createAssistantSetupHandler: <SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes>(fn: (manifest: AssistantSetupManifest<ENTITIES, $MAP, ACTIONS>, inputs: AssistantSetupInputs<SESSION_DATA>) => AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null) => SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<SESSION_DATA, ENTITIES, $MAP, ACTIONS>, AssistantSetupManifest<ENTITIES, $MAP, ACTIONS> | null>;
+export declare const createAssistantSetupHandlerFactory: <SESSION_DATA, ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes>() => TypedCreateAssistantSetupHandler<SESSION_DATA, ENTITIES, $MAP, ACTIONS>;
+export declare const isAssistantSetupHandler: (handler: Pick<HandlerRegistration<never, unknown>, 'type' | 'name'>) => handler is SystemPhoenixHandlerRegistration<AssistantSetupHandlerProps<Record<string, unknown>>, AssistantSetupManifest | null>;

package/dist/domain/application/assistant/session-setup/AssistantSetupHandler.js

@@ -0,0 +1 @@
+export const createAssistantSetupHandler=t=>({type:"system",name:"AssistantSetupHandler",handler:()=>({handler:({manifest:e,inputs:s})=>t(e,s)})});export const createAssistantSetupHandlerFactory=()=>createAssistantSetupHandler;export const isAssistantSetupHandler=t=>"system"===t.type&&"AssistantSetupHandler"===t.name;

package/dist/domain/application/assistant/session-setup/apply-assistant-setup.d.ts

@@ -0,0 +1,10 @@
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+import { type AssistantSetupManifest, type AssistantSetupSettings } from './assistant-setup-manifest.js';
+/** A project returned a setup that broadens or invalidates its declared whitelist. */
+export declare class AssistantSetupError extends Error {
+    constructor(key: string, reason: string);
+}
+export declare const applyAssistantSetup: (resolved: AssistantResolvedManifest, settings: AssistantSetupSettings | null, returned: AssistantSetupManifest | null) => {
+    readonly resolved: AssistantResolvedManifest;
+    readonly settings: AssistantSetupSettings | null;
+} | null;

package/dist/domain/application/assistant/session-setup/apply-assistant-setup.js

@@ -0,0 +1 @@
+import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as t,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";import{describeAssistantValues as s,mergeAssistantFields as n,resolveAssistantField as o}from"../assistant-fields.js";import{ASSISTANT_HINTS as a}from"../assistant-resolved-manifest.js";import{projectAssistantSetupManifest as r}from"./assistant-setup-manifest.js";export class AssistantSetupError extends Error{constructor(e,t){super(`${e}: ${t}`),this.name="AssistantSetupError"}}let l=(e,t)=>{throw new AssistantSetupError(e,t)},p=(e,t,i)=>{for(let s of((null===t||"object"!=typeof t||Array.isArray(t))&&l(i,"expected an object; omit an entry to remove it"),Object.keys(t)))Object.hasOwn(e,s)||l(`${i}.${s}`,"not declared in the spec; remove this key")},d=(e,t)=>Object.hasOwn(e,t)?e[t]:void 0,c=(e,t,i)=>(void 0!==e&&"string"!=typeof e&&l(`${i}.description`,"expected a string"),e??t),u=(e,t,i)=>(void 0!==e&&!1!==e&&l(`${i}.allowDryRuns`,"can only disable dry-runs; omit this flag or set false"),!1!==e&&t);export const applyAssistantSetup=(f,m,b)=>{if(null===b)return null;let y=r(f,m),g=f.declarations;p({entities:{},deletable:{},writable:{},childRecipes:{},replaceRecipes:{},actions:{},instructions:"",ai:{}},b,"assistant"),p(y.entities,b.entities,"assistant.entities"),p(y.deletable,b.deletable,"assistant.deletable"),p(y.writable,b.writable,"assistant.writable"),p(y.actions,b.actions,"assistant.actions");let v=Object.fromEntries(Object.entries(b.entities).map(([e,t])=>{let i=`assistant.entities.${e}`;p(y.entities[e],t,i);let n=g.entities[e];return[e,Object.entries(t).map(([e,t])=>{p({description:""},t,`${i}.${e}`);let o=n.find(t=>t.source===e),a=c(t.description,o.valueDescription,`${i}.${e}`);return{...o,valueDescription:a,description:s(a,o.enumValues),describedByManifest:void 0!==t.description||o.describedByManifest}})]})),w=(e,t,i)=>l(`assistant.entities.${e}`,`conflicting sources ${t} and ${i}`),$=n([],d(v,"AnyDomainEntity")??[],()=>void 0,w),h=new Map([["AnyDomainEntity",$]]);for(let e of Object.keys(f.aliases))"AnyDomainEntity"!==e&&h.set(e,n([$],d(v,e)??[],()=>void 0,w));for(let e of f.entityTypes){let t=Object.entries(f.aliases).filter(([t,i])=>"AnyDomainEntity"!==t&&i.includes(e));h.set(e,n([$,...t.map(([e])=>h.get(e)??[])],d(v,e)??[],t=>g.enumValues[e]?.[t],w))}let j=Object.fromEntries([...h].map(([e,t])=>[e,t.map(t=>o(t,d(v,e)??[]))])),O=new Map,x=new Map;for(let[e,t]of Object.entries(b.writable)){let i=`assistant.writable.${e}`;for(let[s,n]of(p(y.writable[e],t,i),Object.entries(t))){let t=`${i}.${s}`,o=g.writable[e][s];for(let[e,{field:i,options:a,exposedDescription:r}]of(p(Object.values(o.members).some(e=>e.options)?{options:{}}:{},n,t),void 0!==n.options&&(p({validate:!0,allowDryRuns:!1},n.options,`${t}.options`),void 0!==n.options.validate&&!0!==n.options.validate&&l(`${t}.options.validate`,"can only enable validation; omit this flag or set true"),u(n.options.allowDryRuns,!0,`${t}.options`)),Object.entries(o.members))){let p=d(v,e)?.find(e=>e.source===s)?.name??h.get(e)?.find(e=>e.source===s)?.name,c=p??s;void 0===p&&h.get(e)?.some(e=>e.name===s&&e.source!==s)&&l(t,`narrowing leaves ${e}.${s} bound to another read field; retain its original exposure or remove this writable property`);let f=O.get(e)??new Map;if([...f.values()].some(e=>e.name===c&&e.property!==s)&&l(t,`narrowing maps multiple writable properties to ${e}.${c}; retain their original exposures or remove the conflicting property`),f.has(s)||f.set(s,{...i,name:c,...void 0===p?{}:{description:r}}),O.set(e,f),a){let i=o.defaultOptionsName?`${c}Options`:a.options.edgeName;x.get(e)?.some(e=>e.options.edgeName===i||e.options.field===c)&&l(`${t}.options`,`narrowing duplicates options edge ${e}.${i}; retain the original field exposures or remove the conflicting writable declaration`),x.set(e,[...x.get(e)??[],{hints:a.hints,options:{...a.options,field:c,edgeName:i,validate:n.options?.validate??a.options.validate,dryRuns:u(n.options?.allowDryRuns,a.options.dryRuns,`${t}.options`)}}])}}}}for(let[e,t]of Object.entries(f.optionsEdges))for(let i of t){let t=f.writableTypes.find(t=>t.entityType===e)?.fields.find(e=>e.name===i.options.field)?.property;if(i.options.validate&&t&&O.get(e)?.has(t)&&!x.get(e)?.some(i=>i.options.field===O.get(e)?.get(t)?.name&&i.options.validate)){let i=Object.keys(b.writable).find(i=>Object.hasOwn(b.writable[i],t)&&g.writable[i]?.[t]?.members[e]);l(`assistant.writable.${i}.${t}`,`cannot remove declared validation while another declaration keeps ${e}.${t} writable; remove all writable declarations for it`)}}let R=e=>{p(y[e],b[e],`assistant.${e}`);let t=new Map;for(let[i,s]of Object.entries(b[e])){let n=`assistant.${e}.${i}`;p({groups:{}},s,n),p(y[e][i].groups,s.groups,`${n}.groups`);let o=g[e][i],r=Object.entries(s.groups).map(([e,t])=>{let i=`${n}.groups.${e}`;p({description:"",allowDryRuns:!1},t,i);let s=o.groups.find(t=>t.instanceName===e);return{...s,description:c(t.description,s.description,i),dryRuns:u(t.allowDryRuns,s.dryRuns,i)}});for(let e of f.entityTypes.includes(i)?[i]:f.aliases[i]??[]){let i=t.get(e);t.set(e,{groups:[...i?.groups??[],...r],hints:a.filter(e=>o.hints.includes(e)||i?.hints.includes(e))})}}return Object.fromEntries(f.entityTypes.flatMap(e=>{let i=t.get(e);return i?.groups.length?[[e,i]]:[]}))};for(let[e,t]of Object.entries(b.deletable))p({},t,`assistant.deletable.${e}`);let E=new Set(Object.keys(b.deletable).flatMap(e=>f.entityTypes.includes(e)?[e]:f.aliases[e]??[])),T=f.actionFields.flatMap(e=>{let t=d(b.actions,e.actionName);if(void 0===t)return[];let i=`assistant.actions.${e.actionName}`;return p({description:""},t,i),[{...e,description:c(t.description,e.description,i)}]}),D=m;if(m){void 0!==b.ai&&p({...m.ai,maxThreadSize:void 0},b.ai,"assistant.ai");let s={...m.ai,...Object.fromEntries(Object.entries(b.ai??{}).filter(([,e])=>void 0!==e))};e.includes(s.provider)&&t.includes(s.model)&&i.includes(s.reasoning)||l("assistant.ai","expected a supported provider, model and reasoning level"),void 0!==s.maxThreadSize&&(!Number.isInteger(s.maxThreadSize)||s.maxThreadSize<=0)&&l("assistant.ai.maxThreadSize","expected a positive whole number of input tokens"),void 0!==b.instructions&&"string"!=typeof b.instructions&&l("assistant.instructions","expected a string"),D={instructions:""===b.instructions?null:b.instructions??m.instructions,ai:s}}return{resolved:{...f,fields:j,deletableTypes:f.entityTypes.filter(e=>E.has(e)),writableTypes:f.entityTypes.flatMap(e=>{let t=[...O.get(e)?.values()??[]];return t.length?[{entityType:e,fields:t}]:[]}),optionsEdges:Object.fromEntries(x),childRecipes:R("childRecipes"),replaceRecipes:R("replaceRecipes"),actionFields:T},settings:D}};

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.d.ts

@@ -0,0 +1,48 @@
+import type { AssistantAiSettings } from '@salsita-ai/contracts/assistant';
+import type { $DomainEntity, ActionTypes, DomainEntity } from '../../../core/index.js';
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+/** Declaration-shaped whitelist a project may narrow; bindings and hints stay internal. */
+export interface AssistantSetupManifest<ENTITIES extends DomainEntity<string> = DomainEntity<string>, $MAP extends Record<keyof $MAP, $DomainEntity<ENTITIES>> = Record<string, $DomainEntity<ENTITIES>>, ACTIONS extends ActionTypes = ActionTypes> {
+    readonly entities: string extends keyof $MAP ? Readonly<Record<string, Readonly<Record<string, AssistantSetupField>>>> : {
+        readonly [TYPE in keyof $MAP]?: Readonly<Partial<Record<Exclude<keyof $MAP[TYPE], 'id' | 'type' | '_raw' | 'meta'>, AssistantSetupField>>>;
+    };
+    readonly deletable: Readonly<Record<string, Readonly<Record<never, never>>>>;
+    readonly writable: string extends ENTITIES['type'] ? Readonly<Record<string, Readonly<Record<string, AssistantSetupWritableField>>>> : {
+        readonly [TYPE in keyof $MAP]?: Readonly<Partial<Record<Exclude<keyof $MAP[TYPE]['_raw'], 'id' | 'type'>, AssistantSetupWritableField>>>;
+    };
+    readonly childRecipes: Readonly<Record<string, AssistantSetupRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantSetupRecipes>>;
+    readonly actions: {
+        readonly [ACTION in keyof ACTIONS]?: AssistantSetupField;
+    };
+    readonly instructions?: string;
+    readonly ai?: Partial<AssistantAiSettings>;
+}
+/** Optional description override; omission preserves the declaration's effective text. */
+export interface AssistantSetupField {
+    readonly description?: string;
+}
+/** Only stricter validation and disabled dry-runs are configurable. */
+export interface AssistantSetupOptions {
+    readonly validate?: true;
+    readonly allowDryRuns?: false;
+}
+/** Keeping a property also keeps its declared options binding and baseline restrictions. */
+export interface AssistantSetupWritableField {
+    readonly options?: AssistantSetupOptions;
+}
+/** A recipe group's editable description and dry-run restriction. */
+export interface AssistantSetupRecipeGroup {
+    readonly description?: string;
+    readonly allowDryRuns?: false;
+}
+/** Only explicitly declared groups appear, under their original entity or alias key. */
+export interface AssistantSetupRecipes {
+    readonly groups: Readonly<Record<string, AssistantSetupRecipeGroup>>;
+}
+/** Server settings baseline, kept out of the browser spec. */
+export interface AssistantSetupSettings {
+    readonly instructions?: string | null;
+    readonly ai: AssistantAiSettings;
+}
+export declare const projectAssistantSetupManifest: (resolved: AssistantResolvedManifest, settings: AssistantSetupSettings | null) => AssistantSetupManifest;

package/dist/domain/application/assistant/session-setup/assistant-setup-manifest.js

@@ -0,0 +1 @@
+export const projectAssistantSetupManifest=(e,i)=>{let t=e=>Object.fromEntries(Object.entries(e).map(([e,i])=>[e,{groups:Object.fromEntries(i.groups.map(e=>[e.instanceName,{...void 0===e.description?{}:{description:e.description},...!e.dryRuns?{allowDryRuns:!1}:{}}]))}])),s=e.declarations;return{entities:Object.fromEntries(Object.entries(s.entities).map(([e,i])=>[e,Object.fromEntries(i.map(e=>[e.source,{...!e.describedByManifest||void 0===e.valueDescription?{}:{description:e.valueDescription}}]))])),deletable:Object.fromEntries(s.deletable.map(e=>[e,{}])),writable:Object.fromEntries(Object.entries(s.writable).map(([e,i])=>[e,Object.fromEntries(Object.entries(i).map(([e,i])=>{let t=Object.values(i.members).find(e=>e.options)?.options?.options;return[e,t?{options:{...t.validate?{validate:!0}:{},...!t.dryRuns?{allowDryRuns:!1}:{}}}:{}]}))])),childRecipes:t(s.childRecipes),replaceRecipes:t(s.replaceRecipes),actions:Object.fromEntries(e.actionFields.map(e=>[e.actionName,void 0===e.description?{}:{description:e.description}])),...i?{instructions:i.instructions??void 0,ai:{...i.ai}}:{}}};

package/dist/domain/application/assistant/session-setup/create-session-assistant.d.ts

@@ -0,0 +1,15 @@
+import type { AssistantManifest } from '../assistant-manifest.js';
+import type { AssistantResolvedManifest } from '../assistant-resolved-manifest.js';
+import type { AssistantSetupHandlerProps, TypedCreateAssistantSetupHandler } from './AssistantSetupHandler.js';
+/** Session-derived browser manifest; a rejected setup retains its error without exposing the baseline. */
+export interface SessionAssistantSetup {
+    readonly manifest: AssistantManifest | null;
+    readonly error: Error | null;
+}
+interface Props {
+    readonly resolved: AssistantResolvedManifest | null;
+    readonly handler: ReturnType<TypedCreateAssistantSetupHandler<Record<string, unknown>>> | undefined;
+    readonly inputs: AssistantSetupHandlerProps<Record<string, unknown>>['inputs'] | null;
+}
+export declare const createSessionAssistant: ({ resolved, handler, inputs }: Props) => SessionAssistantSetup;
+export {};