@synap-core/sdk 1.4.0 → 1.5.1

package/dist/connect.d.cts

@@ -1,5 +1,5 @@
-import { b as PodConnection, P as PodGrant, c as PodSpace, C as ClientMetadataDocument, A as AppRequest, d as PodIssuer } from './types-C2KGNXEn.cjs';
-export { a as PodUser } from './types-C2KGNXEn.cjs';
+import { c as PodConnection, P as PodGrant, b as PodActsAs, d as PodSpace, C as ClientMetadataDocument, A as AppRequest, e as PodIssuer } from './types-DZYNBCq7.cjs';
+export { a as PodUser } from './types-DZYNBCq7.cjs';
 
 /**
  * The one error type of `@synap-core/sdk/connect`. `code` is the contract a UI
@@ -31,6 +31,12 @@ 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";
 declare class ConnectError extends Error {
@@ -49,7 +55,276 @@ declare const CONNECT_ERROR_CODES: readonly ConnectErrorCode[];
 /** Parse an untrusted `?error=` value back into a code (null when unknown). */
 declare function parseConnectErrorCode(value: string | null | undefined): ConnectErrorCode | null;
 
-type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable" | "server";
+/**
+ * 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`). */
+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;
+    /** The roles it wears, with `includeFacets`; absent when it wears none. */
+    facetSlugs?: string[];
+    /** Each role's overlay, with `includeFacets`; absent when it wears none. */
+    facets?: PodEntityFacet[];
+    [key: string]: unknown;
+}
+/** One role an entity wears (`FacetRowAnnotation`). */
+interface PodEntityFacet {
+    facetId: string;
+    /** The role, e.g. `lead`. */
+    slug: string;
+    properties: Record<string, unknown>;
+    status: string | null;
+}
+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;
+    /** Only the entities wearing this role, e.g. `lead`. */
+    facetSlug?: string;
+    /** Put `facetSlugs` and `facets` on each row that wears a role. */
+    includeFacets?: boolean;
+}
+type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";
+/** One edge of `GET /entities/:id/connections` (`EntityConnection`). */
+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;
+}
+interface PodEntityConnections {
+    connections: PodEntityConnection[];
+    counts: {
+        total: number;
+        graph: number;
+        structural: number;
+        threads: number;
+        contextChannels: number;
+        focusSessions: number;
+    };
+}
+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`). */
+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`). */
+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;
+}
+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). */
+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).
+ */
+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). */
+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;
+}
+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. */
+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`. */
+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;
+}
+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;
+}
+
+type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable"
+/** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
+ | "pod_moved" | "server";
+/**
+ * Why the SDK refused before sending anything (`status: null`):
+ *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
+ *    never lets an agent credential approve; `code: "forbidden"`);
+ *  - `not_granted`: the connection holds no permission for it (`forbidden`);
+ *  - `invalid_input`: an id, a path or an option the pod would refuse (`invalid`).
+ */
+type PodRefusalReason = "agent_cannot_approve" | "not_granted" | "invalid_input";
 interface PodError {
     code: PodErrorCode;
     /** The HTTP status, or null when nothing was answered. */
@@ -57,6 +332,17 @@ interface PodError {
     retryAfterSec?: number;
     /** The pod's own error text, for logs only. */
     detail?: string;
+    /** Set when the SDK refused locally (1.5). */
+    reason?: PodRefusalReason;
+    /**
+     * On `unauthorized` (1.5): the pod refused the access token, the connection
+     * still holds a refresh token, and this client could not renew it (no
+     * `renew`). A forced refresh may restore it (a narrow, or a pod-side "Revoke
+     * key", ends the key, not the connection): run `refreshIfNeeded(request,
+     * { force: true })` where cookies can be set. Absent = the pod refused the
+     * connection itself: connect again.
+     */
+    refreshable?: true;
 }
 type PodResult<T> = {
     ok: true;
@@ -108,15 +394,37 @@ interface ListPendingProposalsOptions {
     /** 1-200, default 20. */
     limit?: number;
     offset?: number;
+    /**
+     * Only these proposals (at most 100 ids; the pod's `proposalIds` filter,
+     * pods that do not filter are filtered here). An empty list matches nothing (answered without a request).
+     */
+    proposalIds?: readonly string[];
 }
 interface PodClientOptions {
     fetch?: typeof fetch;
     now?: () => number;
+    /** Per Hub request, default 10 000 ms; a request past it is `pod_unreachable`. */
+    timeoutMs?: number;
+    /** The most a Hub answer may weigh, default 8 MiB; a bigger one is `server` (the body is not read further). */
+    maxResponseBytes?: number;
+    /**
+     * Renew the connection after the pod refused its access token (401) while it
+     * holds a refresh token: rotate it, PERSIST the result (the old refresh token
+     * is spent once the pod answers), then return it; throw the refresh's
+     * `ConnectError` when it fails. The client calls it at most once (concurrent
+     * 401s share the call), retries the refused request once with the result, and
+     * uses it from then on. `PodAppAuth.client(connection, { persist })` builds
+     * one. Without it a 401 stays `unauthorized` (with `refreshable`).
+     */
+    renew?: (connection: PodConnection) => Promise<PodConnection>;
 }
 interface PodClient {
     podUrl: string;
-    user: PodConnection["user"];
-    grant: PodGrant[];
+    /** The connection's, or the renewed one's after a 401 (`renew`). */
+    readonly user: PodConnection["user"];
+    readonly grant: PodGrant[];
+    /** Who the token acts as (`connectionActsAs`): `"agent"` unless the pod said `"person"`. */
+    readonly actsAs: PodActsAs;
     /** Whether the connection was granted `permission` (in `workspaceId` when given). */
     can(permission: string, workspaceId?: string): boolean;
     /** The granted spaces, each with its permissions (`spaces(connection)`). */
@@ -129,12 +437,43 @@ interface PodClient {
      * empty list, so this answers `forbidden` instead, without a request.
      */
     listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
+    /** `GET /entities` (no full-text `q`: a space-scoped token may list, never search). */
+    listEntities(opts?: ListEntitiesOptions): Promise<PodResult<PodEntity[]>>;
+    /** `GET /entities/:id`; `not_found` when it does not exist or is not readable. */
+    getEntity(id: string): Promise<PodResult<PodEntity>>;
+    /** `GET /entities/:id/connections`: its relations, property links, threads and sessions. */
+    getEntityConnections(id: string, opts?: GetEntityConnectionsOptions): Promise<PodResult<PodEntityConnections>>;
+    /** `GET /documents/:id`: content, revision, sections. */
+    getDocument(id: string, opts?: GetDocumentOptions): Promise<PodResult<PodDocument>>;
+    /**
+     * `GET /focus-sessions` in a space (or a project), newest first, with their
+     * slots (`expectedOutputs`; `humanSlots(session)` = what waits on the person).
+     * `invalid` without a request when neither `workspaceId` nor `projectId` is given.
+     */
+    listFocusSessions(opts: ListFocusSessionsOptions): Promise<PodResult<PodFocusSession[]>>;
+    /** `GET /files/:id/url`: a signed download URL for a file entity (about an hour). */
+    getFileUrl(entityId: string): Promise<PodResult<PodFileUrl>>;
+    /**
+     * `POST /proposals/:id/approve`, as the person. Only a PERSON connection
+     * (`actsAs: "person"`) holding `proposal.approve` can: an agent connection
+     * gets `forbidden` / `agent_cannot_approve` and NOTHING is sent (the pod
+     * never lets an agent approve); without the permission, `forbidden` /
+     * `not_granted`, also without a request.
+     */
+    approveProposal(id: string, opts?: ApproveProposalOptions): Promise<PodResult<PodApproval>>;
     get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
     post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     put<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
 }
+/** Who `connection`'s token acts as: `"person"` only when the pod said so, else `"agent"`. */
+declare function connectionActsAs(connection: Pick<PodConnection, "actsAs">): PodActsAs;
+/**
+ * The slots of `session` that wait on the person (Home's "needs you"):
+ * `owner: "human"`, not done, not retired.
+ */
+declare function humanSlots(session: Pick<PodFocusSession, "expectedOutputs">): PodSessionSlot[];
 /** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
 declare function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean;
 /**
@@ -249,7 +588,12 @@ declare const DEFAULT_PATHS: PodAppPaths;
 /** Refresh only inside the last 5 minutes of the access token's life. */
 declare const REFRESH_WINDOW_MS: number;
 interface PodAppAuthConfig {
-    /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+    /**
+     * The app's origin, e.g. https://studio.example.com. `http://localhost` is
+     * accepted for the SDK's MOCK pod only: every real pod, a local one
+     * included, refuses an http client_id and redirect_uri, so an app that signs
+     * in to a real pod runs on https (a tunnel in development).
+     */
     appUrl: string;
     /** Shown on the pod's consent screen (at most 100 characters). */
     clientName: string;
