prj-state-hub-retirement/architecture/information-model_v0.1.md

---
id: SHR-ARCH-IA-0001
type: architecture
title: "HelixForge Information Model v0.1"
status: draft-reviewable
version: "0.1"
created: "2026-08-09"
updated: "2026-08-09"
workplan_task: SHR-WP-0001-T03
related:
  - inventory/state-hub-disposition.yaml
  - GOAL.md
  - the-custodian/canon/standards/work-record-types_v0.1.md
  - the-custodian/canon/standards/orthogonal-architecture_v1.0.md
  - the-custodian/docs/hub-ecosystem-event-mapping.md
  - repo-manager/INTENT.md
  - hub-core/INTENT.md
---

# HelixForge Information Model v0.1

## Purpose

Define the **canonical information kinds**, entities, relations, and cross-cutting
rules for the system that replaces State Hub. This document satisfies the
information-model success gate in `GOAL.md` at draft-reviewable fidelity so that
T04 (hub/extension contract), T05 (child workplans), and T06 (migration gates)
can bind to stable names.

It is **project-owned architecture**. Durable promotion targets after review:

| Content | Promote to |
| --- | --- |
| Information kinds + correlation rules | `hub-core` contracts + Custodian canon |
| Work-record kinds (already fleet) | remain `work-record-types_v0.1.md` |
| Repository projection rules | `repo-manager` INTENT/contracts |
| Orthogonal extension mapping | T04 extension architecture |

Machine-readable companion: [`information-model_v0.1.yaml`](information-model_v0.1.yaml).

---

## Governing principles

1. **Authority before projection.** Every durable fact has exactly one
   *authority surface* (usually a repository file, specialized service, or
   identity provider). Indexes and APIs are rebuildable projections.
2. **Kinds stay distinct.** Message transport, durable interaction, work
   commitments, knowledge, and telemetry must not collapse into one table or
   one API noun.
3. **Correlation, not dual-write.** When two kinds describe one human/agent
   action, share a `correlation_id`; do not duplicate the same semantic fact
   into both authorities.
4. **Repositories remain usable offline.** Repo-owned records stay coherent
   without HelixForge; HelixForge may be unavailable without destroying Git
   truth.
5. **Infrastructure is not a hub.** Only domain or orthogonal *aspect*
   compositions are “domain hubs.” Repo Manager, schedulers, and forges are
   functional components.
6. **Incremental migration.** Names here map to State Hub inventory
   capabilities (`inventory/capabilities.yaml`); cutover is per-capability.

---

## Identity layers

| Layer | Form | Primary use |
| --- | --- | --- |
| **Stable UUID** | UUIDv7 preferred | Bookkeeping, FKs, event subjects, idempotency |
| **Canonical name** | Human-readable id (`SHR-WP-0001`, `agt-…`, repo slug) | Agents, UI, commits, prose |
| **Address** | Hub/domain/component-qualified locator | Routing, policy, multi-hub composition |
| **Revision** | Git SHA, content hash, schema version | Provenance and rebuild proofs |

Rules:

- UUIDs are stable across renames; names may change with a recorded alias.
- File-backed work records receive a hub UUID at first index and write it back
  into frontmatter (`state_hub_*_id` → successor field names under new owners).
- External systems keep their native ids; HelixForge stores them as
  `external_ref` with `system` + `id`, never as competing primaries.

---

## Information kinds (normative)

These kinds are **semantic**, not storage engines. Multiple tables or services
may implement one kind; one table must not host multiple kinds without an
explicit tagged-union contract.

### 1. Entity

A durable named thing with identity and lifecycle: repository, domain, agent,
hub, service, person (via identity authority), API consumer, widget.

- **Mutates** by governed command or authority write.
- **Not** an event; changes emit events/signals.

### 2. Relation

A typed edge between entities or records: `depends_on`, `owns`, `indexes`,
`realizes`, `governs`, `observes`, `member_of`, `promoted_from`.

- Relations are first-class when they carry their own lifecycle or policy
  (e.g. workplan dependencies). Otherwise they may be fields on a record.

### 3. Event

An **immutable, append-oriented fact that something happened** at a time.

Subfamilies (do not merge):

| Subfamily | Meaning | Typical home |
| --- | --- | --- |
| **Progress event** | Coordination audit (“agent did X on work Y”) | hub-core projection; today State Hub `progress_events` |
| **Interaction event** | Framework/ops evidence (widget, bootstrap, console) | hub-core runtime (today core-hub `interaction_events`) |
| **Repository change event** | Observed or commanded repo mutation | repo-manager |
| **Domain domain-event** | Business/domain fact stream | specialized service or domain hub |

