docs(SHR-WP-0001): complete T04 hub-extension architecture
Add draft-reviewable hub-core and domain-extension contract (helixforge.hub-extension v0.1): role taxonomy, ports, manifests, conformance tiers, and migration stack map.
This commit is contained in:
parent
c4ce7173d5
commit
3e3e4c9f0b
5 changed files with 727 additions and 3 deletions
286
architecture/hub-extension-contract_v0.1.yaml
Normal file
286
architecture/hub-extension-contract_v0.1.yaml
Normal file
|
|
@ -0,0 +1,286 @@
|
|||
# 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: fin-hub
|
||||
notes: authoritative_specialized_with_hub_projection_optional
|
||||
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue