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/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