akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/store/agent/AgentVisibility.ts

@@ -0,0 +1,68 @@
+import { STATE_META } from "akanjs/base";
+import { StoreRegistry } from "../storeRegistry";
+import type { StoreAgentExposure } from "../types";
+
+/**
+ * Which stores the agent surface may show, derived from the registry: every registered store's state keys name
+ * their owner, and a store's `static agent` declaration is its own exposure decision. Liveness rides on top —
+ * `liveOwners` maps the subscribed keys back to store refNames, so the published surface follows the rendered
+ * screen instead of the whole bundle.
+ */
+export class AgentVisibility {
+  #owners: Map<string, string> | null = null;
+  #ownersSize = -1;
+
+  /** State key → owning store refName. First registration wins where a lib mixin shares a key. */
+  #stateOwners(): Map<string, string> {
+    const stores = StoreRegistry.stores;
+    if (this.#owners && this.#ownersSize === stores.size) return this.#owners;
+    const owners = new Map<string, string>();
+    for (const [refName, cls] of stores)
+      for (const key of Object.keys(cls[STATE_META] ?? {})) if (!owners.has(key)) owners.set(key, refName);
+    this.#owners = owners;
+    this.#ownersSize = stores.size;
+    return owners;
+  }
+
+  stateOwner(key: string): string | undefined {
+    return this.#stateOwners().get(key);
+  }
+
+  /** The stores that declared an exposure of their own, for the catalogue's refusal lines. */
+  declaredExposures(): Map<string, StoreAgentExposure> {
+    const declared = new Map<string, StoreAgentExposure>();
+    for (const [refName, cls] of StoreRegistry.stores) if (cls.agent !== undefined) declared.set(refName, cls.agent);
+    return declared;
+  }
+
+  #exposure(refName: string | undefined): StoreAgentExposure | undefined {
+    return refName ? StoreRegistry.get(refName)?.agent : undefined;
+  }
+
+  visibleKey(key: string): boolean {
+    const exposure = this.#exposure(this.stateOwner(key));
+    if (exposure === false) return false;
+    return !exposure?.exclude.includes(key);
+  }
+
+  visibleAction(name: string, ownerRefName?: string): boolean {
+    const exposure = this.#exposure(ownerRefName);
+    if (exposure === false) return false;
+    return !exposure?.exclude.includes(name);
+  }
+
+  /**
+   * The stores the rendered screen is reading right now: owners of the subscribed, still-visible keys. A key no
+   * registered store owns has no module to activate, and an action with no owner stays published — only fabricated
+   * stores outside the registry produce either.
+   */
+  liveOwners(liveKeys: ReadonlyMap<string, number>): Set<string> {
+    const owners = new Set<string>();
+    for (const key of liveKeys.keys()) {
+      if (!this.visibleKey(key)) continue;
+      const owner = this.stateOwner(key);
+      if (owner) owners.add(owner);
+    }
+    return owners;
+  }
+}

package/store/agent/ScreenReader.ts

