Truth and ownership

What this part does

This part answers one question for every value a client sees: why is it this value, and not another one? One match can have a scorer, two providers, Scout and an operator all sending the same score. Something has to decide which one is published, keep the rest, and let a person step in.

Section 2 of the design set out six questions. Every later part (the engine, imports, feeds) builds on the answers.

Five words are used on this page.

How it works

Today: a person pins, an import skips the pin Built today

Every write in omnium is a workflow command (see Commands and the workflow engine). A command is sent either by a person (from the console, through the bridge) or by an integration (a Scout import). The engine refuses any mix: a person may never send an import, and an integration may send nothing else. The record writers then apply one rule, written at the top of records.py:

1. An operator changes a field in the console, for example a start time. The console sends a command such as results.set_start.
2. The engine checks the sender is a person, takes a lock, runs the rules, and calls the record writer fixture.set.
3. The writer saves the new value and adds "start" to fixture.pinned.
4. Later a Scout run sends the same fixture with the old time, through the import command games.import_units.
5. The import writer compares field by field. For start it finds the name in pinned, so it keeps the operator's value and counts one "kept by hand".
6. Other fields on the same row (status, venue, sides) are still written from the import, unless they are pinned too.
7. If the operator clicks Let the feed decide, results.hand_back removes "start" from the list. The next import that sends this row may change it again.

Agreed: every source sends claims, a list per group picks the winner Agreed, to build

The agreed design keeps the same road in, but stops throwing values away and replaces "person beats integration" with a written priority list.

1. One road in. Every source sends claims through the same workflow commands (decision D5 from Section 1). A claim records the source, the value, when we got it, the source's own time and number when it has them, and the person, if there is one.
2. Nothing is thrown away. Every claim is saved, the winners and the losers (T1).
3. A priority list per field group. A sport has a default list. An operator can change it for a competition or a single match, and the change is recorded (T3).
4. The winner is the highest source that is active. "Active" means not quiet: screens send a heartbeat, and for a provider a failed pull or a long silence counts as quiet. Each source has its own quiet limit.
5. Take-over is by hand first. When the winner goes quiet in a live match, an alert fires and an operator switches to the next source with one click. Automatic switching is a setting, off at first. Switching back is always by hand (T5).
6. A hand edit is an override. It is a source with its own place on each list, at the top by default. It shows on one "open overrides" screen until someone releases it (T4). This is today's pin, made visible.
7. Losers are compared with the winner. If a lower source disagrees for longer than a set time, an alert fires: "Provider A says 2–1, we publish 1–1" (T6).
8. Order per source. An older claim from a source never replaces a newer one from the same source (T7).
9. A result has a status and a version. Live, unofficial, official, plus protested. The version goes up with every change (T8).
10. Official is locked. No source changes an official result by itself, unless the competition allows a trusted source to. A person with the right role can still edit it; clients get a new version marked as a correction (T9, T10).
11. Every value can say why (T11).

Who wins when two sources disagree

A worked example

Low-level design

The pinned columns Built today

Four tables carry a pinned list. It is a JSONB array of field names, never null, empty by default. Migration 046 added it to the two fixture tables; 045 added it to competition_entry; medal_standing had it first.

packages/core/alembic/versions/20260914_046_fixture_pins.py:32-40

def upgrade() -> None:
    op.add_column(
        "fixture",
        sa.Column("pinned", JSONB(), server_default=sa.text("'[]'::jsonb"), nullable=False),
    )
    op.add_column(
        "fixture_competitor",
        sa.Column("pinned", JSONB(), server_default=sa.text("'[]'::jsonb"), nullable=False),
    )

The two fixture tables are separate on purpose: a fixture's time and status belong to the fixture, and a side's score or rank belongs to that side.

Three pin names cover more than one column. They are easy to miss:

• status on a fixture covers both status and results_official. Marking a result official pins status.
• result on a side covers the score, the medal, the two record flags and qualified. They all live in the side's result JSON.
• competitors on a fixture means "the sides are the person's". The import then does not touch any side of that fixture.

