tegwick
18121700f7
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
286 lines
7.7 KiB
YAML
286 lines
7.7 KiB
YAML
# 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
|