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

package/store/agent/StoreSurfaceSource.ts

@@ -0,0 +1,122 @@
+import { router } from "akanjs/client";
+import type { SurfaceSource, ToolEntry } from "../../vendor/use-agentic";
+import { AgentBridge, type AgentTool } from "./AgentBridge";
+import { ScreenReader } from "./ScreenReader";
+
+/**
+ * The store bridge as one surface source: every catalogued action of the stores the rendered screen is reading is
+ * a callable tool, executed through `AgentBridge.call` so argument checking, masking, and the transcript stay in
+ * one place. Recomputed per snapshot — the bridge's live view changes as components mount and unmount — and
+ * per zone view: a zone session sees the stores its own subtree subscribes, and its `readScreen` reads its own
+ * `data-agent-zone` container rather than the whole document.
+ *
+ * `remove*` keys default to a confirm gate — destructiveness derived from the key, the way the MCP hints derive
+ * theirs — and a page can still shadow any entry with its own hook registration.
+ */
+export class StoreSurfaceSource implements SurfaceSource {
+  #bridge: AgentBridge | null;
+  readonly #wrapped = new Map<string, { source: AgentTool[]; entries: ToolEntry[] }>();
+  readonly #builtins = new Map<string, ToolEntry[]>();
+
+  /** Lazy by default: `AgentBridge.of()` walks the whole store, so it waits for the first enumeration. */
+  constructor(bridge?: AgentBridge) {
+    this.#bridge = bridge ?? null;
+  }
+
+  tools = (view: string[] = []): ToolEntry[] => {
+    const viewKey = view.join(".");
+    this.#bridge ??= AgentBridge.of();
+    const bridge = this.#bridge;
+    const live = bridge.toolsFor(viewKey);
+    const cached = this.#wrapped.get(viewKey);
+    if (cached?.source !== live)
+      this.#wrapped.set(viewKey, {
+        source: live,
+        entries: live.map((tool) => StoreSurfaceSource.#entry(bridge, tool, viewKey)),
+      });
+    
+    let builtins = this.#builtins.get(viewKey);
+    if (!builtins) {
+      builtins = [StoreSurfaceSource.#navigate(), StoreSurfaceSource.#readScreen(viewKey), this.#readState(viewKey)];
+      this.#builtins.set(viewKey, builtins);
+    }
+    const wrapped = this.#wrapped.get(viewKey);
+    return [...(wrapped?.entries ?? []), ...builtins];
+  };
+
+  static #entry(bridge: AgentBridge, tool: AgentTool, viewKey: string): ToolEntry {
+    const description = tool.description ?? tool.title;
+    return {
+      name: tool.name,
+      ...(description ? { description } : {}),
+      parameters: tool.inputSchema as Record<string, unknown>,
+      effect: tool.effect,
+      ...(tool.name.startsWith("remove") ? { confirm: true } : {}),
+      run: async (args: Record<string, unknown>) => {
+        await bridge.call(tool.name, args, viewKey);
+      },
+    };
+  }
+
+  /** Screen-driving is client navigation, so the agent gets the same router `Link` rides. */
+  static #navigate(): ToolEntry {
+    return {
+      name: "navigate",
+      description: "Navigate this page to an internal path of this app, e.g. /docs/intro/quickstart.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      
+      guard: (args) =>
+        typeof args.path === "string" && args.path.startsWith("/") && !args.path.startsWith("//")
+          ? true
+          : "path must be an internal path starting with /.",
+      run: (args) => {
+        const path = String(args.path);
+        router.push(path);
+        return `Navigating to ${path}.`;
+      },
+    };
+  }
+
+  /** What the user is looking at, read from the rendered DOM — the store never held it, so no key can answer it. */
+  static #readScreen(viewKey: string): ToolEntry {
+    return {
+      name: "readScreen",
+      description: viewKey
+        ? "Read what is currently rendered in this zone — headings, prose, links, buttons, and form values. Use it when the user asks about what this zone shows."
+        : "Read what is currently rendered on this page — headings, prose, links, buttons, and form values. Use it when the user asks about the current page or screen.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      effect: "query",
+      run: () => ScreenReader.read(StoreSurfaceSource.#zoneRoot(viewKey)),
+    };
+  }
+
+  /** The pull half of the state context block: keys are listed there, values arrive masked through this. */
+  #readState(viewKey: string): ToolEntry {
+    return {
+      name: "readState",
+      description: "Read one store state key of this page. Keys are listed in the state context block.",
+      parameters: {
+        type: "object",
+        properties: { key: { type: "string" } },
+        required: ["key"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      run: (args: Record<string, unknown>) => {
+        this.#bridge ??= AgentBridge.of();
+        return this.#bridge.read(String(args.key), viewKey);
+      },
+    };
+  }
+
+  static #zoneRoot(viewKey: string): HTMLElement | undefined {
+    if (!viewKey || typeof document === "undefined") return undefined;
+    return document.querySelector<HTMLElement>(`[data-agent-zone="${CSS.escape(viewKey)}"]`) ?? undefined;
+  }
+}

