fix: use provider-backed embeddings for remote agents

.github/workflows/fuzz.yml

@@ -38,6 +38,9 @@ jobs:
         # fuzz/requirements-property.in (recompile with uv pip compile --generate-hashes).
         run: python -m pip install --require-hashes -r fuzz/requirements-property.txt
 
+      - name: Install Rust token packer
+        run: ./scripts/install_native_token_packer.sh
+
       - name: Run property-based fuzz tests
         run: python -m pytest tests/fuzz -q
 
@@ -64,6 +67,9 @@ jobs:
         # fuzz/requirements-atheris.in (recompile with uv pip compile --generate-hashes).
         run: python -m pip install --require-hashes -r fuzz/requirements-atheris.txt
 
+      - name: Install Rust token packer
+        run: ./scripts/install_native_token_packer.sh
+
       - name: Set per-target time budget
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ] || [ "${{ github.event_name }}" = "push" ]; then

.github/workflows/tests.yml

@@ -23,17 +23,5 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
-        with:
-          python-version: "3.12"
-
-      - name: Install test dependencies
-        # Hash-pinned per OpenSSF Scorecard Pinned-Dependencies. Install both
-        # runtime integrations and the property-test tools exercised below.
-        run: |
-          python -m pip install --require-hashes -r requirements.lock
-          python -m pip install --require-hashes -r fuzz/requirements-property.txt
-
-      - name: Run full test suite
-        run: python -m pytest -q
+      - name: Run hash-locked full test suite
+        run: make test

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+contextual_orchestrator/_token_packer*.so
 tempcred.txt
 
 

CHANGELOG.d/token-packer-utf8-boundary.md

@@ -0,0 +1,3 @@
+- Preserve complete UTF-8 scalar values when the Rust embedding token packer
+  divides an input at a provider token ceiling, and fail closed when the
+  configured ceiling cannot contain one decodable scalar.

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Added
 
+- ADR 0006 defines evidence-gated CPU, MLX, CUDA/OpenCL, Compose, and
+  Kubernetes accelerator runtime boundaries.
 - Bounded first-valid-completion racing for operator-declared equivalent model
   group endpoints across text and media capabilities, with fail-closed contract
   comparison and winner/cancellation provenance.
@@ -61,6 +63,8 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Fixed
 
+- Route embedding batches through configured remote embedding agents instead
+  of returning the standalone deterministic vector.
 - Mixed structured workflows now retain a cost-ledger row for calls whose
   provider omitted usage, using the existing token-counting fallback while
   preserving reported counts for the other calls in the same workflow.

Dockerfile

@@ -8,14 +8,32 @@
 # see docs/kv-credentials.md for the bootstrap flow.
 # Agents: defaults to the bundled mock pool; mount your own and set AGENTS_FILE:
 #           -v ./agents.json:/app/agents.json -e AGENTS_FILE=/app/agents.json
+# Rust and maturin are build-only and pinned by an immutable multi-architecture
+# image digest; the runtime remains the pinned slim Python image.
+ARG MATURIN_BUILDER_IMAGE=ghcr.io/pyo3/maturin@sha256:b6c8b59a0170b77eb31a35b56034abd39972483ad0ebfff344deaa42a85f3bd3
+FROM ${MATURIN_BUILDER_IMAGE} AS token-builder
+COPY rust/Cargo.toml rust/Cargo.lock /build/rust/
+COPY rust/token_counter/ /build/rust/token_counter/
+COPY contextual_orchestrator/ /build/contextual_orchestrator/
+WORKDIR /build/rust/token_counter
+RUN maturin build --locked --release --out /build/wheels
+
+# Export only the native wheel for host-based fuzz jobs. BuildKit writes this
+# scratch stage to a temporary directory without a bind mount into the builder.
+FROM scratch AS token-wheel
+COPY --from=token-builder /build/wheels /
+
 # python:3.12-slim
