@tai42/api-client 16.0.0 → 17.0.0

package/src/client/observability-client.ts

@@ -0,0 +1,82 @@
+/** Run metrics, listing, trace and export sub-client. */
+import { apiDownload, encodeSegment, type RequestOptions } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/** The observability-metrics window + bucket size (GET query params). */
+export interface MetricsQuery {
+  readonly from?: string;
+  readonly to?: string;
+  readonly granularity?: string;
+}
+
+/**
+ * The observability runs filter. List/dict-valued params (`tags`) are
+ * JSON-encoded into the query string; scalars are sent verbatim. Shared by
+ * `listRuns` and the `exportRuns` download.
+ */
+export interface RunsQuery {
+  readonly from?: string;
+  readonly to?: string;
+  readonly tags?: string[];
+  readonly status?: 'error' | 'success';
+  readonly minCost?: number;
+  readonly maxCost?: number;
+  readonly minTokens?: number;
+  readonly maxTokens?: number;
+  readonly minLatencyMs?: number;
+  readonly maxLatencyMs?: number;
+  readonly sort?: string;
+  readonly dir?: 'asc' | 'desc';
+  readonly page?: number;
+  readonly pageSize?: number;
+}
+
+/** Flatten a `RunsQuery` to transport params, JSON-encoding the `tags` list. */
+function runsQueryToParams(query: RunsQuery): Required<RequestOptions>['query'] {
+  return {
+    from: query.from,
+    to: query.to,
+    tags: query.tags === undefined ? undefined : JSON.stringify(query.tags),
+    status: query.status,
+    minCost: query.minCost,
+    maxCost: query.maxCost,
+    minTokens: query.minTokens,
+    maxTokens: query.maxTokens,
+    minLatencyMs: query.minLatencyMs,
+    maxLatencyMs: query.maxLatencyMs,
+    sort: query.sort,
+    dir: query.dir,
+    page: query.page,
+    pageSize: query.pageSize,
+  };
+}
+
+export function observabilityClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    // The monitoring-backend dashboard rollups (`GET /api/observability/metrics`),
+    // a JSON aggregate distinct from any raw process-metrics text endpoint.
+    getObservabilityMetrics: (params: MetricsQuery = {}, signal?: AbortSignal) =>
+      req('/api/observability/metrics', s.dashboardMetrics, {
+        query: { from: params.from, to: params.to, granularity: params.granularity },
+        signal,
+      }),
+    listRuns: (params: RunsQuery = {}, signal?: AbortSignal) =>
+      req('/api/observability/runs', s.runsPage, { query: runsQueryToParams(params), signal }),
+    getRunTrace: (traceId: string, signal?: AbortSignal) =>
+      req(`/api/observability/runs/${encodeSegment(traceId)}/trace`, s.runTrace, { signal }),
+    exportTrace: (traceId: string, signal?: AbortSignal): Promise<Blob> =>
+      apiDownload(config, `/api/observability/runs/${encodeSegment(traceId)}/trace/export`, {
+        signal,
+      }),
+    exportRuns: (
+      params: RunsQuery & { format: 'csv' | 'json' },
+      signal?: AbortSignal,
+    ): Promise<Blob> =>
+      apiDownload(config, '/api/observability/runs/export', {
+        query: { ...runsQueryToParams(params), format: params.format },
+        signal,
+      }),
+  };
+}

package/src/client/plugins-client.ts

@@ -0,0 +1,11 @@
+/** Studio front-end plugin registry sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function pluginsClient(t: Transport) {
+  const { req } = t;
+  return {
+    listStudioPlugins: (signal?: AbortSignal) =>
+      req('/api/plugins', s.studioPluginRegistry, { signal }),
+  };
+}

package/src/client/policy-client.ts

@@ -0,0 +1,41 @@
+/** Access-policy validation, versioning and rollback sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for the fail-closed jq guard (POST `/api/auth/validate-condition`). The guard
+ * compile-checks the inline jq `condition` the author typed. `sample_context` is a
+ * `JqAuthContext`-shaped sample; when present the guard also evaluates the condition
+ * against it and returns the boolean `result` (else `result` is `null`).
+ */
+export interface ValidateConditionBody {
+  readonly condition?: string;
+  readonly sample_context?: Record<string, unknown>;
+}
+
+export function policyClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The fail-closed jq guard: compiles (and, with `sample_context`, evaluates) a
+    // condition without persisting anything, so a broken condition is caught at
+    // author time instead of locking a key out at enforcement. A broken condition
+    // is a 400 the transport throws — never a false-positive `ok`.
+    validateCondition: (body: ValidateConditionBody) =>
+      req('/api/auth/validate-condition', s.validateConditionResult, { method: 'POST', body }),
+    // The user's append-only policy version history (each row's `is_current`
+    // derived from the active pointer). SECRET-ADJACENT — the body carries the raw
+    // condition, so its fixtures are hand-authored.
+    listPolicyVersions: (userId: string, signal?: AbortSignal) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/versions`, s.policyVersionList, {
+        signal,
+      }),
+    // Re-point the enforced policy to a prior version; returns the re-pointed
+    // active version. Enforcement follows on cache invalidation.
+    rollbackPolicy: (userId: string, version: number) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/rollback`, s.policyRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+  };
+}

