docs: record module authorization architecture

Adds ADR 0014 recording the durable architecture Phase 5A established
across both passes: the shared contracts-layer PermissionDeclaration,
manifest version 3 replacing version 2's bare permission strings, the
reserved core.* namespace and the structural guarantee that a
module-vs-Core collision always surfaces as
ModulePermissionCompositionError rather than the generic
PermissionRegistryError duplicate path, deterministic registry
composition, startup ordering, repository-root/package-version
resolution, registry injection into apps/api's enforcement and
explicit-grant HTTP API, the static-snapshot/historical-record
preservation guarantees, and Doctor/modules:validate integration.
Indexes it in the ADR README, cross-references it from ADR 0006 (only
its manifestVersion 2 / permission-string decision is superseded; the
rest of ADR 0006 remains accepted, and its historical text is left
untouched) and ADR 0013 (module permission registration, deferred
there, is what ADR 0014 implements), and links it from the relevant
development documentation.

Corrects two comments discovered during a direct source audit that
overstated where a module-vs-Core permission collision is actually
caught (core/src/modules/permissions.ts,
apps/api/src/platform-permissions.ts) — comment-only, no behavior
change, already covered by existing tests. Also corrects a
documentation claim in docs/development/authorization.md that
incorrectly implied removing a module blocks explicit revocation of
its historical grants; grants-routes.ts's revoke handler never
consults the permission registry, so revocation remains unaffected.

docs/architecture/decisions/0006-versioned-capabilities-and-compiled-module-runtime.md

@@ -19,6 +19,15 @@ registry, which conflicts with install-by-cloning discovery.
 
 ## Decision
 
+> **Partial correction — see [ADR 0014](0014-module-permission-declarations-and-platform-registry.md).**
+> `manifestVersion: 2` and the permission-string-array shape described immediately below (the
+> `permissions` field of the static manifest) were superseded by ADR 0014's `manifestVersion: 3`,
+> which represents each permission as a complete `{id, baseline, description}` declaration instead
+> of a bare identifier string. Every other decision in this ADR — versioned capabilities,
+> `defineModuleRuntime`, the compiled-runtime production loading boundary, and registration/lifecycle
+> ordering — remains accepted and unchanged. This section is left as originally accepted, as the
+> historical record of the manifest's prior shape.
+
 `ekklesia.module.json` remains the one canonical static manifest and moves to
 `manifestVersion: 2`. Provided capabilities are declarations containing an identifier and an exact
 semantic version. Required and optional capability dependencies map identifiers to semantic-version

docs/architecture/decisions/0013-core-authorization-and-owner-bootstrap.md

@@ -194,6 +194,13 @@ module permission discovery/registration (a mechanism for a module to contribute
 declarations to a combined permission registry) are all deliberately out of scope for Phase 4C and
 remain later work.
 
