akanjs 3.0.0-alpha.11 → 3.0.0-alpha.13

package/store/agent/AgentBridge.ts

@@ -0,0 +1,281 @@
+import { DataList } from "akanjs/base";
+import { Translator } from "akanjs/client";
+import { parseAkanI18nEnv } from "akanjs/common";
+import { ConstantRegistry, type MaskModel, mask } from "akanjs/constant";
+import { FetchClient } from "akanjs/fetch";
+import type { AgentRefusal, AgentUndescribed, JsonSchema, SerializedArg, SerializedSignal } from "akanjs/signal";
+
+import { JsonSchemaBuilder } from "../../signal/schema/JsonSchemaBuilder";
+import type { StoreInstance } from "../storeInstance";
+import { StoreRegistry } from "../storeRegistry";
+import { StoreCatalogue } from "./StoreCatalogue";
+import type { SerializedStore, SerializedStoreAction, SerializedStoreState, StoreActionEffect } from "./types";
+
+export interface AgentTool {
+  name: string;
+  title?: string;
+  description?: string;
+  /** One flat named object, the shape MCP publishes. The bridge maps it onto the action's positional parameters. */
+  inputSchema: JsonSchema;
+  effect: StoreActionEffect;
+}
+
+/** One call the agent made, in the order it made them. */
+export interface AgentCall {
+  name: string;
+  args: Record<string, unknown>;
+  at: Date;
+  error?: string;
+}
+
+export interface AgentBridgeOptions {
+  /** Resolves a dictionary key to its text. Defaults to the seeded `Translator` in the active locale. */
+  resolveDescription?: (key: string) => string | undefined;
+}
+
+/**
+ * What an in-page agent may do to the app the user is looking at.
+ *
+ * Every call goes through `st.do`, which is the same single dispatch point a click goes through — so the agent
+ * cannot reach past what the UI already lets this user do, the app re-renders from the write, and the user watches
+ * the result rather than being told about it. That is why the exposure default here is the opposite of the MCP
+ * catalogue's: an external agent's `tools/list` is an attack surface built out of names the operator never chose to
+ * publish, while this one is the user's own session, under their own credential, with them watching.
+ *
+ * It is deliberately not an agent. There is no model, no provider, and no key here — an app wires whichever it uses
+ * to `tools`, `call`, and `read`. The framework's half is the catalogue, the argument checking, the masking, and the
+ * transcript; the conversation is the app's.
+ */
+export class AgentBridge {
+  readonly tools: AgentTool[];
+  readonly refusals: AgentRefusal[];
+  /** Published entries with no words an author wrote. What a source scanner cannot see, per `AgentCatalogue`. */
+  readonly undescribed: AgentUndescribed[] = [];
+
+  readonly #instance: StoreInstance;
+  readonly #store: SerializedStore;
+  readonly #options: AgentBridgeOptions;
+  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/" });
+  readonly #byName = new Map<string, SerializedStoreAction>();
+  readonly #calls: AgentCall[] = [];
+
+  /**
+   * The bridge for the app running in this process: the one store every `st.do` goes through, and every signal any
+   * client has applied. An app needs no arguments to reach its own agent surface.
+   */
+  static of(options: AgentBridgeOptions = {}) {
+    return new AgentBridge(StoreRegistry.instance, FetchClient.sharedSerializedSignal, options);
+  }
+
+  constructor(
+    instance: StoreInstance,
+    serializedSignal: Record<string, SerializedSignal>,
+    options: AgentBridgeOptions = {},
+  ) {
+    this.#instance = instance;
+    this.#options = options;
+    const catalogue = new StoreCatalogue(instance, serializedSignal);
+    this.#store = catalogue.store;
+    this.refusals = catalogue.refusals;
+    for (const [name, action] of Object.entries(this.#store.action)) this.#byName.set(name, action);
+    this.tools = Object.entries(this.#store.action).map(([name, action]) => this.#tool(name, action));
+  }
+
+  get state(): { [key: string]: SerializedStoreState } {
+    return this.#store.state;
+  }
+
+  get transcript(): readonly AgentCall[] {
+    return this.#calls;
+  }
+
+  subscribe(listener: () => void) {
+    return this.#instance.subscribe(listener);
+  }
+
+  /**
+   * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
+   *
+   * Masking is not optional here even though the data mostly came from the server already masked: `<model>Form`
+   * holds what the *user* typed, credentials included, and an in-page agent ships what it reads to a remote model.
+   * The mask is by the declared model rather than by the value's class, because `immerify` copies a form into a
+   * plain object and the class is gone by the time anyone can ask.
+   */
+  read(key: string): unknown {
+    const entry = this.#store.state[key];
+    if (!entry) throw new Error(`Unknown state key: ${key}`);
+    const value = AgentBridge.#unwrap(this.#instance.get()[key]);
+    if (entry.refName && entry.modelType) {
+      const model = ConstantRegistry.getModelRef(entry.refName, entry.modelType) as MaskModel;
+      return mask(model, value);
+    }
+    if (AgentBridge.#isPlainValue(value)) return value;
+    throw new Error(
+      `State key "${key}" holds an object that belongs to no model, so there is nothing to mask it by and it is not published. Read the model's own keys instead.`,
+    );
+  }
+
+  /**
+   * Dispatches through `st.do`, so what happens is what happens when the user clicks.
+   *
+   * Arguments arrive named and are mapped onto the action's parameters in declared order. An omitted optional one
+   * becomes `null`, which is what the slice query builders already expect; an omitted required one is refused,
+   * because the alternative is a call that writes `undefined` into state and reports success.
+   */
+  async call(name: string, args: Record<string, unknown> = {}) {
+    const action = this.#byName.get(name);
+    if (!action) throw new Error(`Unknown action: ${name}`);
+
+    const record: AgentCall = { name, args, at: new Date() };
+    this.#calls.push(record);
+    try {
+      const positional = action.args.map((arg) => this.#value(name, arg, args));
+      await this.#instance.do[name]?.(...positional);
+    } catch (error) {
+      record.error = error instanceof Error ? error.message : String(error);
+      throw error;
+    }
+  }
+
+  #value(name: string, arg: SerializedArg, args: Record<string, unknown>) {
+    if (!(arg.name in args) || args[arg.name] === undefined) {
+      if (arg.nullable || arg.type === "search") return null;
+      throw new Error(`Missing argument "${arg.name}" for ${name}.`);
+    }
+    return AgentBridge.#checked(name, arg, args[arg.name]);
+  }
+
+  /**
+   * Checks a value against what the argument declared, one level of array included.
+   *
+   * `st.do` accepts anything — it is a rest wrapper — so without this a string where an `Int` belongs is written
+   * into state and rendered, and the agent is told the call succeeded. A model argument is checked only for being
+   * an object: the published schema describes its fields and the endpoint validates them server-side.
+   */
+  static #checked(name: string, arg: SerializedArg, value: unknown): unknown {
+    const depth = arg.arrDepth ?? 0;
+    if (depth) {
+      if (!Array.isArray(value)) throw new Error(`Argument "${arg.name}" of ${name} must be an array.`);
+      return value.map((item) => AgentBridge.#checked(name, { ...arg, arrDepth: depth - 1 }, item));
+    }
+    if (value === null) return null;
+    if (arg.enum) return AgentBridge.#checkedEnum(name, arg, value);
+    switch (arg.refName) {
+      case "String":
+      case "ID":
+        return AgentBridge.#assertType(name, arg, value, "string");
+      case "Int":
+        if (!Number.isInteger(value)) throw new Error(`Argument "${arg.name}" of ${name} must be a whole number.`);
+        return value;
+      case "Float":
+        if (typeof value !== "number" || !Number.isFinite(value))
+          throw new Error(`Argument "${arg.name}" of ${name} must be a finite number.`);
+        return value;
+      case "Boolean":
+        return AgentBridge.#assertType(name, arg, value, "boolean");
+      case "Date":
+        return AgentBridge.#checkedDate(name, arg, value);
+      default:
+        if (typeof value !== "object") throw new Error(`Argument "${arg.name}" of ${name} must be an object.`);
+        return value;
+    }
+  }
+
+  static #assertType(name: string, arg: SerializedArg, value: unknown, type: "string" | "boolean") {
+    if (typeof value !== type) throw new Error(`Argument "${arg.name}" of ${name} must be a ${type}.`);
+    return value;
+  }
+
+  static #checkedEnum(name: string, arg: SerializedArg, value: unknown) {
+    const values = arg.enum ? ConstantRegistry.enum.get(arg.enum)?.values : undefined;
+    if (!values) return value;
+    if (!values.includes(value as never))
+      throw new Error(`Argument "${arg.name}" of ${name} must be one of: ${[...values].join(", ")}.`);
+    return value;
+  }
+
+  /** An agent has no `Date`, so an ISO string is what it sends. Anything unparseable is refused rather than `Invalid Date`. */
+  static #checkedDate(name: string, arg: SerializedArg, value: unknown) {
+    if (value instanceof Date) return value;
+    const parsed = typeof value === "string" ? new Date(value) : null;
+    if (!parsed || Number.isNaN(parsed.getTime()))
+      throw new Error(`Argument "${arg.name}" of ${name} must be an ISO 8601 date string.`);
+    return parsed;
+  }
+
+  #tool(name: string, action: SerializedStoreAction): AgentTool {
+    const properties = Object.fromEntries(action.args.map((arg) => [arg.name, this.#argSchema(arg)]));
+    const required = action.args.filter((arg) => !arg.nullable && arg.type !== "search").map((arg) => arg.name);
+    const defs = this.#schema.referencedSchemas(properties);
+    return {
+      name,
+      ...this.#texts(name, action),
+      inputSchema: {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+        ...(Object.keys(defs).length ? { $defs: defs } : {}),
+      },
+      effect: action.effect,
+    };
+  }
+
+  #argSchema(arg: SerializedArg) {
+    return {
+      ...this.#schema.arg(arg),
+      ...(arg.example !== undefined ? { examples: [arg.example] } : {}),
+    };
+  }
+
+  /**
+   * The words an agent picks the action by, from the one channel this codebase has for them.
+   *
+   * Order matters and follows the same leniency the MCP catalogue uses for a slice: an action's own `.store()`
+   * entry, then the endpoint it is named after — which is right rather than merely adequate, because the house
+   * rule makes `st.do.X` and `fetch.X` the same verb — then, on a field setter, the field's own label. Only what
+   * reaches none of the three is recorded as undescribed.
+   */
+  #texts(name: string, action: SerializedStoreAction) {
+    const { refName, endpoint, field } = action;
+    const keys = refName
+      ? [
+          `${refName}.store.${name}`,
+          ...(endpoint ? [`${refName}.signal.${endpoint}`] : []),
+          ...(field ? [`${refName}.${field}`] : []),
+        ]
+      : [];
+    for (const key of keys) {
+      const title = this.#text(key);
+      const description = this.#text(`${key}.desc`);
+      if (title || description) return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
+    }
+    this.undescribed.push({
+      key: name,
+      reason: refName
+        ? `neither \`${refName}.store.${name}\` nor anything it inherits from has text, so an agent has the name and nothing else.`
+        : "it belongs to no model, so there is no dictionary node its text could be written in.",
+    });
+    return {};
+  }
+
+  #text(key: string) {
+    if (this.#options.resolveDescription) return this.#options.resolveDescription(key);
+    const locale = Translator.getActiveLocale() ?? parseAkanI18nEnv().defaultLocale;
+    const text = Translator.translateByLocale(locale, key);
+    
+    return text === key ? undefined : text;
+  }
+
+  static #unwrap(value: unknown) {
+    return value instanceof DataList ? value.values : value;
+  }
+
+  /** True when nothing inside could be carrying a model's fields, so there is nothing a mask would have to strip. */
+  static #isPlainValue(value: unknown): boolean {
+    if (value === null || value === undefined) return true;
+    if (Array.isArray(value)) return value.every((item) => AgentBridge.#isPlainValue(item));
+    if (value instanceof Date) return true;
+    return typeof value !== "object";
+  }
+}

