@forumone/throughline-core 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @forumone/throughline-core
 
+## 0.10.0
+
+### Minor Changes
+
+- 006ae30: A missing environment variable is reported together with every other one, in a
+  single error, instead of one plugin at a time.
+
+  The plugins that read the environment at init now declare what they cannot
+  start without, as data: `approvalsEnv` (`APPROVAL_TOKEN_SECRET`, 32+
+  characters), `emailEnv` (`RESEND_API_KEY`, `EMAIL_FROM_ADDRESS`) and `formsEnv`
+  (`FORMS_IP_HASH_SECRET`, 32+ characters). Each is a list of `EnvRequirement`
+  (`{ name, minLength?, why }`), a new type in `plugin-contract`, and each
+  plugin's own init check now reads the same entries, so the two cannot drift.
+  An empty or whitespace-only value now counts as missing in those checks.
+
+  Core exports `assertEnvironment(...checks)`. Call it first in
+  `payload.config.ts` with the plugins' lists and your own variables; it throws
+  one `EnvironmentError` whose first line reads "Configuration problem: N
+  environment variables are missing or invalid", followed by every missing or
+  too-short variable and why it is needed. Values are never printed. An argument
+  can also be a function, for a rule that is not "this name, this long", such as
+  a database URL accepted under several names. `checkEnvValue` is the one-value
+  check behind it, for a plugin's own backstop.
+
+  New projects call `assertEnvironment` at the top of `payload.config.ts` with
+  `approvalsEnv`, `emailEnv`, `formsEnv`, `PAYLOAD_SECRET` (32+ characters),
+  `NEXT_PUBLIC_SERVER_URL` and the database resolver, and `.env.example` marks
+  which variables are checked. An existing site can do the same and delete any
+  hand-kept copy of the plugins' requirements.
+
+- 549d292: A `throughline-payload` bin: the Payload CLI, run so a hung command cannot outlive the shell that started it. pnpm does not forward signals to the node process it spawns, so a killed shell left `payload generate:types` running, and a hung one spinning on a core indefinitely.
+
+  - Payload runs in its own process group; SIGINT, SIGTERM and SIGHUP are forwarded to the group, then SIGKILL after `PAYLOAD_CLI_GRACE_MS` (default 5s)
+  - a wall clock, `PAYLOAD_CLI_TIMEOUT_MS` (default 5 minutes, `0` disables; none by default for `migrate*`), exits 124
+  - each run is recorded in `.payload-cli-pids` at the workspace root, and the next run — or `throughline-payload --reap` — kills a recorded group whose runner was killed, after checking its pid, start time and command line
+
+- 70385c4: A failed background job has somewhere to be recorded, and core can report errors.
+
+  - **`job-failures` collection.** `jobFailuresPlugin()` from the new `@forumone/throughline-core/observability` subpath adds a read-only `job-failures` collection (admin-only by default) and attaches a writer that never throws; a row it cannot write is logged at `error` with the failure's summary and message. It is deliberately not the audit log: `audit-events` records MCP tool calls, its `mcpServer` column is required and constrained to MCP server names, and a cron that wrote there with any other value was rejected by Payload and silently dropped.
+  - **Error reporting.** `createErrorReporter` / `reportError` post JSON reports to `ERROR_WEBHOOK_URL` (or a URL you pass), with a one-line `text` so a Slack incoming webhook works as-is, a 3-second timeout, and no throw on any failure. `buildRequestErrorReport` shapes what Next's `onRequestError` receives and copies request headers from an allowlist; `authorization`, `cookie`, `x-api-key` and `x-forwarded-for` are never copied. `describeErrorReporting` gives a boot-log sentence for on, off or misconfigured.
+
+  **Migration required.** Registering `jobFailuresPlugin` adds a table (`job_failures`) and an enum (`enum_job_failures_kind`). Run `payload migrate:create` after adding it and commit the migration. The audit collection is unchanged.
+
+- c8a86bf: Adds a `./testing` subpath with `describeAnonymousAccess(config, buckets)`. It registers a vitest suite that checks every collection's `read` rule against an anonymous request, with no database. Every collection in the config, including those added by plugins and by Payload, must be in exactly one bucket:
+
+  - `renderPath`: read by the public site, so an anonymous read must be allowed. A collection with drafts must narrow that read with a query.
+  - `private`: an anonymous read must be refused.
+
+  A collection in no bucket fails, so adding a collection fails until somebody decides where it goes. `checkAnonymousAccess` returns the same findings as a list. `vitest` is an optional peer, and the main entry does not re-export the subpath.
+
+- ab623e1: `mcpApiKeyAccess(isAdmin)` makes `payload-mcp-api-keys`, the key collection `@payloadcms/plugin-mcp` brings, admin-only. Pass it as `mcpPlugin({ overrideApiKeyCollection: mcpApiKeyAccess(isAdmin) })`. It applies the site's admin rule to `read`, `create`, `update`, `delete` and `unlock`, and refuses an MCP key principal before it asks the rule, so a key can never manage keys. It changes `access` and nothing else, so it composes with an override that also sets, say, `admin.group`.
+
+  `isSignedIn(user)` and its `Access` form `signedIn` are a "signed in" check to use instead of `Boolean(req.user)`. They refuse an MCP key document on `req.user`, which Payload before 3.89.0 could put there on any REST route. `isMcpApiKeyPrincipal(user)` and `MCP_API_KEYS_SLUG` are exported for rules that need to tell the two apart directly. None of these affects `/api/mcp`, where a tool runs as the key's user.
+
+- ab623e1: The `payload` peer range moves from `^3.0.0` to `^3.89.0` for every package that has one. **A site on Payload older than 3.89.0 must upgrade Payload before upgrading these packages.**
+
+  Before 3.89.0, the `payload-mcp-api-keys` collection that `@payloadcms/plugin-mcp` adds registered Payload's API-key strategy on every REST route. Any key could then become `req.user` outside `/api/mcp` and pass access rules written as `Boolean(req.user)`. Every Throughline site runs that plugin, so the floor is the same for every package. No package's code changes with this bump.
+
+- 36728c4: Collections that Throughline plugins declare now sit in a `Throughline` group in the admin sidebar, instead of loose at the top of it above every group. That covers `audit-events` (`auditPlugin`), the approvals collection (`approvalsPlugin`), `integrations` (`integrationsPlugin`), and `forms` and `form-submissions` (`formsPlugin`).
+
+  Each of those plugins accepts `admin: { group }`, which applies to every collection it declares:
+
+  - omitted: the `Throughline` group.
+  - a string, or a locale map such as `{ en: 'Workflow', fr: 'Flux' }`: that group.
+  - `false`: ungrouped, in Payload's default "Collections" section. This does not hide the collection, which is what `false` means on a collection's own `admin.group`.
+
+  A site that groups these collections with its own config plugin can pass `admin: { group }` to each plugin and delete that code. `createAuditCollection`, `createApprovalsCollection` and `createIntegrationsCollection` accept the same `admin` option.
+
+  `@forumone/throughline-plugin-contract` exports the shared pieces: `CollectionPluginOptions`, `PluginAdminOptions`, `PluginAdminGroup`, `DEFAULT_ADMIN_GROUP` and `resolveAdminGroup`, the helper a plugin spreads into each collection's `admin` block. `@forumone/throughline-core` re-exports the types.
+
+### Patch Changes
+
+- Updated dependencies [006ae30]
+- Updated dependencies [ab623e1]
+- Updated dependencies [36728c4]
+  - @forumone/throughline-plugin-contract@0.5.0
+
+## 0.9.1
+
+### Patch Changes
+
+- d02772f: A refused MCP tool call now carries MCP's `isError` flag.
+
+  Every server in the suite answers a refusal with `{ error: … }` and returns it
+  rather than throwing, so that a denial reads to the model as a denial rather
+  than as a server fault. None of them set `isError`, so the refusal arrived as a
+  **successful** tool result that happened to contain an `error` key: a client
+  checking the protocol's flag instead of parsing the body read every refusal as
+  a success.
+
+  The publishing tools are where this was found, and they are the worst case for
+  it. `@payloadcms/plugin-mcp` assigns no `req.user` — it mutates `docs[0].user`
+  and passes it separately to its own CRUD tools — so `contextFrom(req)` reads
+  `null` and _every_ `Bearer`-authenticated publishing call is refused at
+  `actor.ts`'s identity guard. All of those refusals reported success.
+
+  Fixed in `toPayloadMcpTool`, which is the one adapter every tool in all six
+  servers passes through, so a tool written tomorrow is covered without its
+  author knowing the file exists.
+
+  **Nothing changes for a client that parses the body.** The content block is
+  byte-identical, and `isError` is absent rather than `false` on a success, so a
+  consumer reading `{ error }` today sees no difference. A consumer reading the
+  flag now sees the truth instead of its opposite.
+
+  The test is a non-empty string `error`, so a refusal that later grows a second
+  field — a code, a retry hint — keeps its flag. The corollary is now documented
+  on `deniedEnvelope`: `error` is reserved for refusals, and a success result
+  reports failure through `ok`, `healthy`, `message` or `details`.
+
+  Found exercising audit `04` F-02 against a real MCP key; forumone-2026#614.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -4,13 +4,17 @@ The shared plumbing every Throughline server package depends on. Drop it into a
 
 ## What's inside
 