@@ -269,7 +613,11 @@ interface PodAppAuthConfig {
      * "Continue with Synap Cloud" (`cloudConnectAvailable`). Unset = address only.
      */
     cloudUrl?: string | null;
-    /** Accept pods (and a Control Plane) on http://localhost (development against a local pod). */
+    /**
+     * Accept a pod (and a Control Plane) on http://localhost: development
+     * against the SDK's mock pod (`@synap-core/sdk/testing`). A real local pod
+     * still refuses an app that is not on https (see `appUrl`).
+     */
     allowInsecureLoopback?: boolean;
     /** Developer log of every refused sign-in; messages never carry a token. Default: console.warn. */
     onError?: (error: ConnectError, where: "connect" | "callback" | "disconnect" | "refresh") => void;
@@ -287,9 +635,9 @@ type RefreshStatus =
  | "refreshed"
 /** The refresh failed (a lost rotation race, the pod busy) but the access token still works: keep it, set nothing. */
  | "kept"
-/** The access token is spent and cannot be renewed: connect again. */
+/** The access token is spent and cannot be renewed (lapsed, or the pod moved: `error.code`): connect again. The session cookie is cleared (the marker stays). */
  | "expired"
-/** The pod refused the refresh token (access removed): connect again. */
+/** The pod refused the refresh token (access removed): connect again. The session cookie is cleared (the marker stays). */
  | "revoked"
 /** The pod could not be reached and the access token is spent: try later. */
  | "unavailable";
@@ -311,6 +659,28 @@ interface RefreshOutcome {
         podUrl: string;
     };
 }
