@synap-core/sdk 1.4.0 → 1.5.0

package/src/connect/discovery.ts

@@ -1,6 +1,6 @@
 /**
- * Pod discovery (spec 17 §6.3): a typed address or a launch `iss` → the pod's
- * authorization server metadata (RFC 8414), validated before any redirect.
+ * Pod discovery: a typed address or a launch `iss` → the pod's authorization
+ * server metadata (RFC 8414), validated before any redirect.
  *
  *  - the metadata's `issuer` must equal the address it was fetched for, byte
  *    for byte (RFC 8414 §3.3): a document naming another issuer is not used;
@@ -11,13 +11,17 @@
  * The fetch runs on the app's server with an address a visitor typed, so it is
  * fenced: https only (http only on loopback when `allowInsecureLoopback`), no
  * IP literal outside public space, no single-label or `.local`/`.internal`
- * host, no redirect followed, 5 s, 64 KB. Residual: a public DNS name that
- * resolves to a private address cannot be refused without a resolver; a
- * deployment that cares adds egress rules.
+ * host, no redirect followed, 5 s, 64 KB counted on the stream. At most three
+ * addresses are tried per call (`discoverPod`). Residual: a public DNS name
+ * that resolves to a private address cannot be refused without a resolver; a
+ * deployment that cares adds egress rules, and an app rate-limits the route
+ * that calls this (it fetches an address a visitor chose).
  *
- * Connecting through Synap Cloud (the CP pod chooser, wave C1) is ./cloud.ts.
+ * Connecting through Synap Cloud (the Control Plane's pod chooser) is ./cloud.ts.
  */
 import { ConnectError, retryAfterSeconds } from "./errors";
+import { readCapped, timeoutSignal } from "./http";
+import { CLOUD_STATE_RE, LOOPBACK_HOSTS, SPACE_HINT_RE } from "./rules";
 import type { PodIssuer } from "./types";
 
 const METADATA_PATH = "/.well-known/oauth-authorization-server";