package/store/agent/StoreCatalogue.ts

@@ -0,0 +1,296 @@
+import { type Cls, FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { capitalize } from "akanjs/common";
+import { ConstantRegistry } from "akanjs/constant";
+import type { AgentRefusal, SerializedArg, SerializedSignal } from "akanjs/signal";
+
+import { AgentCatalogue } from "../../signal/agent/AgentCatalogue";
+import { databaseStateModelTypes, databaseStateNames } from "../databaseStateNames";
+import { formSetterNames } from "../formSetterNames";
+import type { SliceActionKey } from "../sliceRole";
+import type { SliceStateKey } from "../state";
+import type { StoreInstance } from "../storeInstance";
+import type { SerializedStore, SerializedStoreAction, SerializedStoreState } from "./types";
+
+/** A model field as the catalogue reads it. The parts of `FieldProps` a store setter's argument comes from. */
+interface CatalogueField {
+  fieldType?: string;
+  isClass?: boolean;
+  isMap?: boolean;
+  isArray?: boolean;
+  arrDepth?: number;
+  modelRef?: Cls;
+  enum?: { refName: string };
+  example?: unknown;
+}
+
+/** What each generated slice action takes, in the same terms an endpoint states its arguments. */
+const sliceActionArgs: {
+  [key in SliceActionKey]: { effect: "state" | "query"; args: "slice" | SerializedArg[] };
+} = {
+  initModel: { effect: "query", args: "slice" },
+  refreshModel: { effect: "query", args: [] },
+  
+  selectModel: { effect: "state", args: [] },
+  setPageOfModel: { effect: "query", args: [{ type: "param", name: "page", refName: "Int" }] },
+  addPageOfModel: { effect: "query", args: [{ type: "param", name: "page", refName: "Int" }] },
+  setLimitOfModel: { effect: "query", args: [{ type: "param", name: "limit", refName: "Int" }] },
+  setQueryArgsOfModel: { effect: "query", args: "slice" },
+  setSortOfModel: { effect: "query", args: [{ type: "param", name: "sort", refName: "String" }] },
+};
+
+/** Which of the model's classes each slice state key holds. The rest hold a primitive or a query descriptor. */
+const sliceStateModelTypes: { [key in SliceStateKey]?: SerializedStoreState["modelType"] } = {
+  defaultModel: "full",
+  modelList: "light",
+  modelInitList: "light",
+  modelSelection: "light",
+  modelInsight: "insight",
+};
+
+/**
+ * What one built store offers an agent, derived from the store the browser is already running.
+ *
+ * The store is the audience-neutral half of the client surface the way a signal registry is the server's: a key on
+ * `st.do` is the same call the user's own click makes, so an agent that drives it cannot reach past what the UI
+ * already permits. That is why the default here is the opposite of the MCP catalogue's — every key is published
+ * unless something about it cannot be described, and each of those is recorded as a refusal rather than dropped.
+ *
+ * Nothing is re-declared. An action's arguments come from the endpoint it is named after, from the field metadata
+ * the form setter was generated from, or from the role the store recorded while building the slice; a key that
+ * matches none of those three is published only when it takes no arguments at all.
+ */
+export class StoreCatalogue {
+  readonly store: SerializedStore;
+  readonly refusals: AgentRefusal[] = [];
+
+  readonly #instance: StoreInstance;
+  readonly #endpoints = new Map<string, { endpoint: SerializedSignal["endpoint"][string]; refName: string }>();
+  readonly #refused = new Set<string>();
+
+  constructor(instance: StoreInstance, serializedSignal: Record<string, SerializedSignal>) {
+    this.#instance = instance;
+    for (const { key, endpoint, refName } of AgentCatalogue.candidates(serializedSignal))
+      this.#endpoints.set(key, { endpoint, refName });
+    this.store = { state: this.#state(), action: this.#actions() };
+  }
+
+  #refuse(key: string, reason: string) {
+    if (this.#refused.has(key)) return;
+    this.#refused.add(key);
+    this.refusals.push({ key, reason });
+  }
+
+  #state(): { [key: string]: SerializedStoreState } {
+    const state = this.#instance.get();
+    const declared = StoreCatalogue.#declaredStateModels();
+    const entries = Object.keys(state)
+      .sort()
+      .map((key): [string, SerializedStoreState] => {
+        const role = this.#instance.sliceStateRoles.get(key);
+        const model = role
+          ? { refName: role.refName, ...StoreCatalogue.#modelTypeOf(sliceStateModelTypes[role.role]) }
+          : (declared.get(key) ?? StoreCatalogue.#refNameOf(state[key]));
+        return [
+          key,
+          {
+            type: StoreCatalogue.#typeOf(state[key]),
+            ...model,
+            ...(role ? { role: role.role } : {}),
+            derived: this.#instance.derivedKeys.has(key),
+          },
+        ];
+      });
+    return Object.fromEntries(entries);
+  }
+
+  /**
+   * The model each generated state key holds, taken from the declaration rather than from the value.
+   *
+   * A read has to be masked by the model, and the value cannot supply it: `immerify` copies a form into a plain
+   * object, so `<model>Form` — an `Input` holding whatever the user typed — arrives with its class already gone.
+   */
+  static #declaredStateModels() {
+    const declared = new Map<string, { refName: string; modelType: SerializedStoreState["modelType"] }>();
+    for (const refName of ConstantRegistry.database.keys()) {
+      const names = databaseStateNames(refName);
+      for (const [role, modelType] of Object.entries(databaseStateModelTypes))
+        declared.set(names[role as keyof typeof names], { refName, modelType });
+    }
+    return declared;
+  }
+
+  static #modelTypeOf(modelType: SerializedStoreState["modelType"]) {
+    return modelType ? { modelType } : {};
+  }
+
+  #actions(): { [key: string]: SerializedStoreAction } {
+    
+    const formSetters = this.#formSetters();
+    const entries = Object.keys(this.#instance.do)
+      .sort()
+      .map((key): [string, SerializedStoreAction] | null => {
+        if (this.#refused.has(key)) return null;
+        const endpoint = this.#endpoints.get(key);
+        if (endpoint) return [key, this.#endpointAction(key, endpoint)];
+        const formSetter = formSetters.get(key);
+        if (formSetter) return [key, formSetter];
+        const slice = this.#sliceAction(key);
+        if (slice) return [key, slice];
+        return this.#plainAction(key);
+      })
+      .filter((entry): entry is [string, SerializedStoreAction] => !!entry);
+    return Object.fromEntries(entries);
+  }
+
+  /**
+   * An action named after an endpoint takes the endpoint's arguments. That is not a coincidence to be verified but
+   * the house naming rule — "the signal, store, and dictionary re-add the model, so `st.do.X` reads the same as
+   * `fetch.X`" — and it is where the store's schemas come from for free.
+   */
+  #endpointAction(
+    key: string,
+    { endpoint, refName }: { endpoint: SerializedSignal["endpoint"][string]; refName: string },
+  ) {
+    const effect = endpoint.type === "mutation" ? "mutation" : "query";
+    return { args: endpoint.args, effect, refName, endpoint: key } satisfies SerializedStoreAction;
+  }
+
+  /**
+   * The generated field setters, computed forward from the same field metadata `makeFormSetter` generated them from.
+   *
+   * A `hidden` or `secret` field is refused. Nothing else in the framework lets one of those cross an agent
+   * boundary — `resolveReturn` strips them on the way out and `Msg.mask` refuses a payload carrying them — and a
+   * setter is the same boundary facing the other way: publishing `setPasswordOnUser` names the field and invites a
+   * write to it in one entry.
+   */
+  #formSetters(): Map<string, SerializedStoreAction> {
+    const setters = new Map<string, SerializedStoreAction>();
+    for (const [refName, cnst] of ConstantRegistry.database) {
+      const className = capitalize(refName);
+      const fields = (cnst.full as unknown as { [key: symbol]: Record<string, CatalogueField> })[FIELD_META];
+      if (!fields) continue;
+      for (const [field, meta] of Object.entries(fields)) {
+        const names = formSetterNames(className, field);
+        if (!(names.setFieldOnModel in this.#instance.do)) continue;
+        if (names.uploadFieldOnModel in this.#instance.do)
+          this.#refuse(names.uploadFieldOnModel, "it takes a browser `FileList`, which an agent has no way to hold.");
+        const arg = this.#argOfField(names.setFieldOnModel, field, meta);
+        if (!arg) continue;
+        const base = { effect: "state", refName, field } satisfies Partial<SerializedStoreAction>;
+        setters.set(names.setFieldOnModel, { ...base, role: "set", args: [arg] });
+        if (!meta.isArray) continue;
+        const element = { ...arg, ...(arg.arrDepth && arg.arrDepth > 1 ? { arrDepth: arg.arrDepth - 1 } : {}) };
+        if (arg.arrDepth === 1) delete element.arrDepth;
+        setters.set(names.addFieldOnModel, { ...base, role: "add", args: [element] });
+        setters.set(names.addOrSubFieldOnModel, { ...base, role: "addOrSub", args: [element] });
+        setters.set(names.subFieldOnModel, {
+          ...base,
+          role: "sub",
+          args: [{ type: "param", name: "idx", refName: "Int" }],
+        });
+      }
+    }
+    return setters;
+  }
+
+  #argOfField(key: string, name: string, field: CatalogueField): SerializedArg | null {
+    if (field.fieldType === "hidden" || field.fieldType === "secret") {
+      this.#refuse(key, `\`${name}\` is a ${field.fieldType} field, which never crosses an agent boundary.`);
+      return null;
+    }
+    if (field.isMap) {
+      this.#refuse(key, `\`${name}\` is a Map, which has no argument schema to publish.`);
+      return null;
+    }
+    const arrDepth = field.arrDepth ?? 0;
+    if (field.enum)
+      return { type: "body", name, refName: "String", enum: field.enum.refName, ...(arrDepth ? { arrDepth } : {}) };
+    if (field.isClass) {
+      const model = field.modelRef ? ConstantRegistry.getRefName(field.modelRef, { allowEmpty: true }) : undefined;
+      this.#refuse(
+        key,
+        `\`${name}\` takes ${model ? `a \`${model}\`` : "an object"}, which an agent holding an id cannot build — it is chosen through the UI.`,
+      );
+      return null;
+    }
+    if (!field.modelRef || !PrimitiveRegistry.has(field.modelRef)) {
+      this.#refuse(key, `\`${name}\` has no primitive to describe it.`);
+      return null;
+    }
+    return {
+      type: "body",
+      name,
+      refName: PrimitiveRegistry.getName(field.modelRef as typeof PrimitiveScalar),
+      ...(arrDepth ? { arrDepth } : {}),
+      ...(StoreCatalogue.#exampleOf(field.example) ?? {}),
+    };
+  }
+
+  #sliceAction(key: string): SerializedStoreAction | null {
+    const role = this.#instance.sliceActionRoles.get(key);
+    if (!role) return null;
+    if (role.role === "selectModel") {
+      this.#refuse(key, "it takes the list item itself, and an agent holding an id would store a stub in its place.");
+      return null;
+    }
+    const { effect, args } = sliceActionArgs[role.role];
+    return { args: args === "slice" ? role.args : args, effect, refName: role.refName, role: role.role };
+  }
+
+  /**
+   * Everything else — a state setter the store generated for a plain key, and the actions a module wrote itself.
+   *
+   * Published only when it declares no parameters, which is the shape most custom actions have: the data comes from
+   * the form state the agent has already filled, in the same order a person fills it. One that does declare
+   * parameters and matched none of the three schema sources cannot be called safely, so it is refused by name.
+   *
+   * `Function.length` is the arity, so a rest parameter reads as none — the one shape that slips through. It slips
+   * through as callable with no arguments, which for a rest signature is the empty call.
+   */
+  #plainAction(key: string): [string, SerializedStoreAction] | null {
+    const arity = this.#instance.actionArity.get(key) ?? 0;
+    if (arity > 0) {
+      this.#refuse(key, `it declares ${arity} argument${arity > 1 ? "s" : ""} that no endpoint or field describes.`);
+      return null;
+    }
+
+    const refName = this.#instance.actionOwners.get(key);
+    return [key, { args: [], effect: "state", ...(refName ? { refName } : {}) }];
+  }
+
+  static #typeOf(value: unknown): SerializedStoreState["type"] {
+    if (value === null || value === undefined) return "unknown";
+    if (Array.isArray(value)) return "list";
+    if (value instanceof Map) return "map";
+    if (value instanceof Date) return "date";
+    switch (typeof value) {
+      case "string":
+        return "string";
+      case "number":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "object":
+        return StoreCatalogue.#isList(value) ? "list" : "object";
+      default:
+        return "unknown";
+    }
+  }
+
+  /** `DataList` and `dayjs` are the two objects a store holds that are not what `typeof` says they are. */
+  static #isList(value: object) {
+    return "values" in value && Array.isArray((value as { values: unknown }).values);
+  }
+
+  static #refNameOf(value: unknown) {
+    if (!value || typeof value !== "object") return {};
+    const refName = ConstantRegistry.getRefName(value.constructor as Cls, { allowEmpty: true });
+    return refName ? { refName } : {};
+  }
+
+  static #exampleOf(example: unknown) {
+    if (example === null || example === undefined) return null;
+    if (["string", "number", "boolean"].includes(typeof example)) return { example: example as string };
+    return example instanceof Date ? { example } : null;
+  }
+}

