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

id	type	title	status	version	created	updated	workplan_task	related
SHR-ARCH-IA-0001	architecture	HelixForge Information Model v0.1	draft-reviewable	0.1	2026-08-09	2026-08-09	SHR-WP-0001-T03	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.

---

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:

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

• Canonical information kinds named with distinct semantics.
• Core entities and relations listed with authority vs projection.
• Correlation, authority, provenance, sensitivity, retention, cost, transformation rules specified.
• Explicit map from State Hub inventory capabilities to kinds/owners.
• 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