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

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,15 @@
 export * from "./action";
+export * from "./actionTag";
+export * from "./agent";
 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,4 +1,4 @@
-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 { StateDerivedMeta, StateInitializerMap } from "./stateBuilder";
 import type { SetGetWritable } from "./types";
@@ -20,6 +20,7 @@ export type RootStoreCls<
     [STATE_INIT_META]: StateInitializerMap;
     [STATE_DERIVED_META]: StateDerivedMeta;
     [ACTION_META]: { [key: string]: (...args: any[]) => any };
+    [ACTION_OWNER_META]: { [key: string]: string };
     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;
+}

package/store/state.ts

@@ -14,6 +14,7 @@ import type {
   SlceDbSort,
   SliceCls,
 } from "akanjs/signal";
+import { databaseStateNames } from "./databaseStateNames";
 import type { StoreSliceArgs, StoreSliceMap, StoreSliceSuffixCap, Submit } from "./types";
 
 export type SliceStateKey =
@@ -151,18 +152,7 @@ export type DefaultState<
 
 export const createDatabaseState = (refName: string) => {
   const cnst = ConstantRegistry.getDatabase(refName);
-  const [fieldName, className] = [refName, capitalize(refName)];
-  const names = {
-    model: fieldName,
-    Model: className,
-    modelLoading: `${fieldName}Loading`,
-    modelForm: `${fieldName}Form`,
-    modelFormLoading: `${fieldName}FormLoading`,
-    modelSubmit: `${fieldName}Submit`,
-    modelViewAt: `${fieldName}ViewAt`,
-    modelModal: `${fieldName}Modal`,
-    modelOperation: `${fieldName}Operation`,
-  };
+  const names = databaseStateNames(refName);
   const baseState = {
     [names.model]: null,
     [names.modelLoading]: true,

package/store/store.ts

@@ -1,5 +1,6 @@
 import {
   ACTION_META,
+  ACTION_OWNER_META,
   type Cls,
   type MergeAllActionTypes,
   type MergeAllKeyOfObjects,
@@ -120,6 +121,7 @@ export type StoreCls<
     [STATE_INIT_META]: StateInitializerMap;
     [STATE_DERIVED_META]: StateDerivedMeta;
     [ACTION_META]: { [key: string]: (...args: any[]) => any };
+    [ACTION_OWNER_META]: { [key: string]: string };
     slice: { [key: string]: SerializedSlice };
     _slice: SlceCls[typeof SLICE_META];
   }
@@ -187,6 +189,7 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     static [STATE_INIT_META] = {};
     static [STATE_DERIVED_META] = createEmptyDerivedMeta();
     static [ACTION_META] = {};
+    static [ACTION_OWNER_META] = {};
     static slice = {};
   } as StoreCls;
   const writableStateRaw = stateFactory(createWritableStateBuilder());
@@ -204,6 +207,7 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     writable.meta,
   );
   Object.assign(storeCls[ACTION_META], ...libStores.map((libStore) => libStore[ACTION_META]));
