Sport plugins and rule versions

What this part does

This part decides what a sport's rules are made of, and how a new version of them reaches matches safely. Answered wrong, a deploy changes a running match's score, a new sport needs engine changes, or one bad release stops every match of a sport.

The split between code and settings is the base of everything else (decision P2):

How it works

A sport becomes runnable in five steps. Steps 1 to 4 are built today. Step 5 is where today and the agreed design differ.

1. Six files, one class. A sport folder has constants.py, commands.py, validations.py, actions.py, stats.py and sport.py. The first five each define a mixin class. sport.py joins them into one Sport subclass with a permanent code, such as football.
2. One line names it. The plugin's pyproject.toml lists the folder under the entry-point group omnium.flows. An entry point is a name a Python package publishes so other code can find it without importing it by name.
3. The registry imports it. load_registry() reads every entry point in that group, imports the module, and registers each concrete Workflow class it finds. Each decorated method becomes a component with the key code.member, for example football.goal.
4. The engine asks by key. A published program document lists component keys. When a command runs, the engine looks each key up in the registry and calls it. The engine package never names a sport.
5. A match is pinned to rules. Today the pin is to a program document of names (fixture.scoring_program_version_id). In the agreed design it is to an exact release of the whole package (fixture.release_id), set when the match is created.

Agreed, to build How a new version reaches matches. Each release climbs six steps. It can be refused at step 2, and taken back from steps 5 or 6 at any time without touching a match already on it.

Agreed, to build How a match keeps its release. Releases are installed side by side, so a deploy adds a release and never replaces one. Each events match points at the release it was created with.

Who picks up a published change (P12)

This answers the question asked on the design doc: "if I change logic inside the plugin and publish, will it not get picked?" It is picked up wherever that is safe.

A critical bug in a live match is fixed in minutes, never by surprise.

A worked example

Low-level design

This section shows real code first, then the agreed new pieces. Commands, validations and actions themselves are explained line by line in Writing a workflow in code; here we stay on the contract, the registry, sport.py, releases and pinning.

The contract: what a plugin may import Built today

The plugin depends on one package only: omnium-contract. It holds the base classes, the five decorators and the registry. The engine and the plugin meet only here.

# packages/flows/pyproject.toml:11-23 (trimmed)
dependencies = [
    # The ONLY runtime dependency: models + kit + the stat compiler, zero
    # engine code. import-linter enforces this (see the root pyproject).
    "omnium-contract>=0.2",
]

Every decorator attaches a ComponentSpec to the function and does nothing else. The spec is what the registry, the publish gate and the screens read.

# packages/contract/src/omnium_contract/flows/components.py:69-108 (trimmed)
@dataclass(frozen=True, slots=True)
class ComponentSpec:
    """``source_sha`` currently hashes the component's own source. Before M3
    (publish pinning) it must grow to the transitive closure — the component
    plus every helper it calls — per the round-eight flaw review, so a
    ``shared/`` edit cannot change behaviour without changing a pin."""

    kind: ComponentKind
    name: str  # the member name; the key's last segment
    reads: tuple[str, ...] = ()
    input_model: type[BaseModel] | None = None
    validations: tuple[str, ...] = ()
    actions: tuple[str, ...] = ()
    gives: Gives | None = None
    when: When = When.NOW
    keys: tuple[str, ...] = ()
    source_sha: str = ""

# components.py:116-121
def _source_sha(fn: Callable[..., Any]) -> str:
    source = inspect.getsource(fn)
    return hashlib.sha256(source.encode()).hexdigest()

In plain words: each component carries a fingerprint, source_sha, but it is the hash of that one function's own text. A helper the function calls is not part of it. The code's own docstring says this must be fixed. The agreed design replaces it with one code_sha over the whole package (P3).

sport.py: one class per sport Built today

sport.py joins the mixins and declares what the sport is. This is the real football class.

