Files
pages/docs/design/automatic-publication.md
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

71 lines
4.3 KiB
Markdown

# Scoped automatic publication
Implemented 2026-09-19. Explicit opt-in, local Domain policy; no existing scope is
enabled by migration or deployment. This is a live-head publication mechanism,
not the reviewer/Inbox workflow in `publication-approval-inbox.md`.
## Scope and controls
- City detail → governance dialog → Automatic publication → preview current impact.
- `inherit`: no local automatic rule; ancestor automatic rules may apply.
- `required`: manual publication only, including descendants. A descendant cannot
override this floor by selecting automatic. Supported at Domain/Quartier/Street/Spot.
- `automatic`: supported only at Street/Spot, with an effective public audience.
Existing eligible Pages, future descendants (including moved-in Pages) and all
current language heads are public immediately. Empty scopes can opt in too.
- Existing public audience ceilings and user/group restrictions remain authoritative.
Aliased Objects, reserved Paths and restricted descendant scopes remain excluded.
- Automatic and inherited activation require confirmation of current impact and
future publication. Preview binds actor/scope/governance/topology and all automatic
rule versions. CAS plus SQLite writer reservation reject stale or concurrent edits.
- Stopping automatic publication does not revoke separately frozen approvals. Use
audience restriction for complete privacy. Existing publication-revoke also sets
this scope to manual-only to stop automatic publication inherited from an ancestor.
## Authority, data and read behavior
`locality_auto_publication` stores Domain, node kind/UUID, mode, pinned Path boundary,
enabling Principal and version. The enabling Principal must remain an active member
with current governance and scoped read authority. Existing owner/admin delegation
is reused; ownership, membership and role revocation suspend the corresponding grant.
Audit records use `city_governance_events`; no silent new grants or source-content edits.
Automatic publication uses a read transaction, not materialized approval entries or
an asynchronous job. This gives read-after-write publication for authorized posts,
CLI writes and edits without a stale scheduler window. Anonymous body/raw reads,
public navigation, projected blog/diary titles, RSS and share readiness use the same
rules. Manual exact-Revision approvals remain the default and remain separate.
The boundary is pinned to the configured Path; renaming the Street/Spot boundary
suspends its grant until explicitly reconfirmed. Moving a Page outside the boundary
does not carry publication with its UUID. Audience restrictions are checked live.
Domain/Campus disablement and authorization-mode changes fail closed. Enforcing
authorization cannot be switched off while an automatic rule remains configured.
Public-navigation generations include automatic rules and their authority sources.
Role/member invalidation is conditional on the existence of automatic rules, keeping
the existing invariant that ordinary authenticated navigation never caches ACLs.
## API and budgets
`GET/PATCH /_/api/v1/city/{zones|spots|domains}/{uuid}/governance/auto-publication`
uses the existing authenticated handler-owned governance authorization. PATCH fields:
`mode`, `version`, `epoch`, `topology_version`, `confirm`, `impact_token`.
GET never grants publication. Strict JSON and 4KiB input limits apply.
Impact previews retain the existing 512-Path limit; a too-large preview still permits
manual-only shutdown, but not activation. Live navigation is metadata-only and bounded
by 20,000 entries / 4MiB with a 2-second caller deadline. Exact body lookup restricts
the query to the requested Path. Policy enumeration is capped at 128 local rows.
Errors/budget exhaustion do not fall back to public/unfiltered content.
## Remaining work
- Independent reviewer policies, requests, quorum, Inbox and signed Campus inheritance.
A future `approval=required` floor must also block this live-head publication mode.
- Federation of these policies is not implemented; no automatic-policy fields are
added to Domain provisioning manifests.
- Larger activation previews need paginated impact review/token binding rather than
silently lifting the current limit. Policy tombstone/archived-node cleanup is pending.
- External caches, feed-reader copies and already-posted social links cannot be recalled.