@ultimat3/action 20.2.1 → 22.0.0

package/src/mutator.ts

@@ -5,18 +5,22 @@
  * contract tests for free, and its authz is the same single evaluation.
  */
 
-import type { Ctx } from '@ultimat3/core';
-import { assertNever } from '@ultimat3/core';
+import type { ConflictPolicy, Ctx, Row } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import type { Action, ActionCache, ActionDef, ActionDescriptor, ActionMcp } from './action';
+import type {
+  Action,
+  ActionCache,
+  ActionDef,
+  ActionDescriptor,
+  ActionMcp,
+  ActionRateLimit,
+  ActionRowArgs,
+} from './action';
 import { action, isAction } from './action';
+import type { Deprecation } from './deprecation';
+import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
 
-/** Minimum shape of a locally-stored row: an id the local twin can address. */
-export interface LocalRow {
-  readonly id: string;
-}
-
 /**
  * Augmented by the app so `tx.posts` is typed:
  *
@@ -33,43 +37,69 @@ export interface LocalTables {
 
 export type LocalTableName = Exclude<keyof LocalTables, '~ultimate'>;
 
-export interface LocalTable<TRow extends LocalRow> {
-  insert(row: TRow): void;
-  update(id: string, patch: Partial<TRow> | ((row: TRow) => Partial<TRow>)): void;
-  delete(id: string): void;
+/**
+ * One table as a mutator's `local` half sees it — the SAME shape as `@ultimat3/realtime`'s store tx
+ * (`record-tx.ts`), so a twin typed against this runs against the page's record store unchanged.
+ * Rows are addressed by KEY, never by a column: the browser holds no entity schema and cannot know
+ * a primary key, so an optimistic insert names the key its server twin will answer under.
+ */
+export interface LocalTable<TRow extends object = Row> {
+  get(key: string): TRow | undefined;
+  all(): readonly TRow[];
+  insert(key: string, row: TRow): void;
+  /** Merged over what the table holds; an `undefined` field leaves the column alone. */
+  upsert(key: string, row: TRow): void;
+  /** Changed fields only — or a function returning them. A no-op for a key the table does not hold. */
+  update(key: string, patch: Partial<TRow> | ((row: TRow) => Partial<TRow>)): void;
+  delete(key: string): void;
 }
 
 /**
- * The client-side write surface a mutator's `local()` gets. @ultimat3/realtime
- * implements it over OPFS SQLite; tests implement it over a Map.
+ * The client-side write surface a mutator's `local()` gets. `@ultimat3/realtime` implements it over
+ * the page's record store; tests implement it over a Map.
  */
 export type LocalTx = {
-  readonly [K in LocalTableName]: LocalTable<Extract<LocalTables[K], LocalRow>>;
+  readonly [K in LocalTableName]: LocalTable<Extract<LocalTables[K], object>>;
 } & {
   /** Escape hatch for generated code that only knows the table name as a string. */
-  table<TRow extends LocalRow>(name: string): LocalTable<TRow>;
+  table<TRow extends object = Row>(name: string): LocalTable<TRow>;
 };
 
-export interface CustomConflict<TOutput> {
-  readonly strategy: 'custom';
-  merge(local: TOutput, server: TOutput): TOutput;
-}
-
-export type Conflict<TOutput> = 'server-wins' | 'last-write-wins' | CustomConflict<TOutput>;
-
-export function custom<TOutput>(
-  merge: (local: TOutput, server: TOutput) => TOutput,
-): CustomConflict<TOutput> {
-  return { strategy: 'custom', merge };
+/**
+ * `conflict: custom(merge)` — core's row-shaped `ConflictPolicy`, built. `merge` receives the local
+ * ROW and the server ROW, because the client store is row-shaped: the output-shaped variant this
+ * replaced was dropped silently by realtime's rebase, which only ever had rows to hand it.
+ *
+ * `TRow` is the app's declared row shape, a caller-side annotation only — at rebase the resolver
+ * hands over whatever the store holds for that record, which is the entity's row.
+ */
+export function custom<TRow extends object = Row>(
+  merge: (local: TRow, server: TRow) => TRow,
+): ConflictPolicy {
+  // The one widening in the vocabulary: core's policy is over `Row`, the app's merge over its row.
+  return { kind: 'custom', merge: merge as unknown as (local: Row, server: Row) => Row };
 }
 
-export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1> {
+export interface MutatorDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TRow = unknown,
+> {
   readonly input: TInput;
   readonly output: TOutput;
-  readonly policy: ActionPolicy;
+  readonly policy: ActionPolicy<TRow>;
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
+  /** Same key, same meaning as an action's — a mutator IS an action. */
+  readonly rateLimit?: ActionRateLimit;
+  /** Same key, same meaning as an action's: `Deprecation`/`Sunset` on every response. */
+  readonly deprecated?: Deprecation;
   readonly idempotent?: boolean;
+  /**
+   * The row a row-level `policy` decides about — an action's `row`, and dropped on the way into
+   * the action until 2026-09-23, so such a policy received `row === null` and denied every call.
+   */
+  row?(args: ActionRowArgs<TInput>): TRow | null | Promise<TRow | null>;
   /**
    * Record every attempt through the installed `AuditSink`. Same key, same meaning as an
    * action's — a mutator IS an action, so it inherits the seam rather than getting a second one.
@@ -84,7 +114,7 @@ export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends Sta
     ctx: Ctx,
     input: InferOutput<TInput>,
   ): Promise<InferOutput<TOutput>> | InferOutput<TOutput>;
-  readonly conflict: Conflict<InferOutput<TOutput>>;
+  readonly conflict: ConflictPolicy;
 }
 
 export type MutatorDescriptor = Omit<ActionDescriptor, 'kind'> & {
@@ -102,7 +132,7 @@ export interface Mutator<
    * Renaming it here would silently turn every mutator back into a plain action downstream.
    */
   readonly isMutator: true;
-  readonly conflict: Conflict<InferOutput<TOutput>>;
+  readonly conflict: ConflictPolicy;
   /**
    * Applied on the client before the server round trip, and replayed on every
    * rebase — so it must stay a pure function of `(tx, input)`: no I/O, no clock,
@@ -120,19 +150,27 @@ export interface Mutator<
   named(name: string): Mutator<TInput, TOutput>;
 }
 
-export function mutator<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
-  def: MutatorDef<TInput, TOutput>,
-): Mutator<TInput, TOutput> {
-  const actionDef: ActionDef<TInput, TOutput> = {
+export function mutator<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TRow = unknown,
+>(def: MutatorDef<TInput, TOutput, TRow>): Mutator<TInput, TOutput> {
+  const row = def.row;
+  const actionDef: ActionDef<TInput, TOutput, TRow> = {
     input: def.input,
     output: def.output,
     policy: def.policy,
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
     ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };
+  // Before the action is built: a policy that cannot do what it says is refused at declaration.
+  if (def.conflict === 'last-write-wins') assertConflictClock(def.output);
   return wrap(def, action(actionDef));
 }
 
@@ -174,28 +212,7 @@ function wrap<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>
   return self;
 }
 
-export function strategyOf<TOutput>(
-  conflict: Conflict<TOutput>,
-): 'server-wins' | 'last-write-wins' | 'custom' {
-  return typeof conflict === 'string' ? conflict : conflict.strategy;
-}
-
-/**
- * Rebase decision for @ultimat3/realtime: which value survives when the local
- * twin and the server disagree.
- */
-export function resolveConflict<TOutput>(
-  conflict: Conflict<TOutput>,
-  local: TOutput,
-  server: TOutput,
-): TOutput {
-  if (typeof conflict !== 'string') return conflict.merge(local, server);
-  switch (conflict) {
-    case 'server-wins':
-      return server;
-    case 'last-write-wins':
-      return local;
-    default:
-      return assertNever(conflict);
-  }
+/** The descriptor's name for a policy — the manifest and `x actions describe` print this. */
+function strategyOf(conflict: ConflictPolicy): MutatorDescriptor['conflict'] {
+  return typeof conflict === 'string' ? conflict : conflict.kind;
 }

package/src/naming.ts

@@ -5,70 +5,25 @@
  * derived by nothing — it is the export name verbatim.
  */
 
-/** Irregular plurals we actually hit in domain models. Extend deliberately, not eagerly. */
-const IRREGULAR: Readonly<Record<string, string>> = {
-  person: 'people',
-  child: 'children',
-  man: 'men',
-  woman: 'women',
-  datum: 'data',
-  index: 'indexes',
-  entry: 'entries',
-};
-
-export interface ActionPath {
-  /** First camelCase word, kebab-cased. `publishPost` -> `publish`. */
-  readonly verb: string;
-  /** Remaining words, last one pluralized, kebab-cased. `publishPost` -> `posts`. */
-  readonly resource: string;
-  /** `POST /api/<resource>/<verb>`. */
-  readonly path: string;
-}
-
-/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
-export function splitWords(name: string): string[] {
-  return name
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .split(/[\s_-]+/)
-    .filter((word) => word.length > 0)
-    .map((word) => word.toLowerCase());
-}
+import type { ActionRoute } from '@ultimat3/core';
+import { actionRoute, splitWords } from '@ultimat3/core';
 
 /**
- * Naive-on-purpose English pluralizer. A word that already ends in `s` is left
- * alone, so `publishPosts` and `publishPost` agree on the `posts` resource.
+ * The path rule is `@ultimat3/core`'s `client-paths.ts` — the typed client, the route and the
+ * spec derive one URL from one function. Re-exported by name so `@ultimat3/action`'s public
+ * `derivePath` / `pluralize` / `splitWords` / `ActionPath` keep resolving; never re-declared here.
  */
-export function pluralize(word: string): string {
-  // `Object.hasOwn`, never a truthiness check on the read: `IRREGULAR['constructor']` is the
-  // `Object` FUNCTION off the prototype chain, not `undefined`, and `splitWords` lowercases —
-  // which keeps `toString` out of reach and lets `constructor` straight through. `pluralize` is
-  // public API returning `string`, and `derivePath` publishes what it answers as the action's
-  // HTTP path, its OpenAPI `paths` key and its `tags` entry.
-  if (Object.hasOwn(IRREGULAR, word)) return IRREGULAR[word] ?? word;
-  if (word.endsWith('s')) return word;
-  if (/(x|z|ch|sh)$/.test(word)) return `${word}es`;
-  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
-  return `${word}s`;
-}
+export { pluralize, splitWords } from '@ultimat3/core';
+
+export type ActionPath = ActionRoute;
 
 /**
  * `publishPost`        -> POST /api/posts/publish
  * `updateUserProfile`  -> POST /api/user-profiles/update
- * `likePost`           -> POST /api/posts/like
  * `checkout`           -> POST /api/checkouts/invoke   (single-word fallback)
  */
 export function derivePath(name: string): ActionPath {
-  const words = splitWords(name);
-  const head = words[0] ?? 'invoke';
-  if (words.length < 2) {
-    const resource = pluralize(head);
-    return { verb: 'invoke', resource, path: `/api/${resource}/invoke` };
-  }
-  const nouns = words.slice(1);
-  const last = nouns[nouns.length - 1] ?? head;
-  const resource = [...nouns.slice(0, -1), pluralize(last)].join('-');
-  return { verb: head, resource, path: `/api/${resource}/${head}` };
+  return actionRoute(name);
 }
 
 // There is deliberately no `toToolName`. An MCP tool name is the export name verbatim — the one

package/src/record-wire.ts

@@ -0,0 +1,32 @@
+/**
+ * The record envelope, on the action's HTTP projection only. Derived from the output schema — an
+ * action whose output references an entity row answers `{ data, records }` under
+ * `x-ultimate-records: 1`; every other action's body is byte-identical to what it always was.
+ */
+
+import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
+import { hasEntityRows, rowsOf } from '@ultimat3/entity';
+import { json } from '@ultimat3/http';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+
+/** The header value that says "this body is an envelope". Presence alone is not enough. */
+const ENVELOPED = '1';
+
+// The OpenAPI half — the 200 body and its header — is core's `recordEnvelopeSchema` and
+// `RECORDS_OPENAPI_HEADER`, shared with `@ultimat3/query` so both projections describe one shape.
+
+/**
+ * Decided ONCE per action, at projection, from the schema — never per response from the data.
+ * A body whose shape depended on whether this call happened to return rows would need two
+ * OpenAPI shapes for one operation; a schema-derived answer needs exactly one.
+ */
+export function carriesRecords(output: StandardSchemaV1): boolean {
+  return hasEntityRows(output);
+}
+
+/** The 200 for an action that carries records: the envelope, and the header that names it. */
+export function recordResponse(output: StandardSchemaV1, result: unknown): Response {
+  const response = json(encodeRecordEnvelope(result, rowsOf(output, result)));
+  response.headers.set(RECORDS_HEADER, ENVELOPED);
+  return response;
+}

package/src/transition.ts

@@ -18,7 +18,7 @@ import type {
   StringSchema,
 } from '@ultimat3/schema';
 import { t } from '@ultimat3/schema';
-import { type LocalRow, type Mutator, mutator } from './mutator';
+import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
 /**
@@ -126,9 +126,9 @@ export function transition<
       const input = valuesOf(raw);
       // `as Partial<…>`: a computed key widens to an index signature, which is never assignable to
       // a `Partial` of a type parameter. `def.column` is `keyof Row`, so the shape is a real one.
-      tx.table<Row & LocalRow>(def.localTable).update(input.id, {
+      tx.table<Row>(def.localTable).update(input.id, {
         [def.column]: input.to,
-      } as Partial<Row & LocalRow>);
+      } as Partial<Row>);
     },
     // No cast on `from`/`to`: they are the enum's own union, which is `Row[K]`. And no legality
     // check here — `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` are

package/src/type-pins.ts

@@ -3,10 +3,12 @@
 // type-level claim written in one can never fail. This module emits nothing and exports nothing
 // anybody imports — a regression here is a build error, the only enforcement that counts.
 
+import type { Row } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action, AnyAction } from './action';
 import type { ClientMethod } from './client';
 import type { ActionJobHandle } from './job-handle';
+import type { LocalTable } from './mutator';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -43,3 +45,17 @@ export type _ErasedClientIsNotASupertype = Assert<
     ? false
     : true
 >;
+
+/**
+ * A mutator's `tx` table is `@ultimat3/realtime`'s store tx, member for member — the store is what
+ * a twin runs against, so a member here it lacks is a twin that typechecks and throws. Pinned by
+ * the member set because realtime (tier 3, sideways) cannot be imported to compare the types.
+ */
+export type _LocalTableIsTheStoreTxShape = Assert<
+  Equals<keyof LocalTable, 'get' | 'all' | 'insert' | 'upsert' | 'update' | 'delete'>
+>;
+
+/** Addressed by KEY: an insert names the key its server twin answers under, never a column. */
+export type _LocalInsertTakesTheKey = Assert<
+  Equals<Parameters<LocalTable['insert']>, [key: string, row: Row]>
+>;

package/src/wire-headers.ts

@@ -13,5 +13,8 @@
  */
 export const BUILD_ID_HEADER = 'x-ultimate-build';
 
-/** RFC 9110's spelling, lower-cased, as `Headers` normalises it. */
-export const IDEMPOTENCY_HEADER = 'idempotency-key';
+/**
+ * RFC 9110's spelling, lower-cased. Core's, re-exported by name: `clientTransport` sets it and
+ * this package's route reads it, so a second declaration here would be two answers to one header.
+ */
+export { IDEMPOTENCY_HEADER } from '@ultimat3/core';