# packages/flows/src/omnium_flows/football/sport.py:40-64 (trimmed)
class Football(
    FootballCommands,      # commands.py
    FootballValidations,   # validations.py
    FootballActions,       # actions.py
    FootballTotals,        # stats.py
    Sport,
):
    code = "football"
    format_model = FootballFormat   # constants.py

    facts: ClassVar[dict[str, str]] = {
        "goals": "Goals scored by a side, per half (segment) or the match",
        "goals_for": "Goals a side scored in the match",
        "own_goals": "Own goals put in by a player, counted for the other side",
        "red_cards": "Red cards shown, a second yellow included",
        # ... 8 facts in all
    }
    roles: ClassVar[frozenset[str]] = frozenset({"scorer", "assist", "carded"})

In plain words:

• code is permanent. It prefixes every component key, so renaming it breaks every pin.
• format_model is the typed shape of fixture.format. A scoring workflow without one is refused at class definition.
• facts is the line catalogue. The publish gate holds each action's declared keys to this list, so a typo in a fact name is refused before it becomes a column of zeroes.

The base class enforces its rules when Python reads the class, not later:

# packages/contract/src/omnium_contract/flows/sport.py:118-179 (trimmed)
def __init_subclass__(cls, **kwargs: Any) -> None:
    lineage = [base for base in cls.__mro__[1:] if ... concrete Workflow ...]
    if len(lineage) > 1:
        raise TypeError("inheritance depth is capped at workflow → format")
    parent = lineage[0] if lineage else None
    code = _check_declarations(cls)

    for name in dir(cls):
        spec = spec_of(getattr(cls, name, None))
        if spec is None:
            continue
        inherited_from = f"{parent.code}.{name}" if parent and name not in cls.__dict__ else None
        components[name] = RegisteredComponent(
            key=f"{code}.{name}", sport_code=code, spec=spec, fn=member,
            inherited_from=inherited_from,
        )

    if parent is not None and not overrode_anything and cls.format_model is parent.format_model:
        raise TypeError("... a numbers-only difference is a config in the dashboard, not a subclass")
    if parent is not None and not cls.__dict__.get("scope"):
        raise TypeError("... a format must say which configs it scores")

In plain words: a format is a subclass of a sport that changes a rule, such as The Hundred in cricket. It may be one level deep only. It must override something, because a numbers-only change (100 balls) is a setting. It must name its scope, the configs it scores. The real example, TheHundred(Cricket) in cricket/hundred.py:27-35, overrides one validation (bowler_quota) and inherits 32 of its 33 components (counted from the registry, 7 Oct).

The registry: found by entry point, never by name Built today

# packages/flows/pyproject.toml:26-37
[project.entry-points."omnium.flows"]
cricket = "omnium_flows.cricket"
swimming = "omnium_flows.swimming"
beach_volleyball = "omnium_flows.beach_volleyball"
volleyball = "omnium_flows.volleyball"
boxing = "omnium_flows.boxing"
football = "omnium_flows.football"
athletics = "omnium_flows.athletics"
games = "omnium_flows.games"
results = "omnium_flows.results"

# packages/contract/src/omnium_contract/flows/registry.py:94-117 (trimmed)
def load_registry(group: str = ENTRY_POINT_GROUP) -> Registry:   # "omnium.flows"
    registry = Registry()
    for entry_point in importlib_metadata.entry_points(group=group):
        module = entry_point.load()
        found = [
            member for member in vars(module).values()
            if isinstance(member, type) and issubclass(member, Workflow)
            and not member.__dict__.get("__abstract__", False)
        ]
        if not found:
            raise RegistryError(f"entry point {entry_point.name!r} ... defines no Workflow")
        for workflow in found:
            registry.add_workflow(workflow)   # refuses a duplicate code or key (:35-43)
    return registry

In plain words: nine entry points give ten workflows, because omnium_flows.cricket exposes both Cricket and TheHundred (cricket/__init__.py). A module with no workflow, a workflow code used twice, or a component key used twice stops loading with a clear error.

How the engine calls a component today Built today

# packages/core/src/omnium_core/flows_host.py:57-128 (trimmed)
def _check_version_pin() -> None:
    pin = os.environ.get("OMNIUM_FLOWS_VERSION")
    if not pin:
        return                                   # dev: whatever is installed
    installed = importlib_metadata.version("fanos-omnium-flows")
    if installed != pin:
        raise SandboxError(f"flows version mismatch: the deployment pins {pin} "
                           f"but {installed} is installed — fix the image or the pin")