medal_standing and competition_entry also have source_code (which feed last wrote the unpinned fields) and fed_at (when). The fixture tables do not; the feed's code is kept in fixture.meta.source instead.

The person side: a writer pins what it touches Built today

The rule's helpers live in records.py.

packages/core/src/omnium_core/workflows/records.py:164-181

def pin(row: Any, *fields: str) -> None:
    """Mark fields set by hand. A new list, so the session sees the JSONB change."""
    row.pinned = sorted({*(row.pinned or []), *fields})


def held(row: Any, name: str) -> bool:
    return name in (row.pinned or [])


def may_write(ctx: WriteContext, row: Any, name: str) -> bool:
    """The hand-edit rule for one field. A person always may, and pins it."""
    if ctx.actor.by_person:
        pin(row, name)
        return True
    if held(row, name):
        ctx.report.counts["kept_by_hand"] += 1
        return False
    return True

• pin builds a new sorted list. Changing the old list in place would not be seen by SQLAlchemy as a change to the JSONB column, so the pin would not be saved.
• may_write is the whole rule in one function. No writer calls it today (checked with grep, 7 Oct). The person writers call pin directly, and the import code has its own copy of the check (next section). The behaviour is the same, but the rule lives in three places.

A person writer, trimmed to the fields that pin:

packages/core/src/omnium_core/workflows/writers/fixtures.py:107-141

@writer("fixture.set")
async def set_fixture(ctx: WriteContext, data: dict[str, Any]) -> None:
    """Correct a fixture. Every field sent is pinned, so the feed keeps the correction."""
    fixture = _fixture(ctx)
    if "name" in data:
        ...
        fixture.name = name
        pin(fixture, "name")
    if "start" in data:
        fixture.scheduled_start = _start(data["start"])
        pin(fixture, "start")
    ...
    if data.get("official") is not None:
        fixture.results_official = bool(data["official"])
        pin(fixture, "status")
    ...
    if "scoreline" in data:
        _set_scoreline(fixture, data["scoreline"])
        pin(fixture, "result")
    _touched(ctx)

Every field the person sends is written and pinned. The writer does not check who sent it: the engine has already made sure only a person can reach this writer. How a command, its validations and its action are written in the flows plugin is on Writing a workflow in code.

Only an integration sends an import Built today

The split between the two kinds of writer is enforced once, in the engine, before anything runs.

packages/core/src/omnium_core/workflows/engine.py:259-264

    spec = flows_host.spec_for(node.impl)
    if spec.imports and actor.by_person:
        raise Refused("not_allowed", "only an integration may send an import")
    if not spec.imports and not actor.by_person:
        raise Refused("not_allowed", "an integration may only send import commands")
    return pinned.program, node

A command is an import when its @command says imports=True (for example import_units in omnium_flows/games/commands.py:430-437). So "a feed never renames a fixture" is not a promise each writer keeps; it is impossible to send. An integration's actor is Actor(kind="integration", name="integration:<code>", source_code=<code>) (integrations/service.py:424-426).

The import side: the pin check, field by field Built today

The import writer units.import plans the rows, then calls apply_fixtures. For a fixture that already exists, _update_fixture brings it in line with the feed one field at a time.

packages/core/src/omnium_core/ingest/fixtures.py:1131-1180 (trimmed)

def _update_fixture(row, unit, stage_id, venue_id, source_code, report, round_name=None) -> bool:
    """Bring one known fixture in line with the feed, field by field. True if it changed."""
    pinned = set(row.pinned or [])
    changed = False

    def allowed(name: str, same: bool) -> bool:
        if same:
            return False
        if name in pinned:
            report.kept_by_hand += 1
            return False
        return True

    name = _fixture_name(unit) or _mend_name(row, unit, round_name)
    if name and allowed("name", row.name == name):
        row.name, changed = name, True
    if unit.start is not None and allowed("start", row.scheduled_start == unit.start):
        row.scheduled_start, changed = unit.start, True
    if unit.venue and allowed("venue", row.venue_id == venue_id):
        row.venue_id, changed = venue_id, True
    if str(unit.source_status or "").strip():
        status, official = map_status(unit.source_status)
        if allowed("status", (row.status, row.results_official) == (status, official)):
            row.status, row.results_official, changed = status, official, True
    result = _result_of(unit)
    if _says_how_it_went(unit) and allowed("result", row.result == result):
        row.result, changed = result, True
    ...

