Files
pages/docs/design/publication-approval-inbox.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

149 lines
9.1 KiB
Markdown

# Hierarchical publication approval and reviewer Inbox
Status: reviewer/approval workflow remains design / implementation TODO. The
recipient-scoped notification Inbox storage and read API are implemented as a
first slice; approval request producers, reviewer UI and decision lifecycle are
not enabled yet. As of
2026-09-19, explicit Street/Spot live-head publication is implemented separately in
[automatic-publication.md](automatic-publication.md). Existing scopes still default
to exact current-revision approval. No reviewer requests, Inbox or implicit opt-in
are introduced by that implementation.
## Separate audience, approval and revision-following policies
Public/read/write audience controls answer *who may access*. Approval controls
answer *whether a proposed publication needs review*. Neither grants the other's
authority. In particular, an approval must never bypass an ancestor audience
cap, a user/group restriction, or the current actor's read/publish authority.
Each Campus → Domain → Quartier → Street → Spot → Page/Path boundary can carry:
- `approval: inherit | required | not_required`;
- reviewer selection by stable Principal/membership or group UUIDs;
- review quorum (initial implementation: one independent reviewer), expiration
and optional self-approval prohibition (initial default: prohibited).
`required` is a superior floor: effective approval is required if any ancestor
requires it; a subordinate `not_required` cannot turn it off. With no inherited
floor, the owner may choose `required` or `not_required` within delegated
governance authority. Newly introduced policy defaults preserve today's explicit
approval requirement. Campus policy is a signed, versioned inherited ceiling for
managed instances, not a remotely writable local bypass.
Reviewer eligibility is also constrained by superior delegation. A subordinate
cannot satisfy required review by appointing an arbitrary reader, itself, or a
group it controls. Reviewers need explicit review authority for this scope and
read authority over every proposed source. A Domain administrator's recovery
override, if added, is a separate explicit, audited action, not a silent quorum
bypass. No approver available means blocked/pending, never automatic approval.
`not_required` means an authorized publication action can proceed after the
same impact and audience validation without waiting for another person's review.
It does **not** turn every edit/new child public. A future `revision_policy:
frozen | follow_head` must be explicit and separately constrained by ancestors;
the initial implementation keeps exact approved revision tuples. Visibility
tightening and revocation are immediate and must never wait for approval.
## Request lifecycle and immutable subject
1. Publisher previews the bounded exact Path/Object/Revision/SHA-256/language
set, dependencies and alias impact.
2. If review is required, create an idempotent `pending` request, an audit event
and a notification outbox record in one reserved SQLite write transaction.
3. Resolve eligible reviewers and deliver an Inbox item via the event queue.
Notification delivery failure retries independently of the pending request.
4. The reviewer opens the Inbox item, re-authenticates as needed, sees a current
permission-filtered impact/diff, then approves, rejects, or requests changes.
5. Approval atomically rechecks current membership/reviewer authority, audience,
all governance and approval-policy versions, source heads/bindings, expiry,
quorum and request generation. Only then activate the publication manifest.
Terminal states: `approved`, `rejected`, `withdrawn`, `expired`, `superseded`.
An intervening edit, path move, changed audience/policy, or obsolete reviewer
authority makes the old request unusable; it cannot approve a newer head.
Superseded requests keep their audit record and link to an explicitly resubmitted
replacement. Rejection does not grant access or silently change content.
CAS transitions and idempotency prevent double approvals or replay after revoke.
The requester can withdraw its pending request. Authorized superior governance
can cancel requests for the scope. Approval history cannot be erased by clearing
an Inbox item or deleting its notification. Group changes may reroute undelivered
notifications but do not silently alter the immutable publication subject.
## Notification Inbox
- Inbox entries are recipient-specific, with unread/read state, creation time,
event kind, request status and a safe internal deep link. Inbox counts and
queries are scoped to the current Principal and Domain.
- Store request IDs and minimal event metadata, not document text, titles of
unreadable Paths, bearer tokens, preview bodies or unfiltered reviewer lists.
- On listing and opening, recheck live eligibility. If permissions are removed,
show a generic unavailable/resolved item without the protected title or diff.
A notification itself is not a read or approve capability.
- First slice: in-product Inbox only. SMTP/push notifications are separate,
opt-in channels fed by the same durable outbox and disclosure checks.
- Group fan-out is bounded and deduplicated by `(event, recipient, channel)`;
large reviewer groups are delivered in batches. Delivery retries cannot create
multiple requests or make a stale request approvable.
- Cross-instance routing must use the authoritative Domain. Do not copy an
approval request into another Domain and treat it as locally authoritative.
## Persistence and API status
- `publication_approval_policies`: scope, mode, reviewer constraints, policy
generation, actor, timestamps; separate from audience/publication intent.
- `publication_requests`: immutable subject digest/manifest, source and policy
versions, requester, state, generation, expiry, idempotency key.
- `publication_decisions`: request, reviewer stable ID, decision, justification,
timestamp; append-only audit, unique reviewer vote per request generation.
- Domain activity outbox and recipient Inbox tables from the notification
roadmap are implemented with indexed `(domain, recipient, unread, created_at,
id)` keyset pagination. `GET /_/api/v1/notifications` lists the current
principal's entries and accepts `unread=1`, `limit`, and `before`; `POST` or
`PATCH /_/api/v1/notifications/read` marks one entry read. Both routes are
authenticated and domain/recipient scoped. Inserts are idempotent by
`(domain, recipient, event, kind)`.
Suggested handler-owned routes under the existing scope's `.../governance/`:
`approval-policy`, `approval-requests`, and request UUID `/decisions` and
`/withdraw`. Recipient listing/read-state endpoints belong to the common
`/_/api/v1/notifications` namespace, not City or adapter-specific plugins.
Final route names must be registered and verified against the endpoint inventory
at implementation time. GET never approves; mutations use POST/PATCH with the
existing browser-origin guard and strict JSON limits.
## Implementation order / TODO
- [x] AP-0: durable recipient Inbox storage, scoped list/read API and keyset
pagination.
- [x] AP-0.5: immutable request subject/generation persistence and bounded
expiry sweep. The scheduler expires only pending requests with an explicit
deadline; reviewer eligibility and decisions are still handler-gated TODO.
- [x] AP-0.75: authenticated request/decision API. `POST
/_/api/v1/publication/requests` accepts a bounded subject manifest and
idempotency key, validates Domain review authority, and optionally creates
recipient-scoped Inbox notifications. `POST
/_/api/v1/publication/requests/{uuid}/decisions` is Domain-scoped, checks the
current reviewer authority, and enforces generation/state CAS. Full policy
inheritance and quorum evaluation remain required before production use.
- [ ] AP-1: schema, inheritance evaluator and scoped policy settings; superior
required floors, reviewer delegation limits and backward-compatible defaults.
- [ ] AP-2: immutable request/decision lifecycle, idempotency/CAS, transactional
revalidation, stale-source handling and audited emergency/revocation rules.
- [ ] AP-3: durable Domain outbox → scheduler queue → deduplicated recipient Inbox;
live authorization checks, bounded fan-out, retention and retry visibility.
- [ ] AP-4: topbar notification indicator, Inbox subpage, request impact/diff
dialog, approve/reject/withdraw UI and Japanese/English strings.
- [ ] AP-5: explicit `not_required` publication path through the same safety
validation; migration must not publish old drafts or pending requests.
- [ ] AP-6: managed-Campus policy inheritance and authoritative-instance routing;
signed generations, unavailable-controller behavior and revocation propagation.
- [ ] Tests: competing approvals/revocations, self-approval, reviewer/group removal,
private Inbox counts/title/diff leakage, expiry, retry deduplication, policy
tightening while queued, source changes, wrong Domain and cache invalidation.
Navigation-free single-document presentation is reserved for a future share URL
projection (for example `/s/`), not ordinary public Pages. Share tokens remain
purpose-bound credentials with separate scope, expiry and revocation checks;
this design does not authorize a new share endpoint or widen an existing one.