-FROM python:3.12-slim@sha256:423ed6ab25b1921a477529254bfeeabf5855151dc2c3141699a1bfc852199fbf
+FROM python:3.12-slim@sha256:423ed6ab25b1921a477529254bfeeabf5855151dc2c3141699a1bfc852199fbf AS runtime-base
+WORKDIR /app
 
 WORKDIR /app
 COPY pyproject.toml requirements.lock README.md LICENSE ./
 RUN pip install --no-cache-dir --require-hashes -r requirements.lock
 COPY contextual_orchestrator/ /usr/local/lib/python3.12/site-packages/contextual_orchestrator/
 COPY examples/ examples/
+COPY --from=token-builder /build/wheels /tmp/token-wheels
+RUN pip install --no-cache-dir /tmp/token-wheels/*.whl && rm -rf /tmp/token-wheels
 
 ENV AGENTS_FILE=/app/examples/agents.mock.json \
     PORT=8000
@@ -31,3 +49,24 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
 
 # --allow-public-bind: 컨테이너 내부 0.0.0.0 바인딩 필요(외부 노출은 호스트 포트 매핑이 결정)
 CMD ["sh", "-c", "python -m contextual_orchestrator --serve --agents \"$AGENTS_FILE\" --host 0.0.0.0 --port \"$PORT\" --allow-public-bind --auth-token-key CONTEXTUAL_ORCHESTRATOR_TOKEN"]
+
+# Local and CI tests share this target. The wheel remains a BuildKit artifact:
+# it is installed only into uv's ephemeral, hash-locked Python 3.12 environment.
+FROM runtime-base AS test-runner
+USER root
+COPY --from=token-builder /usr/local/bin/uv /usr/local/bin/uv
+COPY --from=token-builder /build/wheels /tmp/token-wheels
+COPY . /io
+WORKDIR /io
+RUN set -eu; \
+    set -- /tmp/token-wheels/*.whl; \
+    test "$#" -eq 1 && test -f "$1" || { \
+      echo "pinned Rust token-packer build must produce exactly one wheel" >&2; exit 1; \
+    }; \
+    uv run --python /usr/local/bin/python --no-project \
+      --with-requirements requirements.lock \
+      --with-requirements fuzz/requirements-property.txt \
+      --with "$1" python -m pytest -q
+USER orchestrator
+
+FROM runtime-base AS runtime

Makefile

@@ -1,4 +1,4 @@
 .PHONY: test
 
 test:
-	uv run --no-project --with-requirements requirements.lock --with-requirements fuzz/requirements-property.txt python -m pytest -q
+	./scripts/run_hash_locked_tests.sh

README.md

@@ -30,6 +30,20 @@ docker compose up --build --wait
 curl http://127.0.0.1:8000/healthz
 ```
 
+The project defaults to `contextual-orchestrator` and has no fixed
+`container_name` values. Run isolated stacks in parallel with distinct project
+names and host ports:
+
+```bash
+CONTEXTUAL_ORCHESTRATOR_COMPOSE_PROJECT_NAME=contextual-orchestrator-dev2 \
+CONTEXTUAL_ORCHESTRATOR_PORT=8001 docker compose up --build --wait
+```
+
+Accelerator runtimes stay separate: CPU PyO3 arithmetic is in-process, macOS
+MLX is an authenticated native-host provider, and CUDA/OpenCL workers require
+measured vendor evidence before overlays or Kubernetes manifests are added.
+See [ADR 0006](docs/adr/0006-native-accelerator-runtime-boundaries.md).
+
 Register provider keys separately with `register-credential`; do not put them
 in `compose.yaml` or the gateway runtime environment.
 
@@ -331,7 +345,8 @@ Grounding papers (LLM cost, routing, load balancing) live in
 
 ## Check
 
-Run the full suite with the same hash-locked pytest toolchain as CI:
+Run the full suite with the same hash-locked pytest toolchain as CI. The target
+builds and installs the Rust token/vector extension before pytest:
 
 ```bash
 make test

compose.yaml

@@ -1,4 +1,4 @@
-name: contextual-orchestrator
+name: ${CONTEXTUAL_ORCHESTRATOR_COMPOSE_PROJECT_NAME:-contextual-orchestrator}
 
 services:
   postgres:

contextual_orchestrator/__init__.py

@@ -1,5 +1,12 @@
 """Public package exports for the contextual orchestration runtime."""
 
+from pkgutil import extend_path
+
+# The ABI3 Rust extension is installed by a wheel while local development and
+# CI import Python sources from the checkout. Extend the regular package path so
+# the source package can find the wheel-owned native submodule.
+__path__ = extend_path(__path__, __name__)
+
 from .batch_routing import (
     BatchJob,
     BatchRequest,
@@ -10,6 +17,7 @@
     LocalEmbeddingBatchBackend,
     PgLlmBatchBackend,
     PgLlmBatchEmbeddingBackend,
+    ProviderEmbeddingBatchBackend,
     RoutingDecision,
     RoutingHints,
     RoutingPolicy,
@@ -46,7 +54,7 @@
     parse_reasoning_effort_profile,
     snapshot_role_effort_catalog,
 )
-from .token_counting import HeuristicTokenCounter, build_token_counter
+from .token_counting import HeuristicTokenCounter, RustCl100kTokenCounter, build_token_counter
 from .response_cache import (
     RedisResponseCacheProvider,
     ResponseCacheProvider,
@@ -103,6 +111,7 @@
     "InMemoryConfigStore",
     "get_config_store",
     "HeuristicTokenCounter",
+    "RustCl100kTokenCounter",
     "build_token_counter",
     "ResponseCacheProvider",
     "RedisResponseCacheProvider",
@@ -121,6 +130,7 @@
     "EmbeddingBatchResultItem",
     "LocalEmbeddingBatchBackend",
     "PgLlmBatchEmbeddingBackend",
+    "ProviderEmbeddingBatchBackend",
     "heuristic_embedding",
     "build_embeddings_jsonl_body",
     "cheapest_upstream",

contextual_orchestrator/__main__.py

@@ -282,13 +282,17 @@ def _discover_models_command(argv: list[str]) -> None:
 
 
 def _auto_discover_runtime_agents(orchestrator: TaskOrchestrator) -> dict[str, list[str]]:
-    """Discover and activate only models with explicit chat capability evidence."""
+    """Activate models carrying explicit provider-declared runtime capabilities."""
     discovered, _errors = discover_all_models()
-    chat_models = [model for model in discovered if "chat" in model.capabilities]
+    capable_models = [
+        model
+        for model in discovered
+        if {"chat", "embedding"}.intersection(model.capabilities)
+    ]
     existing_ids = {agent.id for agent in orchestrator.candidates}
     agents = [
         replace(agent_from_discovered(model), disabled=False)
-        for model in chat_models
+        for model in capable_models
         if agent_id_for(model) not in existing_ids
     ]
     if not agents:
@@ -374,7 +378,7 @@ def main(argv: list[str] | None = None) -> None:
     parser.add_argument(
         "--auto-discover-model-agents",
         action="store_true",
-        help="discover source-declared chat-capable models at startup and activate them",
+        help="discover source-declared chat- and embedding-capable models at startup and activate them",
     )
     args = parser.parse_args(arguments)
 

contextual_orchestrator/api_contract.py

@@ -352,15 +352,54 @@
         "/api/v1/provider_readiness/latest": {
             "get": {
                 "operationId": "get_latest_provider_readiness",
-                "summary": "Read or explicitly refresh bounded provider chat readiness",
+                "summary": "Read cached provider chat readiness without starting probes",
                 "security": [{"admin_bearer_auth": []}],
                 "parameters": [{
                     "name": "refresh",
                     "in": "query",
                     "required": False,
                     "schema": {"type": "boolean", "default": False},
                 }],
-                "responses": {"200": {"description": "Provider readiness report"}},
+                "responses": {
+                    "200": {"description": "Provider readiness report"},
+                    "409": {"description": "Inline refresh must use an asynchronous job"},
+                },
+            }
+        },
+        "/api/v1/provider_readiness_refreshes": {
+            "post": {
+                "operationId": "create_provider_readiness_refresh",
+                "summary": "Probe an explicit provider access list asynchronously",
+                "security": [{"admin_bearer_auth": []}],
+                "responses": {"202": {"description": "Readiness refresh accepted"}},
+            }
+        },
+        "/api/v1/provider_readiness_refreshes/{job_id}": {
+            "get": {
+                "operationId": "get_provider_readiness_refresh",
+                "summary": "Poll readiness refresh progress",
+                "security": [{"admin_bearer_auth": []}],
+                "parameters": [{
+                    "name": "job_id",
+                    "in": "path",
+                    "required": True,
+                    "schema": {"type": "string"},
+                }],
+                "responses": {"200": {"description": "Readiness refresh progress"}},
+            }
+        },
+        "/api/v1/provider_readiness_refreshes/{job_id}/cancel": {
+            "post": {
+                "operationId": "cancel_provider_readiness_refresh",
+                "summary": "Cancel readiness refresh work",
+                "security": [{"admin_bearer_auth": []}],
+                "parameters": [{
+                    "name": "job_id",
+                    "in": "path",
+                    "required": True,
+                    "schema": {"type": "string"},
+                }],
+                "responses": {"200": {"description": "Readiness refresh cancelled"}},
             }
         },
         "/api/v1/analytics_snapshots/latest": {
@@ -746,6 +785,16 @@
                                         ]
                                     },
                                     "inputs": {"type": "array", "items": {"type": "string"}},
+                                    "input_attributions": {
+                                        "type": "array",
+                                        "items": {"type": "object"},
+                                        "description": "Index-aligned cost attribution for each input.",
+                                    },
+                                    "input_metadata": {
+                                        "type": "array",
+                                        "items": {"type": "object"},
+                                        "description": "Index-aligned provenance metadata returned with each output.",
+                                    },
                                     "endpoint": {"type": "string", "description": "batch endpoint alias"},
                                     "metadata": {
                                         "type": "object",
@@ -766,7 +815,13 @@
                             "input_part_counts, map_reduce}"
                         )
                     },
-                    "202": {"description": "Batch accepted; poll GET /v1/batch/embeddings/{batch_id}"},
+                    "202": {
+                        "description": (
+                            "Batch accepted; poll GET /v1/batch/embeddings/{batch_id} "
+                            "after the returned poll_after_ms; terminal results remain "
+                            "available for job_retention_ms"
+                        )
+                    },
                     "503": {"description": "No enabled embedding-capable agent is available"},
                 },
             }
@@ -782,14 +837,32 @@
                 "responses": {
                     "200": {
                         "description": (
-                            "{batch_id, status, embeddings:[[...]], cost_micro_usd, "
-                            "token_counts, input_part_counts, map_reduce}"
+                            "{batch_id, status, poll_after_ms, job_retention_ms, embeddings:[[...]], "
+                            "cost_micro_usd, token_counts, input_part_counts, map_reduce}"
                         )
                     },
                     "404": {"description": "Embeddings batch not found"},
                 },
             }
         },
+        "/v1/batch/embeddings/capabilities": {
+            "get": {
+                "operationId": "get_batch_embeddings_capabilities",
+                "summary": "Read enforced bulk request and provider partition ceilings",
+                "security": [{"inference_bearer_auth": []}],
+                "responses": {
+                    "200": {
+                        "description": (
+                            "Enforced max_request_body_bytes, max_tokens_per_part, "
+                            "max_chars_per_part, rate-budget-derived poll_after_ms, "
+                            "configured job_retention_ms, and resolved provider model, "
+                            "max_inputs, max_total_tokens, tokenizer, and "
+                            "capability_authority_url when available"
+                        )
+                    }
+                },
+            }
+        },
         "/api/v1/access_reports/{workflow_run_id}": {
             "get": {
                 "operationId": "get_access_report",