@ultimat3/action 24.0.0 → 25.0.0

package/src/json-schema.ts

@@ -3,9 +3,10 @@
  * MCP tool's schema is `@ultimat3/schema`'s `toWireSchema` — the one `tools/list` serves.
  */
 
+import { isJsonObject } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { SchemaUnsupportedError, toJsonSchema } from '@ultimat3/schema';
-import { isJsonObject, stableStringify } from './stable';
+import { stableStringify } from './stable';
 
 export type JsonSchemaObject = Record<string, unknown>;
 

package/src/mutator.ts

@@ -5,7 +5,7 @@
  * contract tests for free, and its authz is the same single evaluation.
  */
 
-import type { ConflictPolicy, Ctx, Row } from '@ultimat3/core';
+import type { ConflictPolicy, Ctx, Deprecation, Row } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type {
   Action,
@@ -17,7 +17,6 @@ import type {
   ActionRowArgs,
 } from './action';
 import { action, isAction } from './action';
-import type { Deprecation } from './deprecation';
 import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';

package/src/naming.ts

@@ -11,10 +11,9 @@ import { resolveActionRoute } from './http-path';
 
 /**
  * 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.
+ * spec derive one URL from one function; `pluralize` and `splitWords` are imported from core by
+ * whoever needs them, never re-exported here (`X_HELPER_COPY`).
  */
-export { pluralize, splitWords } from '@ultimat3/core';
 
 export type ActionPath = ActionRoute;
 

package/src/openapi-complete.ts

@@ -79,10 +79,25 @@ interface Refusals {
   readonly unauthorizedHeaders?: Record<string, unknown>;
 }
 
+/**
+ * An ACTION's limit is spent inside `invoke`, so its route carries no bucket to read; the operation
+ * itself publishes the declaration (`x-ultimate.rateLimit`, `null` when none). A query's route
+ * still does, hence both reads above.
+ */
+function declaresRateLimit(operation: Operation): boolean {
+  const extensions = operation['x-ultimate'];
+  if (typeof extensions !== 'object' || extensions === null) return false;
+  const declared = (extensions as Record<string, unknown>)['rateLimit'];
+  return declared !== undefined && declared !== null;
+}
+
 /** One operation, with its route's refusals and security added. Never mutates `operation`. */
 function completeOperation(operation: Operation, route: Route | undefined, refusals: Refusals) {
   const authenticated = route?.meta.auth === 'required';
-  const limited = refusals.everyOpLimited || route?.meta.rateLimitBucket !== undefined;
+  const limited =
+    refusals.everyOpLimited ||
+    route?.meta.rateLimitBucket !== undefined ||
+    declaresRateLimit(operation);
   if (!authenticated && !limited) return operation;
   const responses = { ...(operation['responses'] as Record<string, unknown>) };
   if (limited) {

package/src/policy-gate.ts

@@ -1,18 +1,13 @@
 /**
  * The single point of contact with @ultimat3/policy. Every surface (HTTP, MCP,
- * job, direct server call) reaches authz through `guard()` — there is no second
+ * job, direct server call) reaches authz through `guardAction()` — there is no second
  * code path, which is what makes "one authz system" true rather than aspirational.
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assertNever, isAnonymous } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import {
-  enforce,
-  enforceBeforeInput,
-  policyPermissions as flattenedPermissions,
-  admitsAnonymous as policyAdmitsAnonymous,
-} from '@ultimat3/policy';
+import { enforce, enforceBeforeInput } from '@ultimat3/policy';
 import { ActionDeniedError } from './errors';
 
 /**
@@ -45,7 +40,7 @@ export interface PolicySubject {
  * object for every surface, so an actor denied over HTTP is denied over MCP with
  * the same reason and the same code.
  */
-export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
+export function guardAction(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
   const denial = enforce(policySurface(surface), policy, {
     input: subject.input,
     actor: subject.actor,
@@ -58,13 +53,13 @@ export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Sur
 }
 
 /**
- * The actor-only half of `guard`, run BEFORE the input is parsed: a caller the policy refuses
+ * The actor-only half of `guardAction`, run BEFORE the input is parsed: a caller the policy refuses
  * whatever they send gets the 403 (or 401) here, and never the 400 whose issue list describes
  * the input schema of an operation they may not call. Undecided — a predicate that reads the input
- * or the row — passes, and `guard` decides after the parse exactly as before. Same denial class,
- * same code, same surface rendering as `guard`'s.
+ * or the row — passes, and `guardAction` decides after the parse exactly as before. Same denial
+ * class, same code, same surface rendering as `guardAction`'s.
  */
-export function guardBeforeInput(
+export function guardActionBeforeInput(
   policy: ActionPolicy,
   subject: Omit<PolicySubject, 'input' | 'row'>,
   surface: Surface,
@@ -90,41 +85,3 @@ function policySurface(surface: Surface): PolicySurface {
       return assertNever(surface);
   }
 }
-
-/**
- * Core models "nobody" as an anonymous actor; policy models it as `null`, which is
- * what turns a missing session into `X_UNAUTHENTICATED` instead of a bare denial.
- */
-export function actorOf(ctx: Ctx): Actor | null {
-  return isAnonymous(ctx.actor) ? null : ctx.actor;
-}
-
-/** The capability an action requires, for manifests and OpenAPI metadata. A DISPLAY label. */
-export function policyCapability(policy: ActionPolicy): string {
-  return policy.label;
-}
-
-/**
- * Every permission the policy tree references, flattened and deduped — and the only field a
- * compliance report may match a grant against. `label` renders a composite as
- * `and(post:publish, org:administer)`, which is a sentence and never equals a permission string,
- * so matching on it reported every action guarded by a composite as enforcing nothing: `x policy
- * list` showed real grants as dead. The two are kept side by side rather than one replacing the
- * other — the label is what a human reads, this is what a machine compares.
- */
-export function policyPermissions(policy: ActionPolicy): readonly string[] {
-  return flattenedPermissions(policy);
-}
-
-/**
- * Whether a policy admits an ANONYMOUS caller — `@ultimat3/policy`'s answer, re-exported here so
- * `http.ts` reads it through this file like every other authz question. `toRoute` derives
- * `meta.auth` from it, never from `policy.kind === 'allow'`: that read looked at the ROOT
- * combinator only, so `or(allow(), can('x:y'))` was 401'd by the pipeline before `invoke` ran
- * while the MCP tool and the job handle allowed it. `true` is not "unguarded" — `invoke` still
- * evaluates the policy for every call. Declared once in `policy.ts`, exactly as
- * `policyPermissions` is: the answer is a property of the combinators it walks.
- */
-export function admitsAnonymous(policy: ActionPolicy): boolean {
-  return policyAdmitsAnonymous(policy);
-}

package/src/rate-limit-gate.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a declared `rateLimit:` is spent: once, inside `invoke`, so HTTP, MCP, the in-app agent
+ * tool and `.job()` draw on ONE bucket. The store is `@ultimat3/http`'s installed one — the slot
+ * `@ultimat3/query` spends from too, filled at boot with the instance `httpServer` is handed.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { asyncContext, isAnonymous } from '@ultimat3/core';
+import type { RateLimitDecision } from '@ultimat3/http';
+// The bucket maths, the subject precedence and the refusal are all `@ultimat3/http`'s (tier 2):
+// a copy here would be a second answer to "what does this limit mean" and "whose bucket is it".
+import { installedRateLimitStore, rateLimited, rateLimitSpends, toBucket } from '@ultimat3/http';
+import type { ActionRateLimit } from './action';
+import type { Surface } from './policy-gate';
+
+/**
+ * Who a call chain started from: the address of the request, or the fact that it is a job run.
+ * An `agent()` is an action whose handler calls its tools through `invoke` with no address of its
+ * own, so without this every anonymous visitor's tool calls shared one `ip:unknown` bucket and one
+ * visitor could exhaust it for all. Opened by `invoke`; read by every nested call that has none.
+ */
+interface CallerFrame {
+  readonly address: string | null;
+  /** Inside a job run: nested calls are the job's, never a visitor's. */
+  readonly job: boolean;
+}
+
+const callerFrame = asyncContext<CallerFrame>('the caller frame');
+
+/** Run `fn` with `address` as the inherited caller address; an absent one changes nothing. */
+export function withCallerAddress<T>(address: string | null | undefined, fn: () => T): T {
+  return typeof address === 'string' && address !== ''
+    ? callerFrame.run({ address, job: false }, fn)
+    : fn();
+}
+
+/**
+ * Run `fn` as a job: no inherited address, and every nested call unattributed unless it has an
+ * actor or an org of its own. A FRESH frame, not a read of the current one — a worker loop re-armed
+ * by `setTimeout` inside a request carries that request's frame, and a tenantless job charged to
+ * whichever visitor happened to start the loop is the leak this closes.
+ */
+export function withJobFrame<T>(fn: () => T): T {
+  return callerFrame.run({ address: null, job: true }, fn);
+}
+
+/**
+ * The subject of a job run nobody attributed — no actor, no tenant. Its own population: sharing
+ * `ip:unknown` let a flood of unaddressed anonymous requests park every tenantless job, and the
+ * reverse. Still ONE bucket for all such runs, deliberately: unlimited is the abuse this exists for.
+ */
+const UNATTRIBUTED_JOB = 'job:unattributed';
+
+/**
+ * Namespaced, never the bare action name: the HTTP pipeline still spends its `default` bucket
+ * under `<route name>|<subject>`, and one key taken against two bucket shapes in one store would
+ * corrupt both counters.
+ */
+const ACTION_SCOPE = 'action';
+
+export interface RateLimitSpendOptions {
+  readonly surface: Surface;
+  /** The connection address — the only subject an anonymous caller has. */
+  readonly clientAddress?: string | null | undefined;
+  /** The decision, before a refusal is thrown: how HTTP puts `RateLimit-*` on the answer. */
+  readonly onRateLimit?: ((decision: RateLimitDecision) => void) | undefined;
+}
+
+/**
+ * Spend one token of `limit` for this caller, or throw `X_RATE_LIMITED` — the code, the cause and
+ * the `Retry-After` seconds every limit in the framework answers with.
+ *
+ * `surface: 'server'` spends nothing: that is app code calling its own action in-process (a
+ * service composing two, a seed, a test), not a caller arriving from outside. A refused attempt
+ * spends nothing either — the token bucket only decrements on an admission — so a job retried
+ * into a refusal is not charged for it.
+ */
+export async function spendActionLimit(
+  name: string,
+  limit: ActionRateLimit | undefined,
+  ctx: Ctx,
+  options: RateLimitSpendOptions,
+): Promise<void> {
+  if (limit === undefined || options.surface === 'server') return;
+  const frame = callerFrame.get();
+  // A job run, or any call nested inside one (an `agent()` run as a job calling its tools as
+  // `'mcp'`): never a visitor's address, and the unattributed bucket rather than `ip:unknown`.
+  const inJob = options.surface === 'job' || frame?.job === true;
+  const spends = rateLimitSpends(
+    {
+      actorId: isAnonymous(ctx.actor) ? null : ctx.actor.id,
+      // Read off an anonymous actor too: a job run IS the worker's anonymous identity carrying the
+      // job's org (`jobRunActor`), and that org is who the run is — charging every tenant's runs
+      // to one `ip:unknown` key let one tenant's backlog refuse everyone's.
+      orgId: ctx.actor.orgId ?? null,
+      ip: options.clientAddress ?? (inJob ? null : (frame?.address ?? null)),
+      routeName: `${ACTION_SCOPE}:${name}`,
+      ...(inJob ? { unattributed: UNATTRIBUTED_JOB } : {}),
+    },
+    // The tenant allowance is the HTTP pipeline's (it spends it for every route, a handler-limited
+    // one included); counting it here too would charge an HTTP call against the tenant twice.
+    { route: name, tenant: null },
+  );
+  for (const spend of spends) {
+    const decision = await installedRateLimitStore().take(
+      spend.key,
+      toBucket(name, limit),
+      1,
+      ctx.now().getTime(),
+    );
+    options.onRateLimit?.(decision);
+    if (!decision.allowed) throw rateLimited(spend.key, decision.retryAfterSeconds);
+  }
+}

package/src/record-wire.ts

@@ -6,7 +6,7 @@
 
 import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
 import { hasEntityRows, rowsOf } from '@ultimat3/entity';
-import { json } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 
 /** The header value that says "this body is an envelope". Presence alone is not enough. */
@@ -26,7 +26,7 @@ export function carriesRecords(output: StandardSchemaV1): boolean {
 
 /** 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)));
+  const response = jsonResponse(encodeRecordEnvelope(result, rowsOf(output, result)));
   response.headers.set(RECORDS_HEADER, ENVELOPED);
   return response;
 }

package/src/registry.ts

@@ -111,7 +111,7 @@ function assertProjectable(name: string, target: AnyAction): void {
   for (const field of ['input', 'output'] as const) {
     try {
       jsonSchemaOf(target[field]);
-      // The schema `.tool()` and `tools/list` publish — the one an MCP client reads.
+      // The schema `tools/list` publishes — the one an MCP client reads.
       toWireSchema(target[field]);
     } catch {
       // The thrown value is deliberately not rendered into the cause: it is the provider's, of
@@ -154,7 +154,7 @@ export function describeActions(): readonly ActionDescriptor[] {
 }
 
 /** Test-only. Production registers once at boot and never unregisters. */
-export function resetRegistry(): void {
+export function resetActions(): void {
   registry.clear();
   paths.clear();
   resetActionPathStyle();

package/src/stable.ts

@@ -9,13 +9,6 @@
  * published. Ordinary payloads are byte-identical between the two; `stable.test.ts` pins that.
  */
 
-/**
- * `@ultimat3/core`'s, re-exported so `./stable` stays this package's one import path for the JSON
- * helpers. It was declared here AND identically in `@ultimat3/query`'s own `stable.ts`, which is
- * the duplication `client-wire.ts` moving to tier 0 made unnecessary.
- */
-export { isJsonObject } from '@ultimat3/core';
-
 export type JsonObject = Record<string, unknown>;
 
 /** JSON with object keys sorted at every depth. No timestamps, no insertion-order leaks. */

package/src/type-pins.ts

@@ -3,18 +3,32 @@
 // 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 { AuditRecord, McpExposureDeclaration, Row } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import type { Action, AnyAction } from './action';
+import type { Action, ActionDef, AnyAction, AnyActionDef } from './action';
 import type { ClientMethod } from './client';
+import type {
+  IdempotencyRecord,
+  IdempotencyReservation,
+  IdempotencyScope,
+  IdempotencyStore,
+} from './idempotency';
 import type { ActionJobHandle } from './job-handle';
-import type { LocalTable } from './mutator';
+import type { LocalTable, MutatorDef } from './mutator';
 
 /** 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;
 
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
 type PublishInput = StandardSchemaV1<{ readonly postId: string }>;
 type PublishOutput = StandardSchemaV1<{ readonly published: boolean }>;
 type PublishPost = Action<PublishInput, PublishOutput>;
@@ -59,3 +73,84 @@ export type _LocalTableIsTheStoreTxShape = Assert<
 export type _LocalInsertTakesTheKey = Assert<
   Equals<Parameters<LocalTable['insert']>, [key: string, row: Row]>
 >;
+
+/**
+ * #591: a store written before answers were redacted at rest drops `settle`'s `redacted` flag and
+ * would replay `[redacted]` as the answer. A required 4th PARAMETER cannot refuse it — TypeScript
+ * accepts an implementation with fewer parameters — so the store DECLARES it keeps the flag
+ * (`keepsRedaction: true`), and a pre-25 store without the declaration is a build error here.
+ */
+interface PreRedactionStore {
+  readonly scope?: IdempotencyScope | undefined;
+  reserve(key: string, requestHash: string): Promise<IdempotencyReservation>;
+  settle(key: string, value: unknown, reservationId: string): Promise<void>;
+  release(key: string): Promise<void>;
+  get(key: string): Promise<IdempotencyRecord | undefined>;
+}
+
+export type _APreRedactionStoreIsNotAStore = Assert<
+  Equals<PreRedactionStore extends IdempotencyStore ? true : false, false>
+>;
+
+/** …and `settle`'s flag is required of every CALLER, so a wrapping store cannot drop it either. */
+export type _SettleRequiresTheRedactedFlag = Assert<
+  Equals<Parameters<IdempotencyStore['settle']>['length'], 4>
+>;
+
+/**
+ * 25.0.0 (plan 101, M9): `name` and `primitive` are REQUIRED on an audit record and the `action`
+ * alias is gone. Pinned as keys rather than with a literal record, because a literal would need a
+ * `Ctx` this module has no business building: a field that turned optional again, or an alias
+ * that came back, flips one of these to `false`.
+ */
+type RequiredKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K }[keyof T];
+
+export type _AuditRecordRequiresNameAndPrimitive = Assert<
+  Equals<Extract<RequiredKeys<AuditRecord>, 'name' | 'primitive'>, 'name' | 'primitive'>
+>;
+
+export type _AuditRecordHasNoActionAlias = Assert<
+  Equals<Extract<keyof AuditRecord, 'action'>, never>
+>;
+
+/**
+ * 25.0.0 (plan 101, M5): the deprecation TYPES are `@ultimat3/core`'s alone, as the helpers are.
+ * A runtime test cannot see a type re-export, so each is an expected error: a re-export coming
+ * back makes the directive unused, which `tsc` refuses.
+ */
+// @ts-expect-error — `Deprecation` is imported from `@ultimat3/core`, never from this barrel.
+export type _NoDeprecationReexport = import('./index').Deprecation;
+// @ts-expect-error — `DeprecationField` is imported from `@ultimat3/core`.
+export type _NoDeprecationFieldReexport = import('./index').DeprecationField;
+// @ts-expect-error — `DeprecationRender` is imported from `@ultimat3/core`.
+export type _NoDeprecationRenderReexport = import('./index').DeprecationRender;
+
+/**
+ * O-tool, 25.0.0: an action projects no MCP tool of its own — `@ultimat3/mcp`'s `toolFrom`
+ * is the one projection, and a tier-3 `.tool()` could only ever be a second one. A `tool` member
+ * coming back on either view flips these to `false`.
+ */
+export type _AnActionHasNoToolTwin = Assert<Equals<Extract<keyof AnyAction, 'tool'>, never>>;
+export type _ATypedActionHasNoToolTwin = Assert<Equals<Extract<keyof PublishPost, 'tool'>, never>>;
+
+/**
+ * 25.0.0: an action's `mcp` block is core's ONE `McpExposureDeclaration`, minus the list
+ * whitelist an action has nothing to compose over — on the declaration, the erased declaration,
+ * the erased action and a mutator alike. `ActionMcp` restated the block field by field (and
+ * `McpAnnotationHints` its hints); a field drifting on either side flips these to `false`.
+ */
+type ActionBlock = Omit<McpExposureDeclaration, 'listParams'>;
+export type _ActionDeclaresCoresBlock = Assert<
+  Identical<NonNullable<ActionDef<PublishInput, PublishOutput>['mcp']>, ActionBlock>
+>;
+export type _ErasedActionDefDeclaresCoresBlock = Assert<
+  Identical<NonNullable<AnyActionDef['mcp']>, ActionBlock>
+>;
+export type _AnyActionCarriesCoresBlock = Assert<
+  Identical<NonNullable<AnyAction['mcp']>, ActionBlock>
+>;
+export type _MutatorDeclaresCoresBlock = Assert<
+  Identical<NonNullable<MutatorDef<PublishInput, PublishOutput>['mcp']>, ActionBlock>
+>;
+// @ts-expect-error — `McpAnnotationHints` is `@ultimat3/core`'s, never this barrel's.
+export type _NoAnnotationHintsTwin = import('./index').McpAnnotationHints;

package/src/deprecation.ts

@@ -1,77 +0,0 @@
-/**
- * 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 };
-}

package/src/mcp-tool.ts

@@ -1,95 +0,0 @@
-/**
- * Projection 4: an action as an MCP tool. Its `invoke` is the package's `invoke`
- * — the same core the HTTP route calls — so the tool cannot drift from the
- * endpoint and cannot acquire a second authz path. One authz system, never two.
- */
-import type { Ctx } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
-import { toWireOutputSchema, toWireSchema } from '@ultimat3/schema';
-import type { AnyAction } from './action';
-import { actionName, defOf, invoke } from './invoke';
-import { type JsonSchemaObject, sortSchema } from './json-schema';
-import type { ActionPolicy } from './policy-gate';
-import { listActions } from './registry';
-
-export interface McpToolDescriptor {
-  /**
-   * The export name VERBATIM — `@ultimat3/mcp` serves that name and nothing else, so any
-   * transformation here would be a label no `tools/call` could spell. See `toMcpTool`.
-   */
-  readonly name: string;
-  /** The action's `mcp.description`, or its name when the author gave none. */
-  readonly description: string;
-  /**
-   * The action this tool projects. Equal to `name` by construction since 2026-08 — kept because
-   * a reader asking "which action is behind this tool?" should not have to know that.
-   */
-  readonly action: string;
-  /**
-   * The action's own policy object, not a copy — `tool().policy === action.policy`
-   * is what makes "an MCP call cannot reach a different authz path" checkable.
-   */
-  readonly policy: ActionPolicy;
-  /**
-   * What `@ultimat3/mcp`'s `tools/list` serves for this action — `@ultimat3/schema`'s wire subset,
-   * key-sorted — minus the reserved `idempotencyKey` argument an idempotent action's tool adds,
-   * which `invoke` here takes as an option instead.
-   */
-  readonly inputSchema: JsonSchemaObject;
-  /** The served `outputSchema`: structure only, and absent when `output` has no object root. */
-  readonly outputSchema?: JsonSchemaObject;
-  invoke(input: unknown, options?: McpInvokeOptions): Promise<unknown>;
-}
-
-export interface McpInvokeOptions {
-  readonly ctx?: Ctx;
-  readonly idempotencyKey?: string | null;
-}
-
-/**
- * The tool name is the export name VERBATIM — it was `snake_case`d until 2026-08, and
- * `@ultimat3/mcp` has only ever served the verbatim one, so `.tool().name` was a label no
- * `tools/call` accepted. One name per action, on every surface.
- */
-export function toMcpTool(target: AnyAction): McpToolDescriptor {
-  const name = actionName(target);
-  const def = defOf(target);
-  const output = toWireOutputSchema(def.output);
-  return {
-    name,
-    description: def.mcp?.description ?? name,
-    action: name,
-    policy: def.policy,
-    inputSchema: sortSchema({ ...toWireSchema(def.input) }),
-    ...(output === undefined ? {} : { outputSchema: sortSchema({ ...output }) }),
-    invoke: (input, options = {}) =>
-      invoke(target, input, {
-        surface: 'mcp',
-        ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-        idempotencyKey: options.idempotencyKey ?? null,
-      }),
-  };
-}
-
-/**
- * Opt-in, exactly like a query's: only a literal `mcp: { expose: true }` exposes an action.
- *
- * It read `!== false` until 2026-08, which made writing an action silently hand every agent a
- * new write capability — and disagreed with `@ultimat3/mcp`'s `exposedPrimitives`, the projection
- * that actually builds a catalog. Two functions answering "is this a tool?" differently is the
- * ambiguity axiom 1 rejects, so the fail-closed one wins — and `isMcpExposed` from
- * `@ultimat3/core` is now the single answer every reader in the framework asks.
- */
-export function isExposed(target: AnyAction): boolean {
-  return isMcpExposed(target.mcp);
-}
-
-/** Deterministic order — the tool list is part of the agent-visible contract. */
-export function toMcpTools(
-  actions: readonly AnyAction[] = listActions(),
-): readonly McpToolDescriptor[] {
-  return actions
-    .filter(isExposed)
-    .map(toMcpTool)
-    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-}

package/src/wire-headers.ts

@@ -1,20 +0,0 @@
-/**
- * The two request headers the typed client and the HTTP projection both name. Their own module and
- * not `http.ts`'s, because `client.ts` needs exactly these two strings: importing them from there
- * dragged `@ultimat3/http`, `@ultimat3/cache`, `@ultimat3/policy` and the whole `invoke` runtime
- * into every browser bundle that called `rpc()` — 42,204 B against the read client's 11,977 B,
- * measured, which is why two islands in this repo write a bare `fetch` instead of importing one.
- */
-
-/**
- * Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.clientBuildId` — the
- * CLIENT's claim, never `ctx.buildId`, which is the build this process serves. A mismatch the
- * client sees on the way back is `X_CONTRACT_DRIFT`.
- */
-export const BUILD_ID_HEADER = 'x-ultimate-build';
-
-/**
- * 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';