@@ -31,8 +35,6 @@ export interface DiscoverOptions {
   now?: () => number;
 }
 
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
-
 function isPrivateIpv4(host: string): boolean {
   const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
   if (!m) return false;
@@ -102,10 +104,14 @@ function sameOriginEndpoint(value: unknown, issuer: string): string | null {
 }
 
 async function readJsonCapped(res: Response): Promise<unknown> {
-  const text = await res.text();
-  if (text.length > MAX_METADATA_BYTES) throw new ConnectError("not_a_pod", "Metadata document too large");
+  const read = await readCapped(res, MAX_METADATA_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large"
+      ? new ConnectError("not_a_pod", "Metadata document too large")
+      : new ConnectError("pod_unreachable", "The metadata answer broke off");
+  }
   try {
-    return JSON.parse(text);
+    return JSON.parse(read.text);
   } catch {
     throw new ConnectError("not_a_pod", "Metadata is not JSON");
   }
@@ -120,18 +126,25 @@ async function discoverIssuer(issuer: string, opts: DiscoverOptions): Promise<Po
       method: "GET",
       headers: { Accept: "application/json" },
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+      signal: timeoutSignal(TIMEOUT_MS),
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {});
+    throw new ConnectError("pod_moved", `The address answered ${res.status}: the pod moved (its new address is not followed)`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)()),
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The pod answered ${res.status}`);
-  if (res.status !== 200) throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  if (res.status !== 200) {
+    await res.body?.cancel().catch(() => {});
+    throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  }
   const doc = await readJsonCapped(res);
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new ConnectError("not_a_pod", "Metadata is not an object");
   const m = doc as Record<string, unknown>;
@@ -165,32 +178,53 @@ async function discoverIssuer(issuer: string, opts: DiscoverOptions): Promise<Po
   };
 }
 
+/** Synap Cloud's pod domain: pods are `<name>.pod.synap.live`; `<name>.synap.live` and `pod.<name>.synap.live` are older names. */
+const CLOUD_DOMAIN = "synap.live";
+const CLOUD_POD_ZONE = `pod.${CLOUD_DOMAIN}`;
+const POD_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
+
+/** The addresses to try after the typed one fails, in order (at most two). */
+function fallbackIssuers(first: string): string[] {
+  const url = new URL(first);
+  const host = url.hostname;
+  if (url.pathname !== "/" || !host.includes(".") || host.endsWith(`.${CLOUD_POD_ZONE}`)) return [];
+  const label = host.endsWith(`.${CLOUD_DOMAIN}`) ? host.slice(0, -CLOUD_DOMAIN.length - 1) : null;
+  if (label !== null && POD_NAME_RE.test(label)) {
+    // A Synap Cloud name typed the old way: the pod's current name, then the old nested one.
+    return [`${url.protocol}//${label}.${CLOUD_POD_ZONE}`, `${url.protocol}//pod.${url.host}`];
+  }
+  return host.startsWith("pod.") ? [] : [`${url.protocol}//pod.${url.host}`];
+}
+
 /**
  * A typed pod address (or a launch `iss`) → its validated authorization server.
- * Tries the address, then `pod.<host>` (so "antoine.synap.live" finds
- * "pod.antoine.synap.live").
+ * Tries the address, then the pod names it may stand for: on Synap Cloud,
+ * "you.synap.live" finds "you.pod.synap.live" (and the older
+ * "pod.you.synap.live"); elsewhere, "example.com" finds "pod.example.com".
+ * A redirect is never followed: an old name that answers 308 counts as a
+ * miss (`pod_moved` when nothing else answers).
  */
 export async function discoverPod(input: string, opts: DiscoverOptions = {}): Promise<PodIssuer> {
   const first = canonicalPodUrl(input, opts);
+  let firstError: unknown;
   try {
     return await discoverIssuer(first, opts);
   } catch (err) {
-    const url = new URL(first);
-    const retry =
-      err instanceof ConnectError &&
-      (err.code === "not_a_pod" || err.code === "pod_unreachable") &&
-      !url.hostname.startsWith("pod.") &&
-      url.pathname === "/" &&
-      url.hostname.includes(".");
-    if (!retry) throw err;
-    const second = `${url.protocol}//pod.${url.host}`;
+    firstError = err;
+  }
+  const retryable = (err: unknown) =>
+    err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable" || err.code === "pod_moved");
+  if (!retryable(firstError)) throw firstError;
+  let tooOld: ConnectError | null = null;
+  for (const candidate of fallbackIssuers(first)) {
     try {
-      return await discoverIssuer(second, opts);
-    } catch (err2) {
+      return await discoverIssuer(candidate, opts);
+    } catch (err) {
       // A pod that is there but too old says more than "nothing answered".
-      throw err2 instanceof ConnectError && err2.code === "pod_unsupported" ? err2 : err;
+      if (err instanceof ConnectError && err.code === "pod_unsupported") tooOld ??= err;
     }
   }
+  throw tooOld ?? firstError;
 }
 
 /**
@@ -217,11 +251,11 @@ export function safeNextPath(value: string | null | undefined, appOrigin: string
 }
 
 export interface LaunchHint {
-  /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM (T6), never to auto-connect. */
+  /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM, never to auto-connect. */
   pod: string | null;
   /** Where to land after connecting (`target_link_uri`), same origin only. */
   next: string | null;
-  /** A space to preselect on consent (`synap_space_hint`). */
+  /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
   spaceHint: string | null;
   /**
    * The `state` of a Synap Cloud return (the CP pod chooser answers
@@ -235,7 +269,7 @@ export interface LaunchHint {
 }
 
 /**
- * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
+ * Read a third-party-initiated login (OIDC Core §4): the browser
  * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
  * the browser launch and the Synap Cloud chooser's return (`cloudState`).
  */
@@ -255,9 +289,9 @@ export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allow
   return {
     pod,
     next: safeNextPath(params.get("target_link_uri"), appOrigin),
-    spaceHint: hint && /^[A-Za-z0-9_-]{1,64}$/.test(hint) ? hint : null,
+    spaceHint: hint && SPACE_HINT_RE.test(hint) ? hint : null,
     // A browser launch never carries a state: any well-formed one is a Synap Cloud return
     // (a pick: iss + state; a cancel: state + error=access_denied, no iss).
-    cloudState: state && /^[A-Za-z0-9._~-]{16,256}$/.test(state) ? state : null,
+    cloudState: state && CLOUD_STATE_RE.test(state) ? state : null,
   };
 }

package/src/connect/encoding.ts

@@ -1,6 +1,6 @@
 /**
  * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code
- * runs on Node 18+, edge runtimes and workers. No Node import.
+ * runs on Node 20+, edge runtimes and workers. No Node import.
  */
 
 const encoder = new TextEncoder();

package/src/connect/errors.ts

@@ -29,6 +29,12 @@ export type ConnectErrorCode =
   | "expired"
   /** The pod refused the connection's refresh token while it should still live. */
   | "revoked"