Events are not requests and not work commitments. They may *reference* work
via subject refs + correlation.

### 4. Signal

A **derived or observed condition** that draws attention: health, drift, DoI,
risk score, WSJF rank, “needs human”, meter zero-usage window.

- Signals are **ephemeral or recomputable** unless explicitly materialized.
- Materialized signals must declare their derivation formula and invalidation.
- Signals never replace authority of the underlying records.

### 5. Message

A **point-to-point or addressed communication unit** between agents/humans/
components (inbox item, reply, notification payload).

- Owned by **hub-core** (cross-entity communication), not Repo Manager.
- Transport (NATS, SSE, HTTP) is infrastructure; the *message* is the durable
  interaction unit when retention is required.
- Messages may cite work and events; they are not tasks.

### 6. Conversation

An **ordered thread of messages** (and optional annotations) with shared
context and participants.

- Conversation identity ≠ message identity.
- Work plans are not conversations; a conversation may *link* to work.

### 7. Request

A **solicitation for action or decision** that awaits acceptance, rejection,
or fulfillment: capability request, HTTP API call (ephemeral), launch request,
credential change request, human intervention flag.

| Longevity | Examples | Treatment |
| --- | --- | --- |
| Ephemeral | Single HTTP request | Telemetry/log only unless elevated |
| Durable request record | Capability request, workplan launch request | Explicit entity + lifecycle |
| Work-shaped request | Intake “please do X” | Prefer **work record** kind `intake` |

Do not store all HTTP traffic as first-class request entities.

### 8. Work

**Commitments to do something**, with owner, status, and completion semantics.
Fleet kinds (closed registry in `work-record-types_v0.1.md`):

| Kind | Role |
| --- | --- |
| `workplan` | Structured, dependency-bearing body of work |
| `task` | Smallest executable unit |
| `intake` | Spark / finding / directive awaiting routing |
| `decision` | Approval package + resolution |
| `engagement` | Scheduled external interaction |
| `register-entry` | Persistent registers (risk, TD, CAP, ADR, …) |

**Authority:** repository files for repo-owned work. Repo Manager indexes and
reconciles; issue-core may project issues externally; activity-core executes
scheduled/event work — none become the origin of file-backed records.

**Residual** is a *role* of another work record after handoff, not a kind.

### 9. Decision (as information kind)

A **resolved or pending choice** with alternatives, rationale, and authority.

- As a **work-record kind**, `decision` is the coordination artefact.
- As an **architecture/product decision**, ADRs and hub decisions are
  `register-entry` / specialized decision stores with promotion to canon.
- Decision *outcomes* update entity state; the decision record remains for
  provenance.

### 10. Knowledge

**Durable claims, definitions, and evidence** intended for reuse: canon,
standards, INTENT/GOAL, research notes, capability descriptions, SBOMs as
declared inventories, citations.

- Knowledge is not a progress event.
- Knowledge authority is usually a repository or canon store.
- Search indexes are projections.

### 11. Telemetry

**Measurements and operational traces** for cost, performance, usage, and
observability: token events, request metrics, legacy-meter buckets, NATS
publish outcomes.

- Telemetry must not be the only copy of a business decision or work status.
- Cost attribution attaches telemetry to subjects (repo, workplan, agent,
  hub) via correlation/subject refs without rewriting those subjects.

---

## Canonical entity catalog

### Core identity & addressing (hub-core)

| Entity | Authority | Projection / index | Notes |
| --- | --- | --- | --- |
| **Domain** | Classification + hub registry policy | hub-core `domains` | Market/user domain spine |
| **Hub** | hub-core registry | hub-core | Domain or orthogonal aspect composition — not every service |
| **Agent** | identity / agent registry | hub-core addressing | Includes coach/lead/director *roles* bound via repo-manager |
| **API consumer** | hub-core | hub-core | Former core-hub consumers/keys (hashed secrets only) |
| **Address** | derived | hub-core | Qualified locator for routing |

### Repository boundary (repo-manager)

| Entity | Authority | Projection / index | Notes |
| --- | --- | --- | --- |
| **Repository** | Git forge + local checkout + `.repo-classification.yaml` | repo-manager registry | Survives offline |
| **Checkout / host path** | operator config | repo-manager | Multi-host paths |
| **Work record file** | Markdown/YAML in repo | repo-manager index | ADR-001 |
| **Classification** | `.repo-classification.yaml` | repo-manager + hub domain views | |
| **Consistency finding** | derived from files vs index | repo-manager | Signal when open |

### Work & governance records (repo-anchored)

