@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/tickets.ts

@@ -0,0 +1,195 @@
+/**
+ * Tickets and announcements (ADR-058). A Ticket (`tkt`) is a conversation
+ * with a status between a Customer and its Tenant, a Tenant and the platform,
+ * or a User and the platform on the account page. An announcement is a ticket
+ * of its own primary type: one-to-many, to an audience of tags, with a
+ * lifecycle of its own. Pure and dependency-free: the Operations API decides,
+ * every surface reads the same words.
+ */
+
+import type { TagSelector } from "./tags.js";
+
+export const PRIMARY_TYPES = ["issue", "request", "feedback", "announcement"] as const;
+
+export type PrimaryType = (typeof PRIMARY_TYPES)[number];
+
+/** Who opened it and who answers (§2). Announcements go one way, to an audience. */
+export const DIRECTIONS = ["customer_tenant", "tenant_customer", "tenant_platform", "platform_tenant", "user_platform", "platform_user", "tenant_customers", "platform_tenants", "platform_users"] as const;
+
+export type Direction = (typeof DIRECTIONS)[number];
+
+export const TICKET_STATUSES = ["new", "acknowledged", "in_progress", "waiting", "on_hold", "resolved", "canceled"] as const;
+
+export type TicketStatus = (typeof TICKET_STATUSES)[number];
+
+export const ANNOUNCEMENT_STATUSES = ["draft", "scheduled", "published", "expired", "withdrawn"] as const;
+
+export type AnnouncementStatus = (typeof ANNOUNCEMENT_STATUSES)[number];
+
+export type AnyStatus = TicketStatus | AnnouncementStatus;
+
+export const PRIORITIES = ["low", "normal", "high", "urgent"] as const;
+
+export type Priority = (typeof PRIORITIES)[number];
+
+export type Side = "requester" | "handling";
+
+/** The moves a ticket's status makes (§4, the state diagram). A requester's reply to `waiting` and a reopen are moves too. */
+const MOVES: Record<TicketStatus, readonly TicketStatus[]> = {
+  new: ["acknowledged", "in_progress", "canceled"],
+  acknowledged: ["in_progress", "resolved", "canceled"],
+  in_progress: ["waiting", "on_hold", "resolved", "canceled"],
+  waiting: ["in_progress", "canceled"],
+  on_hold: ["in_progress", "canceled"],
+  resolved: ["in_progress"],
+  canceled: [],
+};
+
+/** Feedback keeps a subset (§4): it is seen, answered and closed, never worked on. */
+const FEEDBACK_STATUSES: readonly TicketStatus[] = ["new", "acknowledged", "resolved", "canceled"];
+
+export function statusesOf(primary: PrimaryType): readonly AnyStatus[] {
+  if (primary === "announcement") return ANNOUNCEMENT_STATUSES;
+  return primary === "feedback" ? FEEDBACK_STATUSES : TICKET_STATUSES;
+}
+
+/** Where a ticket may go from here, for the handling side; the requester may only cancel, resolve or reopen its own. */
+export function nextStatuses(primary: PrimaryType, from: TicketStatus, who: Side): TicketStatus[] {
+  const allowed = statusesOf(primary) as readonly TicketStatus[];
+  const moves = MOVES[from].filter((s) => allowed.includes(s));
+  if (who === "handling") return moves.filter((s) => s !== "in_progress" || from !== "resolved");
+  return moves.filter((s) => s === "canceled" || s === "resolved" || (from === "resolved" && s === "in_progress"));
+}
+
+/** A resolved ticket reopens within this many days; later, or canceled, a new ticket links the old one (§4). */
+export const REOPEN_DAYS = 14;
+
+/** The Operator archives a closed ticket this many days after it closed (§4). */
+export const ARCHIVE_DAYS = 30;
+
+/** The words every surface shows for a status and a priority. */
+export const STATUS_LABELS: Record<AnyStatus, string> = {
+  new: "New",
+  acknowledged: "Seen",
+  in_progress: "In progress",
+  waiting: "Waiting for you",
+  on_hold: "On hold",
+  resolved: "Resolved",
+  canceled: "Canceled",
+  draft: "Draft",
+  scheduled: "Scheduled",
+  published: "Published",
+  expired: "Expired",
+  withdrawn: "Withdrawn",
+};
+
+export const PRIORITY_LABELS: Record<Priority, string> = { low: "Low", normal: "Normal", high: "High", urgent: "Urgent" };
+
+/** A Tenant's own type of ticket for its Customers (§3): a permanent key, the name a Customer reads, its primary type, the role that answers. */
+export interface TenantTicketType {
+  key: string;
+  name: string;
+  primary: "issue" | "request" | "feedback";
+  handled_by: string;
+}
+
+/** Open: still work for someone. Closed tickets count toward nobody's open limit. */
+export function isOpenStatus(s: AnyStatus): boolean {
+  return s !== "resolved" && s !== "canceled" && s !== "draft" && s !== "expired" && s !== "withdrawn";
+}
+
+export const TENANT_PLATFORM_TYPES = ["engine_defect", "engine_limitation", "engine_question", "changeset", "billing", "onboarding", "security", "notice", "other"] as const;
+
+/** A party (§5): a person, a role binding, the Tenant's servers. */
+export interface PartyView {
+  /** `customer:<cst>`, `user:<usr>`, `role:<group>` or `tenant:<tnt>`. */
+  ref: string;
+  kind: "person" | "role" | "tenant";
+  side: Side;
+  access: "ro" | "rw";
+  place: "requester" | "assignee" | "watcher";
+  /** How the reader sees it: a name for someone of their own side, "<Tenant> · Support" or "Asturiu · Support" for the other (§7). */
+  label: string;
+}
+
+/** A post as a reader sees it (§6, §7). */
+export interface PostView {
+  id: string;
+  at: string;
+  side: Side;
+  visibility: "all" | "side";
+  author: { label: string; mine: boolean };
+  body: string;
+  refs: string[];
+}
+
+export interface TicketLink {
+  ticket: string;
+  relation: "escalated_from" | "escalated_to" | "duplicate_of" | "relates_to";
+}
+
+/** A ticket in a list. */
+export interface TicketSummary {
+  arid: string;
+  scope: "platform" | "tenant";
+  tenant?: string;
+  direction: Direction;
+  primary: PrimaryType;
+  secondary: string | null;
+  /** The type's name, as the reader reads it. */
+  type_label: string;
+  subject: string;
+  status: AnyStatus;
+  priority: Priority;
+  archived: boolean;
+  created_at: string;
+  updated_at: string;
+  /** Which side the reader is on, or `audience` when they read it as one of many. */
+  side: Side | "audience";
+  unread: boolean;
+  /** Who it is with, from the reader's side: "<Tenant> · Support", a Customer's name, "Asturiu". */
+  with_label: string;
+}
+
+/** One ticket, whole, as a reader may see it. */
+export interface TicketView extends TicketSummary {
+  parties: PartyView[];
+  posts: PostView[];
+  links: TicketLink[];
+  refs: string[];
+  audience: TagSelector | null;
+  hold_until: string | null;
+  closed_at: string | null;
+  /** What the reader may do now. */
+  can: { post: boolean; note: boolean; triage: boolean; statuses: TicketStatus[]; reopen: boolean };
+  /** Announcements: languages and the rest; absent for a ticket. */
+  announcement?: AnnouncementFields;
+  /** Changesets and feedback (ADR-059): what the ticket is about beyond its text. */
+  changeset?: { number: number; title: string; date: string; deadline: string | null; url: string | null; applied_version: string | null; reason: string | null };
+  feedback?: { area: string | null };
+}
+
+export interface AnnouncementFields {
+  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;
+}
+
+/** An announcement in a reader's inbox, in the reader's language or the default. */
+export interface AnnouncementItem {
+  arid: string;
+  subject: string;
+  body: string;
+  published_at: string;
+  expires_at: string | null;
+  pinned: boolean;
+  severity: "info" | "warning";
+  replies: boolean;
+  read: boolean;
+  /** Who it is from: the Tenant's name, or the platform's. */
+  from: string;
+}

