@synap-core/sdk 1.5.0 → 1.5.2

package/AGENTS.md

@@ -0,0 +1,250 @@
+# AGENTS.md — @synap-core/sdk
+
+Typed tRPC client for a Synap data pod. This is how an app reads and writes a pod.
+
+## Create a client
+
+```ts
+import { createSynapClient } from "@synap-core/sdk";
+
+const synap = createSynapClient({
+  podUrl: "https://pod.example.com", // NO trailing slash, NO /trpc suffix
+  sessionToken: process.env.SYNAP_SESSION_TOKEN, // OR apiKey (local-mode token only), OR omit for cookie auth
+  workspaceId: process.env.SYNAP_WORKSPACE_ID ?? "",
+});
+
+const me = await synap.users.me.query();
+const list = await synap.entities.list.query({});
+const res = await synap.entities.create.mutate({ /* ... */ });
+```
+
+The returned object is a fully-typed tRPC client — every pod router is available
+with autocomplete. Types come from `@synap-core/api-types`.
+
+## Auth (pick one)
+- `apiKey` — the LOCAL_MODE token only. Hub / user API keys (`synap_hub_*`, `synap_user_*`) are refused by `/trpc` and throw here; use `@synap-core/hub-rest-client` on `/api/hub/*`.
+- `sessionToken` — Ory Kratos token, sent as `X-Session-Token`. Non-browser clients.
+- omit both — ambient Kratos cookie (browser, same-origin only).
+
+Bootstrap a machine credential with `@synap-core/auth-bootstrap`
+(`setupAgent` → API key, `handshake` → session token). Browser sign-in:
+`@synap-core/auth`. React bindings: `@synap-core/react`. Realtime:
+`@synap-core/sdk-realtime`.
+
+## Start your app's user from a template
+
+To let a user begin from a ready-made workspace (a CRM, a research desk, …)
+instead of a blank pod, use the `@synap-core/react` hooks — **discovery reads the
+pod's ONE marketplace catalog, apply happens on the pod**:
+
+```tsx
+import { useTemplateCatalog, useInstallTemplate } from "@synap-core/react";
+
+function TemplatePicker() {
+  const { data } = useTemplateCatalog({ query: "crm" }); // browse installable templates
+  const install = useInstallTemplate();
+
+  return data?.templates.map((t) => (
+    <button
+      key={t.slug}
+      onClick={() =>
+        install.mutate(
+          { slug: t.slug },
+          { onSuccess: (r) => console.log("workspaceId", r.workspaceId) },
+        )
+      }
+    >
+      {t.name}
+    </button>
+  ));
+}
+```
+
+- **Discovery** — `useTemplateCatalog()` lists the pod's installable WORKSPACE
+  templates (slug + name + description + tier), read from the pod-local catalog
+  cache. Metadata only; no definition is downloaded to the client.
+- **Install by slug** — `useInstallTemplate().mutate({ slug })` resolves the
+  freshest definition on the pod and provisions through the SAME shared engine
+  the in-app installer uses (idempotent, tier-gated, governed). It returns the
+  created/reconciled `workspaceId`.
+
+Prefer this over hand-building a `definition` for `workspaces.createFromDefinition`
+— you only need a catalog slug. Server door: `trpc.workspaces.installFromCatalog`.
+
+## Public sites (no credentials): `@synap-core/sdk/public`
+
+For a public website use the credentialless entry, never the root client:
+`createPublicClient({ podUrl })` → `readShare`, `getForm`, `submitForm`,
+`getSite`, `listCollection`, `getRecord`. Results are `{ ok: true, data }` or a
+typed `{ ok: false, error }` (`not_found` is one uniform miss). Render with the
+same entry's models (`toFieldModels`, `submitFailure`, `toSharePageModel`,
+`parseSafeMarkdown`, `formatPublicValue`, `toCollectionPageModel`,
+`toRecordViewModel`); never render pod content as HTML in your page. The one
+exception is a body the pod serves as `format: "html"` (a shared HTML document:
+the models give it as `html`, with no blocks): render it ONLY as
+`<iframe sandbox="" srcdoc={html}>` (an empty `sandbox`, never `src`), so its
+scripts never run and it cannot reach your page. Test and preview with
+`createMockPod()` from `@synap-core/sdk/testing` (no network; `MOCK_TOKENS.htmlShare`
+is an html share).
+
+## Pod-app sign-in (server-only): `@synap-core/sdk/connect`
+
+For an app that acts in a person's OWN pod (not a public site): `createPodAppAuth`
+gives the connect / callback / disconnect / client-metadata route handlers, a
+sealed session cookie, `refreshIfNeeded` for `proxy.ts`, and `client(connection)`
+for Hub REST reads and governed writes. Rules:
+- import it ONLY in server files (route handlers, `proxy.ts`, server-only
+  modules); it throws in a browser. Never put the token or
+  `SYNAP_APP_SESSION_SECRET` in a `NEXT_PUBLIC_*` variable;
+- never hand-roll PKCE, `state`, `iss` checks or cookie sealing: the SDK owns them;
+- a write's `proposed` is success: link `reviewUrl`, never retry (an agent
+  connection's writes are proposals; a person connection's, `client.actsAs ===
+  "person"`, apply directly, as the person: say "saved", not "sent for review");
+- a Hub path is pod-relative with each segment encoded (`encodeURIComponent`);
+  a bad one answers `invalid`, never throws;
+- `unauthorized` with `refreshable` (a server component's client): send the
+  visitor through `proxy.ts` once with `refreshIfNeeded(request, { force: true })`;
+  a route handler or action passes `persist` to `client()` and the SDK renews
+  once itself. `unauthorized` without it = the connection is gone: connect again;
+- `pod_moved`: connect again with the pod's new address (never follow the redirect);
+- `space` / `spaceHint` is a hint the pod may ignore: never promise a preselected space;
+- `http://localhost` signs in to the mock pod only; a real pod needs the app on https;
+- read with the typed methods (`listEntities`, `getEntity`, `getEntityConnections`,
+  `getDocument`, `listFocusSessions` + `humanSlots`, `getFileUrl`,
+  `listPendingProposals({ proposalIds })`) rather than raw `get`; approve with
+  `approveProposal` (refused locally for an agent connection);
+- the space made from a template: `client.spaces().find((s) => s.templateSlug === slug)`
+  (absent on pods that do not send it: keep a fallback);
+- "Ask again" = the connect form with `prompt=consent`; "Waiting for review: N" =
+  `client.listPendingProposals()` (needs `proposal.read` in `requests`); the
+  space switcher = `client.spaces()`; "Manage access in your pod" =
+  `connection.manageUrl`, only when present (never build a pod URL);
+- Synap Cloud: only when `synap.cloudConnectAvailable`; the connect page forwards
+  a launch with `cloudState` to GET `paths.cloud` and never acts on it itself;
+- "expired" vs "connect your pod": `synap.readLapsed()` / `RefreshOutcome.lapsed`;
+- Next 16 `proxy.ts`: skip prefetches in the matcher (`missing` the
+  `next-router-prefetch` header); the proxy itself cannot see them;
+- test with `createMockAuthServer()` (and `createMockCloud()`) from `@synap-core/sdk/testing`;
+  seed it from one JSON file (`parseMockPodSeed`), never fixtures in app code.
+
+## What a pod app can see and do
+
+Needs a pod with the space-reach release. On an
+older pod an app sees only rows whose own space is granted, so the pod-wide
+records roled in S (usually people and companies) come back empty; the mock already models the rule below.
+
+- **Spaces are the person's choice.** The consent screen lets the person pick
+  one or more spaces, per permission. The app gets exactly those, nothing else.
+  A read grant is per kind too: `entity.person.read` shows people (own and
+  roled pod-wide), not companies; request every kind the app lists.
+- **Where an entity lives.** In a space, or pod-wide (`workspaceId` null): people
+  and companies are ONE identity across the pod. A **role** (facet) puts a
+  pod-wide entity INTO a space: a lead, contact or client in a CRM.
+- **What read on space S shows.** What a member of S sees: S's own records, plus
+  any other record of the pod (usually people and companies) that has a live role
+  in S, read-only: a pod-wide one, or one of another space with a role stamped in
+  S. A record with no role in a granted space is never returned (a list omits it,
+  `getEntity` is a 404). By default an entity row carries no list of its roles: ask for the role
+  you want with the kind and the space (`listEntities({ workspaceId: S,
+  facetSlug: "lead" })`), and add `includeFacets: true` to get each row's roles
+  (`facetSlugs`, `facets` with their status and properties; pod with that release).
+- **Related records.** A related record shows only when it has a role in a
+  granted space itself. An edge between two pod-wide records is not readable by
+  an app (`getEntityConnections` omits it); an edge to a record of the space is.
+- **List them.** The people roled in S come with S's own:
+
+  ```ts
+  const client = auth.client(connection);
+  const res = await client.listEntities({ workspaceId: S, profileSlug: "person" }); // GET /entities?workspaceId=S&profileSlug=person
+  if (res.ok) res.data; // PodEntity[]: own rows and roled ones (pod-wide: workspaceId null)
+  ```
+
+  Without `workspaceId` you get every granted space plus the records
+  roled in any of them. List people and companies with `listEntities({
+  workspaceId, facetSlug })` or `profileSlug`; never pass `includePodWide: false`
+  for them (it can hide roled pod-wide records).
+- **Writes.** Every create passes `workspaceId` (a granted space): without it a
+  record forks into the space or is refused. Creating an entity in S is a
+  proposal, and its `facets` attach when it is approved (`"proposed"` is
+  success; see "Writes are governed"). An app cannot add a role to an existing
+  entity (`POST /entities/:id/facets`) nor change a role on a pod-wide record
+  (`PATCH /facets/:id`): the pod refuses both with 403, writes nothing and files
+  no proposal. Editing the core fields of a pod-wide person is also outside an
+  S-only grant: the pod refuses it (403 "grant does not allow" on the connected
+  person's own record, 404 on a teammate's), writes nothing and files no
+  proposal. Do not build any of these edits.
+  Creating a person whose email matches a pod-wide person that has a role in S
+  is refused (403). If the match has no role in S, a separate person is created
+  in S (the pod does not merge them yet). Before creating, check
+  `listEntities({ workspaceId: S, profileSlug: "person" })` so the app does not
+  make a duplicate. (The mock does not model identity by email: it never refuses
+  this create.)
+- **Aggregate doors** (`/knowledge/*`, `/memory/search`, `/entities/retrieve`,
+  i.e. search and ask) answer `GRANT_DOOR_UNSUPPORTED` to a space-scoped app.
+  List by kind and space instead.
+- **Ask for the spaces you need, never hard-code an id.** Offer templates with
+  `createPodAppAuth({ templates: ["crm"] })`, then find the space the person
+  granted with `client.spaces().find((s) => s.templateSlug === slug)?.workspaceId`
+  (the kit's `podApp.templates` / `spaceFor(slug)` are this). Keep a fallback to
+  the first granted space: the pod may not send `templateSlug`.
+- **Test it.** In the mock, a seed entity with `workspaceId: null` and
+  `facets: [{ facetId, slug, properties?, status?, workspaceId }]` models a role
+  in the space `workspaceId` (with the role's own fields, e.g. `leadStage`, in
+  `properties`). Seed input only: the mock answers them only when
+  `includeFacets` asks, as the pod. (Mock seed detail, never branch on it:
+  `sharedRole: true` stores the role pod-wide and grants it to `workspaceId`.)
+  `seedRoles: [{ profileSlug, workspaceId }]` is a deprecated shorthand (no id,
+  no fields; removed in 2.0): never state a role in both.
+
+## Sign-in errors and recovery
+
+A refusal is typed, never a generic 403 or failure. `PodError.recovery` names the next step:
+
+| `error.code` | When | `recovery` |
+| --- | --- | --- |
+| `step_up_required` | 403 at a credential door (approving a proposal that widens who or what can reach the pod) for a Synap app whose device last re-confirmed at the pod more than 15 minutes ago | `prompt_login` |
+| `email_unverified` | 409 problem `CP_ACCOUNT_EMAIL_REQUIRED`: Synap Cloud has no verified email for the person | `verify_email` |
+| `origin_insecure` | 409 problem `FEDERATED_APPLICATION_ORIGIN_INSECURE`: Synap Cloud vouches an app origin over HTTPS only | `use_https` |
+
+- **Step-up.** Send the person through the connect handler with `prompt=login`
+  (`form { pod, next, prompt: "login" }`; `next` = the page that retries). They
+  re-confirm AT THE POD (a Synap Cloud sign-in never counts; consent stays a
+  browser act), the callback redeems the code with the connection's refresh token
+  and stores the re-confirmed connection, then retry the refused call ONCE. The
+  pod's Hub REST answer carries only the message, no `reasonCode`; the SDK reads
+  both. Only a Synap app (`actsAs: "person"`) can hit this: the review door is
+  the one door of the SDK that reaches a credential check.
+- **The two Control Plane problems** are JSON the Control Plane sends to the pod
+  and to its own API. This SDK never calls that API (Synap Cloud is browser
+  redirects), so they reach an app only if a door relays them; the SDK types
+  them if one does.
+- **`synap_acts_as`** is read from every token response and never carried over:
+  a refresh that says `agent`, or nothing, makes an agent connection.
+- **Moved pods.** A redirect is never followed. An old name that answers 308
+  (`you.synap.live`) is retried as `you.pod.synap.live`, and the connection stores
+  the issuer that pod's metadata names. A pod renamed to anything else is `pod_moved`:
+  connect again with its new address.
+- **Dev.** `http://localhost` signs in to the SDK's mock pod, or to a local
+  Control Plane started with `CP_ALLOW_DEV_ORIGINS=true`; never to api.synap.live
+  (`origin_insecure`). If an app sends a person to the synap.live sign-in, pass
+  only the Control Plane's `reason`: `expired`, `signed_out` or `refused`.
+- **Test it.** The mock models each refusal as an opt-in failure
+  (`failures: { "/users/me": "step_up_required" | "email_unverified" |
+  "origin_insecure" }`), a stale device (`requireStepUp: true`, `expireStepUp()`),
+  and `setActsAs(...)`.
+
+## Writes are governed — `"proposed"` is SUCCESS
+
+A mutation resolves to `approved | proposed | denied`. **`proposed` = queued for
+the pod owner's review, not an error.** Never treat it as a failure, never retry
+it (duplicates), surface the review. `denied` = no permission; don't retry.
+
+## Install (pin the major)
+
+```bash
+npm install @synap-core/sdk@^1.0.0
+```
+
+Do not install unpinned `@synap-core/sdk` — old `0.x` on the registry is a
+different, abandoned package. Verify with a clean-dir install:
+`node -e "console.log(typeof require('@synap-core/sdk').createSynapClient)"` → `function`.

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # @synap-core/sdk changelog
 
+## 1.5.3 (unreleased)
+
+Sign-in hardening after the 2026-10-23 pod and Control Plane changes. Not published.
+Additive; `PodErrorCode` gains three members, so an exhaustive `switch` over it
+needs a case (semver would call that a minor).
+
+- **Typed refusals with a recovery** (`PodError.recovery`: `PodRecovery`):
+  `step_up_required` (a stale Synap-app device at a credential door; the Hub
+  REST body is `{ error: <message> }`, read by message or by `reasonCode`),
+  `email_unverified` (409 `CP_ACCOUNT_EMAIL_REQUIRED`), `origin_insecure`
+  (409 `FEDERATED_APPLICATION_ORIGIN_INSECURE`). They were `forbidden` / `conflict`.
+- **Step-up**: the connect handler takes `prompt=login`; the callback redeems the
+  code with the connection's refresh token (`synap_device_refresh_token`), as the
+  pod requires of a Synap app's re-confirmation (without it the pod answers
+  `invalid_grant`). `startConnect({ prompt: "login" })`; `handleCallback({ current })`.
+  It is asked of the pod only, never through Synap Cloud.
+- **Behaviour change**: `prompt=login` on the connect form used to be ignored
+  (a live connection went straight to `next`); it now starts a step-up.
+- Mock: `failures` modes `step_up_required`, `email_unverified`, `origin_insecure`;
+  `requireStepUp` / `expireStepUp()` (a stale device refused at approve, unlocked by
+  a step-up code); `setActsAs()`; a code from `prompt=login` needs the device's
+  refresh token and one without it must not carry one, as the pod.
+- Docs: AGENTS.md, "Sign-in errors and recovery" (dev origins, `reason`, moved pods).
+- Checked, no change needed: `synap_acts_as` is read from every response and never
+  carried over (now tested end to end); the SDK verifies no Control Plane token (no
+  JWKS code to add); it keeps no copy of the Synap app ids (its review-verb check is a
+  looser `*.synap.live` pre-check; the pod decides).
+
+## 1.5.2 (unreleased)
+
+Mock pod and docs only; no runtime change. Not published.
+
+- **AGENTS.md now ships in the package** (`files`), so `node_modules/@synap-core/sdk/AGENTS.md`
+  exists; 1.5.1 left it out. A test (`npm pack --dry-run`) keeps AGENTS.md,
+  README.md and CHANGELOG.md in the tarball. The README links the file by path.
+
+Mock behaviour changes (as the pod; they can move a consumer's tests):
+
+- **`GET /entities` and `GET /entities/:id` narrow by kind, as the pod's
+  kindClause**: `entity.<kind>.read` reads that kind only (rows of the space and
+  roled pod-wide rows alike); `entity.read` reads every kind. 1.5.1 treated any
+  `entity.<kind>.read` as every kind, so a page could list people on the mock
+  that an `entity.post.read`-only app never sees on the pod. A mock test that
+  seeds people or companies must request and be granted their kind.
+- **`POST /entities/:id/facets` answers 403** (an app cannot add a role to an
+  existing entity), and **`PATCH /facets/:id` of a pod-wide record's role
+  answers 403**: nothing written, no proposal. Both used to be proposed.
+- **`GET /entities/:id/connections` omits an edge between two pod-wide
+  records** (a pod-wide edge is owner-only; not readable by an app granted S).
+- **`PATCH /entities/:id` of a pod-wide row, as the pod**: 403 "grant does not
+  allow" when the row's `userId` is the token's user, 404 (empty body) when it is
+  another user's (a teammate's record, outside the write floor). A seed row
+  with no `userId` keeps 403. Neither writes nor files a proposal. AGENTS.md,
+  "What a pod app can see and do", states it.
+- Docs: that section now also says every create passes `workspaceId`, creating
+  in S files a proposal whose `facets` attach on approval, and a related record
+  shows only when it has a role in a granted space itself.
+
+## 1.5.1
+
+What a pod app sees of a person's pod, and the roles (Kind + Facets) on it: the
+mock pod models the reach rule and answers roles as the pod does, so an app
+that lists by role (a CRM's leads) shows its pages on mock data; the typed
+client asks for roles; mock mode may ask for the review verbs. Additive, except
+the mock behaviours under "Behaviour changes (mock)".
+
+### `@synap-core/sdk/connect`
+
+- **`listEntities({ facetSlug?, includeFacets? })`**: only the entities wearing
+  a role, and each row's roles on it (`PodEntity.facetSlugs`, `PodEntity.facets:
+  PodEntityFacet[]` = `{ facetId, slug, properties, status }`, present only on a
+  row that wears one). `includeFacets` is sent only when true. It needs a pod
+  whose `GET /entities` supports `includeFacets`; on an older pod it is ignored
+  and the rows come back without roles.
+- **Mock mode may ask for the review verbs**: `buildClientMetadata` (and so
+  `createPodAppAuth`) accepts `proposal.approve` / `proposal.reject` on an http
+  loopback `appUrl` (`localhost`, `127.0.0.1`, `[::1]`), so an app that requests
+  them starts mock mode, smoke and shots. A real pod refuses an http client_id
+  outright (synap-backend `client-id-url.ts`); every other origin is refused
+  as in 1.5.0.
+
+### `@synap-core/sdk/testing`
+
+- **The mock models the pod's reach rule**: `GET /entities`, `GET /entities/:id`
+  and connection neighbours answer rows of a granted space plus pod-wide
+  entities (`workspaceId` null) with a role in a granted space. A pod-wide
+  entity with no role in a granted space, and any row of an ungranted space, is
+  never answered (a miss is the pod's empty 404). Reads need an
+  `entity.<kind>.read` (or `entity.read`) grant in the token's scope.
+- **Seeded roles, one field: `MockSeedEntity.facets`** (`MockSeedFacet`:
+  `facetId`, `slug`, `properties?`, `status?`, and seed-only `workspaceId`: the
+  space whose members see the role, stamped there or a pod-wide facet of a role
+  granted to it). Seed input only: no answer carries them unless `includeFacets`
+  asks. Validated by `parseMockPodSeed`.
+- **`seedRoles`** (`[{ profileSlug, workspaceId }]`), **deprecated: use
+  `facets`; removed in 2.0.** A shorthand desugared into `facets` when the seed
+  is read (a generated `facetId`, no overlay); a role stated in both on one
+  entity is a parse error naming the entity.
+- **`facets[].sharedRole`** (seed only, never served, validated): the role is
+  stored pod-wide and granted to `workspaceId` (default: stamped in it). It
+  differs from a stamped role in `includePodWide=false` on a space lens, and in
+  `GET /entities/:id/facets` (its facet answers `workspaceId` null).
+- **`PATCH /entities/:id` of a pod-wide row** is refused under a space grant
+  (the mock answers 403; 1.5.2 pins 403 vs 404): nothing written, no proposal.
+- **A row of another space T with a role stamped in S** is visible to an app
+  granted S (list and by id), as to a member of S; a shared role does not
+  reach a row of another space.
+- **`GET /entities`** as the pod (`rest/entities.ts`):
+  - `includePodWide=false` on a workspace lens drops only the pod-wide rows
+    reached through a SHARED role (the pod keeps those with a role stamped in
+    the space);
+  - `facetSlug` filters by a role the read sees: what a member of a granted
+    space sees (a workspace lens, that space's roles only; never a role of a
+    space outside the grant);
+  - a `profileSlug` naming a role matches its wearers too;
+  - `includeFacets=true` adds `facetSlugs` + `facets` to the rows wearing one.
+- **`GET /entities/:id/facets`**: `{ facets: [{ facet, profile, effectiveProperties }] }`
+  (`getEffectiveFacets` under the token's floor; the mock knows a role by its
+  slug only, so `profile` is `{ id: "profile_<slug>", slug, profileKind: "role" }`
+  and `effectiveProperties` is empty). A miss, or an entity out of reach, is the
+  pod's empty 404.
+- **`GET /entities/:id/connections`**: the far end's `facetSlugs` come from its
+  seeded roles, under the read's `workspaceId` lens.
+- Not mirrored: the mock knows no profile catalog (an undeclared `facetSlug`
+  answers `[]` where the pod answers 404; `facetProfileId` is not read), and it
+  serves neither `q` (the pod refuses it to a space-scoped key, and answers 400
+  to `q` with `includeFacets`) nor `scope=all`.
+- Docs: AGENTS.md, "What a pod app can see and do". Needs a pod with the
+  space-reach release (an older pod returns no pod-wide rows to an app).
+
+### Behaviour changes (mock)
+
+These move test results for an existing 1.5.0 consumer; check your mock tests
+after upgrading.
+
+- An entity list without `workspaceId` no longer returns rows of spaces the
+  token was not granted.
+- A pod-wide seed row (`workspaceId: null`) with no role in a granted space is no
+  longer listed, and `GET /entities/:id` answers the empty 404 (a 1.5.0 seed that
+  expected such rows must give them a role: `facets`).
+- A mock token with no `entity.<kind>.read` / `entity.read` grant reads no entity.
+- `includePodWide=false` on a space lens keeps the pod-wide rows with a role
+  stamped in the space (it dropped every pod-wide row).
+- `GET /entities` and `GET /entities/:id` no longer echo a seed row's
+  `facets` / `facetSlugs` (the pod's `entityToWire` never sends them).
+- `PATCH /entities/:id` of a `workspaceId: null` row answers 403 and writes
+  nothing (it was applied or proposed).
+
 ## 1.5.0
 
 For Content Studio, the first pod app on `@synap-core/sdk/connect`, plus a

package/README.md

@@ -122,6 +122,8 @@ SDK refuses out-of-bounds `offset`/`limit`/`sort` locally, without a request),
 pass `ifNoneMatch` from a browser: the doors allow no cross-origin request header
 but `Content-Type`, so the preflight fails (browsers revalidate on their own).
 
+What a pod app can see and do (spaces, roled records, writes): read the section "What a pod app can see and do" of `AGENTS.md`, shipped in this package (`node_modules/@synap-core/sdk/AGENTS.md`).
+
 ## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0, 1.4.0, 1.5.0)
 
 An app that reads and writes a person's OWN pod connects as an OAuth 2.1 public
@@ -176,7 +178,7 @@ export const config = {
 const connection = await synap.readConnection((await headers()).get("cookie"));
 if (!connection) redirect("/connect");
 const pod = synap.client(connection);
-const res = await pod.post("/entities", { profileSlug: "post", title: "Hello" });
+const res = await pod.post("/entities", { profileSlug: "post", workspaceId: pod.spaces()[0].workspaceId, title: "Hello" }); // always a granted space
 if (res.ok && res.status === "proposed") showPending(res.reviewUrl); // success: queued for review, never retry
 if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupported | rate_limited (retryAfterSec) | pod_unreachable | pod_moved | …
 ```
@@ -290,6 +292,7 @@ const pod = synap.client(connection);
 // Typed reads: PodResult<T>, the same codes as get/post (expired | unauthorized | forbidden |
 // door_unsupported | not_found | invalid | rate_limited | pod_unreachable | server | …)
 await pod.listEntities({ workspaceId, profileSlug: "post", limit: 1000 }); // PodEntity[]
+await pod.listEntities({ workspaceId, facetSlug: "lead", includeFacets: true }); // the wearers of a role, each with facets
 await pod.getEntity(id);                                                 // PodEntity, not_found on a miss
 await pod.getEntityConnections(id);                                      // { connections, counts }
 await pod.getDocument(documentId);                                       // { content, revision, sections, … }
@@ -390,6 +393,19 @@ const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8")); // {
 const pod = createMockAuthServer({ seed, actsAs: "person" });
 ```
 
+1.5.1: an entity's roles ride on its seed row as `facets`, the shape
+`includeFacets=true` answers, plus the space whose members see it
+(`workspaceId`, seed only). A role in a granted space puts a pod-wide row in the app's reach
+(`AGENTS.md`, "What a pod app can see and do"). `GET /entities` then filters by
+`facetSlug`, drops a lens's pod-wide rows on `includePodWide: false`, and puts
+`facetSlugs` + `facets` on a row only when asked; `GET /entities/:id/facets` is
+served:
+
+```json
+{ "id": "ent_ada", "profileSlug": "person", "title": "Ada", "workspaceId": null,
+  "facets": [{ "facetId": "fct_1", "slug": "lead", "properties": { "leadStage": "prospect" }, "status": "new", "workspaceId": "ws_crm" }] }
+```
+
 
 ```typescript
 const pod = createMockAuthServer();

package/dist/connect.cjs

@@ -682,14 +682,32 @@ function renewalError(err) {
       return { code: "server", status: null, detail };
   }
 }
+var STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
+var CP_PROBLEMS = {
+  CP_ACCOUNT_EMAIL_REQUIRED: { code: "email_unverified", recovery: "verify_email" },
+  FEDERATED_APPLICATION_ORIGIN_INSECURE: { code: "origin_insecure", recovery: "use_https" }
+};
+function isStepUp(obj) {
+  const data = (v) => v && typeof v === "object" ? v : {};
+  const nested = data(data(obj.error).data).reasonCode ?? data(obj.data).reasonCode ?? obj.reasonCode;
+  return nested === "STEP_UP_REQUIRED" || obj.error === STEP_UP_MESSAGE || obj.message === STEP_UP_MESSAGE;
+}
+function classifyRefusal(status, body) {
+  const obj = body && typeof body === "object" ? body : {};
+  if (status === 403) {
+    if (isStepUp(obj)) return { code: "step_up_required", recovery: "prompt_login" };
+    return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden" };
+  }
+  const problem = typeof obj.code === "string" ? CP_PROBLEMS[obj.code] : void 0;
+  return problem ?? { code: "conflict" };
+}
 function errorFor(status, body, retryAfter, now) {
   const obj = body && typeof body === "object" ? body : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : void 0;
   const base = { status, ...detail !== void 0 ? { detail } : {} };
   if (status === 401) return { code: "unauthorized", ...base };
-  if (status === 403) return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden", ...base };
+  if (status === 403 || status === 409) return { ...classifyRefusal(status, body), ...base };
   if (status === 404) return { code: "not_found", ...base };
-  if (status === 409) return { code: "conflict", ...base };
   if (status === 400 || status === 422) return { code: "invalid", ...base };
   if (status === 429) {
     const retryAfterSec = retryAfterSeconds(retryAfter, now);
@@ -860,7 +878,10 @@ function createPodClient(connection, opts = {}) {
       limit: clamp(opts2.limit, 1, 1e3),
       offset: clamp(opts2.offset, 0, Number.MAX_SAFE_INTEGER),
       sort: opts2.sort,
-      includePodWide: opts2.includePodWide
+      includePodWide: opts2.includePodWide,
+      facetSlug: opts2.facetSlug,
+      // Sent only when asked: the default request stays the 1.5.0 one.
+      includeFacets: opts2.includeFacets ? true : void 0
     }, (data) => Array.isArray(data) ? data.filter(hasId) : null);
   }
   async function getEntity(id) {
@@ -1022,7 +1043,7 @@ async function startConnect(opts) {
   url.searchParams.set("code_challenge_method", "S256");
   if (resource) url.searchParams.set("resource", resource);
   if (opts.spaceHint) url.searchParams.set("synap_space_hint", opts.spaceHint);
-  if (opts.prompt === "consent") url.searchParams.set("prompt", "consent");
+  if (opts.prompt === "consent" || opts.prompt === "login") url.searchParams.set("prompt", opts.prompt);
   const tx = {
     v: 1,
     issuer: issuer.issuer,
@@ -1034,6 +1055,7 @@ async function startConnect(opts) {
     verifier,
     resource,
     next: opts.next ?? null,
+    ...opts.prompt === "login" ? { stepUp: true } : {},
     createdAt: now
   };
   const expiresAt = now + TRANSACTION_TTL_MS;
@@ -1091,13 +1113,16 @@ async function handleCallback(opts) {
     code_verifier: tx.verifier
   });
   if (tx.resource) body.set("resource", tx.resource);
+  const device = tx.stepUp && opts.current && opts.current.actsAs === "person" && opts.current.podUrl === tx.issuer && opts.current.clientId === tx.clientId ? opts.current : null;
+  if (device?.refreshToken) body.set("synap_device_refresh_token", device.refreshToken);
   const json = await tokenRequest(tx.tokenEndpoint, body, "token", opts);
   const connection = parseTokenResponse(json, {
     podUrl: tx.issuer,
     clientId: tx.clientId,
     tokenEndpoint: tx.tokenEndpoint,
     revocationEndpoint: tx.revocationEndpoint,
-    now: (opts.now ?? Date.now)()
+    now: (opts.now ?? Date.now)(),
+    ...device ? { previous: device } : {}
   });
   return { connection, next: tx.next };
 }
@@ -1424,6 +1449,10 @@ var PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
 function isSynapAppOrigin(origin) {
   return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
 }
+function isMockModeOrigin(origin) {
+  const url = new URL(origin);
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}
 function assertAppPermission(permission, origin) {
   const segs = permission.split(".");
   const fail = (why) => {
@@ -1433,7 +1462,7 @@ function assertAppPermission(permission, origin) {
     fail("is not <subject>[.<kind>].<action> in lowercase (no *)");
   }
   if (segs.length === 3 && segs[0] !== "entity") fail(`names a kind, but "${segs[0]}" has none (only entity does)`);
-  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && isSynapAppOrigin(origin)) return;
+  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && (isSynapAppOrigin(origin) || isMockModeOrigin(origin))) return;
   if (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
     fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
   }
@@ -1599,7 +1628,8 @@ function createPodAppAuth(config) {
     const pod = formField(form, "pod")?.slice(0, 512) ?? "";
     const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
     const space = formField(form, "space");
-    const prompt = formField(form, "prompt") === "consent" ? "consent" : null;
+    const asked = formField(form, "prompt");
+    const prompt = asked === "consent" || asked === "login" ? asked : null;
     try {
       if (!prompt && await liveConnectionTo(request, pod)) return redirect(new URL(next, origin).href);
       return await toPod({ pod, next, space, prompt });
@@ -1616,6 +1646,7 @@ function createPodAppAuth(config) {
         ...flow,
         callbackUrl: request.url,
         transaction,
+        current: await store.read(request).catch(() => null),
         clientId,
         redirectUri,
         secret: config.secret