@synap-core/sdk 1.3.0 → 1.5.0

package/src/public/share-model.ts

@@ -8,7 +8,7 @@
  * is honest (a network blip) — it never says anything about the token.
  */
 import type { PublicReadError, PublicResult, PublicShare } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 import { formatPublicValue, type FormatOptions } from "./site-model";
 
 export const UNAVAILABLE_TITLE = "This link isn't available";
@@ -20,7 +20,10 @@ export type SharePageModel =
       title: string | null;
       /** Property rows exactly as the publisher allowlisted them. */
       properties: Array<{ key: string; value: string }>;
+      /** A markdown body as safe blocks (`[]` for an html body or none). */
       blocks: Block[];
+      /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+      html: string | null;
       publishedOn: string;
     };
 
@@ -41,7 +44,8 @@ export function toSharePageModel(
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: share.body ? parseSafeMarkdown(share.body.content) : [],
+    ...bodyOf(share.body),
     publishedOn: share.publishedOn,
   };
 }
+

package/src/public/site-model.ts

@@ -14,7 +14,7 @@ import {
   type PublicRecordSummary,
   type PublicValue,
 } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 
 export interface FormatOptions {
   /** BCP 47 locale (default `en`). */
@@ -197,8 +197,10 @@ export interface RecordViewModel {
   slug: string | null;
   /** Rows exactly as the publisher allowlisted them, formatted. */
   properties: Array<{ key: string; value: string }>;
-  /** The body as safe blocks (never HTML). */
+  /** A markdown body as safe blocks (`[]` for an html body or none). */
   blocks: Block[];
+  /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+  html: string | null;
   publishedOn: string;
 }
 
@@ -211,7 +213,7 @@ export function toRecordViewModel(record: PublicRecord, opts: FormatOptions = {}
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: record.body ? parseSafeMarkdown(record.body.content) : [],
+    ...bodyOf(record.body),
     publishedOn: record.publishedOn,
   };
 }

package/src/testing/auth-server.ts

@@ -8,22 +8,47 @@
  * Wire behaviour mirrors synap-backend `routers/oauth/routes.ts` for a CIMD
  * client: `iss` on every authorization answer (RFC 9207), PKCE S256 checked at
  * /token, single-use codes bound to client_id + redirect_uri + resource, the
- * token response's `synap_grant` / `synap_user`. Refresh mirrors PB3
+ * token response's `synap_grant` / `synap_user`. Refresh mirrors the pod's
  * (`routers/oauth/refresh.ts`): rotating and single-use, 30 days from issue;
  * a token presented AGAIN after its use is a reuse that revokes its whole
  * family AND the live access key; a new code ends the client's older
  * families; /revoke with a refresh token kills its family and access key.