@@ -0,0 +1,208 @@
+const skipTags = new Set([
+  "SCRIPT",
+  "STYLE",
+  "NOSCRIPT",
+  "TEMPLATE",
+  "IFRAME",
+  "SVG",
+  "CANVAS",
+  "VIDEO",
+  "AUDIO",
+  "OBJECT",
+  "EMBED",
+]);
+const headingLevels = { H1: 1, H2: 2, H3: 3, H4: 4, H5: 5, H6: 6 } as const;
+const blockTags = new Set([
+  "ADDRESS",
+  "ARTICLE",
+  "ASIDE",
+  "BLOCKQUOTE",
+  "DD",
+  "DETAILS",
+  "DIV",
+  "DL",
+  "DT",
+  "FIELDSET",
+  "FIGCAPTION",
+  "FIGURE",
+  "FOOTER",
+  "FORM",
+  "HEADER",
+  "HR",
+  "LEGEND",
+  "MAIN",
+  "NAV",
+  "OL",
+  "P",
+  "SECTION",
+  "SUMMARY",
+  "TABLE",
+  "THEAD",
+  "TBODY",
+  "TFOOT",
+  "TR",
+  "UL",
+]);
+
+/**
+ * Serializes what the page is rendering into compact text an agent can answer questions from: headings keep their
+ * level, links keep their href, controls keep their value and `data-akan-*` annotation. The agent's own UI is
+ * marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a password value is never
+ * read — the screen shows dots, so the DOM holds more than the user sees.
+ */
+export class ScreenReader {
+  static readonly limit = 8000;
+
+  static read(root?: HTMLElement | null): string {
+    if (typeof document === "undefined") return "No rendered document is available.";
+    const reader = new ScreenReader();
+    const title = document.title.trim();
+    if (title) reader.#lines.push(`Page: ${title}`);
+    reader.#walk(root ?? document.body);
+    reader.#flush();
+    const text = reader.#lines.join("\n").trim();
+    if (text.length <= ScreenReader.limit) return text || "The page is rendering nothing readable.";
+    return `${text.slice(0, ScreenReader.limit)}… [truncated ${text.length - ScreenReader.limit} more characters]`;
+  }
+
+  #lines: string[] = [];
+  #buffer = "";
+  #length = 0;
+
+  #walk(node: Node): void {
+    if (this.#length > ScreenReader.limit * 2) return;
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = (node.textContent ?? "").replace(/\s+/g, " ");
+      if (text.trim()) this.#buffer += text;
+      return;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) return;
+    const el = node as HTMLElement;
+    const tag = el.tagName.toUpperCase();
+    if (skipTags.has(tag)) return;
+    if (el.hasAttribute("data-agent-ui") || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true")
+      return;
+    if (typeof el.checkVisibility === "function" && !el.checkVisibility()) return;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") {
+      this.#control(el, tag);
+      return;
+    }
+    if (tag === "IMG") {
+      const alt = el.getAttribute("alt");
+      if (alt) this.#buffer += ` [image: ${alt}]`;
+      return;
+    }
+    if (tag === "BR") {
+      this.#flush();
+      return;
+    }
+    if (tag === "PRE") {
+      this.#pre(el);
+      return;
+    }
+    if (tag === "A") {
+      this.#anchor(el);
+      return;
+    }
+    if (tag === "BUTTON" || el.getAttribute("role") === "button") {
+      this.#button(el);
+      return;
+    }
+    const level = headingLevels[tag as keyof typeof headingLevels];
+    if (level) {
+      this.#flush();
+      this.#walkChildren(el);
+      this.#flush(`${"#".repeat(level)} `);
+      return;
+    }
+    if (tag === "LI") {
+      this.#flush();
+      this.#walkChildren(el);
+      this.#flush("- ");
+      return;
+    }
+    if (tag === "TD" || tag === "TH") {
+      if (this.#buffer.trim()) this.#buffer += " |";
+      this.#walkChildren(el);
+      return;
+    }
+    if (blockTags.has(tag)) {
+      this.#flush();
+      this.#walkChildren(el);
+      this.#flush();
+      return;
+    }
+    this.#walkChildren(el);
+  }
+
+  #walkChildren(el: HTMLElement) {
+    for (const child of el.childNodes) this.#walk(child);
+  }
+
+  #anchor(el: HTMLElement) {
+    const href = el.getAttribute("href") ?? "";
+    const before = this.#buffer;
+    this.#walkChildren(el);
+    const text = this.#buffer.slice(before.length).replace(/\s+/g, " ").trim();
+    if (href && href !== "#" && !href.startsWith("javascript:") && text !== href) this.#buffer += ` (${href})`;
+  }
+
+  #button(el: HTMLElement) {
+    const before = this.#buffer;
+    this.#walkChildren(el);
+    const inner = this.#buffer.slice(before.length).replace(/\s+/g, " ").trim();
+    this.#buffer = before;
+    const label = inner || el.getAttribute("aria-label") || "";
+    const action = el.getAttribute("data-akan-action");
+    if (label || action) this.#buffer += ` [button: ${label}${action ? ` → ${action}` : ""}]`;
+  }
+
+  #control(el: HTMLElement, tag: string) {
+    const input = el as HTMLInputElement;
+    const type = (el.getAttribute("type") ?? (tag === "INPUT" ? "text" : tag.toLowerCase())).toLowerCase();
+    if (type === "hidden") return;
+    const name =
+      el.getAttribute("data-akan-state") ??
+      el.getAttribute("aria-label") ??
+      el.getAttribute("placeholder") ??
+      el.getAttribute("name") ??
+      type;
+    if (type === "password") {
+      this.#buffer += ` [input ${name}]`;
+      return;
+    }
+    if (type === "checkbox" || type === "radio") {
+      this.#buffer += ` [${type} ${name}: ${input.checked ? "on" : "off"}]`;
+      return;
+    }
+    const raw =
+      tag === "SELECT"
+        ? ((el as unknown as HTMLSelectElement).selectedOptions?.[0]?.textContent ??
+          (el as unknown as HTMLSelectElement).value)
+        : input.value;
+    const value = (raw ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
+    this.#buffer += ` [${tag === "SELECT" ? "select" : "input"} ${name}: ${JSON.stringify(value)}]`;
+  }
+
+  #pre(el: HTMLElement) {
+    this.#flush();
+    const raw = (el.textContent ?? "").trim();
+    if (!raw) return;
+    const rows = raw.split("\n");
+    this.#lines.push(
+      "```",
+      ...rows.slice(0, 30),
+      ...(rows.length > 30 ? [`… ${rows.length - 30} more lines`] : []),
+      "```",
+    );
+    this.#length += raw.length;
+  }
+
+  #flush(prefix = "") {
+    const text = this.#buffer.replace(/\s+/g, " ").trim();
+    this.#buffer = "";
+    if (!text) return;
+    this.#lines.push(prefix + text);
+    this.#length += prefix.length + text.length;
+  }
+}

