Active Hypergraph Inference Prototype

This is the local, dependency-light runtime for the active hypergraph inferencing path described in ARC-ADR-051-active-hypergraph-inferencing. It is a deployable prototype and contract harness, not the final backend-core production service.

Start

node tools/active-hypergraph-server.mjs --host 127.0.0.1 --port 8097

Optional bearer auth:

HYPERGRAPH_AUTH_TOKEN=local-token node tools/active-hypergraph-server.mjs --host 127.0.0.1 --port 8097

When bearer auth is configured, requests default to the read-only object-inference:read scope. Lifecycle mutations require explicit X-Hypergraph-Scopes values:

• object-index:write for /v1/object-index-updates
• object-index:promote for overlay compaction and candidate promotion
• object-index:rollback for rollback
• object-inference:trace:read for trace fetch
• object-inference:trace:replay for trace replay

Local no-token mode grants prototype-local access for development only.

Optional fixture override:

node tools/active-hypergraph-server.mjs --current-view docs/platform-capability-current-view.json

Optional UDA-style HTTP projection source:

node tools/active-hypergraph-server.mjs --current-view-url http://127.0.0.1:8080/current-view

--current-view-url / HYPERGRAPH_CURRENT_VIEW_URL lets the prototype hydrate its Object Model projection from a JSON HTTP source that returns { "tracks": [...] }. This is the local handoff shape for replacing file reads with backend-core/UDA transport.

Optional file-backed prototype store:

node tools/active-hypergraph-server.mjs --persistence-dir tmp/active-hypergraph-store

The file-backed store persists traces, delta overlays, candidate snapshots, promotion state, rollback stack, and audit events into active-hypergraph-store.json under the supplied directory. It is a local deployability seam, not the final backend-core durable storage design.

Optional prototype request budget gate:

node tools/active-hypergraph-server.mjs --request-budget-limit 100

--request-budget-limit / HYPERGRAPH_REQUEST_BUDGET_LIMIT enables a principal-scoped request budget for authenticated and local prototype traffic. Budget exhaustion fails closed with 429 Problem Details before request body parsing, inference, or lifecycle mutation. The runtime emits audit and telemetry evidence for budget denials and persists budget counters with the file-backed store when enabled.

Python authority HTTP rehearsal:

python tools/hypergraph_inference/production_prototype.py --host 127.0.0.1 --port 8098

Optional Python harness controls:

HYPERGRAPH_AUTH_TOKEN=local-token \
HYPERGRAPH_STATE_PATH=tmp/active-hypergraph-python-state.json \
python tools/hypergraph_inference/production_prototype.py --request-budget-limit 100

The Python harness is a stdlib HTTP shell around the same backend-core-shaped authority runtime used by the unit tests. It exists to prove that the authority core can run as a service-shaped port target with bearer auth, supplied scopes, SSE event formatting, request budgets, and JSON state rehearsal. It is still not the final FastAPI/backend-core service.

Python hyperbolic training worker rehearsal:

python tools/hypergraph_inference/training_worker.py \
  --job tmp/hypergraph-training-job.json \
  --current-view docs/platform-capability-current-view.json \
  --out tmp/hypergraph-candidate.json \
  --summary-out tmp/hypergraph-worker-summary.json

The worker job JSON contains changes plus optional evalCases, performanceBudgetsMs, principal, and now. The worker writes the contract-shaped hyperbolic-training.candidate-snapshot artifact consumed by promotion gates. This is the container entrypoint rehearsal for the GPU worker topologies; the production image keeps the IO contract while replacing the stdlib optimizer with PyTorch/Geoopt. The queue/CLI job and summary shapes are contract-checked by contracts/hyperbolic-training-worker-job.schema.json and contracts/hyperbolic-training-worker-result.schema.json, with canonical examples in contracts/hyperbolic-training-worker-job.example.json and contracts/hyperbolic-training-worker-result.example.json.

Worker container template:

