tegwick
d103955217
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
---
|
|
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.
|
|
|
|
## Enforced routing
|
|
|
|
`rmgr authority route` is the executable gate for this contract. File-derived
|
|
records require both repository and domain context and resolve to
|
|
`repository:<domain>/<repo>` under Repo Manager. Central and derived record
|
|
types resolve to their one declared hub owner. Unknown types and writes whose
|
|
claimed owner disagrees with the contract are rejected instead of falling back
|
|
to whichever hub received the request.
|