| Entity | Authority | Index owner |
| --- | --- | --- |
| Workplan, Task, Intake, Decision, Engagement | repo files | repo-manager |
| Register entries (TD, EP, ADR, risk, CAP, …) | repo files / registers | repo-manager (+ specialized) |
| Contribution artefacts | repo `contrib/` | repo-manager |
| SBOM / lockfile facts | repo lockfiles | repo-manager inventory |
| Repo goal / domain goal | repo or hub policy docs | repo-manager / hub-core |

### Communication (hub-core)

| Entity | Authority | Notes |
| --- | --- | --- |
| Message | hub-core store | Cross-entity inbox |
| Conversation / thread | hub-core | Optional grouping |
| Annotation | hub-core or domain hub | Framework-scoped commentary |

### Catalogs & policy

| Entity | Authority | Owner |
| --- | --- | --- |
| Capability catalog entry | declared capability docs + registry | hub-core (composition); sources in repos |
| Capability request | request record | hub-core workflow |
| TPSC entry | inventory + policy | hub-core projection; compliance authority separate |
| Service catalog entry | ops truth | ops-hub |
| Policy document / scope | policy authority | hub-core integration port |
| Hub capability manifest | domain hub declaration | hub-core |

### Specialized authorities (ports, not swallowed)

| Entity family | Authority |
| --- | --- |
| Identity, credentials | identity / OpenBao |
| Authorization decisions | flex-auth (or successor) |
| Fabric graph | fin-hub |
| Ops runs / schedules | activity-core |
| Issues (non-repo) | issue-core |
| Forge repos/PRs | Forgejo |

---

## Canonical relations

| Relation | From → To | Cardinality | Notes |
| --- | --- | --- | --- |
| `member_of` | repo → domain | N:1 primary | Secondary domains as tags |
| `indexed_by` | work record → repository | N:1 | ADR-001 anchor |
| `depends_on` | workplan → workplan | N:M | First-class |
| `child_of` | task → workplan | N:1 | |
| `promoted_from` | work record → intake | 0..1 | Promotion graph |
| `origin_ref` | residual → finished workplan | 0..1 | Residual role |
| `subject_of` | event/signal/telemetry → entity/record | N:M | Via subject refs |
| `correlates_with` | event ↔ event / message / request | N:M | Shared `correlation_id` |
| `addresses` | message → agent/hub/component | N:M | |
| `realizes` | service/component → capability | N:M | OA Logic dimension |
| `governs` | policy → entity/kind | N:M | |
| `observes` | signal/job → entity | N:M | |
| `projects` | index row → authority URI | 1:1 | Rebuild edge |
| `emits` | component → event type | N:M | Cataloged types |

---

## Cross-cutting rules

### Correlation

Every write path that spans kinds SHOULD accept or mint:

```text
correlation_id: UUIDv7
```

Carry it on:

- progress / interaction / repository events (`detail` / metadata)
- messages that refer to the same action
- telemetry samples for cost of that action
- request records that initiated it

**Do not** dual-write the same semantic fact to two event families. Prefer one
authority event + correlation links.

### Authority

| Question | Answer |
| --- | --- |
| Who may create the fact? | Owner of the authority surface |
| Who may project it? | Index/owner component with read contract |
| Who may mutate repo files? | repo-manager governed commands + human/Git workflows |
| Who may route cross-domain messages? | hub-core only |

Competing authorities are defects. Inventory dispositions that say `move` or
`replace` must name the single post-cutover authority.

### Provenance

Every projected record MUST be reconstructible from:

1. authority URI (repo path + revision, or service record id + version), and/or  
2. append-only event log with schema version.

Minimum provenance fields on projections:

- `source_system`, `source_ref`, `content_hash` or `git_sha`, `indexed_at`,
  `schema_version`.

### Sensitivity

| Class | Examples | Rules |
| --- | --- | --- |
| **Public-internal** | workplan titles, domain slugs | Default for coordination |
| **Operational** | host paths, health | Least privilege on APIs |
| **Personal** | assignee names, human notes | Minimize; respect retention |
| **Secret** | API keys, tokens, credentials | **Never** in events, messages, progress detail, or inventory files — custody services only (hash/prefix ok) |

### Retention

| Kind | Default retention stance |
| --- | --- |
| Work records (files) | Git history — indefinite in repo |
| Progress / interaction events | Long-lived append log; compact only with evidence policy |
| Messages | Policy per conversation class; default retain for audit window |
| Signals (derived) | Recompute; materialized TTL allowed |
| Telemetry (token, metrics) | Roll up; raw samples shorter window |
| Legacy meter | Until retirement evidence accepted, then archive |
| Suggestions (legacy) | Retire; historical rows archive-only |

Exact TTLs are operational policy (T06 gates); this model only forbids treating
telemetry TTL as deletion of work authority.

### Cost attribution