docker build -f templates/hypergraph-training-worker-image/Dockerfile -t active-hypergraph-training-worker:prototype .
python tools/validate-active-hypergraph-worker-container.py

The template image is intentionally dependency-light and CPU/stdlib-only. It packages the worker CLI, runs as a non-root user, exposes no request-serving port, mounts /work/in and /work/out, and preserves the offline artifact contract expected by the managed GPU worker topologies. contracts/hyperbolic-training-worker-image-build.schema.json and its example capture the release-engineering image contract: Dockerfile path, build context, entrypoint, default args, volume modes, linked schemas/examples, security expectations, and validation commands.

Surfaces

• GET /healthz: readiness, serving snapshot, delta overlay, and lifecycle counters.
• GET /v1/models: OpenAI-compatible model discovery for untool-hypergraph-gate-0 and its hypergraph capabilities.
• GET /v1/models/{model}: model metadata, including the Poincare-ball activation-space geometry.
• POST /v1/embeddings: OpenAI-compatible embedding response with 2D Poincare-ball activation coordinates. When the input activates Object Model support, the coordinate is derived from graph node, edge, hyperedge, relator, role-binding, and literal-feature embeddings before the gate; deterministic text fallback is used only when no grounded slice activates. These coordinates are activation indexes for attention/retrieval, not canonical truth. contracts/hypergraph-embedding-derivation.schema.json pins the derivation packet so backend-core can reproduce the same source counts, weighting inputs, unit-ball normalization, trace linkage, source-set digest/ref, and fallback-only-when-ungrounded rule. contracts/hyperbolic-embedding-source-set.schema.json makes the served graph-derived source vectors inspectable and digest-bound; the output validator recomputes the weighted barycenter from those source records and rejects source-count, unit-ball, or digest drift.
• POST /v1/object-inference: native authority response, including answer, sufficiency, trace, derived facts, activated objects, and hyperbolic response gate.
• POST /v1/object-inference:stream: Server-sent event stream over the same native authority path. It emits activation, gate, final, and done events; the final event is the same object.inference response and its trace is fetchable through the trace API.
• POST /v1/chat/completions: OpenAI-compatible adapter over the same native response. The returned hypergraph.trace.traceId is fetchable through the trace API. Set stream: true for OpenAI-style chat.completion.chunk SSE data frames terminated by data: [DONE].
• POST /v1/responses: OpenAI-compatible Responses adapter over the same native response. It accepts input or chat-style messages, returns output_text, and carries public-redacted hypergraph metadata. Set stream: true for Responses-style response.* SSE data frames terminated by data: [DONE].
• GET /v1/object-inference/traces/{traceId}: public-redacted trace envelope.
• POST /v1/object-inference/traces/{traceId}:replay: deterministic replay against the recorded serving view.
• POST /v1/object-index-updates: provenance-required Object Model updates into the active delta overlay.
• POST /v1/object-index-training-jobs: dependency-light rehearsal of the offline hyperbolic training worker. It accepts provenance-required Object Model changes, derives graph-backed Poincare coordinates from the candidate view, emits micro-batch optimization evidence, optionally runs sufficiency eval cases, runs deterministic poisoning/adversarial and performance-budget gates, and stores a candidate snapshot for explicit promotion. It does not allow request-path training.
• GET /v1/object-index-training-jobs/{candidateSnapshotId}: fetch a stored hyperbolic training candidate snapshot for inspection or promotion handoff.
• POST /v1/object-index-overlays:compact: compact the delta overlay into a candidate serving snapshot with promotion gate evidence.
• POST /v1/object-index-promotions: promote a candidate snapshot to active serving. The request must include the candidate's promotionGateId.
• POST /v1/object-index-promotions:rollback: restore the previous active snapshot.

The runtime emits structured activeHypergraphAuditEvent records for allowed, denied, and error outcomes across inference, trace, object-index, promotion, rollback, and routing operations. In embedded tests this is exposed through the eventSink callback; with --persistence-dir, events are also stored in the prototype file store.

