@ultimat3/action 1.1.0 → 2.0.0

package/src/audit.ts

@@ -0,0 +1,123 @@
+/**
+ * The audit seam: THAT an action or mutator can be recorded at all. One `AuditSink`, installed
+ * once, handed every fact `invoke` genuinely knows about an attempt — who acted, which primitive,
+ * when, on which surface, with which idempotency key, and whether it was allowed, denied or
+ * failed. What the ROW says — its fields, its retention, its hash chain, its subject index, what
+ * "who" means under impersonation — is the app's, and this file declares none of it.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import type { Surface } from './policy-gate';
+
+/**
+ * The three things that can happen to an attempt. Deliberately the same three words
+ * `@ultimat3/admin`'s `AuditEntry` uses — that package is tier 5 and this one is tier 3, so the
+ * vocabulary is shared by name and not by import. `denied` is an authz refusal, `failed` is
+ * everything else that threw, including an input that never parsed.
+ */
+export type AuditOutcome = 'allowed' | 'denied' | 'failed';
+
+/** Why a non-`allowed` attempt ended. The framework classifies; it never renders. */
+export interface AuditFailure {
+  /** The `X_*` code when an `UltimateError` ended it; `null` for anything else that threw. */
+  readonly code: string | null;
+  /** The thrown value, verbatim — its stack is the thing worth reading. */
+  readonly error: unknown;
+}
+
+/**
+ * One attempt, as the framework observed it. Every field here is something `invoke` already
+ * holds; nothing on it is a guess about the business.
+ *
+ * `result` is deliberately absent. A handler's return value is reachable from the handler
+ * itself, on the one outcome that has one — so shipping it would be the framework deciding the
+ * row carries an after-image, which is the first field of an audit ENTITY. `input` is present
+ * for the opposite reason: on a `denied` record the handler never ran, so nothing in app code
+ * can recover what was attempted, and that is the record an auditor actually wants.
+ */
+export interface AuditRecord {
+  /**
+   * When the attempt began, from `ctx.now()` — never `new Date()`. An instant, not a rendering:
+   * serialising it (ISO, epoch, a Postgres `timestamptz`) is the app's decision, and it is the
+   * app that knows the zone anything is displayed in.
+   */
+  readonly at: Date;
+  /** The registered export name. A mutator carries the name of its action half. */
+  readonly action: string;
+  /** True when `mutator()` built it. Which primitive acted is a framework fact. */
+  readonly mutator: boolean;
+  /** Which projection ran it: a price change over `http` and one over `mcp` are not the same event. */
+  readonly surface: Surface;
+  /**
+   * The context the attempt ran in — actor, `requestId`, `traceId`, locale, and the service bag
+   * a sink needs to write a row at all. Carried whole rather than projected into `actorId` +
+   * `requestId` fields, because choosing WHICH context facts an audit row keeps is precisely the
+   * convention four apps modelled four ways.
+   */
+  readonly ctx: Ctx;
+  /**
+   * The PARSED input, or `undefined` when the parse is what failed. Never the raw payload:
+   * an unvalidated body is attacker-shaped, and handing one to a sink that writes it to a table
+   * is how an audit trail becomes an injection surface.
+   */
+  readonly input: unknown;
+  /** The namespaced key an `idempotent` action was retried under, or `null`. */
+  readonly idempotencyKey: string | null;
+  /** True when the response was replayed from an earlier settled record — a call, not a write. */
+  readonly replayed: boolean;
+  readonly outcome: AuditOutcome;
+  /** Present exactly when `outcome !== 'allowed'`. */
+  readonly failure: AuditFailure | null;
+}
+
+/**
+ * Where a record goes. The app's implementation: a table, an append-only hash chain, an OTel
+ * log, a queue. `@ultimat3/admin`'s `AuditSink` is the same noun one tier up, over its own
+ * fixed entry type; this one carries no `AdminActor` and no `permission`, because an action
+ * outside `/admin` has neither.
+ *
+ * A sink that throws is never swallowed — see `audit-gate.ts` for which failure wins.
+ */
+export interface AuditSink {
+  write(record: AuditRecord): Promise<void> | void;
+}
+
+/** The seam's memory implementation, for tests and `x dev`. Not a system of record. */
+export interface MemoryAuditSink extends AuditSink {
+  /** In the order `invoke` produced them. A copy — the log cannot be mutated through it. */
+  records(): readonly AuditRecord[];
+  clear(): void;
+}
+
+export function memoryAuditSink(): MemoryAuditSink {
+  const log: AuditRecord[] = [];
+  return {
+    write(record: AuditRecord): void {
+      log.push(record);
+    },
+    records: (): readonly AuditRecord[] => [...log],
+    clear: (): void => {
+      log.length = 0;
+    },
+  };
+}
+
+/**
+ * No default. A logger-backed default would satisfy `audit: true` with a line nobody stores,
+ * which is the silent pass this seam exists to remove: an audited action with no sink installed
+ * is `X_AUDIT_SINK_MISSING`, refused before the handler runs.
+ */
+let installed: AuditSink | null = null;
+
+export function setAuditSink(sink: AuditSink): void {
+  installed = sink;
+}
+
+export function getAuditSink(): AuditSink | null {
+  return installed;
+}
+
+/** Test seam: back to "nothing installed", which restoring a literal cannot express. */
+export function resetAuditSink(): void {
+  installed = null;
+}