package/store/agent/index.ts

@@ -0,0 +1,3 @@
+export * from "./AgentBridge";
+export * from "./StoreCatalogue";
+export * from "./types";

package/store/agent/types.ts

@@ -0,0 +1,50 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceActionKey } from "../sliceRole";
+import type { SliceStateKey } from "../state";
+
+/** Which generated form-setter a store key is, when it is one. */
+export type FormSetterRole = "set" | "add" | "sub" | "addOrSub";
+
+/** What calling a store action reaches. `state` never leaves the browser. */
+export type StoreActionEffect = "state" | "query" | "mutation";
+
+export interface SerializedStoreAction {
+  args: SerializedArg[];
+  effect: StoreActionEffect;
+  /** The model this key belongs to, when the key identifies one. */
+  refName?: string;
+  /** The endpoint whose arguments it borrows, when it is named after one. */
+  endpoint?: string;
+  /** The generated role, absent on an action a module wrote itself. */
+  role?: SliceActionKey | FormSetterRole;
+  /** The model field it writes, on a form setter. */
+  field?: string;
+}
+
+export interface SerializedStoreState {
+  /**
+   * What the live value is. A store declares no types — `STATE_META` holds initial values — so this is read off the
+   * value the store is holding, and a key initialized to `null` or `[]` says nothing about what may go into it.
+   */
+  type: "string" | "number" | "boolean" | "date" | "list" | "map" | "object" | "unknown";
+  /** The model this key holds, when it holds one. What a read of it is masked by. */
+  refName?: string;
+  /** Which of the model's five classes, which is what decides the fields a read may carry. */
+  modelType?: "input" | "full" | "light" | "insight";
+  /** Materialized from a computation, the URL, or storage. Writing one throws, so it is read-only by construction. */
+  derived: boolean;
+  role?: SliceStateKey;
+}
+
+/**
+ * One store instance described for an agent: every key it can read and every action it may call.
+ *
+ * Flat rather than grouped by model, because that is what the store is — `st.use.x` and `st.do.y` are one namespace,
+ * so a key means the same thing to every reader and two models cannot both claim one. It is the store's answer to
+ * `SerializedSignal`, and it is derived on the client from the built store rather than shipped from the server: the
+ * store classes are in the bundle already, and a second copy over the wire is a second thing to keep in step.
+ */
+export interface SerializedStore {
+  state: { [key: string]: SerializedStoreState };
+  action: { [key: string]: SerializedStoreAction };
+}

