feat: add hub runtime and extension contract

hub_core/contracts/__init__.py

@@ -0,0 +1,16 @@
+"""Packaged HelixForge hub contract artifacts."""
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+CONTRACT_ID = "helixforge.hub-extension"
+CONTRACT_VERSION = "0.1.0"
+
+
+def extension_contract_root() -> Traversable:
+    """Return the packaged root for the current hub-extension contract."""
+
+    return files("hub_core.contracts.helixforge_hub_extension.v0_1_0")
+
+
+__all__ = ["CONTRACT_ID", "CONTRACT_VERSION", "extension_contract_root"]

hub_core/contracts/helixforge_hub_extension/__init__.py

@@ -0,0 +1 @@
+"""Versioned ``helixforge.hub-extension`` contract packages."""

hub_core/contracts/helixforge_hub_extension/v0_1_0/README.md

@@ -0,0 +1,26 @@
+# helixforge.hub-extension 0.1.0
+
+Tier 1 contract artifacts implementing `SHR-ARCH-HUB-0001` and
+`SHR-ARCH-IA-0001`:
+
+- `schemas/hub-descriptor.schema.json` — hub identity and version negotiation;
+- `schemas/hub-manifest.schema.json` — provided/consumed capabilities, ports,
+  events, endpoints, policies, and operator surfaces;
+- `schemas/event-type-catalog.schema.json` — catalog entries with event family,
+  ownership, sensitivity, and payload schema references;
+- `openapi/ports.openapi.json` — OpenAPI 3.1 fragments for every v0.1 named port;
+- `catalogs/event-types.json` — initial progress and interaction event catalog;
+- `fixtures/ops-hub.extension.json` — non-secret domain/aspect hub package;
+- `fixtures/projection-rebuild.json` — deterministic authority inputs and
+  expected rebuild sources for framework projections;
+- `compatibility-matrix.json` — version and Core Hub migration compatibility.
+
+The package is descriptive and versioned. Runtime conformance belongs to Tier
+2/3 tests exposed through `hub_core.conformance` and `hub-core conformance`.
+Contract changes are additive within a minor line; breaking field,
+enum, or semantic changes require a new major version and a dual-run window.
+
+Manifest and event payloads must never contain credential material. Endpoint
+entries carry only discovery keys or non-secret URLs. Authorization decisions,
+repository work authority, secrets, and schedules remain behind their assigned
+ports.

hub_core/contracts/helixforge_hub_extension/v0_1_0/__init__.py

@@ -0,0 +1 @@
+"""Contract artifacts for ``helixforge.hub-extension`` version 0.1.0."""

hub_core/contracts/helixforge_hub_extension/v0_1_0/catalogs/event-types.json