package/src/cache-gate.ts

@@ -0,0 +1,32 @@
+/**
+ * The post-commit cache bust — the only file in this package that calls `invalidateTags`.
+ * The handler has already committed by the time it runs, so a fan-out that refuses degrades to
+ * one logged failure instead of a failed action: the stale entries expire by TTL, and the caller
+ * keeps the write it already made.
+ */
+
+import type { CacheTag, InvalidationReport } from '@ultimat3/cache';
+import { invalidateTags } from '@ultimat3/cache';
+import { logger } from '@ultimat3/core';
+
+/**
+ * Fan `tags` out and never throw. `undefined` back means the fan-out itself refused and nothing
+ * was cleared — an undeclared tag (`X_CACHE_TAG_UNKNOWN`) is the one an app hits. One dead tier
+ * is not that case: `invalidateTags` absorbs those into `report.errors` and still reports.
+ */
+export async function bustAfterCommit(
+  action: string,
+  tags: readonly CacheTag[],
+): Promise<InvalidationReport | undefined> {
+  try {
+    return await invalidateTags(tags);
+  } catch (error) {
+    // Neither the tags nor `ctx.logger`. Reading a malformed `invalidates` entry back to render
+    // it throws a second time, out of the branch whose whole job is not to — and the failure
+    // names the offending tag while `action` names the one place `invalidates` is declared. Core's
+    // logger already carries `requestId`/`traceId` from the ambient context; an HTTP `Ctx` is a
+    // cast request context that carries no `logger` at all.
+    logger.error('action.invalidate.failed', { action, error });
+    return undefined;
+  }
+}

package/src/client.ts

@@ -3,10 +3,11 @@
  * the same pure derivation the server uses, so a renamed or mistyped action is a
  * compile error in a Solid component — not a 404 at runtime.
  */
