Skip to content

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&sector=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.