# helixforge.hub-extension contract outline v0.1
# Descriptive machine-readable form for T04/T05. Runtime JSON Schemas ship in hub-core.

contract_id: helixforge.hub-extension
contract_version: "0.1.0"
status: draft-reviewable
created: "2026-08-09"
updated: "2026-08-09"
workplan_task: SHR-WP-0001-T04
document: architecture/hub-extension-architecture_v0.1.md
information_model_ref: SHR-ARCH-IA-0001

taxonomy:
  hub_core:
    role: framework_and_runtime
    owns:
      - identity_and_addressing
      - messaging_and_conversations
      - progress_and_interaction_events
      - extension_registry
      - policy_integration_ports
      - telemetry_intake
      - compatibility_surface
      - sdk_and_contracts
    does_not_own:
      - git_file_authority
      - domain_business_data
      - secrets
      - authorization_decisions
      - schedule_execution
  domain_hub:
    hub_kind: [domain, aspect]
    must:
      - hub_descriptor
      - reuse_surface_capability_id
      - versioned_manifest
      - health_endpoints
      - own_domain_data
    must_not:
      - own_other_repos_file_authority
      - bypass_policy_ports
      - store_secrets_in_manifests_or_events
      - dual_write_work_records
  functional_component:
    examples: [repo-manager, activity-core, issue-core, ops-bridge]
    rule: not_a_hub_unless_domain_or_aspect
  authoritative_service:
    examples: [identity, flex-auth, openbao, forgejo, fabric-engine]
    rule: retain_execution_and_data_authority
  projection:
    rule: rebuildable_from_authority
  adapter:
    rule: versioned_boundary_no_schema_leak

oa_binding:
  Stack: platform_substrate_not_hubs
  Logic.L1: reuse_surface_capabilities
  Logic.L2: deployed_services
  Logic.L3: extension_registry_and_manifests
  Logic.L4: solutions_and_operator_experiences
  Plane.P1: workload_runtimes
  Plane.P2: hub_core_registry_policy_repo_commands
  Plane.P3: cli_mcp_console
  Quality: ia_cross_cutting_rules
  Capability.contract: this_contract
  Intelligence: agents_via_control_plane

hub_descriptor_fields:
  required:
    - hub_slug
    - display_name
    - domain
    - hub_kind
    - status
    - reuse_surface_id
    - contract_version_min
    - contract_version_max
  optional:
    - vsm_system
    - vsm_function
    - description
  hub_kind_enum: [domain, aspect]
  status_enum: [draft, active, deprecated, retired]

manifest_fields:
  required:
    - manifest_version
    - reuse_surface_id
    - provides
    - consumes
    - events_emitted
    - events_consumed
    - schema_version
  optional:
    - widgets
    - endpoints
    - policy_scopes
    - operator_surfaces
  rules:
    - no_secrets_in_body
    - endpoints_are_discovery_keys_or_non_secret_urls
    - event_types_must_be_cataloged

ports:
  - id: port.registry
    direction: in
    purpose: register_and_activate_hubs_and_manifests
  - id: port.addressing
    direction: out
    purpose: resolve_agents_hubs_domains
  - id: port.messaging
    direction: bidirectional
    purpose: messages_and_conversations
  - id: port.events.progress
    direction: in
    purpose: append_progress_events
  - id: port.events.interaction
    direction: in
    purpose: append_interaction_events
  - id: port.projection.query
    direction: out
    purpose: orientation_and_registry_reads
  - id: port.repo
    direction: out
    purpose: repository_addressing_via_repo_manager
  - id: port.work
    direction: out
    purpose: work_record_index_queries
  - id: port.policy
    direction: out
    purpose: authorization_and_policy_evaluation
  - id: port.telemetry
    direction: in
    purpose: cost_and_usage_samples
  - id: port.schedule
    direction: out
    purpose: activity_core_execution_requests

event_rules:
  families: [progress, interaction, repository_change, domain]
  cataloged_types: required
  correlation_id: UUIDv7
  dual_write_same_fact: forbidden
  secrets_in_payload: forbidden