Read each line as three checks, in order:

1. Did the feed say anything? unit.start is not None, unit.venue, a non-empty status, _says_how_it_went. A feed that leaves a field out is not saying it is empty. This rule came from real damage: a draws feed with no venue wiped the hall off 180 events on 20 Sep (code comment, ingest/fixtures.py:1164-1171).
2. Is it different? same is true when the values already match. Then nothing happens and nothing is counted.
3. Is it pinned? Only now. A pinned field that differs is left alone and counted in kept_by_hand.

So kept_by_hand counts real disagreements with a person, not every pinned field the import passed. The same pattern, with its own allowed, is in _update_side (ingest/fixtures.py:1490-1538) for participant, result, rank and status. The entry import (ingest/entries.py:1026-1035) and the medal import (ingest/medals.py:265-272, 378) do the same against their own lists.

meta is outside the rule. The feed rewrites fixture.meta.source on every pull. That is why a person's medal-event answer is stored in a separate key, meta.medalEvent, which the feeds read first (writers/fixtures.py:173-185).

Where else a pin is read Built today

Only changed rows are sent: why hand back can wait Built today

A schedule's rows stand alone, so the integration sends only the rows that changed since omnium last held them.

packages/core/src/omnium_core/integrations/service.py:108 and 835-851 (trimmed)

_HELD_VALUE = ("accepted", "unchanged", "kept_by_hand")

async def _changed(session, integration, target, ready, replay_of=None) -> list[Row]:
    """Where rows stand alone, only the rows whose value changed since omnium last held it."""
    if not target.max_rows or replay_of is not None:
        return ready
    last = await _last_hashes(session, integration)
    return [row for row in ready if not (row.key and last.get(row.key) == row.row_hash)]

• row_hash is a sha256 of the mapped row. _last_hashes reads the newest held row per subject from integration_row.
• A row whose outcome was kept_by_hand still counts as "held". So once a run has met a pin, the same unchanged row is not sent again.
• After hand_back, the feed's value comes back only when the site changes that row, or when someone runs a replay (a replay sends every row).
• This applies to imports with a row limit: games.import_units (1,000 rows per command, games/commands.py:52). The medal table and entry list are sent whole every run, so a hand back there takes effect on the next run.

The as-built review of 29 Sep listed this as its top finding: an import compares with its own last read, not with the database.

Hand back Built today

packages/core/src/omnium_core/workflows/writers/fixtures.py:356-375

@writer("fixture.hand_back")
async def hand_back(ctx: WriteContext, data: dict[str, Any]) -> None:
    """Hand fields back to the feed. The next run may change them again."""
    fixture = _fixture(ctx)
    side_id = data.get("side")
    allowed = SIDE_FIELDS if side_id is not None else FIXTURE_FIELDS
    fields = set(data.get("fields") or allowed)
    ...
    if "medal" in fields and side_id is None:
        _set_medal_event(fixture, None)
    target.pinned = [name for name in (target.pinned or []) if name not in fields]
    ctx.report.counts["handed_back"] += 1

• No fields means "all of them" for that fixture or side.
• The value is not changed. Only the pin goes. The old hand value stays until a feed writes over it.
• medal is special: handing it back also deletes meta.medalEvent, so the feed's own grade shows again.
• The console shows "Set by hand" with "Let the feed decide" beside each pinned field, and a count such as "2 fields set by hand" (omnium-console/src/pages/FixturePage.tsx:294-307, 449-451). There is no one list of every open pin across an event; the medal overview only counts them (OverviewPage.tsx:565-585).