-import { UltimateError } from '@ultimat3/core';
+import type { UltimateError } from '@ultimat3/core';
+import { currentSpanContext, traceparent } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action } from './action';
-import { ContractDriftError, RpcFailedError } from './errors';
+import { ContractDriftError, RemoteActionError, RpcFailedError } from './errors';
 import { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './http';
 import { derivePath } from './naming';
 import { isJsonObject } from './stable';
@@ -58,7 +59,10 @@ export function rpc<TActions extends ActionMap>(options: ClientOptions): Client<
     {},
     {
       get(_target, property: string | symbol) {
-        if (typeof property !== 'string') return undefined;
+        // `then` is `undefined` for the same reason a symbol is, and `queryClient` draws the line
+        // in the same place: `await client` reads it, so a method there makes the client a
+        // thenable that posts an action named "then" and resolves the await to its answer.
+        if (typeof property !== 'string' || property === 'then') return undefined;
         return clientMethodFor(property, options);
       },
     },
@@ -93,6 +97,10 @@ async function call(
 ): Promise<unknown> {
   const headers: Record<string, string> = {
     'content-type': 'application/json',
+    // Before the caller's headers, so an explicit `traceparent` still wins. Without this a
+    // service-to-service hop started a fresh root trace on the other side, which makes "which of
+    // my downstreams is slow" unanswerable across every Ultimate-to-Ultimate call.
+    ...traceHeaders(),
     ...options.headers,
   };
   if (options.buildId !== undefined) headers[BUILD_ID_HEADER] = options.buildId;
@@ -114,6 +122,27 @@ async function call(
   return body;
 }
 
+/** A `traceparent` is `00-<32 hex>-<16 hex>-<2 hex>`, and nothing else may be sent as one. */
+const TRACE_ID = /^[0-9a-f]{32}$/;
+const SPAN_ID = /^[0-9a-f]{16}$/;
+
+/**
+ * The current trace, as the W3C header — or nothing at all. `currentSpanContext()` answers with
+ * an empty `spanId` when a request context exists but no span is active, and `00-<trace>--01` is
+ * a header every collector drops, so an incomplete context sends none. In a browser there is no
+ * ambient context and this is always empty, which is also what keeps a cross-origin GET from
+ * acquiring a CORS preflight it did not have.
+ *
+ * `@ultimat3/query`'s client carries the twin of this function: both are tier 3, so neither may
+ * import the other.
+ */
+function traceHeaders(): Record<string, string> {
+  const context = currentSpanContext();
+  if (context === undefined) return {};
+  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
+  return { traceparent: traceparent(context) };
+}
+
 /**
  * Version skew is a contract problem, not a network problem: the client holds
  * types from build A while build B answers. Fail loudly so the shell reloads.
@@ -131,20 +160,45 @@ function assertSameBuild(
   );
 }
 
-/** `application/problem+json` back into the same error the server threw. */
+/**
+ * A framework code, spelled the one way codes are spelled. `typeof code === 'string'` alone
+ * accepted `""` and `"error"` — a gateway's JSON body became an `UltimateError` whose code
+ * nothing in the framework or the app declares, rendering `: ` under a humanised title.
+ */
+const FRAMEWORK_CODE = /^X_[A-Z0-9]+(?:_[A-Z0-9]+)*$/;
+
+/**
+ * `application/problem+json` back into the error the server threw. The code rides along
+ * verbatim — carrying one is the point of the document — but it is a code this bundle may never
+ * have registered, so the result is a `RemoteActionError`: marked remote-origin, and linked only
+ * to a page that exists. A body naming no framework code is a proxy answering rather than the
+ * app, which is what `RpcFailedError` already says.
+ */
 async function toUltimateError(response: Response, name: string): Promise<UltimateError> {
   const body: unknown = await response.json().catch(() => null);
-  if (isJsonObject(body) && typeof body['code'] === 'string') {
-    return new UltimateError({
-      code: body['code'],
-      cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${response.status}`),
-      fix: stringOr(body['fix'], `x actions describe ${name} --json`),
-      docs: stringOr(body['docs'], `https://ultimate.dev/errors/${body['code']}`),
-    });
+  if (!isJsonObject(body)) return new RpcFailedError(name, response.status);
+  const code = body['code'];
+  if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
+    return new RpcFailedError(name, response.status);
   }
-  return new RpcFailedError(name, response.status);
+  return new RemoteActionError({
+    action: name,
+    status: response.status,
+    code,
+    cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${response.status}`),
+    fix: stringOr(body['fix'], `x actions describe ${name} --json`),
+    // RFC-9457's `type` IS a documentation URI, so a server that sends no `docs` extension has
+    // still offered one. Both travel, in preference order: `??` picked `docs` on presence alone,
+    // so a `javascript:` one hid a perfectly good `type` behind it. `remoteDocs` takes the first
+    // that is an absolute HTTP(S) URL — neither is trusted for being there.
+    docs: [nonEmpty(body['docs']), nonEmpty(body['type'])],
+  });
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 
 function stringOr(value: unknown, fallback: string): string {
-  return typeof value === 'string' && value.length > 0 ? value : fallback;
+  return nonEmpty(value) ?? fallback;
 }

package/src/contract-test.ts

@@ -7,10 +7,11 @@
 import type { Ctx } from '@ultimat3/core';
 import { createContext, isUltimateError } from '@ultimat3/core';
 import type { AnyAction } from './action';
-import { ContractDriftError } from './errors';
+import { ActionDeniedError, ContractDriftError } from './errors';
 import { actionName, invoke } from './invoke';
 import { derivePath } from './naming';
 import { buildOpenApi } from './openapi';
+import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
 
 export interface ContractTest {
   readonly name: string;
@@ -20,6 +21,13 @@ export interface ContractTest {
 export interface ContractTestOptions {
   /** Value the input schema must reject. `null` fails every object schema. */
   readonly garbage?: unknown;
+  /**
+   * Input for the policy assertion. Omitted means one synthesized from `input:` itself — pass it
+   * when the schema carries a `pattern` (named for you, before the invocation, by
+   * `assertSampleable`), a provider refinement the IR does not carry, or a `row:` loader that
+   * needs an id which resolves.
+   */
+  readonly input?: unknown;
   readonly ctx?: Ctx;
 }
 
@@ -51,12 +59,12 @@ export function contractTestsFor(
     {
       name: `${name}: policy denies an anonymous actor`,
       run: async () => {
-        await expectThrow(
-          () => invoke(target, emptyInput(), { ctx, surface: 'http' }),
-          null,
-          `${name} ran for an actor of null`,
-          `make the ${name} policy require an authenticated actor`,
-        );
+        if ('input' in options) {
+          await expectDenied(target, name, options.input, ctx);
+          return;
+        }
+        assertSampleable(target, name);
+        await expectDenied(target, name, sampleInput(target.input), ctx);
       },
     },
     {
@@ -75,6 +83,24 @@ export function contractTestsFor(
   ];
 }
 
+/**
+ * A `pattern` cannot be inverted, so the framework cannot build a payload for
+ * `t.string.pattern(...)` — but the pattern IS in the IR, so it knows that BEFORE it invokes.
+ * Reporting it here rather than letting `X_INPUT_INVALID` surface out of the action's own parse
+ * is the difference between an instruction and a misattribution: the action is correct, `input:`
+ * is correct, and the only thing that can supply the value is the author. The `fix:` is therefore
+ * the exact call to paste, not an edit to the declaration.
+ */
+function assertSampleable(target: AnyAction, name: string): void {
+  const gaps = sampleGaps(target.input);
+  if (gaps.length === 0) return;
+  const described = gaps.map((path) => describeSampleGap(target.input, path)).join(', ');
+  throw new ContractDriftError(
+    `${name}: no value can be synthesized for ${described}, so the denial would be unproven`,
+    `contractTestsFor(${name}, { input: { … } })   # x actions describe ${name} --json prints the schema`,
+  );
+}
+
 /**
  * The generated policy test. Emitted as source (not executed here) because the
  * app owns which actors it considers privileged.
@@ -85,7 +111,8 @@ export function policyTestStubFor(target: AnyAction): string {
 import { ${name} } from './actions';
 
 // Fill in: arrange a foreign actor, expect the policy to deny.
-// The contract tests below are framework-generated and always included.
+// The contract tests below are framework-generated and always included. Pass
+// \`{ input }\` if the synthesized one cannot satisfy this action's schema or row loader.
 for (const contract of contractTestsFor(${name})) {
   test(contract.name, async () => {
     await contract.run();
@@ -94,14 +121,51 @@ for (const contract of contractTestsFor(${name})) {
 `;
 }
 
-/** An input the schema may still reject — only the policy assertion depends on it. */
-function emptyInput(): unknown {
-  return {};
+/**
+ * The assertion the second test is named for, and the reason it refuses to accept just any
+ * thrown error: this used to pass on ANY `UltimateError`, and the input it sent was `{}` —
+ * which fails `input:` for every action with a required field, so `X_INPUT_INVALID` was
+ * thrown before the policy ran and the authz claim was never tested at all.
+ *
+ * `ActionDeniedError` is the one outcome that means the policy decided. It is asserted as a
+ * class rather than as `X_FORBIDDEN`, because it re-uses the policy decision's own code and
+ * the blessed `can()` answers a null actor with `X_UNAUTHENTICATED` — pinning one code would
+ * fail every action that authors its policy the way the framework tells it to.
+ */
+async function expectDenied(
+  target: AnyAction,
+  name: string,
+  input: unknown,
+  ctx: Ctx,
+): Promise<void> {
+  try {
+    await invoke(target, input, { ctx, surface: 'http' });
+  } catch (error) {
+    // A handler's own bug keeps its stack: wrapping a TypeError from a `row:` loader in a
+    // drift error would hide the line that threw behind a fix that does not apply.
+    if (!isUltimateError(error)) throw error;
+    if (error instanceof ActionDeniedError) return;
+    // `invoke` runs parse input → row → policy → handle → parse output, and every stage lands
+    // here identically. Only `X_INPUT_INVALID` is attributable: it is what `validateInput`
+    // raises before `guard()` is reached, and `input:` is the knob that answers it. Any other
+    // code — `X_TENANCY_UNSCOPED` from a `row:` loader, `X_DB_CONFLICT` from a handler,
+    // `X_OUTPUT_INVALID` from the parse after it — keeps its own code and its own fix rather
+    // than being retold as an input problem with a fix that changes nothing.
+    if (error.code !== 'X_INPUT_INVALID') throw error;
+    throw new ContractDriftError(
+      `${name} failed with ${error.code} before its policy decided, so the denial is unproven`,
+      `pass \`input:\` to contractTestsFor(${name}) — x actions describe ${name} --json prints the schema`,
+    );
+  }
+  throw new ContractDriftError(
+    `${name} ran for an actor of null`,
+    `make the ${name} policy require an authenticated actor`,
+  );
 }
 
 async function expectThrow(
   run: () => Promise<unknown>,
-  code: string | null,
+  code: string,
   cause: string,
   fix: string,
 ): Promise<void> {
@@ -109,7 +173,12 @@ async function expectThrow(
     await run();
   } catch (error) {
     if (!isUltimateError(error)) throw error;
-    if (code === null || error.code === code) return;
+    if (error.code === code) return;
+    // `X_AUDIT_SINK_MISSING` is the one refusal `invoke` raises BEFORE the input parse, so
+    // "the schema accepted garbage" is a false statement about it and `input:` is not what
+    // answers it. It keeps its own code and its own runnable fix — the same rule `expectDenied`
+    // follows for every code it cannot attribute to `input:`.
+    if (error.code === 'X_AUDIT_SINK_MISSING') throw error;
     throw new ContractDriftError(`${cause} (got ${error.code}, expected ${code})`, fix);
   }
   throw new ContractDriftError(cause, fix);

package/src/deprecation.ts

@@ -0,0 +1,82 @@
+/**
+ * A declared retirement, rendered as the two headers the standards already define — RFC 9745
+ * `Deprecation` and RFC 8594 `Sunset` — plus the successor link. Pure string and date maths, and
+ * deliberately throw-free: each package raises its own `X_*` for a date it cannot render.
+ *
+ * `@ultimat3/query` carries a twin of this file. Both are tier 3, so neither may import the
+ * other, and the shared home is `@ultimat3/http` (tier 2) once that package grows one — the same
+ * compromise `naming.ts` is ported under.
+ */
+import { counter } from '@ultimat3/core';
+
+export interface Deprecation {
+  /** When it was deprecated. ISO-8601, e.g. `'2026-08-01T00:00:00Z'`. */
+  readonly since: string;
+  /** When it stops answering. ISO-8601 — the date `Sunset` publishes and clients plan against. */
+  readonly sunset: string;
+  /** The export name of the replacement, projected to a `rel="successor-version"` link. */
+  readonly replacedBy?: string;
+}
+
+export type DeprecationField = 'since' | 'sunset';
+
+export type DeprecationRender =
+  | {
+      readonly ok: true;
+      readonly headers: Readonly<Record<string, string>>;
+      /** The same facts as data, for `x-ultimate` in the OpenAPI operation and the manifest. */
+      readonly meta: Readonly<Record<string, string>>;
+    }
+  | { readonly ok: false; readonly field: DeprecationField; readonly value: string };
+
+/**
+ * How many calls a deprecated declaration is still taking — the number "can we remove it yet?"
+ * needs and the one nothing in the framework could answer. Attributes are the primitive and the
+ * declared NAME, both bounded by the size of the codebase; a caller id here would be an unbounded
+ * series, which is the cardinality mistake core's own overflow bucket exists to catch.
+ */
+const deprecatedCalls = counter('deprecated_calls_total', {
+  unit: '{call}',
+  description: 'Calls served by a declaration that has been deprecated, by primitive and name',
+});
+
+export function recordDeprecatedCall(primitive: 'action' | 'query', name: string): void {
+  deprecatedCalls.add(1, { primitive, name });
+}
+
+/**
+ * `Deprecation` is a structured-field Date (`@` + unix seconds, RFC 9745); `Sunset` is an
+ * HTTP-date (IMF-fixdate, RFC 8594). Two spellings of one instant because two RFCs chose
+ * differently — never render one in the other's format, and never emit `Invalid Date`.
+ */
+export function renderDeprecation(
+  deprecation: Deprecation,
+  successorPath: string | undefined,
+): DeprecationRender {
+  const since = Date.parse(deprecation.since);
+  if (Number.isNaN(since)) return { ok: false, field: 'since', value: deprecation.since };
+  const sunset = Date.parse(deprecation.sunset);
+  if (Number.isNaN(sunset)) return { ok: false, field: 'sunset', value: deprecation.sunset };
+
+  const headers: Record<string, string> = {
+    deprecation: `@${Math.floor(since / 1000)}`,
+    sunset: new Date(sunset).toUTCString(),
+  };
+  // The successor's URL, derived by the caller from the same `naming.ts` the client uses — a
+  // link this file built from the export name would be the second URL derivation in the package.
+  if (successorPath !== undefined) {
+    headers['link'] = `<${successorPath}>; rel="successor-version"`;
+  }
+
+  const meta: Record<string, string> = {
+    since: new Date(since).toISOString(),
+    sunset: new Date(sunset).toISOString(),
+    ...(deprecation.replacedBy === undefined ? {} : { replacedBy: deprecation.replacedBy }),
+  };
+  return { ok: true, headers, meta };
+}
+
+/** Set on a response that already exists, so a redirect and a problem document carry them too. */
+export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
+  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+}