---
id: RMGR-CONTRACT-AUTHORITY-0001
type: contract
title: "State Hub record authority and offline behaviour"
version: "1"
status: draft-reviewable
created: "2026-08-21"
updated: "2026-08-21"
workplan_task: RMGR-WP-0005-T08
---

# State Hub record authority and offline behaviour v1

`config/hub-record-authority.yaml` classifies every table imported by the State
Hub model package on 2026-08-21. It is the machine-readable routing contract;
this document defines the meaning of its classes.

| Class | Truth source | Offline behaviour | Central write rule |
| --- | --- | --- | --- |
| `file-derived` | Repository file and Git history | Change the source file and commit. The commit is the write. | Re-index after Git settles; reject direct state pushes. |
| `hub-native-append` | The named central hub | Append to an idempotent local outbox and replay. | Accept append-only events with a stable source identity. |
| `hub-native-control` | The named central hub | Do not apply generic append-only replay. Stay read-only unless the record type has an ordered, idempotent command contract. | Accept commands at the one authoritative owner. |
| `derived-cache` | A named upstream source, repository file, log, or runtime observation | Do not buffer. Rebuild or refresh. | Replaceable projection only. |
| `retired` | Archived provenance | Reject new writes. | Read-only until physical deletion. |

The first class is ADR-010's file-derived side. The next two are subdivisions of
its hub-native side. This subdivision is necessary because the current schema
contains mutable control records: message read/archive markers, launch-request
status, service catalog changes, and domain/topic administration are not
append-only events and cannot safely be reconciled by unordered union. A generic
offline buffer is therefore valid only for `hub-native-append`.

Several current State Hub REST endpoints still mutate records classified as
file-derived. Those endpoints are compatibility surfaces during extraction;
their existence does not confer authority. Decisions and intakes are
file-derived under the ratified work-record standard and Repo Manager's governed
commands, superseding ADR-010's older examples.

`managed_repos` is a composite projection. Repository identity, purpose, and
classification derive from repository declarations and Forge; host paths and
observation timestamps are replaceable observations. No field in that row makes
the database a source of repository truth.

## Consequences for the offline edge

- Buffer only progress and token event appends under the generic replay path.
- Route file-derived commands to Repo Manager; when central is absent, commit
  the file and let later indexing observe it.
- Keep control-plane commands online-only until their owning hub publishes
  ordering and idempotency semantics. Queuing them in the append-only stream
  would silently invent a conflict policy.
- Rebuild caches and reject writes to retired suggestion tables.

This narrows the offline-buffer part of `STATE-WP-0068`; it does not authorize
changes in repositories owned by hub-core, activity-core, ops-hub, or fin-hub.