scalio-catalog

Shared code for the Scalio Blueprint governance catalog: one desired state per tenant, used by Foundry (roll out), Citadel (keep, drift) and Rosetta (document). Concept and decisions BP1-BP12: https://claude.ai/artifact/8PYfvHPm17KsooerLU95Ar (scalio-docs concepts/governance-catalog.md, ADR 0027). Format contract: scalio-docs interfaces/catalog-format.md.

Nothing in this package is secret. The catalog content lives in the private repo scalio_blueprint; the signing seed stays in 1Password.

Documents

References: id (highest), id@1.2.3 (exact), id@^1.2 (same major, at least 1.2). Assignments name an exact version.

Use in an app

from scalio_catalog import Catalog, compare, effective, plan, plan_upgrade, summary, verify

catalog = verify(package_bytes, TRUSTED_CATALOG_KEYS)        # signed pack from Compass or the image
eff = effective(catalog, assignment)                         # baseline + customer layer, master untouched
results = compare(eff, {c.id: read_resource(c) for c in eff.controls})   # app reads the tenant
print(summary(results))                                      # {"counts": ..., "score": 92}
plan = plan_upgrade(catalog, assignment, "scalio.kmu-standard@1.5.0")    # three-way, conflicts listed

rollout = plan(catalog, "scalio.project-workspace@1.0.0", {"project": "Apollo"}, tenant="contoso.ch")
for node in rollout.nodes:                                   # build order; ${node} refs via resolve_refs()
    ...
assignment = rollout.assignment                              # baseline of the blueprint, for Citadel/Rosetta

Control objectives: evaluate_objectives(catalog, results) gives per objective met, partly, not_met or not_checked from the control results (compare output or a mapping control id -> status). ok and excepted pass, drift and missing fail, everything else is not checked.

compare statuses: ok, drift, missing, excepted (all deviations covered by an active exception), not_read, removed (customer removed it), incomplete (a value is missing).

Values (later wins): control default, baseline parameters, value on the baseline entry, assignment values, assignment controlValues.<control>. Exceptions need a reason, end date and approver; expired ones count as deviations again and are listed in problems; at most 366 days when approvedAt is given.

Command line

scalio-catalog validate <folders...>          check structure, references, texts
scalio-catalog effective <assignment> <folders...> [--today 2026-11-01]
scalio-catalog plan <blueprint> <folders...> --set project=Apollo --tenant contoso.ch
scalio-catalog pack <folder> -o dist          sign (CATALOG_SIGNING_KEY or --key-file), --base for other packs
scalio-catalog verify <file> --key <public>   check a package
scalio-catalog keygen                         new key: seed to 1Password, public key into the apps
scalio-catalog schema > catalog-v2.schema.json

Editing in VS Code

Install the YAML extension (Red Hat) and add to the workspace settings of scalio_blueprint:

{ "yaml.schemas": { "./schema/catalog-v2.schema.json": ["controls/**/*.yaml", "baselines/**/*.yaml",
  "resource-types/**/*.yaml", "blueprints/**/*.yaml", "objectives/**/*.yaml", "pack.yaml"] } }

(scalio-catalog schema > schema/catalog-v2.schema.json writes the file.)

Release

Bump pyproject.toml and __version__, CHANGELOG line, merge, then "Freigeben" in the Scalio Dev cockpit (or Actions -> Publish with the version). Publishes to PyPI via trusted publishing (no token).