## Status

Proposed.

## Context

Investigating a workplan-identifier flip-flop (`ADR-007`) revealed that two State Hub instances were operating as peer databases, not as a primary and a replica:

Address | Instance | Workplans
--- | --- | ---
`127.0.0.1:8000` (IPv4) | local uvicorn on docker postgres | 955
`[::1]:8000` (IPv6) | ssh tunnel `state-hub-primary` → railiance01 | 649

Both listen on port 8000, separated only by IP family, so every tool defaulting to `127.0.0.1` reached the local instance while believing it was the primary.

Measured divergence — 320 records exist locally but not on the primary:

    backed by a file that exists on disk    288    fully rebuildable
    no backing file recorded                 28    not rebuildable as-is
    same filename, different UUID             4    duplicate registration

No file was missing for any of the 288. The divergence is therefore almost entirely redundant: it can be discarded and rebuilt from repositories without losing anything.

`ADR-001` already says work originates as repository files and the hub is a read model. The two-peer-database situation contradicts that in practice: a second database accumulated 306 net records of its own.

## Decision

1. One authoritative hub, deriving from repository files. The central State Hub — running on railiance — is authoritative. It is authoritative as a reading of the repositories, not as a second place data lives. Repository files remain the source of truth (`ADR-001`).

2. A local hub is a cache, never a database. Local instances hold a rebuildable projection. A cache may be discarded and reconstructed from the repositories at any time, and losing it must never lose work.

This replaces the peer-database arrangement. It is also why the divergence is tractable: a divergent database is a merge problem, a stale cache is a refresh problem.

3. Local work requires no hub at all. Repository files are self-describing — identifier, status, tasks, all in frontmatter. Working in a repository requires reading files, not querying an index. A cache is an optimization for cross-repo questions, never a prerequisite for doing work.

4. Hub data is classified by origin, and the two kinds have opposite rules.

| File-derived | Hub-native
--- | --- | ---
Examples | workplans, tasks, statuses, dependencies | progress events, decisions, inbox messages, token events
Source of truth | the repository file | the hub
Offline behaviour | write the file and commit — the commit is the write | buffer locally, replay when reachable
Conflict model | none; conflicts are git conflicts, resolved in git | none; append-only merges regardless of order
Central accepts pushes? | no — it derives | yes

Neither kind needs a hub-side conflict model. That is the point of the split: if central derives file-backed state, it cannot hold a conflicting version of it — it re-derives whatever git settles on. Two people editing one workplan is a git conflict and belongs to git.

5. Central derives file-backed state; it does not accept pushes of it. "Authoritative" means authoritative reading, so nothing may inject derived state directly. Hub-native records are the exception and keep a real write path.

6. Preliminary until confirmed. Locally registered data and uncommitted repository state are preliminary until the central service has seen them. Mitigation is by changing the repository files and the local cache — never by editing central to match a local view.

Combined with `ADR-007` decision 2 (identifiers derived from `PREFIX-WP-NNNN`), "preliminary" largely stops mattering: a cache computes the same identifier central will, so offline-registered data is already correct on arrival and needs confirmation rather than reconciliation.

7. Every record has exactly one authoritative hub. The State Hub retirement splits one hub into several. Multiple central hubs are permitted only under this rule: the owning hub is determined by the record's repository and domain. Without it, the same peer-database divergence recurs at larger scale.

8. Cache reads are advisory and must carry their age. Cross-repo answers from a cache are advisory and should be presented with staleness. For the repository an agent is working in, the file is truth and the cache is never consulted for correctness.

## Orphan disposition

The 28 records with no backing file are the only ones a cache rebuild would drop. They fall into three classes, to be separated before any rebuild:

1. Broken links — a file exists but `backing_filename` was never recorded. `RMGR-WP-0004` is one: the workplan file exists and is committed. These are metadata repairs, not data loss, and are likely the largest class.
2. Live hub-first records — `proposed`, `ready`, or `backlog` with no file, in `activity-core`, `core-hub`, `hub-core`, `issue-core`, `ops-hub`, `prj-forgejo-org-refactor`, `railiance-enablement`, `railiance-infra`, `reef-railiance`. Each needs a repository file written or an explicit drop. These are `ADR-001` violations and must not be preserved as hub-only records.
3. Closed hub-first records — `finished` or `archived` with no file. Retain as historical provenance where cheap; do not reconstruct plans that are done.

A cache rebuild enforces `ADR-001` retroactively: the only casualties are records that broke it.

## Consequences

Positive. The divergence becomes discardable rather than mergeable. Offline work is fully supported without a write buffer for file-backed state — the git commit is the write. No hub-side conflict model is needed for either data kind. Authority stops being a policy claim and becomes a structural property.

Negative. The 28 orphans require case-by-case disposition before a rebuild. Any consumer that treats a local hub as authoritative must be corrected. The one-hub-per-record rule constrains the retirement's hub split.

Rescoping. `STATE-WP-0068` (offline write buffer and edge relay) is scoped as a single mechanism. Under decision 4, most of what it buffers does not need buffering — only the append-only hub-native stream does. Its scope should be re-examined before more is built on it; this may reduce work rather than add it.

Correction to `ADR-007`. Decision 2 there calls the workstation instance a "development read replica". It was neither a replica nor smaller — it held 306 more workplans than the primary. Superseded by decisions 1–3 here.

## Implementation

Owned by `repo-manager` for file-derived state (decision `747011c6`; it already owns repository representation, file-backed record indexing, and reconciliation) and by `hub-core` for hub-native records. Tracked under `RMGR-WP-0005`.

## References

- ADR-001 — workplans originate as repo files; hub is a read model
- ADR-007 — identifier uniqueness, derived identifiers, worker topology
- Decision `747011c6` — repository standards belong to Repo Manager
- `RMGR-WP-0005` — registrar consolidation and deterministic identifiers
- `STATE-WP-0068` — offline write buffer and edge relay (rescope candidate)
- Divergence measurement, 2026-08-17: 955 local / 649 primary / 320 local-only