Skip to content
PETROVA

eva.consumption.v1 vendor schema widened for failing status and observed field/length drift

Date: 2026-09-22 Status: ratified Supersedes: none Superseded-by: none — current

Context

Section titled “Context”

scripts/doctor-all.sh’s 44-row fleet check flagged 4 consumer repos with .petrova/contract.yaml schema errors (2026-09-22 session, prior handoff left these un-triaged). Running node cli/dist/index.js doctor --repo <clone> --commit-state locally against kahn-hq, stratt-hq, and smo1-io found real AJV violations, not contract-authoring mistakes:

  • contracts/vendor/eva-consumption.v1.json’s status and surfaces.events.state enums only allow wired/pending/not_applicable. stratt-hq legitimately recorded status: failing per docs/decisions/2026-09-11-eva-events-confirmed-dark.md (the events transport is confirmed dark — a real “wired-then-degraded” state the v1 vocabulary has no room for).
  • surfaces.*.reason capped at 120 chars; observed values in stratt-hq and smo1-io run up to 264 chars, driven by re-review prose (re-reviewed 2026-09-05: ...) that the 2026-09 staleness-remediation pass legitimately added.
  • surfaces.prompts.evidence forbids a last_observed_at field that stratt-hq added per docs/decisions/2026-09-11-eva-prompts-verification-evidence-added.md — a real, decision-doc-backed addition the vendor schema never picked up.
  • Separately, contracts/contract.schema.json’s integrations.cairnet_emission block (and contracts/state.schema.json’s probe_history[].detail) had the same class of drift: newer cairnet-emit-kit evidence fields (vendored_at, auth_mode, digests_verified_at, etc.) and longer detail/reason text than the schemas declared.

The fourth flagged repo, null0-toll, is a separate authoring-completeness bug in that repo’s own contract (missing not_applicable_reason/not_applicable_review_by) — not a schema problem, tracked separately as a finding, not fixed here.

Decision

Section titled “Decision”

Widen contracts/vendor/eva-consumption.v1.json, contracts/contract.schema.json, and contracts/state.schema.json additively (no field removed, no cap tightened) to accept the states/fields/lengths repos are legitimately already recording:

  • Add failing to status and surfaces.events.state enums.
  • Raise surfaces.*.reason and not_applicable_reason/probe_history[].detail maxLength caps from 120/200 to 400 (headroom over the largest observed value, 264 chars, without going unbounded).
  • Add last_observed_at (optional) to surfaces.prompts.evidence.
  • Add optional evidence_updated_at, status_changed_at, wired_decision_doc, resolved_failure to the cairnet_emission envelope, and optional vendored_at, auth_mode, last_emitted_at, digests_verified_at, digests_verified to its evidence object.

contracts/vendor/eva-consumption.v1.json mirrors a shape eva-hq publishes (docs/decisions/2026-05-08-adopt-eva-consumption-v1.md). This decision widens the local vendor copy immediately to unblock validation; it does not itself change what eva-hq publishes. eva-hq should be told to adopt the same failing-status/reason-length/last_observed_at additions upstream so the vendor copy doesn’t stay permanently forked from the canonical source — that follow-up is not done by this doc.

Alternatives considered

Section titled “Alternatives considered”
  • Leave the schema narrow and have consumers shorten/reclassify their contract data — rejected: the flagged content (dark-transport downgrade, staleness re-review notes, verification evidence) is real, decision-doc-backed operational state; forcing it out to satisfy an under-specified schema would destroy information the repos correctly recorded.
  • Make maxLength unbounded — rejected: a cap still guards against unbounded contract bloat; 400 gives ~50% headroom over the largest observed value (264) rather than removing the guard entirely.

Consequences

Section titled “Consequences”

For code:

  • contracts/contract.schema.json, contracts/vendor/eva-consumption.v1.json, contracts/state.schema.json widened (additive only).
  • state/kahn-hq.yaml, state/stratt-hq.yaml, state/smo1-io.yaml re-swept via doctor --commit-state now that validation passes.

For docs:

  • This decision doc.
  • docs/findings/20260922-<time>-null0-toll-contract-incomplete-stub.md files the separate, unrelated null0-toll authoring gap.

For in-flight phases:

  • None.

For invariants:

  • None (no MR change; this is a schema-drift bugfix, not a governance rule change).

References

Section titled “References”
  • docs/decisions/2026-09-11-eva-events-confirmed-dark.md
  • docs/decisions/2026-09-11-eva-prompts-verification-evidence-added.md
  • docs/decisions/2026-05-08-adopt-eva-consumption-v1.md
  • docs/audit/handoff-2026-09-22.md

Sign-off

Section titled “Sign-off”
  • Subagent: claude (session_01488gmoyur1UAMfpNMgUAhC)
  • Human: alex@devarno.com on 2026-09-22 — confirms the widened caps/fields are an acceptable permanent schema change, and that eva-hq will be asked to adopt the matching upstream update.