AGENTS.md

1# packages/shared/contracts — shared wire contracts (JSON Schema)
2 
3Source-of-truth schemas for cross-service/SDK wire shapes:
4`schemas/policy.schema.json` covers tenant policy and
5`schemas/practice.schema.json` covers practice-library records.
6 
7## Layout
8 
9- `schemas/policy.schema.json` — JSON Schema 2020-12 for the tenant policy object (required: version, runtime_mode, fail_policy, providers, limits, retention, optimizers, telemetry, sdk)
10- `schemas/practice.schema.json` — strict JSON Schema 2020-12 for one practice record; unknown fields and enums fail closed
11- `schemas/adapter-conformance.schema.json` — static Pi/Claude contract-record
12  shape; `evidence: static_contract_only` explicitly denies executable proof
13- `scripts/validate-schemas.mjs` — compiles every schema with AJV, validates
14  adapter fixtures, and checks their shared static contract fields
15- `package.json` — build/lint/test scripts run schema validation (no compiled output)
16 
17## Key schema fields
18 
19- `capabilities` — `{ compress?, cache_hints?, routing? }` booleans, `additionalProperties: false`; the authoritative description of what a project optimizes. An unordered SET, not a stage — the three compose
20- `pass_through` — boolean; forbids every transform. Outranks `capabilities`, which are retained so operator toggles keep their remembered positions
21- `runtime_mode` — `record | recommend | shadow | canary | active | compress`; **a DERIVED display string, not an input**. Still `required` for the compat window (removal 2026-10-01) because `projects.runtime_mode` and the telemetry write validator read it. A doc carrying `capabilities` is authoritative and its `runtime_mode` derives from them; a legacy doc carrying only `runtime_mode` derives the capability set
22- `fail_policy` — `fail_open | fail_closed`; unknown values fail closed (honesty rule)
23- `limits.monthly_usd` — `{ soft, hard }` spend caps per tenant
24- `telemetry.sample_rate` — float 0–1, validated by schema minimum/maximum
25- `additionalProperties: true` — intentional; services and optimizers may extend the object
26 
27## Conventions
28 
29- Schema version is an integer; `policy_schema_version` returned by `cloud/control-api/internal/httpapi/server.go:372`
30- Adding a new required field is a **breaking change** — bump `version` and coordinate across control-api, SDKs, web
31- No TypeScript types generated from schema yet; the web dashboard manually mirrors the shape
32 
33## Gotchas
34 
35- `fail_policy: fail_closed` aligns with repo honesty rule: unknown enum cases must fail closed, not pass through
36- `runtime_mode: record` is always pass-through (byte-safe rule); never treat it as an optimizer mode
37- The six `runtime_mode` values are **not ordered**. Code comparing them for rank (`mode >= "canary"`) is a bug; the four middle values are behaviourally identical, and `shadow`/`canary` are display labels rather than traffic splits. The derivation lives in exactly one place, `cloud/internal/capability`, because the gateway, control-api, and the worker must never disagree about what a document means
38- Build script validates schemas and static fixtures; it emits no artifact and
39  does not prove executable Pi/Claude parity
40 
41See ../../../CLAUDE.md (root)
42