akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/common/mcpExposure.ts

@@ -0,0 +1,114 @@
+import { capitalize } from "./capitalize";
+
+/**
+ * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
+ *
+ * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
+ * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
+ * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
+ *
+ * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
+ * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
+ */
+export interface McpExposureEndpoint {
+  type: string;
+  returns: { refName: string };
+  args: { name: string; refName: string; type: string; arrDepth?: number; nullable?: boolean }[];
+  guards?: string[];
+  fileUpload?: boolean;
+  mcp?: boolean;
+}
+
+export interface McpExposureOption {
+  /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
+  refName: string;
+  key: string;
+  /**
+   * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
+   * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
+   */
+  readOnly?: boolean;
+}
+
+/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+export const isMcpDescribableArg = (arg: { refName: string }) => arg.refName !== "Any";
+
+/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
+export const mcpBaseVerbOf = (refName: string, key: string) => {
+  const cap = capitalize(refName);
+  if (key === refName || key === `light${cap}`) return "get" as const;
+  if (key === `create${cap}`) return "create" as const;
+  if (key === `update${cap}`) return "update" as const;
+  if (key === `remove${cap}`) return "remove" as const;
+  return null;
+};
+
+/**
+ * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
+ * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
+ * database, not the wider internet.
+ */
+export const mcpHintsOf = (key: string, endpoint: { type: string }) => {
+  const readOnly = endpoint.type === "query";
+  const destructive = !readOnly && /^(remove|delete)/.test(key);
+  return {
+    readOnlyHint: readOnly,
+    destructiveHint: destructive,
+    idempotentHint: readOnly || /^(set|update)/.test(key),
+    openWorldHint: false,
+  };
+};
+
+/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
+export const mcpRefusalOf = (
+  endpoint: McpExposureEndpoint,
+  { refName, key, readOnly }: McpExposureOption,
+): string | null => {
+
+  if (endpoint.mcp === false)
+    return "it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.";
+
+  if (!endpoint.guards?.length)
+    return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
+
+  if (key === `light${capitalize(refName)}`)
+    return `it reads the same document as \`${refName}\` in a smaller shape — call \`${refName}\` instead.`;
+  if (endpoint.type === "prompt") return mcpPromptRefusalOf(endpoint);
+  if (endpoint.type === "pubsub" || endpoint.type === "message")
+    return `\`${endpoint.type}\` rides the websocket, and its internal arguments read a socket an MCP request does not have.`;
+  if (readOnly && endpoint.type !== "query")
+    return "this deployment is read-only, which drops every endpoint that is not a query.";
+  if (endpoint.returns.refName === "Any" || endpoint.returns.refName === "Upload")
+    return `a return typed \`${endpoint.returns.refName}\` cannot be described to a model.`;
+  if (endpoint.returns.refName === "Binary")
+    return "a return typed `Binary` is raw bytes, which cost a model its window and tell it nothing.";
+  if (endpoint.fileUpload || endpoint.args.some((arg) => arg.refName === "Upload"))
+    return "a file upload has no MCP representation.";
+  if (endpoint.type === "mutation" && !endpoint.guards.some((name) => name !== "Public"))
+    return "a mutation needs a real guard — `[Public]` is having none, spelled out.";
+  const opaque = endpoint.args.find((arg) => !isMcpDescribableArg(arg) && arg.type !== "search" && !arg.nullable);
+  if (opaque)
+    return `its required argument \`${opaque.name}\` is typed \`Any\`, which is left out of the published schema — expose a named filter slice instead.`;
+  return null;
+};
+
+/**
+ * A prompt is a read exposed on the same terms as a query, so every rejection here is one thing: an argument
+ * `prompts/get` cannot carry. Its `arguments` is a flat string map — one string per name, and no schema beside it
+ * — which rules out the argument *kinds* the builder already refuses and, just as surely, two argument *types* it
+ * accepts. A tool escapes both because it publishes a real JSON Schema.
+ */
+export const mcpPromptRefusalOf = (endpoint: McpExposureEndpoint): string | null => {
+  const carried = endpoint.args.find((arg) => arg.type === "body" || arg.type === "msg" || arg.type === "room");
+  if (carried)
+    return `a prompt's arguments travel as a flat string map, so its \`${carried.type}\` argument \`${carried.name}\` cannot be carried.`;
+
+  const list = endpoint.args.find((arg) => arg.arrDepth);
+  if (list)
+    return `a prompt argument is one string, so its list argument \`${list.name}\` could never carry more than one value.`;
+
+  const opaque = endpoint.args.find((arg) => !isMcpDescribableArg(arg));
+  if (opaque)
+    return `its argument \`${opaque.name}\` is typed \`Any\`, and a prompt has no schema in which to describe one.`;
+  return null;
+};

