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¶
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 a400ack. 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
admincommand until the domain package names its class. - Some contracts belong to the node.
_StreamGapand_EnrolledIdentityare 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.pywithMaxLength,BoundsorPattern, and the bundle carries it asmaxLength,minimum/maximumorpattern. The declaration is the one definition of the limit: a consumer that validates early reads it withfield_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_CmdEditor_CmdConfigurewhose result breaks a limit is refused with422 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
_AuditEventdeclares a limit (512 characters foroperation, 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.
sourcenames the writer (projector,node_manager,orchestrator); an edge orchestrator records a rollout, a stop or a rollback as actionexecute, with the service it changed inentity_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¶
- Change the payload class in
contracts/src/colca_data_contracts/payload.py. A new contract also needs its class inrouting.py. make contracts-test, thenmake bundle.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. provenanceis the record's writer.field_provenancenames the fields that are not simply its: a placeholder markeddefault, 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.