def registry() -> Registry:
    """The installed flows package's registry, discovered once per process."""
    global _registry
    if _registry is None:
        _check_version_pin()
        _registry = load_registry()
    return _registry

@lru_cache(maxsize=512)
def _component_for(key: str) -> RegisteredComponent:
    component = registry().component(key)
    if component is None:
        raise SandboxError(f"component {key!r} is not in the installed flows package — "
                           f"the pinned program and the deployed omnium-flows version disagree")
    return component

def function_for(impl: str) -> FlowsFunction:
    return FlowsFunction(_component_for(impl))

In plain words, three facts matter for releases:

• One registry per process. A server can hold only one version of every sport at a time.
• The process-wide pin. OMNIUM_FLOWS_VERSION is a deploy setting. If the installed wheel differs, scoring refuses to start. The Jenkins staging job passes it as a Docker build argument (Jenkinsfile_stg:463-476).
• Lookup by name only. The pipeline resolves a node with flows_host.function_for(node.impl) (scoring/pipeline.py:483-495). Whatever code is installed under that key runs.

Pinning today: names, at the first command Partly built

# packages/core/src/omnium_core/scoring/store.py:152-199 (trimmed)
async def for_fixture(session, fixture) -> Pinned:
    """Pinned if it has been scored before; otherwise the most specific published
    one for its format and kind, which the first accepted command will pin."""
    if fixture.scoring_program_version_id is not None:
        return await load_version(session, fixture.scoring_program_version_id)
    resolved = await published_for(session, fixture.sport_id,
                                   fixture_type=fixture.fixture_type,
                                   format_code=fixture.format_code)
    ...

async def for_workflow(session, workflow_id) -> Pinned:
    """An apply-mode workflow is not pinned per fixture: its commands change
    records, and the newest rules apply."""

async def pin(session, fixture, version_id) -> None:
    if fixture.scoring_program_version_id is not None:
        return
    fixture.scoring_program_version_id = version_id

# packages/admin/src/omnium_admin/routers/bridge.py:284-285
if result.accepted and not result.duplicate:
    await store.pin(session, fixture, pinned.version_id)

In plain words: a match gets its pin on its first accepted command, unless an operator picked a program when creating it (admin/routers/fixtures.py:364-366). The pin points at a scoring_program_version row. That row's document lists component keys and each one's implSha, but nothing reads implSha at run time. So a match pinned to version 4 runs whatever code is installed under those keys today.

Publishing today Partly built

The "skip unchanged" row is where today's gap bites. The document holds implSha = source_sha per node (flows_publish.py:110). Football's actions call a plain helper, _line (football/actions.py:27), that has no decorator. Change _line and every component's source_sha stays the same, so the checksum stays the same, so install publishes nothing, while the behaviour has changed.

The structure gate Built today

# packages/flows/scripts/check_structure.py:26-61 (trimmed)
REQUIRED_MODULES = (
    "constants.py", "commands.py", "validations.py",
    "actions.py", "stats.py", "sport.py",
)

def check_shape() -> None:
    for package in sorted(SRC.iterdir()):
        if not package.is_dir() or package.name in {"shared", "__pycache__"}:
            continue
        for module in REQUIRED_MODULES:
            if not (package / module).exists():
                problems.append(f"{package.name}: missing {module} — the shape is fixed")
        if not (TESTS / package.name).is_dir():
            problems.append(f"{package.name}: no tests/{package.name}/ directory")

def check_components() -> None:
    registry = load_registry()
    for component in registry.components():
        if component.key.rsplit(".", 1)[-1] != component.spec.name:
            problems.append(f"{component.key}: key does not end with member name ...")
        if component.inherited_from is None and component.spec.name not in test_text:
            problems.append(f"{component.key}: no test names it")

make structure runs this and check_clean_import.py, which imports every entry point in a subprocess and fails if import prints, opens files or uses the network. make check runs both, and CI runs make check (.github/workflows/ci.yml:70). The plugin's own ruff settings ban clocks, random, os.environ and file IO inside components (packages/flows/pyproject.toml:66-73), so the same log always gives the same answer.

The goldens Built today

A golden is a recorded match kept as proof: its format, its log and the state and lines it produced. Two kinds exist today:

