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

9.1 KiB

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. 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

  • AP-0: durable recipient Inbox storage, scoped list/read API and keyset pagination.
  • 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.
  • 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.