Update docs: retention HTTP routes (CL-6288)

AGENTS.md/ARCHITECTURE.md route lists, docs/RETENTION.md (route table,
grant actions, ownership gate, sweepEphemeral decision), and CHANGELOG.

Author: TheGreatAxios

AGENTS.md

@@ -22,7 +22,8 @@ CI runs `typecheck` + `test` — both must pass before any push.
 - `src/index.ts` — public surface: `createMemory` (optional `app` registers HTTP), `registerMemoryRoutes`
 
 - `src/mount-config.ts` / `src/config.ts` — mount config + engine config
-- `src/routes/` — Hono routes (`add`, `search`, `list`)
+- `src/routes/` — Hono routes (`add`, `search`, `list`, `feed`, retention
+  `forget`/`purge`/`retention-class`)
 - `src/tools/` — Interchange `defineTool` factories (`@corbits/memory/tools`);
   HTTP clients for mounted routes (env credentials; no in-process plane)
 - `src/services/` — capture / search / transform internals (not public verbs)

ARCHITECTURE.md

@@ -85,9 +85,23 @@ exposes the same three verbs.
   authority/recency → MMR); optional live `SourceProvider` merge (fail-soft).
 - `GET /api/tenants/:tenantId/memory/list` — recent documents, same grant-tag filter as local
   search.
-
-Returns an in-process `Memory` (`add`, `search`, `list`, `close`) for host
-workers and ingestion modules that already resolved identity.
+- `POST /api/tenants/:tenantId/memory/documents/:documentId/forget` — tombstone
+  (grant `memory:forget`; creator-only, see below).
+- `POST /api/tenants/:tenantId/memory/documents/:documentId/purge` — hard
+  delete (grant `memory:purge`; creator-only; irreversible).
+- `POST /api/tenants/:tenantId/memory/versions/:versionId/retention-class` —
+  set retention class (grant `memory:forget`; creator-only).
+
+Forget and purge are deliberately separate routes and separate grant actions
+(never one route with a boolean flag) — a host wiring a "forget this" button
+cannot accidentally wire up permanent deletion. `sweepEphemeral` (TTL
+auto-deprecation) is **not** HTTP-routed: it is a maintenance sweep a host
+schedules on its own cron, not a user action; call it in-process against the
+returned `Memory`. See docs/RETENTION.md.
+
+Returns an in-process `Memory` (`add`, `search`, `list`, `close`, plus the
+optional retention writes) for host workers and ingestion modules that
+already resolved identity.
 
 **Agent tools live in this package** as thin HTTP clients
 (`@corbits/memory/tools` / `interchange.tools`): `defineTool` factories that

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Retention HTTP routes (CL-6288): `POST …/memory/documents/:documentId/forget`
+  (tombstone, grant `memory:forget`), `POST …/memory/documents/:documentId/purge`
+  (hard delete, grant `memory:purge`), and
+  `POST …/memory/versions/:versionId/retention-class` (grant `memory:forget`).
+  Forget and purge are separate routes with separate grant actions — never one
+  route with a boolean flag — and both are refused with 403 unless the caller
+  is the document/version's creator, independent of any share grant that lets
+  them merely see it. `sweepEphemeral` stays off the HTTP surface (maintenance
+  sweep, not a user action); a host schedules it on its own cron against the
+  in-process `Memory`. New `memory:forget` / `memory:purge` grant requirements
+  (`source: "creator"`) and `capabilityIdsForSurface()` so distiller/tools
+  installs no longer pick up routes-only capabilities by accident.
 - `RouteDeps.callerResolver` / `createMemory({ callerResolver })` — an
   optional host-supplied resolver from a request to a `{ tenantId,
   principalId }` scope, for a caller that never goes through the host's

docs/RETENTION.md

@@ -30,3 +30,39 @@ versions intentionally (ops / audit). Hard-delete is a separate explicit
 verb — TTL never hard-deletes.
 
 Service module: `src/services/retention.ts`.
+
+## HTTP surface (CL-6288)
+
+| Route | Grant action | Plane verb |
+| --- | --- | --- |
+| `POST …/memory/documents/:documentId/forget` | `memory:forget` | `tombstoneDocument` |
+| `POST …/memory/documents/:documentId/purge` | `memory:purge` | `hardDeleteDocument` |
+| `POST …/memory/versions/:versionId/retention-class` | `memory:forget` | `setRetentionClass` |
+
+`deprecateVersion` and `sweepEphemeral` have no route (see below).
+
+**Tombstone vs. hard delete stay distinct verbs, distinct grants.** A UI
+offering "forget this" must never be one flag away from "shred this" by
+accident. `forget` (tombstone) is the reversible-in-principle, audit-keeping
+action; `purge` (hard delete) is the one that actually removes the row, has
+its own grant action, and is refused outright while a `durable`-class version
+on the document is untombstoned. A host can grant `forget` broadly (every
+user gets a "forget this" button) while keeping `purge` to an operator role.
+
+**Ownership, not just visibility.** `memory:search`/a document's `accessTags`
+say who can *see* a document — never who may forget or purge it. Every
+retention route additionally checks that the caller is the document's
+creator (`created_by_principal_id` — the document's first version for
+`forget`/`purge`, the specific version's own creator for `retention-class`),
+independent of any share grant. A peer who can search a shared document gets
+403 on `forget`/`purge`/`retention-class` for it. See
+`src/services/retention-ownership.ts` and the ownership tests in
+`src/memory.test.ts` / `src/routes/routes.test.ts`.
+
+**`sweepEphemeral` stays off the HTTP surface.** It is a maintenance sweep —
+"deprecate every ephemeral version past its TTL for this tenant" — not
+something a single user requests about their own data, and it has no natural
+per-caller grant (it does not take a `principalId` and touches every
+matching row tenant-wide). A host that wants it schedules a cron job calling
+`memory.sweepEphemeral({ tenantId })` in-process (the returned `Memory`
+already exposes it); the engine stays cron-free per `ARCHITECTURE.md`.