Who did it Partly built

Every accepted command adds one timeline_item row with actor (an account name, or integration:<code>), source_code, event_type (the command code) and the input payload (workflows/engine.py:142-154). An import's rows are kept in integration_row instead, with raw, mapped and an outcome per row. Per the as-built review of 29 Sep, sign-in is off on the admin service, so every person is recorded as "admin" (not re-checked for this page).

What does not read pins today Built today

• The scoring fold. After each scored ball, reflect_status moves the fixture between scheduled, live and completed, and sets results_official to match. It does not read pinned (scoring/pipeline.py:265-283). The research notes of 30 Sep say the live scoring desks were not deployed to production during the Games (not checked on the server).
• The official flag. No writer reads results_official before it writes (checked with grep, 7 Oct). An import can change the score of an official result, unless a person pinned result. An import can also set a result official, by sending the site's OFFICIAL status (ingest/fixtures.py:121-138).
• Version checks. fixture.version exists but is described as an internal counter, "never a conflict resolver" (models/fixtures.py:103-104). A command does not say which version the sender saw, so two people editing one field: the last save wins.

Agreed design: claims, lists and results Agreed, to build

Agreed design, not in the code yet. Section 2 agreed what is saved and decided; it did not name new tables or columns. The engine (Section 4) and the low-level design will.

What a claim records (rule 1 of the design):

The five field groups each sport starts with. A sport can add its own, for example "detailed stats" from a scraper.

A hand edit sits at the top of every list by default. The result is worked out from play by default, so the two cannot disagree. A separate source is listed for the result only where results arrive on their own, such as an official results list.

Settings, no code needed. An operator can change these during a live match.

The example numbers (60 seconds, 5 minutes) are examples from the design doc, not agreed values.

Fixed safety rules. No setting turns these off.

1. Every claim is saved. Nothing a source sends is thrown away.
2. Values that add up, like events and the score built from them, come from one source at a time. Two sources' events are never mixed, so nothing is counted twice.
3. An older message never replaces a newer one from the same source.
4. Any change to an official result, by a person or a source, goes out as a new version marked as a correction.
5. Every change records who made it, when, the old value, the new value, and why it won.

One source, several inputs. One source can fill values from two places, such as two consoles on one match. Each input is given the values it may send, so two inputs never write the same counted values. If two people must enter the same kind of value, the version check stops lost edits, and the console warns about a likely double entry.

Result status and version. Separate from the match status.

live ──► unofficial ──► official ──► protested ──► official ──► correction
            v14            v15                       v16            v17

The version numbers follow the design doc's own examples (T8 and T9): unofficial at the final whistle is version 14, official is 15, official again after a failed protest is 16, and an accepted correction the next day is 17. A match becomes unofficial when it ends. A person with the right role makes it official, or a trusted source if the competition allows it (T10). When the checker step is on, a second person must approve before official.

Order inside one source (T7). Use the source's own number or time. If it gives none: the time we asked, for a source we pull, or the time it reached us, for one that pushes. Times are compared only inside one source, never across sources (E14). A device's actions are ordered by its own counter, not its clock.

When things go wrong

Decisions

All eleven decisions were agreed on 3 Oct 2026. T3, T5 and T6 changed that day after review comments.

Edge cases. Of 16, nine were agreed as rules:

Dropped: E5 (status only moves forward), E8 (status as its own group) and E12 (line-up status), because the normal priority list and versions already cover them. Moved: E1 (partial lists) and E6 (unknown players) to Section 3, Sources and imports; E9 (format changes mid-match) and E15 (shared places) to Section 6. Q1 was answered: no contract stops a provider's data going to a client today, so every client gets the same winner.

Built today, or still to build

Numbers

Read next

• Imports from Scout: how a Scout run becomes import commands, and the guards around it.
• Commands and the workflow engine: the lock, the rules and the log every write goes through.
• The data model: the fixture, side and participant tables these pins sit on.
• Console and scorer apps: where "Set by hand" and "Let the feed decide" appear.