58 lines
4.4 KiB
Markdown
58 lines
4.4 KiB
Markdown
# 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.
|