The file test compares canonical JSON: keys sorted, whole floats as integers, null equal to absent (tests/test_goldens.py:20-30). The agreed compatibility replay uses the same idea, but against two releases and after every event.

The new tables Agreed, to build

Two new tables and four new columns (R1). Nothing below exists in the code yet.

-- NEW: one row per plugin release. Never updated after status 'prod', except to 'retired'.
CREATE TABLE plugin_release (
  id            uuid PRIMARY KEY,
  version       text NOT NULL UNIQUE,          -- "0.8.0", the wheel version
  code_sha      text NOT NULL,                 -- sha256 of the wheel's RECORD (Section 5, M6)
  status        text NOT NULL,                 -- proven, staging, prod, retired
  notes         text NOT NULL,
  rule_changes  jsonb NOT NULL DEFAULT '[]',   -- declared: [{"sport":"cricket","what":"super over tie-break","keys":[...]}]
  replay_report jsonb NOT NULL,                -- matches replayed, differences, by sport
  approved_by   text, approved_at timestamptz,
  created_at    timestamptz NOT NULL DEFAULT now()
);

-- NEW: which release new matches use. competition_id NULL = the sport's default.
CREATE TABLE release_default (
  sport_id       uuid NOT NULL REFERENCES sport(id),
  competition_id uuid REFERENCES competition(id),
  release_id     uuid NOT NULL REFERENCES plugin_release(id),
  from_at        timestamptz NOT NULL,         -- forward only (P8)
  set_by         text NOT NULL, set_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (sport_id, competition_id, from_at)
);

ALTER TABLE fixture                 ADD COLUMN release_id uuid REFERENCES plugin_release(id);  -- pinned at creation (events)
ALTER TABLE scoring_program_version ADD COLUMN release_id uuid REFERENCES plugin_release(id);
ALTER TABLE timeline_item           ADD COLUMN release_id uuid;   -- which release applied this command (P6)
ALTER TABLE scoring_checkpoint      ADD COLUMN code_sha text;     -- Section 5, M4

In plain words:

• code_sha covers the whole wheel, through the hash of its RECORD file (the list of every file in the wheel with its hash). Any change anywhere, a shared helper included, makes a new fingerprint.
• rule_changes is what the CI replay judges against. An undeclared difference cannot pass.
• release_default only moves forward: a new row with a later from_at, never an edit to the past.
• scoring_program_version stays as the generated document and gains the release it came from, so a document and its code can no longer drift apart.
• scoring_checkpoint gains code_sha because saved checkpoints carry no version today (contract/models/scoring.py:185-213). After a deploy, an incremental fold could resume from old-code state.

How a match gets its release Agreed, to build

-- At creation of an events match, inside the same transaction as the INSERT:
SELECT release_id FROM release_default
 WHERE sport_id = $sport
   AND (competition_id = $competition OR competition_id IS NULL)
   AND from_at <= $scheduled_start
 ORDER BY competition_id NULLS LAST, from_at DESC
 LIMIT 1;
-- fixture.release_id = that; never changed by the engine afterwards.

The most specific default wins: the competition's row before the sport's row, and the latest from_at that is not after the match's start (R2). A scorecard or operational command reads the same default at the moment it runs and writes it to timeline_item.release_id.

Retiring a release is refused while this finds a row (R3):

SELECT 1 FROM fixture
 WHERE release_id = $r AND status NOT IN ('COMPLETED','CANCELLED','VOID');

Running releases side by side, each in its own worker process with its own folder and registry, is Section 5's decision M6. See The live scoring engine. The registry change it needs is small: load_registry(path) loads one release from its folder, and flows_host.registry() becomes registry_for(release).

The compatibility replay in CI Agreed, to build

# flows/scripts/replay_compat.py   (new, from the design doc)
def main(old: str, new: str, corpus: Path, notes: ReleaseNotes) -> int:
    with Worker(release=old) as a, Worker(release=new) as b:   # separate processes, own folders
        failures = []
        for match in Corpus(corpus):                            # goldens + nightly prod export
            ra = a.replay(match.format, match.log, every_event=True)
            rb = b.replay(match.format, match.log, every_event=True)
            for diff in first_differences(ra, rb):              # canonical JSON, state and lines
                if not notes.declares(match.sport, diff.keys):
                    failures.append(f"{match.id} ball {diff.seq}: {diff.key} {diff.old} -> {diff.new}")
    print_report(failures)
    return 1 if failures else 0

