Skip to content

Contracts

A contract is the shape of a payload together with the rules that come with its name: which stream a record lands in, which way it flows through the tree, and whether it has a current value. The shapes live in one place, the colca-data-contracts package in contracts/. Nodes do not contain them; they enforce a schema bundle generated from them.

The schema bundle

make bundle        # writes build/bundle/contracts-bundle.json and prints its sha256

The bundle is canonical JSON: a manifest and a restricted JSON Schema for every contract. Generating it again from the same source gives the same bytes, so its digest identifies it.

A node loads the bundle when it starts, from contracts.bundle (/etc/colca/contracts-bundle.json by default; the image contains the bundle of its own commit). contracts.sha256 pins the expected digest, and a node with a different bundle does not start.

  • A bundle replaces the built-in checks. It never merges with them. A contract that is not in the bundle is refused. A node without a bundle applies small built-in checks for its core contracts only.
  • Nesting is limited. With or without a bundle, a payload that nests objects and arrays more than 32 levels deep is refused with 400; a command gets a 400 ack. The contracts need a few levels; readers of the stored records stop at 64 levels including their own envelope.
  • The bundle carries the routing class of each contract, so a new contract can be introduced by shipping a bundle, without a new broker. A new command contract counts as an admin command until the domain package names its class.
  • Some contracts belong to the node. _StreamGap and _EnrolledIdentity are produced and checked by the node itself; a bundle that declares one does not load.
  • Field limits are part of the contract. A payload field declares its limit in payload.py with MaxLength, Bounds or Pattern, and the bundle carries it as maxLength, minimum/maximum or pattern. The declaration is the one definition of the limit: a consumer that validates early reads it with field_limits(cls), and a read model that stores the field sizes its column to it. A record a command executor composes is validated like any other, so a _CmdEdit or _CmdConfigure whose result breaks a limit is refused with 422 invalid_field: <field>: <keyword> <limit> (invalid_field: unit: maxLength 50) and nothing is written.
  • An audit record's text is bounded too. Every text field of _AuditEvent declares a limit (512 characters for operation, 255 for the ids, names and codes), so a producer's overlong record is refused where it is published. The node's own audit writer passes no door; it cuts what a refused caller sent (a contract, a topic path) to the same limits, and a test compares its table with the bundle.
  • Local services write their own audit records. source names the writer (projector, node_manager, orchestrator); an edge orchestrator records a rollout, a stop or a rollback as action execute, with the service it changed in entity_id.
  • Validation happens once, at the door where a record enters. Replication does not validate again, so nodes on different bundle versions keep replicating while a rollout moves through the tree.

colca_contracts_bundle_info{version,digest,source} shows which rules a node enforces.

Changing a contract

  1. Change the payload class in contracts/src/colca_data_contracts/payload.py. A new contract also needs its class in routing.py.
  2. make contracts-test, then make bundle.
  3. make test. The Go tests that judge the doors read the generated bundle.

Catalog records

A catalog is master data kept in _Constant records of data type json: one product per catalog/products/{sku}, one recipe per catalog/recipes/{id}. The node checks only that such a value is JSON, and no bundle applies to it; the record's shape is its own contract, colca_data_contracts.catalog (dataclasses plus PRODUCT_SCHEMA and RECIPE_SCHEMA), and CatalogProduct and CatalogRecipe in the TypeScript client.

{
  "sku": "AMALQ301H6", "name": "MDF 18 mm", "substrate": "MDF",
  "thickness_mm": 18.7, "length_mm": 4100, "width_mm": 2070, "sandoff_mm": 0.7,
  "density_kg_m3": 745, "final_grit": 150, "recipe_id": "recipe-60-80-100-120-150",
  "is_default": true,
  "attributes": {"sap_plant": "BSK1"},
  "provenance": {"source": "erp", "set_by": "sap-bridge", "set_at": "2026-09-25T08:00:00Z"},
  "field_provenance": {"density_kg_m3": {"source": "manual", "set_by": "Admin A", "set_at": "2026-09-25T09:12:00Z"}}
}
  • A product names its recipe by recipe_id: recipes are shared, and one edit changes one record.
  • Anything beyond the standard fields goes in attributes; an unknown top-level field is refused.
  • provenance is the record's writer. field_provenance names the fields that are not simply its: a placeholder marked default, and a value someone else set, such as a density entered by hand (manual).
  • What the writer supplies wins. A hand entry fills only a field the writer leaves empty or gives a default for; a re-sync restores a supplied value and keeps a hand entry over a default.

Golden vectors

Where Go and Python both need a rule natively, a vector file in contracts/src/colca_data_contracts/vectors/ holds the cases and the expected answers, and the tests on both sides read the same file:

File Pins
topic_transformations.json the topic grammar and mount rewriting
grant_evaluation.json how a person's grants are evaluated
authz_objects.json the Keycloak objects a grant is made of
annotation_id.json how an annotation's id is derived
data_model_vocabulary.json, signal_data_types.json the data type vocabularies
metric_rows.json which historian column a metric value lands in
sanitize.json how names become path segments
field_refusal.json the refusal a node answers for a field outside its limit
service_context.json, log_payload.json, manifest_streams.json service identity, log records, stream manifest
catalog_records.json product and recipe records, Python and TypeScript

Change a rule by changing its vector first, then make both sides pass.