The embedded runtime also emits dependency-free, OTel-shaped activeHypergraphTelemetrySpan records for source loading, object inference, chat completion, trace replay, policy denials, and object-index lifecycle operations. The server honors W3C traceparent correlation when supplied and stores spans in the prototype file store when --persistence-dir is enabled.

When the optional request budget gate is enabled, the runtime records budget counters per prototype principal and exposes the number of tracked principals in /healthz.

Smoke Requests

curl -s http://127.0.0.1:8097/healthz

curl -s http://127.0.0.1:8097/v1/models

curl -s http://127.0.0.1:8097/v1/embeddings \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"input\":[\"which UDA adoption tracks are ready?\",\"route backend UDA work\"]}"

curl -s http://127.0.0.1:8097/v1/object-inference \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"query\":\"which UDA adoption tracks are ready?\"}"

curl -N http://127.0.0.1:8097/v1/object-inference:stream \
  -H "accept: text/event-stream" \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"query\":\"which UDA adoption tracks are ready?\"}"

curl -s http://127.0.0.1:8097/v1/chat/completions \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"messages\":[{\"role\":\"user\",\"content\":\"which UDA adoption tracks are ready?\"}]}"

curl -N http://127.0.0.1:8097/v1/chat/completions \
  -H "accept: text/event-stream" \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"stream\":true,\"stream_options\":{\"include_usage\":true},\"messages\":[{\"role\":\"user\",\"content\":\"which UDA adoption tracks are ready?\"}]}"

curl -s http://127.0.0.1:8097/v1/responses \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"input\":\"which UDA adoption tracks are ready?\"}"

curl -N http://127.0.0.1:8097/v1/responses \
  -H "accept: text/event-stream" \
  -H "content-type: application/json" \
  -d "{\"model\":\"untool-hypergraph-gate-0\",\"stream\":true,\"input\":\"which UDA adoption tracks are ready?\"}"

Scoped lifecycle example:

curl -s http://127.0.0.1:8097/v1/object-index-updates \
  -H "authorization: Bearer local-token" \
  -H "x-hypergraph-scopes: object-index:write" \
  -H "content-type: application/json" \
  -d "{\"indexId\":\"active\",\"snapshotId\":\"snapshot-1\",\"changes\":[{\"objectId\":\"track:commons-core:uda.dataobject.runtime.receivers\",\"operation\":\"upsert\",\"objectKind\":\"AdoptionTrack\",\"provenanceHash\":\"sha256:local-demo\",\"object\":{\"repo\":\"commons-core\",\"capabilityId\":\"uda.dataobject.runtime.receivers\",\"capabilityTitle\":\"UDA DataObject runtime receivers available\",\"capabilityStatus\":\"available\",\"target\":\"Serve typed DataObjects through commons projection grammar\",\"issueState\":\"OPEN\",\"dispatchState\":\"ready_to_launch\"}}]}"

Validate

python tools/validate-active-hypergraph-production-prototype.py
node --test tests/active-hypergraph-inference.test.mjs tests/active-hypergraph-server.test.mjs
python -m unittest tests.test_active_hypergraph_inference_contract
python -m unittest tests.test_active_hypergraph_production_readiness
python -m unittest tests.test_active_hypergraph_serving_handoff
python -m unittest tests.test_active_hypergraph_service_port_plan
python -m unittest tests.test_hypergraph_inference_production_prototype
python tools/validate-active-hypergraph-inference-traces.py --live
python tools/validate-active-hypergraph-output-contracts.py
python tools/validate-hypergraph-embedding-derivation.py
python tools/validate-hyperbolic-embedding-source-set.py --live
python tools/validate-active-hypergraph-policy-decision.py
python tools/validate-active-hypergraph-otel-export-batch.py
python tools/validate-active-hypergraph-runtime-state.py
python tools/validate-active-hypergraph-durable-store-operations.py
python tools/validate-active-hypergraph-worker-container.py
node tools/contracts-package.mjs --check
python tools/validate-active-hypergraph-production-readiness.py
python tools/validate-active-hypergraph-serving-handoff.py
python tools/validate-active-hypergraph-service-port-plan.py
node tools/validate-active-hypergraph-http-runtime.mjs

