@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/src/judged-dispatcher.ts

@@ -10,8 +10,8 @@
  *
  * Per case: the replay runs, the items kept, dropped and new (new ones
  * for experts to judge), the tool calls and what happened to each, and
- * whether the replay diverged (a read with no recording ran live under
- * `reads: 'recorded'`). The summary (`JudgedComparisonSummary`) is what a
+ * whether the replay diverged (a read ran live under `reads: 'recorded'`,
+ * other than a recomputed one). The summary (`JudgedComparisonSummary`) is what a
  * promotion gate reads.
  */
 
@@ -21,13 +21,20 @@ import type { RunId } from '@kindgi/types';
 
 import type { AgentRegistryBinding } from './agent-binding.js';
 import type { EvalCaseStoreBinding, JudgedEvalCase } from './eval-case-binding.js';
-import type { AgentRef, EvalClassWeights, EvalComparison, FlowRef } from './eval-run-binding.js';
+import type {
+  AgentRef,
+  EvalClassWeights,
+  EvalComparison,
+  EvalSample,
+  FlowRef,
+} from './eval-run-binding.js';
 import type {
   DispatchContext,
   DispatchResult,
   EvalRunDispatcher,
   EvalRunSubjectInvokeOutcome,
 } from './eval-run-dispatcher.js';
