@jskit-ai/agent-docs 0.1.283 → 0.1.285

package/skills/jskit/references/heuristics/server-search.md

@@ -5,28 +5,26 @@
 Use when:
 - a CRUD list accepts `q` or other server-side query params
 - a resource needs alias filters such as `onlyArchived -> archived`
-- a list needs access-scoped filters that the repository injects before querying
+- a list needs filters with compound SQL (status buckets, null/not-null semantics)
 - the user asks where search belongs on the server in a current JSKIT app
 
 Core rule:
-- for current JSKIT CRUD apps, the server search contract lives in `resource.searchSchema` on the internal JSON REST path
+- the server search contract lives in the table resource's `searchSchema`; a server-only entry (one with `applyFilter`) goes in the owner's `owns` entry, `{ resource, searchSchema }`
 - route validators decide which public query keys HTTP callers may send
-- repositories may add internal-only filter keys before forwarding the query to JSON REST
-- structured list filters should use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization are derived from one definition
+- who may see a row is never a filter: it is the row policy ([row-policies.md](./row-policies.md)), applied by the handle on every read
+- structured list filters should use `createCrudListFilterContract(...)` so route/action validators, the search schema, and query normalization are derived from one definition
 
-The standard CRUD repository pattern follows this path:
+The standard CRUD service lists through the table's handle:
 
 ```js
-return api.resources.contacts.query({
-  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, contactListFilterContract.toJsonRestQuery(query)),
-  format: "jsonapi"
-}, createJsonRestContext(context));
+// what defineCrudFeature's service does; a decorateService list maps structured filters first
+return repository.query(buildJsonRestQueryParams("contacts", contactListFilterContract.toJsonRestQuery(query)), { ...options, format: "jsonapi" });
 ```
 
 The normal layer split is:
 1. `actions.js` / `registerRoutes.js`: accept and validate public query keys
-2. `repository.js`: add internal-only filter keys such as visibility scope, or call `listFilterContract.toJsonRestQuery(query)` for structured filters
-3. provider/resource registration: merge backend filter behavior into JSON REST with `createJsonRestResourceScopeOptions(resource, { searchSchema })`
+2. the feature's `decorateService`: call `listFilterContract.toJsonRestQuery(query)` for structured filters before the standard `list`; visibility belongs in the row policy, never in a filter key
+3. the owner feature: backend filter behavior goes in the table resource's `searchSchema`, or a server-only one in its `owns` entry (`{ resource, searchSchema }`)
 
 ### Shared list and HTTP transport
 
@@ -74,13 +72,13 @@ Do not use `search: true` when:
 - you want a different public key than the storage field
 - you need one key to search several fields
 - you need custom SQL semantics
-- you need an internal-only injected filter
+- you need a key the service maps from a structured filter
 
 Use explicit `searchSchema` when:
 - the public key differs from the field name
 - one key searches multiple fields
 - the route/API contract should stay stable even if field names change
-- the filter is internal-only and injected by the repository
+- the key is internal and only the service's structured-filter mapping sends it
 - you need to override the simple `search: true` behavior
 
 Example:
@@ -110,32 +108,23 @@ Important merge rule:
 Use `applyFilter` when:
 - `actualField`, `oneOf`, and normal operators are not enough
 - the filter needs compound SQL
-- the filter encodes visibility rules, status buckets, or null/not-null semantics that are more complex than a direct field comparison
+- the filter encodes status buckets or null/not-null semantics that are more complex than a direct field comparison (never visibility: that is the row policy)
 
 Example:
 
 ```js
 searchSchema: {
-  "__viewerAccess": {
+  dueState: {
     type: "string",
     applyFilter(query, rawValue) {
       const value = String(rawValue || "").trim();
-
-      query.whereNull("deleted_at");
-      if (value === "privileged") {
+      if (value === "overdue") {
+        query.whereNull("paid_at").where("due_at", "<", new Date());
         return;
       }
-
-      const userId = value.startsWith("user:")
-        ? String(value.slice(5) || "").trim()
-        : "";
-
-      query.where(function () {
-        this.where("user_added", 0);
-        if (userId) {
-          this.orWhere("added_by_user_id", userId);
-        }
-      });
+      if (value === "paid") {
+        query.whereNotNull("paid_at");
+      }
     }
   }
 }
@@ -143,6 +132,7 @@ searchSchema: {
 
 Keep `applyFilter` focused on query semantics:
 - build the SQL/knex filter there
+- read only the row's own columns in a filter a `patchWhere` or `deleteWhere` decides on: one that reads another table through a subquery is not detected, and is no compare-and-set on MySQL and MariaDB
 - do not put permission checks there
 - do not turn it into a second service layer
 
@@ -167,7 +157,7 @@ input: composeSchemaDefinitions([
 That means:
 - pagination, `q`, parent filters, includes, sparse fieldsets, and the
   structured filter keys remain one standard group
-- the repository may still add internal-only keys later
+- the service may still map structured keys before the standard list
 
 Use the same `listFilterQueryValidator` option with
 `createCrudJsonApiRouteContracts(...)` at the route boundary. The layers
@@ -196,14 +186,17 @@ const receivalListFilterContract = createCrudListFilterContract(
 );
 ```
 
-Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` when registering the JSON REST resource. Use `receivalListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`.
+Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` as the `searchSchema` of the table's `owns` entry. Use `receivalListFilterContract.toJsonRestQuery(query)` in the service's `list` before the standard one.
 
 That contract preserves arrays for `enumMany` and `recordIdMany`, maps range filters to internal JSON REST search keys, and keeps those internal keys out of the public HTTP query contract.
 
 Do not add route validators for:
-- repository-injected internal keys such as `"__viewerAccess"`
+- internal keys that only the service's structured-filter mapping sends
 - filters that must never be supplied by the client directly
 
+Who may see a row is never a search key at all: it is the row policy, which
+the handle applies to every read whatever the query says.
+
 ## Recommended Shapes
 
 Simple direct field exposure:
@@ -236,15 +229,10 @@ searchSchema: {
 }
 ```
 
-Repository-injected internal filter:
+Visibility, by the owner, on every read:
 
 ```js
-function buildScopedQuery(query = {}, context = null) {
-  return {
-    ...(query || {}),
-    "__viewerAccess": resolveViewerAccess(context)
-  };
-}
+owns: [{ resource: contactResource, rowPolicy: ownContactsOrShared }]
 ```
 
 ## Keep These Boundaries Clean
@@ -252,8 +240,8 @@ function buildScopedQuery(query = {}, context = null) {
 - Put backend filter behavior in `searchSchema`, not in page code.
 - Use `createCrudListFilterContract(...)` for structured list filters before writing custom JSON REST query glue.
 - Put permission checks in the action/service layer, not in `applyFilter`.
-- Put repository-only scoping in the repository, not in route query validation.
-- Do not expose a query key publicly just because the repository uses it internally.
+- Put visibility in the owner's row policy, never in a search key or route query validation.
+- Do not expose a query key publicly just because the service maps to it internally.
 - Do not rely on route validators alone; a public key still needs a matching backend search definition.
 
 ## Quick Rule Of Thumb
@@ -262,4 +250,4 @@ function buildScopedQuery(query = {}, context = null) {
 - Public alias or multi-field search: `searchSchema`
 - Complex SQL semantics: `searchSchema` + `applyFilter`
 - Public HTTP query key: add it through the standard route/action query group
-- Internal-only repository key: inject it in `repository.js`, skip the public validator
+- Who may see a row: the owner's row policy, never a key

package/skills/jskit/references/heuristics/table-resource-fields.md

@@ -0,0 +1,78 @@
+<!-- Generated from `packages/agent-docs/heuristics/table-resource-fields.md`. -->
+
+# Table Resource Fields
+
+Use when:
+- a table resource field needs an explicit column mapping
+- a field should appear in records but is not a real column
+- the user mentions computed fields, projections or date write serialization
+
+Default JSKIT pattern:
+1. The table resource's schema describes the record; each field maps to its column itself.
+2. Use `storage: { column: "<column>" }` (or `actualField`) only when the default snake_case column is wrong.
+3. Standard writable `dateTime` fields are serialized at the write seam automatically; `storage.writeSerializer` is only for non-default serialization.
+4. A computed output field is `storage: { virtual: true }` in the shared schema, and its SQL goes in the owner's `owns` entry as `queryFields`, on the server.
+5. Handles apply those projections on every read; no repository method re-selects them.
+6. A field's default value is `defaultTo`; `default` is refused, since json-rest-api would ignore it.
+7. A field no request may see (an ownership id, a bearer token) is `hidden: true`, and stays hidden: the owner's code
+   reads it by naming it in a handle read's `fields`, and a system context may name it through another feature's
+   CRUD repository. Unhiding it puts it in every read's answer, other features' included; never read it with `scopedQuery`.
+
+Field metadata rules:
+
+```js
+// a column override
+createdAt: { type: "dateTime", required: true, storage: { column: "created_at" } }
+
+// a non-default write serializer
+arrivalDatetime: { type: "dateTime", required: true, storage: { writeSerializer: "datetime-utc" } }
+
+// a computed output field
+remainingWeight: { type: "number", required: true, storage: { virtual: true } }
+```
+
+- omit `actualField`/`storage` when the field is column-backed and the default snake_case mapping is correct
+- `storage: { virtual: true }` cannot also define `actualField`, `storage.column` or `storage.writeSerializer`
+- `storage: { virtual: true }` fields are never written
+
+Computed fields (server only):
+
+```js
+const ReceivalsFeature = defineFeature({
+  id: "receivals",
+  owns: [{
+    resource: receivalResource,
+    queryFields: {
+      remainingWeight: {
+        type: "number",
+        select({ raw, column }) {
+          return raw("?? - coalesce(??, 0)", [column("receivedWeight"), column("processedWeight")]);
+        }
+      }
+    }
+  }],
+  setup: ({ resources }) => ({ receivals: createReceivalsRepository(resources) })
+});
+```
+
+Keep projection SQL in the server feature that owns the table, never in the shared resource that ships to the browser.
+`select` receives `raw`, which builds one SQL expression from a string literal and its bindings (a value only: it never runs on its own),
+`column(field)`, which names a field's column, and the read's `filters`; never Knex. The expression is the field's value
+only, so it reads no other table.
+
+What the resource runtime does for you:
+- reads select only column-backed fields plus the registered query fields
+- writes serialize standard writable `dateTime` fields, and any explicit `storage.writeSerializer`
+- database reads serialize `date`, `time` and `dateTime` values to their strict `json-rest-schema` strings before validation, respecting `temporalPrecision`
+- search and filters only use column-backed fields
+
+Avoid:
+- `clearSelect()` / re-select hacks in a repository method to add a computed field
+- SQL fragments or joins in shared field metadata
+- `storage` modes beyond the documented `column`, `writeSerializer` and `virtual`
+
+Review checks:
+- one table resource per table, and field definitions own their mapping
+- non-default write serialization lives in `storage.writeSerializer`, not in repository code
+- every `storage: { virtual: true }` field has a matching `queryFields` entry in the owner's `owns`
+- no JavaScript `Date` object crosses a strict resource validation boundary; scoped-query reports return ISO/RFC 3339 strings explicitly

package/skills/jskit/references/heuristics/typed-features.md

@@ -63,11 +63,11 @@ ends with the same link.
   - [One helper per package](../typed-features.md#one-helper-per-package)
 - `options?.trx || options?.transaction`, a hand-read actor, cursor or created id
   - [One reader per fact](../typed-features.md#one-reader-per-fact)
-- `api.resources.x.query(…)` with no `page` for a list, `queryDocuments(query)` with no `limit` in a service, a list that stops at 20 rows, `page: { size: 500 }` or `limit: 500` that returns 100 rows
+- a list read with `query()` where every row is meant (`queryAll()`), a list that stops at one page, `page: { size: 500 }` refused above the page limit
   - [Every row](../typed-features.md#every-row)
-- `await getDocumentById(…)`, `queryDocuments(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a list whose query count grows with its rows, a slow list endpoint
+- `await handle.get(…)`, `handle.query(…)` or a service `get` inside a loop or a `Promise.all` over a list, a single-record helper reused for a list, N+1 queries, a list whose query count grows with its rows, a slow list endpoint
   - [Lists read related rows in batches](../typed-features.md#lists-read-related-rows-in-batches)
-- a `rowPolicy` that loads a person's whole history or calls an access check per item, `createDocument` per row of a batch, a write that gets slower as history grows
+- a `rowPolicy` that loads a person's whole history or calls an access check per item, `create()` per row of a batch instead of `createMany()`, a write that gets slower as history grows
   - [Bounded access checks](../typed-features.md#bounded-access-checks)
 - a route that queries storage, `boot*.js` holding routes
   - [Routes](../typed-features.md#routes)

package/skills/jskit/references/multi-homing.md

@@ -110,14 +110,25 @@ The package migrations create and own these tables:
 | `workspace_invites` | `workspace_id`, `email`, `role_sid`, `status`, `token_hash`, `invited_by_user_id`, `expires_at`, `accepted_at`, `revoked_at` |
 
 Application records that belong to a workspace use a non-null `workspace_id`
-foreign key to `workspaces.id`. Read and change these tables through the
-`workspaces.core` repositories and services, not directly.
+foreign key to `workspaces.id`. Read and change these tables through their
+owners' capabilities (`workspaces`, `workspaces.memberships` and
+`workspaces.core`, below), not directly.
 
 ## Server composition
 
 Use `workspaces/workspace-server` for role vocabulary, creation policy,
 invitations, settings, and app-owned invitation email rendering.
 
+Two server settings are required, and the server refuses to start without
+them: whether new workspaces accept invitations, and how long an invitation
+lasts.
+
+```js
+// config/server.js
+config.workspaceSettings = { defaults: { invitesEnabled: true } };
+config.workspaceMembers = { defaults: { inviteExpiresInMs: 7 * 24 * 60 * 60 * 1000 } };
+```
+
 Workspace scope must reach repository queries. Parsing a workspace slug or
 hiding an admin link is not authorization. Membership and role checks happen
 before an operation discloses records or record existence.
@@ -125,14 +136,12 @@ before an operation discloses records or record existence.
 ### Workspace-scoped features and routes
 
 For a standard CRUD resource owned by a workspace, give its table the
-`workspace_id` column, set the resource's `autofilter: "workspace"`, and bind
-`defineCrudJsonApiFeature()` with `ownershipFilter: "workspace"` and `scope:
-WORKSPACE_CRUD_SCOPE` (from `@jskit-ai/workspaces-core/server/support/workspaceCrud`)
-on a workspace surface. JSKIT then filters `workspaceId` by the workspace in the
-route. A repository method you add reads the workspace id with
-`resolveWorkspaceScopeValue(options.context)`
-(`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`), which throws when the
-context names two workspaces.
+`workspace_id` column, set its table resource's `ownership: "workspace"`, and bind
+`defineCrudFeature()` with `scope: WORKSPACE_CRUD_SCOPE` (from
+`@jskit-ai/workspaces-core/server/support/workspaceCrud`) on a workspace
+surface. JSKIT then filters `workspaceId` by the workspace in the route. A
+repository method you add passes the call's `options` on to the table's handle,
+which scopes every read and write to the context's workspace.
 `workspace_user` also filters by the signed-in user. See the CRUD operations
 guide.
 
@@ -175,9 +184,29 @@ capability provides:
 | `workspaces.services.members` | Members, roles and invitations |
 | `workspaces.services.pendingInvitations` | Invitation resolution, redemption and acceptance participants |
 | `workspaces.services.settings` | Workspace settings |
-| `workspaces.repositories.workspaces`, `.workspaceMemberships`, `.workspaceSettings`, `.workspaceInvites` | Repository access inside the application's own transactions |
+| `workspaces.repositories.workspaceSettings`, `.workspaceInvites` | Settings and invitation records inside the application's own transactions |
 | `workspaces.tenancyProfile` | The resolved tenancy mode and workspace policy |
 
+The workspaces and their memberships are their own capabilities, for code that
+reads or changes them inside its own transactions, typed `Workspaces` and
+`WorkspacesMemberships` in `@jskit-ai/workspaces-core/server/types`. Every
+method takes the call's `options` last and joins the transaction of the
+`txOptions` it is given.
+
+| Capability | Methods |
+| --- | --- |
+| `workspaces` | `findById(id, options)`, `findBySlug(slug, options)` (a deleted workspace is not found, though its slug stays taken), `listSlugsIn`, `findPersonalByOwnerUserId`, `listForUserId(userId, options)`, `insert`, `updateById`, `lock(workspaceId, options)` |
+| `workspaces.memberships` | `findByWorkspaceIdAndUserId`, `ensureOwnerMembership`, `upsertMembership(workspaceId, userId, patch, options)`, `addMember({ workspaceId, userId, roleSid }, options)`, `activeMemberIds(workspaceId, options)`, `listActiveByWorkspaceId`, `findActiveByWorkspaceIdAndUserId`, `listActiveWorkspaceIdsByUserId`, `listActiveWorkspaceIdsByUserIds` |
+
+`addMember` makes the user an active member with the role (`member` when none
+is given), adding the membership or reactivating it. `activeMemberIds` answers
+the active members' user ids at the same cost however many members there
+are, without including their profiles. `lock` takes
+the workspace's row lock until the caller's transaction ends, so work that must
+not interleave for one workspace takes turns; it runs only inside a
+transaction, given its `txOptions`, and answers `{ id }`, or `null` when there
+is no such workspace.
+
 To check one person's membership, for example a notification recipient, call
 `workspaces.services.members.getMember(workspace, userId, options)`. It answers
 that member's `listMembers` entry, or `null` for a removed or unknown member,
@@ -225,8 +254,8 @@ workspace routes, `workspaces-web` switches Vuetify to the `workspace-light` or
 colours. Other routes use the application's themes.
 
 New workspaces start from JSKIT's blue palette unless `config/server.js` sets
-the application's own. Missing fields keep JSKIT's values; an invalid colour
-stops the server at startup:
+the application's own beside the required `invitesEnabled`. Missing colours
+keep JSKIT's values; an invalid colour stops the server at startup:
 
 ```js
 // config/server.js
@@ -301,11 +330,11 @@ authorization and role checks. Do not pass arbitrary HTTP input as options.
 
 | Capability method | Contract |
 | --- | --- |
-| `workspaces.repositories.workspaceInvites.withTransaction(work)` | Delegates to the same JSON REST API's managed `transaction(work)`; awaits commit and completion hooks before resolving. Runs `work` again when the database aborts it as a deadlock victim (see [Database layer](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#deadlock-retries)). |
-| `workspaces.repositories.workspaceInvites.lockWorkspaceForInvitations(workspaceId, { trx })` | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
-| `workspaces.services.members.prepareInvite(workspace, actor, payload, options)` | Requires a managed `options.trx`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
-| `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Requires no `options.trx`. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
-| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Rejects `options.trx`. |
+| `workspaces.repositories.workspaceInvites.withTransaction(options, (txOptions) => …)` | The invitations handle's `withTransaction`: joins the caller's transaction or opens one and hands `work` the `txOptions` to pass on; awaits commit and completion hooks before resolving. Runs `work` again when the database aborts it as a deadlock victim (see [data access](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access#transactions)). `{ ...options, outermost: true }` refuses a call that already runs inside one. |
+| `workspaces.lock(workspaceId, txOptions)` (capability `workspaces`) | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
+| `workspaces.services.members.prepareInvite(workspace, actor, payload, txOptions)` | Runs only inside a transaction, given its `txOptions`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
+| `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Refuses to run inside a transaction: it delivers after the preparation's transaction commits. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
+| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Refuses to run inside a transaction. |
 | `workspaces.invite-acceptance-participant` (optional capability) | One application function receiving `({ invite, user }, options)` inside the acceptance transaction. Without it, acceptance activates the membership only. |
 
 `sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
@@ -344,21 +373,20 @@ setup: ({ reviewedPeople, people, scopes, audit }) => ({
 })
 
 // Inside an authorized application command, in a feature that requires
-// workspaces: "workspaces.core":
+// workspaces: "workspaces.core" and workspaceRecords: "workspaces":
 const { members } = workspaces.services;
 const invites = workspaces.repositories.workspaceInvites;
-const prepared = await invites.withTransaction(async (trx) => {
-  const options = { trx, context };
+const prepared = await invites.withTransaction({ context }, async (txOptions) => {
   // Match acceptance's order: workspace, then application draft/receipt rows.
-  await invites.lockWorkspaceForInvitations(workspace.id, options);
-  const reviewed = await reviewedPeople.lockAuthorizedDraft(draftId, workspace.id, actor, options);
-  const receipt = await reviewedPeople.findMatchingReceipt(reviewed, requestId, options);
+  await workspaceRecords.lock(workspace.id, txOptions);
+  const reviewed = await reviewedPeople.lockAuthorizedDraft(draftId, workspace.id, actor, txOptions);
+  const receipt = await reviewedPeople.findMatchingReceipt(reviewed, requestId, txOptions);
   if (receipt) return { createdInviteId: receipt.inviteId };
   const created = await members.prepareInvite(workspace, actor, {
     email: reviewed.email,
     roleSid: reviewed.roleSid
-  }, options);
-  await reviewedPeople.associateInvitationAndSaveReceipt(reviewed, requestId, created.createdInviteId, options);
+  }, txOptions);
+  await reviewedPeople.associateInvitationAndSaveReceipt(reviewed, requestId, created.createdInviteId, txOptions);
   return { createdInviteId: created.createdInviteId };
 });
 
@@ -401,8 +429,8 @@ exactly once. Revocation after sending starts cannot recall a message.
 Register one callback during feature setup to call the required application
 services. Non-functions throw `TypeError`; duplicate registration throws, and
 registration closes when acceptance/refusal first begins. The callback's invite,
-user and options are shallow frozen. JSKIT owns the transaction and passes its
-`trx` and request `context` to the callback.
+user and options are shallow frozen. JSKIT owns the transaction and passes the
+callback the `txOptions` that carry it and the request's `context`.
 
 Acceptance checks authentication, recipient email, pending state and expiry under
 workspace/invitation locks. Before calling the participant, it activates membership
@@ -420,8 +448,8 @@ callback must not commit, roll back, create transactions/savepoints or perform
 external effects. Participant and later invitation-status failures roll back
 membership (including its previous role/status), person/training links, scopes,
 audit and accepted status. Invalid invitations and refusals do not call the
-participant. Acceptance/refusal reject borrowed `options.trx`; revocation can
-join a managed transaction or create one.
+participant. Acceptance and refusal refuse to run inside the caller's
+transaction; revocation can join one or open its own.
 
 Acceptance/refusal return 401 for unauthenticated access, 403 for a recipient
 email mismatch and 404 for a missing or handled invitation. A matching recipient's
@@ -435,7 +463,7 @@ Preserve `error.transactionOutcome` and `error.cause`: `rolledBack` confirms
 rollback, `committed` can accompany a failed completion hook, and `unknown`
 requires resolving the outcome before retrying. Errors after commit cannot undo
 persistence. See
-[managed transaction guidance](existing-application-migration.md#json-rest-v2-integration).
+[managed transaction guidance](existing-application-migration.md#data-access-on-table-resources-json-rest-api-3).
 
 Invitation mutations lock workspace before invitation rows. A losing acceptance,
 refusal, revocation or replacement cannot overwrite accepted/revoked state.
@@ -494,7 +522,41 @@ Workspace surfaces put the slug in their pages root, such as
 `w/[workspaceSlug]/admin` for administration. Keep the default surface
 (`surfaceDefaultId`, usually `home`) free of a workspace requirement: `/`,
 invitation links and other unscoped pages belong to it. With
-`webRootAllowed: "no"`, `/` opens that surface's root.
+`webRootAllowed: "no"`, `/` opens that surface's root. The foundation
+defines `home` and its `public` access policy, and the `auth/auth-surface`
+pattern the `auth` surface; the workspace surfaces add a policy and two
+definitions:
+
+```js
+// config/surfaceAccessPolicies.js
+surfaceAccessPolicies.workspace_member = { requireAuth: true, requireWorkspaceMembership: true };
+
+// config/public.js
+config.surfaceDefinitions.app = {
+  id: "app",
+  label: "App",
+  pagesRoot: "w/[workspaceSlug]",
+  requiresAuth: true,
+  requiresWorkspace: true,
+  accessPolicyId: "workspace_member"
+};
+config.surfaceDefinitions.admin = {
+  id: "admin",
+  label: "Admin",
+  pagesRoot: "w/[workspaceSlug]/admin",
+  requiresAuth: true,
+  requiresWorkspace: true,
+  accessPolicyId: "workspace_member"
+};
+```
+
+An access policy takes `requireAuth`, `requireWorkspaceMembership`,
+`requireAnyPermissions` and `requireAllPermissions` (permission lists), and
+`requireFlagsAny` and `requireFlagsAll` (flags the server's bootstrap sets in
+`surfaceAccess`). Without `requireAuth` or `requireWorkspaceMembership` it
+takes the surface's `requiresAuth` or `requiresWorkspace`. The browser applies
+the whole policy; the server reads only `requireWorkspaceMembership: false`
+from it, and a route's own `auth` and `permission` authorize it there.
 
 `workspaces-web` remembers the last workspace each person opened in this
 browser. The **Your workspaces** page, `WorkspacesClientElement` from