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.
149 lines
9.1 KiB
Markdown
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.
|