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

package/src/routes/memory-access.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Who can see and change which memory, for a caller of `/v1/memory`.
+ *
+ * Reads: the containers the caller may read (`MemoryReaders`), worked out
+ * here from the principal and handed to the binding, which applies them
+ * inside its query. A tenant admin (or a deployment without
+ * authorization) reads everything; anyone else reads tenant-wide facts,
+ * the projects and orgs they may read, their own user facts, and every
+ * end user's and conversation's facts in the projects they may write (an
+ * app's own credential acting for its users).
+ *
+ * Writes: what the fact's scope names decides the check.
+ */
+
+import type { Context } from 'hono';
+
+import { type Principal, ref } from '@kindgi/authz';
+import type { MemoryReaders, MemoryScope } from '@kindgi/memory';
+import type { ProjectBinding } from '@kindgi/platform';
+import type { OrgId, ProjectId, TenantId, UserId } from '@kindgi/types';
+
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+
+export interface MemoryAccessDeps {
+  readonly authorizer?: Authorizer;
+  /** The tenant's projects, to check one by one when the authorizer can't list them. */
+  readonly projects?: Pick<ProjectBinding, 'list'>;
+}
+
+const PROJECT_PAGE = 200;
+
+/** The caller's user id, when the caller is a Kindgi user. */
+function callerUserId(c: Context<AppEnv>): UserId | undefined {
+  const actor = (c.get('principal') as Principal | undefined)?.actor;
+  return actor?.kind === 'user' ? (actor.id as UserId) : undefined;
+}
+
+/** `user:<id>` or `service:<id>`: who did it, for a record. */
+export function callerRef(c: Context<AppEnv>): string {
+  const actor = (c.get('principal') as Principal | undefined)?.actor;
+  if (actor === undefined) return 'service:unknown';
+  return `${actor.kind === 'user' ? 'user' : 'service'}:${actor.id}`;
+}
+
+/** Who asserts a fact the caller writes. */
+export function callerAttribution(c: Context<AppEnv>): {
+  readonly kind: 'user' | 'service';
+  readonly id: string;
+} {
+  const actor = (c.get('principal') as Principal | undefined)?.actor;
+  if (actor === undefined) return { kind: 'service', id: 'unknown' };
+  return { kind: actor.kind === 'user' ? 'user' : 'service', id: actor.id };
+}
+
+async function isTenantAdmin(c: Context<AppEnv>, authorizer: Authorizer): Promise<boolean> {
+  return authorizer.can(c, 'admin', ref('tenant', c.get('tenantId') as unknown as string));
+}
+
+type ProjectRow = { readonly id: ProjectId; readonly orgId?: OrgId };
+
+/** The tenant's projects, every page. */
+async function allProjects(c: Context<AppEnv>, deps: MemoryAccessDeps): Promise<ProjectRow[]> {
+  if (deps.projects === undefined) return [];
+  const tenantId = c.get('tenantId') as TenantId;
+  const all: ProjectRow[] = [];
+  let cursor: Parameters<ProjectBinding['list']>[1]['cursor'];
+  for (;;) {
+    const page = await deps.projects.list(tenantId, {
+      limit: PROJECT_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    all.push(
+      ...page.items.map((p) => ({ id: p.id, ...(p.orgId !== undefined && { orgId: p.orgId }) })),
+    );
+    if (page.nextCursor === undefined) break;
+    cursor = page.nextCursor;
+  }
+  return all;
+}
+
+/**
+ * The projects the caller may `action`, and the orgs whose org-wide facts
+ * it reads: listed by the authorizer (`read` on the org), else the
+ * projects checked one by one and the orgs of those it may read.
+ */
+async function readerContainers(
+  c: Context<AppEnv>,
+  deps: MemoryAccessDeps & { readonly authorizer: Authorizer },
+): Promise<{ readable: ProjectId[]; writable: ProjectId[]; orgs: OrgId[] }> {
+  const { authorizer } = deps;
+  const [readable, writable, orgs] = await Promise.all([
+    authorizer.listObjects?.(c, 'read', 'project'),
+    authorizer.listObjects?.(c, 'write', 'project'),
+    authorizer.listObjects?.(c, 'read', 'org'),
+  ]);
+  if (readable !== undefined && writable !== undefined && orgs !== undefined) {
+    return {
+      readable: readable.map((id) => id as ProjectId),
+      writable: writable.map((id) => id as ProjectId),
+      orgs: orgs.map((id) => id as OrgId),
+    };
+  }
+  const all = await allProjects(c, deps);
+  const projectRef = (p: ProjectRow) => ref('project', p.id as unknown as string);
+  const [canRead, canWrite] = await Promise.all([
+    authorizer.filterByCan(c, 'read', all, projectRef),
+    authorizer.filterByCan(c, 'write', all, projectRef),
+  ]);
+  return {
+    readable: canRead.map((p) => p.id),
+    writable: canWrite.map((p) => p.id),
+    orgs: [...new Set(canRead.flatMap((p) => (p.orgId !== undefined ? [p.orgId] : [])))],
+  };
+}
+
+/** What the caller may read. */
+export async function memoryReadersFor(
+  c: Context<AppEnv>,
+  deps: MemoryAccessDeps,
+): Promise<MemoryReaders> {
+  const { authorizer } = deps;
+  // Without authorization (a development deployment), the one credential reads it all.
+  if (authorizer === undefined) return { all: true };
+  if (await isTenantAdmin(c, authorizer)) return { all: true };
+  const { readable, writable, orgs } = await readerContainers(c, { ...deps, authorizer });
+  const user = callerUserId(c);
+  return {
+    projectIds: readable,
+    orgIds: orgs,
+    ...(user !== undefined && { userIds: [user] }),
+    onBehalfOfProjectIds: writable,
+  };
+}
+
+/**
+ * Why the caller may not write a fact in `scope`, if they may not:
+ *   - a tenant-wide fact needs `admin` on the tenant;
+ *   - an org-wide fact, `admin` on the org;
+ *   - a project's fact (an end user's or a conversation's included),
+ *     `write` on the project;
+ *   - a conversation's fact outside a project, `write` on the conversation;
+ *   - a user's fact, being that user (or a tenant admin).
+ */
+export async function memoryWriteProblem(
+  c: Context<AppEnv>,
+  deps: MemoryAccessDeps,
+  scope: MemoryScope,
+): Promise<string | undefined> {
+  const { authorizer } = deps;
+  if (authorizer === undefined || (await isTenantAdmin(c, authorizer))) return undefined;
+  if (scope.userId !== undefined && scope.userId !== callerUserId(c)) {
+    return "Only that user (or a tenant admin) can write a user's memory.";
+  }
+  if (scope.projectId !== undefined) {
+    return (await authorizer.can(c, 'write', ref('project', scope.projectId as unknown as string)))
+      ? undefined
+      : `Writing memory in project "${scope.projectId as unknown as string}" needs write on it.`;
+  }
+  if (scope.threadId !== undefined) {
+    return (await authorizer.can(
+      c,
+      'write',
+      ref('conversation', scope.threadId as unknown as string),
+    ))
+      ? undefined
+      : `Writing a conversation's memory needs write on conversation "${scope.threadId as unknown as string}".`;
+  }
+  if (scope.orgId !== undefined) {
+    return (await authorizer.can(c, 'admin', ref('org', scope.orgId as unknown as string)))
+      ? undefined
+      : `Writing org-wide memory needs admin on org "${scope.orgId as unknown as string}".`;
+  }
+  if (scope.userId !== undefined) return undefined;
+  return 'Writing tenant-wide memory needs admin on the tenant.';
+}

package/src/routes/memory-erasures.ts

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Context, Hono } from 'hono';
+
+import { ref } from '@kindgi/authz';
+import type { TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type {
+  MemoryErasureBinding,
+  MemoryErasureLedgerEntry,
+  MemoryErasureSelector,
+  MemoryErasureSelectorKind,
+} from '../memory-erasure-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+import { callerRef } from './memory-access.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Erasing a person's words (T273 M-5):
+ *
+ *   - `POST /v1/memory/erasures`          start one (202); `409 legal-hold`
+ *                                         when a fact it reaches is held
+ *   - `GET  /v1/memory/erasures`          newest first, in pages
+ *   - `GET  /v1/memory/erasures/export`   the whole ledger, content-free,
+ *                                         to keep off-box
+ *   - `GET  /v1/memory/erasures/:id`      one, and how far it got
+ *   - `POST /v1/memory/erasures/:id/resume`  try again now; `force`: stop
+ *                                         waiting for a shared flow's run
+ *   - `POST /v1/memory/erasures/replay`   after a backup restore: the
+ *                                         exported ledger back, its
+ *                                         erasures run again
+ *
+ * PEP: a tenant admin only, for every selector (`admin` on
+ * `tenant:<tenantId>`), as retention; a service account only through an
+ * explicit tenant-admin grant.
+ */
+export function memoryErasuresRouter(
+  binding: MemoryErasureBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  if (authorizer !== undefined) {
+    r.use('/*', async (c, next) => {
+      const tenantId = c.get('tenantId') as TenantId;
+      const mw = authorizer.authorize('admin', async () =>
+        ref('tenant', tenantId as unknown as string),
+      );
+      return mw(c, next);
+    });
+  }
+
+  r.post('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const body = await jsonBody(c);
+    const selector = parseSelector(body);
+    if (typeof selector === 'string') return fail(c, 'bad-input', selector);
+    const outcome = await binding.create({ tenantId, selector, requestedBy: callerRef(c) });
+    if (outcome.kind === 'refused') {
+      const { code, message, factIds } = outcome.refusal;
+      return fail(c, code, message, factIds !== undefined ? { factIds: [...factIds] } : {});
+    }
+    c.status(202);
+    return c.json({
+      ...outcome.erasure,
+      ...(outcome.warnings.length > 0 && { warnings: outcome.warnings }),
+    });
+  });
+
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const cursor = c.req.query('cursor');
+    const page = await binding.list(tenantId, {
+      limit: clampLimit(c.req.query('limit')),
+      ...(cursor !== undefined && cursor !== '' && { cursor }),
+    });
+    if (page === undefined) return fail(c, 'bad-input', '`cursor` is not one this list issued');
+    return c.json({
+      data: page.data,
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+    });
+  });
+
+  r.get('/export', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    return c.json({ data: await binding.exportLedger(tenantId) });
+  });
+
+  r.post('/replay', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const body = await jsonBody(c);
+    const entries = parseLedger(body);
+    if (typeof entries === 'string') return fail(c, 'bad-input', entries);
+    return c.json(await binding.replay(tenantId, entries));
+  });
+
+  r.post('/:erasureId/resume', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const id = c.req.param('erasureId');
+    const body = (await jsonBody(c)) ?? {};
+    const force = (body as { force?: unknown }).force;
+    if (
+      typeof body !== 'object' ||
+      Array.isArray(body) ||
+      (force !== undefined && typeof force !== 'boolean')
+    ) {
+      return fail(c, 'bad-input', 'The body is `{force?: boolean}`');
+    }
+    const erasure = UUID.test(id)
+      ? await binding.resume(tenantId, id, { ...(force === true && { force: true }) })
+      : undefined;
+    if (erasure === undefined) return fail(c, 'not-found', `No erasure ${id}`);
+    return c.json(erasure);
+  });
+
+  r.get('/:erasureId', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const id = c.req.param('erasureId');
+    const erasure = UUID.test(id) ? await binding.get(tenantId, id) : undefined;
+    if (erasure === undefined) return fail(c, 'not-found', `No erasure ${id}`);
+    return c.json(erasure);
+  });
+
+  return r;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SUBJECT_KINDS = ['participant', 'external'] as const;
+const SELECTOR_KINDS: readonly MemoryErasureSelectorKind[] = [
+  'fact',
+  'participant',
+  'external',
+  'conversation',
+];
+const STATUSES = ['pending', 'running', 'waiting-on-run', 'completed', 'failed'] as const;
+const MAX_ID = 256;
+const MAX_LEDGER = 10_000;
+
+function fail(
+  c: Context<AppEnv>,
+  code: string,
+  message: string,
+  extra: Readonly<Record<string, unknown>> = {},
+) {
+  c.status(statusFor(code as never) as never);
+  return c.json(toWireError({ code, message, ...extra }, c.get('requestId')));
+}
+
+async function jsonBody(c: Context<AppEnv>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return undefined;
+  }
+}
+
+const isId = (v: unknown): v is string =>
+  typeof v === 'string' && v.trim() !== '' && v.length <= MAX_ID;
+
+/** Exactly one of `factId`, `subject` or `conversationId`; or why not. */
+function parseSelector(body: unknown): MemoryErasureSelector | string {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return 'The body must be an object naming one of `factId`, `subject` or `conversationId`';
+  }
+  const b = body as Record<string, unknown>;
+  const named = ['factId', 'subject', 'conversationId'].filter((k) => b[k] !== undefined);
+  if (named.length !== 1) {
+    return 'Name exactly one of `factId`, `subject` (`{kind, id}`) or `conversationId`';
+  }
+  const unknown = Object.keys(b).filter(
+    (k) => !['factId', 'subject', 'conversationId'].includes(k),
+  );
+  if (unknown.length > 0) return `Unknown field \`${unknown[0]}\``;
+  if (b.factId !== undefined) {
+    return isId(b.factId) ? { factId: b.factId } : '`factId` must be a non-empty string';
+  }
+  if (b.conversationId !== undefined) {
+    return isId(b.conversationId)
+      ? { conversationId: b.conversationId }
+      : '`conversationId` must be a non-empty string';
+  }
+  const s = b.subject as { kind?: unknown; id?: unknown } | null;
+  if (s === null || typeof s !== 'object') return '`subject` must be `{kind, id}`';
+  if (s.kind === 'user') {
+    return "Erasing a Kindgi user isn't offered: `subject.kind` must be `participant` (an app's end user) or `external`";
+  }
+  if (!SUBJECT_KINDS.includes(s.kind as (typeof SUBJECT_KINDS)[number])) {
+    return '`subject.kind` must be `participant` or `external`';
+  }
+  if (!isId(s.id)) return '`subject.id` must be a non-empty string';
+  return { subject: { kind: s.kind as (typeof SUBJECT_KINDS)[number], id: s.id } };
+}
+
+/** `{erasures: MemoryErasureLedgerEntry[]}`, as `GET /export` gave it; or why not. */
+function parseLedger(body: unknown): MemoryErasureLedgerEntry[] | string {
+  const list = (body as { erasures?: unknown } | null)?.erasures;
+  if (!Array.isArray(list)) return 'The body must be `{erasures: [...]}`, as the export gave them';
+  if (list.length > MAX_LEDGER) return `At most ${MAX_LEDGER} erasures per replay`;
+  const out: MemoryErasureLedgerEntry[] = [];
+  for (const [i, raw] of list.entries()) {
+    const e = raw as Record<string, unknown> | null;
+    const at = `erasures[${i}]`;
+    if (e === null || typeof e !== 'object') return `${at} must be an object`;
+    if (typeof e.id !== 'string' || !UUID.test(e.id)) return `${at}.id must be a uuid`;
+    if (!SELECTOR_KINDS.includes(e.selectorKind as MemoryErasureSelectorKind)) {
+      return `${at}.selectorKind must be one of ${SELECTOR_KINDS.join(', ')}`;
+    }
+    if (
+      e.selectorHmac !== undefined &&
+      (typeof e.selectorHmac !== 'string' || !/^[0-9a-f]{64}$/.test(e.selectorHmac))
+    ) {
+      return `${at}.selectorHmac must be 64 hex characters`;
+    }
+    if (e.keyId !== undefined && !isId(e.keyId)) return `${at}.keyId must be a string`;
+    if (!isId(e.requestedBy)) return `${at}.requestedBy must be a string`;
+    if (!STATUSES.includes(e.status as (typeof STATUSES)[number])) {
+      return `${at}.status must be one of ${STATUSES.join(', ')}`;
+    }
+    for (const k of ['createdAt', 'completedAt'] as const) {
+      const v = e[k];
+      if (v === undefined && k === 'completedAt') continue;
+      if (typeof v !== 'string' || Number.isNaN(Date.parse(v))) return `${at}.${k} must be a time`;
+    }
+    out.push({
+      id: e.id,
+      selectorKind: e.selectorKind as MemoryErasureSelectorKind,
+      ...(typeof e.selectorHmac === 'string' && { selectorHmac: e.selectorHmac }),
+      ...(typeof e.keyId === 'string' && { keyId: e.keyId }),
+      requestedBy: e.requestedBy as string,
+      status: e.status as (typeof STATUSES)[number],
+      createdAt: e.createdAt as string,
+      ...(typeof e.completedAt === 'string' && { completedAt: e.completedAt }),
+    });
+  }
+  return out;
+}

