@startsimpli/ui 0.4.141 → 0.4.143

package/src/components/history/restore.ts

@@ -0,0 +1,295 @@
+/**
+ * Restore, the pure half (bd startsim-zkyk4; server bd startsim-ti1yv).
+ *
+ * `POST /entities/<id>/revisions/<N>/restore/` puts one field — or the whole
+ * record — back to how it stood AFTER revision N, as an ordinary new write. This
+ * module answers the two questions the panel has to answer before and after that
+ * call, without React and without a backend:
+ *
+ * 1. WHAT WOULD CHANGE ({@link restorePreview}). The confirm dialog shows this,
+ *    and it must agree with the server EXACTLY or the dialog promises one change
+ *    and the server makes another. The server's rule (`_state_at` in
+ *    tenant-starter/apps/api/revision_history.py): start from the record as it is
+ *    now and undo, newest first, every edit after N — a key whose `before` is
+ *    absent was created after N and is removed. That is a fold over exactly the
+ *    rows NEWER than N, and the panel already holds them: the trail is read
+ *    newest first, so any row the reader can see has every newer row loaded
+ *    above it. Values come from the trail alone — `after` of the newest row that
+ *    touched a field is its current value, because the chain is gapless.
+ *
+ * 2. WHAT THE SERVER SAID ({@link parseRestoreOutcome}) — resolved or thrown,
+ *    snake or camel, with a sentence for every refusal the route can give.
+ */
+import { parseStaleSaveRefusal, toVersion } from './conditional-write';
+import { normalizeRevision, type FoldedFieldChange, type NormalizedRevision } from './revision-history';
+import type { EntityRevision } from './types';
+
+/** One side of a previewed value. `has: false` means the key is ABSENT — a
+ *  different fact from a stored `null`. */
+export interface RestoreSide {
+  has: boolean;
+  value?: unknown;
+}
+
+export interface RestoreFieldChange {
+  field: string;
+  /** What the field holds now. */
+  current: RestoreSide;
+  /** What the restore would put back. `has: false` = the key is removed. */
+  restored: RestoreSide;
+}
+
+export interface RestorePreview {
+  /** The version being restored to. */
+  target: number;
+  /** The newest version in the trail the preview was computed over. */
+  newest: number;
+  /** Fields that would move, in a stable order. Withheld and unknowable fields
+   *  are NOT here — see {@link withheld} and {@link unknowable}. */
+  changes: RestoreFieldChange[];
+  /** The name column, on a whole-record restore that would move it. */
+  name?: Omit<RestoreFieldChange, 'field'>;
+  /** Nothing would change. The server answers a no-op with `revision: null`. */
+  noop: boolean;
+  /** Every row between N and the newest is loaded. When false, the preview is
+   *  NOT shown as a confident answer — a hole would hide a change. */
+  complete: boolean;
+  /** A whole restore leaves these as they are: the reader may not see them. */
+  withheld: string[];
+  /** A truncated or omitted side after N: the value at N is not known exactly,
+   *  and the server refuses with a 409. */
+  unknowable: string[];
+}
+
+function same(a: RestoreSide, b: RestoreSide): boolean {
+  if (a.has !== b.has) return false;
+  if (!a.has) return true;
+  if (a.value === b.value) return true;
+  try {
+    return JSON.stringify(a.value) === JSON.stringify(b.value);
+  } catch {
+    return false;
+  }
+}
+
+function sideOf(change: FoldedFieldChange, which: 'before' | 'after'): RestoreSide {
+  return which === 'before'
+    ? change.hasBefore
+      ? { has: true, value: change.before }
+      : { has: false }
+    : change.hasAfter
+      ? { has: true, value: change.after }
+      : { has: false };
+}
+
+/**
+ * What a restore to version `target` would change, computed exactly as the
+ * server computes it. `fields` narrows to a field restore; omit it for the whole
+ * record (which also covers the name column).
+ *
+ * `revisions` is the trail as the route returns it — newest first — and may
+ * contain rows at or below `target`; only rows NEWER than it are folded.
+ */
+export function restorePreview(
+  revisions: EntityRevision[],
+  target: number,
+  options: {
+    fields?: string[];
+    /** The rows came from a `?field=` read: they are that field's own trail, so
+     *  version gaps between them are other fields' edits, not holes. Only
+     *  meaningful with `fields`. */
+    narrowed?: boolean;
+  } = {},
+): RestorePreview {
+  const only = options.fields ? new Set(options.fields) : null;
+  const rows: NormalizedRevision[] = (revisions ?? [])
+    .map(normalizeRevision)
+    .sort((a, b) => b.version - a.version);
+  const newest = rows.length ? rows[0]!.version : target;
+  const later = rows.filter((r) => r.version > target);
+
+  // GAPLESS by construction server-side, so a count mismatch is a hole in what
+  // was LOADED (or a lost revision) — either way, not a preview to trust.
+  const versions = new Set(later.map((r) => r.version));
+  const complete =
+    (options.narrowed === true && !!only) || versions.size === Math.max(0, newest - target);
+
+  const current = new Map<string, RestoreSide>();
+  const restored = new Map<string, RestoreSide>();
+  const withheld = new Set<string>();
+  const unknowable = new Set<string>();
+  let nameCurrent: RestoreSide | undefined;
+  let nameRestored: RestoreSide | undefined;
+
+  // Newest first: the first row seen for a field gives its CURRENT value, and
+  // each older row overwrites what the restore would put back, so the last one
+  // standing is the oldest row after N — exactly the server's undo order.
+  for (const row of later) {
+    for (const [field, change] of Object.entries(row.changed)) {
+      if (only && !only.has(field)) continue;
+      if (change.withheld) {
+        withheld.add(field);
+        continue;
+      }
+      if (change.omitted || change.truncated) {
+        unknowable.add(field);
+        continue;
+      }
+      if (!current.has(field)) current.set(field, sideOf(change, 'after'));
+      restored.set(field, sideOf(change, 'before'));
+    }
+    if (!only) {
+      if (row.valuesOmitted) {
+        unknowable.add('name');
+      } else if (row.name) {
+        if (row.name.truncated) unknowable.add('name');
+        else {
+          if (!nameCurrent) nameCurrent = sideOf(row.name, 'after');
+          nameRestored = sideOf(row.name, 'before');
+        }
+      }
+    }
+  }
+
+  const changes: RestoreFieldChange[] = [];
+  for (const field of [...restored.keys()].sort()) {
+    if (unknowable.has(field) || withheld.has(field)) continue;
+    const c = current.get(field)!;
+    const r = restored.get(field)!;
+    if (!same(c, r)) changes.push({ field, current: c, restored: r });
+  }
+  const name =
+    nameCurrent && nameRestored && !same(nameCurrent, nameRestored)
+      ? { current: nameCurrent, restored: nameRestored }
+      : undefined;
+
+  const unknown = [...unknowable].filter((f) => !withheld.has(f)).sort();
+  return {
+    target,
+    newest,
+    changes,
+    ...(name ? { name } : {}),
+    noop: changes.length === 0 && !name && unknown.length === 0,
+    complete,
+    withheld: [...withheld].sort(),
+    unknowable: unknown,
+  };
+}
+
+/**
+ * Per field, the newest version that changed it, over the rows loaded. A field
+ * restore at version N is offered only where this is NEWER than N — on the row
+ * whose value IS the current one, a restore would change nothing.
+ */
+export function latestFieldVersions(revisions: EntityRevision[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const row of (revisions ?? []).map(normalizeRevision)) {
+    for (const field of Object.keys(row.changed)) {
+      if ((out[field] ?? -1) < row.version) out[field] = row.version;
+    }
+  }
+  return out;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  READING THE ANSWER                                                        */
+/* -------------------------------------------------------------------------- */
+
+export interface RestoreSummary {
+  restoredFrom?: number;
+  /** The keys that actually moved. */
+  fields: string[];
+  /** The new version, or `null` when nothing changed (no revision written). */
+  revision: number | null;
+}
+
+export type ParsedRestoreOutcome =
+  | {
+      kind: 'restored';
+      /** The record as the server saved it — prime the host cache with this. */
+      record: Record<string, unknown>;
+      /** The record's version after the call (unchanged on a no-op). */
+      version?: number;
+      summary: RestoreSummary;
+    }
+  | { kind: 'stale'; currentVersion?: number; detail?: string }
+  | { kind: 'refused'; status?: number; message: string };
+
+function statusOf(source: unknown): number | undefined {
+  if (!source || typeof source !== 'object') return undefined;
+  const c = source as { status?: unknown; statusCode?: unknown; response?: { status?: unknown } };
+  for (const raw of [c.status, c.statusCode, c.response?.status]) {
+    const v = toVersion(raw);
+    if (v !== undefined) return v;
+  }
+  return undefined;
+}
+
+function bodyOf(source: unknown): Record<string, unknown> {
+  if (!source || typeof source !== 'object') return {};
+  const c = source as { body?: unknown; data?: unknown; response?: { data?: unknown; body?: unknown } };
+  const raw = c.body ?? c.data ?? c.response?.data ?? c.response?.body;
+  return raw && typeof raw === 'object' ? (raw as Record<string, unknown>) : {};
+}
+
+/** DRF's error bodies: `{detail}`, or `{field: [msg]}` for a 400. */
+function serverSentence(body: Record<string, unknown>): string | undefined {
+  if (typeof body.detail === 'string' && body.detail) return body.detail;
+  for (const value of Object.values(body)) {
+    if (typeof value === 'string' && value) return value;
+    if (Array.isArray(value)) {
+      const first = value.find((v) => typeof v === 'string' && v);
+      if (first) return first as string;
+    }
+  }
+  return undefined;
+}
+
+const FALLBACK: Record<number, string> = {
+  400: 'This restore was refused — the field may no longer be declared on this type, or it would move the record out of its scope.',
+  403: 'You do not have access to one of these fields, so you cannot restore it.',
+  404: 'That version is no longer available — the record, or your access to it, has changed.',
+  409: 'The history cannot say exactly what the value was at that version, so it cannot be restored.',
+  428: 'A restore must say which version of the record it was chosen from. Reload and try again.',
+};
+
+/**
+ * What the route answered, from a resolved outcome OR a thrown error — a plain
+ * `fetch` resolves non-2xx and a wrapper throws, and a restore must not fall
+ * through to a generic failure on either.
+ */
+export function parseRestoreOutcome(source: unknown): ParsedRestoreOutcome {
+  const refusal = parseStaleSaveRefusal(source);
+  if (refusal) {
+    return {
+      kind: 'stale',
+      ...(refusal.currentVersion !== undefined ? { currentVersion: refusal.currentVersion } : {}),
+      ...(refusal.detail ? { detail: refusal.detail } : {}),
+    };
+  }
+  const status = statusOf(source);
+  const body = bodyOf(source);
+  const ok = status === undefined ? source instanceof Error === false && 'restore' in body : status >= 200 && status < 300;
+  if (!ok) {
+    const message =
+      serverSentence(body) ??
+      (status !== undefined ? FALLBACK[status] : undefined) ??
+      (source instanceof Error && source.message ? source.message : undefined) ??
+      'The restore did not go through. Please try again.';
+    return { kind: 'refused', ...(status !== undefined ? { status } : {}), message };
+  }
+  const raw = body.restore && typeof body.restore === 'object' ? (body.restore as Record<string, unknown>) : {};
+  const from = toVersion(raw.restored_from ?? raw.restoredFrom);
+  const revision = toVersion(raw.revision);
+  const version = toVersion(body.version);
+  return {
+    kind: 'restored',
+    record: body,
+    ...(version !== undefined ? { version } : {}),
+    summary: {
+      ...(from !== undefined ? { restoredFrom: from } : {}),
+      fields: Array.isArray(raw.fields) ? raw.fields.filter((f): f is string => typeof f === 'string') : [],
+      revision: revision ?? null,
+    },
+  };
+}

package/src/components/history/revision-feed.ts

@@ -0,0 +1,105 @@
+/**
+ * The cross-record edit feed, the pure half (bd startsim-ucg5u; route bd
+ * startsim-ivr3n `GET /api/v1/revisions/`).
+ *
+ * Two rules, each with a sharp edge on the wire:
+ *
+ * 1. ONLY THE PARAMS THE ROUTE ACCEPTS, NEVER BLANK. The route 400s a parameter
+ *    it does not recognise AND a blank `actor` or `scope` — a filter that could
+ *    have narrowed and did not is how a feed silently shows everything. So
+ *    {@link revisionFeedParams} is an allowlist that drops empty values, and the
+ *    panel sends nothing else (no `q`, no `action`, never `page`).
+ * 2. SITTINGS NEVER CROSS RECORDS. `foldRevisions` folds adjacent rows by the
+ *    same actor and assumes ONE entity. In a feed, two records saved a second
+ *    apart by the same person would fold into one sitting with a meaningless
+ *    version span. {@link foldFeed} folds only runs on the same record.
+ */
+import { COLLAPSE_WINDOW_MS, foldRevisions, type RevisionSitting } from './revision-history';
+import type { RevisionFeedEntity, RevisionFeedFilters, RevisionFeedRow } from './types';
+
+/** The filter keys the route accepts, in the order a URL shows them. */
+export const REVISION_FEED_FILTER_KEYS = ['actor', 'actor_kind', 'type', 'scope', 'since', 'until'] as const;
+
+/** The actor kinds the route accepts for `actor_kind`. */
+export const REVISION_FEED_ACTOR_KINDS = ['person', 'machine', 'unknown'] as const;
+
+/** Filters → query params: the allowlist, with blanks OMITTED. */
+export function revisionFeedParams(filters: RevisionFeedFilters | Record<string, unknown>): RevisionFeedFilters {
+  const out: Record<string, string> = {};
+  const source = (filters ?? {}) as Record<string, unknown>;
+  for (const key of REVISION_FEED_FILTER_KEYS) {
+    const value = source[key];
+    if (typeof value === 'string' && value.trim()) out[key] = value.trim();
+  }
+  return out as RevisionFeedFilters;
+}
+
+/** Read the filters out of URL search params (or anything with `get`). The
+ *  host's page owns the URL; this only knows the spelling. */
+export function revisionFeedFiltersFrom(params: { get(name: string): string | null } | null | undefined): RevisionFeedFilters {
+  const out: Record<string, string> = {};
+  if (!params) return out;
+  for (const key of REVISION_FEED_FILTER_KEYS) {
+    const v = params.get(key);
+    if (v && v.trim()) out[key] = v.trim();
+  }
+  return out as RevisionFeedFilters;
+}
+
+export interface FeedSitting {
+  /** Stable key: the entity plus the sitting's newest row. */
+  id: string;
+  entity: RevisionFeedEntity | null;
+  sitting: RevisionSitting;
+}
+
+function entityId(row: RevisionFeedRow): string {
+  return row.entity?.id ? String(row.entity.id) : '';
+}
+
+/** Fold a newest-first feed page into sittings, never across records. */
+export function foldFeed(rows: RevisionFeedRow[], windowMs: number = COLLAPSE_WINDOW_MS): FeedSitting[] {
+  const out: FeedSitting[] = [];
+  let run: RevisionFeedRow[] = [];
+  const flush = () => {
+    if (!run.length) return;
+    const entity = run[0]!.entity ?? null;
+    for (const sitting of foldRevisions(run, windowMs)) {
+      out.push({ id: `${entityId(run[0]!)}:${sitting.id}`, entity, sitting });
+    }
+    run = [];
+  };
+  for (const row of rows ?? []) {
+    if (run.length && entityId(run[run.length - 1]!) !== entityId(row)) flush();
+    run.push(row);
+  }
+  flush();
+  return out;
+}
+
+/** Monday 00:00 in the READER's timezone, as an ISO instant. "This week" means
+ *  the reader's week; sending the UTC day boundary instead would, east of
+ *  Greenwich, ask the server for a `since` in the future early on a Monday. */
+export function startOfThisWeek(now: Date = new Date()): string {
+  const d = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  d.setDate(d.getDate() - ((d.getDay() + 6) % 7)); // back to Monday
+  return d.toISOString();
+}
+
+/** A `YYYY-MM-DD` date input → the instant that local day starts / ends. */
+export function localDayStart(date: string): string {
+  const [y, m, d] = date.split('-').map(Number);
+  return new Date(y!, (m ?? 1) - 1, d ?? 1, 0, 0, 0, 0).toISOString();
+}
+export function localDayEnd(date: string): string {
+  const [y, m, d] = date.split('-').map(Number);
+  return new Date(y!, (m ?? 1) - 1, d ?? 1, 23, 59, 59, 999).toISOString();
+}
+/** An instant → the local `YYYY-MM-DD` a date input shows. */
+export function localDateInput(iso?: string): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}

