Mount retention routes: forget, purge, retention-class (CL-6288)

POST …/memory/documents/:documentId/forget (grant memory:forget) tombstones;
POST …/memory/documents/:documentId/purge (grant memory:purge) hard-deletes;
POST …/memory/versions/:versionId/retention-class (grant memory:forget) sets
retention class. Separate routes and separate grant actions for tombstone vs
hard delete — never a single route toggled by a boolean a client could get
wrong. Path/body validated with arktype (DocumentIdParam, VersionIdParam,
ForgetRequest, SetRetentionClassRequest); ownership refusal from the plane
surfaces as 403, an unknown document/version as 404.

sweepEphemeral gets no route — it is a tenant-wide maintenance sweep, not a
per-caller action, and has no natural ownership check; a host schedules it
on its own cron against the in-process Memory (docs/RETENTION.md).

Author: TheGreatAxios

src/http-bodies.ts

@@ -152,3 +152,31 @@ export function parseWithArk<T>(
   }
   return parsed;
 }
+
+/** Path param for the two document-scoped retention routes (forget/purge). */
+export const DocumentIdParam = type({
+  documentId: "string >= 1",
+});
+
+export type DocumentIdParam = typeof DocumentIdParam.infer;
+
+/** Path param for the version-scoped retention-class route. */
+export const VersionIdParam = type({
+  versionId: "string >= 1",
+});
+
+export type VersionIdParam = typeof VersionIdParam.infer;
+
+/** POST body for `.../forget` (tombstone) — reason is audit-only, never required. */
+export const ForgetRequest = type({
+  "reason?": "string",
+});
+
+export type ForgetRequest = typeof ForgetRequest.infer;
+
+/** POST body for `.../retention-class`. Kept in lockstep with RETENTION_CLASSES (core/enums.ts). */
+export const SetRetentionClassRequest = type({
+  retention_class: "'durable'|'standard'|'ephemeral'|'source_only'",
+});
+
+export type SetRetentionClassRequest = typeof SetRetentionClassRequest.infer;

src/routes/mount.ts

@@ -18,6 +18,11 @@ import { mountAddRoute } from "./add.ts";
 import { mountSearchRoute } from "./search.ts";
 import { mountListRoute } from "./list.ts";
 import { mountFeedRoute } from "./feed.ts";
