Billy schemas

JSON Schema 2020-12 contracts published from the Billy monorepo. Every $id resolves under this host. Machine-readable manifest at /index.json (includes per-file SHA-256 integrity hashes). Security disclosures via security.txt.

• benchmarks/schema/fixture-manifest.schema.json
  BenchFixtureManifest SHA-pinned manifest for third-party benchmark corpora. Fetched into benchmarks/.cache/<suite>/<name>/ on first run; never refetched once sha256 matches.
• benchmarks/schema/mission-fixture.schema.json
  MissionFixture Hermetic mission scenario for benchmarks/suites/mission-completion/. Specifies the objective, scripted per-phase LLM outputs (for replanner + counterpoint stubs), mocked tool responses keyed by tool+arg-hash, expected phase-graph edges, keyword recall targets, expected counterpoint triggers, and per-fixture budgets.
• benchmarks/schema/recall-corpus.schema.json
  RecallCorpus Hermetic JSONL pair for benchmarks/suites/multi-agent-memory/ `recall-at-k`. One `corpus.jsonl` of `{id, text}` docs + one `queries.jsonl` of `{id, query, gold: [doc_id, ...]}` retrieval cases. Kept deliberately minimal so a SciFact / HotpotQA subset can drop in later without touching the scorer.
• benchmarks/schema/result.schema.json
  BenchResult Canonical per-run benchmark result. Emitted by harness/reporter, consumed by the admin backend and the /admin/bench/metrics.prom exporter.
• benchmarks/schema/routing-corpus.schema.json
  RoutingCorpus Hermetic JSONL corpus for benchmarks/suites/department-routing/. Each line is one routing case: a user utterance + the fixture-expected specialist agent (and optionally the tool it should invoke first). Read line-by-line so corpora can grow without touching the schema loader.
• benchmarks/schema/rubric.schema.json
  BenchRubric F-class rubric definition. Each item scored 0..5 with an evidence link. Reviewer fills the blanks; harness uploads the result.
• benchmarks/schema/scenario.schema.json
  BenchScenario Declarative scenario spec. Loaded per suite at harness startup.
• benchmarks/schema/signal-timeline.schema.json
  SignalTimeline Hermetic signal timeline for benchmarks/suites/proactive-foresight/. Replays a sequence of foresight Signal events against a mocked clock and records the adapter's outreach decisions; fixtures declare the expected outreach moments + content keywords for the scorer.
• benchmarks/schema/tool-use-corpus.schema.json
  ToolUseCorpus Hermetic JSONL corpus for benchmarks/suites/agent-orchestration/ `tool-use-accuracy`. Each line is one function-calling case: a user query, the available tool schemas the agent should pick from, and the gold call sequence. Shape deliberately BFCL-compatible so we can graft a 20-task BFCL subset in later without touching the scorer.
• contracts/domain/substrate/substrate_state.schema.json
  SubstrateStateEnvelope Full persistence envelope written by the AI substrate controller and served via GET /api/v1/substrate/state.
• contracts/observe/telemetry/log_envelope.schema.json
  Billy Log Envelope Canonical JSON shape every Billy log emitter must produce (ADR-159).
• contracts/observe/user/events.schema.json
  Billy User Telemetry Contract Source-of-truth JSON Schema for client-emitted user events, client-session context, and typed user preferences. Generates contracts/observe/user/events.generated.ts (zod) via scripts/codegen/forward/workspace/zod/user.mjs; Go structs at services/backend/api/internal/handler/telemetry/events.go must keep field tags in sync.
• contracts/trust/vendors/vendors.schema.json
  Vendor / Data-Processor Registry (vendors.toml) Tier-0 contract for every external destination Billy dials. One source, six projections — same shape as the network DSL. Projections: • services/backend/shared/netcfg/vendors_gen.go — Go runtime (LookupVendor, MODEL_COSTS, ModelCost) • services/ai/core/foundation/io/net/_vendors_gen.py — Python runtime (lookup_vendor, MODEL_COSTS, model_cost) • services/backend/api/internal/handler/connect/admin/compliancerpc/vendors.gen.json — admin embed JSON • infra/network/vendors.json — manifest for the network DSL validators • policy/cedar/schema.cedarschema (Billy::Vendor) — entity attribute mirror (cross-checked by check_vendors_cedar_parity) • core.llm.costs.MODEL_COSTS — derived alias-expanded lookup table Cross-checks: • infra/network/checks/vendors.py — vendors.toml ↔ perimeter.firewall coverage + BAA inventory • scripts/codegen/forward/trust/vendors/lint.py — every Cedar Vendor attribute is producible from every vendor row • scripts/codegen/forward/trust/vendors/compile.py --check — byte-parity drift gate against committed projections Cost catalogue: each LLM-class vendor MAY declare a `cost` table mapping model id → cents-per-million-tokens rates. The vendor-cost-poll Forgejo workflow (.forgejo/workflows/vendor-costs.yml) refreshes these rates from `pricing_url` and opens a PR when drift is detected.
• contracts/wire/network/budget.schema.json
  Per-LLM Cost Governance (spend.budget) Per-route, per-tier, and per-tenant cost ceilings consumed by services/backend/shared/spend (Go) + services/ai/core/spend (Python). The runtime gate consults these maps before every LLM dial — see ADR-088.
• contracts/wire/network/dns.schema.json
  DNS Security Policy (records.dns) Domain CAA records (which CAs may issue for our domain) plus per-subdomain ingress topology. Per-service hostname egress lives in perimeter.firewall — never re-introduce a `resolution_policy:` block here.
• contracts/wire/network/firewall.schema.json
  Perimeter Firewall (perimeter.firewall) Per-service ingress posture + egress allowlist. The single source of truth that gen_netcfg.py compiles into AllowedEgress (Go), ALLOWED_EGRESS (Python), and netcfg.json for the Terraform perimeter module.
• contracts/wire/network/socket.schema.json
  Socket-Type Affinity (topology.socket) Per-pair socket selection (UDS / TCP localhost / HTTPS) plus the env-var + default-address wiring every consumer needs to dial each destination.
• contracts/wire/network/tls.schema.json
  TLS Posture (*.tls) Either edge TLS policy (scope: edge — public-facing protocol/HSTS/CSP) or internal transport security (scope: internal — sidecar channels, NATS/Redis posture). Discriminated by `scope`.
• contracts/wire/network/wire.schema.json
  Wire-Format Budgets (budget.wire) Per-channel timeouts, payload caps, pool sizes, and keepalive cadences. The codegen (gen_netcfg.py) flattens these into typed Go/Python/TS/Swift constants — no consumer is allowed to carry a literal that lives here.
• contracts/wire/rest/schemas/api.schema.json
  Billy API wire types
• contracts/wire/stream/sse/stream_events.schema.json
  SSE Stream Event Discriminated union of all SSE events emitted by the AI service and bridged to the frontend. Keyed on the `type` field.