# Semantic Documentation Subjects

## Purpose And Ownership

The semantic-documentation subject contract lets an optional module expose the
configured artifacts that administrators may document: for example a form, a
form field, a workflow, or a workflow state. It is a discovery and resolution
contract, not a second configuration API.

The module that owns an artifact also owns its subject provider, authorization,
identity, revision, route, and lifecycle semantics. Docs may discover those
providers through Core and attach authored documentation to their stable
references. Docs must not import the feature module, read its tables, or copy
configuration content into a generic index.

This contract is additive to manifest `DocumentationTopic` contributions and
configured-state `documentation_providers`. Every providing module must retain
static user and administrator documentation baselines. The baselines explain
the feature even when the provider is disabled, unavailable, or has no
configured subjects.

## Identity And Versioning

`SemanticDocumentationSubjectReference` identifies a subject with:

- owning module and tenant;
- a module-defined subject kind and stable identifier;
- an optional typed nested anchor, such as `field/registration-number`;
- the revision and canonical fingerprint observed when documentation was
  authored or reviewed.

The `stable_key` derives only from identity. A rename or configuration revision
therefore does not detach existing documentation. A nested anchor has its own
identity so a field can be documented independently from its form.

Providers must resolve an old reference as one of:

- `available`: the observed revision/fingerprint is still current;
- `changed`: the same stable subject has changed and may need review;
- `superseded`: another stable reference replaced it;
- `missing`: the subject was removed or is no longer resolvable;
- `temporarily_unavailable`: the provider cannot currently determine state.

Absence is not authorization. A provider returns `None` when the principal may
not learn whether a subject exists. Core also rejects cross-tenant list and
resolution requests before calling a provider.

## Safe Projection

Descriptors contain only bounded, explicit presentation fields: localized
labels and descriptions, breadcrumbs, a local route, audience,
classification, and required scopes. They must not contain credentials,
personal data, arbitrary provider metadata, configuration payloads, or the
authored documentation itself. Routes are application-local and are still
subject to normal route authorization.

The fingerprint is a review signal, not a concurrency token or a content hash
that callers may use to reconstruct configuration. Providers should calculate
it from the smallest canonical JSON projection whose semantic changes require
documentation review. Volatile timestamps and secrets must be excluded.

## Provider Registration

A provider is registered under its exact module-scoped capability name:

```python
from govoplan_core.core.modules import CapabilityDocumentation
from govoplan_core.core.semantic_documentation import (
    SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
    semantic_documentation_subject_capability,
)

capability = semantic_documentation_subject_capability("forms")

manifest = ModuleManifest(
    id="forms",
    # ...
    capability_factories={capability: build_semantic_subject_provider},
    capability_documentation={
        capability: CapabilityDocumentation(
            label="Form semantic subjects",
            summary="Lists authorized configured forms and fields for Docs.",
            contract_version=SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
            documentation_types=("admin", "user"),
        )
    },
    documentation=(admin_baseline, user_baseline),
)
```

The capability is `documentation.semantic_subjects.<module_id>`. Registry
validation rejects a mismatched owner, missing capability documentation, a
wrong contract version, or missing static baselines.

`list_semantic_documentation_subjects` performs authorized, paginated discovery
across installed providers. `resolve_semantic_documentation_subject` targets
one owner without loading another feature module. Providers must apply the
current tenant and principal on every call and must not infer visibility from a
previous list result.

## Lifecycle And Integration Rules

- Keep subject and anchor identifiers stable across display-name and route
  changes.
- Return `superseded` only with the replacement reference; do not silently
  rewrite stored references.
- Return a reason code for missing or temporarily unavailable subjects without
  exposing sensitive detail.
- Reauthorize both discovery and resolution. Stored documentation references
  confer no access to a live artifact.
- Treat a changed fingerprint as a request for editorial review. It does not
  automatically invalidate or publish authored documentation.
- Removing a feature module leaves references resolvable as provider
  unavailable. Docs can preserve history without importing the module.

Forms, Workflow, and later modules should implement their subject providers in
their own repositories. Docs owns the authored semantic-documentation records,
review workflow, and projection UI.