projections:
  - id: hub_registry
    served_by: hub-core
    rebuild_from: [hub_descriptors, manifests]
  - id: domain_summary
    served_by: hub-core
    rebuild_from: [work_index, messages, progress_events]
  - id: repo_health
    served_by: repo-manager
    rebuild_from: [repository_files, consistency_findings]
  - id: capability_matrix
    served_by: hub-core
    rebuild_from: [reuse_surface_registry, catalog, manifests]
  - id: ops_evidence
    served_by: hub-core
    rebuild_from: [interaction_events, widgets]

adapters:
  - id: state_hub_compatibility
    lifetime: until_retirement_gates
  - id: core_hub_api_v2
    lifetime: until_single_runtime
  - id: repo_manager_port
    lifetime: permanent
  - id: activity_core_sink
    lifetime: permanent
  - id: identity_auth_ports
    lifetime: permanent

conformance:
  tier_0_descriptive:
    - architecture_docs
    - contract_yaml
    - inventory_port_map
  tier_1_contract_artefacts:
    - hub_descriptor_schema
    - manifest_schema
    - event_type_catalog_schema
    - port_openapi_fragments
    - sample_hub_fixture
    - compatibility_matrix
  tier_2_domain_hub:
    - C1_schema_validate
    - C2_reuse_surface_resolve
    - C3_health_probe
    - C4_activate_idempotent
    - C5_events_validate
    - C6_no_secrets
    - C7_ports_only
    - C8_correlation_propagation
    - C9_fail_closed_readiness
    - C10_version_negotiation
  tier_3_framework:
    - F1_registry_audit
    - F2_event_family_separation
    - F3_projection_rebuild
    - F4_api_v2_consumer_smokes
    - F5_mcp_bound_to_projections
    - F6_policy_fail_closed
    - F7_telemetry_secret_heuristic
    - F8_metadata_isolation
  tier_4_migration:
    - M1_disposition_has_port
    - M2_compat_feature_flags
    - M3_rowcount_provenance
    - M4_zero_state_hub_traffic_window
    - M5_rollback_exercised

inventory_port_map:
  # capability id -> primary port or owner component
  - capability: agent-messaging
    port: port.messaging
    owner: hub-core
  - capability: progress-telemetry
    port: port.events.progress
    owner: hub-core
  - capability: token-telemetry
    port: port.telemetry
    owner: hub-core
  - capability: state-projections
    port: port.projection.query
    owner: hub-core
  - capability: cross-domain-registry
    port: port.addressing
    owner: hub-core
  - capability: capability-catalog
    port: port.registry
    owner: hub-core
  - capability: policy-integration
    port: port.policy
    owner: hub-core
  - capability: repository-registry
    port: port.repo
    owner: repo-manager
  - capability: work-records-workplan
    port: port.work
    owner: repo-manager
  - capability: work-records-task
    port: port.work
    owner: repo-manager
  - capability: repo-consistency
    port: port.repo
    owner: repo-manager
  - capability: workplan-execution-queue
    port: port.schedule
    owner: activity-core
  - capability: task-flow-engine
    port: port.schedule
    owner: activity-core
  - capability: service-catalog
    owner: ops-hub
    notes: domain_hub_data_plus_registry_manifest
  - capability: fabric-graph
    owner: railiance-fabric
    notes: specialized_authority_fin_hub_accountable_hub_projection_deferred

migration_stack_map:
  hub-core_library: grows_into_sdk_of_surviving_runtime
  core-hub_runtime: absorbed_then_archived
  state-hub_work_and_consistency: repo-manager
  state-hub_messages_progress_domains_catalogs: hub-core
  state-hub_dashboard: projection_ui_clients
  state-hub_suggestions_and_workstream_aliases: retire
  ops-hub: domain_or_aspect_hub
  fin-hub: domain_hub
  activity-core: functional_component

child_streams_suggested:
  - hub-core-runtime-consolidation
  - repo-manager-extraction
  - extension-conformance-suite
  - compatibility-adapters
  - domain-hub-manifest-alignment
  - state-hub-retirement-gates

open_questions:
  - single_deployable_vs_library_plus_host
  - widget_model_generalization
  - multi_tenant_isolation
  - file_backed_manifests_vs_db_only
  - mcp_gateway_vs_per_component