@@ -0,0 +1,53 @@
+{
+  "catalog_version": "0.1.0",
+  "event_types": [
+    {
+      "type": "hub.progress.recorded",
+      "display_name": "Hub Progress Recorded",
+      "description": "Coordination audit evidence linked to work or another governed subject.",
+      "family": "progress",
+      "schema_version": "0.1.0",
+      "owner": "hub-core",
+      "sensitivity": "operational",
+      "payload_schema_ref": "urn:helixforge:event:hub.progress.recorded:0.1.0",
+      "correlation_required": true,
+      "retention_class": "audit"
+    },
+    {
+      "type": "hub.interaction.recorded",
+      "display_name": "Hub Interaction Recorded",
+      "description": "Framework or operator interaction evidence distinct from coordination progress.",
+      "family": "interaction",
+      "schema_version": "0.1.0",
+      "owner": "hub-core",
+      "sensitivity": "operational",
+      "payload_schema_ref": "urn:helixforge:event:hub.interaction.recorded:0.1.0",
+      "correlation_required": true,
+      "retention_class": "audit"
+    },
+    {
+      "type": "repository.change.observed",
+      "display_name": "Repository Change Observed",
+      "description": "A repository revision or governed mutation observed by repo-manager.",
+      "family": "repository_change",
+      "schema_version": "0.1.0",
+      "owner": "repo-manager",
+      "sensitivity": "operational",
+      "payload_schema_ref": "urn:helixforge:event:repository.change.observed:0.1.0",
+      "correlation_required": false,
+      "retention_class": "audit"
+    },
+    {
+      "type": "ops.endpoint.verified",
+      "display_name": "Operations Endpoint Verified",
+      "description": "A domain-owned operations endpoint passed its declared verification.",
+      "family": "domain",
+      "schema_version": "0.1.0",
+      "owner": "ops-hub",
+      "sensitivity": "operational",
+      "payload_schema_ref": "urn:helixforge:event:ops.endpoint.verified:0.1.0",
+      "correlation_required": true,
+      "retention_class": "domain_policy"
+    }
+  ]
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/compatibility-matrix.json

@@ -0,0 +1,33 @@
+{
+  "contract_id": "helixforge.hub-extension",
+  "current_version": "0.1.0",
+  "versions": [
+    {
+      "version": "0.1.0",
+      "status": "current",
+      "compatible_min": "0.1.0",
+      "compatible_max": "0.1.0",
+      "breaking": false
+    }
+  ],
+  "migration_adapters": [
+    {
+      "source": "core-hub.hub-manifest",
+      "source_version": "0.1",
+      "target_version": "0.1.0",
+      "status": "required-during-dual-run",
+      "mapping": {
+        "hub_slug": "descriptor.hub_slug",
+        "manifest_version": "manifest.manifest_version",
+        "capabilities": "manifest.provides",
+        "endpoints": "manifest.endpoints"
+      },
+      "notes": "The adapter must supply descriptor identity/version fields and explicit consumes/event lists; it must not infer credentials from endpoint metadata."
+    }
+  ],
+  "change_policy": {
+    "patch": "Clarifications and compatible constraint corrections only.",
+    "minor": "Additive optional fields, ports, event types, and enum values.",
+    "major": "Removed or renamed fields, narrowed enums, changed authority semantics, or incompatible port behavior; requires a dual-run window."
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/fixtures/ops-hub.extension.json

@@ -0,0 +1,72 @@
+{
+  "descriptor": {
+    "contract_id": "helixforge.hub-extension",
+    "contract_version": "0.1.0",
+    "hub_slug": "ops-hub",
+    "display_name": "Operations Hub",
+    "description": "Operations aspect hub fixture for contract and composition tests.",
+    "domain": "operations",
+    "hub_kind": "aspect",
+    "status": "active",
+    "reuse_surface_id": "capability.operations.ops-hub",
+    "contract_version_min": "0.1.0",
+    "contract_version_max": "0.1.0",
+    "vsm_system": "operations",
+    "vsm_function": "coordination"
+  },
+  "manifest": {
+    "manifest_version": "0.1.0",
+    "schema_version": "0.1.0",
+    "reuse_surface_id": "capability.operations.ops-hub",
+    "provides": [
+      "capability.operations.ops-hub",
+      "capability.operations.service-catalog"
+    ],
+    "consumes": [
+      "port.registry",
+      "port.messaging",
+      "port.events.interaction",
+      "port.projection.query",
+      "port.policy"
+    ],
+    "events_emitted": [
+      "ops.endpoint.verified"
+    ],
+    "events_consumed": [
+      "hub.progress.recorded"
+    ],
+    "endpoints": [
+      {
+        "id": "api",
+        "discovery_key": "service.ops-hub.http"
+      },
+      {
+        "id": "docs",
+        "url": "https://ops-hub.example.invalid/docs"
+      }
+    ],
+    "policy_scopes": [
+      "ops.catalog.read",
+      "ops.evidence.write"
+    ],
+    "widgets": [
+      {
+        "id": "ops-overview",
+        "kind": "widget",
+        "description": "Non-secret operations overview surface."
+      }
+    ],
+    "operator_surfaces": [
+      {
+        "id": "ops-console",
+        "kind": "console",
+        "description": "Operator-facing operations console."
+      },
+      {
+        "id": "ops-mcp",
+        "kind": "mcp",
+        "description": "Policy-bound operations MCP surface."
+      }
+    ]
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/fixtures/projection-rebuild.json

@@ -0,0 +1,37 @@
+{
+  "contract_version": "0.1.0",
+  "extension_fixture": "ops-hub.extension.json",
+  "authority": {
+    "messages": [
+      {
+        "schema_version": "0.1.0",
+        "from_address": "hub:ops-hub",
+        "to_addresses": ["agent:conformance"],
+        "body": "Projection rebuild conformance fixture.",
+        "subject_refs": {"hub": "ops-hub", "fixture": "projection-rebuild"}
+      }
+    ],
+    "progress_events": [
+      {
+        "schema_version": "0.1.0",
+        "event_type": "hub.progress.recorded",
+        "subject_refs": {"hub": "ops-hub", "fixture": "projection-rebuild"},
+        "payload": {"result": "fixture-progress"}
+      }
+    ],
+    "interaction_events": [
+      {
+        "schema_version": "0.1.0",
+        "event_type": "hub.interaction.recorded",
+        "subject_refs": {"hub": "ops-hub", "fixture": "projection-rebuild"},
+        "payload": {"result": "fixture-interaction"}
+      }
+    ]
+  },
+  "expected_projections": {
+    "hub_registry": {"rebuild_from": ["hub_descriptors", "hub_manifests"]},
+    "messages": {"rebuild_from": ["messages"]},
+    "progress_events": {"rebuild_from": ["progress_events"]},
+    "interaction_events": {"rebuild_from": ["interaction_events"]}
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/openapi/ports.openapi.json

@@ -0,0 +1,669 @@
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  "info": {
+    "title": "HelixForge Hub Extension Ports",
+    "version": "0.1.0",
+    "description": "Implementation-neutral HTTP fragments for helixforge.hub-extension named ports. Implementations may mount compatibility aliases while these operations remain the stable contract."
+  },
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/ports/registry/registrations": {
+      "post": {
+        "operationId": "registerHubExtension",
+        "summary": "Register or idempotently update a hub descriptor and manifest",
+        "tags": ["registry"],
+        "x-port-id": "port.registry",
+        "x-direction": "in",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CorrelationHeader"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RegistryRegistration"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          }
+        }
+      }
+    },
+    "/ports/addressing/resolve/{address}": {
+      "get": {
+        "operationId": "resolveAddress",
+        "summary": "Resolve a qualified agent, hub, domain, or component address",
+        "tags": ["addressing"],
+        "x-port-id": "port.addressing",
+        "x-direction": "out",
+        "parameters": [
+          {
+            "name": "address",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 240
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Record"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/ports/messaging/messages": {
+      "get": {
+        "operationId": "listAddressedMessages",
+        "summary": "Read retained messages addressed to a participant",
+        "tags": ["messaging"],
+        "x-port-id": "port.messaging",
+        "x-direction": "out",
+        "parameters": [
+          {
+            "name": "address",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "conversation_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Collection"
+          }
+        }
+      },
+      "post": {
+        "operationId": "sendAddressedMessage",
+        "summary": "Append an addressed message to a conversation",
+        "tags": ["messaging"],
+        "x-port-id": "port.messaging",
+        "x-direction": "in",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MessageCommand"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          }
+        }
+      }
+    },
+    "/ports/events/progress": {
+      "post": {
+        "operationId": "appendProgressEvent",
+        "summary": "Append coordination progress evidence",
+        "tags": ["events"],
+        "x-port-id": "port.events.progress",
+        "x-direction": "in",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EventCommand"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          }
+        }
+      }
+    },
+    "/ports/events/interaction": {
+      "post": {
+        "operationId": "appendInteractionEvent",
+        "summary": "Append framework or domain interaction evidence",
+        "tags": ["events"],
+        "x-port-id": "port.events.interaction",
+        "x-direction": "in",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EventCommand"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          }
+        }
+      }
+    },
+    "/ports/projections/{projection_id}": {
+      "get": {
+        "operationId": "queryProjection",
+        "summary": "Read a rebuildable projection with provenance",
+        "tags": ["projections"],
+        "x-port-id": "port.projection.query",
+        "x-direction": "out",
+        "parameters": [
+          {
+            "name": "projection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9_.-]*$"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Record"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/ports/repos/{repo_slug}": {
+      "get": {
+        "operationId": "getRepositoryReference",
+        "summary": "Resolve repository metadata through repo-manager",
+        "tags": ["repositories"],
+        "x-port-id": "port.repo",
+        "x-direction": "out",
+        "parameters": [
+          {
+            "name": "repo_slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Record"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/ports/work/{record_id}": {
+      "get": {
+        "operationId": "getWorkRecordProjection",
+        "summary": "Read a repository-authoritative work-record projection",
+        "tags": ["work"],
+        "x-port-id": "port.work",
+        "x-direction": "out",
+        "parameters": [
+          {
+            "name": "record_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Record"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/ports/policy/evaluations": {
+      "post": {
+        "operationId": "evaluatePolicy",
+        "summary": "Request an authorization or policy decision from its authority",
+        "tags": ["policy"],
+        "x-port-id": "port.policy",
+        "x-direction": "out",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PolicyEvaluation"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Record"
+          },
+          "503": {
+            "description": "Policy authority unavailable; callers fail closed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PortError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/ports/telemetry/samples": {
+      "post": {
+        "operationId": "submitTelemetrySample",
+        "summary": "Submit correlated cost or usage telemetry",
+        "tags": ["telemetry"],
+        "x-port-id": "port.telemetry",
+        "x-direction": "in",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TelemetryCommand"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          }
+        }
+      }
+    },
+    "/ports/schedule/requests": {
+      "post": {
+        "operationId": "requestScheduledExecution",
+        "summary": "Request activity-core execution without embedding a scheduler",
+        "tags": ["schedule"],
+        "x-port-id": "port.schedule",
+        "x-direction": "out",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleCommand"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "$ref": "#/components/responses/Accepted"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "CorrelationHeader": {
+        "name": "X-Correlation-ID",
+        "in": "header",
+        "required": true,
+        "description": "UUIDv7 correlation identifier for the registration action.",
+        "schema": {
+          "$ref": "#/components/schemas/CorrelationId"
+        }
+      }
+    },
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      }
+    },
+    "schemas": {
+      "RegistryRegistration": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["descriptor", "manifest"],
+        "properties": {
+          "descriptor": {
+            "$ref": "../schemas/hub-descriptor.schema.json"
+          },
+          "manifest": {
+            "$ref": "../schemas/hub-manifest.schema.json"
+          }
+        }
+      },
+      "MessageCommand": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["schema_version", "correlation_id", "from_address", "to_addresses", "body"],
+        "properties": {
+          "schema_version": {
+            "type": "string"
+          },
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          },
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "from_address": {
+            "type": "string",
+            "minLength": 1
+          },
+          "to_addresses": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1
+          },
+          "subject_refs": {
+            "$ref": "#/components/schemas/SubjectRefs"
+          }
+        }
+      },
+      "EventCommand": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["schema_version", "correlation_id", "event_type", "occurred_at", "payload"],
+        "properties": {
+          "schema_version": {
+            "type": "string"
+          },
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          },
+          "event_type": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9][a-z0-9-]*)+$"
+          },
+          "occurred_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject_refs": {
+            "$ref": "#/components/schemas/SubjectRefs"
+          },
+          "payload": {
+            "type": "object"
+          }
+        }
+      },
+      "PolicyEvaluation": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["correlation_id", "subject", "action", "resource"],
+        "properties": {
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          },
+          "subject": {
+            "type": "string",
+            "minLength": 1
+          },
+          "action": {
+            "type": "string",
+            "minLength": 1
+          },
+          "resource": {
+            "type": "string",
+            "minLength": 1
+          },
+          "context": {
+            "type": "object"
+          }
+        }
+      },
+      "TelemetryCommand": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["schema_version", "correlation_id", "metric", "value", "recorded_at"],
+        "properties": {
+          "schema_version": {
+            "type": "string"
+          },
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          },
+          "metric": {
+            "type": "string",
+            "minLength": 1
+          },
+          "value": {
+            "type": "number"
+          },
+          "unit": {
+            "type": "string"
+          },
+          "recorded_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject_refs": {
+            "$ref": "#/components/schemas/SubjectRefs"
+          }
+        }
+      },
+      "ScheduleCommand": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["correlation_id", "capability", "requested_for", "input"],
+        "properties": {
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          },
+          "capability": {
+            "type": "string",
+            "pattern": "^capability\\.[a-z0-9][a-z0-9-]*\\.[a-z0-9][a-z0-9-]*$"
+          },
+          "requested_for": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "input": {
+            "type": "object"
+          }
+        }
+      },
+      "CorrelationId": {
+        "type": "string",
+        "format": "uuid",
+        "description": "UUIDv7 correlation identifier for one action spanning information kinds."
+      },
+      "SubjectRefs": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "PortAccepted": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "correlation_id"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "enum": ["accepted", "duplicate"]
+          },
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          }
+        }
+      },
+      "PortRecord": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "data", "provenance"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "data": {
+            "type": "object"
+          },
+          "provenance": {
+            "type": "object",
+            "required": ["source_system", "source_ref", "schema_version"],
+            "properties": {
+              "source_system": {
+                "type": "string"
+              },
+              "source_ref": {
+                "type": "string"
+              },
+              "schema_version": {
+                "type": "string"
+              },
+              "content_hash": {
+                "type": "string"
+              },
+              "indexed_at": {
+                "type": "string",
+                "format": "date-time"
+              }
+            }
+          }
+        }
+      },
+      "PortCollection": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["items"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PortRecord"
+            }
+          },
+          "next_cursor": {
+            "type": ["string", "null"]
+          }
+        }
+      },
+      "PortError": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "correlation_id": {
+            "$ref": "#/components/schemas/CorrelationId"
+          }
+        }
+      }
+    },
+    "responses": {
+      "Accepted": {
+        "description": "Command accepted idempotently",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PortAccepted"
+            }
+          }
+        }
+      },
+      "Record": {
+        "description": "Projected record with provenance",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PortRecord"
+            }
+          }
+        }
+      },
+      "Collection": {
+        "description": "Projected collection",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PortCollection"
+            }
+          }
+        }
+      },
+      "InvalidRequest": {
+        "description": "Contract validation failed",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PortError"
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Requested projection or authority reference was not found",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PortError"
+            }
+          }
+        }
+      }
+    }
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/schemas/event-type-catalog.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.helixforge.local/helixforge.hub-extension/0.1.0/event-type-catalog.schema.json",
+  "title": "HelixForge Event Type Catalog",
+  "description": "Catalog of versioned, non-secret event types with distinct semantic families.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["catalog_version", "event_types"],
+  "properties": {
+    "catalog_version": {
+      "$ref": "#/$defs/semver"
+    },
+    "event_types": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/eventType"
+      }
+    }
+  },
+  "$defs": {
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "eventType": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "display_name",
+        "description",
+        "family",
+        "schema_version",
+        "owner",
+        "sensitivity",
+        "payload_schema_ref",
+        "correlation_required"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9][a-z0-9-]*)+$",
+          "maxLength": 180
+        },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000
+        },
+        "family": {
+          "enum": ["progress", "interaction", "repository_change", "domain"]
+        },
+        "schema_version": {
+          "$ref": "#/$defs/semver"
+        },
+        "owner": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "maxLength": 80
+        },
+        "sensitivity": {
+          "enum": ["public_internal", "operational", "personal"]
+        },
+        "payload_schema_ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "correlation_required": {
+          "type": "boolean"
+        },
+        "retention_class": {
+          "enum": ["audit", "operational", "domain_policy"]
+        }
+      }
+    }
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/schemas/hub-descriptor.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.helixforge.local/helixforge.hub-extension/0.1.0/hub-descriptor.schema.json",
+  "title": "HelixForge Hub Descriptor",
+  "description": "Identity and contract-version declaration for a domain or aspect hub.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract_id",
+    "contract_version",
+    "hub_slug",
+    "display_name",
+    "domain",
+    "hub_kind",
+    "status",
+    "reuse_surface_id",
+    "contract_version_min",
+    "contract_version_max"
+  ],
+  "properties": {
+    "contract_id": {
+      "const": "helixforge.hub-extension"
+    },
+    "contract_version": {
+      "$ref": "#/$defs/semver"
+    },
+    "hub_slug": {
+      "$ref": "#/$defs/slug"
+    },
+    "display_name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "domain": {
+      "$ref": "#/$defs/slug"
+    },
+    "hub_kind": {
+      "enum": ["domain", "aspect"]
+    },
+    "status": {
+      "enum": ["draft", "active", "deprecated", "retired"]
+    },
+    "reuse_surface_id": {
+      "$ref": "#/$defs/capabilityId"
+    },
+    "contract_version_min": {
+      "$ref": "#/$defs/semver"
+    },
+    "contract_version_max": {
+      "$ref": "#/$defs/semver"
+    },
+    "vsm_system": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    },
+    "vsm_function": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    }
+  },
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "maxLength": 80
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "capabilityId": {
+      "type": "string",
+      "pattern": "^capability\\.[a-z0-9][a-z0-9-]*\\.[a-z0-9][a-z0-9-]*$",
+      "maxLength": 160
+    }
+  }
+}