package/src/routes/memory-parse.ts

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/** Request parsing for `/v1/memory`: fact writes, supersedes, retrieve intents and query values. */
+
+import type { FactSubject, MemoryScope, Retention } from '@kindgi/memory';
+import type { Timestamp } from '@kindgi/types';
+
+import type { MemoryRetrieveIntent } from '../memory-binding.js';
+
+export type ValidationResult<T> =
+  | { readonly kind: 'ok'; readonly value: T }
+  | { readonly kind: 'err'; readonly message: string };
+
+const ok = <T>(value: T): ValidationResult<T> => ({ kind: 'ok', value });
+const err = <T>(message: string): ValidationResult<T> => ({ kind: 'err', message });
+
+const MAX_SUBJECTS = 20;
+
+export function parseScopeParam(raw: string): Partial<MemoryScope> | null {
+  try {
+    const decoded = JSON.parse(raw) as unknown;
+    if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) return null;
+    return decoded as Partial<MemoryScope>;
+  } catch {
+    return null;
+  }
+}
+
+/** An ISO 8601 time, as a query value or a body field. */
+export function parseTime(raw: unknown, field: string): ValidationResult<Timestamp | undefined> {
+  if (raw === undefined) return ok(undefined);
+  if (typeof raw !== 'string' || Number.isNaN(Date.parse(raw))) {
+    return err(`\`${field}\` must be an ISO 8601 time`);
+  }
+  return ok(new Date(raw).toISOString() as Timestamp);
+}
+
+/** A revision number: a whole number of 1 or more. */
+export function parseVersion(raw: unknown, field: string): ValidationResult<number | undefined> {
+  if (raw === undefined) return ok(undefined);
+  const n = typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : raw;
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+    return err(`\`${field}\` must be a revision number (1 or more)`);
+  }
+  return ok(n);
+}
+
+function parseScope(raw: unknown): ValidationResult<MemoryScope> {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return err('Field `scope` must be an object');
+  }
+  const scope = raw as Record<string, unknown>;
+  if (typeof scope.tenantId !== 'string') return err('Field `scope.tenantId` must be a string');
+  if (
+    scope.participantId !== undefined &&
+    (typeof scope.participantId !== 'string' || scope.participantId.length === 0)
+  ) {
+    return err('Field `scope.participantId` must be a non-empty string');
+  }
+  if (scope.participantId !== undefined && scope.projectId === undefined) {
+    return err(
+      "`scope.participantId` needs `scope.projectId`: an app's end users belong to a project",
+    );
+  }
+  return ok(scope as unknown as MemoryScope);
+}
+
+function parseRetention(raw: unknown): ValidationResult<Retention | undefined> {
+  if (raw === undefined) return ok(undefined);
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return err('Field `retention` must be an object when present');
+  }
+  const r = raw as Record<string, unknown>;
+  const keepUntil = parseTime(r.keepUntil, 'retention.keepUntil');
+  if (keepUntil.kind === 'err') return keepUntil;
+  if (
+    r.keepDays !== undefined &&
+    (typeof r.keepDays !== 'number' || !Number.isInteger(r.keepDays) || r.keepDays < 1)
+  ) {
+    return err('`retention.keepDays` must be a whole number of days (1 or more)');
+  }
+  if (r.legalHold !== undefined && typeof r.legalHold !== 'boolean') {
+    return err('`retention.legalHold` must be true or false');
+  }
+  return ok(r as Retention);
+}
+
+function parseSubjects(raw: unknown): ValidationResult<readonly FactSubject[] | undefined> {
+  if (raw === undefined) return ok(undefined);
+  const shape =
+    "Field `subjects` is a list of whom the fact is about: [{ kind: 'participant' | 'user' | 'external', id }]";
+  if (!Array.isArray(raw) || raw.length > MAX_SUBJECTS) {
+    return err(`${shape}, at most ${MAX_SUBJECTS}`);
+  }
+  for (const s of raw) {
+    const o = s as Record<string, unknown> | null;
+    if (
+      o === null ||
+      typeof o !== 'object' ||
+      !['participant', 'user', 'external'].includes(o.kind as string) ||
+      typeof o.id !== 'string' ||
+      o.id.length === 0 ||
+      Object.keys(o).length !== 2
+    ) {
+      return err(shape);
+    }
+  }
+  return ok(raw as FactSubject[]);
+}
+
+/** The fields a write and a supersede share: retention, subjects and the times. */
+export interface ValidatedFactFields {
+  readonly retention?: Retention;
+  readonly subjects?: readonly FactSubject[];
+  readonly validFrom?: Timestamp;
+  readonly validUntil?: Timestamp;
+  readonly observedAt?: Timestamp;
+}
+
+function parseFactFields(body: Record<string, unknown>): ValidationResult<ValidatedFactFields> {
+  const retention = parseRetention(body.retention);
+  if (retention.kind === 'err') return retention;
+  const subjects = parseSubjects(body.subjects);
+  if (subjects.kind === 'err') return subjects;
+  const times: Record<string, Timestamp> = {};
+  for (const field of ['validFrom', 'validUntil', 'observedAt'] as const) {
+    const t = parseTime(body[field], field);
+    if (t.kind === 'err') return t;
+    if (t.value !== undefined) times[field] = t.value;
+  }
+  if (
+    times.validFrom !== undefined &&
+    times.validUntil !== undefined &&
+    times.validFrom > times.validUntil
+  ) {
+    return err('`validFrom` must not be after `validUntil`');
+  }
+  return ok({
+    ...(retention.value !== undefined && { retention: retention.value }),
+    ...(subjects.value !== undefined && { subjects: subjects.value }),
+    ...times,
+  });
+}
+
+export interface ValidatedWriteFactBody extends ValidatedFactFields {
+  readonly type: string;
+  readonly scope: MemoryScope;
+  readonly content: unknown;
+  readonly contentHash?: string;
+}
+
+export function validateWriteFactBody(
+  body: Record<string, unknown>,
+): ValidationResult<ValidatedWriteFactBody> {
+  const type = body.type;
+  if (typeof type !== 'string' || type.length === 0) {
+    return err('Field `type` must be a non-empty string');
+  }
+  const scope = parseScope(body.scope);
+  if (scope.kind === 'err') return scope;
+  if (!('content' in body)) return err('Field `content` is required');
+  const rawContentHash = body.contentHash;
+  if (
+    rawContentHash !== undefined &&
+    (typeof rawContentHash !== 'string' || rawContentHash.length === 0)
+  ) {
+    return err('Field `contentHash` must be a non-empty string when present');
+  }
+  const fields = parseFactFields(body);
+  if (fields.kind === 'err') return fields;
+  return ok({
+    type,
+    scope: scope.value,
+    content: body.content,
+    ...(typeof rawContentHash === 'string' && { contentHash: rawContentHash }),
+    ...fields.value,
+  });
+}
+
+export interface ValidatedSupersedeBody extends ValidatedFactFields {
+  readonly content: unknown;
+  readonly expectVersion?: number;
+}
+
+export function validateSupersedeBody(
+  body: Record<string, unknown>,
+): ValidationResult<ValidatedSupersedeBody> {
+  if (!('content' in body)) {
+    return err("Field `content` is required: the fact's next revision");
+  }
+  const expectVersion = parseVersion(body.expectVersion, 'expectVersion');
+  if (expectVersion.kind === 'err') return expectVersion;
+  const fields = parseFactFields(body);
+  if (fields.kind === 'err') return fields;
+  return ok({
+    content: body.content,
+    ...(expectVersion.value !== undefined && { expectVersion: expectVersion.value }),
+    ...fields.value,
+  });
+}
+
+export function validateRetrieveIntent(
+  body: Record<string, unknown>,
+): ValidationResult<MemoryRetrieveIntent> {
+  const mode = body.mode;
+  if (mode !== 'list' && mode !== 'keyword' && mode !== 'semantic' && mode !== 'both') {
+    return err('Field `mode` must be one of "list", "keyword", "semantic", "both"');
+  }
+  const rawQuery = body.query;
+  if (rawQuery !== undefined && typeof rawQuery !== 'string') {
+    return err('Field `query` must be a string when present');
+  }
+  if ((mode === 'keyword' || mode === 'semantic' || mode === 'both') && rawQuery === undefined) {
+    return err(`Field \`query\` is required when \`mode\` is "${mode}"`);
+  }
+  const rawType = body.type;
+  if (rawType !== undefined && (typeof rawType !== 'string' || rawType.length === 0)) {
+    return err('Field `type` must be a non-empty string when present');
+  }
+  const rawScope = body.scope;
+  if (
+    rawScope !== undefined &&
+    (rawScope === null || typeof rawScope !== 'object' || Array.isArray(rawScope))
+  ) {
+    return err('Field `scope` must be an object when present');
+  }
+  const rawLimit = body.limit;
+  if (
+    rawLimit !== undefined &&
+    (typeof rawLimit !== 'number' || !Number.isFinite(rawLimit) || rawLimit < 1)
+  ) {
+    return err('Field `limit` must be a positive number when present');
+  }
+  const rawEmbeddingModel = body.embeddingModel;
+  if (
+    rawEmbeddingModel !== undefined &&
+    (typeof rawEmbeddingModel !== 'string' || rawEmbeddingModel.length === 0)
+  ) {
+    return err('Field `embeddingModel` must be a non-empty string when present');
+  }
+  return ok({
+    mode,
+    ...(typeof rawQuery === 'string' && { query: rawQuery }),
+    ...(typeof rawType === 'string' && { type: rawType }),
+    ...(rawScope !== undefined && { scope: rawScope as Partial<MemoryScope> }),
+    ...(typeof rawLimit === 'number' && { limit: Math.floor(rawLimit) }),
+    ...(typeof rawEmbeddingModel === 'string' && { embeddingModel: rawEmbeddingModel }),
+  });
+}