package/store/agent/index.ts

@@ -0,0 +1,9 @@
+export * from "./AgentBridge";
+export * from "./AgentContext";
+export * from "./AgentPrompts";
+export * from "./AgentVisibility";
+export * from "./ScreenReader";
+export * from "./StoreCatalogue";
+export * from "./StoreSurfaceSource";
+export * from "./storeSurface";
+export * from "./types";

package/store/agent/storeSurface.ts

@@ -0,0 +1,28 @@
+import { AgenticSurface } from "../../vendor/use-agentic";
+import { AgentBridge } from "./AgentBridge";
+import { StoreSurfaceSource } from "./StoreSurfaceSource";
+
+export interface StoreSurface {
+  bridge: AgentBridge;
+  source: StoreSurfaceSource;
+  surface: AgenticSurface;
+}
+
+const SURFACE_KEY = Symbol.for("akanjs.store.agentSurface");
+
+/**
+ * Attaches the app's store catalogue to the shared surface, once per runtime, lazily — nothing pays for the
+ * bridge walk until something agent-facing (the dock, a chat) actually asks. On the server it builds but does not
+ * attach: a server-global surface would be shared across requests, and no session assembles context there.
+ */
+export const ensureStoreSurface = (): StoreSurface => {
+  const holder = globalThis as typeof globalThis & { [SURFACE_KEY]?: StoreSurface };
+  if (!holder[SURFACE_KEY]) {
+    const bridge = AgentBridge.of();
+    const source = new StoreSurfaceSource(bridge);
+    const surface = AgenticSurface.shared;
+    if (typeof window !== "undefined") surface.addSource(source);
+    holder[SURFACE_KEY] = { bridge, source, surface };
+  }
+  return holder[SURFACE_KEY];
+};

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/agentic/StToolBuilder.ts