package/src/client/presets-client.ts

@@ -0,0 +1,124 @@
+/** Preset CRUD, versioning and validation sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for creating a preset (POST `/api/presets`). `description` is the bound
+ * tool's LLM-facing docstring — REQUIRED non-empty on every create path (the door
+ * rejects an empty one with a 422); it is never the tool_meta `display_name`.
+ * `extensions` is the combos list — the create flow OMITS it when there are no
+ * combos (the route rejects an explicit `extensions: []`). `output_schema` is the
+ * optional author-set output JSON Schema; `input_schema` is the optional author-set
+ * input JSON Schema, read by the router as a top-level version field. Each combo
+ * element is a bare extension name or a `{ name, config }` mapping. Categorization
+ * tags live in the tool_meta overlay, written after a successful create — never in
+ * this body.
+ */
+export interface CreatePresetBody {
+  readonly name: string;
+  readonly base_tool: string;
+  readonly description: string;
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding applied around every run of this preset.
+  readonly state_binding?: s.StateBinding | null;
+}
+
+/**
+ * Body for saving a new preset version (POST `/api/presets/{name}/versions`). At
+ * least one field must be provided (an empty body is a loud 400). Each field's
+ * sentinel is uniform: omitted carries the active version's value forward; an
+ * explicit `[]` clears `extensions`, and an explicit `null` clears `output_schema`
+ * or `input_schema`. `input_schema` is the optional author-set input JSON Schema and
+ * follows the same carry-forward sentinel as `output_schema`. `state_binding` is the
+ * optional door-layer binding and follows the same sentinel: omitted carries the active
+ * one forward, an explicit `null` clears it. `description` carries forward when omitted;
+ * an explicit non-empty string sets it (the API rejects an explicit empty one).
+ * Categorization tags are not a version field — they live in the tool_meta overlay.
+ */
+export interface SavePresetVersionBody {
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly description?: string;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  readonly state_binding?: s.StateBinding | null;
+}
+
+/**
+ * Body for the dry-run validate door (POST `/api/presets/validate`). `name` is
+ * required and selects the verdict mode server-side: CREATE when no preset named
+ * `name` exists (then `base_tool` is required), VERSION when one does (the version
+ * fields are read under save-version semantics). The draft is sent exactly as the
+ * matching write would send it.
+ */
+export interface ValidatePresetBody {
+  readonly name: string;
+  readonly base_tool?: string;
+  readonly description?: string;
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding to dry-run — validated (never mounted) by the
+  // same checks the write would run. In VERSION mode it follows the save-version sentinel:
+  // omitted carries the active binding forward, an explicit `null` clears it.
+  readonly state_binding?: s.StateBinding | null;
+}
+
+export function presetsClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Every preset is store-backed and versioned; the list is the single
+    // management population (the presets plus the conflicted quarantined rows).
+    listPresets: (signal?: AbortSignal) => req('/api/presets', s.presetList, { signal }),
+    createPreset: (body: CreatePresetBody) =>
+      req('/api/presets', s.presetRecord, { method: 'POST', body }),
+    getPreset: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}`, s.presetDetail, { signal }),
+    listPresetVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersionList, { signal }),
+    getPresetVersion: (name: string, version: number, signal?: AbortSignal) =>
+      req(
+        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
+        s.presetVersion,
+        { signal },
+      ),
+    savePresetVersion: (name: string, body: SavePresetVersionBody) =>
+      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersion, {
+        method: 'POST',
+        body,
+      }),
+    rollbackPreset: (name: string, version: number) =>
+      req(`/api/presets/${encodeSegment(name)}/rollback`, s.presetRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+    deletePreset: (name: string) =>
+      req(`/api/presets/${encodeSegment(name)}`, s.presetDeleted, { method: 'DELETE' }),
+    renamePreset: (name: string, newName: string) =>
+      req(`/api/presets/${encodeSegment(name)}/rename`, s.presetRenamed, {
+        method: 'POST',
+        body: { new_name: newName },
+      }),
+    // The presets whose active composition names this one as a tool — the referees
+    // a rename would strand. A rename preflight reads this to warn before the 409.
+    getPresetReferees: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}/referees`, s.presetReferees, { signal }),
+    // The dry-run verdict for a draft (create OR version, mode-resolved server-side):
+    // `valid` plus the server's verbatim `error` message. Both verdicts are HTTP 200.
+    validatePreset: (body: ValidatePresetBody) =>
+      req('/api/presets/validate', s.presetValidation, { method: 'POST', body }),
+    // Replace one version's `tags` annotation — labels on an immutable body, so no
+    // rebind. Returns the re-annotated identity + new tag list.
+    setPresetVersionTags: (name: string, version: number, tags: readonly string[]) =>
+      req(
+        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}/tags`,
+        s.presetVersionTags,
+        { method: 'PUT', body: { tags } },
+      ),
+  };
+}

package/src/client/profiles-client.ts

@@ -0,0 +1,51 @@
+/** Settings-profile CRUD, versioning and apply sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function profilesClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The admin-only `/api/config/profiles/*` surface. Bodies/diff/versions carry
+    // REAL secret values (secret/fenced routes); masking is CLIENT-SIDE.
+    listSettingsProfiles: (signal?: AbortSignal) =>
+      req('/api/config/profiles', s.settingsProfileList, { signal }),
+    getSettingsProfile: (name: string, signal?: AbortSignal) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileBody, { signal }),
+    putSettingsProfile: (name: string, body: s.SettingsProfileBody) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileSaved, {
+        method: 'PUT',
+        body,
+      }),
+    deleteSettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileDeleted, {
+        method: 'DELETE',
+      }),
+    // Diff of the SAVED profile vs the stored env — server-computed, no request body.
+    diffSettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/diff`, s.settingsProfileDiff, {
+        method: 'POST',
+      }),
+    // Apply the SAVED profile (full-replace of the profile-managed band). Fenced,
+    // destructive → the dedicated `profile_apply_response` report.
+    applySettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/apply`, s.profileApplyResponse, {
+        method: 'POST',
+      }),
+    listSettingsProfileVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/versions`, s.settingsProfileVersionList, {
+        signal,
+      }),
+    getSettingsProfileVersion: (name: string, version: number, signal?: AbortSignal) =>
+      req(
+        `/api/config/profiles/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
+        s.settingsProfileVersion,
+        { signal },
+      ),
+    rollbackSettingsProfile: (name: string, version: number) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/rollback`, s.settingsProfileRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+  };
+}

package/src/client/schedules-client.ts

@@ -0,0 +1,22 @@
+/** Schedule listing and mutation sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function schedulesClient(t: Transport) {
+  const { req } = t;
+  return {
+    listSchedules: (signal?: AbortSignal) => req('/api/schedules', s.scheduleList, { signal }),
+    getServerDateTime: (signal?: AbortSignal) =>
+      req('/api/schedules/server-datetime', s.serverDateTime, { signal }),
+    addSchedule: (body: {
+      tool_name: string;
+      tool_kwargs: Record<string, unknown>;
+      schedule_kwargs: Record<string, unknown>;
+      // The optional door-layer state binding applied around every fire of this schedule.
+      state_binding?: s.StateBinding | null;
+    }) => req('/api/schedules', s.jsonValue, { method: 'POST', body }),
+    deleteSchedule: (name: string) =>
+      req(`/api/schedules/${encodeSegment(name)}`, s.jsonValue, { method: 'DELETE' }),
+  };
+}

package/src/client/settings-schema-client.ts

@@ -0,0 +1,11 @@
+/** Settings-form schema read sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function settingsSchemaClient(t: Transport) {
+  const { req } = t;
+  return {
+    getSettingsSchema: (signal?: AbortSignal) =>
+      req('/api/config/settings-schema', s.settingsSchema, { signal }),
+  };
+}

package/src/client/states-client.ts

@@ -0,0 +1,292 @@
+/** State declaration, record, template and consumer sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * The client-facing write body for a state declaration (`PUT /api/states/{name}`), the
+ * wire shape of `tai42_contract.states.StateDeclaration` minus the platform-computed
+ * `effective_schema`/`regimes` (those are read-only, refused on a write). `schema` is the
+ * `TemplatedText | dict` union: an inline JSON-schema object, or a stored template reference
+ * (`id` + render `kwargs`) the platform renders to the schema. `retention_days` is `null` to
+ * keep records forever.
+ */
+export interface StateDeclarationBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly schema: s.TemplatedText | Record<string, unknown>;
+  readonly subject_kinds: readonly string[];
+  readonly default_subject_kind: string;
+  readonly retention_days?: number | null;
+}
+
+/**
+ * A state-template document write body (`PUT /api/state-templates/{name}`, the platform half).
+ * `schema` is the `TemplatedText | dict` union — an inline fragment schema, or a stored
+ * template reference the platform renders to the fragment.
+ */
+export interface StateTemplateBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters?: Record<string, unknown>;
+  readonly schema: s.TemplatedText | Record<string, unknown>;
+  readonly regimes?: Record<string, unknown>[];
+  readonly declarations?: Record<string, unknown> | null;
+  readonly trace?: Record<string, unknown>;
+}
+
+/** A template attach / re-attach body (`PUT|PATCH /api/states/{name}/attachments/{template}`). */
+export interface StateAttachmentBody {
+  readonly path?: string[];
+  readonly parameters?: Record<string, unknown>;
+  readonly declarations?: Record<string, unknown>;
+  // Reconcile directive for a re-attach that would orphan open records: retry with
+  // `{ orphans: "close", resolution: "<name>" }` to close them (the server refuses
+  // without it). Omitted on a first attach.
+  readonly options?: Record<string, unknown>;
+}
+
+/** The four-part subject a record route addresses in its path. */
+export interface StateSubjectRef {
+  readonly target_kind: string;
+  readonly target_name: string;
+  readonly kind: string;
+  readonly key: string;
+}
+
+/** A keyset page request: an optional size and the opaque cursor a prior page returned. */
+export interface StatePageQuery {
+  readonly limit?: number;
+  readonly cursor?: string;
+}
+
+/**
+ * The subject-addressed record path: `/api/states/{name}/records/{target_kind}/
+ * {target_name}/{kind}/{key}` — four path segments, each percent-encoded, so a key
+ * carrying a slash or a colon never escapes its segment.
+ */
+function stateRecordPath(name: string, subject: StateSubjectRef): string {
+  return (
+    `/api/states/${encodeSegment(name)}/records/` +
+    `${encodeSegment(subject.target_kind)}/${encodeSegment(subject.target_name)}/` +
+    `${encodeSegment(subject.kind)}/${encodeSegment(subject.key)}`
+  );
+}
+
+/**
+ * Encode a template jq's declared params as JSON query values: the record `template-jq`
+ * route reads each `?<param>=<json>` as a JSON-decoded argument, so a string, number,
+ * array or object round-trips faithfully. An `undefined` value is dropped (an
+ * omitted optional param).
+ */
+function encodeJqParams(params?: Record<string, unknown>): Record<string, string> | undefined {
+  if (params === undefined) return undefined;
+  const query: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    query[key] = JSON.stringify(value);
+  }
+  return query;
+}
+
+/** State declaration CRUD: list, read, upsert, delete and stats of a state document. */
+function stateDeclarationMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // A state is a declared JSON document, one per subject. The list is the
+    // management population; a single state read composes the declaration with its
+    // effective schema, regimes and attachments. Every record route addresses its subject
+    // as four percent-encoded path segments (see `stateRecordPath`).
+    listStates: (signal?: AbortSignal) => req('/api/states', s.stateList, { signal }),
+    getState: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, { signal }),
+    // A plain declaration upsert — no `replace` flag. With records present the server
+    // accepts additive schema changes and refuses with a 409 any change that removes or
+    // alters an existing field, or a subject-kind removal that would strand records.
+    putState: (name: string, body: StateDeclarationBody) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, {
+        method: 'PUT',
+        body,
+      }),
+    deleteState: (name: string) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
+    getStateStats: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
+  };
+}
+
+/** Template attachments on a state: list, read, attach, re-attach and detach. */
+function stateAttachmentMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateAttachments: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
+    getStateAttachment: (name: string, template: string, signal?: AbortSignal) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachment,
+        { signal },
+      ),
+    attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttached,
+        { method: 'PUT', body },
+      ),
+    patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachmentUpdated,
+        { method: 'PATCH', body },
+      ),
+    detachStateTemplate: (name: string, template: string) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateDetached,
+        { method: 'DELETE' },
+      ),
+  };
+}
+
+/** Record reads and writes: subject listing, content search, and per-subject CRUD. */
+function stateRecordMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateSubjects: (
+      name: string,
+      params: { kind?: string } & StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/states/${encodeSegment(name)}/subjects`, s.subjectPage, {
+        signal,
+        query: { kind: params.kind, limit: params.limit, cursor: params.cursor },
+      }),
+    // The content search body is a single JSONB containment document (`filters`); the
+    // server refuses an empty one, so the UI validates a non-empty object first.
+    searchStateRecords: (
+      name: string,
+      body: { filters: Record<string, unknown> } & StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/states/${encodeSegment(name)}/records/search`, s.recordSearchPage, {
+        method: 'POST',
+        body,
+        signal,
+      }),
+    // A subject with no document yet reads as `null` (a 200 `{data: null}`, the record
+    // page's Create path) — never an error, so the schema is nullable.
+    getStateRecord: (name: string, subject: StateSubjectRef, signal?: AbortSignal) =>
+      req(stateRecordPath(name, subject), s.stateRecord.nullable(), { signal }),
+    putStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PUT', body: data }),
+    patchStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PATCH', body: data }),
+    applyStateRecord: (
+      name: string,
+      subject: StateSubjectRef,
+      ops: readonly Record<string, unknown>[],
+    ) =>
+      req(`${stateRecordPath(name, subject)}/deltas`, s.applyResult, {
+        method: 'POST',
+        body: { ops },
+      }),
+  };
+}
+
+/** Record operations on a subject: template-jq eval/apply, delete, fold, write log, consumers. */
+function stateRecordOpMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // Evaluate a template jq over the subject: each declared param is JSON-encoded into
+    // the query string (`?<param>=<json>`); the response is `{name, purpose, value}`. An
+    // `attachment.name` jq is percent-encoded as one path segment.
+    evalTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      params?: Record<string, unknown>,
+      signal?: AbortSignal,
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqResult,
+        { signal, query: encodeJqParams(params) },
+      ),
+    // Apply an `update`-purpose template jq to the subject: `input` is the jq's argument,
+    // `op_id` its idempotency key (a replay is a no-op). The jq lands its op batch through
+    // the apply chokepoint. An `attachment.name` jq is percent-encoded as one path segment.
+    applyTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      body?: { input?: unknown; op_id?: string },
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqApplyResult,
+        { method: 'POST', body: body ?? {} },
+      ),
+    deleteStateRecord: (name: string, subject: StateSubjectRef) =>
+      req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
+    // `mode` is required server-side (`switch` drops, `merge` combines); the fold returns
+    // a report, not the surviving record.
+    foldStateRecord: (
+      name: string,
+      subject: StateSubjectRef,
+      into: StateSubjectRef,
+      mode: 'switch' | 'merge',
+    ) =>
+      req(`${stateRecordPath(name, subject)}/fold`, s.stateFoldReport, {
+        method: 'POST',
+        body: { into, mode },
+      }),
+    listStateWrites: (
+      name: string,
+      subject: StateSubjectRef,
+      params?: StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`${stateRecordPath(name, subject)}/writes`, s.writesPage, {
+        signal,
+        query: { limit: params?.limit, cursor: params?.cursor },
+      }),
+    stateConsumers: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
+  };
+}
+
+/** State-template documents and retention: list, read, upsert, delete, prune. */
+function stateTemplateMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateTemplates: (signal?: AbortSignal) =>
+      req('/api/state-templates', s.stateTemplateList, { signal }),
+    getStateTemplate: (name: string, signal?: AbortSignal) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
+    putStateTemplate: (name: string, body: StateTemplateBody, replace?: boolean) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, {
+        method: 'PUT',
+        body,
+        query: replace === true ? { replace: 'true' } : undefined,
+      }),
+    deleteStateTemplate: (name: string) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDeleted, {
+        method: 'DELETE',
+      }),
+    pruneStateRetention: () =>
+      req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
+  };
+}
+
+export function statesClient(t: Transport) {
+  // Declaration emit prepends each spread group's members, so the groups are
+  // spread in reverse of their public order to keep the surface declaration →
+  // attachments → records → record-ops → templates.
+  return {
+    ...stateTemplateMethods(t),
+    ...stateRecordOpMethods(t),
+    ...stateRecordMethods(t),
+    ...stateAttachmentMethods(t),
+    ...stateDeclarationMethods(t),
+  };
+}