+> **Update — see [ADR 0014](0014-module-permission-declarations-and-platform-registry.md).** Module
+> permission discovery/registration, deferred above, was implemented by ADR 0014: a module manifest
+> declares permissions in the same `PermissionDeclaration` shape this ADR's registry uses, and
+> `apps/api` composes Core's declarations with every installed module's into the one registry every
+> request is enforced against. Roles/groups/teams/tenants, owner-management HTTP, and service
+> accounts/API tokens remain deferred.
+
 ## Alternatives
 
 - Representing platform-owner status as a special grant row (a synthetic `*` permission, or a

docs/architecture/decisions/0014-module-permission-declarations-and-platform-registry.md

@@ -0,0 +1,233 @@
+# 0014: Module permission declarations and platform permission registry
+
+- Status: Accepted
+- Date: 2026-07-24
+- Extends: [0013](0013-core-authorization-and-owner-bootstrap.md)
+- Supersedes (partial): [0006](0006-versioned-capabilities-and-compiled-module-runtime.md) — only
+  its `manifestVersion: 2` and bare-permission-string decision. Capabilities, the compiled-runtime
+  production loading boundary, and registration/lifecycle ordering established in ADR 0006 remain
+  accepted and unchanged.
+
+## Context
+
+ADR 0013 established Core's authorization foundation — schema, evaluator, store, permission
+registry, platform-owner bootstrap, and HTTP enforcement — but explicitly deferred module
+permission registration: a module manifest (ADR 0006, `manifestVersion: 2`) could declare a
+`permissions` array, but only as bare namespaced strings. That was enough to validate a namespace
+at manifest-parse time, but not enough to *register* anything: Core's authorization registry needs
+a trusted baseline and an operator-facing description for every permission it enforces, and a bare
+string carries neither. Phase 5A closes that gap in two passes on this branch: pass 1
+(`feat: declare module permissions`) established the shared declaration contract, manifest version
+3, and a pure composition function; pass 2 (`feat: integrate module authorization`) wired the
+composed registry into `apps/api`'s production startup and its existing enforcement/explicit-grant
+HTTP surface. This ADR records the durable architecture both passes established.
+
+## Decision
+
+### `PermissionDeclaration` is the one shared, contracts-layer definition
+
+`packages/contracts/src/authorization.ts`'s `permissionDeclarationSchema` is the single
+authoritative shape of a registered permission declaration — `id` (a branded `PermissionId`),
+`baseline` (`public`/`authenticated`/`restricted`, the evaluator's trusted baseline), and
+`description` (required, trimmed, non-empty, capped at 240 characters). `.strict()` rejects any
+other property. Both Core's own authorization registry
+(`core/src/authorization/permissions.ts`) and a module manifest's `permissions` array
+(`packages/contracts/src/module-manifest.ts`) consume this exact type — Core does not declare a
+second, independently maintained interface, and a module cannot smuggle extra fields into a
+declaration Core treats as trusted. `description` is informational only: audit and operator UI
+text, never read or interpreted by the evaluator, the registry, or enforcement — changing it can
+never change what a permission allows.
+
+### Module manifests are inert JSON and the sole permission-declaration source
+
+A module's `ekklesia.module.json` remains inert, static data Core parses without executing any
+module code — consistent with ADR 0006's discovery model. Its `permissions` array is the only
+place a module declares permissions; nothing in `defineModuleRuntime` (Module SDK,
+`packages/module-sdk/src/define-module-runtime.ts`) repeats, duplicates, or otherwise re-declares
+permissions, baselines, or descriptions — exactly like it already does not repeat capabilities,
+dependencies, storage requests, or entrypoints (ADR 0006). Core never imports or runs a module's
+server entrypoint, job, or lifecycle hook to discover its permissions; only the manifest is read.
+
+### Manifest version 3 replaces version 2's bare permission strings
+
+Representing a permission as a complete declaration instead of a bare identifier string is an
+incompatible manifest shape change, so the canonical manifest moves to `manifestVersion: 3`
+(`z.literal(3)`). Version 2 — and any other version — fails validation outright; there is no
+compatibility adapter, no automatic conversion from a string array to declarations, and no dual
+acceptance of both shapes. A module author must rewrite `permissions` explicitly. `permissions`
+still defaults to an empty array when the field is omitted entirely, exactly as version 2 did.
+
+### Each module owns exactly its own namespace; `core.*` is reserved
+
+A permission id declared in a module's manifest must begin with `<module-id>.`, checked the same
+way a capability id already is (ADR 0006). Module ids never contain a dot (`moduleIdSchema` is
+plain kebab-case), so the only module whose manifest could ever declare a `core.`-prefixed
+permission and still pass this per-manifest namespace check is one whose own id is literally
+`"core"` — `core.*` itself remains reserved for Core's own permissions, enforced independently at
+composition time (below). Duplicate permission ids within one manifest fail manifest validation at
+the exact issue path `permissions[index].id`, mirroring the existing capability and storage-bucket
+duplicate checks.
+
+### Core and installed-module declarations compose into one immutable registry
+
+`composePlatformPermissionRegistry` (`core/src/modules/permissions.ts`) builds the platform's one
+permission registry from Core's own declarations (`CORE_PERMISSION_DECLARATIONS`) plus every
+already-discovered module's declarations. It reuses `createPermissionRegistry`
+(`core/src/authorization/permissions.ts`) rather than reimplementing registry construction or
+duplicate detection — there is no second, module-specific registry type. Order is deterministic:
+Core's declarations first, then each module in the exact order it appears in the caller-supplied
+list, then each module's own declarations in manifest-array order. The resulting registry, and
+every declaration it exposes, is immutable (`Object.freeze`), matching `createPermissionRegistry`'s
+existing guarantee. Composition is pure, synchronous, in-memory work over data the caller already
+discovered: no filesystem, environment, database, network, or module-code operation happens inside
+it.
+
+`core/src/authorization` continues to know nothing about modules — it does not import module
+discovery or runtime. `core/src/modules/permissions.ts` is the one-directional module-integration
+layer that depends on `core/src/authorization`, never the reverse.
+
+### The structural collision guarantee
+
+A discovered module contributing any `core.`-prefixed permission id fails composition with
+`ModulePermissionCompositionError` (`MODULE_PERMISSION_RESERVED_NAMESPACE`) — checked, and thrown,
+before that declaration is ever added to the list `createPermissionRegistry` sees. This is a
+deliberate architectural guarantee, not an incidental test limitation, and it follows from three
+facts holding simultaneously: real module discovery rejects a duplicate module id
+(`MODULE_ID_DUPLICATE`), so module ids are unique; a manifest's own namespace check requires every
+permission id to begin with `<module-id>.`; and a manifest already rejects a duplicate permission
+id within itself. Together, these mean a module can only ever produce a `core.`-prefixed permission
+if its own id is literally `"core"` — and when it does, that declaration is caught by the
+reserved-namespace check specifically, never by `createPermissionRegistry`'s generic duplicate
+detection (`PermissionRegistryError`, `PERMISSION_REGISTRY_DUPLICATE_DECLARATION`). The same three
+facts also mean a genuine *module-vs-module* exact permission-id collision cannot arise from a
+valid, really-discovered installed-module set at all — two different module ids can never produce
+the identical permission string. `createPermissionRegistry`'s own duplicate rejection remains in
+place regardless, as an unconditional, defense-in-depth guarantee of the underlying registry
+primitive; both Core's test suite and this composer's own tests exercise it directly with
+deliberately conflicting internal test data (not reachable through real discovery), specifically to
+prove the guarantee holds even though production traffic cannot currently trigger it. Both error
+families carry only a module id and/or permission id — never a module directory, manifest path,
+caught cause, or stack.
+
+### Module discovery and permission composition precede all database and HTTP construction
+
+`apps/api`'s `startApi()` (`apps/api/src/server.ts`) composes the platform registry
+(`composeStartupPermissionRegistry`, `apps/api/src/platform-permissions.ts`) as its first step,
+strictly before constructing the shared PostgreSQL pool, Better Auth, the authorization store and
+evaluator, the Hono application, or binding the HTTP server. A discovery or composition failure —
+an invalid manifest, an incompatible dependency graph, a reserved-namespace claim, or a duplicate
+declaration — therefore has nothing to close: it propagates directly out of `startApi()`, and
+startup never falls back to a Core-only registry. Modules are discovered exactly once for this
+composition; nothing re-discovers them a second time for permissions specifically.
+
+Repository and package-version information is derived from the installed repository's own layout —
+never `process.cwd()`, which a package-scoped test run does not set to the repository root. The
+repository root is resolved from the composing module's own compiled/source file location (a fixed
+number of directory levels up, identical whether running `apps/api/dist/*.js` or, under a test
+runner, `apps/api/src/*.ts`); the platform and Module SDK versions are read from their real
+`package.json` files, only when startup actually executes — never merely by importing the API's
+server, config, or app modules, which remain side-effect-free at import time.
+
+### API enforcement and explicit grants use one registry for Core and module permissions alike
+
+`createApiApp` requires the composed platform registry as an injected authorization option;
+`startApi` is the only production caller, and it always supplies the registry
+`composeStartupPermissionRegistry` produced. There is no `CORE_PERMISSION_REGISTRY` fallback
+anywhere in `apps/api` — not in `createApiApp`, not in `createGrantsRoutes`, not in the
+`requirePermission` middleware. `requirePermission` has no notion of "Core" versus "module"
+permissions; it resolves a route's declared `PermissionId` and its trusted baseline from whichever
+registry it is given, denies before principal resolution or evaluator access when the permission is
+unregistered, and never accepts a baseline, actor, or any other authorization-relevant field from
+client input. A module's `public`, `authenticated`, or `restricted` declaration is therefore
+enforced identically to Core's own `core.authorization.grants.manage`, through the identical
+evaluator and grant path, and — because registration and evaluator shape validation remain the two
+separate, independent fail-closed layers ADR 0013 established — a well-formed but unregistered
+permission (module or Core) still receives a sanitized `403` with no store or audit write, whether
+the request is a permission check or an explicit-grant creation attempt on `POST /api/v1/grants`.
+
+### The registry is a static startup snapshot
+
+There is no hot installation, removal, or dynamic mutation of the composed registry while `apps/api`
+is running. Installing, removing, or editing a module's manifest takes effect only on the next API
+restart. Removing a module from the next startup's discovered inventory makes its permission
+unknown to new authorization checks and new explicit grants — it denies exactly like any other
+unregistered permission — but never deletes, revokes, or otherwise modifies a historical grant or
+audit row already recorded for that permission. A previously granted, still-unrevoked explicit
+grant remains listed through `GET /api/v1/grants`, and revoking it explicitly remains possible,
+since revocation is keyed to the grant's own id and source kind, not to whether its permission is
+currently registered. What happens if the exact same permission id is later reinstalled or
+reactivated in a future startup — whether a preserved, still-active grant becomes effective again
+automatically — is **explicitly not decided by this ADR** and remains deferred; nothing here should
+be read as a guarantee either way.
+
+### Doctor and `modules:validate` compose the same inventory
+
+`pnpm doctor`'s `modules.permissions` check and `pnpm modules:validate` both call
+`composePlatformPermissionRegistry` over the module list their own already-completed discovery
+produced — neither rediscovers modules solely to check permissions. A structurally valid manifest
+that claims the `core.*` namespace, or that would produce a duplicate declaration, now fails before
+that module is considered installable (`modules:validate`) or reported healthy (`doctor`).
+
+### Test-only discovery overrides are not a production configuration surface
+
+`composeStartupPermissionRegistry`'s `modulesDirectoryOverride` and `discoveredModulesOverride`
+exist solely so tests can exercise discovery and composition against controlled fixtures or
+deliberately conflicting data — the latter specifically because a genuine module-vs-module
+duplicate is otherwise unreachable through real discovery, as established above. Neither is read
+from an environment variable, an HTTP header, or any other client- or deployment-controlled input;
+`main()`, the executable entry point, never sets either.
+
+## Alternatives
+
+- **Runtime, code-based permission registration** (a module registering permissions imperatively
+  from its server entrypoint or a registration hook) was rejected: it would require executing
+  module code to discover what a module can even offer, breaking the inert-manifest discovery
+  model ADR 0006 already established and that Doctor and `modules:validate` depend on for
+  offline, side-effect-free validation.
+- **A second, module-specific registry implementation** was rejected in favor of reusing
+  `createPermissionRegistry` — a second implementation would need to reimplement duplicate
+  detection, immutability, and fail-closed lookup independently, with no guarantee the two stayed
+  behaviorally identical.
+- **Falling back to `CORE_PERMISSION_REGISTRY` when discovery or composition fails** was rejected:
+  it would let the API start in a state where module-declared permissions silently do not exist,
+  which is indistinguishable from "no modules were ever installed" and would mask a real
+  configuration error as ordinary, healthy startup.
+- **Dynamic, mutable, or hot-reloaded registration** (updating the registry while the process
+  runs, without a restart) was rejected for this phase: it introduces concurrent-mutation and
+  partial-update hazards this phase does not need to solve, and a static snapshot is sufficient
+  for the current deployment model.
+- **Silently accepting version-2 manifests** (auto-converting a bare permission string into a
+  declaration with a synthesized baseline/description) was rejected: any synthesized baseline
+  would be a guess Core cannot trust, and the whole point of requiring a real declaration is that
+  the baseline and description come from the module author, not from Core inventing them.
+- **Deleting or automatically revoking a module's grants when the module disappears** was
+  rejected: it would destroy an audit trail that must remain queryable regardless of a module's
+  current installation state, and revocation is a deliberate, actor-attributed action elsewhere in
+  this system (ADR 0013) — an uninstall is not that action.
+- **Reading a permission's baseline from HTTP request input** (letting a caller assert which
+  baseline to check) was already rejected by ADR 0013 and remains rejected here: the baseline is
+  never anything but the registry's own trusted value for a request-supplied `PermissionId`.
+
+## Consequences
+
+A module gains a real, enforceable permission the moment its manifest is written correctly and the
+module is discovered — no separate registration step, no code to write beyond the manifest itself.
+Core's own permissions and every module's permissions share one enforcement mechanism end to end:
+one registry, one middleware, one explicit-grant HTTP API. The reserved `core.*` namespace and the
+structural collision guarantee mean a module can never accidentally or deliberately shadow a
+Core-owned permission without that attempt being caught, sanitized, and reported as exactly what it
+is. The cost is the one explicitly deferred question this ADR leaves open — reinstall/reactivation
+semantics for a permission whose module was previously removed — and the operational fact that
+every module inventory change requires an API restart to take effect, which is acceptable for the
+current deployment model but not the final word on it.
+
+## Deferred
+
+Module HTTP route-registration contracts (a module mounting its own endpoints); a
+`ModuleRuntimeContext` authorization service; relationship-derived grant creation (a roster or
+similar module operation using `sourceKind: "relationship"`, not the generic explicit-grant API);
+reinstall/reactivation policy for a permission whose owning module was previously removed;
+roles, groups, teams, and tenants; an owner-management HTTP endpoint; service accounts and API
+tokens for non-browser automation; module installation/uninstallation state and hot reload; Surfaces
+and UI; and workflow/event automation. None of these are implemented by, or required for, the
+architecture this ADR records.