package/src/components/history/revision-history.ts

@@ -194,6 +194,9 @@ export interface NormalizedRevision {
   valuesOmitted: boolean;
   /** A machine ATTEMPT: something was held back and nothing moved. */
   isAttempt: boolean;
+  /** Set on a `source: "restore"` row: the version it put back
+   *  (bd startsim-ti1yv). */
+  restoredFrom?: number;
 }
 
 export function normalizeRevision(revision: EntityRevision): NormalizedRevision {
@@ -213,6 +216,9 @@ export function normalizeRevision(revision: EntityRevision): NormalizedRevision
   }
 
   const preserved = strings(metadata.preserved);
+  const restoredRaw = metadata.restored_from ?? metadata.restoredFrom;
+  const restoredFrom =
+    typeof restoredRaw === 'number' && Number.isInteger(restoredRaw) ? restoredRaw : undefined;
   return {
     id: String(revision.id ?? ''),
     version: typeof revision.version === 'number' ? revision.version : 0,
@@ -233,6 +239,7 @@ export function normalizeRevision(revision: EntityRevision): NormalizedRevision
     redacted,
     valuesOmitted,
     isAttempt: preserved.length > 0 && Object.keys(changed).length === 0,
+    ...(restoredFrom !== undefined ? { restoredFrom } : {}),
   };
 }
 
