llm-connect/contracts/functional/messages-admission.md

# Owner-hosted Messages admission

`llm_connect.messages_gate` supplies an opt-in, stdlib-only Messages listener.
It is separate from `LLMServer` and is never enabled by normal `serve` mode.
The work record is `LLM-WP-0009`; factory integration is HFACT-WP-0001-T01 and
REINAH-WP-0003-T05/T06.

## Contract

The owner constructs immutable `MessagesPolicy` with an exact model, tariff
reference, maximum admitted context/output, integer micro-USD per-token upper
rates, explicit beta allowlist, body limit and request timeout. There is no
built-in live price, FX source, token estimate or default beta grant. Input rates
must conservatively cover input, both cache-write lifetimes, cache reads and all
accepted multipliers. Accepted provider limits and tariff validity remain an
operator policy responsibility; a fixture policy cannot establish them.

`RequestMeter.reserve_request(token, policy_sha256, liability_microusd)` must
atomically check authority and remaining parent capacity, persist the hold and
return an opaque receipt **before** the transport opens a provider connection.
The reserved amount is full context times the maximum input rate plus requested
output times the maximum output rate. This deliberately trades utilization for
a bound that does not depend on unproven local token estimation.

`request_active(receipt)` checks the run and lease. `complete_request(receipt,
observed_microusd)` records trusted terminal accounting while retaining the full
reservation. Any exception, cancellation, non-200 response, truncated stream,
unknown fee/model/content feature or missing usage leaves an unknown hold. A
retry is another request and cannot be forwarded through an unresolved hold.
The forwarder neither retries nor follows redirects; it ignores proxy variables
and accepts only a fixed HTTPS provider origin (loopback HTTP is explicit for
tests). Only owner headers and the accepted beta list reach that origin.

The listener accepts `POST /v1/messages[?beta=true]` with an opaque `x-api-key`
route token. No `/execute`, arbitrary URL, alternate authorization or compressed
request route is available. Duplicate JSON/header fields and unsupported API
features refuse. The supported subset is streaming text, custom client tools,
ordinary thinking/effort and ephemeral cache controls. Context management is
limited to the CLI's exact keep-all-thinking form; server compaction, server
tools, media/URL blocks, model fallback, extended context and extra paid features
need separate implementation and accepted bounds.

SSE terminal accounting includes input, output, cache creation and cache reads;
output deltas are cumulative. The final stream event is held until the durable
completion returns so a following tool-loop request cannot race that write.
Request bodies, provider bodies and credentials are not written to logs or
request receipts. Client metadata is untrusted context, never authorization.

## Owning integration and remaining admission

Rein's `RequestLedger` implements this protocol as child holds in the existing
private SQLite envelope. Parent reservations continue to account for daily/total
capacity; child requests cannot mint a second allowance. Its explicit schema
provisioning never runs automatically on missing state. A trusted owner binds
one route to the admitted parent run, exact policy digest and queue lease expiry;
the parent already binds worker, definition, project, target, grant and runtime
digests. Route tokens are random, stored only as hashes, cannot be rebound or
renewed by the workload, and revoke on parent terminal observation.

The next integration must host the listener in the trusted owner boundary, keep
provider credentials and ledger inaccessible to the sandbox, deliver only its
run token/base URL, bind actual lease loss to route revocation, and prove direct
provider and alternate-route denial. This module does not install a listener,
configure a sandbox, resolve credentials, or promote a profile. The installed
CLI fixture demonstrates transport/ledger behavior in a fake-provider namespace;
it does **not** prove secret or network separation between real owner/workload
processes. LLM-WP-0009-T03 retains this owner integration return.

## Verification and primary protocol references

`tests/test_messages_gate.py` exercises the policy, protocol and bounded refusal.
Rein's `tests/test_request_admission.py` exercises actual HTTP and SQLite capacity,
concurrency, recovery, lease loss and uncertain outcomes. Its opt-in
`tests/test_native_cli_boundary.py` also uses the installed 2.1.266 CLI: the
USD 0.01 counterexample is refused before any fake upstream call, while a
permitted two-request tool session succeeds. All rates/FX/keys in those tests
are synthetic and have no production authority.

Protocol references inspected 2026-09-09:
[Messages](https://platform.claude.com/docs/en/api/messages/create),
[streaming](https://platform.claude.com/docs/en/build-with-claude/streaming),
[context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing),
[prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).

## Private Unix hosting

`MessagesServer(..., unix_path=Path(...))` binds AF_UNIX only, mode 0600 inside
an owner-owned mode 0700 directory. It refuses an existing path rather than
unlinking another listener, and removes only its own socket inode on stop.
At most 16 request handlers are active; idle header reads time out. TCP host/port
selection cannot coexist with Unix mode. The protocol and durable meter interface
are unchanged. Rein's MessagesOwner supplies the private listener, accepted lease
and cancellation hooks; sand-boxer mounts only the socket and enforces sole routing.
The provider key and ledger remain outside the workload. This source/library path
is tested with a fake provider; accepted custody, protected bootstrap/artifact and
Railiance placement are still required by LLM-WP-0009-T03.