+interface RefreshOptions {
+    /**
+     * Rotate now, whatever the access token's expiry says: the pod refused it
+     * (a Hub call answered `unauthorized` with `refreshable`). Needs a refresh
+     * token. If the pod refuses the refresh too, the outcome is `revoked` (or
+     * `expired`), never `kept`: the access token is known dead.
+     */
+    force?: boolean;
+}
+interface PodAppClientOptions extends PodClientOptions {
+    /**
+     * Where the client may set cookies (a route handler, a server action): after
+     * a 401 it then renews the connection ONCE (rotate, seal, `persist` the
+     * Set-Cookie values, retry the request once). The rotation spends the old
+     * refresh token, so it is never done where its result cannot be stored: a
+     * server component passes no `persist`, and a 401 there answers
+     * `unauthorized` with `refreshable` (see `RefreshOptions.force`).
+     */
+    persist?: (setCookies: string[]) => void | Promise<void>;
+    /** The request (or its Cookie header) the connection came from: chunks a larger old cookie left are cleared. */
+    request?: Request | string | null;
+}
 interface PodAppAuth {
     clientId: string;
     redirectUri: string;
@@ -342,12 +712,17 @@ interface PodAppAuth {
     readLapsed(source: Request | string | null): Promise<{
         podUrl: string;
     } | null>;
-    /** For `proxy.ts` / a route handler: rotate near expiry, lost-race safe. */
-    refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
-    /** A Hub REST client for the connection. */
-    client(connection: PodConnection, opts?: PodClientOptions): PodClient;
+    /** For `proxy.ts` / a route handler: rotate near expiry (or now, `force`), lost-race safe. */
+    refreshIfNeeded(request: Request, opts?: RefreshOptions): Promise<RefreshOutcome>;
+    /** A Hub REST client for the connection (renewing it after a 401 when it can `persist`). */
+    client(connection: PodConnection, opts?: PodAppClientOptions): PodClient;
 }
-/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+/**
+ * The app's client metadata document (its client_id URL serves it). Refuses,
+ * at setup, every document the pod would refuse at sign-in: the permissions
+ * (`assertAppPermission`), at most 32 requests counted as sent, duplicates
+ * included, an IP address origin, the 5 KB cap.
+ */
 declare function buildClientMetadata(opts: {
     appUrl: string;
     clientName: string;
@@ -387,8 +762,11 @@ declare function canonicalPodUrl(input: string, opts?: {
 }): string;
 /**
  * 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).
  */
 declare function discoverPod(input: string, opts?: DiscoverOptions): Promise<PodIssuer>;
 /**
@@ -398,11 +776,11 @@ declare function discoverPod(input: string, opts?: DiscoverOptions): Promise<Pod
  */
 declare function safeNextPath(value: string | null | undefined, appOrigin: string): string | null;
 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
@@ -415,7 +793,7 @@ interface LaunchHint {
     cloudState: string | null;
 }
 /**
- * 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`).
  */
@@ -456,15 +834,18 @@ declare function cloudConnectAvailable(config?: CloudConnectConfig | null): bool
 interface StartCloudConnectOptions extends CloudConnectConfig {
     /** The app's client_id (its CIMD URL): the CP reads `initiate_login_uri` from it. */
     clientId: string;
-    /** SERVER-ONLY app secret that seals the transaction. */
+    /**
+     * SERVER-ONLY app secret that seals the transaction. Required: without it the call throws `misconfigured`.
+     * Optional in the type only for 1.x semver; required in 2.0.
+     */
     secret?: AppSecret;
     /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
     next?: string | null;
-    /** A space to preselect on the pod's consent. */
+    /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
     spaceHint?: string | null;
     /** Show the pod's consent again even if this browser is already connected to the pod the person picks. */
     prompt?: "consent" | null;
-    /** @deprecated Ignored: the SDK always draws its own 32-byte state. */
+    /** @deprecated Ignored: the SDK always draws its own 32-byte state. Removed in 2.0. */
     state?: string;
     now?: () => number;
 }
@@ -478,7 +859,10 @@ interface StartedCloudConnect {
 }
 /**
  * Start a Synap Cloud sign-in. Throws `cp_unavailable` at once when no CP URL
- * is configured (as 1.3 always did), `misconfigured` without a secret.
+ * is configured, `misconfigured` without a secret: both SYNCHRONOUSLY, before
+ * a Promise exists, so wrap the call in try/catch rather than relying on
+ * `.catch` (kept from 1.3 for compatibility; 2.0 makes it a plain async
+ * function with a required secret).
  */
 declare function startCloudConnect(opts: StartCloudConnectOptions): Promise<StartedCloudConnect>;
 interface AcceptCloudReturnOptions {
@@ -507,9 +891,11 @@ interface CloudReturn {
  */
 declare function acceptCloudReturn(opts: AcceptCloudReturnOptions): Promise<CloudReturn>;
 
+declare function isBrowserRuntime(): boolean;
+
 /** How long a started sign-in stays valid. */
 declare const TRANSACTION_TTL_MS: number;
-/** 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). */
 declare const DEFAULT_REFRESH_IDLE_MS: number;
 /** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
 type SealedTransaction = string & {
@@ -587,8 +973,8 @@ interface CallbackResult {
 declare function handleCallback(opts: HandleCallbackOptions): Promise<CallbackResult>;
 /**
  * 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.
@@ -603,7 +989,7 @@ declare function parseTokenResponse(body: Record<string, unknown>, ctx: {
 }): PodConnection;
 /**
  * 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
@@ -613,7 +999,7 @@ declare function parseTokenResponse(body: Record<string, unknown>, ctx: {
 declare const ROTATION_MEMORY_MS: number;
 /**
  * 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
@@ -627,7 +1013,7 @@ declare const ROTATION_MEMORY_MS: number;
  * (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`.
  */
 declare function refreshConnection(connection: PodConnection, opts?: FlowOptions): Promise<PodConnection>;
 /**
@@ -642,6 +1028,4 @@ declare function revokeConnection(connection: PodConnection, opts?: FlowOptions)
 /** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
 declare function pkceChallenge(verifier: string): Promise<string>;
 
-declare function isBrowserRuntime(): boolean;
-
-export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, CLOUD_TRANSACTION_TTL_MS, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, type CloudConnectConfig, type CloudReturn, type CloudTransaction, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type HandleCallbackOptions, type LaunchHint, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, type PodAppAuth, type PodAppAuthConfig, type PodAppPaths, type PodClient, type PodClientOptions, PodConnection, type PodError, type PodErrorCode, PodGrant, PodIssuer, type PodResult, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCloudTransaction, type SealedCookieStoreOptions, type SealedTransaction, type StartCloudConnectOptions, type StartConnectOptions, type StartedCloudConnect, type StartedConnect, TRANSACTION_TTL_MS, acceptCloudReturn, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudBaseUrl, cloudConnectAvailable, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };
+export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, CLOUD_TRANSACTION_TTL_MS, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, type CloudConnectConfig, type CloudReturn, type CloudTransaction, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodEntityFacet, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCloudTransaction, type SealedCookieStoreOptions, type SealedTransaction, type StartCloudConnectOptions, type StartConnectOptions, type StartedCloudConnect, type StartedConnect, TRANSACTION_TTL_MS, acceptCloudReturn, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudBaseUrl, cloudConnectAvailable, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };