@ultimat3/action 1.1.0 → 2.0.0

package/src/registry.ts

@@ -4,18 +4,35 @@
  * actions. Registration is also where a missing policy becomes a build error.
  */
 
+import { SchemaUnsupportedError } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
-import { ActionDuplicateError, ActionPolicyMissingError } from './errors';
+import { ActionDuplicateError, ActionPathDuplicateError, ActionPolicyMissingError } from './errors';
+import { assertIdempotencyScope } from './idempotency';
+import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+import { derivePath } from './naming';
 
 const registry = new Map<string, AnyAction>();
 
+/**
+ * Derived route -> the action name that owns it. A second index because the name is not the
+ * path: `pluralize` leaves a trailing `s` alone by design, so `archiveOrder` and `archiveOrders`
+ * are two names and one route. Nothing downstream can refuse that — the router seats whichever
+ * came last and the shadowed action stays in the OpenAPI document and the MCP tool list.
+ */
+const paths = new Map<string, string>();
+
 /**
  * Register one action under an explicit name. The name lands on the action you
  * passed, so the module's own export is projectable after boot and there is no
  * "use the return value instead" rule to forget.
  */
 export function registerAction<A extends AnyAction>(name: string, target: A): A {
+  // Boot, never the first request, and here rather than in `registerActions` because this is the
+  // funnel every registration path goes through — and it necessarily runs before a route is
+  // mounted. A no-op unless the app declared `scope: 'shared'`, which is the only case where the
+  // framework has been told something it can check. See `assertRateLimitScope`, its twin.
+  assertIdempotencyScope();
   const seated = registry.get(name);
   if (seated !== undefined) {
     // Re-registering the SAME object under the SAME name is one registration seen twice, not a
@@ -28,11 +45,44 @@ export function registerAction<A extends AnyAction>(name: string, target: A): A
   if (target.policy === undefined || target.policy === null) {
     throw new ActionPolicyMissingError(name);
   }
+  assertProjectable(name, target);
+  const { path } = derivePath(name);
+  const owner = paths.get(path);
+  if (owner !== undefined && owner !== name) {
+    throw new ActionPathDuplicateError({ name, existing: owner, path });
+  }
   const named = nameAction(target, name);
   registry.set(name, named);
+  paths.set(path, name);
   return named;
 }
 
+/**
+ * Both schemas must reach JSON Schema, and this is where that is decided — boot, beside the policy
+ * check, never the first `tools/list`. `jsonSchemaOf` used to swallow the refusal into
+ * `additionalProperties: true`, so an action whose `input:` the provider cannot describe registered
+ * cleanly and then published "any object accepted" on three surfaces while `validateInput` rejected
+ * every payload. The shipped `X_SCHEMA_UNSUPPORTED` is re-raised rather than re-coded — the failure
+ * is the provider's, and only the cause needs to say which action and which field.
+ */
+function assertProjectable(name: string, target: AnyAction): void {
+  for (const field of ['input', 'output'] as const) {
+    try {
+      jsonSchemaOf(target[field]);
+      mcpSchemaOf(target[field]);
+    } catch {
+      // The thrown value is deliberately not rendered into the cause: it is the provider's, of
+      // unknown shape, and this package's own two facts — which action, which field — are the
+      // ones a reader acts on.
+      throw new SchemaUnsupportedError({
+        cause: `${name}: \`${field}:\` cannot be projected to JSON Schema`,
+        fix: `declare ${name}'s \`${field}:\` with t.object({ ... }) from @ultimat3/action, or call configureSchemaProvider() with a provider that can introspect it`,
+        meta: { action: name, field },
+      });
+    }
+  }
+}
+
 /**
  * Register every action exported by a module namespace, keyed by export name.
  * `registerActions(await import('./actions'))` at boot; the CLI does the same
@@ -63,6 +113,7 @@ export function describeActions(): readonly ActionDescriptor[] {
 /** Test-only. Production registers once at boot and never unregisters. */
 export function resetRegistry(): void {
   registry.clear();
+  paths.clear();
 }
 
 function byName(a: readonly [string, AnyAction], b: readonly [string, AnyAction]): number {

package/src/sample-input.ts

@@ -0,0 +1,177 @@
+/**
+ * A value an input schema accepts, derived from that schema's own IR. The policy contract
+ * test needs its invocation to REACH the policy, and `{}` fails `input:` first for every
+ * action with a required field — which is how "policy denies an anonymous actor" passed on
+ * `X_INPUT_INVALID` and proved nothing about authz.
+ */
+
+import type { SchemaFormat, SchemaNode, StandardSchemaV1 } from '@ultimat3/schema';
+import { requiredKeys, tryIntrospect } from '@ultimat3/schema';
+
+/** Version 4, variant 1 — the shape `t.uuid` insists on, and no byte of it means anything. */
+const SAMPLE_UUID = '00000000-0000-4000-8000-000000000000';
+
+/** Short, and valid under `t.slug`'s and `t.cursor`'s patterns as well as bare `t.string`. */
+const SAMPLE_STRING = 'sample';
+
+/**
+ * One entry per `SchemaFormat`, exhaustively — a new format is a type error here rather than a
+ * silent `'sample'` that fails its own validator and reads as an authz test that cannot pass.
+ */
+const BY_FORMAT: Readonly<Record<SchemaFormat, string>> = {
+  uuid: SAMPLE_UUID,
+  email: 'sample@example.test',
+  uri: 'https://example.test/sample',
+  'date-time': '2020-01-01T00:00:00.000Z',
+  slug: SAMPLE_STRING,
+  timezone: 'UTC',
+  locale: 'en',
+  cursor: SAMPLE_STRING,
+};
+
+function sampleString(node: SchemaNode): string {
+  if (node.format !== undefined) {
+    // A format value is already the exact shape its validator wants; padding or truncating it
+    // to a length bound would break the only thing that makes it valid.
+    const known: string | undefined = BY_FORMAT[node.format];
+    return known ?? SAMPLE_STRING;
+  }
+  const min = node.minLength ?? 0;
+  const padded = SAMPLE_STRING.length >= min ? SAMPLE_STRING : SAMPLE_STRING.padEnd(min, 'x');
+  return node.maxLength === undefined ? padded : padded.slice(0, node.maxLength);
+}
+
+/**
+ * Whether the value this module built for `node` satisfies the node's own `pattern`.
+ *
+ * A regex cannot be inverted, so `sampleString` cannot construct a value for an arbitrary one —
+ * but `pattern` IS in the IR, so whether the value it DID construct is acceptable is knowable
+ * here, before the sample is ever handed to `invoke`. That is the whole difference between
+ * "the framework could not build your payload, pass one" and an `X_INPUT_INVALID` surfacing out
+ * of the action's own parse, which reads as the action being wrong when the action is fine.
+ *
+ * An uncompilable pattern is a gap, not a throw: only a foreign provider's IR can produce one
+ * (`t.string.pattern()` takes a `RegExp`, whose `.source` always recompiles), and a generated
+ * contract test must not die on the way to reporting what it needs.
+ */
+function satisfiesPattern(node: SchemaNode, value: unknown): boolean {
+  if (node.pattern === undefined) return true;
+  if (typeof value !== 'string') return false;
+  try {
+    return new RegExp(node.pattern, node.patternFlags ?? '').test(value);
+  } catch {
+    return false;
+  }
+}
+
+function sampleNumber(node: SchemaNode): number {
+  const low = node.minimum ?? 0;
+  const value = node.integer === true ? Math.ceil(low) : low;
+  if (node.maximum === undefined || value <= node.maximum) return value;
+  return node.integer === true ? Math.floor(node.maximum) : node.maximum;
+}
+
+function sampleObject(node: SchemaNode): Record<string, unknown> {
+  const properties = node.properties ?? {};
+  const sample: Record<string, unknown> = {};
+  // Required-only is what "minimal" means: an optional key and a defaulted one are both
+  // absences the schema already accepts, so adding them would only widen what can go wrong.
+  for (const key of requiredKeys(node)) {
+    const child = properties[key];
+    if (child !== undefined) sample[key] = sampleFor(child);
+  }
+  return sample;
+}
+
+function sampleFor(node: SchemaNode): unknown {
+  // A nullable field accepts `null`, and `null` is the smallest thing it accepts.
+  if (node.nullable === true) return null;
+  switch (node.kind) {
+    case 'string':
+      return sampleString(node);
+    case 'number':
+      return sampleNumber(node);
+    case 'boolean':
+      return false;
+    case 'date':
+      return BY_FORMAT['date-time'];
+    case 'enum':
+      return node.values?.[0] ?? SAMPLE_STRING;
+    case 'literal':
+      return node.literal ?? null;
+    case 'array':
+      return [];
+    case 'union': {
+      const first = node.anyOf?.[0];
+      return first === undefined ? null : sampleFor(first);
+    }
+    case 'record':
+      return {};
+    case 'money':
+      return { minor: 0, currency: 'USD' };
+    case 'object':
+      return sampleObject(node);
+    default:
+      // `unknown`, and any kind a third-party provider emits that this build has never heard
+      // of. Deliberately not `assertNever`: a swapped schema provider must not turn a
+      // generated contract test into a crash, and the caller already reports a rejected
+      // sample as drift with the instruction to pass the input itself.
+      return null;
+  }
+}
+
+/**
+ * Best effort, and honest about it: a schema carrying a constraint the IR does not — a provider's
+ * own refinement — yields a value the schema rejects. The caller turns that into
+ * `X_CONTRACT_DRIFT`, because a silently skipped assertion is the vacuous test this function
+ * exists to end. The one constraint the IR DOES carry is `pattern`, and `sampleGaps` reads it.
+ */
+export function sampleInput(schema: StandardSchemaV1): unknown {
+  const node = tryIntrospect(schema);
+  return node === undefined ? {} : sampleFor(node);
+}
+
+/** The root's name in a gap path — a bare `t.string` input has no field to point at. */
+const ROOT_PATH = '(the input)';
+
+/**
+ * Dotted paths of every sampled field whose own `pattern` the synthesized value cannot satisfy —
+ * "what this schema needs that the framework cannot invent", in the order a reader fills them in.
+ *
+ * Empty is the common case, including for `t.slug` and `t.cursor`, whose patterns `'sample'`
+ * already matches. It walks the SAMPLED shape, so an optional key — which `sampleObject`
+ * deliberately omits — owes nothing.
+ */
+export function sampleGaps(schema: StandardSchemaV1): readonly string[] {
+  const node = tryIntrospect(schema);
+  return node === undefined ? [] : gapsIn(node, '');
+}
+
+function gapsIn(node: SchemaNode, path: string): string[] {
+  if (node.nullable === true) return [];
+  if (node.kind === 'object') {
+    const properties = node.properties ?? {};
+    const out: string[] = [];
+    for (const key of requiredKeys(node)) {
+      const child = properties[key];
+      if (child !== undefined) out.push(...gapsIn(child, path === '' ? key : `${path}.${key}`));
+    }
+    return out;
+  }
+  if (satisfiesPattern(node, sampleFor(node))) return [];
+  return [path === '' ? ROOT_PATH : path];
+}
+
+/** `orderRef` -> `orderRef (must match ^ORD-\d{4}$)`, for a cause a reader can act on. */
+export function describeSampleGap(schema: StandardSchemaV1, path: string): string {
+  const pattern = patternAt(tryIntrospect(schema), path);
+  return pattern === undefined ? path : `${path} (must match ${pattern})`;
+}
+
+function patternAt(node: SchemaNode | undefined, path: string): string | undefined {
+  if (node === undefined) return undefined;
+  if (path === '' || path === ROOT_PATH) return node.pattern;
+  const [head, ...rest] = path.split('.');
+  const child = head === undefined ? undefined : node.properties?.[head];
+  return child === undefined ? undefined : patternAt(child, rest.join('.'));
+}

package/src/stable.ts

@@ -1,7 +1,8 @@
 /**
- * Deterministic JSON: key-sorted serialization plus a cheap content hash.
- * Both the OpenAPI document and idempotency fingerprints depend on byte-stable
- * output, so this is the only serializer either path is allowed to use.
+ * Deterministic JSON in two forms, deliberately NOT one function. `stableStringify` is the
+ * DOCUMENT form — `openapi.json` is published from it and `json-schema.ts` re-reads it with
+ * `JSON.parse`, so a non-finite number must be `null`. `canonicalJson` is the HASH form — it is
+ * only ever hashed, so it must be INJECTIVE. One walk, two number rules.
  */
 
 export type JsonObject = Record<string, unknown>;
@@ -10,18 +11,47 @@ export function isJsonObject(value: unknown): value is JsonObject {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** How the two forms disagree, and the only thing they disagree about. */
+type NumberForm = (value: number) => string;
+
+/** JSON's own rule: a non-finite number has no token in the grammar, so it is `null`. */
+const jsonNumber: NumberForm = (value) => (Number.isFinite(value) ? String(value) : 'null');
+
+/**
+ * Bare tokens, never quoted and never `'null'`. This output is only ever hashed, so an unquoted
+ * word cannot collide with the `string` branch (which always quotes), while `'null'` collided with
+ * JSON `null` itself — `{ n: NaN }`, `{ n: Infinity }`, `{ n: -Infinity }` and `{ n: null }` were
+ * one `requestHash` and therefore one idempotency record. `-0` is spelled out for the same reason:
+ * `String(-0)` is `"0"`, so `-0` and `0` were one record too. The twin of `@ultimat3/query`'s rule
+ * in its own `stable.ts`; both are tier 3, so neither can import the other.
+ */
+const hashNumber: NumberForm = (value) => {
+  if (Number.isNaN(value)) return 'NaN';
+  if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
+  return Object.is(value, -0) ? '-0' : String(value);
+};
+
 /** JSON with object keys sorted at every depth. No timestamps, no insertion-order leaks. */
 export function stableStringify(value: unknown, indent = 0): string {
-  return write(value, indent, 0);
+  return write(value, indent, 0, jsonNumber);
+}
+
+/**
+ * The canonical form a `fingerprint` is taken over. Byte-identical to `stableStringify(value)` for
+ * any value carrying no `NaN`, no `±Infinity` and no `-0`, which is why no idempotency record and
+ * no job dedupe key issued before this moved.
+ */
+export function canonicalJson(value: unknown): string {
+  return write(value, 0, 0, hashNumber);
 }
 
-function write(value: unknown, indent: number, depth: number): string {
+function write(value: unknown, indent: number, depth: number, number: NumberForm): string {
   if (value === null) return 'null';
   switch (typeof value) {
     case 'string':
       return JSON.stringify(value);
     case 'number':
-      return Number.isFinite(value) ? String(value) : 'null';
+      return number(value);
     case 'boolean':
       return String(value);
     case 'bigint':
@@ -37,7 +67,7 @@ function write(value: unknown, indent: number, depth: number): string {
   const close = indent > 0 ? '\n'.padEnd(1 + indent * depth, ' ') : '';
   if (Array.isArray(value)) {
     if (value.length === 0) return '[]';
-    const items = value.map((item) => write(item, indent, depth + 1));
+    const items = value.map((item) => write(item, indent, depth + 1, number));
     return `[${pad}${items.join(`,${pad || ''}`)}${close}]`;
   }
   const record = value as JsonObject;
@@ -47,22 +77,27 @@ function write(value: unknown, indent: number, depth: number): string {
   if (keys.length === 0) return '{}';
   const gap = indent > 0 ? ' ' : '';
   const entries = keys.map(
-    (key) => `${JSON.stringify(key)}:${gap}${write(record[key], indent, depth + 1)}`,
+    (key) => `${JSON.stringify(key)}:${gap}${write(record[key], indent, depth + 1, number)}`,
   );
   return `{${pad}${entries.join(`,${pad || ''}`)}${close}}`;
 }
 
-/** FNV-1a/32 as hex. Fingerprinting only — never a security boundary. */
-export function fnv1a(input: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < input.length; i += 1) {
-    hash ^= input.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
-}
-
-/** Stable fingerprint of any JSON-ish value. */
+/**
+ * SHA-256, first 16 hex characters — the same primitive and width `@ultimat3/query`'s `fingerprint`
+ * and `@ultimat3/realtime`'s `stableDigest` already chose, and for the same reason.
+ *
+ * A fingerprint here is a SHARING key over input a client chooses, not a checksum. It is the
+ * `requestHash` that decides "same request, replay the stored response" and the job dedupe key
+ * `job-handle.ts` files an enqueue under, so a collision hands one caller's stored response to a
+ * different request, or drops an enqueue as a duplicate of a job it shares nothing with. FNV-1a/32
+ * — what this was — is 4x10^9 values, brute-forceable offline in seconds, so a payload landing on
+ * another request's hash was something an attacker could mint rather than something they had to
+ * wait for.
+ *
+ * It is taken over `canonicalJson` and not `stableStringify` for the second half of the same
+ * argument: the document form is not injective, so four distinct inputs shared one hash without
+ * anyone having to mint anything.
+ */
 export function fingerprint(value: unknown): string {
-  return fnv1a(stableStringify(value));
+  return new Bun.CryptoHasher('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
 }

package/src/type-pins.ts

@@ -0,0 +1,45 @@
+// Compile-time pins for the erased action view. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// 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 { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Action, AnyAction } from './action';
+import type { ClientMethod } from './client';
+import type { ActionJobHandle } from './job-handle';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+type PublishInput = StandardSchemaV1<{ readonly postId: string }>;
+type PublishOutput = StandardSchemaV1<{ readonly published: boolean }>;
+type PublishPost = Action<PublishInput, PublishOutput>;
+
+/**
+ * The registry hands back `AnyAction` and nothing else, so the erased view has to project every
+ * surface — the queue included. Written as the return type rather than `'job' in keyof` because
+ * an `AnyAction['job']` that answered the wrong shape would satisfy a key check.
+ */
+export type _ErasedViewProjectsAJobHandle = Assert<
+  Equals<ReturnType<AnyAction['job']>, ActionJobHandle>
+>;
+
+/** …and the typed action still narrows it to its own schemas, which is what `.job()` is for. */
+export type _TypedActionNarrowsTheJobHandle = Assert<
+  Equals<ReturnType<PublishPost['job']>, ActionJobHandle<PublishInput, PublishOutput>>
+>;
+
+/**
+ * Why `client()` is NOT on the erased view, pinned rather than asserted in a comment: a
+ * `ClientMethod` is a function type, so its input is checked contravariantly and the erased
+ * `(input: unknown) => …` is a supertype of no concrete action's method. Spelling `ClientMethod`
+ * with method syntax — or with an `any` — would flip this to `true` and make the asymmetry
+ * between `job()` and `client()` look arbitrary.
+ */
+export type _ErasedClientIsNotASupertype = Assert<
+  ClientMethod<PublishInput, PublishOutput> extends ClientMethod<StandardSchemaV1, StandardSchemaV1>
+    ? false
+    : true
+>;

package/src/tags.ts

@@ -1,17 +0,0 @@
-/**
- * Cache tags stay opaque to actions — we hand them back to @ultimat3/cache
- * untouched. The only thing this package needs is the wire string per tag, for
- * manifests, OpenAPI metadata and the invalidation graph in `/_x`.
- */
-
-import type { CacheTag } from '@ultimat3/cache';
-import { serializeTag } from '@ultimat3/cache';
-
-export function tagKey(value: CacheTag): string {
-  return serializeTag(value);
-}
-
-/** Sorted + de-duplicated: descriptor output must not depend on declaration order. */
-export function tagKeys(tags: readonly CacheTag[]): readonly string[] {
-  return [...new Set(tags.map(tagKey))].sort();
-}