Runtime Quick Start
Enforce Contract Policy At Runtime
Use this repo-level Runtime (edge) workflow to block strict live adaptive violations while still reporting warning-level diagnostics for review and cleanup. It is built on interfacectl, not a replacement for the canonical runtime docs.
Canonical contract source: contracts/surfaces.web.contract.json
Quick Start
- Generate runtime manifest. Build per-surface runtime policy from the canonical contract before running runtime checks.
- Validate proposed runtime changes. Pass proposed styles through runtime validation before applying them.
- Block strict violations. Return 422 when strict color/raw policy or other strict rules fail.
- Allow warning-level events with visibility. Capture warnings (for example token namespace mismatch) without blocking traffic.
- Keep icon policy enforcement at earlier lifecycle points. Icon-source policy is not enforced at Runtime (edge) in this increment; rely on Generation time + CI/CD time checks.
- Include contract provenance in violation payloads. Return contractId, version, and surfaceId for each runtime decision.
Canonical interfacectl docs
This page is a repo-local quick start. Canonical generator, validation, and runtime semantics live in the interfacectl docs.
Runtime Verification Commands
# 1) Build runtime manifest from canonical contract
pnpm run generate:runtime-manifest
# 2) Propose a runtime style change (expected strict violation)
curl -i -H "x-proposed-bg: rgba(15, 23, 42, 0.45)" \
"http://localhost:3000/adaptive/test?section=hero"
# 3) Example allow path
curl -i -H "x-proposed-bg: var(--background)" \
"http://localhost:3000/adaptive/test?section=hero"
- Runtime should block strict-policy findings only.
- Warn findings remain visible for remediation and policy hygiene.
- Runtime checks complement Generation time + CI/CD time checks, not replace them.
- Icon-source policy (`icon.source-disallowed`) is currently visible in integration/CI validation paths, not Runtime (edge).
- Concrete consumer example walkthrough: `ios/ContractChatSample/README.md`.
Status Rules
pass No findings. Continue.
warn Warnings only. Continue with visibility.
block Strict/error finding present. Stop and fix.
Consumer Runtime Example: ContractChatSample
The platform/web flow above is request-time enforcement of proposed live changes. `ContractChatSample` is a client-side consumer example where the app gates streamed content before rendering. It is testing local runtime orchestration and UI-state transitions, not model quality.
- `CoreMLStubRuntime` emits token-sized events into an async stream.
- `ChatViewModel` consumes the stream and owns transcript, footer, and cancellation state.
- `StreamingContractValidator` accepts, buffers, replaces, or rejects each chunk before it reaches the renderer.
- Render rule only approved text is appended to the UIKit assistant transcript.
ContractChatSample Event Sequence
This sample makes the runtime decision path visible in three small UI scenarios.
- `Send` Prompt submitted, chunks emitted, validator approves, assistant bubble updates incrementally, footer ends at `Complete`.
- `Cancel` Prompt submitted, footer reaches `Streaming`, cancel tapped, cancellation becomes authoritative, late completion is ignored, footer ends at `Cancelled`.
- `Blocked` Safe text renders first, a prohibited chunk is rejected, a governance/status row appears, the rejected text never renders, and the footer ends at `Complete`.
surfaces.dev docs • runtime