# Data mastership

*Building a meta-model · lesson 4 of 6 · ~15 min*

## What you will learn

The question that decides whether your model and your wiki coexist in order or in chaos: for every dataset, who is the master? (ARCH-018.)

## The two-truths disease

Your model describes the product. But the runbooks live in Confluence, the tasks lived in a tracker, the code lives in GitLab, and people edit all of them daily. The moment the same fact exists in two editable places, you have two truths, and every reader silently picks one. The cure is not centralization (you will not move ops off their wiki); it is **declared mastership**: every dataset has exactly one System of Record, machine-readably.

## The three lawful patterns

**Model-mastered (write-back).** The dataset is born in the model; external systems get generated, clearly-marked, read-only projections "for convenience of reading". Flow: model → external. Conflict: the model wins; external edits are void or become change proposals. *Live example: the Orkestron.AI model masters its product facts; the public site serves a generated `product-facts.json` marked "do not edit here", with a content hash for drift detection.*

**External-mastered (mirror).** The dataset lives and changes in an external system; the model holds a harvested mirror so it can link, classify and reason. Flow: external → model, via a pipeline that lands raw captures (with provenance) and transforms them. Mirrors are read-only in the model and carry **freshness metadata**: last harvest, cadence, staleness limit. Conflict: the external system wins; you re-harvest, never patch the mirror. *Live example: constantly-updated wiki spaces, source-code clones mastered in GitLab.*

**Partitioned.** The honest mixed case: some datasets model-mastered, some external, each declared separately. One iron rule: the same field is never writable on both sides. If you truly need both, split the datum (external masters `status`, model masters `assessment`).

## The register: sources.yaml

One file at the repository root declares every dataset: master, external system and scope, model location, flow direction, pipeline, cadence, conflict rule, steward, and a **status**: `active`, `declared` (mastership decided, pipeline not built yet: lawful, visible debt), `suspended`, or `retired`. This is the artifact that answers "there's a Confluence: what's in it and who is more authoritative?" mechanically, for every dataset, forever.

## Statuses that met reality

The status vocabulary came from production within days of being written:

- `declared`: the Orkestron model shipped with its canon mirror declared but not yet vendored: visible debt on the register, closed a session later. Registers with zero `declared` entries are earned, not assumed.
- `retired`: DevTeam.Games holds a full export of a task tracker whose account was closed. The SoR is gone; the mirror is a frozen evidence archive that can never be re-harvested and must never be "corrected". The register says exactly that.
- `suspended` + a never-publish conflict rule: a proprietary reference codebase used once for design inspiration: present on disk, legally untouchable, and the register is where that fact lives instead of in someone's memory.

## Drift, watched by machinery

Declared mastership enables mechanical honesty: the write-back example above runs a daily check that regenerates the projection from the model, compares content hashes with the live copy, and alerts the owner on drift, on absence, or if the check itself breaks. Divergence gets noticed by a cron job, not by embarrassment in a meeting.

## Key takeaways

- One master per dataset; flow follows mastership; copies are disposable and marked.
- Three patterns: write-back, mirror, partitioned; the same field never writable twice.
- `sources.yaml` + statuses (active/declared/suspended/retired) turn tribal knowledge about authority into versioned data.

## Go deeper

- [Data mastership and Systems of Record (ARCH-018)](/spec/#02-architecture/Data-Mastership.md)
- [Synchronization across universes](/spec/#03-federation/Synchronization.md) (the federation-level sibling of this lesson)

Next: [Reusing the world](05-reuse.md)