[Contract] Expose stable semantic-documentation subjects from modules #292

New Issue

2026-08-21T00:07:02+02:00

zemion commented

2026-08-21 00:07:02 +02:00

Problem

Docs can render module-owned topics and configured-state provider output, but tenant-authored semantics need a stable, authorized reference to the configured artifact they describe. Docs must not learn feature-internal models or persist copies of executable configuration.

Proposed contract

Add a typed cross-module subject descriptor and provider/resolver boundary for artifacts that may receive semantic documentation. The exact names are implementation details, but the contract must cover:

module and subject kind;
a tenant-scoped, deterministic stable identifier and optional nested anchor such as a field or step;
localized display label, safe description, hierarchy/breadcrumbs, contextual route/anchor, and owning-module provenance;
a revision or semantic fingerprint that lets Docs detect when authored content needs review;
availability state and safe rename/deletion/supersession handling;
audience/classification metadata that may narrow visibility;
a resolver that re-authorizes subject visibility for the current tenant and principal.

Providers expose only documentation-safe metadata. Secrets, credentials, sensitive field values, raw policy payloads, and feature-internal persistence objects must not cross the boundary.

Acceptance criteria

Core defines and validates the typed subject descriptor/provider/resolver contract.
Subject identity is deterministic within a tenant and remains stable across display-label changes.
Nested subjects are supported without path parsing in Docs.
The owning module can resolve a reference as available, changed, superseded, missing, or temporarily unavailable.
Resolution is tenant-aware and principal-aware; callers cannot infer inaccessible subjects.
Revision/fingerprint behavior and rename/removal semantics are documented.
The contract is additive to DocumentationTopic and documentation_providers; static user/admin baselines remain mandatory.
Registry/capability lookup lets optional modules participate without direct imports.
Contract tests cover validation, duplicates, tenant separation, authorization, revision changes, missing modules, and unsafe metadata rejection.
Core and integration documentation describes the extension point and its security obligations.
Focused Core and workspace manifest-shape checks pass.

Non-goals

Storing or publishing authored semantic content in Core.
Defining feature-specific subject models.
Replacing module-owned product documentation or configured-state providers.

Parent epic: GovOPlaN/govoplan#49 ## Problem Docs can render module-owned topics and configured-state provider output, but tenant-authored semantics need a stable, authorized reference to the configured artifact they describe. Docs must not learn feature-internal models or persist copies of executable configuration. ## Proposed contract Add a typed cross-module subject descriptor and provider/resolver boundary for artifacts that may receive semantic documentation. The exact names are implementation details, but the contract must cover: - module and subject kind; - a tenant-scoped, deterministic stable identifier and optional nested anchor such as a field or step; - localized display label, safe description, hierarchy/breadcrumbs, contextual route/anchor, and owning-module provenance; - a revision or semantic fingerprint that lets Docs detect when authored content needs review; - availability state and safe rename/deletion/supersession handling; - audience/classification metadata that may narrow visibility; - a resolver that re-authorizes subject visibility for the current tenant and principal. Providers expose only documentation-safe metadata. Secrets, credentials, sensitive field values, raw policy payloads, and feature-internal persistence objects must not cross the boundary. ## Acceptance criteria - [x] Core defines and validates the typed subject descriptor/provider/resolver contract. - [x] Subject identity is deterministic within a tenant and remains stable across display-label changes. - [x] Nested subjects are supported without path parsing in Docs. - [x] The owning module can resolve a reference as available, changed, superseded, missing, or temporarily unavailable. - [x] Resolution is tenant-aware and principal-aware; callers cannot infer inaccessible subjects. - [x] Revision/fingerprint behavior and rename/removal semantics are documented. - [x] The contract is additive to `DocumentationTopic` and `documentation_providers`; static user/admin baselines remain mandatory. - [x] Registry/capability lookup lets optional modules participate without direct imports. - [x] Contract tests cover validation, duplicates, tenant separation, authorization, revision changes, missing modules, and unsafe metadata rejection. - [x] Core and integration documentation describes the extension point and its security obligations. - [x] Focused Core and workspace manifest-shape checks pass. ## Non-goals - Storing or publishing authored semantic content in Core. - Defining feature-specific subject models. - Replacing module-owned product documentation or configured-state providers.

zemion added the module/docs

type

task

area/governance codex/ready

area/api module/core labels 2026-08-21 00:07:02 +02:00

zemion referenced this issue from GovOPlaN/govoplan-docs

2026-08-21 00:07:21 +02:00

[User Story] Author, review, and publish tenant semantic documentation #21

zemion referenced this issue from GovOPlaN/govoplan-forms

2026-08-21 00:07:35 +02:00

[User Story] Document the local meaning of configured forms and fields #5

zemion referenced this issue from GovOPlaN/govoplan-workflow

2026-08-21 00:07:48 +02:00

[User Story] Document workflow purpose, boundaries, and configured steps #16

zemion referenced this issue from GovOPlaN/govoplan

2026-08-21 00:08:04 +02:00

[Epic] Author configured-system semantics in Docs #49

zemion commented

2026-08-21 14:57:41 +02:00

Implemented and pushed in Core commit 925dc33 (feat(docs): define semantic subject contract).

Evidence:

typed tenant-scoped references, nested anchors, localized safe descriptors, provider discovery, and resolver states (available, changed, superseded, missing, temporarily_unavailable);
strict validation prevents foreign tenants/modules, duplicate identities, remote routes, unknown reference fields, and unsafe fingerprint inputs;
manifest validation requires the exact module capability, contract version 1, capability documentation, and retained static user/admin baselines;
integration/security/lifecycle documentation added in SEMANTIC_DOCUMENTATION_SUBJECTS.md and linked from the architecture and documentation map;
focused Core: 145 tests + 255 subtests passed; Ruff and git diff --check passed;
workspace: 68/68 manifests, DSAR coverage gate, dependency/layout/primitive contracts, composed backend/migrations, 59 WebUI permutations, full-product bundle, 7 Playwright conformance journeys, and downstream UI checks passed.

Remote main was verified at 925dc33696.

Implemented and pushed in Core commit 925dc33 (`feat(docs): define semantic subject contract`). Evidence: - typed tenant-scoped references, nested anchors, localized safe descriptors, provider discovery, and resolver states (`available`, `changed`, `superseded`, `missing`, `temporarily_unavailable`); - strict validation prevents foreign tenants/modules, duplicate identities, remote routes, unknown reference fields, and unsafe fingerprint inputs; - manifest validation requires the exact module capability, contract version 1, capability documentation, and retained static user/admin baselines; - integration/security/lifecycle documentation added in `SEMANTIC_DOCUMENTATION_SUBJECTS.md` and linked from the architecture and documentation map; - focused Core: 145 tests + 255 subtests passed; Ruff and `git diff --check` passed; - workspace: 68/68 manifests, DSAR coverage gate, dependency/layout/primitive contracts, composed backend/migrations, 59 WebUI permutations, full-product bundle, 7 Playwright conformance journeys, and downstream UI checks passed. Remote `main` was verified at 925dc3369651378428d37b4995c30d059d785fa1.

zemion closed this issue

2026-08-21 14:57:41 +02:00

zemion referenced this issue from GovOPlaN/govoplan

2026-08-21 14:58:32 +02:00

[Epic] Author configured-system semantics in Docs #49

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-core#292