@@ -272,6 +279,9 @@ export interface RevisionSitting {
   redacted: string[];
   valuesOmitted: boolean;
   isAttempt: boolean;
+  /** A restore is always its own sitting, so this is the restore's source
+   *  version when the sitting IS one. */
+  restoredFrom?: number;
 }
 
 /**
@@ -309,6 +319,10 @@ function sameSitting(
   if (newer.actorKindSource !== older.actorKindSource) return false;
   if (newer.isAttempt !== older.isAttempt) return false;
   if (older.action === 'created' || newer.action === 'created') return false;
+  // 5. A RESTORE IS ITS OWN ROW. Folded into the edit before it, "restored
+  //    from v2" would vanish into "Edited blog" and the one fact a restore row
+  //    carries — which version came back, and who chose it — would be lost.
+  if (newer.restoredFrom !== undefined || older.restoredFrom !== undefined) return false;
   if (!newer.createdAt || !older.createdAt) return false;
   const gap = Date.parse(newer.createdAt) - Date.parse(older.createdAt);
   return gap >= 0 && gap <= windowMs;
@@ -364,6 +378,7 @@ function startSitting(revision: NormalizedRevision): RevisionSitting {
     redacted: [...revision.redacted],
     valuesOmitted: revision.valuesOmitted,
     isAttempt: revision.isAttempt,
+    ...(revision.restoredFrom !== undefined ? { restoredFrom: revision.restoredFrom } : {}),
   };
 }
 
@@ -472,6 +487,13 @@ export function sittingHeadline(
   }
   const fields = sittingFields(sitting);
   const renamed = sitting.name !== undefined;
+  if (sitting.restoredFrom !== undefined) {
+    const from = `v${sitting.restoredFrom}`;
+    if (!fields.length) return renamed ? `Restored the name from ${from}` : `Restored from ${from} — nothing changed`;
+    return fields.length <= 3
+      ? `Restored ${joinNames(fields.map(fieldLabel))} from ${from}`
+      : `Restored ${fields.length} fields from ${from}`;
+  }
   if (sitting.action === 'created') {
     return fields.length ? `Created the record with ${fields.length} ${fields.length === 1 ? 'field' : 'fields'}` : 'Created the record';
   }

package/src/components/history/types.ts

@@ -45,7 +45,7 @@ export type RevisionAction = 'created' | 'updated' | 'deleted';
 
 /** Which endpoint wrote. `server` is a management command or a worker — a real
  *  write that must not claim to be an endpoint. */