The production-prototype validator is the umbrella proof surface for the local active-hypergraph ladder. --list reports the exact commands without executing them for readiness-manifest and CI introspection; the default mode runs the Python unit ladder, Node reference/runtime tests, manifest validators, live contract validators, HTTP smoke validation, runtime-state validation, and whitespace/conflict-marker checks.

The HTTP runtime validator exercises health, bearer auth, native object inference, model discovery, hyperbolic embeddings, UDA-style current-view source loading, object-index updates, overlay compaction, candidate promotion, rollback, trace fetch, trace replay, OpenAI-compatible chat completion, OpenAI-compatible chat streaming, OpenAI-compatible Responses, OpenAI-compatible Responses streaming, object-inference SSE streaming, public-redaction checks, scoped lifecycle policy, request budget enforcement, audit events, OTel-shaped telemetry spans, promotion gate evidence, and file-backed restart recovery.

The production-readiness validator checks contracts/active-hypergraph-production-readiness.example.json. That manifest is the explicit graduation gate from local deployable prototype to backend-core production service. The dependency-light Python core under tools/hypergraph_inference/production_prototype.py proves the backend-core authority path shape: policy filtering before activation, object.inference as authority, chat/Responses as adapters, and graph-derived hyperbolic embeddings. It also includes a small in-memory runtime wrapper for backend-core port rehearsal: authority traces can be stored, exposed through public-redacted trace envelopes, replayed deterministically against the recorded serving view, and guarded by a principal-scoped request budget that emits audit events before denying exhausted callers. The runtime state can be exported/imported as JSON for restart rehearsal, preserving recorded traces, audit events, and prototype budget counters. contracts/active-hypergraph-runtime-state.schema.json and tools/validate-active-hypergraph-runtime-state.py make that exported state shape contract-checked, including records, budget counters, audit/telemetry, delta overlays, training candidates, active snapshots, and rollback stack. contracts/active-hypergraph-durable-store-operations.schema.json adds the backend-core persistence handoff over that state: the Python runtime can emit content-addressed operations for the activation trace store, principal budget store, active object-index store, audit store, and OTel export path. Each operation carries a store id, production gate id, payload kind, digest, idempotency key, and backend-core-durable durability requirement, so the prototype can prove the consumer contract without claiming its JSON state file is production storage. JsonFileRuntimeStateStore adds a write-through store seam over the same state shape. It is still a dependency-light rehearsal, not the production store, but it proves backend-core can replace prototype memory with a durable trace, budget, object-index, audit, and telemetry boundary without changing the authority path. UdaDataObjectHydrator adds the matching production-shaped hydration seam. The Python runtime can hydrate a typed Object Model view through a UDA-shaped adapter, scope-filter before inference, disallow fallback on that path, emit active-hypergraph.uda-hydration telemetry, and then activate the graph-native authority path from the hydrated view. contracts/uda-hypergraph-hydration.schema.json pins that exchange shape for backend-core: the receiver packet must include the transport, policy filter, hydrated object kinds, scoped view digest, fallback disallowance, and the before-object-inference hydration boundary. The Python runtime also exposes framework-free route handlers for /healthz, /v1/models, /v1/models/{model}, /v1/object-inference, trace fetch/replay, /v1/chat/completions, /v1/responses, and /v1/embeddings; these are backend-core/FastAPI port rehearsal handlers, not a public server. It also supports provenance-required /v1/object-index-updates for local delta-overlay rehearsal; accepted AdoptionTrack upserts/deletes participate in subsequent inference and embeddings and are included in JSON restart state. The Python object-index lifecycle can compact overlays into candidate snapshots, require matching promotion gate evidence before activation, promote an active snapshot, and roll back to the prior active snapshot. The Python core also rehearses the offline hyperbolic training worker through run_hyperbolic_training_batch and /v1/object-index-training-jobs: candidate snapshots get graph-derived source embeddings, loss-before/loss-after evidence, optional sufficiency eval evidence, and promotion gates while keeping per-request training disallowed. Candidate snapshots also carry a content-addressed hyperbolic-embedding.index-delta manifest so backend-core can revalidate the exact per-object embedding mutations before changing the active index. Graph-derived index-delta entries carry the source-set ref and digest from their derivation, and those fields are part of the entry embeddingDigest, so promotion can revalidate the exact graph-native source set that produced the coordinate. tools/hypergraph_inference/training_worker.py wraps that same core as a container-friendly worker CLI with explicit job/current-view/artifact paths and a small machine-readable summary output. contracts/hyperbolic-training-promotion-package.schema.json adds the backend-core promotion input package: candidate snapshot id, promotion gate id, candidate artifact digest, worker-result digest, source Object Model digest, worker image digest, contract bundle version, idempotency key, and backend-core revalidation checks. This keeps promotion content-addressed; backend-core should revalidate the package before mutating the active snapshot instead of trusting a path-only candidate artifact. Promotion package revalidation now explicitly includes source-set-digest-matches, so backend-core must prove graph-derived source-set lineage before mutating the active embedding index. The backend-core service-port plan mirrors that requirement as promotionRevalidation, assigning the checks and input contracts to app/llm/hypergraph/training_queue.py. The skeleton also pins app/llm/hypergraph/training_policy.py against the backend-core port manifest: both promotion bindings must use the hyperbolic-training-jobs queue, candidate/result/promotion package schemas, and requestPathAllowed=false. The OpenAPI promotion request exposes optional promotionPackage evidence with the same source-set and embedding-index-delta digest checks, giving SDK callers a native way to pass graph-derived lineage into backend-core revalidation without turning the hypergraph into a fake LLM provider string. The Python promotion handler now enforces that optional handle when it is supplied: malformed digests, unknown schemas, unknown checks, or incomplete backend-core revalidation checklists are rejected before active snapshot mutation, and accepted package evidence is echoed through response/audit/span metadata for the service-port handoff. templates/hypergraph-training-worker-image/Dockerfile packages that CLI as a non-root, no-ingress, volume-oriented prototype image, and tools/validate-active-hypergraph-worker-container.py validates the image contract, worker job schema, candidate artifact schema, worker-result schema, canonical job/result examples, and a worker CLI smoke run without requiring Docker in every test environment. contracts/hypergraph-embedding-derivation.schema.json, contracts/hypergraph-embedding-derivation.graph.example.json, contracts/hypergraph-embedding-derivation.fallback.example.json, and tools/validate-hypergraph-embedding-derivation.py make embedding adapter evidence machine-checkable: graph-derived coordinates must line up source counts with activated IDs and a digest-backed source set, and deterministic fallback cannot carry graph source counts or unredacted reasons. contracts/hyperbolic-embedding-source-set.schema.json separately validates the inspectable node, edge, hyperedge, relator, role-binding, and literal-feature records used to compose graph-derived Poincare barycenters. tools/validate-hyperbolic-embedding-source-set.py --live validates both the canonical source-set example and a live source set generated from the current view, including source-count parity, duplicate source refs, unit-ball safety, barycenter recomposition, digest checks, and redaction. contracts/hyperbolic-training-candidate.schema.json and the output contract validator make that candidate snapshot shape machine-checkable alongside trace, gate, object-inference, embedding derivation, source-set, and chat-completion packets. node tools/contracts-package.mjs --check keeps the active-hypergraph schemas, OpenAPI contract, worker IO fixtures, readiness manifests, and handoff manifests inside the fleet contract bundle so backend-core, Fleet Console, and worker consumers can pin one distribution surface. Training candidates can be saved with save_training_candidate_artifact, loaded into a fresh runtime with load_training_candidate_artifact, fetched through the candidate route, and then promoted through the same explicit promotion API. The training report includes a prototype poisoning gate that blocks weak provenance hashes, object-id mismatches, unsupported dispatch states, prompt-injection markers, and oversized training text from producing a passed promotion gate. The same report includes deterministic performance-budget evidence for inference, training, and promotion estimates. Candidate promotion is blocked if the estimated budget checks fail. Python unit tests also compare core contract fields against the Node reference harness for seeded and fail-closed queries so the backend-core port target does not drift from the executable OpenAI-compatible harness. Contract tests enumerate every GET/POST path declared in contracts/hypergraph-object-inference.openapi.yaml and probe the Python route adapter with valid sample requests, including the explicit /v1/object-inference:stream route, so the backend-core-shaped harness cannot silently drift from OpenAPI. The Python core includes a deterministic sufficiency eval harness for seeded, partial, and fail-closed cases. It asserts expected sufficiency/gate status, required or forbidden fact kinds, activated support, no model claims, and fact supports inside the active set. The Python authority runtime can also be launched as a dependency-free stdlib HTTP harness. Its unit test starts the harness on a loopback port and verifies bearer-token denial, health, native object inference, scoped object-index mutation, OpenAI-compatible SSE streaming, and JSON state reload from the same runtime state file. stream: true on the Python object-inference, chat, and Responses handlers returns deterministic event envelopes matching the Node authority/adapters, including final trace metadata and [DONE] markers for OpenAI-style streams. Python runtime actions emit OTel-shaped activeHypergraphTelemetrySpan records for object inference, chat, Responses, embeddings, health, trace fetch, trace replay, budget denial, and route errors. These spans are prototype evidence; backend-core still owns collector/export integration. contracts/active-hypergraph-otel-export-batch.schema.json adds the collector handoff over those spans. The Python runtime can emit an active-hypergraph.otel-export-batch with backend-core collector identity, service resource metadata, span count, prompt-redaction requirement, and traceparent requirement. The validator rejects prompt or credential leakage and inconsistent span status. The backend-core port manifest now maps the concrete active-hypergraph.* runtime span names into backend-core collector span names through telemetryBindings.spanMappings, including required attributes, traceparent propagation, and prompt-redaction expectations. The validator fails if the mapping drifts from the runtime span names or drops a required telemetry category. When request scopes are supplied, the Python route handlers fail closed before inference unless the caller has object-inference:read, and trace fetch/replay require object-inference:trace:read / object-inference:trace:replay. contracts/active-hypergraph-policy-decision.schema.json pins those decisions as a backend-core middleware exchange: each supplied-scope decision records the principal, route, action, required scope, granted scopes, decision, reason, jwt-authn / scope-authz middleware ids, and request-path training exclusion. Local no-scope mode remains a prototype convenience only. Public traffic still stays blocked until the backend service port, JWT/RBAC integration, durable trace/budget/index stores, production UDA binding, OTel collector export, production promotion gates, and hyperbolic training pipeline are marked passing. The production-readiness validator also allowlists prototype evidence validation commands and requires critical evidence ids, so the readiness manifest cannot cite stale, missing, or invented checks. It requires the umbrella production-prototype validator as evidence, but records the validator's --list command so readiness checks remain cheap while the full ladder remains available as an explicit release-engineering gate.