@@ -0,0 +1,199 @@
+import {
+  type CLIENT_VALUE,
+  type Cls,
+  dayjs,
+  type EnumInstance,
+  Int,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+} from "akanjs/base";
+import type { ParamFieldType } from "akanjs/constant";
+import {
+  AgenticSurface,
+  type JsonSchema,
+  type ToolConfirm,
+  type ToolEffect,
+  type ToolGuard,
+  useScopePath,
+  useSurface,
+} from "../../vendor/use-agentic";
+import { tagAction } from "../actionTag";
+
+import { useEffect, useRef } from "../hooks";
+
+export interface StToolMeta {
+  desc?: string;
+  effect?: ToolEffect;
+  confirm?: ToolConfirm;
+  guard?: ToolGuard;
+}
+
+interface StToolArg {
+  name: string;
+  type: ParamFieldType;
+  optional: boolean;
+}
+
+type ArgValue<T> = T extends EnumInstance<string, infer V> ? V : T extends { [CLIENT_VALUE]: infer V } ? V : never;
+
+/**
+ * A component tool in the signal's vocabulary: `st.tool("x", { desc }).arg("id", ID).exec(fn)`.
+ *
+ * This is not A12's rejected store-action builder — a store action derives its schema from the endpoint it is
+ * named after, while a component tool exists nowhere else, so declaring is the only source there is. `.arg()` only
+ * accumulates data; `.exec()` is the one hook, so the chain must complete in one unconditional statement.
+ */
+export class StToolBuilder<Args extends unknown[] = []> {
+  readonly #name: string;
+  readonly #meta: StToolMeta;
+  readonly #args: StToolArg[];
+
+  constructor(name: string, meta: StToolMeta = {}, args: StToolArg[] = []) {
+    this.#name = name;
+    this.#meta = meta;
+    this.#args = args;
+  }
+
+  arg<T extends ParamFieldType>(name: string, type: T): StToolBuilder<[...Args, ArgValue<T>]>;
+  arg<T extends ParamFieldType>(
+    name: string,
+    type: T,
+    option: { optional: true },
+  ): StToolBuilder<[...Args, ArgValue<T> | null]>;
+  arg<T extends ParamFieldType>(
+    name: string,
+    type: T,
+    option: { optional?: boolean } = {},
+  ): StToolBuilder<[...Args, ArgValue<T> | null]> {
+    
+    StToolBuilder.schemaOf(type);
+    return new StToolBuilder(this.#name, this.#meta, [...this.#args, { name, type, optional: !!option.optional }]);
+  }
+
+  /** The only hook in the chain. `run`, `guard`, and `confirm` stay always-latest; the declaration is mount-static. */
+  exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void> {
+    const surface = useSurface();
+    const scope = useScopePath();
+    const live = useRef({ run, meta: this.#meta });
+    live.current = { run, meta: this.#meta };
+    const declared = useRef<{ name: string; meta: StToolMeta; args: StToolArg[] } | null>(null);
+    declared.current ??= { name: this.#name, meta: this.#meta, args: this.#args };
+    const callable = useRef<((...args: Args) => Promise<void>) | null>(null);
+    if (!callable.current) {
+      const action = AgenticSurface.fullName(scope, this.#name);
+      callable.current = tagAction(
+        async (...args: Args) => {
+          await live.current.run(...args);
+        },
+        { action },
+      );
+    }
+    const scopeKey = scope.join(".");
+    useEffect(() => {
+      const spec = declared.current;
+      if (!spec) return;
+      return surface.registerTool(scope, {
+        name: spec.name,
+        description: spec.meta.desc,
+        effect: spec.meta.effect,
+        parameters: StToolBuilder.parametersOf(spec.args),
+        ...(spec.meta.confirm === undefined
+          ? {}
+          : {
+              confirm: (args: Record<string, unknown>) => {
+                const confirm = live.current.meta.confirm;
+                return typeof confirm === "function" ? confirm(args) : (confirm ?? false);
+              },
+            }),
+        ...(spec.meta.guard === undefined
+          ? {}
+          : { guard: (args: Record<string, unknown>) => live.current.meta.guard?.(args) ?? true }),
+        run: (named) => live.current.run(...(StToolBuilder.positionalOf(spec.name, spec.args, named) as Args)),
+      });
+    }, [surface, scopeKey, this.#name]);
+    return callable.current;
+  }
+
+  static parametersOf(args: StToolArg[]): JsonSchema | undefined {
+    if (!args.length) return undefined;
+    const required = args.filter((arg) => !arg.optional).map((arg) => arg.name);
+    return {
+      type: "object",
+      properties: Object.fromEntries(args.map((arg) => [arg.name, StToolBuilder.schemaOf(arg.type)])),
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    };
+  }
+
+  /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
+  static schemaOf(type: ParamFieldType): JsonSchema {
+    if (isEnum(type as Cls)) {
+      const enumRef = type as EnumInstance;
+      const kind = enumRef.type === String ? "string" : enumRef.type === Int ? "integer" : "number";
+      return { type: kind, enum: [...enumRef.values] };
+    }
+    const scalar = type as typeof PrimitiveScalar;
+    if (!PrimitiveRegistry.has(scalar as unknown as Cls))
+      throw new Error("st.tool takes scalar and enum arguments only.");
+    switch (PrimitiveRegistry.getName(scalar)) {
+      case "ID":
+      case "String":
+        return { type: "string" };
+      case "Int":
+        return { type: "integer" };
+      case "Float":
+        return { type: "number" };
+      case "Boolean":
+        return { type: "boolean" };
+      case "Date":
+        return { type: "string", format: "date-time" };
+      default:
+        throw new Error(`st.tool cannot describe the scalar ${PrimitiveRegistry.getName(scalar)}.`);
+    }
+  }
+
+  static positionalOf(toolName: string, args: StToolArg[], named: Record<string, unknown>): unknown[] {
+    return args.map((arg) => {
+      const value = named[arg.name];
+      if (value === undefined || value === null) {
+        if (arg.optional) return null;
+        throw new Error(`Missing argument "${arg.name}" for ${toolName}.`);
+      }
+      return StToolBuilder.checkedValue(toolName, arg.name, arg.type, value);
+    });
+  }
+
+  /** What `AgentBridge` does for endpoint arguments, for a component tool's own — nothing on the wire enforces the published schema. */
+  static checkedValue(toolName: string, argName: string, type: ParamFieldType, value: unknown): unknown {
+    if (isEnum(type as Cls)) {
+      const enumRef = type as EnumInstance;
+      if (!enumRef.values.includes(value as never))
+        throw new Error(`Argument "${argName}" of ${toolName} must be one of: ${[...enumRef.values].join(", ")}.`);
+      return value;
+    }
+    switch (PrimitiveRegistry.getName(type as typeof PrimitiveScalar)) {
+      case "ID":
+      case "String":
+        if (typeof value !== "string") throw new Error(`Argument "${argName}" of ${toolName} must be a string.`);
+        return value;
+      case "Int":
+        if (!Number.isInteger(value)) throw new Error(`Argument "${argName}" of ${toolName} must be a whole number.`);
+        return value;
+      case "Float":
+        if (typeof value !== "number" || !Number.isFinite(value))
+          throw new Error(`Argument "${argName}" of ${toolName} must be a finite number.`);
+        return value;
+      case "Boolean":
+        if (typeof value !== "boolean") throw new Error(`Argument "${argName}" of ${toolName} must be a boolean.`);
+        return value;
+      case "Date": {
+        const parsed = dayjs(value as string | number | Date);
+        if (!parsed.isValid()) throw new Error(`Argument "${argName}" of ${toolName} must be an ISO 8601 date string.`);
+        return parsed;
+      }
+      default:
+        return value;
+    }
+  }
+}

package/store/agentic/attachAgentic.ts

@@ -0,0 +1,22 @@
+import type { Dispatch, SetStateAction } from "react";
+import { StToolBuilder, type StToolMeta } from "./StToolBuilder";
+import { type StExposeMeta, useStExpose } from "./useStExpose";
+import { type StStateMeta, useStState } from "./useStState";
+
+export interface StAgentic {
+  /** Local state the in-page agent can read. Writes need a `set` type and go through a named setter tool. */
+  useState: <T>(name: string, initial: T | (() => T), meta?: StStateMeta<T>) => [T, Dispatch<SetStateAction<T>>];
+  /** A read-only derived value the agent can read while the component is mounted. */
+  expose: (name: string, value: unknown, meta?: StExposeMeta) => void;
+  /** A component tool: `.arg("id", ID)` chained onto one `.exec()` hook. */
+  tool: (name: string, meta?: StToolMeta) => StToolBuilder;
+}
+
+const stAgentic: StAgentic = {
+  useState: useStState,
+  expose: useStExpose,
+  tool: (name, meta) => new StToolBuilder(name, meta),
+};
+
+/** Idempotent — `StoreRegistry.build` runs once per merged root, always onto the one instance. */
+export const attachAgentic = <T extends object>(instance: T): T & StAgentic => Object.assign(instance, stAgentic);

package/store/agentic/index.ts

@@ -0,0 +1,5 @@
+export * from "./attachAgentic";
+export * from "./readableValue";
+export * from "./StToolBuilder";
+export * from "./useStExpose";
+export * from "./useStState";

package/store/agentic/readableValue.ts

@@ -0,0 +1,17 @@
+import { type MaskModel, mask } from "akanjs/constant";
+
+const isPlainAgentValue = (value: unknown): boolean => {
+  if (value === null || value === undefined) return true;
+  if (Array.isArray(value)) return value.every((item) => isPlainAgentValue(item));
+  if (value instanceof Date) return true;
+  return typeof value !== "object";
+};
+
+/** What `AgentBridge.read` does for store keys, for a hook's value: mask by the declared model, pass scalars, refuse the rest. */
+export const readableValue = (name: string, value: unknown, model?: MaskModel): unknown => {
+  if (model) return mask(model, value);
+  if (isPlainAgentValue(value)) return value;
+  throw new Error(
+    `State "${name}" holds an object that belongs to no model, so there is nothing to mask it by and it is not published. Declare mask: or serialize: on it.`,
+  );
+};

package/store/agentic/useStExpose.ts

@@ -0,0 +1,18 @@
+import type { MaskModel } from "akanjs/constant";
+import { useAgentResource } from "../../vendor/use-agentic";
+import { readableValue } from "./readableValue";
+
+export interface StExposeMeta {
+  desc?: string;
+  mask?: MaskModel;
+  serialize?: (value: unknown) => unknown;
+  report?: boolean;
+}
+
+export const useStExpose = (name: string, value: unknown, meta: StExposeMeta = {}): void => {
+  useAgentResource(name, value, {
+    description: meta.desc,
+    report: meta.report,
+    serialize: meta.serialize ?? ((current) => readableValue(name, current, meta.mask)),
+  });
+};

package/store/agentic/useStState.ts

@@ -0,0 +1,35 @@
+import { capitalize } from "akanjs/common";
+import type { MaskModel, ParamFieldType } from "akanjs/constant";
+import type { Dispatch, SetStateAction } from "react";
+import { useAgentState } from "../../vendor/use-agentic";
+import { readableValue } from "./readableValue";
+import { StToolBuilder } from "./StToolBuilder";
+
+export interface StStateMeta<T> {
+  desc?: string;
+  /** The model whose `hidden`/`secret` fields a read strips. An object value with no `mask` and no `serialize` is refused. */
+  mask?: MaskModel;
+  serialize?: (value: T) => unknown;
+  report?: boolean;
+  /** The scalar or enum an agent may write through the generated `set<Name>` tool. Read-only without it. */
+  set?: ParamFieldType;
+}
+
+export const useStState = <T>(
+  name: string,
+  initial: T | (() => T),
+  meta: StStateMeta<T> = {},
+): [T, Dispatch<SetStateAction<T>>] => {
+  const set = meta.set;
+  return useAgentState<T>(name, initial, {
+    description: meta.desc,
+    report: meta.report,
+    serialize: meta.serialize ?? ((value) => readableValue(name, value, meta.mask)),
+    ...(set
+      ? {
+          set: StToolBuilder.schemaOf(set),
+          parse: (value) => StToolBuilder.checkedValue(`set${capitalize(name)}`, "value", set, value) as T,
+        }
+      : {}),
+  });
+};

package/store/baseSt.ts

@@ -19,6 +19,12 @@ export const getBaseSearchParam = (searchParams: BaseSearchParamsState, key: str
   return Array.isArray(value) ? value[0] : value;
 };
 
+/**
+ * `agent: false` keeps the whole base store off the agent surface. Its keys are framework plumbing that other
+ * effects write into, so the generated setters are levers that do nothing (`setPath` does not navigate — the
+ * router overwrites it) — and `tryJwt`/`tryAccount` hold the caller's credential, which must never reach a model.
+ * The route context block carries the three keys an agent legitimately needs.
+ */
 export class BaseStore extends store("base" as const, () => ({
   csrLoaded: false,
   path: "/",
@@ -52,6 +58,7 @@ export class BaseStore extends store("base" as const, () => ({
   deviceToken: "" as string,
   currentPath: "" as string,
 })) {
+  static override agent = false as const;
   setDevMode(value: boolean) {
     this.set({ devMode: value });
     localStorage.setItem("devMode", value.toString());

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" };

package/store/formSetterNames.ts

@@ -0,0 +1,21 @@
+import { capitalize, lowerlize } from "akanjs/common";
+
+/**
+ * The keys `makeFormSetter` publishes for one field of one model.
+ *
+ * Shared with the agent catalogue, which has to answer what `setNameOnUser` takes without parsing the name apart —
+ * `set(.+)On(.+)` has more than one reading whenever a field or a model name contains `On`. Computing the same names
+ * forward from the same field metadata is unambiguous, and keeps the two from drifting when a name changes here.
+ */
+export const formSetterNames = (className: string, key: string) => {
+  const classKeyName = capitalize(key);
+  return {
+    field: lowerlize(key),
+    Field: classKeyName,
+    setFieldOnModel: `set${classKeyName}On${className}`,
+    addFieldOnModel: `add${classKeyName}On${className}`,
+    subFieldOnModel: `sub${classKeyName}On${className}`,
+    addOrSubFieldOnModel: `addOrSub${classKeyName}On${className}`,
+    uploadFieldOnModel: `upload${classKeyName}On${className}`,
+  };
+};

package/store/index.ts

@@ -1,8 +1,16 @@
 export * from "./action";
+export * from "./actionTag";
+export * from "./agent";
+export * from "./agentic";
 export * from "./baseSt";
+export * from "./databaseStateNames";
+export * from "./formSetterNames";
 export * from "./rootStore";
+export * from "./sliceRole";
 export * from "./state";
 export * from "./stateBuilder";
 export * from "./store";
+
+export { StoreInstance } from "./storeInstance";
 export * from "./storeRegistry";
 export * from "./types";

package/store/rootStore.ts

@@ -1,5 +1,6 @@
-import type { ACTION_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
+import type { ACTION_META, ACTION_OWNER_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
 import type { SerializedSlice } from "akanjs/signal";
+import type { ActionOwner } from "./actionTag";
 import type { StateDerivedMeta, StateInitializerMap } from "./stateBuilder";
 import type { SetGetWritable } from "./types";
 
@@ -20,6 +21,7 @@ export type RootStoreCls<
     [STATE_INIT_META]: StateInitializerMap;
     [STATE_DERIVED_META]: StateDerivedMeta;
     [ACTION_META]: { [key: string]: (...args: any[]) => any };
+    [ACTION_OWNER_META]: { [key: string]: ActionOwner };
     slice: { [key: string]: { [key: string]: SerializedSlice } };
     _slice: SliceInfoObj;
   }

package/store/sliceRole.ts

@@ -0,0 +1,36 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceStateKey } from "./state";
+
+/** The generated slice actions, named by what they do rather than by the key any one slice publishes them under. */
+export type SliceActionKey =
+  | "initModel"
+  | "refreshModel"
+  | "selectModel"
+  | "setPageOfModel"
+  | "addPageOfModel"
+  | "setLimitOfModel"
+  | "setQueryArgsOfModel"
+  | "setSortOfModel";
+
+/**
+ * What a generated key on `st.do` / `st.use` actually is.
+ *
+ * A slice publishes its keys with the model and the suffix spliced into the role name — `setPageOfUserInOrg` for the
+ * `setPageOfModel` role of `user`'s `inOrg` slice — and the splicing is string replacement over capitalized names.
+ * Recording the role while the key is being built is what saves a reader of the finished store from running that
+ * replacement backwards, which does not have one answer: on a model named `page`, `setPageOfPage` is both the
+ * paging action and a field setter.
+ */
+export interface SliceActionRole {
+  role: SliceActionKey;
+  refName: string;
+  sliceName: string;
+  /** The slice's own arguments, which the `initModel` and `setQueryArgsOfModel` roles take positionally. */
+  args: SerializedArg[];
+}
+
+export interface SliceStateRole {
+  role: SliceStateKey;
+  refName: string;
+  sliceName: string;
+}