Communication¶
A pipeline spans several projects, and each project's agent sees only its own. The declarations tell one reader what the data means; communication tells the other projects what happened to it. Five messages travel between projects:
| Message | Sent by | Tells | So that |
|---|---|---|---|
| Import | consumer | which dataset a project reads, at which build | the producer knows who to tell |
| Change notice | producer's tool, on each published build | what changed since the previous build | every reader hears before it quotes a moved number |
| Ack | consumer | that someone checked a notice, and what they checked | a notice stays open until a reader has looked |
| Request | anyone | a question or a needed change on a dataset or column, and later its answer | the fix lands at the source, once |
| Decision | any agent proposes; a person settles | a house rule (a definition, a basis, a join) | a choice is made once and reused |
A sixth, Cited file, lets a change notice name the memos that quote a changed cell.
Messages are not keys in oryxkb/project.yaml. Tools exchange them through a shared service (a hub); this page fixes
their fields so different tools can exchange them. The declarations are what they point at: renames and removals
(Schema changes), column types, facts and ids.
Rules¶
- Local work never depends on it. Declarations, checks, cards and citations work with no shared service. A tool that cannot reach one says so in one line and carries on.
- Metadata, not values. A message carries names, ids, descriptions, units, build ids, counts and the text people write. It never carries table contents, cell values, quoted figures or row keys. A consumer's tool reads old and new values from the builds it can already read.
- Warn, never block. An open notice or an unsettled decision is shown, never enforced.
- A person settles. Agents may propose, discuss, vote and summarize. Only a person's review makes a decision
settled.
Ids¶
Every message names things by the ids used across the spec:
| Thing | Id | Example |
|---|---|---|
| Project | <project> |
marketdata-example |
| Dataset | <project>/<Dataset> |
marketdata-example/Rents |
| Column | <project>/<Dataset>#<column> |
marketdata-example/Rents#rent |
| Cell | a column id plus ?<key>=<value> for every grain column |
marketdata-example/Rents#rent?market_id=29484§or=office&period_yq=2026Q3 |
| Fact | <project>/<Dataset>/fact:<id> |
marketdata-example/Rents/fact:office-incl-flex |
| Build | the build's timestamp, ISO 8601 in UTC | 2026-11-02T23:48:40Z |
| Sender | <project>, or <project>/<agent> for one agent of a project |
research/analyst |
A cell id appears only in a Cited file, which stays with the consumer; see the rules above.
Example¶
A rebuild of Rents renames a column. The producer's tool sends a notice to the projects that import it; one of them
checks its memo and acks.
{"type": "notice", "id": "n-4868d0", "dataset": "marketdata-example/Rents",
"build": "2026-11-15T10:02:11Z", "previous_build": "2026-11-02T23:48:40Z",
"rows_changed": 12,
"changes": [{"kind": "renamed", "column": "rent_growth_pct", "to": "rent_growth"},
{"kind": "values", "column": "rent", "rows": 12}],
"summary": "12 rows changed in [rent]; rent_growth_pct renamed to rent_growth",
"from": "marketdata-example", "at": "2026-11-15T10:02:15Z"}
{"type": "ack", "notice": "n-4868d0", "consumer": "research",
"note": "memo q3.md re-checked: 2 figures updated", "from": "research/analyst", "at": "2026-11-15T11:20:00Z"}
Common fields¶
Every message has these:
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
type |
import, notice, ack, request, cited_file |
yes | Critical | error on any other value | The kind of message. A decision is a request with kind: decision. |
id |
string | yes, except import and ack |
Important | error if two messages share it | Stable id people cite, such as n-4868d0 for a notice or h-d930e2 for a request. |
from |
sender id | yes | Important | error unless <project> or <project>/<agent> |
Who sent it. |
at |
timestamp, ISO 8601 | yes | Useful | error if not a timestamp | When it was sent. |
Import¶
A consumer project tells the shared service that one of its datasets reads another project's dataset. A tool sends it when the consumer runs with the import, not when it is declared.
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
consumer |
project id | yes | Critical | - | The project that reads. |
consumer_dataset |
dataset name | no | Useful | - | The consumer's dataset that reads it, when known. |
dataset |
dataset id | yes | Critical | error if not <project>/<Dataset> |
The dataset read. |
build |
build id | yes | Important | - | The build read. |
Change notice¶
The producer's tool sends a notice when a published build differs from the previous published build of the same dataset. The audience is every project that imports the dataset, watches it, or has a Cited file that cites it.
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
dataset |
dataset id | yes | Critical | - | The dataset rebuilt. |
build |
build id | yes | Critical | - | The new build. |
previous_build |
build id | yes | Critical | - | The build it is compared with. |
rows_changed |
integer | no | Important | error if negative | Rows whose values changed. |
changes |
list of Change | no | Critical | - | What changed, one entry per column and kind. |
changes[].kind |
values, added, renamed, removed, type, scale, blanks |
yes | Critical | error on any other value | values: values changed; added, renamed, removed: the column itself (Schema changes); type: its type changed; scale: its range jumped by about x100 or x1000; blanks: blanks appeared. |
changes[].column |
column name | yes | Critical | - | The column, by its name in the previous build. |
changes[].to |
string | no | Critical | required for renamed and type |
The new name, or the new type. |
changes[].rows |
integer | no | Useful | - | Rows affected, for values and blanks. |
summary |
string | yes | Important | - | One line for people, such as the line a rebuild prints. |
A notice stays open for a consumer until that consumer sends an Ack.
Ack¶
A consumer confirms it checked a notice.
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
notice |
notice id | yes | Critical | error if no such notice | The notice checked. |
consumer |
project id | yes | Critical | - | The project that checked. One ack per notice and consumer; a later one replaces it. |
note |
string | yes | Important | warning if empty | What was checked, such as "memo q3.md re-checked, 2 figures updated". |
Request¶
A question or a needed change, on a dataset or a column, to the project that publishes it.
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
target |
dataset id or column id | yes | Critical | error if neither | What it is about. |
kind |
schema, definition, pipeline, data, question, decision, contradiction |
yes | Important | error on any other value | data: a value looks wrong; definition: a meaning is unclear; schema: a column is missing or should change; pipeline: how it is built; contradiction: two statements disagree; decision: see Decision. |
text |
string | yes | Critical | - | The request, in plain words. |
status |
open, accepted, declined, done, closed |
yes | Important | error on any other value | Set by the producer, except closed, which the author may set. |
done_build |
build id | no | Important | required when status is done |
The build that resolved it. |
replies |
list of {from, at, text} |
no | Useful | - | The discussion. |
Before sending a request, a tool searches open requests on the same target; filing the same target and kind while one is open joins it.
Decision¶
A decision is a request with kind: decision. It adds a proposal, a review state and votes.
proposed --discuss--> ai_discussion --summarize--> awaiting_human --accept--> settled
--reject--> rejected
settled --(net revisit votes, or new evidence)--> revisit_requested --review--> settled / rejected
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
proposal |
string | yes | Critical | - | The rule as it would be recorded. |
review |
proposed, ai_discussion, awaiting_human, settled, revisit_requested, rejected |
yes | Critical | error on any other value; only a person moves it to settled or rejected |
Where it is in the lifecycle. Every state except rejected is in use; a reader says "not yet signed off" until settled. |
votes |
list of {voter, value, reason} |
no | Useful | value is keep or revisit; one per voter |
Agents' and people's votes; a later vote by the same voter replaces it. |
summary |
string | no | Useful | - | An agent's summary that puts it in a person's queue. |
settled_by |
string | no | Important | required when review is settled or rejected |
The person who decided. |
settled_at |
timestamp | no | Important | as above | When. |
A settled decision that applies to a dataset becomes a fact in the producer's declarations, with
status: reviewed and source set to the decision's id. While no rule exists, the fact is status: decision-open
with its options.
Cited file¶
A consumer tells the shared service which cells a file of its own (a memo, a report) cites, so a change notice can name the file. The file and its figures stay with the consumer.
| Key | Type | Required | Priority | Check | Description |
|---|---|---|---|---|---|
consumer |
project id | yes | Critical | - | The project the file belongs to. |
file |
string | yes | Important | - | The file's path inside the consumer's repository, never a path on a machine. |
cites |
list of column or fact ids | yes | Critical | - | What it cites, at column level; the cell ids stay in the consumer's citation record. |
Not in the spec yet¶
- Consent rules for showing a producer which projects import its data, beyond a team or an organisation.
- Notices from a data vendor to its clients' agents across organisations. The reverse direction is a principle on the full picture.
- A JSON Schema for these messages, like the one for the declarations.