Internal API reference (advanced) (1.0.1)

Warning

The modules listed under Internals are intended for contributors and advanced integrations. They are not covered by the stable public API compatibility contract and may evolve between minor releases.

Prefer the stable public API whenever possible.

Internals complement the stable public API.

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

Whenever possible, prefer using:

• topmark.api
• documented machine-readable JSON and NDJSON contracts
• the stable Registry facade APIs

Internal modules should generally be used only for advanced integrations, debugging, testing, or TopMark development.

For details on how these pages are generated and validated, see Development → Documentation pipeline and reference hygiene.

See also:

• Architecture
• Registry model
• Resolution
• Plugins and extensibility
• API stability and snapshot policy
• Machine-readable output
• Terminology and Canonical Vocabulary

This section provides generated per-module reference pages (see tools/docs/gen_api_pages.py). They are not added individually to the navigation in order to keep the sidebar compact. Use the search box to find symbols, or browse the generated paths under /api/internals/topmark/....

The generated internals span multiple architectural layers:

• TOML layer (topmark.toml)
• Configuration layer (topmark.config)
• Runtime layer (topmark.runtime)
• Pipeline subsystem (topmark.pipeline)
• Registry and overlay subsystems (topmark.registry)

See Architecture for the conceptual overview.

Canonical file type identity semantics are documented in Registry model and Terminology and Canonical Vocabulary.

These pages are generated automatically during the MkDocs build and should not be edited manually.

The generated reference pages reflect internal implementation structure and may evolve more frequently than the stable public API surface or documented machine-readable contracts.

Any changes should be made in the corresponding Python source files under src/.

Browse the generated internals index: topmark internals

Internal modules are documented for maintainers and advanced integrations, but they intentionally evolve more flexibly than:

• topmark.api
• CLI contracts
• machine-readable JSON and NDJSON contracts
• canonical file type identity semantics

You can also browse the full generated tree from the sidebar under API → Internals → Reference (generated).