+import { sampleCases } from './eval-sample.js';
 import {
   type ItemChanges,
   type OutputScore,
@@ -92,6 +99,15 @@ export type ComparisonCandidate =
        * without an agent registry.
        */
       readonly pinsDigest?: string;
+      /**
+       * The blocks whose content the replays replaced
+       * (`comparison.overrides`): it ran no published version, so it
+       * can't gate a promotion.
+       */
+      readonly overrides?: {
+        readonly settings?: readonly string[];
+        readonly prompts?: readonly string[];
+      };
     }
   | {
       readonly kind: 'flow';
@@ -112,7 +128,11 @@ export interface JudgedComparisonSummary {
   /** Where the test set's judgments came from. */
   readonly scope: { readonly projectId?: string };
   readonly cases: number;
-  /** Cases where a read with no recording ran live under `reads: 'recorded'`. */
+  /**
+   * Cases where a read ran live under `reads: 'recorded'`: one with no
+   * recording, or one re-run because the candidate pins other settings
+   * that reads from somewhere. A recomputed call (reads from nowhere) isn't.
+   */
   readonly diverged: number;
   /** Tool calls refused across the cases (what the candidate would have done). */
   readonly refusedWrites: number;
@@ -123,6 +143,11 @@ export interface JudgedComparisonSummary {
    * refused): no output to score, so they're left out of the metrics.
    */
   readonly stopped: number;
+  /**
+   * Cases an erasure cleared (a person's words were erased): left out of
+   * the run and the metrics. Absent: none.
+   */
+  readonly erased?: number;
   readonly reads: EvalComparison['reads'];
   /**
    * Which judgments counted: `restricted-only` weighs a judgment not
@@ -130,6 +155,8 @@ export interface JudgedComparisonSummary {
    * from a summary recorded before T200: `as-recorded`.
    */
   readonly classWeights?: EvalClassWeights;
+  /** The part of the test set it ran (absent: every case). */
+  readonly sample?: EvalSample;
   /** The models that answered the candidate's replays, and how many replays each. */
   readonly sampling: {
     readonly models: readonly {
@@ -176,6 +203,9 @@ export interface JudgedDispatcherOptions {
 /** Cases read per page. */
 const CASE_PAGE = 100;
 
+export const OVERRIDES_NEED_AN_AGENT =
+  "`overrides` replaces an agent version's block content: it needs `agentRef`.";
+
 export const VERSIONS_NEED_A_FLOW =
   '`versions` runs a flow with some of its agents or tools at other versions: it needs `flowRef`.';
 
@@ -200,6 +230,9 @@ function validateComparison(
   if (c.versions !== undefined && 'agentId' in target) {
     return { kind: 'err', message: VERSIONS_NEED_A_FLOW };
   }
+  if (c.overrides !== undefined && !('agentId' in target)) {
+    return { kind: 'err', message: OVERRIDES_NEED_AN_AGENT };
+  }
   if (c.baseline !== 'recorded') {
     return { kind: 'err', message: "Only `baseline: 'recorded'` runs today." };
   }
@@ -212,22 +245,41 @@ export function createJudgedDispatcher(options: JudgedDispatcherOptions): EvalRu
     validate: validateComparison,
     async dispatch(ctx): Promise<DispatchResult> {
       const comparison = ctx.comparison ?? DEFAULT_COMPARISON;
-      const stored = await allCases(options.cases, ctx);
+      const listed = await allCases(options.cases, ctx);
+      // An erased case has nothing left to replay: left out, and counted.
+      // A sample is drawn from the rest.
+      const replayable = listed.filter((c) => c.erased !== true);
+      const erased = listed.length - replayable.length;
+      const stored =
+        comparison.sample === undefined ? replayable : sampleCases(replayable, comparison.sample);
       const all =
         comparison.classWeights === 'restricted-only' ? stored.map(restrictedOnly) : stored;
       if (ctx.dryRun) {
-        return { result: { dryRun: true, cases: all.length, comparison } };
+        return {
+          result: { dryRun: true, cases: all.length, ...(erased > 0 && { erased }), comparison },
+        };
       }
       const results: JudgedCaseResult[] = [];
       const models = new Map<string, { providerId: string; model: string; runs: number }>();
+      // Erased after they were listed: the replay was refused (`run-erased`).
+      const erasedLate = new Set<string>();
       for (const judgedCase of all) {
         if (ctx.abortSignal.aborted) break;
         const result = await runCase(ctx, comparison, judgedCase, models);
+        if (result === 'erased') {
+          erasedLate.add(judgedCase.caseId);
+          continue;
+        }
         results.push(result);
         ctx.onProgress(result as unknown as Readonly<Record<string, unknown>>);
       }
       const pinsDigest = await candidatePins(options.agents, ctx);
-      const summary = summarize(ctx, comparison, all, results, [...models.values()], pinsDigest);
+      const ran = all.filter((c) => !erasedLate.has(c.caseId));
+      const erasedAll = erased + erasedLate.size;
+      const summary = {
+        ...summarize(ctx, comparison, ran, results, [...models.values()], pinsDigest),
+        ...(erasedAll > 0 && { erased: erasedAll }),
+      };
       return {
         result: { summary, perCase: results },
         ...(ctx.abortSignal.aborted && { error: 'cancelled' }),
@@ -299,7 +351,11 @@ class CaseTally {
     this.candidate.push(scoreItems(matched, comparison.k));
     const tools = outcome.replay?.tools ?? [];
     this.refusedWrites = Math.max(this.refusedWrites, refusedCount(outcome));
-    if (comparison.reads === 'recorded' && tools.some((t) => t.source === 'live')) {
+    // A recomputed call read nothing new: only a live read diverges.
+    if (
+      comparison.reads === 'recorded' &&
+      tools.some((t) => t.source === 'live' && t.recomputed !== true)
+    ) {
       this.diverged = true;
     }
     if (outcome.replay?.approval === 'skipped') this.approvalSkipped = true;
@@ -331,7 +387,7 @@ async function runCase(
   comparison: EvalComparison,
   judgedCase: JudgedEvalCase,
   models: Map<string, { providerId: string; model: string; runs: number }>,
-): Promise<JudgedCaseResult> {
+): Promise<JudgedCaseResult | 'erased'> {
   // An agent turn's items are its answer and typed result; a flow run's, its whole output.
   const agentTurn = judgedCase.subject.kind === 'agent';
   const baseline = scoreItems(
@@ -341,6 +397,8 @@ async function runCase(
   const tally = new CaseTally(judgedCase, comparison, agentTurn);
   for (let rep = 0; rep < comparison.repetitions; rep++) {
     const outcome = await invokeCase(ctx, judgedCase);
+    // Its past run was erased meanwhile: nothing left to replay.
+    if (outcome.erased === true) return 'erased';
     if (tally.add(outcome) === 'ran') countModel(models, outcome);
   }
   return tally.result(baseline);
@@ -505,7 +563,7 @@ function summarize(
           : 'failed',
     completedAt: new Date().toISOString(),
     suite: { id: ctx.suite.id, version: ctx.suite.version },
-    candidate: candidateOf(ctx.target, ctx.comparison?.versions, pinsDigest),
+    candidate: candidateOf(ctx.target, ctx.comparison, pinsDigest),
     baseline: {
       kind: 'recorded',
       versions: [...versions.values()].map(
@@ -523,6 +581,7 @@ function summarize(
     stopped,
     reads: comparison.reads,
     classWeights: comparison.classWeights ?? 'as-recorded',
+    ...(comparison.sample !== undefined && { sample: comparison.sample }),
     sampling: { models },
     repetitions: comparison.repetitions,
     metrics: {
@@ -579,15 +638,23 @@ async function candidatePins(
 
 function candidateOf(
   target: AgentRef | FlowRef,
-  versions: FlowVersionOverrides | undefined,
+  comparison: EvalComparison | undefined,
   pinsDigest?: string,
 ): ComparisonCandidate {
+  const versions = comparison?.versions;
+  const settings = Object.keys(comparison?.overrides?.settings ?? {}).sort();
+  const prompts = Object.keys(comparison?.overrides?.prompts ?? {}).sort();
+  const overrides = {
+    ...(settings.length > 0 && { settings }),
+    ...(prompts.length > 0 && { prompts }),
+  };
   return 'agentId' in target
     ? {
         kind: 'agent',
         agentId: target.agentId as unknown as string,
         version: target.version ?? '',
         ...(pinsDigest !== undefined && { pinsDigest }),
+        ...(Object.keys(overrides).length > 0 && { overrides }),
       }
     : {
         kind: 'flow',

package/src/judgment-binding.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
-import type { Cursor, ListScope, ProjectId, TenantId } from '@kindgi/types';
+import type { Cursor, ListScope, ProjectId, ScopeSegment, TenantId } from '@kindgi/types';
 
 /**
  * Caller-plugged surface for judgments: a person says yes or no, with an
@@ -272,6 +272,8 @@ export interface JudgedRunContext {
   readonly historyTruncated?: boolean;
   /** What the turn's retrievals returned. */
   readonly retrieved?: unknown;
+  /** Messages of earlier conversations the turn recalled. A replay of the turn reuses them. */
+  readonly recalled?: unknown;
   /**
    * The reviewer's decision at the turn's session approval gate, when the
    * turn waited on one. A replay of the turn follows it.
@@ -279,6 +281,13 @@ export interface JudgedRunContext {
   readonly sessionApproval?: { readonly approved: boolean; readonly rationale?: string };
   /** For a flow run: what it did (see `JudgedFlowContext`). */
   readonly flow?: JudgedFlowContext;
+  /**
+   * The env values each tool's calls were sent (`needsSpec.env`), by tool
+   * id: its first call's, as the run recorded them. A replay sends them to
+   * a read-only tool it runs live, so the tool reads the config the run
+   * saw, not today's. Absent for a run from before env was recorded.
+   */
+  readonly toolEnv?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
 
 /** One tool call a judged run made, and its result. */
@@ -303,6 +312,8 @@ export interface JudgedFlowStep {
   readonly agentVersion: string;
   /** What the turn's retrievals returned. */
   readonly retrieved?: unknown;
+  /** Messages of earlier conversations the turn recalled. */
+  readonly recalled?: unknown;
 }
 
 /**
@@ -325,6 +336,11 @@ export interface JudgedRunCopy {
   readonly output: unknown;
   /** Absent for runs judged before context was captured, and for flow runs. */
   readonly context?: JudgedRunContext;
+  /**
+   * The segment path the run was started with (empty: none). Absent for
+   * runs judged before it was captured: such a run belongs to no segment.
+   */
+  readonly segments?: readonly ScopeSegment[];
   readonly capturedAt: string;
 }
 
@@ -345,6 +361,8 @@ export interface JudgmentRecordInput {
     readonly input: unknown;
     readonly output: unknown;
     readonly context?: JudgedRunContext;
+    /** The segment path the run was started with (empty: none). */
+    readonly segments?: readonly ScopeSegment[];
   };
   readonly item: JudgedItem;
   /** The item's value at `item.pointer`, resolved by the route from the run's output. */
@@ -393,6 +411,12 @@ export interface JudgedRunListInput {
   readonly since?: string;
   /** Runs first judged before this time (ISO 8601). */
   readonly until?: string;
+  /**
+   * Runs started in this segment path or below it (their captured
+   * `segments` start with it). A run judged before segments were captured
+   * is in none.
+   */
+  readonly segments?: readonly ScopeSegment[];
   readonly cursor?: Cursor;
   readonly limit: number;
 }

package/src/mcp-endpoint-binding.ts

@@ -126,6 +126,13 @@ export interface MCPEndpoint {
   readonly instructions?: string;
   /** Optional caller-defined metadata bag. */
   readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * Whether the runtime sends the W3C `traceparent` of the run calling a
+   * tool to this endpoint (as a request header; ids only, never content),
+   * so the server's logs can be matched to the run. Opt-in: absent or
+   * `false` sends none. HTTP transports only (`stdio` has no headers).
+   */
+  readonly sendTraceparent?: boolean;
 }
 
 export interface MCPEndpointListInput {

package/src/memory-binding.ts

@@ -1,9 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { Fact, MemoryScope, Retention } from '@kindgi/memory';
+import type {
+  Fact,
+  FactAttribution,
+  FactSubject,
+  MemoryReaders,
+  MemoryScope,
+  Retention,
+} from '@kindgi/memory';
 import type { Scope as PlatformScope } from '@kindgi/platform';
-import type { Cursor, FactId, TenantId } from '@kindgi/types';
+import type { Cursor, FactId, TenantId, Timestamp } from '@kindgi/types';
 
 /**
  * Caller-plugged surface for the memory resource. Same shape as
@@ -21,12 +28,36 @@ import type { Cursor, FactId, TenantId } from '@kindgi/types';
  * ISO timestamp, `id@version`, whatever). The API layer only validates
  * that a cursor round-trips as a string; it never inspects the payload.
  *
- * Supersession, not delete: facts are append-only. `supersedeFact`
- * writes a new revision that supersedes the target; the historical row
- * remains readable until retention sweeps it. There is no hard delete;
- * the retention sweep handles physical removal.
+ * A fact keeps its id across revisions. `supersedeFact` writes the next
+ * revision and closes the current one; `deleteFact` tombstones the fact
+ * (the retention sweep removes it later); `verifyFact` writes a revision
+ * marked verified. Reads see each fact's current revision unless they
+ * ask for history (`asOf`, `listRevisions`).
+ *
+ * Every read and write names what the caller may see (`readers`), worked
+ * out by the route from the principal: the binding applies it inside its
+ * query, before any limit, and treats what it can't see as not found.
  */
 export interface MemoryBinding {
+  /**
+   * Whether this memory can search by meaning (an embedding model is
+   * configured). Absent: unknown. When `false`, publishing an agent whose
+   * retrieval searches by meaning warns, and a semantic retrieval answers
+   * `422 semantic-unavailable`.
+   */
+  readonly semanticSearch?: boolean;
+  /**
+   * Whether agent turns can store what an agent remembers (an agent's
+   * `memory.remember`). Absent: unknown. When `false`, publishing an agent
+   * that remembers warns `remember-unavailable`.
+   */
+  readonly agentRemember?: boolean;
+  /**
+   * Whether agent turns can recall earlier conversations (an intent with
+   * `source: 'conversations'`). Absent: unknown. When `false`, publishing
+   * such an agent warns `recall-unavailable`.
+   */
+  readonly conversationRecall?: boolean;
   /**
    * Cursor-paginated list of facts under the tenant. Filters:
    *   - `type` — exact fact-type match.
@@ -37,10 +68,9 @@ export interface MemoryBinding {
    */
   listFacts(input: MemoryListFactsInput): Promise<MemoryFactPage>;
   /**
-   * The fact with the given id, or `null` if unknown. Latest version
-   * by default; bindings MAY accept a `version` in the input to select
-   * a specific historical revision (not exposed on the route today).
-   * The route surfaces `null` as `404 fact-not-found`.
+   * The fact with the given id: its current revision, or the one at
+   * `version`, or the one current at `asOf`; `null` when there's none
+   * the caller may see. The route surfaces `null` as `404 fact-not-found`.
    */
   getFact(input: MemoryGetFactInput): Promise<Fact | null>;
   /**
@@ -54,13 +84,29 @@ export interface MemoryBinding {
    */
   writeFact(input: MemoryWriteFactInput): Promise<MemoryWriteFactOutcome>;
   /**
-   * Mark a fact as superseded. The binding writes a superseding
-   * revision (or flags the row, depending on its runtime semantics).
-   * Idempotent — superseding an already-superseded fact returns
-   * `{ superseded: true }` without error. When the fact id is unknown,
-   * returns `{ superseded: false }` and the route flips that to `404`.
+   * Write the fact's next revision (new content, the same id) and close
+   * the current one, atomically. With `expectVersion`, only when that is
+   * still the current revision (`fact-changed` otherwise). Legal hold
+   * refuses it.
    */
   supersedeFact(input: MemorySupersedeFactInput): Promise<MemorySupersedeFactOutcome>;
+  /**
+   * Tombstone the fact: its current revision is closed as `deleted`, and
+   * reads no longer see it (history still does, until the retention sweep
+   * removes it). Legal hold refuses it. Optional: without it, the route
+   * answers `501 memory-operation-unsupported`.
+   */
+  deleteFact?(input: MemoryDeleteFactInput): Promise<MemoryFactChangeOutcome>;
+  /**
+   * Mark the fact verified: a revision with the same content and
+   * `trust: verified`, by the caller. Optional (`501` without it).
+   */
+  verifyFact?(input: MemoryVerifyFactInput): Promise<MemoryFactChangeOutcome>;
+  /**
+   * Every revision of the fact, newest first; `null` when there's none
+   * the caller may see. Optional (`501` without it).
+   */
+  listRevisions?(input: MemoryGetFactInput): Promise<readonly Fact[] | null>;
   /**
    * Cross-history retrieval. The `intent` mirrors the shape agents use
    * for declarative retrieval (`packages/agents/src/retrieval.ts`):
@@ -83,6 +129,10 @@ export interface MemoryBinding {
 
 export interface MemoryListFactsInput {
   readonly tenantId: TenantId;
+  /** What the caller may see: applied in the query, before the limit. */
+  readonly readers: MemoryReaders;
+  /** Each fact's revision current at this time, instead of now. */
+  readonly asOf?: Timestamp;
   readonly limit: number;
   readonly cursor?: Cursor;
   /** Exact match on `Fact.type`. Undefined = no type filter. */
@@ -133,6 +183,11 @@ export interface MemoryFactPage {
 export interface MemoryGetFactInput {
   readonly tenantId: TenantId;
   readonly factId: FactId;
+  readonly readers: MemoryReaders;
+  /** A given revision. */
+  readonly version?: number;
+  /** The revision current at this time. */
+  readonly asOf?: Timestamp;
 }
 
 // -------------------- write --------------------
@@ -150,6 +205,12 @@ export interface MemoryWriteFactInput {
   readonly content: unknown;
   readonly retention?: Retention;
   readonly contentHash?: string;
+  /** Who writes it: set by the route from the principal, never from the body. */
+  readonly attributedTo?: FactAttribution;
+  readonly subjects?: readonly FactSubject[];
+  readonly validFrom?: Timestamp;
+  readonly validUntil?: Timestamp;
+  readonly observedAt?: Timestamp;
 }
 
 export type MemoryWriteFactOutcome =
@@ -178,12 +239,53 @@ export type MemoryWriteFactOutcome =
 export interface MemorySupersedeFactInput {
   readonly tenantId: TenantId;
   readonly factId: FactId;
+  readonly readers: MemoryReaders;
+  /**
+   * The next revision's content; the fact's type and scope stay, and the
+   * fields below keep the current revision's values when absent.
+   */
+  readonly content: unknown;
+  readonly retention?: Retention;
+  readonly subjects?: readonly FactSubject[];
+  readonly validFrom?: Timestamp;
+  readonly validUntil?: Timestamp;
+  readonly observedAt?: Timestamp;
+  /** Only when this is still the current revision. */
+  readonly expectVersion?: number;
+  readonly attributedTo?: FactAttribution;
+}
+
+export type MemorySupersedeFactOutcome = MemoryFactChangeOutcome;
+
+export interface MemoryDeleteFactInput {
+  readonly tenantId: TenantId;
+  readonly factId: FactId;
+  readonly readers: MemoryReaders;
+  /** `user:<id>` or `service:<id>`. */
+  readonly by: string;
+  readonly expectVersion?: number;
 }
 
-export interface MemorySupersedeFactOutcome {
-  readonly superseded: boolean;
+export interface MemoryVerifyFactInput {
+  readonly tenantId: TenantId;
+  readonly factId: FactId;
+  readonly readers: MemoryReaders;
+  /** `user:<id>` or `service:<id>`. */
+  readonly by: string;
+  readonly expectVersion?: number;
 }
 
+/** What changing a fact (supersede, delete, verify) came to. */
+export type MemoryFactChangeOutcome =
+  /** The fact's revision now current (for a delete: the tombstoned one). */
+  | { readonly kind: 'ok'; readonly fact: Fact }
+  | { readonly kind: 'not-found' }
+  /** `expectVersion` isn't the current revision any more. */
+  | { readonly kind: 'fact-changed'; readonly current: Fact }
+  /** The fact is under legal hold. */
+  | { readonly kind: 'legal-hold'; readonly message: string }
+  | { readonly kind: 'error'; readonly code: string; readonly message: string };
+
 // -------------------- retrieve --------------------
 
 /**
@@ -215,6 +317,8 @@ export interface MemoryRetrieveIntent {
 export interface MemoryRetrieveInput {
   readonly tenantId: TenantId;
   readonly intent: MemoryRetrieveIntent;
+  /** What the caller may see: applied in the query, before any limit. */
+  readonly readers: MemoryReaders;
 }
 
 export interface MemoryRetrievalHit {

package/src/memory-erasure-binding.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for erasing a person's words
+ * (`/v1/memory/erasures`). The API package validates, authorizes (a
+ * tenant admin only) and shapes the wire; the binding runs the erasure:
+ * memory facts, conversations, the runs that served them, and what they
+ * left in provenance, as the deployment's runtime knows its stores. An
+ * erasure runs in the background; `create` answers once it's recorded.
+ *
+ * A completed erasure keeps no identifier: what's left is its ledger row
+ * (the selector's kind, a keyed hash of it, who, when, how much), which
+ * an operator exports off-box and replays after restoring a backup.
+ */
+export interface MemoryErasureBinding {
+  create(input: {
+    readonly tenantId: TenantId;
+    readonly selector: MemoryErasureSelector;
+    /** `user:<id>` or `service:<id>`: who asked. */
+    readonly requestedBy: string;
+  }): Promise<CreateMemoryErasureOutcome>;
+  get(tenantId: TenantId, id: string): Promise<MemoryErasure | undefined>;
+  /** Newest first. `undefined` when the cursor isn't one this binding issued. */
+  list(
+    tenantId: TenantId,
+    page: { readonly limit: number; readonly cursor?: string },
+  ): Promise<{ readonly data: readonly MemoryErasure[]; readonly nextCursor?: string } | undefined>;
+  /** The whole ledger, content-free, oldest first. */
+  exportLedger(tenantId: TenantId): Promise<readonly MemoryErasureLedgerEntry[]>;
+  /**
+   * Try an unfinished erasure again now; with `force`, stop waiting for a
+   * run in a flow that serves other people (it's cancelled). A finished
+   * one comes back as it is; `undefined` when there's no such erasure.
+   */
+  resume(
+    tenantId: TenantId,
+    id: string,
+    options: { readonly force?: boolean },
+  ): Promise<MemoryErasure | undefined>;
+  /** After a backup restore: restore the ledger and run its erasures again. */
+  replay(
+    tenantId: TenantId,
+    entries: readonly MemoryErasureLedgerEntry[],
+  ): Promise<ReplayMemoryErasuresResult>;
+}
+
+/**
+ * Whose words to erase: one fact, a person (an app's end user
+ * `participant`, or an `external` subject facts name), or one
+ * conversation. Erasing a Kindgi user isn't offered.
+ */
+export type MemoryErasureSelector =
+  | { readonly factId: string }
+  | {
+      readonly subject: {
+        readonly kind: 'participant' | 'external';
+        readonly id: string;
+      };
+    }
+  | { readonly conversationId: string };
+
+export type MemoryErasureSelectorKind = 'fact' | 'participant' | 'external' | 'conversation';
+
+/**
+ * `waiting-on-run`: a turn of the person's sits in a flow that serves
+ * other people; the erasure waits for it (`waitingOn`) until its
+ * deadline, then cancels it. `resume` with `force` stops the wait.
+ */
+export type MemoryErasureStatus = 'pending' | 'running' | 'waiting-on-run' | 'completed' | 'failed';
+
+export interface MemoryErasure {
+  readonly id: string;
+  readonly selectorKind: MemoryErasureSelectorKind;
+  /** Only while it runs: a completed or failed erasure keeps no identifier. */
+  readonly selector?: MemoryErasureSelector;
+  readonly status: MemoryErasureStatus;
+  /**
+   * Where a running erasure is: `seed`, `expand`, `settle` (the person's
+   * unfinished runs end, or it waits for them, before anything is
+   * cleared), `erase`, then `done`.
+   */
+  readonly phase: 'seed' | 'expand' | 'settle' | 'erase' | 'done';
+  readonly requestedBy: string;
+  /** A replay after a backup restore can find this person again (a keyed hash was kept). */
+  readonly matchable: boolean;
+  /** What each store cleared or deleted, by store. */
+  readonly counts: Readonly<Record<string, number>>;
+  /** Failed attempts so far. */
+  readonly attempts: number;
+  /** The last failure's code, or why it's waiting (`not-yet:<reason>`). Never content. */
+  readonly lastError?: string;
+  /** The run it waits (or waited) for, and until when; kept as the record of the wait. */
+  readonly waitingOn?: { readonly runId: string; readonly until?: string };
+  /** A tenant admin said not to wait. */
+  readonly forced?: true;
+  /**
+   * Runs of the person's kept appearing, round after round: the erasure
+   * went on to erase after its last round rather than wait any longer.
+   */
+  readonly settleRoundsCapped?: true;
+  readonly createdAt: string;
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+  readonly replayedAt?: string;
+}
+
+/** One ledger row, as exported off-box and given back to a replay. Content-free. */
+export interface MemoryErasureLedgerEntry {
+  readonly id: string;
+  readonly selectorKind: MemoryErasureSelectorKind;
+  /** HMAC-SHA256 (hex) of the selector under the tenant's ledger key; absent without one. */
+  readonly selectorHmac?: string;
+  /** Which ledger key made `selectorHmac`. */
+  readonly keyId?: string;
+  readonly requestedBy: string;
+  readonly status: MemoryErasureStatus;
+  readonly createdAt: string;
+  readonly completedAt?: string;
+}
+
+export interface MemoryErasureWarning {
+  /** `erasure-unmatchable`: no ledger key, so a replay after a restore can't find this person. */
+  readonly code: 'erasure-unmatchable';
+  readonly message: string;
+}
+
+export type CreateMemoryErasureOutcome =
+  | {
+      readonly kind: 'created';
+      readonly erasure: MemoryErasure;
+      readonly warnings: readonly MemoryErasureWarning[];
+    }
+  | {
+      readonly kind: 'refused';
+      /** Legal hold on a fact it reaches: nothing started. */
+      readonly refusal: {
+        readonly code: 'legal-hold';
+        readonly message: string;
+        readonly factIds?: readonly string[];
+      };
+    };
+
+export interface ReplayMemoryErasuresResult {
+  /** Matched to an id in the tenant again: run again. */
+  readonly replayed: readonly string[];
+  /** Put back in the ledger; nothing in the tenant matches (nothing to erase). */
+  readonly restored: readonly string[];
+  /** No keyed hash, or a key this deployment doesn't hold. */
+  readonly unmatched: readonly {
+    readonly id: string;
+    readonly reason: 'no-keyed-hash' | 'unknown-key';
+  }[];
+}