docs/architecture/decisions/README.md

@@ -22,3 +22,4 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0011: Identity HTTP transport and public enrollment policy](0011-identity-http-transport-and-public-enrollment.md) — Accepted
 - [0012: Production-equivalent identity origin/CSRF protection under test](0012-identity-origin-csrf-protection-under-test.md) — Accepted
 - [0013: Core authorization, permission registry, and platform-owner bootstrap](0013-core-authorization-and-owner-bootstrap.md) — Accepted
+- [0014: Module permission declarations and platform permission registry](0014-module-permission-declarations-and-platform-registry.md) — Accepted

docs/development/authorization.md

@@ -1,24 +1,29 @@
 # Authorization
 
-Phase 4C establishes Core's authorization foundation and, in a second slice, wires it into
-`apps/api` over HTTP. This page covers both: the schema/evaluator/store/registry Core owns, the
-platform-owner bootstrap operation, and the enforcement/endpoints `apps/api` exposes on top of it.
-See [Identity](identity.md) for the identity foundation this builds on, [API](api.md) for the
-HTTP transport it is mounted into, and [ADR
-0013](../architecture/decisions/0013-core-authorization-and-owner-bootstrap.md) for the durable
-architectural decisions this page describes in more implementation detail.
+Phase 4C establishes Core's authorization foundation and wires it into `apps/api` over HTTP. Phase
+5A extends that same system so an installed module's declared permissions are enforced and
+grantable through the identical mechanism as Core's own. This page covers all of it: the
+schema/evaluator/store/registry Core owns, the platform-owner bootstrap operation, the
+enforcement/endpoints `apps/api` exposes, and how module manifests contribute to the one platform
+permission registry. See [Identity](identity.md) for the identity foundation this builds on,
+[API](api.md) for the HTTP transport it is mounted into, [Module development](../module-development/README.md)
+for the manifest shape that declares module permissions, and
+[ADR 0013](../architecture/decisions/0013-core-authorization-and-owner-bootstrap.md) /
+[ADR 0014](../architecture/decisions/0014-module-permission-declarations-and-platform-registry.md)
+for the durable architectural decisions this page describes in more implementation detail.
 
 ## What this is, and is not
 