package/store/databaseStateNames.ts

@@ -0,0 +1,31 @@
+import { capitalize } from "akanjs/common";
+
+/**
+ * The state keys every model store holds, and which of the model's five classes each one is an instance of.
+ *
+ * Shared with the agent catalogue, which needs the class rather than the key: a value read out of the store is
+ * masked by the model it belongs to, and `immerify` drops the constructor, so the live value cannot say what it is.
+ * `modelForm` is the one that matters most — it is an `Input` holding whatever the user has typed, credentials
+ * included, and it reaches the catalogue as a plain object.
+ */
+export const databaseStateNames = (refName: string) => {
+  const className = capitalize(refName);
+  return {
+    model: refName,
+    modelLoading: `${refName}Loading`,
+    modelForm: `${refName}Form`,
+    modelFormLoading: `${refName}FormLoading`,
+    modelSubmit: `${refName}Submit`,
+    modelViewAt: `${refName}ViewAt`,
+    modelModal: `${refName}Modal`,
+    modelOperation: `${refName}Operation`,
+    defaultModel: `default${className}`,
+  };
+};
+
+/** Which of the model's classes each generated state key holds, for the keys that hold one at all. */
+export const databaseStateModelTypes = {
+  model: "full",
+  modelForm: "input",
+  defaultModel: "full",
+} as const satisfies { [key in keyof ReturnType<typeof databaseStateNames>]?: "full" | "input" | "light" | "insight" };