Skip to content

runtime-integrations.md

Latest commit

 

History

History
68 lines (52 loc) · 3.88 KB

runtime-integrations.md

File metadata and controls

68 lines (52 loc) · 3.88 KB
Raw

Runtime integration contracts

These contracts make production integration testable without treating a mocked request as a live provider, MC-1, or Colibri deployment.

Feature gates

c3r.feature_flags.FeatureFlags parses the directive's seven environment switches. Unknown boolean values fail closed, C3R_ENABLED=false disables every learned/native control surface, and C3R_ONLINE_LEARNING=true is rejected. A host still owns the deterministic path that runs when C3R is disabled.

Deliberative providers

The stateless production target is self-hosted DeepSeek V4.1 Flash alongside Qwen3-8B/CLM on the existing eight-H100 node. Canonical identifiers are:

  • Hugging Face checkpoint: deepseek-ai/DeepSeek-V4.1-Flash
  • Local OpenAI-compatible endpoint: http://127.0.0.1:8000/v1, alias /model

This is a provider default, not execution authority. The official checkpoint has passed a private 8×H100 GCP localhost inference smoke test and has a verified private GCS backup; neither result qualifies a public C3R endpoint. c3r.deliberative.default_provider_config constructs this local profile by default. Explicit remote profiles remain legacy compatibility contracts only, not production routing or fallback. See deploy/deepseek-v41 for the pinned qualification target, startup correction, and recovery/candidate distinction.

c3r.adapters.providers.ProviderAdapter supports four protocol shapes:

  • OpenAI;
  • Anthropic Messages;
  • Gemini generateContent;
  • OpenAI-compatible endpoints used by MC-1, Qwen, DeepSeek, vLLM, SGLang, and llama.cpp.

Remote endpoints must use HTTPS; plain HTTP is accepted only for loopback runtimes. Responses must contain the five bounded arrays required by the Deliberative Envelope. The adapter limits response bytes, array cardinality, individual strings, and aggregate structured content. Missing fields, invalid JSON, oversize content, or non-success HTTP status fail closed. ProviderController converts transport, outage, timeout, and malformed-response failures into the deterministic action selected by host policy. API keys are supplied by the host and are absent from results and telemetry.

These are protocol-level contracts. Historical credentialed, fixed-prompt remote probes for DeepSeek, Qwen3.8 Flash, and Claude Sonnet 4.6 capture limited latency and usage evidence. A provider becomes release-qualified only after multi-case tests capture model revision, region, latency, usage, failure, and fallback evidence in the integrated C3R path. c3r.deliberative.provider_bridge.ProviderDeliberator connects compiled state to the adapter while rejecting local-only state for remote endpoints. Its structured plan has no commit authority.

Colibri shadow control

c3r.colibri.ColibriShadowController consumes route trace, .coli usage, DSpark acceptance, verification width, expert/cache/I/O/utilization, and context metrics. Its output is always marked authoritative=False. Low draft acceptance recommends TARGET_ONLY; controller failure returns NATIVE_FALLBACK. Native token acceptance and MoE routing remain authoritative.

The dedicated public integration repository and pinned build exist. Live completion still requires compatible instrumentation, immutable route/build evidence, and captured shadow traces.

Evidence ledger

c3r.telemetry.trace_ledger.TraceLedger canonicalizes decision traces and links them with SHA-256. Replay rejects reordered, modified, non-canonical, or broken-chain records. The ledger supplies an integrity check, not tamper proofing or empirical evidence by itself. A transactional SqliteTraceLedger survives restart and verifies its chain on open, but must be placed on durable, access-controlled storage and backed up. Evidence-grade use must anchor or sign ledger heads in an independently controlled append-only store, and release traces must still be governed, redacted, licensed, and independently reproducible.