package/src/tiers.ts

@@ -0,0 +1,397 @@
+/**
+ * Tiers (ADR-061). A tier is a named set of features. Engine features come
+ * from the closed catalogue below and the Engine enforces them; Tenant
+ * features are the Tenant's own, and the Engine stores and returns them
+ * without reading them. Dependency-free, so the Admin UI, the Customer Portal
+ * and a Tenant's application draw from the same list the Interface API
+ * enforces.
+ */
+
+import { PASS_LIMITS } from "./passes.js";
+
+export const TIER_LIMITS = {
+  tiers: 32,
+  label: 120,
+  /** Tenant features on one tier. */
+  tenantFeatures: 64,
+  tenantFeatureString: 200,
+  graceDays: 365,
+  /** A file removal gives a person time to act (§6). */
+  storageGraceDaysMin: 30,
+} as const;
+
+export const TIER_KEY_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export const TENANT_FEATURE_KEY_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** `false` or `0`: off. `true`: on, no limit. A positive number: on, up to that number (§2). */
+export type FeatureValue = boolean | number;
+
+export type EngineFeatureKind = "toggle" | "stock" | "monthly" | "window" | "size";
+
+export interface EngineFeature {
+  key: string;
+  kind: EngineFeatureKind;
+  /** What a number counts; `null` for a toggle. */
+  unit: "count" | "bytes" | "days" | "people" | null;
+  /** What a tier that does not name it gets. These keep the behaviour from before tiers. */
+  default: FeatureValue;
+  /** What a limit is counted over. */
+  scope: "vault" | "customer" | "wallet" | "upload" | null;
+  /** On a group plan the number is a total for the group (ADR-063 §6). */
+  pooled: boolean;
+  /** The highest number a tier may set; absent: no ceiling here. */
+  max?: number;
+  label: string;
+}
+
+/** ADR-061 §4. A feature joins this list when the Engine can enforce it. */
+export const ENGINE_FEATURES: readonly EngineFeature[] = [
+  { key: "wallets", kind: "stock", unit: "count", default: true, scope: "vault", pooled: true, label: "Wallets" },
+  { key: "entries", kind: "stock", unit: "count", default: true, scope: "vault", pooled: true, label: "Entries" },
+  { key: "storage", kind: "stock", unit: "bytes", default: true, scope: "vault", pooled: true, label: "Storage" },
+  { key: "file_size", kind: "size", unit: "bytes", default: true, scope: "upload", pooled: false, label: "Largest file" },
+  { key: "sharing", kind: "stock", unit: "people", default: true, scope: "vault", pooled: false, label: "People shared with" },
+  { key: "conditional_sharing", kind: "toggle", unit: null, default: true, scope: null, pooled: false, label: "Conditional sharing" },
+  { key: "groups", kind: "stock", unit: "count", default: true, scope: "vault", pooled: true, label: "Groups" },
+  { key: "contacts", kind: "stock", unit: "count", default: true, scope: "customer", pooled: true, label: "Contacts" },
+  { key: "messages", kind: "monthly", unit: "count", default: true, scope: "customer", pooled: true, label: "Messages a month" },
+  { key: "transfers", kind: "monthly", unit: "count", default: true, scope: "customer", pooled: true, label: "Transfers a month" },
+  { key: "passes", kind: "stock", unit: "count", default: 0, scope: "vault", pooled: false, max: PASS_LIMITS.passesPerLevelMax, label: "Live guest passes" },
+  { key: "triggers", kind: "stock", unit: "count", default: true, scope: "vault", pooled: true, label: "Triggers" },
+  { key: "recovery", kind: "toggle", unit: null, default: true, scope: null, pooled: false, label: "Vault recovery" },
+  { key: "tickets", kind: "toggle", unit: null, default: true, scope: null, pooled: false, label: "Support tickets" },
+  { key: "sms", kind: "toggle", unit: null, default: true, scope: null, pooled: false, label: "SMS" },
+  { key: "trash_days", kind: "window", unit: "days", default: true, scope: null, pooled: false, label: "Days to restore" },
+  { key: "portfolios", kind: "stock", unit: "count", default: true, scope: "vault", pooled: true, label: "Portfolios" },
+  { key: "rename", kind: "toggle", unit: null, default: false, scope: null, pooled: false, label: "Rename fields" },
+  { key: "arrange", kind: "toggle", unit: null, default: false, scope: null, pooled: false, label: "Arrange fields" },
+  { key: "custom_fields", kind: "stock", unit: "count", default: 0, scope: "wallet", pooled: false, max: 200, label: "Custom fields per Wallet" },
+  { key: "secret_custom_fields", kind: "toggle", unit: null, default: false, scope: null, pooled: false, label: "Secret custom fields" },
+  { key: "searchable_custom_fields", kind: "stock", unit: "count", default: 0, scope: "wallet", pooled: false, max: 50, label: "Searchable custom fields per Wallet" },
+];
+
+const CATALOGUE = new Map(ENGINE_FEATURES.map((f) => [f.key, f]));
+
+export function engineFeature(key: string): EngineFeature | undefined {
+  return CATALOGUE.get(key);
+}
+
+export type TenantFeatureValue = boolean | number | string;
+
+export interface TierDefinition {
+  label?: string;
+  /** Wallet type keys (ADR-029) or `"*"`. A key not in the Definition set is skipped when read. */
+  wallet_types: string[];
+  engine_features?: Record<string, FeatureValue>;
+  tenant_features?: Record<string, TenantFeatureValue>;
+}
+
+export type Tiers = Record<string, TierDefinition>;
+
+export const TRIGGER_RULE_MODES = ["freeze", "pause"] as const;
+export type TriggerRuleMode = (typeof TRIGGER_RULE_MODES)[number];
+export const STORAGE_RULE_MODES = ["keep", "remove"] as const;
+export type StorageRuleMode = (typeof STORAGE_RULE_MODES)[number];
+
+/** What happens to what a Customer has above a lower tier (ADR-061 §6). */
+export interface TierRules {
+  triggers: { mode: TriggerRuleMode; grace_days: number };
+  storage: { mode: StorageRuleMode; grace_days: number };
+  /** When a Tenant last lowered a limit these rules act on; set by the Operations API. */
+  changed_at?: string;
+}
+
+export interface TenantTierSet {
+  tiers: Tiers;
+  default_tier: string;
+  tier_rules: TierRules;
+}
+
+export function defaultTierRules(): TierRules {
+  return { triggers: { mode: "freeze", grace_days: 0 }, storage: { mode: "keep", grace_days: 90 } };
+}
+
+/** What a Tenant record with no tiers reads as (§3): one tier that creates from every Wallet type. */
+export function defaultTierSet(): TenantTierSet {
+  return { tiers: { free: { wallet_types: ["*"] } }, default_tier: "free", tier_rules: defaultTierRules() };
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** The fields tiers replace, as records written before ADR-061 keep them. */
+export interface LegacyTierFields {
+  scoping?: unknown;
+  customization?: unknown;
+  passes?: unknown;
+  billing?: unknown;
+  definitions?: unknown;
+}
+
+/** One tier's overlay limits from `Tenant.customization` (ADR-028), as Engine features. */
+function featuresFromCustomization(raw: unknown): Record<string, FeatureValue> {
+  if (!isObject(raw)) return {};
+  const out: Record<string, FeatureValue> = {};
+  if (raw.rename === true) out.rename = true;
+  if (raw.arrange === true) out.arrange = true;
+  if (typeof raw.extra_fields === "number" && raw.extra_fields > 0) out.custom_fields = raw.extra_fields;
+  if (raw.secret_fields === true) out.secret_custom_fields = true;
+  if (typeof raw.searchable_fields === "number" && raw.searchable_fields > 0) out.searchable_custom_fields = raw.searchable_fields;
+  return out;
+}
+
+/**
+ * Tiers from the four fields they replace (§11). Each default is the one the
+ * old field had, so nothing changes for a Customer. ARIDs in `scoping` become
+ * Wallet type keys through the Tenant's Definition map; one the map does not
+ * know stays an ARID, which `walletTypeArids` still honours.
+ */
+export function tiersFromLegacy(raw: LegacyTierFields): TenantTierSet {
+  const scoping = isObject(raw.scoping) ? raw.scoping : {};
+  const customization = isObject(raw.customization) ? raw.customization : {};
+  const passes = isObject(raw.passes) && isObject(raw.passes.levels) ? raw.passes.levels : {};
+  const map = isObject(raw.definitions) && isObject(raw.definitions.map) ? (raw.definitions.map as Record<string, string>) : {};
+  const keyOf = new Map(Object.entries(map).filter(([k]) => k.startsWith("wallet:")).map(([k, arid]) => [arid, k.slice("wallet:".length)]));
+  const levels = [...new Set([...Object.keys(scoping), ...Object.keys(customization), ...Object.keys(passes)])].filter((l) => TIER_KEY_PATTERN.test(l));
+  const free = isObject(raw.billing) && typeof raw.billing.free_level === "string" ? raw.billing.free_level : "free";
+  if (!levels.length) return { ...defaultTierSet(), default_tier: "free" };
+  const tiers: Tiers = {};
+  for (const level of levels) {
+    const list = Array.isArray(scoping[level]) ? (scoping[level] as unknown[]).filter((a): a is string => typeof a === "string") : [];
+    const engine_features = featuresFromCustomization(customization[level]);
+    const allowed = isObject(passes[level]) ? passes[level].passes : undefined;
+    if (typeof allowed === "number" && allowed > 0) engine_features.passes = allowed;
+    tiers[level] = { wallet_types: list.map((a) => (a === "*" ? a : (keyOf.get(a) ?? a))), ...(Object.keys(engine_features).length ? { engine_features } : {}) };
+  }
+  // The old fall-back read the key `free`, then nothing: a level that was named nowhere stays empty.
+  const default_tier = free in tiers ? free : "free" in tiers ? "free" : free;
+  if (!(default_tier in tiers)) tiers[default_tier] = { wallet_types: [] };
+  return { tiers, default_tier, tier_rules: defaultTierRules() };
+}
+
+function readRules(raw: unknown): TierRules {
+  const out = defaultTierRules();
+  if (!isObject(raw)) return out;
+  const t = raw.triggers;
+  if (isObject(t)) {
+    if ((TRIGGER_RULE_MODES as readonly unknown[]).includes(t.mode)) out.triggers.mode = t.mode as TriggerRuleMode;
+    if (Number.isInteger(t.grace_days) && (t.grace_days as number) >= 0 && (t.grace_days as number) <= TIER_LIMITS.graceDays) out.triggers.grace_days = t.grace_days as number;
+  }
+  const s = raw.storage;
+  if (isObject(s)) {
+    if ((STORAGE_RULE_MODES as readonly unknown[]).includes(s.mode)) out.storage.mode = s.mode as StorageRuleMode;
+    if (Number.isInteger(s.grace_days) && (s.grace_days as number) >= TIER_LIMITS.storageGraceDaysMin && (s.grace_days as number) <= TIER_LIMITS.graceDays) out.storage.grace_days = s.grace_days as number;
+  }
+  if (typeof raw.changed_at === "string") out.changed_at = raw.changed_at;
+  return out;
+}
+
+/** A stored `tiers` block, read leniently: what cannot be read is left out, never a broken page. */
+function readTiers(raw: unknown): Tiers {
+  const out: Tiers = {};
+  if (!isObject(raw)) return out;
+  for (const [key, t] of Object.entries(raw)) {
+    if (!TIER_KEY_PATTERN.test(key) || !isObject(t)) continue;
+    const tier: TierDefinition = { wallet_types: Array.isArray(t.wallet_types) ? t.wallet_types.filter((w): w is string => typeof w === "string") : [] };
+    if (typeof t.label === "string") tier.label = t.label;
+    if (isObject(t.engine_features)) {
+      const features: Record<string, FeatureValue> = {};
+      for (const [k, v] of Object.entries(t.engine_features)) if (CATALOGUE.has(k) && (typeof v === "boolean" || typeof v === "number")) features[k] = v;
+      if (Object.keys(features).length) tier.engine_features = features;
+    }
+    if (isObject(t.tenant_features)) tier.tenant_features = t.tenant_features as Record<string, TenantFeatureValue>;
+    out[key] = tier;
+  }
+  return out;
+}
+
+/** A Tenant's tiers, from `tiers` when the record has them, otherwise from the fields they replace. */
+export function tierSetOf(raw: LegacyTierFields & { tiers?: unknown; default_tier?: unknown; tier_rules?: unknown }): TenantTierSet {
+  const tiers = readTiers(raw.tiers);
+  const keys = Object.keys(tiers);
+  if (!keys.length) return tiersFromLegacy(raw);
+  const stored = typeof raw.default_tier === "string" ? raw.default_tier : "";
+  return { tiers, default_tier: stored in tiers ? stored : (keys[0] as string), tier_rules: readRules(raw.tier_rules) };
+}
+
+/** The tier in force: the stored key, or `default_tier` when there is none or it no longer exists (§3). */
+export function tierKeyOf(set: TenantTierSet, stored: string | null | undefined): string {
+  return stored && stored in set.tiers ? stored : set.default_tier;
+}
+
+export function tierOf(set: TenantTierSet, stored: string | null | undefined): TierDefinition {
+  return set.tiers[tierKeyOf(set, stored)] ?? { wallet_types: [] };
+}
+
+/** A feature's value on a tier: as written, or the catalogue's default. */
+export function featureValue(tier: TierDefinition, key: string): FeatureValue {
+  const stored = tier.engine_features?.[key];
+  if (stored !== undefined) return stored;
+  return CATALOGUE.get(key)?.default ?? false;
+}
+
+/** `null`: no limit. `0`: off. Otherwise the number (§2). */
+export function featureLimit(value: FeatureValue): number | null {
+  if (value === true) return null;
+  if (value === false) return 0;
+  return value;
+}
+
+/** Whether a Customer may use a feature at all. */
+export function featureIsOn(value: FeatureValue): boolean {
+  return value === true || (typeof value === "number" && value > 0);
+}
+
+/** The Wallet type ARIDs a tier may create from. `map` is the Tenant's Definition map; a key not in it is skipped (§3). */
+export function walletTypeArids(tier: TierDefinition, map: Record<string, string>, all: readonly string[]): Set<string> {
+  if (tier.wallet_types.includes("*")) return new Set(all);
+  const out = new Set<string>();
+  for (const w of tier.wallet_types) {
+    const arid = map[`wallet:${w}`] ?? (all.includes(w) ? w : undefined);
+    if (arid) out.add(arid);
+  }
+  return out;
+}
+
+/** Whether any tier switches a Wallet overlay feature on: the Tenant has customisation at all (ADR-028). */
+export function overlaysOn(set: TenantTierSet): boolean {
+  return Object.values(set.tiers).some((t) => ["rename", "arrange", "custom_fields", "secret_custom_fields", "searchable_custom_fields"].some((k) => featureIsOn(featureValue(t, k))));
+}
+
+/** What a tier may add to a Wallet overlay, in the shape the overlay code checks against. */
+export function overlayLimitsOf(tier: TierDefinition): { rename: boolean; arrange: boolean; extra_fields: number; secret_fields: boolean; searchable_fields: number } {
+  const count = (key: string) => {
+    const limit = featureLimit(featureValue(tier, key));
+    return limit === null ? (CATALOGUE.get(key)?.max ?? 0) : limit;
+  };
+  return { rename: featureIsOn(featureValue(tier, "rename")), arrange: featureIsOn(featureValue(tier, "arrange")), extra_fields: count("custom_fields"), secret_fields: featureIsOn(featureValue(tier, "secret_custom_fields")), searchable_fields: count("searchable_custom_fields") };
+}
+
+export interface TierProblem {
+  path: (string | number)[];
+  message: string;
+}
+
+/** Strict checks on a block being written (§3). One entry per problem, with its path. */
+export function tierProblems(raw: { tiers?: unknown; default_tier?: unknown; tier_rules?: unknown }): TierProblem[] {
+  const out: TierProblem[] = [];
+  if (!isObject(raw.tiers)) return [{ path: ["tiers"], message: "tiers is an object of tier keys" }];
+  const keys = Object.keys(raw.tiers);
+  if (!keys.length) out.push({ path: ["tiers"], message: "a Tenant needs at least one tier" });
+  if (keys.length > TIER_LIMITS.tiers) out.push({ path: ["tiers"], message: `at most ${TIER_LIMITS.tiers} tiers` });
+  if (typeof raw.default_tier !== "string" || !keys.includes(raw.default_tier)) out.push({ path: ["default_tier"], message: "default_tier must be a tier key" });
+  for (const key of keys) {
+    const at = (...rest: (string | number)[]) => ["tiers", key, ...rest];
+    if (!TIER_KEY_PATTERN.test(key)) out.push({ path: at(), message: "a tier key is lowercase letters, digits, - and _, starting with a letter, at most 64" });
+    const t = raw.tiers[key];
+    if (!isObject(t)) {
+      out.push({ path: at(), message: "a tier is an object" });
+      continue;
+    }
+    for (const k of Object.keys(t)) if (!["label", "wallet_types", "engine_features", "tenant_features"].includes(k)) out.push({ path: at(k), message: "unknown key" });
+    if (t.label !== undefined && (typeof t.label !== "string" || t.label.length > TIER_LIMITS.label)) out.push({ path: at("label"), message: `a label is text of at most ${TIER_LIMITS.label} characters` });
+    if (!Array.isArray(t.wallet_types) || t.wallet_types.some((w) => typeof w !== "string")) out.push({ path: at("wallet_types"), message: "wallet_types is a list of Wallet type keys, or \"*\"" });
+    if (t.engine_features !== undefined) {
+      if (!isObject(t.engine_features)) out.push({ path: at("engine_features"), message: "engine_features is an object" });
+      else
+        for (const [k, v] of Object.entries(t.engine_features)) {
+          const f = CATALOGUE.get(k);
+          if (!f) {
+            out.push({ path: at("engine_features", k), message: "not an Engine feature" });
+            continue;
+          }
+          if (f.kind === "toggle") {
+            if (typeof v !== "boolean") out.push({ path: at("engine_features", k), message: "this feature is on or off: true or false" });
+            continue;
+          }
+          const okNumber = typeof v === "number" && Number.isInteger(v) && v >= 0 && (f.max === undefined || v <= f.max);
+          if (typeof v !== "boolean" && !okNumber) out.push({ path: at("engine_features", k), message: f.max === undefined ? "true, false or a whole number" : `true, false or a whole number up to ${f.max}` });
+        }
+    }
+    if (t.tenant_features !== undefined) {
+      if (!isObject(t.tenant_features)) out.push({ path: at("tenant_features"), message: "tenant_features is an object" });
+      else {
+        const entries = Object.entries(t.tenant_features);
+        if (entries.length > TIER_LIMITS.tenantFeatures) out.push({ path: at("tenant_features"), message: `at most ${TIER_LIMITS.tenantFeatures} keys` });
+        for (const [k, v] of entries) {
+          if (!TENANT_FEATURE_KEY_PATTERN.test(k)) out.push({ path: at("tenant_features", k), message: "a key is lowercase letters, digits and _, starting with a letter, at most 64" });
+          const okValue = typeof v === "boolean" || (typeof v === "number" && Number.isInteger(v)) || (typeof v === "string" && v.length <= TIER_LIMITS.tenantFeatureString);
+          if (!okValue) out.push({ path: at("tenant_features", k), message: `a boolean, a whole number, or text of at most ${TIER_LIMITS.tenantFeatureString} characters` });
+        }
+      }
+    }
+  }
+  const rules = raw.tier_rules;
+  if (rules !== undefined) {
+    if (!isObject(rules)) out.push({ path: ["tier_rules"], message: "tier_rules is an object" });
+    else {
+      for (const k of Object.keys(rules)) if (!["triggers", "storage", "changed_at"].includes(k)) out.push({ path: ["tier_rules", k], message: "unknown key" });
+      const t = rules.triggers;
+      if (t !== undefined) {
+        if (!isObject(t) || !(TRIGGER_RULE_MODES as readonly unknown[]).includes(t.mode)) out.push({ path: ["tier_rules", "triggers", "mode"], message: `one of ${TRIGGER_RULE_MODES.join(", ")}` });
+        else if (t.grace_days !== undefined && !(Number.isInteger(t.grace_days) && (t.grace_days as number) >= 0 && (t.grace_days as number) <= TIER_LIMITS.graceDays)) out.push({ path: ["tier_rules", "triggers", "grace_days"], message: `0 to ${TIER_LIMITS.graceDays} days` });
+      }
+      const s = rules.storage;
+      if (s !== undefined) {
+        if (!isObject(s) || !(STORAGE_RULE_MODES as readonly unknown[]).includes(s.mode)) out.push({ path: ["tier_rules", "storage", "mode"], message: `one of ${STORAGE_RULE_MODES.join(", ")}` });
+        else if (s.grace_days !== undefined && !(Number.isInteger(s.grace_days) && (s.grace_days as number) >= TIER_LIMITS.storageGraceDaysMin && (s.grace_days as number) <= TIER_LIMITS.graceDays)) out.push({ path: ["tier_rules", "storage", "grace_days"], message: `${TIER_LIMITS.storageGraceDaysMin} to ${TIER_LIMITS.graceDays} days` });
+      }
+    }
+  }
+  return out;
+}
+
+/** A value as a number to compare: no limit counts as more than any number. */
+const rank = (v: FeatureValue) => (v === true ? Number.POSITIVE_INFINITY : v === false ? 0 : v);
+
+/** Features whose value falls between two tier sets, on tiers that exist in both: what the Admin UI warns about (§12), and what starts a grace period (§6). */
+export function loweredFeatures(before: Tiers, after: Tiers): { tier: string; feature: string; from: FeatureValue; to: FeatureValue }[] {
+  const out: { tier: string; feature: string; from: FeatureValue; to: FeatureValue }[] = [];
+  for (const [key, was] of Object.entries(before)) {
+    const now = after[key];
+    if (!now) continue;
+    for (const f of ENGINE_FEATURES) {
+      const from = featureValue(was, f.key);
+      const to = featureValue(now, f.key);
+      if (rank(to) < rank(from)) out.push({ tier: key, feature: f.key, from, to });
+    }
+  }
+  return out;
+}
+
+/** One Engine feature as a Customer has it (§9). */
+export interface EntitledFeature {
+  value: FeatureValue;
+  /** Present for stock and monthly limits. On a group plan, the group's total. */
+  used?: number;
+  /** On a group plan, the caller's share. */
+  own?: number;
+}
+
+/** `GET /v0/customer/entitlements`, and the Tenant API's read of one Customer (§9). */
+export interface CustomerEntitlements {
+  tier: string;
+  label: string;
+  /** Wallet type keys or `"*"`. */
+  wallet_types: string[];
+  engine_features: Record<string, EntitledFeature>;
+  tenant_features: Record<string, TenantFeatureValue>;
+  /** While files are due to be removed (§6). */
+  storage_review?: { at: string; over_bytes: number };
+}
+
+export function entitlementsOf(set: TenantTierSet, stored: string | null | undefined, used: Record<string, { used?: number; own?: number }> = {}): CustomerEntitlements {
+  const key = tierKeyOf(set, stored);
+  const tier = tierOf(set, key);
+  const engine_features: Record<string, EntitledFeature> = {};
+  for (const f of ENGINE_FEATURES) engine_features[f.key] = { value: featureValue(tier, f.key), ...(used[f.key] ?? {}) };
+  return { tier: key, label: tier.label ?? key, wallet_types: tier.wallet_types, engine_features, tenant_features: tier.tenant_features ?? {} };
+}
+
+/** A feature read for showing: whether it is on, its limit, what is used and what is left. */
+export function featureOf(entitlements: CustomerEntitlements, key: string): { on: boolean; limit: number | null; used: number | null; left: number | null } {
+  const f = entitlements.engine_features[key];
+  if (!f) return { on: false, limit: 0, used: null, left: null };
+  const limit = featureLimit(f.value);
+  const used = f.used ?? null;
+  return { on: featureIsOn(f.value), limit, used, left: limit === null || used === null ? null : Math.max(0, limit - used) };
+}