The serving-handoff validator checks contracts/active-hypergraph-serving-handoff.example.json. That handoff pins the production serving split: backend-core Python/FastAPI owns the spigot and OpenAI-compatible routes, Rust/UDA owns typed Object Model hydration, managed stores own trace/budget/index state, and a Python GPU worker owns offline hyperbolic optimization and promotion evidence. The embedding shape is derived from the hypergraph's node, edge, hyperedge, relator, role-binding, and literal feature embeddings before the exact hyperbolic rerank/gate. The handoff now references the embedding derivation contract directly through embeddingDerivation.projectionRecipe, keeping the /v1/embeddings adapter portable without making embeddings the truth authority. It also defines the hyperbolic-training-jobs queue seam from backend-core-spigot to hyperbolic-training-worker, bound to the worker job, worker result, candidate snapshot, and promotion package schemas with at-least-once idempotent delivery, DLQ ownership, request-path exclusion, and promotion-gate enforcement. The same handoff now includes machine-checkable deployment topologies for the GPU worker: a first hosted Cloud Run L4-style worker, an Azure Container Apps GPU placement, an AWS ECS/EKS GPU fleet placement, and an external experiment worker. Each topology binds a GPU option to the hyperbolic-training-worker component, a Python/PyTorch/Geoopt container contract, durable artifact IO, scale rule, request-path exclusion, and required promotion gates.

