@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/definition-set.ts

@@ -0,0 +1,965 @@
+/**
+ * Definition sets and Tenant keys (ADR-029, ADR-030) — the part a Tenant's own
+ * application server uses. A Tenant keeps its whole Definition set as one file;
+ * when its application starts, `applyDefinitions` sends it through the Tenant
+ * API, signed with a Tenant key whose private half never leaves the Tenant.
+ *
+ * Dependency-free and Web Crypto only, like the rest of the kit; the signing
+ * functions refuse to run in a browser, so a key bundled by mistake fails
+ * instead of working.
+ */
+
+import type { TenantSubscriptionView } from "./tenant-subscription.js";
+import type { FieldValueType } from "./types.js";
+import type { CustomerEntitlements, TenantTierSet, TierRules } from "./tiers.js";
+import type { RevealLevel } from "./reveal.js";
+import type { FillMode, LocatorRule } from "./fill.js";
+import type { RepositoryBranding, RepositoryPortal, TenantSource } from "./branding.js";
+import type { PortalPage, PortalSwitch } from "./portal-options.js";
+import type { ChangesetStatus, FeedbackReport, TenantChangeset } from "./changesets.js";
+import { SDK_USER_AGENT } from "./version.js";
+import type { AnnouncementItem, AnyStatus, Priority, TicketSummary, TicketView } from "./tickets.js";
+import { type TagColour, type TagEffect, type TagRule, type TagSelector, type TagView, type TagVisibility, encodeSelector } from "./tags.js";
+
+// ------------------------------------------------------------- the set
+
+/** A field's rules in a Definition set: a FieldDefinition without its `name`, which is the key it stands under. */
+export interface SetFieldSpec {
+  label?: string;
+  description?: string;
+  value_type: FieldValueType;
+  validation?: { pattern?: string; min?: number; max?: number; min_length?: number; max_length?: number; enum?: (string | number | boolean)[] };
+  secret?: boolean;
+  reveal?: RevealLevel;
+  searchable?: boolean;
+  immutable?: boolean;
+  locked?: boolean;
+  /** ADR-046: the modes a Field may use, the first preselected. Absent: `value`, `internal`, `external`. */
+  filled_by?: FillMode[];
+  /** Resource type tokens an internal reference may point at (`fld`, `ent`, `wlt`, `att`, …). Absent: any. */
+  targets?: string[];
+  /**
+   * Definitions of this set a target must be of. A bare key is an Entry type, as in `accepts`; a Wallet type or a
+   * field is named by its address (`wallet:<key>`, `field:<entry>.<key>`, `field:shared.<key>`). Each restricts
+   * targets of its own kind. Absent: any.
+   */
+  target_definitions?: string[];
+  locator?: LocatorRule;
+}
+
+/** What belongs to the reference, wherever the field is declared. `fill_in` only with `required`. */
+export interface SetFieldReference {
+  required?: boolean;
+  order?: number;
+  fill_in?: unknown;
+}
+
+/** A field owned by its Entry type (address `<entry>.<key>`), or one of the shared fields (`{ use: "<key>" }`, optionally narrowing its modes here). */
+export type SetEntryField = (SetFieldSpec & SetFieldReference) | ({ use: string; filled_by?: FillMode[] } & SetFieldReference);
+
+export interface SetEntry {
+  label?: string;
+  description?: string;
+  kind?: "file" | "folder";
+  nestable?: boolean;
+  /** Folders only: Entry type keys. */
+  contains?: string[];
+  customizable?: boolean;
+  value_types?: FieldValueType[];
+  secret_reveal_min?: RevealLevel;
+  /** The modes a custom field on this type may allow (ADR-046). Absent: all three. */
+  custom_filled_by?: FillMode[];
+  fields: Record<string, SetEntryField>;
+}
+
+export interface SetWallet {
+  label?: string;
+  description?: string;
+  /**
+   * The Entry types this Wallet type owns, by key; it accepts each of them and
+   * no other Wallet type may. An Entry type key is unique across the set.
+   */
+  entries?: Record<string, SetEntry>;
+  /** Entry types from `shared_entries` this Wallet type accepts, by key. */
+  accepts?: string[];
+  nestable?: boolean;
+  immutable?: boolean;
+  metering?: "storage" | "events";
+  event_retention_days?: number;
+  default_policy?: Record<string, unknown>;
+}
+
+/**
+ * Every Definition of one Tenant, as one document (ADR-029, ADR-031): Wallet
+ * types with the Entry types they own, Entry types with the fields they own,
+ * and what is shared on purpose — fields used by several Entry types
+ * (`shared_fields`, through `use`) and Entry types accepted by several Wallet
+ * types or by none (`shared_entries`, through `accepts`). Keys are permanent;
+ * labels are what people see. The tree is only how the set is written: an
+ * Entry type is one EntryDefinition, addressed `entry:<key>` wherever it is
+ * declared.
+ */
+export interface DefinitionSet {
+  shared_fields?: Record<string, SetFieldSpec>;
+  shared_entries?: Record<string, SetEntry>;
+  wallets: Record<string, SetWallet>;
+  /** `expose:<address>` for each change that makes values more visible. Not part of the set's hash. */
+  acknowledge?: string[];
+}
+
+/** One Entry type of a set with the Wallet type that owns it, or `null` for a shared one. */
+export interface SetEntryOf extends SetEntry {
+  wallet: string | null;
+}
+
+/**
+ * Every Entry type of a set by its key, wherever it is declared. When a key is
+ * declared twice the first one wins here (shared, then Wallet types in order);
+ * the Engine refuses such a set.
+ */
+export function entryTypesOf(set: Pick<DefinitionSet, "wallets" | "shared_entries">): Record<string, SetEntryOf> {
+  const out: Record<string, SetEntryOf> = {};
+  for (const [ek, e] of Object.entries(set.shared_entries ?? {})) out[ek] = { ...e, wallet: null };
+  for (const [wk, w] of Object.entries(set.wallets ?? {})) for (const [ek, e] of Object.entries(w.entries ?? {})) if (!out[ek]) out[ek] = { ...e, wallet: wk };
+  return out;
+}
+
+/** The Entry type keys a Wallet type accepts: those it owns, then the shared ones it names in `accepts`. */
+export function acceptedBy(wallet: SetWallet): string[] {
+  return [...new Set([...Object.keys(wallet.entries ?? {}), ...(wallet.accepts ?? [])])];
+}
+
+/** A set in the format of changeset 003: Entry types at the top level, Wallet types naming them in `accepts`. */
+export interface FlatDefinitionSet {
+  shared_fields?: Record<string, SetFieldSpec>;
+  entries: Record<string, SetEntry>;
+  wallets: Record<string, Omit<SetWallet, "entries" | "accepts"> & { accepts: string[] }>;
+  acknowledge?: string[];
+}
+
+/**
+ * A set with Entry types at the top level, as the tree — the same rule as for
+ * fields: an Entry type accepted by exactly one Wallet type moves under it;
+ * one accepted by several Wallet types, or by none, goes to `shared_entries`
+ * and the Wallet types that accept it name it in `accepts`. The Definitions
+ * the set describes do not change.
+ */
+export function nestDefinitionSet(flat: FlatDefinitionSet): DefinitionSet {
+  const users = new Map<string, string[]>();
+  for (const [wk, w] of Object.entries(flat.wallets ?? {})) for (const ek of new Set(w.accepts ?? [])) users.set(ek, [...(users.get(ek) ?? []), wk]);
+  const owned = (ek: string) => (users.get(ek)?.length ?? 0) === 1 && Object.prototype.hasOwnProperty.call(flat.entries ?? {}, ek);
+  const shared_entries: Record<string, SetEntry> = {};
+  for (const [ek, e] of Object.entries(flat.entries ?? {})) if (!owned(ek)) shared_entries[ek] = e;
+  const wallets: Record<string, SetWallet> = {};
+  for (const [wk, w] of Object.entries(flat.wallets ?? {})) {
+    const { accepts, ...rest } = w;
+    const keys = [...new Set(accepts ?? [])];
+    const own = Object.fromEntries(keys.filter(owned).map((ek) => [ek, flat.entries[ek]]));
+    const others = keys.filter((ek) => !owned(ek));
+    wallets[wk] = { ...rest, ...(Object.keys(own).length ? { entries: own } : {}), ...(others.length ? { accepts: others } : {}) };
+  }
+  return {
+    ...(flat.shared_fields ? { shared_fields: flat.shared_fields } : {}),
+    ...(Object.keys(shared_entries).length ? { shared_entries } : {}),
+    wallets,
+    ...(flat.acknowledge ? { acknowledge: flat.acknowledge } : {}),
+  };
+}
+
+/** The effect of one change, as a plan reports it (ADR-029, decision 5). */
+export type PlanEffect = "repins" | "creates" | "tightens" | "stays_pinned" | "may_stay_pinned" | "retires_values" | "withdraws" | "exposes";
+
+export interface PlanChange {
+  /** `wallet:<key>`, `entry:<key>`, `field:<entry>.<key>` or `field:shared.<key>`. */
+  address: string;
+  kind: "wallet" | "entry" | "field";
+  /** What changed, in a word: `registered`, `label`, `value_type`, `validation_tighter`, `field_added_required`, … */
+  change: string;
+  effect: PlanEffect;
+  safe: boolean;
+  /** Resources on this Definition per version, counted from their pins — never from their content. */
+  in_use?: { version: number; count: number }[];
+  detail?: Record<string, unknown>;
+}
+
+export interface PlanRefusal {
+  address?: string;
+  reason: string;
+}
+
+export interface DefinitionPlan {
+  plan_id: string;
+  based_on: number;
+  hash: string;
+  changes: PlanChange[];
+  refused: PlanRefusal[];
+  /** What the set still says in an older form, read as its current form (e.g. a reference value type, ADR-046). Nothing to approve. */
+  warnings?: PlanRefusal[];
+  /** Every change is safe: a submission may apply it at once under `auto_apply: safe`. */
+  safe: boolean;
+  /** Nothing would be published. */
+  empty: boolean;
+  expires_at: string;
+  /** The revision a revert plan brings back (ADR-049). */
+  reverts?: number;
+}
+
+export type DefinitionSubmitStatus = "unchanged" | "applied" | "waiting" | "refused";
+
+export interface DefinitionSubmitResult {
+  status: DefinitionSubmitStatus;
+  hash: string;
+  /** The revision now live: the new one when `applied`, the current one otherwise. */
+  revision: number;
+  plan_id?: string;
+  summary?: { changes: number; unsafe: number };
+  changes?: PlanChange[];
+  reasons?: PlanRefusal[];
+  /** What the set still says in an older form, read as its current form (ADR-046). */
+  warnings?: PlanRefusal[];
+  /** Where a tenant administrator approves a waiting plan. */
+  approve_url?: string;
+  /** The set waits because an administrator reverted it, in this revision (ADR-049). */
+  reverted_in?: number;
+}
+
+export interface DefinitionStatus {
+  revision: number;
+  hash: string | null;
+  source: "admin_ui" | "repository";
+  auto_apply: "safe" | "none";
+  waiting: { plan_id: string; hash: string; created_at: string }[];
+}
+
+/**
+ * JSON with object keys sorted and `undefined` dropped: the same bytes for the
+ * same value wherever it is computed, so the kit and the Engine agree on a hash.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+
+/** The set without `acknowledge`, canonical: what its hash covers. */
+export function definitionSetHashInput(set: DefinitionSet | Record<string, unknown>): string {
+  const { acknowledge: _a, ...rest } = set as Record<string, unknown>;
+  return canonicalJson(rest);
+}
+
+/** SHA-256 hex of the set's canonical form, as the Engine reports it (`hash`). */
+export async function definitionSetHash(set: DefinitionSet | Record<string, unknown>): Promise<string> {
+  return hex(await subtle().digest("SHA-256", new TextEncoder().encode(definitionSetHashInput(set))));
+}
+
+// ----------------------------------------------------------- Tenant API
+
+/**
+ * The Tenant API's routes (ADR-030, decision 5; ADR-038; ADR-039; ADR-057;
+ * ADR-058; ADR-059): the only paths it forwards, and the scope each needs. A
+ * route whose scope is `null` is reached by any live key of the Tenant.
+ */
+export const TENANT_API_ROUTES: readonly { method: string; path: string; scope: TenantKeyScope | null }[] = [
+  { method: "POST", path: "/tenant/v0/definitions", scope: "definitions" },
+  { method: "GET", path: "/tenant/v0/definitions/status", scope: "definitions" },
+  { method: "GET", path: "/tenant/v0/branding", scope: "branding" },
+  { method: "PUT", path: "/tenant/v0/branding", scope: "branding" },
+  { method: "GET", path: "/tenant/v0/portal", scope: "portal" },
+  { method: "PUT", path: "/tenant/v0/portal", scope: "portal" },
+  { method: "GET", path: "/tenant/v0/tiers", scope: "tiers" },
+  { method: "PUT", path: "/tenant/v0/tiers", scope: "tiers" },
+  { method: "PUT", path: "/tenant/v0/customers/:cst/entitlement", scope: "entitlements" },
+  { method: "GET", path: "/tenant/v0/customers/:cst/entitlements", scope: "entitlements" },
+  // A Tenant's agent reads its tier and use (ADR-064 §11). Paying stays with people.
+  { method: "GET", path: "/tenant/v0/subscription", scope: null },
+  // Tags (ADR-057 §7): the Tenant's own tags, and tagging its Customers, by name.
+  { method: "GET", path: "/tenant/v0/tags", scope: "tags" },
+  { method: "PUT", path: "/tenant/v0/tags/:name", scope: "tags" },
+  { method: "PUT", path: "/tenant/v0/customers/:cst/tags/:name", scope: "tags" },
+  { method: "DELETE", path: "/tenant/v0/customers/:cst/tags/:name", scope: "tags" },
+  // The Engine, its changesets and the Tenant's feedback (ADR-054 §7, ADR-059 §5): any live key, no scope.
+  { method: "GET", path: "/tenant/v0/engine", scope: null },
+  // The calling key's own record (ADR-074 §8): any live key, no scope.
+  { method: "GET", path: "/tenant/v0/key", scope: null },
+  { method: "GET", path: "/tenant/v0/changesets", scope: null },
+  { method: "PUT", path: "/tenant/v0/changesets/:n/status", scope: null },
+  { method: "POST", path: "/tenant/v0/feedback", scope: null },
+  { method: "GET", path: "/tenant/v0/feedback", scope: null },
+  { method: "POST", path: "/tenant/v0/feedback/:tkt/posts", scope: null },
+  // Tickets and announcements (ADR-058 §10): the Tenant's servers as a party of their own Tenant's tickets.
+  { method: "GET", path: "/tenant/v0/tickets", scope: "tickets" },
+  { method: "POST", path: "/tenant/v0/tickets", scope: "tickets" },
+  { method: "GET", path: "/tenant/v0/tickets/:tkt", scope: "tickets" },
+  { method: "PATCH", path: "/tenant/v0/tickets/:tkt", scope: "tickets" },
+  { method: "POST", path: "/tenant/v0/tickets/:tkt/posts", scope: "tickets" },
+  { method: "GET", path: "/tenant/v0/announcements", scope: "tickets" },
+  { method: "POST", path: "/tenant/v0/announcements", scope: "tickets" },
+  { method: "GET", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+  { method: "PATCH", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+  { method: "DELETE", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+];
+
+export type TenantKeyScope = "definitions" | "branding" | "portal" | "tiers" | "entitlements" | "tags" | "tickets";
+export const TENANT_KEY_SCOPES: readonly TenantKeyScope[] = ["definitions", "branding", "portal", "tiers", "entitlements", "tags", "tickets"];
+/** What a Tenant keeps in its repository (ADR-038, decision 4): one key may carry any of these together. */
+export const REPOSITORY_SCOPES: readonly TenantKeyScope[] = ["definitions", "branding", "portal", "tiers"];
+
+/** Why a key cannot carry these scopes, or null: at least one known scope, none twice, and `entitlements` only on its own (the billing backend keeps its own key). */
+export function tenantKeyScopesProblem(scopes: readonly string[]): string | null {
+  if (!scopes.length) return "a key needs at least one scope";
+  const unknown = scopes.filter((s) => !(TENANT_KEY_SCOPES as readonly string[]).includes(s));
+  if (unknown.length) return `unknown scope: ${unknown.join(", ")}`;
+  if (new Set(scopes).size !== scopes.length) return "a scope is named twice";
+  if (scopes.includes("entitlements") && scopes.length > 1) return "entitlements is never combined with another scope: the billing backend keeps its own key";
+  return null;
+}
+
+/** A key's scopes from its stored or listed form: `scopes`, or `scope` as one scope or several separated by spaces (keys from before ADR-038). */
+export function tenantKeyScopesOf(record: { scopes?: unknown; scope?: unknown }): TenantKeyScope[] {
+  const raw = Array.isArray(record.scopes) ? record.scopes : typeof record.scope === "string" ? record.scope.split(/\s+/) : [];
+  return raw.filter((s): s is TenantKeyScope => typeof s === "string" && (TENANT_KEY_SCOPES as readonly string[]).includes(s));
+}
+export type TenantApiRoute = (typeof TENANT_API_ROUTES)[number];
+
+/** Whether a key with these scopes reaches a route: it carries the route's scope, or the route names none. */
+export function keyReachesRoute(scopes: readonly string[], route: Pick<TenantApiRoute, "scope">): boolean {
+  return route.scope === null || scopes.includes(route.scope);
+}
+
+function matchPattern(pattern: string, path: string): Record<string, string> | null {
+  const p = pattern.split("/");
+  const a = path.split("/");
+  if (p.length !== a.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < p.length; i++) {
+    if (p[i].startsWith(":")) {
+      if (!a[i]) return null;
+      params[p[i].slice(1)] = decodeURIComponent(a[i]);
+    } else if (p[i] !== a[i]) return null;
+  }
+  return params;
+}
+
+const fill = (pattern: string, params: Record<string, string>) => pattern.replace(/:([a-z_]+)/g, (_, k: string) => encodeURIComponent(params[k] ?? ""));
+
+/** The route a Tenant API request names, with its parameters, or null when the Tenant API has no such route. */
+export function matchTenantApiRoute(method: string, path: string): { route: TenantApiRoute; params: Record<string, string> } | null {
+  for (const route of TENANT_API_ROUTES) {
+    if (route.method !== method.toUpperCase()) continue;
+    const params = matchPattern(route.path, path);
+    if (params) return { route, params };
+  }
+  return null;
+}
+
+/** A route pattern's parameters, or null when the path does not fit: shared with the Engine, which matches its forwards the same way. */
+export function matchRoutePattern(pattern: string, path: string): Record<string, string> | null {
+  return matchPattern(pattern, path);
+}
+
+/** A route pattern with its parameters filled in, each encoded. */
+export function fillRoutePattern(pattern: string, params: Record<string, string>): string {
+  return fill(pattern, params);
+}
+
+// ----------------------------------------------------------- Tenant keys
+
+export const TENANT_KEY_PREFIX = "atk";
+export const TENANT_ASSERTION_AUDIENCE = "asturiu-tenant-api";
+/** Longest an assertion may live, and the most a key may live (ADR-030). */
+export const TENANT_ASSERTION_MAX_SECONDS = 60;
+export const TENANT_KEY_MAX_DAYS = 180;
+
+export interface TenantKeyParts {
+  slug: string;
+  kid: string;
+  /** PKCS#8 private key, base64url. */
+  pkcs8: string;
+}
+
+/** `atk.<slug>.<key id>.<private key>` — the one environment variable a Tenant's server holds. */
+export function parseTenantKey(value: string): TenantKeyParts {
+  const m = /^atk\.([a-z0-9][a-z0-9-]*)\.([0-9a-f]{16})\.([A-Za-z0-9_-]{40,})$/.exec((value ?? "").trim());
+  if (!m) throw new Error("not a Tenant key: expected atk.<slug>.<key id>.<private key>");
+  return { slug: m[1], kid: m[2], pkcs8: m[3] };
+}
+
+export function formatTenantKey(parts: TenantKeyParts): string {
+  return `${TENANT_KEY_PREFIX}.${parts.slug}.${parts.kid}.${parts.pkcs8}`;
+}
+
+/**
+ * A new Ed25519 key pair, made where this runs (the administrator's browser in
+ * the Admin UI): the private half as PKCS#8 for the Tenant to keep, the public
+ * half as the raw 32 bytes for Asturiu to store. Both base64url.
+ */
+export async function generateTenantKeyPair(): Promise<{ privatePkcs8: string; publicRaw: string }> {
+  const pair = (await subtle().generateKey({ name: "Ed25519" }, true, ["sign", "verify"])) as { privateKey: Parameters<ReturnType<typeof subtle>["exportKey"]>[1]; publicKey: Parameters<ReturnType<typeof subtle>["exportKey"]>[1] };
+  const [priv, pub] = await Promise.all([subtle().exportKey("pkcs8", pair.privateKey), subtle().exportKey("raw", pair.publicKey)]);
+  return { privatePkcs8: b64url(new Uint8Array(priv)), publicRaw: b64url(new Uint8Array(pub)) };
+}
+
+function refuseBrowser(what: string): void {
+  const g = globalThis as { window?: unknown; document?: unknown };
+  if (g.window !== undefined && g.document !== undefined) throw new Error(`${what} runs on a server only: a Tenant key must never reach a browser`);
+}
+
+/**
+ * The signed assertion for one request (ADR-030, decision 3): valid for one
+ * minute, for this method, path and body, once. The key itself is never sent.
+ */
+export async function signTenantAssertion(opts: { key: string; method: string; path: string; body?: string | Uint8Array; now?: number }): Promise<string> {
+  refuseBrowser("signTenantAssertion");
+  const k = parseTenantKey(opts.key);
+  const now = Math.floor((opts.now ?? Date.now()) / 1000);
+  const bytes = typeof opts.body === "string" ? new TextEncoder().encode(opts.body) : (opts.body ?? new Uint8Array());
+  const bdh = b64url(new Uint8Array(await subtle().digest("SHA-256", bytes)));
+  const header = { alg: "EdDSA", typ: "JWT", kid: k.kid };
+  const claims = { iss: k.slug, sub: k.kid, aud: TENANT_ASSERTION_AUDIENCE, htm: opts.method.toUpperCase(), htu: opts.path, bdh, iat: now, exp: now + TENANT_ASSERTION_MAX_SECONDS, jti: randomId() };
+  const input = `${b64urlText(JSON.stringify(header))}.${b64urlText(JSON.stringify(claims))}`;
+  const key = await subtle().importKey("pkcs8", fromB64url(k.pkcs8), { name: "Ed25519" }, false, ["sign"]);
+  const sig = await subtle().sign({ name: "Ed25519" }, key, new TextEncoder().encode(input));
+  return `${input}.${b64url(new Uint8Array(sig))}`;
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+type Logger = { info: (msg: string, detail?: Record<string, unknown>) => void; warn: (msg: string, detail?: Record<string, unknown>) => void; error: (msg: string, detail?: Record<string, unknown>) => void };
+const consoleLog: Logger = {
+  info: (m, d) => console.info(`[asturiu] ${m}`, d ?? ""),
+  warn: (m, d) => console.warn(`[asturiu] ${m}`, d ?? ""),
+  error: (m, d) => console.error(`[asturiu] ${m}`, d ?? ""),
+};
+
+/**
+ * What every Tenant API call throws when the Engine answers with an error
+ * (ADR-074 §2): `status` tells a route this Engine lacks (`404`) from a
+ * refusal (`401`, `403`, `409`, `422`). `type` and `detail` are the
+ * problem document's. A network failure is not one: `fetch` throws its own.
+ */
+export class TenantApiError extends Error {
+  readonly status: number;
+  readonly type: string | null;
+  readonly detail: string | null;
+  /** The whole problem document, with `issues` when the Engine names them. */
+  readonly problem: Record<string, unknown> | null;
+  constructor(status: number, problem: unknown) {
+    const p = problem && typeof problem === "object" ? (problem as Record<string, unknown>) : null;
+    const detail = typeof p?.detail === "string" ? p.detail : null;
+    const title = typeof p?.title === "string" ? p.title : null;
+    super(detail ?? title ?? `HTTP ${status}`);
+    this.name = "TenantApiError";
+    this.status = status;
+    this.type = typeof p?.type === "string" ? p.type : null;
+    this.detail = detail;
+    this.problem = p;
+  }
+}
+
+const fail = (r: { status: number; json: unknown }) => new TenantApiError(r.status, r.json);
+
+/** The assertion signs the path alone; a query rides beside it (`?since=`), as the Operations API checks the route's path. */
+async function tenantCall(opts: { key: string; baseUrl: string; method: string; path: string; query?: Record<string, string | number | undefined>; body?: unknown; idempotencyKey?: string; fetch?: FetchLike; log?: Logger }): Promise<{ status: number; json: any; keyExpires: string | null }> {
+  const text = opts.body === undefined ? "" : JSON.stringify(opts.body);
+  const assertion = await signTenantAssertion({ key: opts.key, method: opts.method, path: opts.path, body: text });
+  const f: FetchLike = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  // The SDK names its version, which the Engine records on the key as `last_sdk_version` (ADR-074 §4): how an administrator sees what a Tenant runs.
+  const headers: Record<string, string> = { authorization: `Asturiu-Assertion ${assertion}`, accept: "application/json", "user-agent": SDK_USER_AGENT };
+  if (text) headers["content-type"] = "application/json";
+  if (opts.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
+  const q = Object.entries(opts.query ?? {}).filter((e): e is [string, string | number] => e[1] !== undefined && e[1] !== "");
+  const search = q.length ? `?${new URLSearchParams(q.map(([k, v]): [string, string] => [k, String(v)])).toString()}` : "";
+  const res = await f(`${opts.baseUrl.replace(/\/+$/, "")}${opts.path}${search}`, { method: opts.method, headers, body: text || undefined });
+  const keyExpires = res.headers.get("asturiu-key-expires");
+  if (keyExpires) (opts.log ?? consoleLog).warn("the Tenant key expires soon; create its successor in the Admin UI and replace the environment variable", { expires: keyExpires });
+  const json = await res.json().catch(() => null);
+  return { status: res.status, json, keyExpires };
+}
+
+/**
+ * Send the application's Definition set when it starts (ADR-029, the
+ * repository flow). Never throws and never blocks start-up: the outcome is
+ * logged — applied, unchanged, waiting for a tenant administrator, or refused
+ * with the reasons — and returned.
+ */
+export async function applyDefinitions(opts: { set: DefinitionSet | string; key: string; baseUrl: string; fetch?: FetchLike; log?: Logger }): Promise<DefinitionSubmitResult | { status: "error"; message: string }> {
+  const log = opts.log ?? consoleLog;
+  try {
+    refuseBrowser("applyDefinitions");
+    const set = typeof opts.set === "string" ? (JSON.parse(opts.set) as DefinitionSet) : opts.set;
+    const hash = await definitionSetHash(set);
+    // A fresh key per start: the submission is idempotent by its hash already, and a replayed answer would
+    // report "waiting" for a plan an administrator has since approved.
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/definitions", body: set, idempotencyKey: `definitions-${hash.slice(0, 32)}-${randomId()}`, fetch: opts.fetch, log });
+    if (r.status >= 400 && r.json?.status !== "refused") {
+      const message = r.json?.detail ?? r.json?.title ?? `HTTP ${r.status}`;
+      log.error("Definition set not submitted", { status: r.status, message });
+      return { status: "error", message };
+    }
+    const out = r.json as DefinitionSubmitResult;
+    if (out.status === "applied") log.info("Definition set applied", { revision: out.revision, hash: out.hash, changes: out.summary?.changes });
+    else if (out.status === "unchanged") log.info("Definition set unchanged", { revision: out.revision });
+    else if (out.status === "waiting" && out.reverted_in) log.warn(`Definition set waits for a tenant administrator: an administrator reverted it in revision ${out.reverted_in}; correct the repository's file, or have it approved again`, { plan: out.plan_id, approve: out.approve_url });
+    else if (out.status === "waiting") log.warn("Definition set waits for a tenant administrator: it changes existing data", { plan: out.plan_id, approve: out.approve_url, unsafe: out.summary?.unsafe });
+    else log.error("Definition set refused", { reasons: out.reasons });
+    return out;
+  } catch (err) {
+    const message = (err as Error).message;
+    log.error("Definition set not submitted", { message });
+    return { status: "error", message };
+  }
+}
+
+/** What `PUT /tenant/v0/branding` and `PUT /tenant/v0/portal` answer (ADR-038). `kept`, on the portal's answer: redirected pages the body named, left as an administrator set them (ADR-039). */
+export interface TenantRepositoryResult {
+  status: "unchanged" | "applied";
+  kept?: PortalPage[];
+}
+
+async function applyWhole(what: "branding" | "portal" | "tiers", opts: { body: Record<string, unknown> | string; key: string; baseUrl: string; fetch?: FetchLike; log?: Logger }): Promise<TenantRepositoryResult | { status: "error"; message: string; problems?: unknown }> {
+  const log = opts.log ?? consoleLog;
+  const label = what === "branding" ? "Branding" : what === "portal" ? "Portal options" : "Tiers";
+  try {
+    refuseBrowser(what === "branding" ? "applyBranding" : what === "portal" ? "applyPortal" : "applyTiers");
+    const body = typeof opts.body === "string" ? (JSON.parse(opts.body) as Record<string, unknown>) : opts.body;
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/${what}`, body, idempotencyKey: `${what}-${randomId()}`, fetch: opts.fetch, log });
+    if (r.status >= 400) {
+      const message = r.json?.detail ?? r.json?.title ?? `HTTP ${r.status}`;
+      log.error(`${label} not applied`, { status: r.status, message, ...(r.json?.issues ? { issues: r.json.issues } : {}) });
+      return { status: "error", message, ...(r.json?.issues ? { problems: r.json.issues } : {}) };
+    }
+    const out = r.json as TenantRepositoryResult;
+    log.info(out.status === "applied" ? `${label} applied` : `${label} unchanged`);
+    if (out.kept?.length) log.warn("these portal pages stay where an administrator moved them (the Tenant's application); leave them out, or ask an administrator to bring them back", { pages: out.kept });
+    return out;
+  } catch (err) {
+    const message = (err as Error).message;
+    log.error(`${label} not applied`, { message });
+    return { status: "error", message };
+  }
+}
+
+/**
+ * Send the branding the repository keeps when the application starts
+ * (ADR-038): the theme, `primary_color` and the images, inline
+ * (`inlineImage(bytes, type)`) — everything the Admin UI's Branding tab sets
+ * except addresses. The whole desired state of those keys: one left out is
+ * cleared, so send the whole theme. A string is read as JSON (a
+ * `branding.json` kept in the repository, as the Admin UI exports it).
+ * Applies at once; never throws, never blocks start-up.
+ */
+export async function applyBranding(opts: { branding: RepositoryBranding | string; key: string; baseUrl: string; fetch?: FetchLike; log?: Logger }) {
+  return applyWhole("branding", { ...opts, body: opts.branding as Record<string, unknown> | string });
+}
+
+/**
+ * Send the portal options the repository keeps when the application starts
+ * (ADR-038, ADR-039): the switches and which pages show. A switch left out is
+ * on, a page left out is in the portal; a page an administrator moved to the
+ * application keeps its redirect and comes back in `kept`. Like `applyBranding`.
+ */
+export async function applyPortal(opts: { portal: RepositoryPortal | string; key: string; baseUrl: string; fetch?: FetchLike; log?: Logger }) {
+  return applyWhole("portal", { ...opts, body: opts.portal as Record<string, unknown> | string });
+}
+
+/** The block a repository keeps (ADR-061 §10): the tiers, `default_tier` and `tier_rules`. */
+export type RepositoryTiers = Pick<TenantTierSet, "tiers" | "default_tier"> & { tier_rules?: Partial<Omit<TierRules, "changed_at">> };
+
+/**
+ * Send the tiers the repository keeps when the application starts (ADR-061
+ * §10). Run it after `applyDefinitions`, as tiers name Wallet types by key.
+ * Like `applyBranding`, it never blocks start-up.
+ */
+export async function applyTiers(opts: { tiers: RepositoryTiers | string; key: string; baseUrl: string; fetch?: FetchLike; log?: Logger }) {
+  return applyWhole("tiers", { ...opts, body: opts.tiers as Record<string, unknown> | string });
+}
+
+/** What `GET /tenant/v0/tiers` answers: who edits the tab, and the block a `PUT` would send back unchanged. */
+export interface RepositoryTiersState extends RepositoryTiers {
+  source: TenantSource;
+}
+
+/** The tiers as stored, in the shape `applyTiers` takes. Like `readBranding`. */
+export async function readTiers(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<RepositoryTiersState> {
+  refuseBrowser("readTiers");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tiers", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** What one Customer may do now, for a server-side check or a background job (ADR-061 §9), with a key of scope `entitlements`. */
+export async function readEntitlements(opts: { customer: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<CustomerEntitlements> {
+  refuseBrowser("readEntitlements");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/entitlements`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** What `GET /tenant/v0/branding` answers (ADR-039): who edits the tab, and the branding a `PUT` would send back unchanged. */
+export interface RepositoryBrandingState {
+  source: TenantSource;
+  branding: RepositoryBranding;
+}
+
+/** What `GET /tenant/v0/portal` answers (ADR-039): who edits the tab, the options a `PUT` would send back unchanged, and the pages an administrator moved to the Tenant's application. */
+export interface RepositoryPortalState {
+  source: TenantSource;
+  portal: Record<PortalSwitch, boolean> & { pages: RepositoryPortal["pages"] };
+  redirected: PortalPage[];
+}
+
+/**
+ * The branding as stored, in the shape `applyBranding` takes: to take the
+ * look designed in the Admin UI into the repository before the tab is handed
+ * over, or to compare. Readable whatever the tab's source. Throws on an error.
+ */
+export async function readBranding(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<RepositoryBrandingState> {
+  refuseBrowser("readBranding");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/branding", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** The portal options as stored, in the shape `applyPortal` takes. Like `readBranding`. */
+export async function readPortal(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<RepositoryPortalState> {
+  refuseBrowser("readPortal");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/portal", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Report a Customer's tier (ADR-023, ADR-061), signed with a key of scope `entitlements`. */
+export async function reportEntitlement(opts: { customer: string; tier: string; status?: "active" | "past_due" | "canceled"; period_end?: string | null; members?: string[]; key: string; baseUrl: string; idempotencyKey?: string; fetch?: FetchLike }): Promise<{ customer: string; tier: string; billing: Record<string, unknown> }> {
+  refuseBrowser("reportEntitlement");
+  const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/entitlement`;
+  const body = { tier: opts.tier, status: opts.status ?? "active", ...(opts.period_end !== undefined ? { period_end: opts.period_end } : {}), ...(opts.members ? { members: opts.members } : {}) };
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path, body, idempotencyKey: opts.idempotencyKey ?? `entitlement-${opts.customer}-${opts.tier}-${Date.now()}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** The Tenant's own tier and use (ADR-064 §11), for its server or its agent. Read-only: paying stays with people. */
+export async function readTenantSubscription(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<TenantSubscriptionView> {
+  refuseBrowser("readTenantSubscription");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/subscription", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** The current revision and hash, and what waits for approval. */
+export async function definitionStatus(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<DefinitionStatus> {
+  refuseBrowser("definitionStatus");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/definitions/status", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+// ------------------------------------------------------------- engine, changesets, feedback (ADR-054 §7, ADR-059 §5)
+
+/** What `GET /tenant/v0/engine` answers. `sdk` (ADR-074 §4): the SDK version the Engine was built with, and the oldest it still serves without a break. */
+export interface EngineInfo {
+  version: string;
+  released_at: string | null;
+  latest_changeset: number;
+  site: { docs: string | null; changesets: string | null };
+  /** Absent on an Engine from before ADR-074. */
+  sdk?: { built_with: string; minimum: string };
+}
+
+/** The Engine's version, its latest changeset, the Engine site's addresses and the SDK versions it serves. Any live key of the Tenant. */
+export async function readEngine(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<EngineInfo> {
+  refuseBrowser("readEngine");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/engine", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Every changeset after `since`, each with this Tenant's ticket and status when it has one. */
+export async function readChangesets(opts: { key: string; baseUrl: string; since?: number; fetch?: FetchLike }): Promise<{ latest: number; changesets: TenantChangeset[] }> {
+  refuseBrowser("readChangesets");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/changesets", query: { since: opts.since }, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Where this Tenant stands with a changeset: `in_progress` while applying it, `resolved` with the SDK version installed, `canceled` with the reason. A note becomes a post. */
+export async function setChangesetStatus(opts: { key: string; baseUrl: string; number: number; status: Exclude<ChangesetStatus, "new">; applied_version?: string; reason?: string; note?: string; fetch?: FetchLike }): Promise<TenantChangeset> {
+  refuseBrowser("setChangesetStatus");
+  const body = { status: opts.status, ...(opts.applied_version ? { applied_version: opts.applied_version } : {}), ...(opts.reason ? { reason: opts.reason } : {}), ...(opts.note ? { note: opts.note } : {}) };
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/changesets/${opts.number}/status`, body, idempotencyKey: `changeset-${opts.number}-${await digest(JSON.stringify(body))}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Report what the Engine cannot do, or does otherwise than documented. The same report sent twice is one ticket: the key is the body's hash. */
+export async function sendFeedback(opts: { key: string; baseUrl: string; report: FeedbackReport; fetch?: FetchLike }): Promise<{ id: string; received_at: string }> {
+  refuseBrowser("sendFeedback");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/feedback", body: opts.report, idempotencyKey: `feedback-${await digest(JSON.stringify(opts.report))}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** The Tenant's feedback tickets that changed after the cursor, with the replies it may read; keep `next` for the next call. */
+export async function readFeedback(opts: { key: string; baseUrl: string; since?: string; fetch?: FetchLike }): Promise<{ items: TicketView[]; next: string | null }> {
+  refuseBrowser("readFeedback");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/feedback", query: { since: opts.since }, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Answer on one of the Tenant's feedback tickets. */
+export async function replyToFeedback(opts: { key: string; baseUrl: string; id: string; body: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("replyToFeedback");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: `/tenant/v0/feedback/${encodeURIComponent(opts.id)}/posts`, body: { body: opts.body }, idempotencyKey: `feedback-reply-${await digest(`${opts.id}|${opts.body}`)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+// ------------------------------------------------------------- the key, tags, tickets, announcements (ADR-074 §2, §8)
+
+/** What `GET /tenant/v0/key` answers: the calling key's own record. Never another key, never key material. */
+export interface TenantKeyRecord {
+  id: string;
+  name: string;
+  /** The Tenant's slug. */
+  tenant: string;
+  scopes: TenantKeyScope[];
+  created_at: string;
+  expires_at: string;
+}
+
+/** The calling key's own record: which Tenant it is for, what it reaches and when it expires. Any live key. */
+export async function readKey(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<TenantKeyRecord> {
+  refuseBrowser("readKey");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/key", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** The Tenant's tags (ADR-057), with a key of scope `tags`. */
+export async function readTags(opts: { key: string; baseUrl: string; fetch?: FetchLike }): Promise<TagView[]> {
+  refuseBrowser("readTags");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tags", fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json?.items ?? [];
+}
+
+/** What `setTag` may set on a tag. A part left out keeps its value; a new tag starts as `staff`, `slate`, with no rules and no effects. */
+export interface TagChange {
+  visibility?: TagVisibility;
+  description?: string;
+  colour?: TagColour;
+  rules?: TagRule[];
+  effects?: TagEffect[];
+}
+
+/** Create the tag or change it, by name, so a server keeps its tags in step. `created` says which happened. */
+export async function setTag(opts: { name: string; change?: TagChange; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TagView & { created: boolean }> {
+  refuseBrowser("setTag");
+  const body = opts.change ?? {};
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/tags/${encodeURIComponent(opts.name)}`, body, idempotencyKey: `tag-${await digest(`${opts.name}|${JSON.stringify(body)}`)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Put a tag on one of the Tenant's Customers. `added` is false when the Customer had it already. */
+export async function tagCustomer(opts: { customer: string; tag: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<{ customer: string; tag: string; added: boolean }> {
+  refuseBrowser("tagCustomer");
+  const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/tags/${encodeURIComponent(opts.tag)}`;
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path, idempotencyKey: `tag-on-${await digest(path)}-${randomId()}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Take a tag off one of the Tenant's Customers. `removed` is false when the Customer did not have it. */
+export async function untagCustomer(opts: { customer: string; tag: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<{ customer: string; tag: string; removed: boolean }> {
+  refuseBrowser("untagCustomer");
+  const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/tags/${encodeURIComponent(opts.tag)}`;
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "DELETE", path, idempotencyKey: `tag-off-${await digest(path)}-${randomId()}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Which tickets `listTickets` answers with. Every part is optional; none lists the open and recent ones. */
+export interface TicketFilter {
+  status?: string;
+  /** A primary type (`issue`, `request`, `feedback`) or a secondary one. */
+  type?: string;
+  archived?: boolean;
+  unread?: boolean;
+  tags?: TagSelector;
+  limit?: number;
+}
+
+/** The tickets the Tenant's servers are a party of (ADR-058 §10), with a key of scope `tickets`. */
+export async function listTickets(opts: { filter?: TicketFilter; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketSummary[]> {
+  refuseBrowser("listTickets");
+  const f = opts.filter ?? {};
+  const query = { status: f.status, type: f.type, archived: f.archived ? "true" : undefined, unread: f.unread ? "true" : undefined, tags: f.tags ? encodeSelector(f.tags) : undefined, limit: f.limit };
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tickets", query, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json?.items ?? [];
+}
+
+/** One ticket with its posts. Reading it marks it read for the Tenant's servers. */
+export async function readTicket(opts: { id: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("readTicket");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** A new ticket: to the platform (`to: "platform"`, `type` one of `TENANT_PLATFORM_TYPES`) or to one of the Tenant's Customers (`to: <cst>`). */
+export interface OpenTicket {
+  to: string;
+  type?: string;
+  subject: string;
+  body: string;
+  priority?: Priority;
+  refs?: string[];
+  /** The Customer's name as the Tenant's own pages show it, kept for the lists. */
+  to_name?: string;
+}
+
+export async function openTicket(opts: { ticket: OpenTicket; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("openTicket");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/tickets", body: opts.ticket, idempotencyKey: `ticket-${await digest(JSON.stringify(opts.ticket))}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** A reply on a ticket. `visibility: "side"` keeps it to the Tenant's own side. */
+export async function postToTicket(opts: { id: string; body: string; visibility?: "all" | "side"; refs?: string[]; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("postToTicket");
+  const body = { body: opts.body, ...(opts.visibility ? { visibility: opts.visibility } : {}), ...(opts.refs ? { refs: opts.refs } : {}) };
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}/posts`, body, idempotencyKey: `ticket-post-${await digest(`${opts.id}|${JSON.stringify(body)}`)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** One change to a ticket or an announcement: its status, its priority or archiving it. */
+export interface TicketChange {
+  status?: AnyStatus;
+  hold_until?: string | null;
+  priority?: Priority;
+  archived?: boolean;
+  audience?: TagSelector | null;
+  announcement?: AnnouncementOptions;
+}
+
+export async function updateTicket(opts: { id: string; change: TicketChange; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("updateTicket");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PATCH", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}`, body: opts.change, idempotencyKey: `ticket-change-${await digest(`${opts.id}|${JSON.stringify(opts.change)}`)}-${randomId()}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** An announcement's own settings (ADR-058 §8): texts per language, when it shows and how. */
+export interface AnnouncementOptions {
+  languages?: Record<string, { subject: string; body: string }>;
+  default_language?: string;
+  publish_at?: string | null;
+  expires_at?: string | null;
+  pinned?: boolean;
+  severity?: "info" | "warning";
+  replies?: boolean;
+}
+
+/** The Tenant's announcements to its Customers, with every status, and the platform's announcements to the Tenant, read only. */
+export async function listAnnouncements(opts: { lang?: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<{ items: TicketSummary[]; platform: AnnouncementItem[] }> {
+  refuseBrowser("listAnnouncements");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/announcements", query: { lang: opts.lang }, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return { items: r.json?.items ?? [], platform: r.json?.platform ?? [] };
+}
+
+export async function readAnnouncement(opts: { id: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("readAnnouncement");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** A new announcement to the Tenant's Customers: its text, its audience of tags (everyone without one) and its own settings. */
+export interface NewAnnouncement {
+  subject: string;
+  body?: string;
+  type?: string;
+  priority?: Priority;
+  audience?: TagSelector;
+  announcement?: AnnouncementOptions;
+}
+
+/** Start an announcement to the Tenant's Customers, to everyone or to an audience of tags. It starts as a draft; `publishAnnouncement` sends it, or `announcement.publish_at` schedules it. */
+export async function draftAnnouncement(opts: { announcement: NewAnnouncement; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("draftAnnouncement");
+  const body = { ...opts.announcement, to: "customers" };
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/announcements", body, idempotencyKey: `announcement-${await digest(JSON.stringify(body))}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Publish a draft announcement now: its status becomes `published`. */
+export async function publishAnnouncement(opts: { id: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  return updateAnnouncement({ ...opts, change: { status: "published" } });
+}
+
+export async function updateAnnouncement(opts: { id: string; change: TicketChange; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  refuseBrowser("updateAnnouncement");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PATCH", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, body: opts.change, idempotencyKey: `announcement-change-${await digest(`${opts.id}|${JSON.stringify(opts.change)}`)}-${randomId()}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+  return r.json;
+}
+
+/** Take a published announcement down: its status becomes `withdrawn`. */
+export async function withdrawAnnouncement(opts: { id: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<TicketView> {
+  return updateAnnouncement({ ...opts, change: { status: "withdrawn" } });
+}
+
+/** Delete an announcement that is still a draft; a published one is withdrawn instead. */
+export async function deleteAnnouncementDraft(opts: { id: string; key: string; baseUrl: string; fetch?: FetchLike }): Promise<void> {
+  refuseBrowser("deleteAnnouncementDraft");
+  const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "DELETE", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, idempotencyKey: `announcement-delete-${await digest(opts.id)}`, fetch: opts.fetch });
+  if (r.status >= 400) throw fail(r);
+}
+
+async function digest(text: string): Promise<string> {
+  const h = await subtle().digest("SHA-256", new TextEncoder().encode(text));
+  return Array.from(new Uint8Array(h).slice(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ------------------------------------------------------------- helpers
+
+function subtle(): typeof globalThis.crypto.subtle {
+  const s = globalThis.crypto?.subtle;
+  if (!s) throw new Error("Web Crypto is not available in this runtime");
+  return s;
+}
+
+function randomId(): string {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  return b64url(b);
+}
+
+function hex(buf: ArrayBuffer): string {
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function b64url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlText(text: string): string {
+  return b64url(new TextEncoder().encode(text));
+}
+
+export function fromB64url(value: string): Uint8Array {
+  const s = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((value.length + 3) % 4));
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}