1. The corpus. Today's 20 file goldens plus the logs of finished matches, exported nightly from prod to a read-only store without personal data. Each entry is the match's format, its log, and its final state and lines.
2. Replay twice. With the previous release and the new one, each in its own process with only its own package loaded.
3. Compare. Canonical JSON of the state after each event and of the final lines, so a difference names the first ball where the two releases part.
4. Judge. Each difference must fall inside a declared rule change (its sport and keys). Anything else fails the build with the match, the ball, and the old and new value.

Cost. From the design doc: the 20 goldens replayed in 1.35 s in total on 6 Oct, Python start-up included. Re-measured for this page on a laptop on 7 Oct: 0.75 s wall time, pytest reporting 0.45 s. For 200 recorded matches of about 600 events, replayed twice, that is about 240,000 steps, well under a minute (estimate, from the design doc).

The release workflow in CI Agreed, to build

# .github/workflows/flows-release.yml   (new, from the design doc)
on: { push: { branches: [main], paths: ["packages/flows/**"] } }
jobs:
  release:
    steps:
      - run: make check                                   # gate, tests, goldens
      - run: uv build --package fanos-omnium-flows
      - run: python packages/flows/scripts/replay_compat.py --old $PREV --new dist/*.whl --corpus s3://.../replay-corpus
      - run: scripts/publish-flows.sh                      # refuses an existing version (today)
      - run: python -m omnium_worker register-release --env staging   # plugin_release row + install

Prod is not in this file. An admin presses "Approve for prod" on the releases screen, which runs the same register step against prod (R7). Who may press it is Section 13's question.

Changing a unit's type Agreed, to build

Today archetype and fixture_type are set only when a fixture is created (admin/routers/fixtures.py:346-352), and no command changes them. At the Asian Games a duel that was really a ranking needed SQL (F16, F33). The agreed command results.change_type (R6):

-- results.change_type, run as a dry run first (Section 4, C11), then for real:
SELECT ... FROM fixture WHERE id = $fixture FOR NO KEY UPDATE;       -- the match lock
-- refused if the match is in events mode and has any timeline_item
-- dry run: list every rank, place, score shape and medal that the new type cannot hold
UPDATE fixture SET archetype = $archetype, fixture_type = $type, changed_seq = $seq WHERE id = $fixture;
DELETE FROM fixture_competitor_rank WHERE fixture_competitor_id IN (...);   -- only what the person confirmed
INSERT INTO timeline_item (...);                                             -- old type, new type, removed values
COMMIT;

Sides (fixture_competitor) are kept. After the change, the import's compare can fill the unit's places on its next run, as happened after the SQL fix on 1 Oct. results.set_release, for a match that has not started, is the other new command (P8).

Settings

Migration from today's code

1. code_sha over the whole package; written on scoring_program_version.
2. Create plugin_release and release_default. Register today's installed 0.6.0 as the first release and the default for every sport.
3. Add fixture.release_id, filled for existing unfinished events matches from what is installed today.
4. Pin at creation: store.pin moves from the bridge to fixture creation.
5. Releases side by side in workers (Section 5, migration step 4).
6. results.change_type and results.set_release.
7. The CI release workflow and the replay corpus export.
8. The admin releases screen, the release line on a match, the change type dialog.
9. The new-sport scaffold and docs, fixed to the six-file shape.

Tests that prove it

Screens

Agreed, to build Two people use these screens: an admin who adds sports and rolls out releases, and an operator who sees which rules a match runs. Each sees what one click will change before they click.

The numbers in the releases screen are examples from the design doc. Today the old program editor's routes return 410 Gone (admin/routers/scoring_programs.py:322), and no screen lists releases or shows a match's release.

When things go wrong

Decisions

All 22 are agreed (closed 6 Oct 2026).

Built today, or still to build

Numbers

Read next

• The live scoring engine: step functions, checkpoints, and the side-by-side workers (M6) this page relies on.
• Commands and the workflow engine: the one road every command takes, where the release is read.
• Writing a workflow in code: commands, validations and actions, line by line.
• What's next: what is built in which order.