package/common/pathGetLoose.ts

@@ -0,0 +1,31 @@
+type Indexable = Record<string, unknown>;
+
+const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
+
+/**
+ * Reads a dotted path whose segments may themselves contain the separator.
+ *
+ * Dictionary keys are built as `<refName>.<value>` and an enum value is a real-world identifier — `gpt-5.6-terra`,
+ * `v1.2` — so the key is not a clean dotted path and `pathGet` splits it into segments that were never nodes.
+ * The tree stores such a key literally, so resolution has to try joined prefixes too.
+ */
+export const pathGetLoose = (
+  path: string | readonly string[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  const walk = (node: unknown, rest: readonly string[]): unknown => {
+    if (!rest.length) return node;
+    if (!isIndexable(node)) return undefined;
+    
+    for (let take = 1; take <= rest.length; take += 1) {
+      const child = node[rest.slice(0, take).join(separator)];
+      if (child === undefined) continue;
+      const found = walk(child, rest.slice(take));
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return walk(obj, Array.isArray(path) ? [...path] : (path as string).split(separator)) ?? fallback;
+};

package/common/pathSet.ts

@@ -1,16 +1,28 @@
 type MutableIndexable = Record<string | number, unknown>;
 type PathSegment = string | number;
+type Container = MutableIndexable | Map<PathSegment, unknown>;
 
 const toPathSegments = (path: string | readonly PathSegment[]) =>
   Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
 
+const readChild = (container: Container, key: PathSegment) =>
+  container instanceof Map ? container.get(key) : container[key];
+
+const writeChild = (container: Container, key: PathSegment, value: unknown) => {
+  if (container instanceof Map) container.set(key, value);
+  else container[key] = value;
+};
+
 export const pathSet = <T>(obj: T, path: string | readonly PathSegment[], value: unknown): T => {
   if (Object(obj) !== obj) return obj;
   const pathSegments = toPathSegments(path);
-  pathSegments.slice(0, -1).reduce<MutableIndexable>((a, c, i) => {
-    if (Object(a[c]) === a[c]) return a[c] as MutableIndexable;
-    a[c] = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
-    return a[c] as MutableIndexable;
-  }, obj as MutableIndexable)[pathSegments[pathSegments.length - 1]] = value;
+  const parent = pathSegments.slice(0, -1).reduce<Container>((a, c, i) => {
+    const child = readChild(a, c);
+    if (Object(child) === child) return child as Container;
+    const created = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
+    writeChild(a, c, created);
+    return created as unknown as Container;
+  }, obj as Container);
+  writeChild(parent, pathSegments[pathSegments.length - 1], value);
   return obj;
 };

package/common/plainFieldsOf.ts

@@ -0,0 +1,13 @@
+/**
+ * Own and inherited enumerable data of an object as a plain record. An Akan model keeps its Date fields as
+ * enumerable prototype accessors, which `Object.keys` and a spread never reach; methods are non-enumerable and stay
+ * out either way.
+ */
+export const plainFieldsOf = (source: object): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const key in source) {
+    const value = (source as Record<string, unknown>)[key];
+    if (typeof value !== "function") out[key] = value;
+  }
+  return out;
+};

package/common/routeConvention.ts

@@ -67,27 +67,37 @@ export function isRouteSourceFile(filePath: string): boolean {
   return tryParseRouteModuleKey(key) !== null;
 }
 
-export function validatePageSourceFile(filePath: string, options: ValidatePageSourceFileOptions = {}): boolean {
-  if (!SOURCE_EXT_RE.test(filePath)) return false;
+/**
+ * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
+ * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
+ * so the rule stays in one place instead of being restated where it cannot afford to throw.
+ */
+export function getPageSourceFileViolation(filePath: string): string | null {
+  if (!SOURCE_EXT_RE.test(filePath)) return null;
 
   const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
   const match = ROUTE_SOURCE_RE.exec(key);
-  const displayPath = options.filePath ?? key;
-  if (!match) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+  if (!match) return "invalid page source file";
 
   const file = match[1] as string;
   const ext = match[2] as string;
   const leaf = file.split("/").filter(Boolean).at(-1);
-  if (!leaf) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+  if (!leaf) return "invalid page source file";
 
-  if (ext !== "tsx") throw new Error(`[route-convention] route source files under page/ must use .tsx: ${displayPath}`);
+  if (ext !== "tsx") return "route source files under page/ must use .tsx";
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && leaf !== INTERNAL_ROOT_LAYOUT_LEAF)
-    throw new Error(
-      `[route-convention] only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/: ${displayPath}`,
-    );
-  if (/^[A-Z]/.test(leaf))
-    throw new Error(`[route-convention] route page filenames must not start with an uppercase letter: ${displayPath}`);
-  return true;
+    return "only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/";
+  if (/^[A-Z]/.test(leaf)) return "route page filenames must not start with an uppercase letter";
+  return null;
+}
+
+export function validatePageSourceFile(filePath: string, options: ValidatePageSourceFileOptions = {}): boolean {
+  if (!SOURCE_EXT_RE.test(filePath)) return false;
+
+  const violation = getPageSourceFileViolation(filePath);
+  if (!violation) return true;
+  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? key}`);
 }
 
 export function validateSubRoutePageKey(

package/common/websocketBinaryFrame.ts

@@ -0,0 +1,46 @@
+export interface WebsocketBinaryFrame {
+  roomId: string;
+  payload: Uint8Array;
+}
+
+const MAGIC = 0xab;
+const KIND_PUB = 0x01;
+const HEADER_BYTES = 4;
+const MAX_ROOM_BYTES = 0xffff;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Framework-owned binary pubsub frame, shared by the publisher and the client dispatcher. A room whose whole
+ * return is `Binary` sends its bytes in a websocket binary frame instead of the JSON `{ type: "pub" }` envelope,
+ * because `Buffer.toJSON()` turns bytes into `{ type: "Buffer", data: number[] }` — 3.6x the wire and ~300x the
+ * encode cost on a 64 KB payload, and a shape `JSON.parse` never restores.
+ *
+ * Text and binary frames coexist on one socket, so this is additive: every JSON endpoint is untouched, and a
+ * federation gateway relays a binary frame unchanged with no code of its own.
+ */
+export const websocketBinaryFrameContract = {
+  encode: ({ roomId, payload }: WebsocketBinaryFrame): Uint8Array => {
+    const room = encoder.encode(roomId);
+    if (room.length > MAX_ROOM_BYTES) throw new Error(`Room id is too long to frame: ${roomId}`);
+    const frame = new Uint8Array(HEADER_BYTES + room.length + payload.length);
+    frame[0] = MAGIC;
+    frame[1] = KIND_PUB;
+    frame[2] = room.length >> 8;
+    frame[3] = room.length & 0xff;
+    frame.set(room, HEADER_BYTES);
+    frame.set(payload, HEADER_BYTES + room.length);
+    return frame;
+  },
+  decode: (data: ArrayBuffer | Uint8Array): WebsocketBinaryFrame | null => {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.length < HEADER_BYTES || bytes[0] !== MAGIC || bytes[1] !== KIND_PUB) return null;
+    const roomBytes = (bytes[2] << 8) | bytes[3];
+    if (bytes.length < HEADER_BYTES + roomBytes) return null;
+    return {
+      roomId: decoder.decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + roomBytes)),
+      payload: bytes.subarray(HEADER_BYTES + roomBytes),
+    };
+  },
+} as const;

package/constant/crystalize.ts

@@ -8,38 +8,104 @@ import {
 } from "akanjs/base";
 
 import type { FieldProps } from ".";
+import { ConstantRegistry } from "./constantRegistry";
 
 export type CrystalizeFunc<Model> = (self: GetStateObject<Model>, isChild?: boolean) => Model;
+export type Converter = (value: unknown) => unknown;
 
-export const crystalize = (field: FieldProps, value: unknown): unknown => {
-  if (value === undefined || value === null) return value as undefined | null;
-  if (field.isArray && Array.isArray(value))
-    return value.map((v: unknown) =>
-      crystalize({ ...field, isArray: field.arrDepth > 1, arrDepth: field.arrDepth - 1 }, v),
-    );
-  const crystalizeValue = PrimitiveRegistry.has(field.modelRef)
-    ? (value: unknown) => (field.modelRef as unknown as typeof PrimitiveScalar)._parse(value as never)
-    : (value: unknown) => value as object;
-  if (field.isMap) {
-    const mapValueField = {
-      ...field,
-      modelRef: field.of ?? field.modelRef,
-      isMap: false,
-      isClass: !!field.of && !PrimitiveRegistry.has(field.of),
-      isScalar: !!field.of && PrimitiveRegistry.has(field.of),
-      isArray: false,
-      arrDepth: 0,
-    };
+/**
+ * The relation instances one hydration pass has already built, by model class and then document id.
+ *
+ * A listing hands the same relation to every row that references it — twenty users wearing one avatar — and
+ * each row would otherwise build its own copy of it, re-parsing every `Date` on the way. Sharing is safe
+ * because a constant model is `[immerable]`: a store write copies before it mutates.
+ *
+ * Module-scoped rather than passed down, because `crystalize` is reached through a model's own constructor,
+ * which has nowhere to carry it. A pass is wholly synchronous, so no other one can observe this mid-flight.
+ */
+let sharedInstances: Map<Cls, Map<string, object>> | null = null;
+
+/** Runs one hydration pass, sharing a relation instance across every value in it that names the same id. */
+export const withSharedInstances = <T>(hydrate: () => T): T => {
+  if (sharedInstances) return hydrate();
+  sharedInstances = new Map();
+  try {
+    return hydrate();
+  } finally {
+    sharedInstances = null;
+  }
+};
+
+type ModelCls = new (obj?: object) => object;
+
+const relationIdOf = (value: object): string | null => {
+  const id = (value as { id?: unknown }).id;
+  return typeof id === "string" && id ? id : null;
+};
+
+const modelConverterOf = (props: FieldProps): Converter => {
+  const modelRef = props.modelRef as unknown as ModelCls;
+
+  if (props.isScalar) return (value) => (value instanceof modelRef ? value : new modelRef(value as object));
+  return (value) => {
+    if (value instanceof modelRef) return value;
+
+    const id = relationIdOf(value as object);
+    if (!sharedInstances || !id) return new modelRef(value as object);
+    const byId = sharedInstances.get(modelRef as unknown as Cls) ?? new Map<string, object>();
+    if (!sharedInstances.has(modelRef as unknown as Cls)) sharedInstances.set(modelRef as unknown as Cls, byId);
+    const shared = byId.get(id) ?? new modelRef(value as object);
+    byId.set(id, shared);
+    return shared;
+  };
+};
+
+const mapConverterOf = (props: FieldProps): Converter => {
+  const of = props.of as Cls | undefined;
+  const valueConverter: Converter = of
+    ? singleConverterOf({
+        ...props,
+        modelRef: of as FieldProps["modelRef"],
+        isMap: false,
+        isClass: !PrimitiveRegistry.has(of),
+        isScalar: PrimitiveRegistry.has(of) || ConstantRegistry.isScalar(of),
+        isArray: false,
+        arrDepth: 0,
+      })
+    : (value) => value;
+  return (value) => {
+    
+    const entries = value instanceof Map ? [...value.entries()] : Object.entries(value as Record<string, unknown>);
     return new Map(
-      Object.entries(value as Record<string, unknown>).map(([key, val]) => [
-        key,
-        field.of
-          ? applyFnToArrayObjects(val, (v: never) => crystalize(mapValueField, v))
-          : applyFnToArrayObjects(val, crystalizeValue),
-      ]),
+      entries.map(([key, val]: [string, unknown]) => [key, applyFnToArrayObjects(val, valueConverter as never)]),
     );
+  };
+};
+
+const singleConverterOf = (props: FieldProps): Converter => {
+  if (props.isMap) return mapConverterOf(props);
+  if (props.isClass) return modelConverterOf(props);
+  
+  if ((props.modelRef as unknown) === Date) return (value) => dayjs(value as Date);
+  if (PrimitiveRegistry.has(props.modelRef as Cls))
+    return (value) => (props.modelRef as unknown as typeof PrimitiveScalar)._parse(value as never);
+  return (value) => value;
+};
+
+const converters = new WeakMap<FieldProps, Converter>();
+
+/** The converter for one field, compiled once per `FieldProps` — which `getProps()` freezes and shares per field. */
+export const converterOf = (props: FieldProps): Converter => {
+  const cached = converters.get(props);
+  if (cached) return cached;
+  const single = singleConverterOf(props);
+  let convert: Converter = (value) => (value === null || value === undefined ? value : single(value));
+  for (let depth = props.arrDepth; depth > 0; depth--) {
+    const inner: Converter = convert;
+    convert = (value: unknown): unknown => (Array.isArray(value) ? value.map(inner) : inner(value));
   }
-  if (field.isClass) return new (field.modelRef as Cls<{ set: (obj: object) => object }>)().set(value as object);
-  if (field.modelRef === Date) return dayjs(value as Date);
-  return crystalizeValue(value);
+  converters.set(props, convert);
+  return convert;
 };
+
+export const crystalize = (field: FieldProps, value: unknown): unknown => converterOf(field)(value);

package/constant/dateSlot.ts

@@ -0,0 +1,62 @@
+import { type Dayjs, dayjs } from "akanjs/base";
+
+/**
+ * A Date field stores a native `Date` under a per-key symbol and builds the `Dayjs` its type promises on first
+ * read, memoized by that `Date`. A dayjs instance is ~300 bytes and eight getter calls at construction; a `Date`
+ * is 40 bytes. A listing carries every row's dates and reads a handful of them, so this is most of what a
+ * hydrated list used to cost — see `crystalize`.
+ *
+ * The slot is a function of the key, not the class (`Symbol.for`): `applyMixins` copies a light model's accessors
+ * onto the full model's prototype, so an accessor and the `set()` that fills its slot must agree on the slot
+ * whichever class defined either one.
+ */
+const slotByKey = new Map<string, symbol>();
+export const dateSlotOf = (key: string): symbol => {
+  const cached = slotByKey.get(key);
+  if (cached) return cached;
+  const slot = Symbol.for(`akan.date.${key}`);
+  slotByKey.set(key, slot);
+  return slot;
+};
+
+const dayjsByDate = new WeakMap<Date, Dayjs>();
+const lazyDayjsOf = (date: Date): Dayjs => {
+  const cached = dayjsByDate.get(date);
+  if (cached) return cached;
+  const value = dayjs(date);
+  dayjsByDate.set(date, value);
+  return value;
+};
+
+/** A caller's own `Date` is copied: the slot must not alias an object the caller can still mutate. */
+export const toDateValue = (value: unknown): Date | null | undefined => {
+  if (value === null || value === undefined) return value;
+  if (value instanceof Date) return new Date(value.getTime());
+  if (dayjs.isDayjs(value)) return value.toDate();
+  return new Date(value as string | number);
+};
+
+type DateSlotHolder = Record<symbol, Date | null | undefined>;
+
+/**
+ * Enumerable so `for...in` — `plainFieldsOf`, `immerify`, `deepObjectify` — still sees the field. immer calls a
+ * prototype setter with the draft as `this`, so a write through the accessor stays copy-on-write, and the getter
+ * writes nothing, so a read never marks a draft modified.
+ */
+export const dateAccessorOf = (key: string): PropertyDescriptor => {
+  const slot = dateSlotOf(key);
+  return {
+    enumerable: true,
+    configurable: true,
+    get(this: DateSlotHolder) {
+      const date = this[slot];
+      return date === null || date === undefined ? date : lazyDayjsOf(date);
+    },
+    set(this: DateSlotHolder, value: unknown) {
+      this[slot] = toDateValue(value);
+    },
+  };
+};
+
+export const isDateSlotField = (props: { modelRef: unknown; isArray: boolean; isMap: boolean }): boolean =>
+  props.modelRef === Date && !props.isArray && !props.isMap;

package/constant/deserialize.ts

@@ -1,6 +1,6 @@
 import { Any, applyFnToArrayObjects, type Cls, FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
 
-import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps } from ".";
+import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps, withSharedInstances } from ".";
 
 const getDeserializeFn = (inputRef: ConstantModelRef | PrimitiveScalar) => {
   const deserializeFn = PrimitiveRegistry.has(inputRef as Cls)
@@ -66,5 +66,6 @@ export const deserialize = (
   if (nullable && (value === null || value === undefined)) return null;
   else if (!nullable && (value === null || value === undefined) && argRef !== Any)
     throw new Error(`Invalid Value (Nullable) in ${key} ${argRef} for value ${value}`);
-  return deserializeInput(value, argRef, arrDepth, convertFn) as object[];
+
+  return withSharedInstances(() => deserializeInput(value, argRef, arrDepth, convertFn)) as object[];
 };

package/constant/fieldInfo.ts

@@ -106,6 +106,13 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  /**
+   * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
+   * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
+   * placeholder still ships to `<Image>`. Unlike `hidden`/`secret` this is about cost, not secrecy: a field
+   * nothing can answer a question with is pure spend on every turn it rides.
+   */
+  visual?: boolean;
   meta?: Metadata;
 }
 export const fieldPresets = ["email", "password", "url"] as const;
@@ -197,6 +204,7 @@ interface ConstantFieldBuildProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  visual: boolean;
   modelRef: ConstantModelRef;
   arrDepth: number;
   optArrDepth: number;
@@ -321,6 +329,7 @@ export class ConstantField<
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
   readonly cascade?: CascadeAction;
+  readonly visual: boolean;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
   readonly optArrDepth: number;
@@ -353,6 +362,7 @@ export class ConstantField<
     this.validate = props.validate;
     this.text = props.text;
     this.cascade = props.cascade;
+    this.visual = props.visual;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
     this.optArrDepth = props.optArrDepth;
@@ -432,6 +442,7 @@ export class ConstantField<
       validate: option.validate,
       text: option.text,
       cascade: option.cascade,
+      visual: option.visual ?? false,
       modelRef,
       arrDepth: arrDepth,
       optArrDepth: optArrDepth,
@@ -478,6 +489,7 @@ export class ConstantField<
       validate: this.validate,
       text: this.text,
       cascade: this.cascade,
+      visual: this.visual,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,
       optArrDepth: this.optArrDepth,
@@ -493,6 +505,14 @@ export interface FieldObject {
   [key: string]: ConstantField;
 }
 
+/**
+ * `text` names a column in the plaintext search mirror, so a masked field carrying one would publish what it
+ * masks through search — the class build refuses it (`TextFieldPaths`). Removing the key from the option type
+ * moves that refusal to the call site, where the fix is obvious. Distributive because `FieldOption` is a union:
+ * a plain `Omit` over it would collapse to the keys the members share.
+ */
+type WithoutTextRole<Option> = Option extends unknown ? Omit<Option, "text"> : never;
+
 type FieldOption<
   Value extends ConstantFieldTypeInput,
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
@@ -530,13 +550,33 @@ export const field = <
     fieldType: "property",
   });
 
-field.hidden = <
+/**
+ * A stored property the page renders and an agent never sees — `field(value, { visual: true })`, spelled short
+ * because the reason to reach for it is always the same one. A blur placeholder, a rendered HTML body, a
+ * serialized geometry: real data the screen needs, and hundreds of tokens per record that no question is answered
+ * from. It stays a plain `property` everywhere else, so persistence, search, forms and the page response are
+ * untouched.
+ */
+field.visual = <
   ExplicitType,
   Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
   option: FieldOption<Value, MapValue> = {},
+) =>
+  new FieldInfo<"property", Value, ExplicitType, MapValue>(value, {
+    ...option,
+    fieldType: "property",
+    visual: true,
+  });
+field.hidden = <
+  ExplicitType,
+  Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
+  MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
+>(
+  value: Value,
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"hidden", Value, ExplicitType, MapValue>(value, {
     ...option,
@@ -549,7 +589,7 @@ field.secret = <
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
-  option: FieldOption<Value, MapValue> = {},
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"secret", Value | null, ExplicitType | null, MapValue>(value, {
     ...option,
@@ -564,7 +604,7 @@ export const resolve = <
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
 >(
   value: Value,
-  option: FieldOption<Value, MapValue> = {},
+  option: WithoutTextRole<FieldOption<Value, MapValue>> = {},
 ) =>
   new FieldInfo<"resolve", Value, ExplicitType, MapValue>(value, {
     ...option,

package/constant/fieldQueryMeta.ts

@@ -0,0 +1,35 @@
+import { FIELD_META } from "akanjs/base";
+import { ConstantRegistry } from "./constantRegistry";
+import type { FieldObject } from "./fieldInfo";
+
+/**
+ * The query a field's value stands for, declared on the field itself with `.meta(...)`. A summary counter is the
+ * case this exists for: `hau` is however many rows one filter returns, so the tile showing it can open that exact
+ * listing without the page restating the filter beside it.
+ *
+ * The shape is read structurally rather than by class, so an app declares it with whatever builder it already has.
+ */
+export interface FieldQueryMeta {
+  /** The model the query runs against. */
+  refName: string;
+  /** One of that model's declared filter keys. */
+  queryKey: string | null;
+  /** Read when the query is applied, so an arg relative to now — `() => [dayjs().subtract(1, "hour")]` — is current. */
+  queryArgs?: unknown[] | (() => unknown[]);
+}
+
+const isFieldQueryMeta = (meta: unknown): meta is FieldQueryMeta => {
+  if (!meta || typeof meta !== "object") return false;
+  const { refName, queryKey, queryArgs } = meta as Record<string, unknown>;
+  if (typeof refName !== "string" || !refName) return false;
+  if (queryKey !== null && typeof queryKey !== "string") return false;
+  return queryArgs === undefined || Array.isArray(queryArgs) || typeof queryArgs === "function";
+};
+
+/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
+export const fieldQueryMetaOf = (refName: string, field: string): FieldQueryMeta | undefined => {
+  const cnst = ConstantRegistry.getDatabase(refName, { allowEmpty: true });
+  const fieldMap = cnst?.full[FIELD_META] as FieldObject | undefined;
+  const meta = fieldMap?.[field]?.meta;
+  return isFieldQueryMeta(meta) ? meta : undefined;
+};