+import {
+  mountForgetRoute,
+  mountPurgeRoute,
+  mountSetRetentionClassRoute,
+} from "./retention.ts";
 
 export type {
   CallerResolver,
@@ -26,7 +31,7 @@ export type {
   RouteDeps,
 } from "./deps.ts";
 
-/** HTTP JSON routes: add, search, list, feed. */
+/** HTTP JSON routes: add, search, list, feed, forget, purge, retention-class. */
 export function registerMemoryRoutes(
   app: Hono<TenantEnv>,
   deps: RouteDeps,
@@ -35,4 +40,7 @@ export function registerMemoryRoutes(
   mountSearchRoute(app, deps);
   mountListRoute(app, deps);
   mountFeedRoute(app, deps);
+  mountForgetRoute(app, deps);
+  mountPurgeRoute(app, deps);
+  mountSetRetentionClassRoute(app, deps);
 }

src/routes/retention.ts

@@ -0,0 +1,215 @@
+/**
+ * Retention HTTP routes (CL-6288): forget (tombstone), purge (hard delete),
+ * and set-retention-class. See docs/RETENTION.md.
+ *
+ * Tombstone and hard delete are deliberately separate routes with separate
+ * grant actions (`forget` vs `purge`) — never one route with a boolean flag
+ * a client could flip by accident. `purge` is the one that actually removes
+ * data; its path and grant name say so.
+ *
+ * `sweepEphemeral` has no route here — it is a maintenance sweep a host
+ * schedules on its own cron, not a user action (see docs/RETENTION.md).
+ */
+import type { Hono } from "hono";
+import type { TenantEnv } from "@intx/hub-api";
+import { describeRoute, resolver, validator } from "hono-openapi";
+import { type } from "arktype";
+
+import { formatCaughtError, log } from "../log.ts";
+import {
+  DocumentIdParam,
+  ForgetRequest,
+  SetRetentionClassRequest,
+  VersionIdParam,
+} from "../http-bodies.ts";
+import { MemoryError } from "../memory.ts";
+import type { RouteDeps } from "./deps.ts";
+import {
+  caller,
+  grantGuard,
+  requirePrincipal,
+  resolveCaller,
+} from "./deps.ts";
+
+function respondRetentionError(err: unknown, action: string) {
+  const errMessage = formatCaughtError(err);
+  log.error(`memory ${action} failed: ${errMessage}`, { error: errMessage });
+  if (err instanceof MemoryError) {
+    return { body: { error: err.message }, status: err.status as 403 | 404 | 501 };
+  }
+  return { body: { error: `${action} failed` }, status: 502 as const };
+}
+
+const ForgetResponse = type({
+  documentId: "string",
+  versions: "number",
+});
+
+const PurgeResponse = type({
+  documentId: "string",
+  deleted: "boolean",
+  "reason?": "string",
+});
+
+const RetentionClassResponse = type({
+  versionId: "string",
+  documentId: "string",
+  status: "string",
+});
+
+export function mountForgetRoute(app: Hono<TenantEnv>, deps: RouteDeps): void {
+  app.post(
+    "/api/tenants/:tenantId/memory/documents/:documentId/forget",
+
+    describeRoute({
+      tags: ["memory"],
+      summary: "Tombstone a document (reversible in principle: row stays for audit, chunk text redacted)",
+      responses: {
+        200: {
+          description: "Tombstoned",
+          content: { "application/json": { schema: resolver(ForgetResponse) } },
+        },
+        401: { description: "No principal on the request context" },
+        403: {
+          description:
+            "Missing the memory:forget grant, or caller is not the document's creator",
+        },
+        404: { description: "Document not found" },
+        502: { description: "forget failed" },
+      },
+    }),
+    resolveCaller(deps),
+    requirePrincipal(),
+    grantGuard(deps, "forget"),
+    validator("param", DocumentIdParam),
+    validator("json", ForgetRequest),
+    async (c) => {
+      const { documentId } = c.req.valid("param");
+      const { reason } = c.req.valid("json");
+      const { scopeId, subjectId } = caller(c);
+      if (!deps.memory.tombstoneDocument) {
+        return c.json({ error: "retention APIs require the engine DocumentStore" }, 501);
+      }
+      try {
+        const result = await deps.memory.tombstoneDocument({
+          tenantId: scopeId,
+          principalId: subjectId,
+          documentId,
+          ...(reason !== undefined ? { reason } : {}),
+        });
+        return c.json({ documentId, versions: result.versions });
+      } catch (err) {
+        const { body, status } = respondRetentionError(err, "forget");
+        return c.json(body, status);
+      }
+    },
+  );
+}
+
+export function mountPurgeRoute(app: Hono<TenantEnv>, deps: RouteDeps): void {
+  app.post(
+    "/api/tenants/:tenantId/memory/documents/:documentId/purge",
+
+    describeRoute({
+      tags: ["memory"],
+      summary: "Hard-delete a document — irreversible; refused while a durable version is untombstoned",
+      responses: {
+        200: {
+          description: "Deletion result (deleted may be false with a reason)",
+          content: { "application/json": { schema: resolver(PurgeResponse) } },
+        },
+        401: { description: "No principal on the request context" },
+        403: {
+          description:
+            "Missing the memory:purge grant, or caller is not the document's creator",
+        },
+        404: { description: "Document not found" },
+        502: { description: "purge failed" },
+      },
+    }),
+    resolveCaller(deps),
+    requirePrincipal(),
+    grantGuard(deps, "purge"),
+    validator("param", DocumentIdParam),
+    async (c) => {
+      const { documentId } = c.req.valid("param");
+      const { scopeId, subjectId } = caller(c);
+      if (!deps.memory.hardDeleteDocument) {
+        return c.json({ error: "retention APIs require the engine DocumentStore" }, 501);
+      }
+      try {
+        const result = await deps.memory.hardDeleteDocument({
+          tenantId: scopeId,
+          principalId: subjectId,
+          documentId,
+        });
+        return c.json({
+          documentId,
+          deleted: result.deleted,
+          ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        });
+      } catch (err) {
+        const { body, status } = respondRetentionError(err, "purge");
+        return c.json(body, status);
+      }
+    },
+  );
+}
+
+export function mountSetRetentionClassRoute(
+  app: Hono<TenantEnv>,
+  deps: RouteDeps,
+): void {
+  app.post(
+    "/api/tenants/:tenantId/memory/versions/:versionId/retention-class",
+
+    describeRoute({
+      tags: ["memory"],
+      summary: "Set a version's retention class (durable/standard/ephemeral/source_only)",
+      responses: {
+        200: {
+          description: "Updated",
+          content: {
+            "application/json": { schema: resolver(RetentionClassResponse) },
+          },
+        },
+        400: { description: "Invalid retention_class" },
+        401: { description: "No principal on the request context" },
+        403: {
+          description:
+            "Missing the memory:forget grant, or caller is not the version's creator",
+        },
+        404: { description: "Version not found" },
+        502: { description: "retention-class update failed" },
+      },
+    }),
+    resolveCaller(deps),
+    requirePrincipal(),
+    grantGuard(deps, "forget"),
+    validator("param", VersionIdParam),
+    validator("json", SetRetentionClassRequest),
+    async (c) => {
+      const { versionId } = c.req.valid("param");
+      const { retention_class } = c.req.valid("json");
+      const { scopeId, subjectId } = caller(c);
+      if (!deps.memory.setRetentionClass) {
+        return c.json({ error: "retention APIs require the engine DocumentStore" }, 501);
+      }
+      try {
+        const result = await deps.memory.setRetentionClass({
+          tenantId: scopeId,
+          principalId: subjectId,
+          versionId,
+          retentionClass: retention_class,
+        });
+        if (!result) {
+          return c.json({ error: "version not found" }, 404);
+        }
+        return c.json(result);
+      } catch (err) {
+        const { body, status } = respondRetentionError(err, "retention-class");
+        return c.json(body, status);
+      }
+    },
+  );
+}