@ultimat3/action 23.0.0 → 25.0.0

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,87 +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 type { AnyAction } from './action';
-import { actionName, defOf, invoke } from './invoke';
-import { type JsonSchemaObject, mcpSchemaOf, 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;
-  readonly inputSchema: JsonSchemaObject;
-  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);
-  return {
-    name,
-    description: def.mcp?.description ?? name,
-    action: name,
-    policy: def.policy,
-    inputSchema: sortSchema(mcpSchemaOf(def.input)),
-    outputSchema: sortSchema(mcpSchemaOf(def.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';