coulomb/repo-manager
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: advance conformance and deterministic ID migration

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
This commit is contained in:
tegwick 2026-08-21 22:43:37 +02:00
parent 3791411591
commit ad621d6c0d
10 changed files with 513 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

55
docs/hub-record-authority_v1.md Normal file
View file

@ -0,0 +1,55 @@
---
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.