+  /**
+   * The pod answered a redirect where it must answer itself (a moved pod
+   * answers 308 from its old name for a while): connect again with its new
+   * address. The new address is never taken from the redirect.
+   */
+  | "pod_moved"
   /** The pod answered something the SDK cannot use. */
   | "server_error";
 
@@ -69,6 +75,7 @@ export const CONNECT_ERROR_CODES: readonly ConnectErrorCode[] = [
   "rate_limited",
   "expired",
   "revoked",
+  "pod_moved",
   "server_error",
 ];
 

package/src/connect/flow.ts

@@ -1,5 +1,5 @@
 /**
- * The OAuth 2.1 authorization-code flow of a pod app (spec 17 §6.4-§6.7), as
+ * The OAuth 2.1 authorization-code flow of a pod app, as
  * plain functions over a SEALED transaction string. `createPodAppAuth` wires
  * them to cookies and route handlers; use these directly for another store.
  *
@@ -18,15 +18,19 @@
 import { ConnectError, fromOAuthError, retryAfterSeconds } from "./errors";
 import { constantTimeEqual, pkceChallenge, randomToken } from "./encoding";
 import { discoverPod, type DiscoverOptions } from "./discovery";
+import { readCapped, timeoutSignal } from "./http";
+import { LOOPBACK_HOSTS } from "./rules";
 import { seal, unseal, type AppSecret } from "./seal";
-import type { PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
+import type { PodActsAs, PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
 
 /** How long a started sign-in stays valid. */
 export const TRANSACTION_TTL_MS = 10 * 60 * 1000;
-/** The refresh token's idle life when the pod does not say (spec 17 F5: 30 days). */
+/** The refresh token's idle life when the pod does not say (the pod's: 30 days). */
 export const DEFAULT_REFRESH_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_ACCESS_TTL_SEC = 3600;
 const TIMEOUT_MS = 10_000;
