# Architecture

## Runtime path

```text
request
  -> size/rate/concurrency limits
  -> tenant credential
  -> tenant-scoped card stack
  -> before-phase cards
  -> compatibility batch key
  -> backend
       evidence sandbox
       Hugging Face + KV cache + bounded hooks + PEFT registry
       vLLM + signed-card per-request LoRA routing
  -> after-phase cards
  -> content-addressed receipt
  -> tenant-scoped receipt store
```

The central invariant is that a request can only see its tenant's assigned card
stack, state, and receipts. Card ordering is persisted and included in the stack
digest, so changing order creates a different execution identity.

## Card phases

`before` cards may validate or enrich a request. `activation` cards may execute
only on a backend that declares activation support. `after` cards validate,
redact, or transform a response. A backend rejects a stack before inference if
it cannot execute a required phase.

This avoids the dangerous failure mode where a deployment silently ignores a
card but still returns a successful response.

## Batching

The scheduler groups requests by the digest of their ordered card stack and
active intervention specs. Different tenants can share a microbatch only when
they resolve to the same effective stack. An assigned metadata-routed adapter
therefore produces distinct inactive and active batch identities. The backend
still receives the tenant and request identity for receipt attribution.

The first implementation batches over a short bounded window. Distributed
scheduling is intentionally outside the 0.1 boundary.

## Hugging Face execution

`TransformersBackend` discovers decoder blocks, freezes host parameters, uses
normal `model.generate(..., use_cache=True)`, records peak CUDA allocation, and
installs trusted activation hooks inside an `ExitStack` while holding the model
mutation lock. Hook handles are removed before the lock is released.

The current activation implementation supports bounded token-direction steering.
It is an execution-path proof, not a claim that steering alone is a safety
system.

PEFT adapters use a two-sided boundary. A signed adapter card commits the
artifact SHA-256 and activation policy. The runtime never accepts a local path
from that package. Instead, the operator registers `card_id -> local directory`
when constructing the backend. Before inference, the backend recomputes the
adapter hash, selects at most one adapter, and otherwise executes inside PEFT's
disabled-adapter context. The recommended typed-envelope activation mode
requires an exact schema, operator type, term, boolean apply flag, and prompt
commitment; text inside the prompt cannot activate the adapter. A card may also
commit the application system-prompt hash. The backend applies that system
contract through the tokenizer's own chat template and refuses a hash mismatch.
Signed card IDs are hashed into PyTorch-safe internal module names. Local model
directories require an explicit path-free label before any receipt can be
issued.

## vLLM execution

`VLLMBackend` targets the OpenAI-compatible server and maps one active signed
adapter card to its already-governed served-model/LoRA name. It refuses residual
cards because the public HTTP API cannot provide the lifecycle guarantees
Backplane requires. Request metadata cannot override the configured base model,
and an active adapter card without a signed `served_model` fails closed.

The next engine milestone is a vLLM worker plugin that:

1. loads signed declarative card state;
2. compiles compatible stacks into batch keys;
3. applies bounded internal operations inside the worker;
4. returns per-request telemetry to the control plane;
5. removes all card state on rollout or failure.

## Persistence

SQLite in WAL mode provides the single-node boundary. Tenant credentials are
scrypt-derived; raw keys are returned only at creation. Assignments, memory, and
receipts carry a tenant foreign key. A future clustered deployment can replace
the store behind the same interface.

