27 lines
1.5 KiB
Markdown
27 lines
1.5 KiB
Markdown
# Declarative catalog
|
|
|
|
This directory is the desired-state source for ITWorx MCP Hub. Catalog documents use **JSON-compatible YAML**: every `.yaml` file is valid YAML 1.2 and also valid JSON. This deliberate restriction lets the design pack validate the catalog using only Python's standard library before `uv`, PyYAML, or application dependencies exist.
|
|
|
|
## Reconciliation rules
|
|
|
|
1. Parse and validate every document against `contracts/schemas/`.
|
|
2. Normalize slugs and endpoint aliases.
|
|
3. Resolve template references without reading secrets.
|
|
4. Calculate a deterministic desired-state hash.
|
|
5. Produce a preview with create/update/disable/no-op actions.
|
|
6. Reject destructive or privilege-expanding drift unless the active policy permits it.
|
|
7. Apply through the ContextForge adapter and Hub repositories.
|
|
8. Read back actual state and compare it with desired state.
|
|
9. Record an append-only audit event and reconciliation evidence.
|
|
|
|
Catalog files never contain credentials. They contain references such as `docker-secret://gitea_mcp_token` or `authentik-client://itworx-mcp-hub`.
|
|
|
|
## Verification states
|
|
|
|
- `verified`: discovered and tested against the real target;
|
|
- `unverified`: plausible desired state that must not be reported as live;
|
|
- `external-input-required`: implementation is complete but a credential, URL, or target mapping is unavailable;
|
|
- `fake-only`: deterministic fake is the current test binding.
|
|
|
|
The initial project files intentionally use discovery placeholders. `WP-145` replaces only facts it can prove and retains explicit placeholders for everything else.
|