# 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: railiance-fabric
  - 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: railiance-fabric
  - 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