## About this document

First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.

## 01Introduction and Goals

State Hub is a queryable, auditable memory of work: domains, repos, workplans, tasks, decisions, progress. Files remain the origin. The hub is derived state (custodian ADR-001, ADR-003).

It remains operational until retirement gates in `prj-state-hub-retirement` are met. Replacement ownership is moving toward `repo-manager` and `hub-core`.

### 1.1 Requirements Overview

- Rebuild coordination state from registered repository files.
- Deterministic UUIDv5 work-record identifiers (ADR-007). Any instance may reconcile the same repository; the canonical record id produces the same database key and writeback bytes on every instance.
- Preserve compatibility; do not take new permanent architectural ownership.

### 1.2 Quality Goals

1. Rebuildability from git.
2. Hub never becomes the origin of work.
3. Extraction paths stay open.

### 1.3 Stakeholders

Role | Concern
--- | ---
state-hub | Live read-model during retirement.
the-custodian | Estate rules the hub must not invert.
repo-manager | Incoming consistency / repo representation.
product repos | Workplan files the hub indexes.

## 02Architecture Constraints

N/A for this stub — retirement program is the binding constraint.

## 03System Scope and Context

In: indexing workplans/tasks/decisions, consistency rebuild, query API and dashboard used today. Out: being the source of work items; new cross-domain capabilities; publication of policy (policy-nexus).

### 3.1 Business Context

Files are excellent for canon and provenance. The estate still needs a live query surface while retirement proceeds.

### 3.2 Technical Context

Inputs: workplan markdown via `fix-consistency`. Outputs: HTTP/MCP APIs. Neighbours: every registered repo, activity-core (ops runs), policy-nexus (does not index the hub).

## 04Solution Strategy

N/A for this stub. The strategy is already in the estate ADRs: files first, materialized derived state, single registrar, local cache vs authority (ADR-010, proposed).

## 05Building Block View

### 5.1 Level 1 – System/Top-Level

N/A for this stub.

## 06Runtime View

N/A for this stub.

## 07Deployment View

N/A for this stub.

## 08Cross-Cutting Concepts

N/A for this stub.

## 09Architecture Decisions

Estate-wide binding decisions live in the-custodian and are listed on the estate map. Service-local implementation decisions live in `docs/adr/` and do not supersede the estate decisions:

Estate ADR | Status | Why it binds this system
--- | --- | ---
`CUST-ADR-001` | accepted | File-backed work originates in repositories; the Hub projects it. Published `/adr/custodian-workplans-as-repo-artefacts/v1/`.
`CUST-ADR-003` | accepted | How derived state invalidates; ADR-012 supplies commit provenance.
`CUST-ADR-007` | accepted | Namespace-aware identity and deterministic work-record UUIDs.
`CUST-ADR-010` | proposed | Two kinds of hub data.
`CUST-ADR-011` | proposed | Namespace and reconciliation limits.
`CUST-ADR-012` | accepted | Forge projection baseline and preliminary overlays.

Local ADR | Status | Scope
--- | --- | ---
`STATE-ADR-001` | accepted | Repository identity and recovery contract for canonical-name changes.

Do not treat a State Hub `/decisions` row as the published ADR.

## 10Quality Requirements

N/A for this stub.

## 11Risks and Technical Debt

N/A for this stub. Residual: this workstation cannot mint registrar UUIDs.

## 12Glossary

Term | Meaning
--- | ---
Read model | Derived index; never the origin.
Registrar | The single instance allowed to mint workplan UUIDs.
Retirement | Coordinated move of capabilities out of this repo.