4.4 KiB
Tenant semantic documentation
Docs stores tenant-specific explanations of stable configured subjects supplied by owning modules. Forms and Workflow are the first providers; additional modules can implement the Core semantic-subject contract without Docs importing their internals.
Lifecycle and authorization
An entry is unique by tenant, stable subject identity, anchor, and locale. Every create, edit, publish, supersede, and retire operation appends an immutable revision and requires optimistic concurrency. A published revision remains reader-visible while a newer draft is being reviewed.
The tenant setting docs.semantic_publication_policy accepts:
reviewer_required(default): the account that authored the current draft cannot publish it.direct: an author with the publish permission may publish their own draft.
Creation, editing, publication, supersession, retirement, tenant export, and policy changes use separate permission scopes. All mutations write audit events containing stable references and revision numbers, never the authored prose.
Reads always intersect:
- active tenant isolation;
- current authorization returned by the owning subject provider;
- scopes required by that subject;
- the semantic entry's classification and typed audience selectors;
- publication state and requested locale.
The same read-time check protects direct entry URLs, search authorization rechecks, contextual consumers, and tenant export. Provider denial is indistinguishable from absence. Changed, superseded, missing, and temporarily unavailable subjects are represented explicitly; locale fallback is exposed in the response.
Content and safety
Semantic content is bounded plain text. Links must be local absolute paths or HTTPS URLs without embedded credentials. Restricted content requires at least one typed audience selector: account:, group:, role:, function:, scope:, or authenticated.
Search indexes only published revisions and always requires provider reauthorization before returning a result. Generic public documentation generation reads static manifest topics only, so it cannot include tenant semantic entries. The separately authorized tenant export includes current entries and immutable history and sends private, no-store.
Collection/context projection and search authorization load required revisions in request-local batches of at most 400 identifiers. Read-only projection loads published content only, never pending draft bodies, and remains available if a pending draft reference is broken. Editors still receive an explicit error for an unavailable current revision. Revision tenant, entry, and publication-state references must agree before content is projected or indexed. An audience denial is checked before calling the subject provider; an allowed audience does not replace the provider's current permission checks.
This reduces Docs-owned database round trips without caching authorization between requests or importing subject-module internals. Owner-provider reads remain independent. The batch size is not a collection or export limit: complete semantic catalogues and separately authorized history exports can still require work proportional to their size.
Backup, recovery, and module removal
Back up docs_semantic_entries and docs_semantic_revisions together with Core tenant and audit state. Restoring only one table breaks revision pointers and is unsupported. The installer blocks normal uninstall while rows remain. Destructive retirement is explicit, requires a database snapshot, and drops revision history before entries.
Published authorship and review references are retained as configuration-governance evidence during data-subject erasure. Draft attribution is returned for governed manual review rather than silently anonymized because ownership and stewardship may need reassignment first.
Provider obligations
An owning module registers exactly documentation.semantic_subjects.<module_id> with Core contract version 1. It must return only tenant-local, currently authorized descriptors; stable subject and anchor IDs; current revision and fingerprint; localized labels; and relevant route and scope metadata. Resolution must return None when a principal may not learn whether a subject exists.
Provider unavailability does not expose stored content. Subject deletion or replacement must produce an explicit missing or superseded resolution so configurators can govern the documentation lifecycle.