hub_core/contracts/helixforge_hub_extension/v0_1_0/schemas/hub-manifest.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.helixforge.local/helixforge.hub-extension/0.1.0/hub-manifest.schema.json",
+  "title": "HelixForge Hub Capability Manifest",
+  "description": "Versioned capabilities, ports, events, and non-secret integration metadata for a hub.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "manifest_version",
+    "schema_version",
+    "reuse_surface_id",
+    "provides",
+    "consumes",
+    "events_emitted",
+    "events_consumed"
+  ],
+  "properties": {
+    "manifest_version": {
+      "$ref": "#/$defs/semver"
+    },
+    "schema_version": {
+      "$ref": "#/$defs/semver"
+    },
+    "reuse_surface_id": {
+      "$ref": "#/$defs/capabilityId"
+    },
+    "provides": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/capabilityId"
+      },
+      "uniqueItems": true
+    },
+    "consumes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/portId"
+      },
+      "uniqueItems": true
+    },
+    "events_emitted": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/eventType"
+      },
+      "uniqueItems": true
+    },
+    "events_consumed": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/eventType"
+      },
+      "uniqueItems": true
+    },
+    "endpoints": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/endpoint"
+      },
+      "uniqueItems": true,
+      "default": []
+    },
+    "policy_scopes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_.:-]*$",
+        "maxLength": 160
+      },
+      "uniqueItems": true,
+      "default": []
+    },
+    "widgets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/surface"
+      },
+      "uniqueItems": true,
+      "default": []
+    },
+    "operator_surfaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/surface"
+      },
+      "uniqueItems": true,
+      "default": []
+    }
+  },
+  "$defs": {
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "capabilityId": {
+      "type": "string",
+      "pattern": "^capability\\.[a-z0-9][a-z0-9-]*\\.[a-z0-9][a-z0-9-]*$",
+      "maxLength": 160
+    },
+    "eventType": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9][a-z0-9-]*)+$",
+      "maxLength": 180
+    },
+    "portId": {
+      "enum": [
+        "port.registry",
+        "port.addressing",
+        "port.messaging",
+        "port.events.progress",
+        "port.events.interaction",
+        "port.projection.query",
+        "port.repo",
+        "port.work",
+        "port.policy",
+        "port.telemetry",
+        "port.schedule"
+      ]
+    },
+    "endpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "discovery_key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https?://"
+        }
+      },
+      "oneOf": [
+        {"required": ["discovery_key"]},
+        {"required": ["url"]}
+      ]
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "kind": {
+          "enum": ["widget", "console", "dashboard", "mcp", "cli"]
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 1000
+        }
+      }
+    }
+  }
+}