-After this slice, an operator can bootstrap exactly one platform owner for a deployment, a
-platform owner (or anyone they delegate to) can create, list, and revoke *explicit* authorization
-grants over HTTP, and every enforced route fails closed on infrastructure trouble instead of
-silently allowing or denying. It is **not** possible to manage roles, groups, teams, or tenants;
-there is no owner-management HTTP endpoint (revoking or re-granting platform-owner status is not
-exposed at all in this slice); there are no service accounts or API tokens, so only
-cookie-authenticated browser callers can reach the mutation routes; and relationship-derived
-grants (for example, automatic access from a roster assignment) cannot yet be created by anything
-in this repository — the generic grants API structurally cannot create or revoke them either.
+An operator can bootstrap exactly one platform owner for a deployment; a platform owner (or anyone
+they delegate to) can create, list, and revoke *explicit* authorization grants over HTTP for any
+registered permission, Core-owned or module-owned; and every enforced route fails closed on
+infrastructure trouble instead of silently allowing or denying. It is **not** possible to manage
+roles, groups, teams, or tenants; there is no owner-management HTTP endpoint (revoking or
+re-granting platform-owner status is not exposed at all); there are no service accounts or API
+tokens, so only cookie-authenticated browser callers can reach the mutation routes; a module cannot
+yet mount its own HTTP routes; and relationship-derived grants (for example, automatic access from
+a roster assignment) cannot yet be created by anything in this repository — the generic grants API
+structurally cannot create or revoke them either.
 
 ## Core authorization schema and store
 
@@ -132,11 +137,16 @@ registry Core's own `core.authorization.grants.manage` permission is registered
 module-owned permission and Core's own are enforced, and grantable, through the identical
 mechanism — there is no module-specific enforcement path. Removing a module from the next
 startup's discovered inventory makes its permission unknown to new authorization checks and new
-grants (a well-formed but unregistered permission denies exactly as before); it never deletes,
-revokes, or otherwise modifies a historical grant or audit row already recorded for that
-permission — a previously granted, still-unrevoked explicit grant for a now-uninstalled module's
-permission remains visible through `GET /api/v1/grants` and simply stops being something anyone
-can newly grant, revoke, or have authorized against.
+grants (a well-formed but unregistered permission denies exactly as before, including on
+`POST /api/v1/grants`, which checks the registry explicitly before calling the store); it never
+deletes, revokes, or otherwise modifies a historical grant or audit row already recorded for that
+permission. A previously granted, still-unrevoked explicit grant for a now-uninstalled module's
+permission remains visible through `GET /api/v1/grants` and simply stops being something a
+`restricted`-baseline authorization check can newly succeed against. Listing and explicit
+revocation (`POST /api/v1/grants/:grantId/revoke`) are unaffected either way: neither route
+consults the registry for a grant that already exists — revocation is keyed to the grant's own id
+and source kind, not to whether its permission is currently registered — so a manager can still
+revoke a historical grant for a now-unregistered permission.
 
 Module HTTP route registration (a module owning its own mounted endpoints) and relationship-derived
 grant creation both remain deferred, unrelated slices — this work only makes a module's *declared*
@@ -477,8 +487,10 @@ pnpm test:migrations:integration   # requires Docker
 
 ## Next phase
 
-Phase 5A, pass 3: deferred from this slice — module HTTP route-registration contracts (a module
-mounting its own endpoints), a module runtime-context authorization service, relationship-derived
-grant creation itself (a roster or similar module operation, not the generic grants API),
-roles/groups/teams/tenants, an owner-management HTTP endpoint, and service accounts/API tokens for
-non-browser automation.
+Deliberately deferred, unrelated slices — see
+[ADR 0014](../architecture/decisions/0014-module-permission-declarations-and-platform-registry.md#deferred)
+for the complete list: module HTTP route-registration contracts (a module mounting its own
+endpoints), a module runtime-context authorization service, relationship-derived grant creation
+itself (a roster or similar module operation, not the generic grants API), reinstall/reactivation
+policy for a permission whose owning module was previously removed, roles/groups/teams/tenants, an
+owner-management HTTP endpoint, and service accounts/API tokens for non-browser automation.