+  Object.assign(storeCls[ACTION_OWNER_META], ...libStores.map((libStore) => libStore[ACTION_OWNER_META] ?? {}));
   applyMixins(storeCls, libStores);
   if (signal) {
     const signalState = {
@@ -218,6 +222,7 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     };
     Object.assign(storeCls.prototype, actions);
     Object.assign(storeCls[ACTION_META], actions);
+    Object.assign(storeCls[ACTION_OWNER_META], Object.fromEntries(Object.keys(actions).map((key) => [key, refName])));
     Object.assign(storeCls.slice, signal.serializedSignal.slice ?? {});
   }
   if (derivedStateFactory) {

package/store/storeInstance.ts

@@ -1,10 +1,13 @@
-import { ACTION_META, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
+import { ACTION_META, ACTION_OWNER_META, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
 import { Translator } from "akanjs/client";
 import { capitalize, Logger, parseAkanI18nEnv } from "akanjs/common";
+import type { SerializedArg } from "akanjs/signal";
 import { enableMapSet, produce } from "immer";
 import type { RefObject } from "react";
+import { actionTagOf, tagAction } from "./actionTag";
 import { useEffect, useRef, useSyncExternalStore } from "./hooks";
 import type { RootStoreCls } from "./rootStore";
+import type { SliceActionKey, SliceActionRole, SliceStateRole } from "./sliceRole";
 import type { SliceStateKey } from "./state";
 import { evaluateInitializers, type SearchParamsState, type StateDerivedMeta } from "./stateBuilder";
 
@@ -14,16 +17,6 @@ type StoreStateRecord = Record<string, unknown>;
 type StoreAction = (...args: unknown[]) => unknown;
 type TranslationParam = Record<string, string | number>;
 
-type SliceActionKey =
-  | "initModel"
-  | "refreshModel"
-  | "selectModel"
-  | "setPageOfModel"
-  | "addPageOfModel"
-  | "setLimitOfModel"
-  | "setQueryArgsOfModel"
-  | "setSortOfModel";
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value && typeof value === "object" && !Array.isArray(value));
 
@@ -172,6 +165,41 @@ export class StoreInstance {
   do: { [key: string]: StoreAction } = {};
   slice: { [key: string]: unknown } = {};
 
+  readonly #sliceActionRoles = new Map<string, SliceActionRole>();
+  readonly #sliceStateRoles = new Map<string, SliceStateRole>();
+  readonly #actionArity = new Map<string, number>();
+  readonly #actionOwners = new Map<string, string>();
+
+  /** Which module declared each action. The dictionary node its words are written in is named after it. */
+  get actionOwners(): ReadonlyMap<string, string> {
+    return this.#actionOwners;
+  }
+
+  /**
+   * How many arguments each action declares.
+   *
+   * Recorded because `do[key]` is a rest-argument wrapper around the real method, so its own `length` is zero for
+   * everything — the arity is gone by the time anyone holding the instance could ask. A rest parameter on the method
+   * itself still reads as zero; nothing can recover that.
+   */
+  get actionArity(): ReadonlyMap<string, number> {
+    return this.#actionArity;
+  }
+
+  /** What each generated slice key is, for a reader that has only the finished store. See `SliceActionRole`. */
+  get sliceActionRoles(): ReadonlyMap<string, SliceActionRole> {
+    return this.#sliceActionRoles;
+  }
+
+  get sliceStateRoles(): ReadonlyMap<string, SliceStateRole> {
+    return this.#sliceStateRoles;
+  }
+
+  /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+  get derivedKeys(): ReadonlySet<string> {
+    return this.#derivedMeta.derivedKeys;
+  }
+
   constructor(store?: RootStoreCls) {
     if (store) this.addStore(store);
   }
@@ -189,6 +217,7 @@ export class StoreInstance {
       hasNewStateKey = true;
     }
     if (hasNewStateKey) this.#state = nextState;
+    for (const [key, refName] of Object.entries(store[ACTION_OWNER_META] ?? {})) this.#actionOwners.set(key, refName);
     this.#mergeActions(store[ACTION_META]);
     this.#extendAccessors(derivedState, store[ACTION_META]);
     this.#buildSlices(store);
@@ -199,6 +228,7 @@ export class StoreInstance {
   #mergeActions(actions: { [key: string]: StoreAction }) {
     for (const [k, method] of Object.entries(actions)) {
       this.#ctx[k] = (...args: unknown[]) => method.call(this.#ctx, ...args);
+      this.#actionArity.set(k, method.length);
     }
   }
 
@@ -208,11 +238,11 @@ export class StoreInstance {
         this.use[k] = () => this.sel((s) => s[k]);
         if (this.#derivedMeta.derivedKeys.has(k)) continue;
         const setKey = `set${capitalize(k)}`;
-        this.do[setKey] = (value: unknown) => this.set({ [k]: value });
+        this.do[setKey] = tagAction((value: unknown) => this.set({ [k]: value }), { action: setKey, state: k });
       }
     }
     for (const k of Object.keys(actions)) {
-      this.do[k] = async (...args: unknown[]) => {
+      const dispatch = async (...args: unknown[]) => {
         Logger.verbose(`${k} action loading...`);
         const start = Date.now();
         try {
@@ -225,6 +255,8 @@ export class StoreInstance {
           throw error;
         }
       };
+
+      this.do[k] = tagAction(dispatch, actionTagOf(actions[k]) ?? { action: k });
     }
   }
 
@@ -254,7 +286,7 @@ export class StoreInstance {
     });
   }
 
-  #buildSlice(refName: string, sliceName: string, serializedSlice: { args?: any[] }) {
+  #buildSlice(refName: string, sliceName: string, serializedSlice: { args?: SerializedArg[] }) {
     const [fieldName, className] = [refName, capitalize(refName)];
     const names: { [key in SliceStateKey | SliceActionKey | "model" | "Model"]: string } = {
       model: fieldName,
@@ -324,14 +356,20 @@ export class StoreInstance {
       argLength: serializedSlice.args?.length ?? 0,
     };
 
+    const args = serializedSlice.args ?? [];
     for (const key of Object.keys(namesOfSliceAction) as SliceActionKey[]) {
       const rootActionKey = namesOfSliceAction[key];
-      if (this.do[rootActionKey]) targetSlice.do[names[key]] = this.do[rootActionKey];
+      if (!this.do[rootActionKey]) continue;
+      targetSlice.do[names[key]] = this.do[rootActionKey];
+      this.#sliceActionRoles.set(rootActionKey, { role: key, refName, sliceName, args });
     }
 
     for (const key of Object.keys(namesOfSliceState) as SliceStateKey[]) {
       const rootStateKey = namesOfSliceState[key];
-      if (this.use[rootStateKey]) targetSlice.use[names[key]] = this.use[rootStateKey];
+      if (this.use[rootStateKey]) {
+        targetSlice.use[names[key]] = this.use[rootStateKey];
+        this.#sliceStateRoles.set(rootStateKey, { role: key, refName, sliceName });
+      }
       const setRootKey = `set${capitalize(rootStateKey)}`;
       const setLocalKey = `set${capitalize(names[key])}`;
       if (this.do[setRootKey]) targetSlice.do[setLocalKey] = this.do[setRootKey];

package/store/storeRegistry.ts

@@ -1,5 +1,6 @@
 import {
   ACTION_META,
+  ACTION_OWNER_META,
   type MergeAllKeyOfObjects,
   type MergeAllKeyOfTypes,
   type MergeAllTypes,
@@ -37,15 +38,23 @@ function getStoreRegistryState(): StoreRegistryState {
 
 export class StoreRegistry {
   static #state = getStoreRegistryState();
+  /** The one store every `st.use` / `st.do` in the process goes through. What an agent bridge drives. */
+  static get instance(): StoreInstance {
+    return StoreRegistry.#state.instance;
+  }
   static register<StrCls extends StoreCls>(store: StrCls): StrCls {
     const parentStore = Object.getPrototypeOf(store) as StoreCls | null;
     const actions = { ...(parentStore?.[ACTION_META] ?? {}) };
+
+    const owners = { ...(parentStore?.[ACTION_OWNER_META] ?? {}) };
     Object.entries(Object.getOwnPropertyDescriptors(store.prototype)).forEach(([key, descriptor]) => {
       if (key === "constructor") return;
       if (!descriptor.value || typeof descriptor.value !== "function") return;
       actions[key] = descriptor.value;
+      owners[key] = store.refName;
     });
     store[ACTION_META] = actions;
+    store[ACTION_OWNER_META] = owners;
     StoreRegistry.#state.store.set(store.refName, store);
     return store;
   }
@@ -69,6 +78,7 @@ export class StoreRegistry {
       static [STATE_INIT_META] = Object.assign({}, ...stores.map((store) => store[STATE_INIT_META]));
       static [STATE_DERIVED_META] = mergeDerivedMeta(...stores.map((store) => store[STATE_DERIVED_META]));
       static [ACTION_META] = Object.assign({}, ...stores.map((store) => store[ACTION_META]));
+      static [ACTION_OWNER_META] = Object.assign({}, ...stores.map((store) => store[ACTION_OWNER_META] ?? {}));
       static slice: { [key: string]: { [key: string]: SerializedSlice } } = {};
     }
     stores.forEach((store) => {

package/types/base/symbols.d.ts

@@ -13,6 +13,10 @@ export declare const STATE_META: unique symbol;
 export declare const STATE_INIT_META: unique symbol;
 export declare const STATE_DERIVED_META: unique symbol;
 export declare const ACTION_META: unique symbol;
+/** Which module declared each action, which is the dictionary node its words are written in. */
+export declare const ACTION_OWNER_META: unique symbol;
+/** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
+export declare const ACTION_TAG: unique symbol;
 export declare const SERVER_VALUE: unique symbol;
 export declare const CLIENT_VALUE: unique symbol;
 export declare const DEFAULT_VALUE: unique symbol;

package/types/constant/index.d.ts

@@ -5,6 +5,7 @@ export * from "./deserialize.d.ts";
 export * from "./fieldInfo.d.ts";
 export * from "./getDefault.d.ts";
 export * from "./immerify.d.ts";
+export * from "./mask.d.ts";
 export * from "./purify.d.ts";
 export * from "./serialize.d.ts";
 export * from "./textFieldPathSet.d.ts";

package/types/constant/mask.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A model as masking reads it — the constructor, for the field metadata it carries at runtime.
+ *
+ * Structural rather than `ConstantModelRef` so that anything holding the class can name it, and read through
+ * `FIELD_META` the way `resolveReturn` reads it.
+ */
+export interface MaskModel {
+    name: string;
+}
+/** The part of a field's metadata masking turns on. Mirrors what `resolveReturn` branches over. */
+interface MaskField {
+    fieldType?: string;
+    isClass?: boolean;
+    modelRef?: MaskModel;
+}
+export declare const maskFieldsOf: (model: MaskModel) => Record<string, MaskField> | null;
+/** The `hidden` and `secret` field names of `model` that `value` still carries populated. */
+export declare const leakingFieldsOf: (model: MaskModel, value: Record<string, unknown>) => string[];
+/**
+ * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the value
+ * happens to still carry.
+ *
+ * That distinction is the whole point. A check that reads the class off the value can only mask what arrives as an
+ * instance, so a `{ ...doc }` spread, a `toJSON()`, an `immerify()`, or a round-trip through `JSON.stringify` reaches
+ * its destination with the metadata already gone and nothing can be done about it. A named model is metadata the
+ * value cannot lose, so a hydrated document and a plain object copied out of one mask identically.
+ *
+ * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every relation
+ * it walks past, which is right for a query's return value and wrong here, where the value is already in hand.
+ *
+ * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type promises.
+ */
+export declare const mask: (model: MaskModel, value: unknown) => unknown;
+export {};

package/types/dictionary/dictInfo.d.ts

@@ -180,8 +180,15 @@ export declare class ModelDictInfo<Languages extends [string, ...string[]] = [st
         [K in Enum["value"]]: FieldTranslation<Languages>;
     };
 }
-type AnyModelDictInfo = ModelDictInfo<any, any, any, any, any, any, any, any, any, any, any>;
-type MergeTwoModelDicts<ModelDict1, ModelDict2> = ModelDict1 extends ModelDictInfo<infer Languages1, infer ModelKey1, infer InsightKey1, infer QueryKey1, infer SortKey1, infer EnumKey1, infer BaseSignalKey1, infer SliceKey1, infer EndpointKey1, infer ErrorKey1, infer EtcKey1> ? ModelDict2 extends ModelDictInfo<infer _Languages2, infer ModelKey2, infer InsightKey2, infer QueryKey2, infer SortKey2, infer EnumKey2, infer BaseSignalKey2, infer SliceKey2, infer EndpointKey2, infer ErrorKey2, infer EtcKey2> ? ModelDictInfo<Languages1, ModelKey1 | ModelKey2, InsightKey1 | InsightKey2, QueryKey1 | QueryKey2, SortKey1 | SortKey2, EnumKey1 | EnumKey2, BaseSignalKey1 | BaseSignalKey2, SliceKey1 | SliceKey2, EndpointKey1 | EndpointKey2, ErrorKey1 | ErrorKey2, EtcKey1 | EtcKey2> : ModelDict1 : never;
+/**
+ * Every parameter of `ModelDictInfo` is listed here positionally, so a parameter added to the class has to be
+ * added to all three lists below in the same slot. Omitting one does not fail to compile — inference silently
+ * shifts, so the last parameter falls off the end and becomes its default `never`: adding `StoreKey` before
+ * `ErrorKey` once cost an extending app the whole of the lib's `EtcKey` (`.translate()`) union, which reads at
+ * the call site as `l("<model>.<key>")` no longer existing.
+ */
+type AnyModelDictInfo = ModelDictInfo<any, any, any, any, any, any, any, any, any, any, any, any>;
+type MergeTwoModelDicts<ModelDict1, ModelDict2> = ModelDict1 extends ModelDictInfo<infer Languages1, infer ModelKey1, infer InsightKey1, infer QueryKey1, infer SortKey1, infer EnumKey1, infer BaseSignalKey1, infer SliceKey1, infer EndpointKey1, infer StoreKey1, infer ErrorKey1, infer EtcKey1> ? ModelDict2 extends ModelDictInfo<infer _Languages2, infer ModelKey2, infer InsightKey2, infer QueryKey2, infer SortKey2, infer EnumKey2, infer BaseSignalKey2, infer SliceKey2, infer EndpointKey2, infer StoreKey2, infer ErrorKey2, infer EtcKey2> ? ModelDictInfo<Languages1, ModelKey1 | ModelKey2, InsightKey1 | InsightKey2, QueryKey1 | QueryKey2, SortKey1 | SortKey2, EnumKey1 | EnumKey2, BaseSignalKey1 | BaseSignalKey2, SliceKey1 | SliceKey2, EndpointKey1 | EndpointKey2, StoreKey1 | StoreKey2, ErrorKey1 | ErrorKey2, EtcKey1 | EtcKey2> : ModelDict1 : never;
 type MergeModelDicts<ModelDicts extends AnyModelDictInfo[]> = ModelDicts extends [
     infer First extends AnyModelDictInfo,
     ...infer Rest extends AnyModelDictInfo[]

package/types/fetch/client/fetchClient.d.ts

@@ -34,6 +34,15 @@ export declare class FetchClient {
     constructor(origin: string, handler?: Record<string, FetchHandler>, serializedSignal?: {
         [key: string]: SerializedSignal;
     }, ErrorCls?: ErrorConstructor | undefined);
+    /**
+     * Every signal any client in this process has applied, which is the whole callable surface of the app.
+     *
+     * A copy, because this is the registry each client merges its own signals into and a reader that mutated it
+     * would change what the next client applies. Read by the agent catalogue, which needs the argument schemas.
+     */
+    static get sharedSerializedSignal(): {
+        [key: string]: SerializedSignal;
+    };
     static resetSharedRegistry(): void;
     static resetSharedClient(): void;
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;

package/types/service/predefinedAdaptor/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
+export * from "./insightQuery.d.ts";
 export * from "./logging.adaptor";
 export * from "./queue.adaptor";
 export * from "./role.adaptor";

package/types/service/predefinedAdaptor/insightQuery.d.ts

@@ -0,0 +1,50 @@
+import type { AkanSqlClient } from "./database.adaptor";
+export interface InsightQueryOptions {
+    /** Rows to return at most. Clamped to `InsightQuery.maxRows`, which no caller can raise. */
+    limit?: number;
+    /** How long to wait for the driver, in ms. See the note on `#raced` for which dialects this can actually stop. */
+    timeoutMs?: number;
+}
+export interface InsightQueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    /** The ceiling cut the answer short, so the caller knows not to read it as complete. */
+    truncated: boolean;
+}
+/**
+ * One read-only SQL statement, for an agent or an operator asking a question the domain endpoints cannot express.
+ *
+ * This is the layer-bypassing read, and every safeguard the framework has is bypassed with it — guards, soft delete,
+ * cascade, `_postRemove`, and the `hidden`/`secret` masking every other response path performs. So it is read-only
+ * by construction rather than by convention, and it is deliberately *not* wired to an endpoint here: the framework
+ * owns no guard strong enough to sit in front of it. An app that wants it writes the endpoint with its own
+ * `SuperAdmin`, the same way guards ship with the library that owns the model.
+ *
+ * Three things enforce read-only, and only the third is ours:
+ *
+ * 1. The statement is wrapped as a derived table — `SELECT * FROM (<sql>) AS "akanInsight" LIMIT ?`. Nothing but a
+ *    query is legal in that position, in either dialect, so a write is a syntax error from the engine rather than a
+ *    pattern this code had to recognise. A second statement smuggled behind `;` is a syntax error for the same
+ *    reason, and the row ceiling rides along on the same wrapper.
+ * 2. A rejection before execution, so the caller reads why rather than a syntax error. It runs on the statement with
+ *    comments and string literals removed, because that is what makes `-- ` and `'…'` unable to hide anything.
+ * 3. **`_doc` never crosses the boundary.** Every non-base field lives in that one JSON column, which is where the
+ *    plan's "re-apply schema-based masking" runs into the fact that an arbitrary SELECT has no model to mask by. So
+ *    the enforceable rule is the column itself: unnameable in the statement, dropped from the rows, and any cell
+ *    that still arrives holding a JSON object or array is refused. An insight is made of scalars; a value that is
+ *    not one is either a document or indistinguishable from it.
+ *
+ * What that costs is real and worth saying: this answers "how many, since when, grouped how" over base columns and
+ * the search mirror, and it cannot read a domain field. Field-level reads go through the domain tools, which mask.
+ */
+export declare class InsightQuery {
+    #private;
+    /** Not an option. A caller asking for more gets this, because the point is that no caller sets the ceiling. */
+    static readonly maxRows = 1000;
+    constructor(client: AkanSqlClient);
+    run(sql: string, { limit, timeoutMs }?: InsightQueryOptions): Promise<{
+        columns: string[];
+        rows: Record<string, unknown>[];
+        truncated: boolean;
+    }>;
+}

package/types/signal/mcp/Msg.d.ts

@@ -1,3 +1,4 @@
+import { type MaskModel } from "akanjs/constant";
 import type { JsonSchema } from "../schema.d.ts";
 export type PromptRole = "user" | "assistant";
 /**
@@ -60,11 +61,9 @@ export interface PromptFileSource {
 }
 /**
  * A model class, named by the caller so an attachment can be masked by what it *is* rather than by what it still
- * carries at runtime. Structural, and read through `FIELD_META` the way `resolveReturn` reads it.
+ * carries at runtime. The same model any other audience masks by — see `mask` in `akanjs/constant`.
  */
-export interface PromptModel {
-    name: string;
-}
+export type PromptModel = MaskModel;
 /**
  * Builds the messages a `prompt()` endpoint returns.
  *

package/types/store/actionTag.d.ts

@@ -0,0 +1,17 @@
+export interface ActionTag {
+    /** The `st.do` key this function is. */
+    action: string;
+    /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
+    state?: string;
+}
+/**
+ * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
+ *
+ * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
+ * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
+ * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
+ *
+ * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
+ */
+export declare const tagAction: <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag) => T;
+export declare const actionTagOf: (value: unknown) => ActionTag | undefined;

package/types/store/agent/AgentBridge.d.ts

@@ -0,0 +1,70 @@
+import type { AgentRefusal, AgentUndescribed, JsonSchema, SerializedSignal } from "akanjs/signal";
+import type { StoreInstance } from "../storeInstance.d.ts";
+import type { SerializedStoreState, StoreActionEffect } from "./types.d.ts";
+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 declare class AgentBridge {
+    #private;
+    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[];
+    /**
+     * 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): AgentBridge;
+    constructor(instance: StoreInstance, serializedSignal: Record<string, SerializedSignal>, options?: AgentBridgeOptions);
+    get state(): {
+        [key: string]: SerializedStoreState;
+    };
+    get transcript(): readonly AgentCall[];
+    subscribe(listener: () => void): () => void;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    call(name: string, args?: Record<string, unknown>): Promise<void>;
+}

package/types/store/agent/StoreCatalogue.d.ts

@@ -0,0 +1,21 @@
+import type { AgentRefusal, SerializedSignal } from "akanjs/signal";
+import type { StoreInstance } from "../storeInstance.d.ts";
+import type { SerializedStore } from "./types.d.ts";
+/**
+ * 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 declare class StoreCatalogue {
+    #private;
+    readonly store: SerializedStore;
+    readonly refusals: AgentRefusal[];
+    constructor(instance: StoreInstance, serializedSignal: Record<string, SerializedSignal>);
+}

package/types/store/agent/index.d.ts

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