-export type RevisionSource = 'create' | 'patch' | 'put' | 'upsert' | 'server';
+export type RevisionSource = 'create' | 'patch' | 'put' | 'upsert' | 'server' | 'restore';
 
 /** `none` always, today; `matched` arrives with the conditional write
  *  (bd startsim-3c2wc). */
@@ -98,6 +98,14 @@ export interface RevisionMetadata {
   values_omitted?: boolean;
   /** Camelised alias — see the header. */
   valuesOmitted?: boolean;
+  /** On a `source: "restore"` row: the version whose values it put back
+   *  (bd startsim-ti1yv). */
+  restored_from?: number;
+  restoredFrom?: number;
+  /** On a FIELD restore: the fields the caller named. Absent on a whole-record
+   *  restore. */
+  restored_fields?: string[];
+  restoredFields?: string[];
 }
 
 /** One row of the append-only revision trail. Only `id` and `version` are
@@ -135,6 +143,9 @@ export interface EntityRevision {
  *  was held back. */
 export interface RevisionPage {
   count?: number;
+  /** The resolved history policy for this record's TYPE (bd startsim-jkkn7.17).
+   *  `enabled: false` means new edits are not recorded. */
+  history?: RevisionHistoryPolicy | null;
   next?: string | null;
   previous?: string | null;
   results?: EntityRevision[];
@@ -148,6 +159,12 @@ export interface RevisionPage {
 export interface RevisionQuery {
   page?: number;
   pageSize?: number;
+  /** Narrow to revisions that changed this field — `?field=` (bd
+   *  startsim-jkkn7.8). A key-existence test server-side, so the result is the
+   *  field's own trail; it misses held-back re-sends and name changes (bd
+   *  startsim-jkkn7.18), which is why a narrowed panel offers no whole-record
+   *  restore. */
+  field?: string;
   // Index signature so this satisfies an API client's query-params type; the
   // injected client is the app's own.
   [key: string]: unknown;
@@ -164,4 +181,139 @@ export interface RevisionQuery {
  */
 export interface RevisionClient {
   list: (query: RevisionQuery) => Promise<RevisionPage>;
+  /**
+   * `POST /entities/<id>/revisions/<N>/restore/` (bd startsim-ti1yv). Optional:
+   * a host that omits it gets a read-only panel with no restore actions.
+   *
+   * Like {@link ConditionalWriteClient.write} it may RESOLVE with a non-2xx
+   * outcome or THROW one carrying `status`/`body`; both are understood. Send
+   * `expectedVersion` in ONE spelling only (body `expected_version` or
+   * `If-Match`) — the server refuses if either of two disagrees.
+   */
+  restore?: (request: RestoreRequest) => Promise<RestoreOutcome>;
+}
+
+/** The resolved history policy, as the revisions envelope and the field-authors
+ *  read both carry it. */
+export interface RevisionHistoryPolicy {
+  enabled?: boolean;
+  /** `type`, `"*"`, or `default` — who decided. */
+  declared_by?: string;
+  declaredBy?: string;
+}
+
+/** One restore. `fields` omitted restores the WHOLE record to version N. */
+export interface RestoreRequest {
+  /** N — the record is put back to how it stood AFTER revision N. */
+  version: number;
+  fields?: string[];
+  /** REQUIRED by the route (428 without it): the version the caller believes is
+   *  current. */
+  expectedVersion: number;
+}
+
+/** What the transport hands back — the same shape as a conditional write. */
+export interface RestoreOutcome {
+  status?: number;
+  body?: unknown;
+  headers?: Record<string, string | null | undefined> | { get(name: string): string | null | undefined };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  FIELD AUTHORS — GET /entities/<id>/field-authors/ (bd startsim-6sso4)     */
+/* -------------------------------------------------------------------------- */
+
+/** The latest author of ONE field. Snake and camel both declared — see the
+ *  spelling trap in this module's header. */
+export interface FieldAuthor {
+  version?: number;
+  at?: string | null;
+  actor_sub?: string | null;
+  actorSub?: string | null;
+  actor_label?: string | null;
+  actorLabel?: string | null;
+  actor_kind?: ActorKind | string | null;
+  actorKind?: ActorKind | string | null;
+  actor_kind_source?: ActorKindSource | string | null;
+  actorKindSource?: ActorKindSource | string | null;
+  source?: string | null;
+  restored_from?: number | null;
+  restoredFrom?: number | null;
+}
+
+/** Where the trail begins for this record. Live rows PREDATE the trail, so a
+ *  field with no entry means "not edited since this", never "never edited". */
+export interface FieldAuthorsTrailStart {
+  version?: number;
+  at?: string | null;
+  from_creation?: boolean;
+  fromCreation?: boolean;
+}
+
+export interface FieldAuthorsResponse {
+  entity_id?: string;
+  entityId?: string;
+  version?: number;
+  history?: RevisionHistoryPolicy | null;
+  /** `false` when history is off for this type: `fields` is then `null` and
+   *  NOTHING may be inferred about who edited what. */
+  recorded?: boolean;
+  trail_starts?: FieldAuthorsTrailStart | null;
+  trailStarts?: FieldAuthorsTrailStart | null;
+  /** Withheld fields are omitted entirely. `null` when not recorded. */
+  fields?: Record<string, FieldAuthor> | null;
+  /** The name COLUMN's latest author, namespaced away from data keys. */
+  name?: FieldAuthor | null;
+  /** The server's sentence when `recorded` is false. */
+  detail?: string;
+}
+
+export interface FieldAuthorsClient {
+  get: () => Promise<FieldAuthorsResponse>;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE FEED — GET /api/v1/revisions/ (bd startsim-ivr3n)                     */
+/* -------------------------------------------------------------------------- */
+
+/** The record a feed row belongs to. */
+export interface RevisionFeedEntity {
+  id: string;
+  type?: string;
+  name?: string | null;
+}
+
+/** One feed row: a revision plus the record it changed. */
+export interface RevisionFeedRow extends EntityRevision {
+  entity?: RevisionFeedEntity | null;
+}
+
+/** The filters the route accepts, keyed exactly as the URL spells them so a
+ *  host can round-trip them through search params unchanged. */
+export interface RevisionFeedFilters {
+  /** An actor SUB, never a label. */
+  actor?: string;
+  actor_kind?: string;
+  type?: string;
+  scope?: string;
+  since?: string;
+  until?: string;
+}
+
+export interface RevisionFeedQuery extends RevisionFeedFilters {
+  cursor?: string;
+  pageSize?: number;
+  [key: string]: unknown;
+}
+
+/** NO `count` — the route does not compute one, and `?page=` is a 400. */
+export interface RevisionFeedPage {
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: RevisionFeedRow[];
+}
+
+export interface RevisionFeedClient {
+  list: (query: RevisionFeedQuery) => Promise<RevisionFeedPage>;
 }