docs: accept repository classification boundary
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
This commit is contained in:
parent
f51a5819d5
commit
6288ba3d7d
6 changed files with 201 additions and 12 deletions
10
INTENT.md
10
INTENT.md
|
|
@ -2,8 +2,8 @@
|
|||
|
||||
**Project:** `hub-core`
|
||||
**Domain:** `infotech`
|
||||
**Status:** Active — surviving hub framework and runtime (`HUB-WP-0004`)
|
||||
**Updated:** 2026-08-21
|
||||
**Status:** Active — production hub framework and runtime
|
||||
**Updated:** 2026-08-22
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ three-repo hub stack:
|
|||
| --- | --- |
|
||||
| `hub-core` | Shared Python package plus target framework/runtime — this repo |
|
||||
| `state-hub` | Legacy coordination host; capabilities move or retire incrementally |
|
||||
| `core-hub` | Current `/api/v2` runtime; routes are absorbed, then the repo is archived |
|
||||
| `core-hub` | Previous `/api/v2` runtime; retained temporarily as rollback before archive |
|
||||
|
||||
Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
|
||||
|
||||
|
|
@ -109,6 +109,7 @@ models where extended, and workflow callbacks.
|
|||
| Concern | Owner |
|
||||
|---|---|
|
||||
| Repository-owned workplans, tasks, decisions, and consistency | `repo-manager` over Git authority |
|
||||
| Repository classification validation and repository projection | `repo-manager` over `.repo-classification.yaml` authority |
|
||||
| Domain-specific business data and APIs | Domain hubs and specialized services |
|
||||
| Custodian canon, constitution, domain charters | `the-custodian` |
|
||||
| Event-triggered maintenance task creation | `activity-core` |
|
||||
|
|
@ -127,7 +128,7 @@ acceptance flows) stay in the host hub.
|
|||
| Consumer | Relationship |
|
||||
|---|---|
|
||||
| `state-hub` | Compatibility source during incremental capability cutover |
|
||||
| `core-hub` | `/api/v2` route/runtime source to absorb before archival |
|
||||
| `core-hub` | Rollback source during stabilization; archive after CORE-WP-0010 closes |
|
||||
| `ops-hub`, `fin-hub`, future hubs | Domain/aspect extensions using versioned hub-core ports and manifests |
|
||||
|
||||
Extraction boundary and migration status:
|
||||
|
|
@ -145,6 +146,7 @@ Extraction boundary and migration status:
|
|||
- the surviving runtime exposes versioned `helixforge.hub-extension` ports and projections
|
||||
- schema changes to shared primitives are versioned through hub-core migrations, not ad hoc forks
|
||||
- repository work authority and domain-specific business models never migrate into hub-core
|
||||
- cross-domain navigation is rebuilt from versioned owner projections with provenance
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -77,6 +77,13 @@ surface runs the immutable `055cf49` image while Core Hub remains deployed with
|
|||
an empty writer set through the seven-day stabilization window ending no
|
||||
earlier than 2026-08-28T20:49:50+02:00.
|
||||
|
||||
Repository classification remains authoritative in each repository and is
|
||||
validated/projected by Repo Manager. Hub-core consumes that versioned
|
||||
projection for cross-domain navigation under
|
||||
`docs/adr/ADR-0002-repository-classification-projections.md`; it does not own a
|
||||
mutable topic or classification write surface. Implementation and A5 handoff
|
||||
are tracked in `HUB-WP-0006`.
|
||||
|
||||
## First Slice
|
||||
|
||||
- SQLAlchemy base metadata and timestamp helpers.
|
||||
|
|
|
|||
20
SCOPE.md
20
SCOPE.md
|
|
@ -1,6 +1,6 @@
|
|||
# SCOPE — hub-core
|
||||
|
||||
**Updated:** 2026-08-21
|
||||
**Updated:** 2026-08-22
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -38,6 +38,9 @@ the Python package remains independently importable.
|
|||
catalogs, port APIs, fixtures, and compatibility matrices
|
||||
- **Surviving runtime surfaces** — registry, messaging, progress and
|
||||
interaction events, projections, telemetry, `/api/v2` compatibility, and MCP
|
||||
- **Cross-domain navigation projections** — rebuildable aggregation of Repo
|
||||
Manager's validated repository classifications without classification write
|
||||
authority
|
||||
- **Documentation** — `README.md`, `INTENT.md`, `SCOPE.md`, pointer to
|
||||
extraction boundary in `the-custodian`
|
||||
|
||||
|
|
@ -82,12 +85,13 @@ python3 -m venv .venv && .venv/bin/pip install -e .
|
|||
|
||||
---
|
||||
|
||||
## What is not possible yet
|
||||
## What remains
|
||||
|
||||
- **Published PyPI package** — consumed via editable path or private index only
|
||||
- **Production durable port store** — T04 ships only the fail-closed ephemeral conformance backend
|
||||
- **Complete State Hub decoupling** — dev-hub routes and models still live in `state-hub`
|
||||
- **ops-hub / fin-hub adoption** — planned; not verified in this repo
|
||||
- **Repository classification navigation** — accepted contract; ingestion,
|
||||
query/MCP, and A5 cutover remain in `HUB-WP-0006`
|
||||
- **fin-hub adoption** — planned; not verified in this repo
|
||||
- **Capability registry entries** — scaffold only (`capabilities: []`); no registered reusable behaviors yet
|
||||
|
||||
---
|
||||
|
|
@ -104,7 +108,7 @@ python3 -m venv .venv && .venv/bin/pip install -e .
|
|||
| Primary consumer | `state-hub` (editable dependency, router/schema import in progress) |
|
||||
| Extraction workplan | `CUST-WP-0025` (custodian domain) |
|
||||
| Target architecture | `SHR-ARCH-IA-0001` + `SHR-ARCH-HUB-0001` |
|
||||
| Runtime workplan | `HUB-WP-0004` |
|
||||
| Runtime workplans | `HUB-WP-0004` and `HUB-WP-0005` finished; `HUB-WP-0006` active |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -140,11 +144,11 @@ hub-core/
|
|||
| Repo | Boundary |
|
||||
|---|---|
|
||||
| `state-hub` | Temporary compatibility source; no new permanent authorities |
|
||||
| `core-hub` | `/api/v2` runtime and route source to absorb, then archive |
|
||||
| `repo-manager` | Owns repository representation, work index, consistency, and governed Git mutations |
|
||||
| `core-hub` | Previous `/api/v2` runtime retained as rollback through stabilization, then archive |
|
||||
| `repo-manager` | Owns repository representation, classification validation/projection, work index, consistency, and governed Git mutations |
|
||||
| `the-custodian` | Owns ecosystem architecture (`hub-ecosystem-architecture.md`) and extraction boundary |
|
||||
| `reuse-surface` | Federation hub for capability indexes; not a runtime dependency of hub-core |
|
||||
| `ops-hub` | Consumer of core-hub `/api/v2`; operations tables stay local |
|
||||
| `ops-hub` | Verified consumer of hub-core `/api/v2`; operations tables stay local |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@
|
|||
| workplan | HUB-WP-0003 | finished | — | workplans/HUB-WP-0003-ecosystem-consolidation-library-lane.md |
|
||||
| workplan | HUB-WP-0004 | finished | — | workplans/HUB-WP-0004-runtime-and-extension-contract.md |
|
||||
| workplan | HUB-WP-0005 | finished | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md |
|
||||
| workplan | HUB-WP-0006 | active | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0001-T01 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md |
|
||||
| task | HUB-WP-0001-T02 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md |
|
||||
| task | HUB-WP-0001-T03 | done | — | workplans/HUB-WP-0001-statehub-bootstrap.md |
|
||||
|
|
@ -37,3 +38,9 @@
|
|||
| task | HUB-WP-0005-T04 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md |
|
||||
| task | HUB-WP-0005-T05 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md |
|
||||
| task | HUB-WP-0005-T06 | done | — | workplans/HUB-WP-0005-core-hub-absorption-execution.md |
|
||||
| task | HUB-WP-0006-T01 | done | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0006-T02 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0006-T03 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0006-T04 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0006-T05 | todo | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
| task | HUB-WP-0006-T06 | wait | — | workplans/HUB-WP-0006-repository-classification-navigation.md |
|
||||
|
|
|
|||
51
docs/adr/ADR-0002-repository-classification-projections.md
Normal file
51
docs/adr/ADR-0002-repository-classification-projections.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# ADR-0002: Consume repository classification as a projection
|
||||
|
||||
**Status:** Accepted
|
||||
**Date:** 2026-08-22
|
||||
**Workplan:** `HUB-WP-0006-T01`
|
||||
**Upstream contract:** `RMGR-CONTRACT-CLASSIFICATION-0001` version 1.0
|
||||
|
||||
## Context
|
||||
|
||||
State Hub's legacy topic spine mixes mutable topic rows with repository
|
||||
classification and navigation. State Hub retirement slice A5 replaces that
|
||||
model. Repo Manager now validates each repository-authoritative
|
||||
`.repo-classification.yaml` and publishes the validated classification in its
|
||||
repository projection.
|
||||
|
||||
Hub-core owns cross-domain projection and navigation, but it must not turn the
|
||||
projection into a second classification authority or recreate a mutable topic
|
||||
table.
|
||||
|
||||
## Decision
|
||||
|
||||
1. Repo Manager's classification contract version 1.0 is accepted without a
|
||||
schema gap. Repo Manager owns validation and publication; the repository
|
||||
file remains authoritative.
|
||||
2. Hub-core consumes only validated Repo Manager projections through a
|
||||
versioned `port.repo` boundary. It does not read, validate, infer, coerce, or
|
||||
write `.repo-classification.yaml` directly.
|
||||
3. Hub-core may aggregate repositories by primary domain, secondary domain,
|
||||
category, capability tag, business stake, and business mechanic for
|
||||
navigation and hub composition. Every derived view carries Repo Manager
|
||||
source identity, repository revision, contract version, and rebuild time.
|
||||
4. A legacy State Hub topic identifier may be retained as a compatibility
|
||||
alias during A5 cutover. It is not a new authority and must have an expiry
|
||||
or residual owner.
|
||||
5. Invalid or unsupported projection versions fail closed and remain visible
|
||||
as diagnostics. Hub-core does not silently reinterpret them.
|
||||
6. State Hub owns the A5 consumer-route switch and rollback flag under
|
||||
`STATE-WP-0079`. Hub-core owns the receiving projection/query and navigation
|
||||
surface; Repo Manager owns the input contract.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Topic navigation becomes rebuildable from repository authority rather than
|
||||
copied from the State Hub `topics` table.
|
||||
- Repository classification changes continue through governed Repo Manager
|
||||
mutation and repository review, never a hub-core write endpoint.
|
||||
- Hub-core needs an explicit Repo Manager client, projection schema, query/MCP
|
||||
surface, provenance checks, and unavailable/version-mismatch behavior before
|
||||
A5 can switch.
|
||||
- Contract evolution is negotiated by version; a canon vocabulary change is
|
||||
not inferred from observed data.
|
||||
118
workplans/HUB-WP-0006-repository-classification-navigation.md
Normal file
118
workplans/HUB-WP-0006-repository-classification-navigation.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
---
|
||||
id: HUB-WP-0006
|
||||
type: workplan
|
||||
title: "Repository classification aggregation and navigation"
|
||||
domain: infotech
|
||||
repo: hub-core
|
||||
status: active
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
created: "2026-08-22"
|
||||
updated: "2026-08-22"
|
||||
parent_project: prj-state-hub-retirement
|
||||
parent_workplan: STATE-WP-0079
|
||||
related:
|
||||
- HUB-WP-0004
|
||||
- HUB-WP-0005
|
||||
- RMGR-WP-0008
|
||||
- RMGR-CONTRACT-CLASSIFICATION-0001
|
||||
---
|
||||
|
||||
# Repository classification aggregation and navigation
|
||||
|
||||
## Goal
|
||||
|
||||
Consume Repo Manager's validated repository-classification projections and
|
||||
provide rebuildable cross-domain aggregation/navigation without creating a
|
||||
second classification authority. Supply the hub-core receiving surface needed
|
||||
for State Hub retirement slices A5 and the repository-facing part of A4/B5.
|
||||
|
||||
## Accept the classification projection boundary
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T01
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Review `RMGR-CONTRACT-CLASSIFICATION-0001` version 1.0 and record the hub-core
|
||||
authority, validation, versioning, provenance, failure, and A5 routing
|
||||
boundary.
|
||||
|
||||
Completed 2026-08-22. `docs/adr/ADR-0002-repository-classification-projections.md`
|
||||
accepts the contract without a schema gap. Repository files remain authority;
|
||||
Repo Manager validates and publishes; hub-core derives navigation only; and
|
||||
STATE-WP-0079 retains the consumer-route switch and rollback flag.
|
||||
|
||||
## Freeze the hub-side projection contract
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Define the input envelope, supported contract versions, stable repository
|
||||
identity, cursor/snapshot semantics, provenance, diagnostics, and the derived
|
||||
domain/category/tag/stake/mechanic views. Define legacy topic aliases as
|
||||
temporary compatibility metadata, not mutable topic authority.
|
||||
|
||||
## Implement Repo Manager ingestion and rebuild
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T03
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Add an injected `port.repo` client, deterministic full rebuild plus incremental
|
||||
upsert/delete behavior, durable PostgreSQL projection tables, content hashes,
|
||||
and dependency-aware readiness. Reject invalid or unsupported projection
|
||||
versions without coercion.
|
||||
|
||||
## Expose projection query and MCP navigation
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T04
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Expose cross-repository query routes and MCP tools for domain, secondary
|
||||
domain, category, capability tag, business stake, and business mechanic.
|
||||
Responses carry source revision and rebuild provenance. No endpoint writes
|
||||
classification authority.
|
||||
|
||||
## Prove conformance and failure behavior
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Add contract fixtures and checks for full rebuild, incremental changes,
|
||||
deletion, duplicate delivery, unsupported versions, Repo Manager outage,
|
||||
stable ordering/cursors, provenance, and absence of classification writes or
|
||||
foreign database access.
|
||||
|
||||
## Hand A5/A4 navigation to State Hub retirement
|
||||
|
||||
```task
|
||||
id: HUB-WP-0006-T06
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
With `STATE-WP-0079`, compare legacy topic/navigation consumers with the new
|
||||
projection, retain explicit aliases where required, run owned consumer smokes,
|
||||
switch A5 through `RM_SLICE_TOPICSPINE`, and record rollback plus residual
|
||||
expiry. Wait on T02-T05 and the State Hub cutover window.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- [x] Repo Manager v1.0 authority and projection contract accepted
|
||||
- [ ] Hub-side projection and compatibility alias contract versioned
|
||||
- [ ] Rebuildable durable ingestion passes provenance and failure checks
|
||||
- [ ] HTTP/MCP navigation reads only the derived projection
|
||||
- [ ] A5/A4 consumer comparison and rollback evidence recorded
|
||||
Loading…
Add table
Add a link
Reference in a new issue