contracts/active-hypergraph-backend-core-port.example.json is the next backend-core implementation checklist. It maps every OpenAPI route to a backend-core handler, required scope, and full middleware chain; binds prototype file/in-memory seams to backend-core durable trace, budget, object-index, and audit stores through the durable-store operation contract; requires UDA DataObject hydration with scope filtering before hydration; maps active-hypergraph telemetry to the backend-core OTel collector; and binds promotion/training gates to offline queue evidence. This contract does not make production ready by itself. It proves the port has named production dependencies for each remaining readiness gate. contracts/active-hypergraph-service-port-plan.example.json turns that checklist into a file-level backend-core FastAPI implementation map. It pins app/llm/hypergraph/routes.py, service orchestration, dependency injection, schemas, durable stores, UDA adapter, telemetry exporter, training queue, and tests, and its validator requires exact route/handler parity with the backend-core port manifest. templates/backend-core-active-hypergraph/ is the generated handoff package for that map. It contains thin FastAPI route handlers, service/dependency/schema shells, durable-store/UDA/telemetry/training-queue ports, and backend-core route tests. tools/validate-active-hypergraph-backend-core-skeleton.py statically parses the template and fails if files, route decorators, handler names, service methods, promotion revalidation checks, or promotion evidence schemas drift from the service-port plan. The service-port validator also now compares routeImplementations directly against the OpenAPI /v1 GET/POST surface, so the public SDK contract remains the outer boundary. app/llm/hypergraph/package_policy.py and __init__.py make the package composition explicit for backend-core: the service exports router, health_router, ActiveHypergraphService, and get_active_hypergraph_service, pins /v1 and /healthz mount points, and keeps the installation boundary at the backend-core LLM gateway spigot. The skeleton validator also parses generated Depends(require_scope(...)) dependencies and compares them to each route's declared requiredScopes, catching scope regressions such as treating rollback as a promote-only action. app/llm/hypergraph/route_policy.py adds a backend-core route policy matrix for the same handoff: handler name, required scope, middleware ids, and requestTrainingAllowed=false are all statically compared against the service-port plan, so JWT/RBAC, budget, audit, problem-details, OTel, redaction, and request-path training exclusion cannot drift silently in the template. app/llm/hypergraph/stores.py now exposes the durable state ports backend-core must implement: activation traces, principal budget counters, audit events, OTel export payloads, active object-index delta overlays, candidate snapshots, active snapshot pointers, and rollback stacks. The skeleton validator requires the durable operation store ids from contracts/active-hypergraph-durable-store-operations.schema.json and fails if a store method or id disappears from the backend-core handoff. app/llm/hypergraph/telemetry_policy.py mirrors the backend-core OTel binding: collector exporter, export contract, traceparent requirement, prompt-redaction requirement, span names, backend-core span names, categories, and required attributes. The skeleton validator fails if prompt redaction is disabled or if a required attribute such as hypergraph.request_training_allowed drifts from the manifest. app/llm/hypergraph/uda_policy.py mirrors the backend-core UDA binding: binding id, production gate, component id, transport, hydration contract, hydrated element kinds, fallbackAllowed=false, and scopeFilteredBeforeHydration=true. The skeleton validator rejects fallback or scope-filter drift before the handoff can be applied. app/llm/hypergraph/training_policy.py mirrors the promotion/training bindings: promotion gate ids, queue id, candidate schema, worker-result schema, promotion package schema, and request-path exclusion. That keeps graph-derived hyperbolic coordinate recomputation on the offline trainer/promoter path while serving uses the active snapshot plus audited delta overlays. app/llm/hypergraph/embedding_policy.py mirrors the serving handoff projection recipe: Poincare-ball geometry, the embedding derivation contract, source inputs for node, edge, hyperedge, relator, role-binding, and literal-feature embeddings, graph-derived barycenter method, deterministic fallback method, composition stages, and request-path training exclusion. The source embeddings are typed prior coordinates; the served request coordinate is recomputed from the scoped activated hypergraph slice before the response gate. The skeleton validator rejects source-input, composition, fallback, geometry, serving computation, or request-path drift before backend-core ports the runtime. app/llm/hypergraph/health.py mirrors the OpenAPI /healthz probe as an unauthenticated backend-core readiness route and delegates to the same service health projection used by the model/health policy. app/llm/hypergraph/policy_decision_policy.py mirrors the active-hypergraph policy decision contract so backend-core JWT/RBAC integration emits schema-bound jwt-authn and scope-authz decisions before object inference, adapter rendering, trace access, or object-index lifecycle operations. The skeleton validator rejects contract, middleware id, reason, enforcement-mode, principal-redaction, or request-training evidence drift. app/llm/hypergraph/budget_policy.py mirrors the budget/FinOps middleware handoff: budget-policy must check quota before object inference and adapter rendering, persist budget-counter operations through principal-budget-store under the durable-budget-store gate, and fail closed with 429 denial evidence without enabling request-path training. app/llm/hypergraph/store_operation_policy.py mirrors the durable-store operation contract used for trace records, budget counters, policy decisions, audit events, telemetry spans, delta overlays, candidate snapshots, active snapshots, and rollback stacks. The stores skeleton carries the contract, durability, idempotency format, request-path flags, and request-training exclusion so backend-core storage consumers can replay the same operation semantics the prototype emits. app/llm/hypergraph/spigot_policy.py mirrors the remaining public spigot guardrails: audit logging, Problem Details responses, OTel trace middleware, adapter/trace redaction, public-redacted visibility, denied export classes, and content_filter finish reasons for blocked hypergraph gate decisions. This keeps OpenAI-compatible responses from becoming an unredacted side channel. app/llm/hypergraph/response_gate_policy.py mirrors the public hyperbolic response gate contract and the current runtime decision rule: nearest eight hyperbolic supports, sufficient sufficiency, distance threshold 4.0 for sufficient traces and 1.4 otherwise, a required nearest distance, and at least one derived fact before an answer is allowed. The skeleton validator rejects policy drift that would allow partial answers or unsupported text. app/llm/hypergraph/adapter_policy.py mirrors the OpenAI-compatible facade boundary: chat completions and Responses render the native object.inference authority, carry public-redacted hypergraph metadata, preserve content_filter for blocked gate decisions, and stream the expected chat-completion and Responses event frames before [DONE]. The skeleton validator rejects adapter drift that would turn compatibility routes into a second inference authority. app/llm/hypergraph/request_schema_policy.py mirrors the OpenAPI request schema boundary for embedding, object inference, index updates, training jobs, promotion, chat completions, and Responses. The skeleton validator compares required fields and additional-properties policy against OpenAPI, and also requires the Pydantic shells to expose those required fields, including object-index lifecycle ids and the Responses input/messages alternatives. app/llm/hypergraph/model_policy.py mirrors the health and model discovery contract: the hosted model id stays untool-hypergraph-gate-0, model ownership stays untool.ai, authority stays object.inference, embeddings remain activation-index outputs rather than canonical truth, and the advertised health/model capabilities stay aligned with OpenAPI.

Production Boundary

The final service belongs behind backend-core auth, policy, quotas, audit, and OTel export. This Node runtime should remain a reference harness, local mock, and contract conformance tool while backend-core ports the authority path to its production gateway/runtime boundary.