- * `refresh: false` is a pod before PB3 (no refresh_token at all).
+ * The reuse grace: within 30 s of its use, a spent token presented
+ * again with its own client_id gets the SAME pair its first use got (the
+ * successor refresh token and the live key, `expires_in` = what that key has
+ * left), as long as the successor is unused; past it, a reuse.
+ * `refresh: false` is a pod without refresh tokens (no refresh_token at all).
+ *
+ * Hub REST: `GET /users/me`, `GET /entities` (an ARRAY of entities, as the pod
+ * answers; the seeds plus what applied writes created), `GET /proposals`
+ * (`{ proposals, limit, offset, total, hasMore }`, rows only in spaces where
+ * the token holds `proposal.read`, as the pod's grant clause; `proposalIds`),
+ * governed writes. 1.5, from `seed` (one JSON shape, ./seed.ts):
+ * `GET /entities/:id` (404 with an empty body, as the pod), `GET
+ * /entities/:id/connections` (`{ connections, counts }`: seeded relations and
+ * the sessions about it), `GET /documents/:id` (`{ document }`), `GET
+ * /focus-sessions` (an ARRAY; `workspaceId` or `projectId` required; status,
+ * limit 1-50, lens, kind, subjectEntityId), `POST /proposals/:id/approve`.
+ *
+ * Who the token acts as: `actsAs: "person"` answers
+ * `synap_acts_as: "person"`, applies writes directly (unless `writeMode`
+ * says otherwise) and lets the token approve where it holds
+ * `proposal.approve`; `"agent"` answers `"agent"`; omitted, the field is not
+ * sent (a pod that does not name it) and the token is an agent's. An agent's approve is
+ * refused 403, as the pod's `rejectAgentReviewer`.
  *
  *   mock.authorize(authorizeUrl)                  → the callback URL (approved)
  *   mock.authorize(authorizeUrl, { deny: true })  → error=access_denied
  *   mock.authorize(authorizeUrl, { iss: "https://evil.example" })  → a mix-up attempt
- *   mock.loseNextRefreshRace()                    → the next redeem is a concurrent loser (refused, no revoke)
- *   mock.consumeRefreshToken(t)                   → the token was used elsewhere (presenting it is a reuse)
+ *   mock.loseNextRefreshRace()                    → the next redeem is a concurrent loser that found no successor (refused, no revoke)
+ *   mock.redeemElsewhere(t)                       → another app instance rotated t (presenting it within 30 s gets that pair)
+ *   mock.consumeRefreshToken(t)                   → the token was used elsewhere with no successor (presenting it is a reuse)
  *   mock.revokeAll()                              → the person removed the app in their pod
+ *   mock.revokeAccessKeys()                       → a narrow or a pod-side "Revoke key": the live keys stop, the connection (its refresh token) lives
  */
 import { pkceChallenge, randomToken } from "../connect/encoding";
-import type { PodGrant, PodUser } from "../connect/types";
+import type { PodActsAs, PodGrant, PodUser } from "../connect/types";
+import type { MockPodSeed, MockSeedDocument, MockSeedRelation, MockSeedSession } from "./seed";
 
 /** A placeholder pod origin; never contacted. */
 export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
@@ -39,7 +64,7 @@ export type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" |
 
 export interface MockAuthServerOptions {
   issuer?: string;
-  /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+  /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
   refresh?: boolean;
   /** Default 3600 (the pod's 1 h). */
   accessTtlSec?: number;
@@ -47,12 +72,35 @@ export interface MockAuthServerOptions {
   refreshIdleSec?: number;
   /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
   advertiseRefreshExpiry?: boolean;
+  /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
+  refreshGraceSec?: number;
+  /**
+   * `synap_app` on token responses: the connection's id and its page on the
+   * pod console. Default `MOCK_APP`; null = a pod that does not send it.
+   */
+  app?: { id: string; manageUrl: string | null } | null;
+  /** Entities `GET /entities` answers (with `workspaceId` / `profileSlug` filters). */
+  entities?: Array<Record<string, unknown>>;
   grant?: PodGrant[];
   user?: PodUser;
   /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
   metadata?: Record<string, unknown>;
-  /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+  /**
+   * Hub writes: "proposed" (ask-first, the default for an agent token) or
+   * "applied" (the default for `actsAs: "person"`).
+   */
   writeMode?: "proposed" | "applied";
+  /**
+   * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+   * not name it; the SDK reads an agent connection).
+   */
+  actsAs?: PodActsAs;
+  /**
+   * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+   * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+   * those spaces.
+   */
+  seed?: MockPodSeed;
   /** Hub paths (after /api/hub) that answer one failure. */
   failures?: Record<string, MockHubFailure>;
   now?: () => number;
@@ -76,12 +124,43 @@ export interface AuthorizeDecision {
   state?: string;
 }
 
+/** A proposal a governed write filed (`GET /proposals` lists the pending ones). */
+export interface MockProposal {
+  id: string;
+  proposalType: string;
+  targetType: string;
+  targetId: string | null;
+  status: "pending" | "approved" | "rejected";
+  workspaceId: string | null;
+  createdAt: string;
+  correlationId: string | null;
+  sessionId: string | null;
+  agentUserId: string | null;
+  summary?: string;
+}
+
+/** The connection's `synap_app` the mock pod answers by default (backend `appTokenResponse`). */
+export const MOCK_APP = { id: "app_mock_studio", manageUrl: "https://pod-admin.mock-synap.test/apps/app_mock_studio" };
+
+/** The app's agent on the mock pod: who files its proposals. */
+export const MOCK_APP_AGENT_ID = "agent_mock_app";
+
 export interface MockAuthServer {
   issuer: string;
   fetch: typeof fetch;
   requests: MockAuthRequest[];
   /** Hub writes seen, in order. */
   writes: Array<{ method: string; path: string; body: unknown }>;
+  /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
+  proposals: MockProposal[];
+  /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+  approvals: string[];
+  /** The person approved or rejected one: it leaves the pending list. */
+  settleProposal(id: string, status: "approved" | "rejected"): void;
+  /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
+  redeemElsewhere(token: string): Promise<{ access_token: string; refresh_token: string; expires_in: number }>;
+  /** Refresh redeems answered within the reuse grace (the same pair again). */
+  graceAnswers: number;
   /** Stand-in for the consent screen: validates the request like /authorize, returns where the pod redirects. */
   authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
   /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
@@ -92,6 +171,12 @@ export interface MockAuthServer {
   reuses: number;
   /** The person revoked the app: every token stops working. */
   revokeAll(): void;
+  /**
+   * The live access keys stop working, the refresh tokens do not: what a
+   * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+   * does. The next refresh mints a new key.
+   */
+  revokeAccessKeys(): void;
   /** Live (unrevoked) refresh tokens. */
   liveRefreshTokens(): string[];
   reset(): void;
@@ -109,6 +194,7 @@ interface AccessRow {
   expiresAt: number;
   revoked: boolean;
   family: string | null;
+  scope: string[];
 }
 
 interface RefreshRow {
@@ -118,6 +204,10 @@ interface RefreshRow {
   used: boolean;
   revoked: boolean;
   scope: string[];
+  /** When it was spent, and the pair that use was answered (the grace re-answers it). */
+  usedAt?: number;
+  successor?: string;
+  pairAccess?: string;
 }
 
 function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
@@ -144,7 +234,34 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
   const refreshTokens = new Map<string, RefreshRow>();
   const requests: MockAuthRequest[] = [];
   const writes: Array<{ method: string; path: string; body: unknown }> = [];
+  const proposals: MockProposal[] = [];
+  const seed = options.seed ?? {};
+  const entities: Array<Record<string, unknown>> = [...(seed.entities ?? []), ...(options.entities ?? [])];
+  const sessions: MockSeedSession[] = [...(seed.sessions ?? [])];
+  const documents: MockSeedDocument[] = [...(seed.documents ?? [])];
+  const relations: MockSeedRelation[] = [...(seed.relations ?? [])];
+  const templateOf = new Map((seed.spaces ?? []).filter((sp) => sp.templateSlug).map((sp) => [sp.id, sp.templateSlug!]));
+  const approvals: string[] = [];
+  const seededAt = new Date(now()).toISOString();
+  for (const p of seed.proposals ?? []) {
+    proposals.push({
+      proposalType: "create",
+      targetType: "entity",
+      targetId: null,
+      status: "pending",
+      workspaceId: null,
+      createdAt: seededAt,
+      correlationId: null,
+      sessionId: null,
+      agentUserId: null,
+      ...p,
+    });
+  }
+  const writeMode = options.writeMode ?? (options.actsAs === "person" ? "applied" : "proposed");
+  const graceMs = (options.refreshGraceSec ?? 30) * 1000;
+  const app = options.app === undefined ? MOCK_APP : options.app;
   let proposalSeq = 0;
+  let graceAnswers = 0;
 
   const metadata = (): Record<string, unknown> => {
     const base: Record<string, unknown> = {
@@ -175,18 +292,29 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     for (const a of access.values()) if (a.family === family) a.revoked = true;
   };
 
-  const tokenBody = (scope: string[], clientId: string, family: string) => {
-    const accessToken = `synap_hub_mock_${randomToken()}`;
-    access.set(accessToken, { expiresAt: now() + accessTtl * 1000, revoked: false, family: refresh ? family : null });
+  /** The token response; `pair` re-answers an existing access key + refresh token (the grace). */
+  const tokenBody = (scope: string[], clientId: string, family: string, pair?: { accessToken: string; refreshToken: string }) => {
+    const accessToken = pair?.accessToken ?? `synap_hub_mock_${randomToken()}`;
+    if (!pair) access.set(accessToken, { expiresAt: now() + accessTtl * 1000, revoked: false, family: refresh ? family : null, scope });
+    const row = access.get(accessToken)!;
     const body: Record<string, unknown> = {
       access_token: accessToken,
       token_type: "Bearer",
-      expires_in: accessTtl,
+      // As the pod: what the key has left, never an assumed hour.
+      expires_in: Math.max(0, Math.floor((row.expiresAt - now()) / 1000)),
       scope: scope.join(" "),
-      synap_grant: grant.filter((g) => scope.includes(g.permission)),
+      // Each grant row names its space's template when it came from one.
+      synap_grant: grant
+        .filter((g) => scope.includes(g.permission))
+        .map((g) => (g.templateSlug || !templateOf.has(g.workspaceId) ? g : { ...g, templateSlug: templateOf.get(g.workspaceId)! })),
       synap_user: user,
+      ...(app ? { synap_app: app } : {}),
+      ...(options.actsAs ? { synap_acts_as: options.actsAs } : {}),
     };
-    if (refresh) {
+    if (pair) {
+      body.refresh_token = pair.refreshToken;
+      if (options.advertiseRefreshExpiry) body.refresh_token_expires_in = Math.floor((refreshTokens.get(pair.refreshToken)!.idleUntil - now()) / 1000);
+    } else if (refresh) {
       const refreshToken = randomToken();
       refreshTokens.set(refreshToken, { clientId, family, idleUntil: now() + refreshIdle * 1000, used: false, revoked: false, scope });
       body.refresh_token = refreshToken;
@@ -220,6 +348,14 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
       }
       if (row.used) {
+        // The same pair again, inside the grace, while the successor is unused and its key lives.
+        const successor = row.successor ? refreshTokens.get(row.successor) : undefined;
+        const key = row.pairAccess ? access.get(row.pairAccess) : undefined;
+        const inGrace = graceMs > 0 && row.usedAt !== undefined && now() - row.usedAt < graceMs;
+        if (inGrace && successor && !successor.used && !successor.revoked && key && !key.revoked && key.expiresAt > now()) {
+          graceAnswers++;
+          return json(200, tokenBody(row.scope, row.clientId, row.family, { accessToken: row.pairAccess!, refreshToken: row.successor! }));
+        }
         reuses++;
         revokeFamily(row.family);
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
@@ -230,12 +366,151 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
       }
       row.used = true;
-      return json(200, tokenBody(row.scope, row.clientId, row.family));
+      row.usedAt = now();
+      // One live key per connection: the rotation retires the family's older keys.
+      for (const a of access.values()) if (a.family === row.family) a.revoked = true;
+      const body = tokenBody(row.scope, row.clientId, row.family);
+      row.successor = body.refresh_token as string;
+      row.pairAccess = body.access_token as string;
+      return json(200, body);
     }
     return oauthError("unsupported_grant_type", "Unsupported grant_type");
   }
 
-  function hub(method: string, path: string, headers: Record<string, string>, body: unknown): Response | "reject" {
+  /** A focus-session row as the list door answers it: the table's columns (defaults filled), `triage`, `kind`. */
+  const sessionRow = (s: MockSeedSession): Record<string, unknown> => ({
+    workspaceId: null,
+    projectId: null,
+    userId: user.id,
+    correlationId: null,
+    title: null,
+    goal: "",
+    status: "active",
+    templateId: null,
+    expectedOutputs: [],
+    channelId: null,
+    progress: null,
+    currentStage: null,
+    agentIds: [],
+    closedAt: null,
+    verificationReport: null,
+    metadata: {},
+    startedAt: seededAt,
+    createdAt: seededAt,
+    updatedAt: seededAt,
+    kind: "work",
+    triage: { pending: false, acceptedAt: null, acceptedBy: null },
+    ...s,
+  });
+
+  /** The seeded read doors (1.5); null when `path` is none of them. */
+  function readSeeded(path: string, query: URLSearchParams): Response | null {
+    const conn = /^\/entities\/([^/]+)\/connections$/.exec(path);
+    if (conn) {
+      const id = decodeURIComponent(conn[1]);
+      const ws = query.get("workspaceId");
+      const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
+      const inLens = (e: Record<string, unknown>) => !ws || e.workspaceId === ws || e.workspaceId == null;
+      const connections: Array<Record<string, unknown>> = [];
+      const graph = relations
+        .filter((r) => r.sourceEntityId === id || r.targetEntityId === id)
+        .sort((a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")))
+        .slice(0, limit);
+      for (const r of graph) {
+        const outgoing = r.sourceEntityId === id;
+        const otherId = outgoing ? r.targetEntityId : r.sourceEntityId;
+        const other = entities.find((e) => e.id === otherId);
+        // As the pod: an edge whose far end is gone or out of the lens is not a neighbour.
+        if (!other || !inLens(other)) continue;
+        connections.push({
+          entityId: otherId,
+          entity: { ...other, type: other.profileSlug ?? other.type ?? null, facetSlugs: other.facetSlugs ?? [] },
+          label: r.type,
+          direction: outgoing ? "outgoing" : "incoming",
+          source: "graph",
+          relationId: r.id,
+          relationType: r.type,
+          createdAt: r.createdAt ?? null,
+        });
+      }
+      for (const s of sessions.filter((x) => x.subjectEntityId === id).slice(0, limit)) {
+        const row = sessionRow(s);
+        connections.push({
+          entityId: s.id,
+          entity: null,
+          label: (row.title as string | null) || (row.goal as string),
+          direction: "incoming",
+          source: "focus_session",
+          focusSessionId: s.id,
+          focusSessionGoal: row.goal,
+          focusSessionStatus: row.status,
+          focusSessionWorkspaceId: row.workspaceId,
+          createdAt: row.createdAt,
+        });
+      }
+      const n = (source: string) => connections.filter((c) => c.source === source).length;
+      return json(200, {
+        connections,
+        counts: { total: connections.length, graph: n("graph"), structural: n("property"), threads: n("thread"), contextChannels: n("context_channel"), focusSessions: n("focus_session") },
+      });
+    }
+    const entity = /^\/entities\/([^/]+)$/.exec(path);
+    if (entity) {
+      const found = entities.find((e) => e.id === decodeURIComponent(entity[1]));
+      // The pod answers a miss with an EMPTY 404 body (rest/entities.ts `c.body(null, 404)`).
+      return found ? json(200, found) : new Response(null, { status: 404 });
+    }
+    const doc = /^\/documents\/([^/]+)$/.exec(path);
+    if (doc) {
+      const format = query.get("format") ?? "raw";
+      if (format !== "raw" && format !== "readable") return json(400, { error: "format must be raw or readable" });
+      const d = documents.find((x) => x.id === decodeURIComponent(doc[1]));
+      if (!d) return json(404, { error: "Document not found" });
+      // projectAgentDocument; the mock has no embeds, so `readable` = `raw`, and no sections are parsed.
+      return json(200, {
+        document: {
+          id: d.id,
+          title: d.title,
+          type: d.type ?? "markdown",
+          language: d.language ?? null,
+          workspaceId: d.workspaceId ?? null,
+          format,
+          content: d.content,
+          revision: d.revision ?? 1,
+          version: d.version ?? 1,
+          sections: [],
+          diagnostics: [],
+          updatedAt: d.updatedAt ?? seededAt,
+          createdAt: d.createdAt ?? seededAt,
+        },
+      });
+    }
+    if (path === "/focus-sessions") {
+      const ws = query.get("workspaceId");
+      const project = query.get("projectId");
+      if (!ws && !project) return json(400, { error: "workspaceId or projectId is required" });
+      const status = query.get("status") ?? "all";
+      const lens = query.get("lens") ?? "all";
+      const kind = query.get("kind") ?? "all";
+      const subject = query.get("subjectEntityId");
+      const limit = Math.min(Math.max(Number(query.get("limit") ?? 20) || 20, 1), 50);
+      const rows = sessions
+        .map(sessionRow)
+        .filter((r) => (!ws || r.workspaceId === ws) && (!project || r.projectId === project))
+        .filter((r) => status === "all" || r.status === status)
+        .filter((r) => {
+          const pending = (r.triage as { pending?: boolean } | undefined)?.pending === true;
+          return lens === "triage" ? pending : lens === "default" ? !pending : true;
+        })
+        .filter((r) => kind === "all" || r.kind === kind)
+        .filter((r) => !subject || r.subjectEntityId === subject)
+        .sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+      return json(200, rows.slice(0, limit));
+    }
+    return null;
+  }
+
+  function hub(method: string, path: string, query: URLSearchParams, headers: Record<string, string>, body: unknown): Response | "reject" {
     const failure = options.failures?.[path];
     if (failure === "unreachable") return "reject";
     const bearer = /^Bearer (.+)$/.exec(headers.authorization ?? "")?.[1];
@@ -253,16 +528,78 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       case "unavailable":
         return json(503, { error: "Unavailable" });
     }
-    // The grant fence (spec 17 §5): aggregate reads are refused to a scoped token.
+    // The grant fence: aggregate reads are refused to a space-scoped token.
     if (path.startsWith("/knowledge/") || path === "/entities/retrieve" || path === "/memory/search") {
       return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
     }
     if (method === "GET" && path === "/users/me") return json(200, user);
-    if (method === "GET" && path === "/entities") return json(200, { entities: [], total: 0 });
+    if (method === "GET" && path === "/entities") {
+      // The pod answers an ARRAY (rest/entities.ts), not a page object.
+      const ws = query.get("workspaceId");
+      const kind = query.get("profileSlug");
+      const offset = Number(query.get("offset") ?? 0) || 0;
+      const limit = Number(query.get("limit") ?? 50) || 50;
+      const rows = entities.filter((e) => (!ws || e.workspaceId === ws) && (!kind || e.profileSlug === kind));
+      return json(200, rows.slice(offset, offset + limit));
+    }
+    if (method === "GET" && path === "/proposals") {
+      // The grant clause: proposals are read only where the token holds proposal.read (else none, not a 403).
+      const readable = new Set(grant.filter((g) => g.permission === "proposal.read" && row.scope.includes(g.permission)).map((g) => g.workspaceId));
+      const status = query.get("status") ?? "pending";
+      const ws = query.get("workspaceId");
+      const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
+      const offset = Number(query.get("offset") ?? 0) || 0;
+      // proposalIds: comma-separated and/or repeated; present but empty matches nothing.
+      const idsRaw = query.getAll("proposalIds");
+      const ids = idsRaw.length > 0 ? new Set(idsRaw.flatMap((v) => v.split(",").map((x) => x.trim()).filter(Boolean))) : null;
+      const rows = proposals
+        .filter((p) => p.workspaceId !== null && readable.has(p.workspaceId))
+        .filter((p) => (status === "all" || p.status === status) && (!ws || p.workspaceId === ws))
+        .filter((p) => !ids || ids.has(p.id))
+        .reverse(); // newest first
+      const page = rows.slice(offset, offset + limit);
+      return json(200, { proposals: page, limit, offset, total: rows.length, hasMore: offset + page.length < rows.length });
+    }
+    if (method === "GET") {
+      const read = readSeeded(path, query);
+      if (read) return read;
+    }
+    const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
+    if (approve) {
+      // rejectAgentReviewer: an agent credential never approves, before anything is read.
+      if (options.actsAs !== "person") {
+        return json(403, { error: "An agent credential cannot approve proposals — approve is human review. Approve from a human session." });
+      }
+      const p = proposals.find((x) => x.id === decodeURIComponent(approve[1]));
+      if (!p) return json(404, { error: "Proposal not found" });
+      // Only where the person granted proposal.approve, for the proposal's own space.
+      if (!grant.some((g) => g.permission === "proposal.approve" && row.scope.includes(g.permission) && g.workspaceId === p.workspaceId)) {
+        return json(403, { error: "You may not approve changes here" });
+      }
+      if (p.status !== "pending") return json(409, { error: `The proposal is ${p.status}, not pending` });
+      p.status = "approved";
+      approvals.push(p.id);
+      return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
+    }
     if (method !== "GET") {
       writes.push({ method, path, body });
-      if ((options.writeMode ?? "proposed") === "proposed") {
+      const fields = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+      const workspaceId = typeof fields.workspaceId === "string" ? fields.workspaceId : null;
+      if (writeMode === "proposed") {
         const proposalId = `prop_mock_${++proposalSeq}`;
+        proposals.push({
+          id: proposalId,
+          proposalType: method === "POST" ? "create" : method === "DELETE" ? "delete" : "update",
+          targetType: path.split("/")[1]?.replace(/s$/, "") ?? "entity",
+          targetId: null,
+          status: "pending",
+          workspaceId,
+          createdAt: new Date(now()).toISOString(),
+          correlationId: null,
+          sessionId: null,
+          agentUserId: MOCK_APP_AGENT_ID,
+          ...(typeof fields.title === "string" ? { summary: `Create "${fields.title}"` } : {}),
+        });
         return json(200, {
           status: "proposed",
           message: "Sent for review",
@@ -270,7 +607,9 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
           reviewUrl: `${issuer}/open/${proposalId}`,
         });
       }
-      return json(200, { status: "created", id: `ent_mock_${writes.length}` });
+      const id = `ent_mock_${writes.length}`;
+      if (method === "POST" && path === "/entities") entities.push({ id, ...fields });
+      return json(200, { status: "created", id });
     }
     return json(404, { error: "Not found" });
   }
@@ -311,7 +650,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       } catch {
         body = rawBody;
       }
-      const res = hub(method, hubPath, headers, body);
+      const res = hub(method, hubPath, url.searchParams, headers, body);
       if (res === "reject") throw new TypeError("Failed to fetch: mock pod unreachable");
       return res;
     }
@@ -323,6 +662,21 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     fetch: mockFetch as typeof fetch,
     requests,
     writes,
+    proposals,
+    approvals,
+    settleProposal(id, status) {
+      const p = proposals.find((x) => x.id === id);
+      if (p) p.status = status;
+    },
+    async redeemElsewhere(t) {
+      const row = refreshTokens.get(t);
+      const res = await token({ grant_type: "refresh_token", refresh_token: t, client_id: row?.clientId ?? "" });
+      if (res.status !== 200) throw new Error(`redeemElsewhere: the pod answered ${res.status}`);
+      return (await res.json()) as { access_token: string; refresh_token: string; expires_in: number };
+    },
+    get graceAnswers() {
+      return graceAnswers;
+    },
     authorize(authorizeUrl, decision = {}) {
       const url = new URL(authorizeUrl);
       if (`${url.origin}${url.pathname}` !== `${issuer}/authorize`) throw new Error(`Not this pod's /authorize: ${authorizeUrl}`);
@@ -369,6 +723,9 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       for (const row of access.values()) row.revoked = true;
       for (const row of refreshTokens.values()) row.revoked = true;
     },
+    revokeAccessKeys() {
+      for (const row of access.values()) row.revoked = true;
+    },
     liveRefreshTokens() {
       return [...refreshTokens].filter(([, r]) => !r.used && !r.revoked).map(([t]) => t);
     },