+/** A token response is a few KB; more is not a token response. */
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
 
 /** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
 export type SealedTransaction = string & { readonly __sealedTransaction: true };
@@ -240,20 +244,30 @@ async function tokenRequest(
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
       body: body.toString(),
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+      signal: timeoutSignal(TIMEOUT_MS),
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod's token endpoint did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {});
+    throw new ConnectError("pod_moved", `The token endpoint answered ${res.status}: the pod moved; connect again with its new address`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)()),
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The token endpoint answered ${res.status}`);
+  const read = await readCapped(res, MAX_TOKEN_RESPONSE_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large"
+      ? new ConnectError("server_error", "The token endpoint's answer is too large")
+      : new ConnectError("pod_unreachable", "The token endpoint's answer broke off");
+  }
   let json: unknown;
   try {
-    json = await res.json();
+    json = JSON.parse(read.text);
   } catch {
     throw new ConnectError("server_error", `The token endpoint answered ${res.status} without JSON`);
   }
@@ -270,15 +284,26 @@ function parseGrant(value: unknown): PodGrant[] | null {
   const out: PodGrant[] = [];
   for (const g of value) {
     if (!g || typeof g !== "object") return null;
-    const { permission, workspaceId, workspaceName } = g as Record<string, unknown>;
+    const { permission, workspaceId, workspaceName, templateSlug } = g as Record<string, unknown>;
     if (typeof permission !== "string" || typeof workspaceId !== "string") return null;
-    out.push({ permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" });
+    const row: PodGrant = { permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" };
+    // The space's template, omitted when it came from none.
+    if (typeof templateSlug === "string" && templateSlug.length > 0 && templateSlug.length <= 200) row.templateSlug = templateSlug;
+    out.push(row);
   }
   return out;
 }
 
+/**
+ * `synap_acts_as`: read from EVERY token response, never carried
+ * over from the previous one, so a pod that stops saying "person" (or never
+ * did) gives an agent connection.
+ */
+function parseActsAs(value: unknown): PodActsAs | undefined {
+  return value === "person" || value === "agent" ? value : undefined;
+}
+
 const APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
 /**
  * `synap_app` (Synap extension): the pod's id for this app connection and its
@@ -311,8 +336,8 @@ function parseUser(value: unknown): PodUser | null {
 
 /**
  * A token response → a connection. On a refresh, `previous` supplies what the
- * response may omit (grant, user, app). `expires_in` is read as sent: a refresh
- * answered within the pod's reuse grace (PB3b) hands back the live key the
+ * response may omit (grant, user, app; never `actsAs`). `expires_in` is read as sent: a refresh
+ * answered within the pod's reuse grace hands back the live key the
  * first redeem got, with less than an hour left. A refresh response WITHOUT a new
  * refresh_token drops the old one: with single-use rotation, resending a
  * consumed token reads as theft and revokes the whole family.
@@ -362,6 +387,8 @@ export function parseTokenResponse(
   const manageUrl = app.manageUrl ?? ctx.previous?.manageUrl;
   if (appId !== undefined) connection.appId = appId;
   if (manageUrl !== undefined) connection.manageUrl = manageUrl;
+  const actsAs = parseActsAs(body.synap_acts_as);
+  if (actsAs !== undefined) connection.actsAs = actsAs;
   if (typeof refresh_token === "string" && refresh_token !== "") {
     connection.refreshToken = refresh_token;
     const idle =
@@ -375,7 +402,7 @@ export function parseTokenResponse(
 
 /**
  * How long a rotation's result is remembered for its SPENT refresh token.
- * The pod (PB3) refuses a concurrent second redeem softly, but a token
+ * The pod refuses a concurrent second redeem softly, but a token
  * presented AGAIN after its use is a reuse: the whole family and the live
  * access key are revoked. A browser easily sends that replay: parallel
  * requests, a second tab, a response it had not stored yet, all still
@@ -401,7 +428,7 @@ function pruneRotations(now: number): void {
 
 /**
  * Exchange the refresh token for a new access token and the rotated refresh
- * token (PB3: single-use, 30 days from issue, reach re-derived by the pod).
+ * token (single-use, 30 days from issue, its reach re-derived by the pod).
  *
  * SINGLE-FLIGHT per connection within this process: concurrent callers share
  * one request, and for `ROTATION_MEMORY_MS` after it a caller still holding
@@ -415,7 +442,7 @@ function pruneRotations(now: number): void {
  * (invalid_grant while it should live: spent, revoked, the app removed or
  * narrowed to nothing, or a concurrent redeem lost), `misconfigured`
  * (invalid_client, unauthorized_client), `rate_limited`, `pod_unreachable`,
- * `server_error`.
+ * `pod_moved` (the token endpoint answered a redirect), `server_error`.
  */
 export function refreshConnection(connection: PodConnection, opts: FlowOptions = {}): Promise<PodConnection> {
   const clock = opts.now ?? Date.now;
@@ -478,8 +505,9 @@ export async function revokeConnection(connection: PodConnection, opts: FlowOpti
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({ token, token_type_hint: hint, client_id: connection.clientId }).toString(),
         redirect: "manual",
-        signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+        signal: timeoutSignal(TIMEOUT_MS),
       });
+      await res.body?.cancel().catch(() => {});
       if (res.status !== 200) revoked = false;
     } catch {
       revoked = false;

package/src/connect/http.ts

@@ -0,0 +1,42 @@
+/**
+ * Reading answers from hosts the SDK does not control: a pod a visitor typed,
+ * its token endpoint, its Hub API. Bounded in time (`timeoutSignal`) and in
+ * bytes (`readCapped`): the bytes are counted on the stream, so an answer past
+ * the cap is cancelled there, never buffered whole first.
+ */
+
+/** An abort signal after `ms`, where the runtime has `AbortSignal.timeout` (workers and edge runtimes may not). */
+export function timeoutSignal(ms: number): AbortSignal | undefined {
+  return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : undefined;
+}
+
+export type CappedRead = { ok: true; text: string } | { ok: false; reason: "too_large" | "unreadable" };
+
+/** The body as UTF-8 text, at most `maxBytes` bytes. */
+export async function readCapped(res: Response, maxBytes: number): Promise<CappedRead> {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {});
+    return { ok: false, reason: "too_large" };
+  }
+  if (!res.body) return { ok: true, text: "" };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let total = 0;
+  let text = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {});
+        return { ok: false, reason: "too_large" };
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+  return { ok: true, text: text + decoder.decode() };
+}

package/src/connect/hub-types.ts