Token and compute telemetry SHOULD attach:

- `subject_refs`: `{repo?, workplan_id?, task_id?, agent?, hub?, session_id?}`
- `correlation_id` when part of a larger action
- `provider` / `model` / `units` without secrets

Cost aggregates are **signals/read models**, not work status.

### Transformation rules

| From | To | Allowed transformation |
| --- | --- | --- |
| Intake | workplan / task / decision / engagement | **Promotion** (first-class); sets back-links |
| File work record | index row | **Reconcile** (idempotent upsert) |
| Index row | file | **Writeback** only via governed command |
| Event | signal | **Derive** (pure function + window) |
| Event | knowledge | **Only** by explicit human/agent curation, not auto-promote |
| Message | task | **Only** via intake/work creation, not implicit |
| Progress event | interaction event | **Not** automatic; optional correlation |
| HTTP request | request entity | **Only** if elevated to durable request kind |
| Suggestion (legacy) | intake | One-way migration; then retire suggestions |

**Forbidden:** silent authority flip (DB becomes origin of repo-owned work);
auto-creating workplans from telemetry; storing secrets in event payloads.

---

## Mapping from State Hub inventory

Selected capability → information kind → target owner (from SHR-INV-0001):

| Inventory capability | Kind(s) | Target owner |
| --- | --- | --- |
| `work-records-*` | work, decision, relation | repo-manager |
| `repository-registry`, `repo-consistency` | entity, event, signal | repo-manager |
| `agent-messaging` | message, conversation | hub-core |
| `progress-telemetry` | event (progress) | hub-core |
| `token-telemetry` | telemetry | hub-core |
| `state-projections`, `hub-projection-ui` | signal + read model | hub-core |
| `capability-catalog` | knowledge + request | hub-core |
| `service-catalog` | entity/knowledge | ops-hub |
| `fabric-graph` | knowledge + relation | fin-hub |
| `task-flow-engine`, `workplan-execution-queue` | request + work execution | activity-core |
| `suggestion-backlog`, `work-records-workplan-legacy` | — | archive / retire |
| `legacy-meter` | telemetry/signal | state-hub-until-cutover → retire |

Full item-level map remains in `inventory/state-hub-disposition.yaml`.

---

## Orthogonal Architecture alignment (preview for T04)

| OA concept | Information-model binding |
| --- | --- |
| Capability (stable intent) | Capability catalog + manifests (knowledge/entity) |
| Service realization | Specialized services + hub components (entity) |
| Plane (control vs workload) | Governed commands vs runtime execution |
| Quality dimensions | sensitivity, retention, provenance rules above |
| Relations | Canonical relation table |
| Intelligence | Agents as entities; autonomy lane on work records |

The **extension contract** (how domain hubs publish entities/events without
forking the core model) is specified in T04; this document freezes the
vocabulary that contract must use.

---

## Anti-patterns

1. One “Event” table for progress, interaction, telemetry, and messages.  
2. Calling Repo Manager a “hub.”  
3. Hub DB as origin of workplans/tasks.  
4. Using messages as the only store of commitments.  
5. Promoting every signal into a task.  
6. Embedding secrets in `detail` / `metadata_json`.  
7. Dual-writing the same fact to progress and interaction “to be safe.”  
8. Growing State Hub with new permanent authorities during migration.

---

## Open questions (for T04 / human review)

1. **Topic entity** — retain as first-class or fully replace by domain +
   classification tags? Inventory currently `replace`.  
2. **Conversation persistence** — always durable vs ephemeral threads with
   selective retention.  
3. **Issue-core boundary** — which non-repo work remains outside work-record
   files.  
4. **Single progress+interaction envelope** — shared envelope schema with
   kind discriminator vs separate stores forever (current: separate +
   correlation).  
5. **Knowledge search** — dedicated service vs hub projection only.

---

## Acceptance for T03

- [x] Canonical information kinds named with distinct semantics.  
- [x] Core entities and relations listed with authority vs projection.  
- [x] Correlation, authority, provenance, sensitivity, retention, cost,
      transformation rules specified.  
- [x] Explicit map from State Hub inventory capabilities to kinds/owners.  
- [x] Machine-readable companion YAML for tooling and T04/T05 binding.  
- [ ] Human review before promotion into fleet canon / hub-core contracts
      (expected residual; does not block T04 draft).

## Related

- `inventory/README.md` — disposition inventory  
- `architecture/hub-extension-architecture_v0.1.md` — T04 hub/extension contract  
- `work-record-types_v0.1.md` — closed work-record kind registry  
- `project-repository-flavor_v0.1.md` — `prj-` / GOAL.md  
- ADR-001, ADR-005 — file authority and project repos