coulomb/repo-manager
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
repo-manager/docs/hub-record-authority_v1.md
tegwick ad621d6c0d feat: advance conformance and deterministic ID migration 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
2026-08-21 22:43:37 +02:00

3.1 KiB
Raw Blame History

id type title version status created updated workplan_task
RMGR-CONTRACT-AUTHORITY-0001 contract State Hub record authority and offline behaviour 1 draft-reviewable 2026-08-21 2026-08-21 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.