@@ -0,0 +1,254 @@
+/**
+ * Wire shapes of the Hub REST doors `createPodClient`'s typed methods read.
+ *
+ * DRIFT RISK: hand-written from synap-backend main (2026-10-22), each from the
+ * route itself, never from `@synap-core/hub-rest-client` alone:
+ *  - entities: `routers/hub-protocol/rest/entities.ts` (`GET /entities`,
+ *    `GET /entities/:id` → `entityToWire`, `_codecs/entity.ts`
+ *    `WireEntitySchema`; `GET /entities/:id/connections` → `relations.ts`
+ *    `getConnections`, `services/object-graph/entity-connections.ts`);
+ *  - documents: `rest/documents.ts` `GET /documents/:id` →
+ *    `services/document-patch/read-document.ts` `projectAgentDocument`;
+ *  - focus sessions: `rest/focus-sessions.ts` `GET /focus-sessions` (raw rows +
+ *    `triage` + `kind`), slots `services/focus-sessions/update-session.ts`
+ *    `expectedOutputWireSchema`;
+ *  - files: `rest/entities.ts` `GET /files/:id/url` → `file-upload.ts`
+ *    `signFileEntityUrl`;
+ *  - approve: `rest/proposals.ts` `POST /proposals/:id/approve`.
+ * Fields the SDK does not read stay on the objects (index signatures): the pod
+ * sends more than is typed here. The mock pod (`@synap-core/sdk/testing`)
+ * answers these shapes; `src/__tests__/connect.typed.test.ts` drives both.
+ */
+
+/** One entity, as `GET /entities` and `GET /entities/:id` answer it (`WireEntitySchema`). */
+export interface PodEntity {
+  id: string;
+  profileSlug: string;
+  /** Deprecated alias of `profileSlug`, still sent. */
+  type?: string;
+  title?: string | null;
+  preview?: string | null;
+  description?: string | null;
+  properties: Record<string, unknown>;
+  systemData?: Record<string, unknown>;
+  userId: string;
+  workspaceId?: string | null;
+  documentId?: string | null;
+  version?: number;
+  /** ISO 8601. */
+  createdAt?: string;
+  updatedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface ListEntitiesOptions {
+  /** One granted space. Omitted: every space the connection can read. */
+  workspaceId?: string;
+  /** One kind, e.g. `post`. */
+  profileSlug?: string;
+  /** 1-1000 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  offset?: number;
+  /** e.g. `updatedAt:desc`. */
+  sort?: string;
+  /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
+  includePodWide?: boolean;
+}
+
+export type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";
+
+/** One edge of `GET /entities/:id/connections` (`EntityConnection`). */
+export interface PodEntityConnection {
+  /** The other end: an entity, or the channel / session for those sources. */
+  entityId: string;
+  /** The other entity's row (title, `type` = its kind, workspaceId, facetSlugs, …); null for channels and sessions. */
+  entity: {
+    title?: string | null;
+    type?: string | null;
+    workspaceId?: string | null;
+    facetSlugs?: string[] | null;
+    [key: string]: unknown;
+  } | null;
+  label: string;
+  direction: "outgoing" | "incoming" | "structural";
+  source: PodConnectionSource;
+  relationId?: string;
+  relationType?: string;
+  storedAs?: "link";
+  propertySlug?: string;
+  propertyLabel?: string;
+  channelId?: string;
+  channelRelationshipType?: string;
+  channelTitle?: string | null;
+  channelWorkspaceId?: string | null;
+  focusSessionId?: string;
+  focusSessionGoal?: string;
+  focusSessionStatus?: string;
+  focusSessionWorkspaceId?: string | null;
+  /** ISO 8601, or null (a property link has no date). */
+  createdAt?: string | null;
+  [key: string]: unknown;
+}
+
+export interface PodEntityConnections {
+  connections: PodEntityConnection[];
+  counts: {
+    total: number;
+    graph: number;
+    structural: number;
+    threads: number;
+    contextChannels: number;
+    focusSessions: number;
+  };
+}
+
+export interface GetEntityConnectionsOptions {
+  /** A space lens; omitted = everything the connection can read. */
+  workspaceId?: string;
+  /** Per source, 1-200 (the pod's default: 50). */
+  limit?: number;
+}
+
+/** A document's top-level section (`listDocumentSections`). */
+export interface PodDocumentSection {
+  id: string;
+  /** Who owns it (a person's section is not an agent's to change). */
+  owner: string;
+  title: string | null;
+  author: string | null;
+}
+
+/** `GET /documents/:id` → `document` (`projectAgentDocument`). */
+export interface PodDocument {
+  id: string;
+  title: string;
+  /** `markdown`, `text`, `html`, … */
+  type: string;
+  language: string | null;
+  workspaceId: string | null;
+  format: "raw" | "readable";
+  /** Markdown; `readable` replaces embeds by their fallback text. */
+  content: string;
+  /** Pass back as `baseRevision` on a guarded edit. */
+  revision: number;
+  version: number;
+  sections: PodDocumentSection[];
+  /** What will not render; null when the check could not run (`diagnosticsError`). */
+  diagnostics: unknown[] | null;
+  diagnosticsError?: string;
+  updatedAt: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface GetDocumentOptions {
+  /** `raw` (the stored markdown, the pod's default) or `readable`. */
+  format?: "raw" | "readable";
+}
+
+/** `focus_sessions.status` (`@synap-core/types/focus-sessions` SESSION_STATUSES). */
+export type PodSessionStatus = "active" | "paused" | "forming" | "scheduled" | "closed" | "failed" | "cancelled" | "stale";
+
+/**
+ * One declared deliverable of a session (`expectedOutputWireSchema`). A slot
+ * with `owner: "human"` is waiting on the person: `blockedReason` and `why` say
+ * for what, `ask` how they can answer (confirm, choose, form, act, provide).
+ */
+export interface PodSessionSlot {
+  kind: string;
+  label: string;
+  key?: string;
+  optional?: boolean;
+  status?: "pending" | "done";
+  /** Absent = `agent`. */
+  owner?: "human" | "agent";
+  blockedReason?: string;
+  why?: string;
+  /** ISO 8601, stamped by the pod with `owner: "human"`. */
+  owedSince?: string;
+  /** How the person can answer (`@synap-core/types/ask`), or null. */
+  ask?: unknown;
+  answer?: {
+    text: string;
+    messageId: string | null;
+    answeredBy: string;
+    answeredAt: string;
+    question?: string;
+    value?: unknown;
+    [key: string]: unknown;
+  };
+  retiredAt?: string;
+  [key: string]: unknown;
+}
+
+/** One row of `GET /focus-sessions`. `expectedOutputs` is always an array here (the SDK drops anything else). */
+export interface PodFocusSession {
+  id: string;
+  workspaceId: string | null;
+  projectId: string | null;
+  userId: string;
+  title: string | null;
+  goal: string;
+  status: PodSessionStatus | (string & {});
+  templateId: string | null;
+  expectedOutputs: PodSessionSlot[];
+  channelId: string | null;
+  progress: number | null;
+  currentStage: string | null;
+  agentIds: string[];
+  closedAt: string | null;
+  metadata: unknown;
+  startedAt: string;
+  createdAt: string;
+  updatedAt: string;
+  /** Projected by the list door: `work`, `run` (a playbook or automation ran it) or `receipt`. */
+  kind?: "work" | "run" | "receipt";
+  /** Projected by the list door: an agent-started session the person has not accepted yet. */
+  triage?: { pending: boolean; acceptedAt: string | null; acceptedBy: string | null };
+  [key: string]: unknown;
+}
+
+export interface ListFocusSessionsOptions {
+  /** A space; `workspaceId` or `projectId` is required (the pod's rule). */
+  workspaceId?: string;
+  projectId?: string;
+  /** Default `all` (the pod's default on this door). */
+  status?: PodSessionStatus | "all";
+  /** 1-50 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  /** Triage lens: `all` (default here), `default` (hides unaccepted agent sessions), `triage`. */
+  lens?: "all" | "default" | "triage";
+  /** Population lens: `all` (default here), `work`, `run`, `receipt`. */
+  kind?: "all" | "work" | "run" | "receipt";
+  /** Sessions about one thing. */
+  subjectEntityId?: string;
+}
+
+/** `GET /files/:id/url`: a signed GET for a file entity's blob. */
+export interface PodFileUrl {
+  /** Served as an `attachment`, with the stored type. */
+  url: string;
+  /** ISO 8601; the signature's end (about an hour). */
+  expiresAt: string;
+  /** Decide drawability on this, never on the URL; null when unknown. */
+  mimeType: string | null;
+}
+
+/** `POST /proposals/:id/approve`. */
+export interface PodApproval {
+  proposalId: string;
+  /** The row the approval produced or linked, when it names one. */
+  primaryId?: string;
+  linked?: number;
+  /** The proposal after the approval (status, execution result), when the pod could read it back. */
+  proposal: Record<string, unknown> | null;
+}
+
+export interface ApproveProposalOptions {
+  /**
+   * The proposal's space, when known: refused locally unless the connection
+   * holds `proposal.approve` there. Omitted: needs it in some space, and the
+   * pod checks the proposal's own space.
+   */
+  workspaceId?: string;
+}