CLAUDE.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/Vercel AI SDK/Eve/
12  Mastra contract-record shape; `evidence: static_contract_only` explicitly
13  denies executable proof
14- `schemas/canonical-span.schema.json` — `caveman.span.v1`, the normalized
15  evidence-plane span shared by trace intelligence and replay
16- `schemas/agent-run-receipt.schema.json` — `caveman.agent.run-receipt.v1`,
17  content-blind per-run SDK economic receipt. It is a shared wire shape, not an
18  anonymous CLI event and not a signed verified-savings receipt. Retry events
19  carry reserved spend, measured spend, and measurement basis
20- `schemas/continuous-improvement-report.schema.json` — versioned end-to-end
21  improvement report; the current generated result is E3 `inferred` /
22  `symbolic_counterfactual`. E4 `replayed_counterfactual` remains a reserved
23  actual recorded-output/sandbox shape and never means verified savings
24- `scripts/validate-schemas.mjs` — compiles every schema with AJV, validates
25  adapter fixtures, and checks their shared static contract fields
26- `package.json` — build/lint/test scripts run schema validation (no compiled output)
27 
28## Key schema fields
29 
30- `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
31- `pass_through` — boolean; forbids every transform. Outranks `capabilities`, which are retained so operator toggles keep their remembered positions
32- `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
33- `fail_policy` — `fail_open | fail_closed`; unknown values fail closed (honesty rule)
34- `limits.monthly_usd` — `{ soft, hard }` spend caps per tenant
35- `telemetry.sample_rate` — float 0–1, validated by schema minimum/maximum
36- `runtime_policies` — OPTIONAL array (additive, nothing new required): the per-task-family runtime policies delivered to SDK callers through the policy overlay and served by the gateway's `GET /sdk/v1/runtime-policy`. Guard ops are a closed set (`eq|ne|gt|gte|lt|lte|in`, AND-ed); `budget` is an advisory cap the caller enforces, never a savings figure; the renderer drops a structurally invalid policy WHOLE rather than stripping the broken guard or experiment, because either strip would widen who the policy applies to
37- `additionalProperties: true` — intentional; services and optimizers may extend the object
38 
39## Conventions
40 
41- Schema version is an integer; `policy_schema_version` returned by `cloud/control-api/internal/httpapi/server.go:372`
42- Adding a new required field is a **breaking change** — bump `version` and coordinate across control-api, SDKs, web
43- No TypeScript types generated from schema yet; the web dashboard manually mirrors the shape
44- `scripts/check-contract-compat.mjs` **at the REPO ROOT** (`make check-contract-compat`), not this package's `scripts/`, is a bounded 2020-12 compatibility gate: it proves common narrowing constraints (types, enums/consts, bounds, object/array applicators, and supported combinators/refs) and treats changed unknown assertion/applicator keywords or unresolved reference semantics as major-version review items. Metadata annotations remain non-breaking. It is intentionally not a complete JSON Schema subsumption prover; add a focused fixture before relying on a new keyword.
45 
46## Gotchas
47 
48- `fail_policy: fail_closed` aligns with repo honesty rule: unknown enum cases must fail closed, not pass through
49- `runtime_mode: record` is always pass-through (byte-safe rule); never treat it as an optimizer mode
50- 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
51- Build script validates schemas and static fixtures; it emits no artifact and
52  does not prove executable cross-harness parity
53 
54See ../../../CLAUDE.md (root)
55