-| Subsystem | Subpath | Role |
-|---|---|---|
-| Audit | `./audit` | `auditPlugin`, `createAuditCollection`, `createAuditWriter`, `getAuditWriter`, `AUDIT_ACTIONS`, `AUDIT_MCP_SERVERS` |
-| Events | `./events` | `createInngestClient`, `CoreEvents`, `FrameworkEvents` (module-augmentation seam) |
-| MCP | `./mcp` | `createMcpToolCollector`, `toPayloadMcpTools`, `McpMetaSchema`, `withMeta`, `auditContext` |
-| Logger | (main) | `defaultLogger`, `createNamedLogger` |
-| Utils | (main) | `documentContentHash`, `sha256Hex`, `formatZodIssues` |
+| Subsystem          | Subpath           | Role                                                                                                                                                            |
+| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Audit              | `./audit`         | `auditPlugin`, `createAuditCollection`, `createAuditWriter`, `getAuditWriter`, `AUDIT_ACTIONS`, `AUDIT_MCP_SERVERS`                                             |
+| Events             | `./events`        | `createInngestClient`, `CoreEvents`, `FrameworkEvents` (module-augmentation seam)                                                                               |
+| MCP                | `./mcp`           | `createMcpToolCollector`, `toPayloadMcpTools`, `McpMetaSchema`, `withMeta`, `auditContext`, `mcpApiKeyAccess`, `isSignedIn`, `signedIn`, `isMcpApiKeyPrincipal` |
+| Environment        | `./env`           | `assertEnvironment`, `checkEnvValue`, `EnvironmentError`                                                                                                        |
+| Observability      | `./observability` | `jobFailuresPlugin`, `getJobFailureWriter`, `createErrorReporter`, `reportError`, `buildRequestErrorReport`, `describeErrorReporting`                           |
+| Logger             | (main)            | `defaultLogger`, `createNamedLogger`                                                                                                                            |
+| Utils              | (main)            | `documentContentHash`, `sha256Hex`, `formatZodIssues`                                                                                                           |
+| Testing            | `./testing` only  | `describeAnonymousAccess`, `checkAnonymousAccess` — test helpers for a site; not re-exported from the main entry                                                |
+| Payload CLI runner | bin               | `throughline-payload` — see [below](#running-the-payload-cli-throughline-payload)                                                                               |
 
 There is no `./auth` any more. It held an MCP key collection, a bearer-token
 authenticator and `createMcpHandler` — a JSON-RPC subset each plugin mounted at its
@@ -18,7 +22,7 @@ own `/mcp`. `@payloadcms/plugin-mcp` owns the transport, the keys and authentica
 now; `createMcpToolCollector` is how this suite's tools get to it. `sha256Hex`
 survived, under `./utils`.
 
-The main entry re-exports everything; the subpath exports keep bundles smaller for consumers who only need one slice.
+The main entry re-exports everything except `./testing`; the subpath exports keep bundles smaller for consumers who only need one slice.
 
 ## Installation
 
@@ -26,7 +30,7 @@ The main entry re-exports everything; the subpath exports keep bundles smaller f
 pnpm add @forumone/throughline-core
 ```
 
-Peers: `payload@^3.0.0` and `inngest@^4.0.0`.
+Peers: `payload@^3.89.0` and `inngest@^4.0.0`.
 
 ## The audit log
 
@@ -68,30 +72,80 @@ onInit: async (payload) => {
 
 The writer is **fire-and-forget**: failures log but never throw. Audit failures must never break the originating action.
 
+### Sidebar group
+
+The `audit-events` collection sits in the admin sidebar's `Throughline` group by default. `auditPlugin({ inngest, admin: { group: 'Workflow' } })` files it elsewhere; `admin: { group: false }` leaves it ungrouped. Every Throughline plugin that declares a collection takes the same option — see [the reference](https://github.com/forumone/throughline/blob/main/docs/reference/plugin-contract.md#admin-sidebar-group).
+
+## Job failures and error reporting
+
+The audit log records who did what through an MCP tool. A background job that
+ran out of retries is not that, so it has its own collection:
+`jobFailuresPlugin()` adds `job-failures` and attaches a writer that
+`@forumone/throughline-workflows`' failure handlers find. Adding it to an
+existing site is a schema change — run `payload migrate:create` afterwards.
+
+Error reports go to a webhook, not to a vendor SDK: `reportError` posts JSON to
+`ERROR_WEBHOOK_URL` (a log drain, an alerting endpoint, a Slack incoming
+webhook, a proxy in front of a tracker), with a 3-second timeout, and never
+throws. `buildRequestErrorReport` shapes what Next's `onRequestError` hands
+over, copying request headers from an allowlist — `cookie` and `authorization`
+are never copied.
+
+```typescript
+// instrumentation.ts
+import type { Instrumentation } from 'next'
+import { buildRequestErrorReport, reportError } from '@forumone/throughline-core/observability'
+
+export const onRequestError: Instrumentation.onRequestError = async (error, request, context) => {
+  await reportError(buildRequestErrorReport(error, request, context))
+}
+```
+
+`./observability` imports neither Payload nor Inngest at runtime, so it is safe
+in `instrumentation.ts`. See `docs/operations/observability.md`.
+
 ## MCP authentication
 
-`createApiKeysCollection` adds a Payload collection that stores SHA-256 hashes of bearer tokens (the raw key is shown to the operator once on create, then never persisted). `createBearerTokenAuthenticator` validates incoming requests against that collection.
+`@payloadcms/plugin-mcp` handles MCP authentication. It adds the `payload-mcp-api-keys` collection, looks up `Authorization: Bearer <key>` on `/api/mcp`, and runs each tool as the person the key is bound to. This package's `createApiKeysCollection`, `createBearerTokenAuthenticator` and `createMcpHandler` are gone.
+
+What this package adds is two access helpers for a site that registers that plugin.
+
+**Only admins should manage keys.** A key runs every tool as its user, so minting, reading and revoking keys is an admin's job. The plugin doesn't enforce that by default. `mcpApiKeyAccess(isAdmin)` is an `overrideApiKeyCollection` that applies your admin rule to `read`, `create`, `update`, `delete` and `unlock`, and refuses an MCP key principal before it asks the rule:
 
 ```ts
-import { createApiKeysCollection, createBearerTokenAuthenticator, createMcpHandler } from '@forumone/throughline-core'
-import type { Payload } from 'payload'
-
-// In your Payload config:
-collections: [createApiKeysCollection({ usersSlug: 'users' })],
-
-// In your MCP route:
-const authenticator = createBearerTokenAuthenticator({ payload })
-const handleMcp = createMcpHandler({
-  payload,
-  serverName: 'publishing',
-  tools: [/* McpToolDefinition[] */],
-  authenticator,
+import { createMcpToolCollector, mcpApiKeyAccess } from '@forumone/throughline-core'
+import { mcpPlugin } from '@payloadcms/plugin-mcp'
+import type { Access } from 'payload'
+
+const isAdmin: Access = ({ req: { user } }) =>
+  user?.collection === 'users' && Array.isArray(user.roles) && user.roles.includes('admin')
+
+mcpPlugin({
+  mcp: { tools: mcpTools.tools },
+  overrideApiKeyCollection: mcpApiKeyAccess(isAdmin),
 })
+```
 
-// Next.js app router:
-export const POST = (req: Request) => handleMcp(req)
+It changes `access` and nothing else. To set other options too, call it inside your own override:
+
+```ts
+overrideApiKeyCollection: collection => {
+  const hardened = mcpApiKeyAccess(isAdmin)(collection)
+  return { ...hardened, admin: { ...hardened.admin, group: 'Throughline' } }
+},
 ```
 
+**"Signed in" is not `Boolean(req.user)`.** Before Payload 3.89.0, the key collection's `auth.useAPIKey` registered Payload's API-key strategy on every REST route, so a key _document_ could become `req.user`. It has no roles, but it passes `Boolean(req.user)`, so a rule like "published, or anybody signed in" served drafts to anyone holding a key. Payload 3.89.0 fixed this, and it's this package's peer floor. Refuse the principal in your own rules as well:
+
+| Export                       | What it does                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------- |
+| `isSignedIn(user)`           | `true` for a person, `false` for anonymous or an MCP key document. A type guard |
+| `signedIn`                   | `isSignedIn` as an `Access` function                                            |
+| `isMcpApiKeyPrincipal(user)` | `true` only for a key document from `payload-mcp-api-keys`                      |
+| `MCP_API_KEYS_SLUG`          | `'payload-mcp-api-keys'`                                                        |
+
+None of these affects `/api/mcp`. A tool call there arrives as the key's user, in `users`, with that person's roles. See [the security model](../../docs/operations/security-model.md#signed-in-is-not-booleanrequser).
+
 ### Scopes
 
 A key carries `scopes`, and a tool may declare the one it needs:
@@ -135,13 +189,13 @@ not as everything.
 
 The consequential tools in this suite and the scopes they require:
 
-| Scope | Tools |
-|---|---|
-| `publishing.execute` | `publish`, `unpublish`, `schedule_publish`, `rollback` |
-| `approvals.request` | `request_approval` |
-| `approvals.decide` | `respond_to_approval` |
-| `forms.manage` | `create_form`, `update_form_fields`, `update_form_destinations` |
-| `integrations.trigger` | `trigger_sync`, `test_integration` |
+| Scope                  | Tools                                                           |
+| ---------------------- | --------------------------------------------------------------- |
+| `publishing.execute`   | `publish`, `unpublish`, `schedule_publish`, `rollback`          |
+| `approvals.request`    | `request_approval`                                              |
+| `approvals.decide`     | `respond_to_approval`                                           |
+| `forms.manage`         | `create_form`, `update_form_fields`, `update_form_destinations` |
+| `integrations.trigger` | `trigger_sync`, `test_integration`                              |
 
 Everything else — the component tools, the audit queries, the read side of publishing and approvals — needs only a valid key.
 
@@ -161,6 +215,26 @@ declare module '@forumone/throughline-core/events' {
 
 After augmentation, `inngest.send({ name: 'approval/decided', data: { ... } })` is type-checked everywhere.
 
+## Checking the environment
+
+Each plugin that falls back to `process.env` exports what it needs as data — `approvalsEnv`, `emailEnv`, `formsEnv` — and checks the same entries at init. A site passes every list, plus its own variables, to `assertEnvironment` first thing in `payload.config.ts`:
+
+```ts
+import { assertEnvironment } from '@forumone/throughline-core'
+import { approvalsEnv } from '@forumone/throughline-approvals'
+import { emailEnv } from '@forumone/throughline-email'
+
+assertEnvironment(
+  approvalsEnv,
+  emailEnv,
+  { name: 'PAYLOAD_SECRET', minLength: 32, why: 'Signs Payload sessions.' },
+  () => databaseConnectionString(),
+)
+```
+
+It throws once, listing every missing or too-short value with the reason it is needed, under a first line that says `Configuration problem` — instead of each plugin failing on the first thing it finds, one deploy at a time, inside a `next build` stack trace. It never prints a value. A function argument is for a rule that is not "this name, this long": what it throws becomes a line in the report.
+
+`checkEnvValue(requirement, value)` is the one-value check behind it, which a plugin uses for its own init backstop.
 
 ## Document content hashing
 
@@ -173,10 +247,95 @@ const version = await documentContentHash(page)
 const withExtras = await documentContentHash(page, { exclude: ['syncedAt'] })
 ```
 
-It exists so that approvals can bind to *what an approver read* rather than to when it was last saved. Approvals writes it as `targetVersion`; publishing recomputes it at publish time. Two consequences worth stating: a save that changed nothing keeps a granted approval, and an edit that is reverted brings one back.
+It exists so that approvals can bind to _what an approver read_ rather than to when it was last saved. Approvals writes it as `targetVersion`; publishing recomputes it at publish time. Two consequences worth stating: a save that changed nothing keeps a granted approval, and an edit that is reverted brings one back.
 
 **Two callers only agree if they hash a document loaded the same way.** Both of the above use `payload.findByID({ collection, id, draft: true })` at the config's default depth. A populated relationship and a bare relationship id are different values, and normalising cannot turn one into the other — so a third caller fetching at a different depth would produce a hash that matches nothing.
 
+## Running the Payload CLI: `throughline-payload`
+
+`pnpm payload generate:types` is shell → pnpm → node, and pnpm (like npm and
+yarn) does not forward signals to the node child it spawns. Kill the shell — a
+Ctrl-C, an agent's tool-call timeout, a cancelled CI step — and node keeps
+running, reparented to PID 1. When the run was hung rather than slow, it spins
+on a core until something kills it; one machine collected 48 of them.
+
+`throughline-payload` is a drop-in for the `payload` binary that cannot do that.
+Point every script that runs the Payload CLI at it:
+
+```json
+{
+  "scripts": {
+    "payload": "throughline-payload",
+    "payload:reap": "throughline-payload --reap",
+    "generate:types": "throughline-payload generate:types",
+    "generate:importmap": "throughline-payload generate:importmap",
+    "migrate": "PAYLOAD_MIGRATING=1 throughline-payload migrate",
+    "migrate:create": "throughline-payload migrate:create",
+    "migrate:status": "throughline-payload migrate:status"
+  }
+}
+```
+
+Arguments pass straight through. What it adds:
+
+- **Its own process group.** Payload runs `detached`, so the whole subtree can be
+  killed as a group, by pid. Nothing is ever matched by process name.
+- **Signals forwarded.** SIGINT, SIGTERM and SIGHUP go to the group; after a
+  grace period, whatever ignored them gets SIGKILL. When Payload exits on its
+  own, anything it left running in its group goes with it.
+- **A wall clock.** `PAYLOAD_CLI_TIMEOUT_MS`, default 300000 (five minutes); `0`
+  disables it. The `migrate` family (`migrate`, `migrate:create`, …) has no wall
+  clock unless you set one: a large migration is legitimately long and
+  `migrate:create` can stop at a prompt. A timed-out run exits 124.
+  `PAYLOAD_CLI_GRACE_MS` (default 5000) is the wait between the polite signal
+  and SIGKILL.
+- **A sweep for what a killed runner left behind.** A SIGKILLed runner runs no
+  handlers, so each run is recorded in `.payload-cli-pids` and the next run —
+  or `throughline-payload --reap` — kills the group of any entry whose runner
+  is gone. An entry is acted on only if the pid is alive, its start time and
+  full command line still match what was recorded (so a recycled pid is never
+  touched), the command line is rooted in this workspace, and its runner is
+  gone (so a concurrent run keeps its child). Anything else is forgotten, not
+  signalled.
+
+Payload is resolved from the directory the command runs in — the app — not
+from this package's install. `.payload-cli-pids` lives at the workspace root:
+the nearest ancestor with a `pnpm-workspace.yaml`, or, outside a pnpm
+workspace, the nearest directory with a `package.json`. Add it to
+`.gitignore`. On Windows, which has neither process groups nor `ps`, the runner
+just runs Payload.
+
+## Testing what an anonymous reader can read
+
+`@forumone/throughline-core/testing` holds a site's access rules to a bucket map, as a vitest suite that needs no database. It imports `vitest`, an optional peer, so it lives on its own subpath and the main entry never loads it.
+
+Every query the public site makes runs with nobody signed in, so a collection's own `read` rule decides whether a page can see its content. Close one by mistake and nothing errors: the page renders empty. Open the wrong one and the audit log or the MCP keys are on the internet.
+
+```ts
+// apps/web/src/access/anonymousAccess.test.ts
+import { describeAnonymousAccess } from '@forumone/throughline-core/testing'
+import config from '../payload.config'
+
+describeAnonymousAccess(config, {
+  renderPath: {
+    pages: 'the [...slug] route',
+    media: 'every populated upload',
+  },
+  private: ['users', 'payload-mcp-api-keys', 'audit-events', 'payload-preferences'],
+  // Optional. When given, every global must be in it.
+  globals: { renderPath: { navigation: 'the header and footer' } },
+})
+```
+
+It asserts:
+
+- **Every collection is in exactly one bucket.** That covers the collections plugins and Payload add as well as the site's own. A collection in no bucket fails, so adding one forces somebody to decide. An entry the config no longer has fails too.
+- **Render-path collections allow an anonymous read.** The rule must answer `true` or a query. Having no rule fails, because Payload's default needs a user.
+- **Collections with drafts narrow that read.** On a collection with `versions.drafts`, a bare `true` serves unpublished documents, so the rule has to answer a query, usually `{ _status: { equals: 'published' } }`.
+- **Private collections refuse it.** `true` or a query fails. Having no rule passes, because Payload's default refuses.
+
+A rule that calls `req.payload` cannot be checked as a value, and it throws rather than guessing. `checkAnonymousAccess(config, buckets)` returns the same findings as a list, for a script or a custom assertion.
+
 ## Why all of this lives in one package
 
 Server packages (Component, Publishing, Approvals, Audit Query, Forms, Integrations) all depend on the same audit log, the same authentication pattern, and the same event taxonomy. Splitting these across packages would create circular dependencies — every server package would need the audit writer, and an audit-only package would need to know about every server. Consolidating the plumbing here keeps the dependency graph one-way: core → server packages → client app.