package/store/agent/StoreCatalogue.ts

@@ -0,0 +1,351 @@
+import { type Cls, FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { capitalize, Logger } 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 { AgentVisibility } from "./AgentVisibility";
+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.
+ *
+ * This is the visible universe, not the live view: a store's own `static agent` declaration is honored here, and
+ * the bridge narrows the result to the stores the rendered screen is reading when it answers.
+ *
+ * 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 visibility = new AgentVisibility();
+
+  readonly #instance: StoreInstance;
+  readonly #endpoints = new Map<string, { endpoint: SerializedSignal["endpoint"][string]; refName: string }>();
+  readonly #refused = new Set<string>();
+  readonly #baseFieldSetters = new Set<string>();
+  #formSetterCache: Map<string, SerializedStoreAction> | null = null;
+  static readonly #baseDocumentFields = new Set(["id", "createdAt", "updatedAt", "removedAt"]);
+  static readonly #warnedMismatches = 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.#refuseDeclaredExposures();
+    this.store = { state: this.#state(), action: this.#actions() };
+  }
+
+  /** One line per opted-out store, so the Dock answers "why is X missing" without a row per hidden key. */
+  #refuseDeclaredExposures() {
+    for (const [refName, exposure] of this.visibility.declaredExposures()) {
+      if (exposure === false)
+        this.#refuse(refName, "its store declares `agent: false`, so none of its keys or actions are published.");
+      else for (const name of exposure.exclude) this.#refuse(name, "excluded by its store's `agent` declaration.");
+    }
+  }
+
+  #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)
+      .filter((key) => this.visibility.visibleKey(key))
+      .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 } {
+    
+    this.#formSetterCache = this.#formSetters();
+    const entries = Object.keys(this.#instance.do)
+      .sort()
+      .map((key): [string, SerializedStoreAction] | null => this.#action(key))
+      .filter((entry): entry is [string, SerializedStoreAction] => !!entry);
+    return Object.fromEntries(entries);
+  }
+
+  #action(key: string): [string, SerializedStoreAction] | null {
+    if (this.#refused.has(key)) return null;
+
+    if (this.#instance.generatedSetters.has(key)) return null;
+    
+    if (this.#baseFieldSetters.has(key)) return null;
+    if (!this.visibility.visibleAction(key, this.#instance.actionOwners.get(key)?.refName)) return null;
+    const endpoint = this.#endpoints.get(key);
+    if (endpoint)
+      return this.#actionFitsEndpoint(key, endpoint.endpoint) ? [key, this.#endpointAction(key, endpoint)] : null;
+    const formSetter = this.#formSetterCache?.get(key);
+    if (formSetter) return [key, formSetter];
+    const slice = this.#sliceAction(key);
+    if (slice) return [key, slice];
+    return this.#plainAction(key);
+  }
+
+  /**
+   * The borrowed schema is only honest when the action can consume it: one that declares fewer parameters than the
+   * endpoint silently drops the tail and reads stale form state instead, so a schema-correct call becomes a wrong
+   * mutation reported as success. More parameters than the endpoint is the generated shape —
+   * `create<Model>(data, options?)` — and stays published. `Function.length` stops at the first default, so a
+   * defaulted mirror parameter reads as missing here; align it with the endpoint or exclude the action.
+   */
+  #actionFitsEndpoint(key: string, endpoint: SerializedSignal["endpoint"][string]) {
+    const arity = this.#instance.actionArity.get(key) ?? 0;
+    const declared = endpoint.args.length;
+    if (arity >= declared) return true;
+    this.#refuse(
+      key,
+      `it declares ${arity} parameter${arity === 1 ? "" : "s"} while the same-named endpoint takes ${declared} — a schema-shaped call would drop the tail and read form state instead. Align the action's parameters with the endpoint, or exclude the action.`,
+    );
+    if (!StoreCatalogue.#warnedMismatches.has(key)) {
+      StoreCatalogue.#warnedMismatches.add(key);
+      Logger.warn(
+        `st.do.${key} does not mirror endpoint ${key} (${arity} vs ${declared} args) — not published to agents.`,
+      );
+    }
+    return false;
+  }
+
+  /**
+   * An action named after an endpoint takes the endpoint's arguments — the house naming rule ("the signal, store,
+   * and dictionary re-add the model, so `st.do.X` reads the same as `fetch.X`") is where the store's schemas come
+   * from for free, and #actionFitsEndpoint is what holds the rule to its word.
+   */
+  #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 (StoreCatalogue.#baseDocumentFields.has(field)) {
+          for (const name of Object.values(names)) if (name in this.#instance.do) this.#baseFieldSetters.add(name);
+          continue;
+        }
+        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)?.refName;
+    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;
+  }
+}