From 7d5ba4d93387418f31313e5652c4a4eb0d9cf37e Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 9 Aug 2026 17:44:57 +0200 Subject: [PATCH] docs(SHR-WP-0001): complete T03 HelixForge information model Add draft-reviewable information architecture (SHR-ARCH-IA-0001): eleven kinds, entity/relation catalog, cross-cutting rules, and inventory map. --- architecture/README.md | 12 + architecture/information-model_v0.1.md | 482 +++++++++++++++++++++++ architecture/information-model_v0.1.yaml | 346 ++++++++++++++++ workplans/SHR-WP-0001-foundation.md | 8 +- 4 files changed, 847 insertions(+), 1 deletion(-) create mode 100644 architecture/README.md create mode 100644 architecture/information-model_v0.1.md create mode 100644 architecture/information-model_v0.1.yaml diff --git a/architecture/README.md b/architecture/README.md new file mode 100644 index 0000000..e3ec063 --- /dev/null +++ b/architecture/README.md @@ -0,0 +1,12 @@ +# Architecture (project-owned) + +Cross-repository architecture for State Hub retirement. Implementation stays +in child repos; durable promotion targets are noted in each document. + +| Doc | Task | Status | +| --- | --- | --- | +| [information-model_v0.1.md](information-model_v0.1.md) | SHR-WP-0001-T03 | draft-reviewable | +| [information-model_v0.1.yaml](information-model_v0.1.yaml) | SHR-WP-0001-T03 | companion | +| hub-extension-architecture (T04) | SHR-WP-0001-T04 | pending | + +Related: [`../inventory/`](../inventory/) disposition inventory, [`../GOAL.md`](../GOAL.md). diff --git a/architecture/information-model_v0.1.md b/architecture/information-model_v0.1.md new file mode 100644 index 0000000..39f9e51 --- /dev/null +++ b/architecture/information-model_v0.1.md @@ -0,0 +1,482 @@ +--- +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 (successor doc) +- `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 diff --git a/architecture/information-model_v0.1.yaml b/architecture/information-model_v0.1.yaml new file mode 100644 index 0000000..66d214d --- /dev/null +++ b/architecture/information-model_v0.1.yaml @@ -0,0 +1,346 @@ +# SHR-ARCH-IA-0001 — machine-readable companion to information-model_v0.1.md +# Schema is descriptive for T03/T04 tooling; not yet a runtime validation schema. + +id: SHR-ARCH-IA-0001 +title: HelixForge Information Model +version: "0.1" +status: draft-reviewable +created: "2026-08-09" +updated: "2026-08-09" +workplan_task: SHR-WP-0001-T03 +document: architecture/information-model_v0.1.md + +identity_layers: + - id: uuid + form: UUIDv7 + primary_for: [bookkeeping, foreign_keys, idempotency, event_subjects] + - id: canonical_name + form: human-readable id + primary_for: [agents, ui, commits, prose] + - id: address + form: hub/domain/component-qualified locator + primary_for: [routing, policy, multi_hub] + - id: revision + form: git_sha | content_hash | schema_version + primary_for: [provenance, rebuild_proofs] + +information_kinds: + - id: entity + summary: Durable named thing with identity and lifecycle + mutable: true + append_only: false + - id: relation + summary: Typed edge between entities or records + mutable: true + append_only: false + - id: event + summary: Immutable fact that something happened + mutable: false + append_only: true + subfamilies: + - id: progress_event + owner: hub-core + legacy: state-hub.progress_events + - id: interaction_event + owner: hub-core + legacy: core-hub.interaction_events + - id: repository_change_event + owner: repo-manager + - id: domain_event + owner: specialized-or-domain-hub + - id: signal + summary: Derived or observed attention condition + mutable: true + append_only: false + recomputable: true + - id: message + summary: Addressed communication unit + owner: hub-core + mutable: false + append_only: true + - id: conversation + summary: Ordered thread of messages with shared context + owner: hub-core + - id: request + summary: Solicitation awaiting accept/reject/fulfill + longevity: [ephemeral, durable_record, work_shaped] + - id: work + summary: Commitment to do something with owner and completion semantics + owner_index: repo-manager + authority: repository-files + closed_kinds_ref: the-custodian/canon/standards/work-record-types_v0.1.md + work_record_kinds: + - workplan + - task + - intake + - decision + - engagement + - register-entry + - id: decision + summary: Choice with alternatives, rationale, and authority + notes: Overlaps work-record kind decision and ADR/register forms + - id: knowledge + summary: Durable reusable claims, definitions, evidence + authority: repository-or-canon + - id: telemetry + summary: Measurements and operational traces + owner: hub-core + must_not_replace: [work, decision, knowledge] + +entities: + - id: domain + kind: entity + authority: classification-and-hub-policy + projection_owner: hub-core + - id: hub + kind: entity + authority: hub-core-registry + projection_owner: hub-core + notes: Domain or orthogonal aspect composition only + - id: agent + kind: entity + authority: identity-agent-registry + projection_owner: hub-core + - id: api_consumer + kind: entity + authority: hub-core + projection_owner: hub-core + - id: repository + kind: entity + authority: git-forge-and-repo-files + projection_owner: repo-manager + - id: checkout + kind: entity + authority: operator-config + projection_owner: repo-manager + - id: work_record + kind: work + authority: repository-files + projection_owner: repo-manager + - id: classification + kind: knowledge + authority: .repo-classification.yaml + projection_owner: repo-manager + - id: message + kind: message + authority: hub-core + projection_owner: hub-core + - id: conversation + kind: conversation + authority: hub-core + projection_owner: hub-core + - id: progress_event + kind: event + subfamily: progress_event + authority: hub-core + - id: interaction_event + kind: event + subfamily: interaction_event + authority: hub-core + - id: capability_entry + kind: knowledge + projection_owner: hub-core + - id: capability_request + kind: request + projection_owner: hub-core + - id: service_catalog_entry + kind: entity + authority: ops-hub + - id: tpsc_entry + kind: knowledge + projection_owner: hub-core + - id: policy_scope + kind: knowledge + projection_owner: hub-core + authority: policy-service + - id: fabric_node + kind: entity + authority: fin-hub + - id: ops_run + kind: entity + authority: activity-core + - id: token_event + kind: telemetry + projection_owner: hub-core + +relations: + - id: member_of + from: repository + to: domain + - id: indexed_by + from: work_record + to: repository + - id: depends_on + from: workplan + to: workplan + - id: child_of + from: task + to: workplan + - id: promoted_from + from: work_record + to: intake + - id: origin_ref + from: residual_work_record + to: workplan + - id: subject_of + from: [event, signal, telemetry] + to: [entity, work_record] + - id: correlates_with + from: [event, message, request, telemetry] + to: [event, message, request, telemetry] + via: correlation_id + - id: addresses + from: message + to: [agent, hub, component] + - id: realizes + from: component + to: capability + - id: governs + from: policy + to: [entity, kind] + - id: observes + from: [signal, job] + to: entity + - id: projects + from: index_row + to: authority_uri + - id: emits + from: component + to: event_type + +cross_cutting: + correlation: + field: correlation_id + type: UUIDv7 + required_when: action_spans_multiple_kinds + dual_write: forbidden + authority: + rule: single_authority_surface_per_fact + repo_owned_records: repository-files + cross_entity_communication: hub-core + governed_repo_mutation: repo-manager + provenance_fields: + - source_system + - source_ref + - content_hash_or_git_sha + - indexed_at + - schema_version + sensitivity_classes: + - public_internal + - operational + - personal + - secret + secret_rule: never_in_events_messages_progress_inventory + retention_stance: + work_record_files: git_history + progress_and_interaction_events: long_lived_append + messages: policy_per_class + signals: recompute_or_ttl + telemetry: rollup_raw_shorter + legacy_meter: until_retirement_evidence + suggestions: archive_only + cost_attribution_fields: + - subject_refs + - correlation_id + - provider + - model + - units + transformations: + - from: intake + to: [workplan, task, decision, engagement] + type: promotion + - from: work_record_file + to: index_row + type: reconcile + - from: index_row + to: work_record_file + type: writeback_governed + - from: event + to: signal + type: derive + - from: event + to: knowledge + type: explicit_curation_only + - from: message + to: task + type: via_intake_only + - from: suggestion + to: intake + type: one_way_migration + forbidden: + - db_origin_for_repo_owned_work + - auto_work_from_telemetry + - secrets_in_event_payloads + - dual_write_same_fact_to_progress_and_interaction + - new_permanent_authorities_in_state_hub + +inventory_capability_map: + - capability: work-records-workplan + kinds: [work, relation] + owner: repo-manager + - capability: work-records-task + kinds: [work] + owner: repo-manager + - capability: work-records-intake + kinds: [work, request] + owner: repo-manager + - capability: work-records-decision + kinds: [work, decision] + owner: repo-manager + - capability: repository-registry + kinds: [entity, event] + owner: repo-manager + - capability: repo-consistency + kinds: [signal, event] + owner: repo-manager + - capability: agent-messaging + kinds: [message, conversation] + owner: hub-core + - capability: progress-telemetry + kinds: [event] + owner: hub-core + - capability: token-telemetry + kinds: [telemetry] + owner: hub-core + - capability: state-projections + kinds: [signal] + owner: hub-core + - capability: capability-catalog + kinds: [knowledge, request] + owner: hub-core + - capability: service-catalog + kinds: [entity, knowledge] + owner: ops-hub + - capability: fabric-graph + kinds: [entity, relation, knowledge] + owner: fin-hub + - capability: task-flow-engine + kinds: [request, work] + owner: activity-core + - capability: workplan-execution-queue + kinds: [request] + owner: activity-core + - capability: suggestion-backlog + kinds: [] + owner: archive + disposition: retire + - capability: work-records-workplan-legacy + kinds: [] + owner: archive + disposition: retire + - capability: legacy-meter + kinds: [telemetry, signal] + owner: state-hub-until-cutover + disposition: retire + +open_questions: + - id: topic-entity + summary: Retain topics or replace with domain + classification + - id: conversation-retention + summary: Always durable vs selective retention + - id: issue-core-boundary + summary: Non-repo work outside file-backed work records + - id: event-envelope + summary: Shared envelope with discriminator vs separate stores + - id: knowledge-search + summary: Dedicated search service vs hub projection only diff --git a/workplans/SHR-WP-0001-foundation.md b/workplans/SHR-WP-0001-foundation.md index 67c5827..5c53a63 100644 --- a/workplans/SHR-WP-0001-foundation.md +++ b/workplans/SHR-WP-0001-foundation.md @@ -68,7 +68,7 @@ revisable via T03/T04/T05. Baseline orientation counts from live summary ```task id: SHR-WP-0001-T03 -status: todo +status: done priority: high state_hub_task_id: "65e522c7-2550-4187-a308-a23a2bae7615" ``` @@ -78,6 +78,12 @@ signals, messages, conversations, requests, work, decisions, knowledge, and telemetry. Specify correlation, authority, provenance, sensitivity, retention, cost attribution, and transformation rules. +**Result (2026-08-09):** Draft-reviewable model `SHR-ARCH-IA-0001` at +`architecture/information-model_v0.1.md` + YAML companion. Eleven information +kinds; entity/relation catalog with authority vs projection; cross-cutting +rules; map from SHR-INV-0001 capabilities. Residual: human review before fleet +canon/hub-core promotion; open questions listed for T04. + ## Define the hub and extension architecture ```task