Development documentation¶
This section contains maintainer-facing documentation for TopMark's architecture, filesystem-identity evaluation model, configuration-resolution model, compatibility contracts, release process, generated documentation pipeline, and post-1.0 governance model.
Use these pages when changing internals, reviewing compatibility boundaries, preparing releases, or understanding how the stable 1.x runtime model is organized.
The 1.x runtime model distinguishes several independent identity domains and discovery concepts:
- workspace-root and configuration-discovery anchoring;
- filesystem identity (normalization, processing-path selection, and eligibility checks);
- configuration-source identity;
- file type identity;
- processor identity; and
- machine-readable serialization identity.
Understanding these distinctions is important when reviewing compatibility boundaries, runtime behavior, configuration discovery, and symlink-related path handling.
Architecture and runtime model¶
The pages in this section define TopMark's canonical runtime behavior, including filesystem-identity evaluation, path resolution, configuration layering, file-type resolution, runtime pipelines, and plugin integration.
- Terminology and canonical vocabulary
- Architecture
- Registry model - file-type, processor, and registry identity
- Resolution - workspace-root discovery, filesystem-identity evaluation, processing paths, hard-link policy, and configuration-source identity
- Configuration discovery and layering - discovery anchors, project-chain discovery, layered precedence, and configuration-source identity
- Plugins and extensibility
- Configuration schema
- Pipelines
- Pipelines reference hub
- Performance baselines - memory and allocation measurement methodology
Compatibility and output contracts¶
These documents define the stable 1.x compatibility boundaries for APIs, machine-readable output, filesystem path serialization, file-type identity, and configuration provenance.