validation-broker-contract.json

{
  "schema": "pi.validation_broker.contract.v1",
  "request_schema": "pi.validation_broker.request.v1",
  "slot_schema": "pi.validation_broker.slot.v1",
  "decision_schema": "pi.validation_broker.decision.v1",
  "fault_corpus_schema": "pi.validation_broker.fault_corpus.v1",
  "fault_event_schema": "pi.validation_broker.fault_event.v1",
  "cli_status_schema": "pi.validation_broker.cli_status.v1",
  "cli_plan_schema": "pi.validation_broker.cli_plan.v1",
  "cli_lease_mutation_schema": "pi.validation_broker.cli_lease_mutation.v1",
  "stress_profile_corpus_schema": "pi.validation_broker.stress_profile_corpus.v1",
  "stress_budget_report_schema": "pi.validation_broker.stress_budget_report.v1",
  "stress_evidence_schema": "pi.validation_broker.stress_evidence.v1",
  "contract_version": "1.0.0",
  "bead_id": "bd-gusp4.1",
  "parent_bead_id": "bd-gusp4",
  "purpose": "live_validation_admission_advisory_not_ci_or_rch_replacement",
  "summary": "Defines the source inventory and machine contract for an advisory validation slot broker. The broker helps agents decide whether to run, wait, narrow, coalesce, or recover validation work; it does not replace RCH, cargo_headroom.sh, Beads, Agent Mail, Doctor, runpacks, CI, UBS, or required repo gates.",
  "non_goals": [
    "replace_rch_or_run_cargo_without_explicit_agent_action",
    "replace_cargo_headroom_or_doctor_resource_preflight",
    "replace_beads_or_agent_mail_as_sources_of_truth",
    "replace_ci_or_release_claim_integrity_gates",
    "suppress_required_cargo_clippy_fmt_ubs_or_ledger_checks",
    "treat_reused_validation_evidence_as_green_when_provenance_mismatches",
    "infer_missing_source_facts_without_degraded_uncertainty",
    "delete_logs_sessions_mail_archives_build_artifacts_or_user_files"
  ],
  "required_source_ids": [
    "beads_jsonl",
    "beads_db",
    "agent_mail_reservations",
    "rch_status",
    "rch_queue",
    "cargo_headroom_preflight",
    "doctor_swarm_preflight",
    "git_status",
    "validation_artifact_manifest",
    "cargo_command_request",
    "agent_identity"
  ],
  "source_status_contract": {
    "required_fields": [
      "source_id",
      "source_kind",
      "path",
      "availability",
      "freshness_state",
      "observed_at_utc",
      "source_hash",
      "authoritative_for",
      "redaction_state",
      "degraded_reasons",
      "suppressed_claims"
    ],
    "allowed_availability": [
      "available",
      "unavailable",
      "partial",
      "malformed",
      "stale",
      "not_configured"
    ],
    "allowed_freshness_states": [
      "current",
      "stale",
      "missing",
      "malformed",
      "freshness_unknown"
    ],
    "missing_source_policy": "Missing, malformed, unavailable, partial, stale, or freshness_unknown sources must remain explicit source_status rows. The broker must not infer or invent facts from missing inputs. Decisions that depend on missing authority must be degraded_block, wait, narrow, or stale_recover; they must not become allow or coalesce.",
    "minimum_required_authority_for_allow": [
      "cargo_command_request",
      "git_status",
      "cargo_headroom_preflight",
      "rch_status",
      "rch_queue",
      "validation_artifact_manifest"
    ]
  },
  "authoritative_source_boundaries": [
    {
      "source_id": "beads_jsonl",
      "authoritative_for": [
        "issue_status",
        "priority",
        "dependencies",
        "assignee"
      ],
      "broker_boundary": "May prioritize and label validation requests; must not claim, close, reopen, or rewrite Beads except through explicit br workflow outside read-only plan mode."
    },
    {
      "source_id": "agent_mail_reservations",
      "authoritative_for": [
        "file_reservation_intent",
        "build_slot_claims",
        "agent_coordination_messages"
      ],
      "broker_boundary": "May report reservation conflicts and unavailable mail; must not treat Agent Mail absence as permission to collide with active Beads or dirty files."
    },
    {
      "source_id": "rch_status",
      "authoritative_for": [
        "worker_availability",
        "remote_offload_health"
      ],
      "broker_boundary": "May advise backoff or remote-only validation; must not replace RCH scheduling or hide fail-open local execution."
    },
    {
      "source_id": "cargo_headroom_preflight",
      "authoritative_for": [
        "target_dir_headroom",
        "tmpdir_headroom",
        "repo_target_rejection"
      ],
      "broker_boundary": "May deny or narrow local validation when scratch space is unsafe; must not bypass cargo_headroom.sh safeguards."
    },
    {
      "source_id": "doctor_swarm_preflight",
      "authoritative_for": [
        "cgroup_cpu",
        "cpuset_size",
        "memory_limit",
        "numa_topology",
        "recommended_budgets"
      ],
      "broker_boundary": "May consume budgets and caveats; must not replace Doctor diagnostics or resource evidence."
    },
    {
      "source_id": "git_status",
      "authoritative_for": [
        "head_commit",
        "branch",
        "dirty_paths",
        "staged_paths"
      ],
      "broker_boundary": "May reject reusable evidence when git identity or dirty-path scope differs; must not stash, reset, clean, or checkout files."
    },
    {
      "source_id": "validation_artifact_manifest",
      "authoritative_for": [
        "command_exit_code",
        "artifact_paths",
        "artifact_hashes",
        "runner_identity",
        "feature_flags"
      ],
      "broker_boundary": "May coalesce only when provenance matches; must not convert absent or failed artifacts into success."
    }
  ],
  "request_contract": {
    "required_top_level_keys": [
      "schema",
      "request_id",
      "generated_at",
      "agent_name",
      "bead_id",
      "cwd",
      "git_head",
      "command",
      "command_class",
      "requested_scope",
      "feature_flags",
      "target_dir",
      "tmpdir",
      "runner_requirement",
      "dirty_worktree_policy",
      "evidence_requirements"
    ],
    "allowed_command_classes": [
      "cargo_check",
      "cargo_clippy",
      "cargo_test",
      "cargo_fmt_check",
      "ubs_staged",
      "beads_ledger_reconcile",
      "script_self_test",
      "custom_validation"
    ],
    "allowed_runner_requirements": [
      "rch_required",
      "local_allowed",
      "read_only",
      "no_compile"
    ],
    "dirty_worktree_policy": "Requests must declare whether unrelated dirty paths are allowed, forbidden, or ignored. Reusable evidence must name dirty-path scope so agents do not accidentally rely on validation over a different working tree."
  },
  "slot_lease_contract": {
    "required_top_level_keys": [
      "schema",
      "slot_id",
      "state",
      "owner_agent",
      "bead_id",
      "command_fingerprint",
      "environment_fingerprint",
      "git_head",
      "target_dir",
      "tmpdir",
      "runner",
      "rch_job_id",
      "started_at_utc",
      "heartbeat_at_utc",
      "expires_at_utc",
      "artifacts",
      "release_reason"
    ],
    "allowed_states": [
      "requested",
      "active",
      "reusable",
      "stale",
      "failed",
      "released",
      "expired",
      "degraded"
    ],
    "stale_policy": {
      "heartbeat_required": true,
      "stale_requires_explicit_reason": true,
      "stale_recovery_must_not_kill_processes": true,
      "safe_next_actions": [
        "wait_for_owner",
        "request_owner_update",
        "open_new_non_overlapping_slot",
        "surface_blocker",
        "rerun_after_provenance_mismatch"
      ]
    }
  },
  "decision_contract": {
    "required_top_level_keys": [
      "schema",
      "decision_id",
      "request_id",
      "generated_at",
      "decision",
      "confidence",
      "reasons",
      "source_statuses",
      "required_actions",
      "reusable_slot",
      "coalesced_artifacts",
      "rejected_reusable_slots",
      "suppressed_claims",
      "no_claims"
    ],
    "allowed_decisions": [
      "allow",
      "wait",
      "coalesce",
      "narrow",
      "deny_local_fallback",
      "stale_recover",
      "degraded_block"
    ],
    "coalescing_equivalence_fields": [
      "command_fingerprint",
      "cwd",
      "git_head",
      "feature_flags",
      "target_dir",
      "tmpdir",
      "runner",
      "rust_toolchain",
      "environment_fingerprint",
      "artifact_schema",
      "artifact_hash"
    ],
    "required_no_claims": [
      "not_ci_success",
      "not_release_performance_evidence",
      "not_dropin_certification_evidence",
      "not_permission_to_skip_required_gates",
      "not_permission_to_modify_other_agents_files"
    ]
  },
  "fault_corpus_contract": {
    "corpus_path": "tests/golden_corpus/validation_broker/fault_corpus.json",
    "event_log_path": "tests/golden_corpus/validation_broker/fault_events.jsonl",
    "schema": "pi.validation_broker.fault_corpus.v1",
    "event_schema": "pi.validation_broker.fault_event.v1",
    "required_faults": [
      "agent_mail_unavailable",
      "rch_queue_saturated",
      "rch_fail_open_local_fallback",
      "stale_pre_commit_ubs",
      "stuck_cargo_clippy",
      "insufficient_tmpdir",
      "target_dir_collision",
      "reusable_provenance_mismatch",
      "duplicate_broad_gate_request",
      "equivalent_reusable_artifact"
    ],
    "required_decisions": [
      "allow",
      "wait",
      "coalesce",
      "narrow",
      "deny_local_fallback",
      "stale_recover",
      "degraded_block"
    ],
    "required_rejected_reusable_slot_reasons": [
      "command_fingerprint_mismatch",
      "environment_fingerprint_mismatch",
      "cwd_mismatch",
      "git_head_mismatch",
      "feature_flags_mismatch",
      "target_dir_mismatch",
      "tmpdir_mismatch",
      "runner_mismatch",
      "rust_toolchain_mismatch",
      "artifact_schema_mismatch",
      "artifact_hash_mismatch"
    ],
    "artifact_manifest_policy": "Every fault scenario must point at durable corpus and event-log artifacts and name expected decisions, reasons, actions, source statuses, policy fields, reusable slots, coalesced artifacts, and rejected reusable slot mismatch reasons when those fields are material to the fault."
  },
  "stress_budget_contract": {
    "profile_corpus_path": "tests/golden_corpus/validation_broker/stress_profiles.json",
    "profile_corpus_schema": "pi.validation_broker.stress_profile_corpus.v1",
    "report_path": "docs/evidence/validation-broker-stress-budgets.json",
    "report_schema": "pi.validation_broker.stress_budget_report.v1",
    "entry_schema": "pi.validation_broker.stress_evidence.v1",
    "bead_id": "bd-gusp4.9",
    "required_profiles": [
      "synthetic_64c_256gb_nominal",
      "synthetic_64c_256gb_saturated",
      "synthetic_64c_256gb_missing_store_bytes"
    ],
    "required_budget_fields": [
      "max_plan_latency_ms",
      "max_status_latency_ms",
      "max_stale_scan_ms",
      "max_slot_store_bytes",
      "max_memory_growth_bytes",
      "min_request_throughput_per_minute"
    ],
    "required_measurement_fields": [
      "plan_latency_ms",
      "status_latency_ms",
      "stale_scan_ms",
      "request_throughput_per_minute",
      "slot_store_bytes",
      "memory_growth_bytes",
      "duplicate_gate_opportunities"
    ],
    "required_cache_fields": [
      "cache_key",
      "cache_status",
      "ttl_seconds",
      "input_fingerprint"
    ],
    "required_scenario_guards": [
      "synthetic_data",
      "no_live_rch_mutation",
      "provider_calls",
      "live_mutations",
      "release_claim_allowed"
    ],
    "required_verdicts": [
      "pass",
      "fail",
      "blocked"
    ],
    "required_guards": [
      "synthetic_only",
      "not_release_performance_evidence",
      "not_ci_success",
      "does_not_replace_rch_doctor_cargo_headroom_ci_ubs_beads_agent_mail",
      "missing_data_blocks_measurements"
    ],
    "required_no_claims": [
      "not_ci_success",
      "not_release_performance_evidence",
      "not_dropin_certification_evidence",
      "not_permission_to_skip_required_gates",
      "not_permission_to_modify_other_agents_files"
    ],
    "missing_data_policy": "Synthetic stress evidence with missing profile inputs must emit verdict=blocked, list missing_data, leave measurement fields null, and must not become pass or release performance evidence.",
    "claim_policy": "Stress-budget evidence is an engineering signal for validation-broker sizing and backpressure only. It is not release-facing performance evidence and cannot replace RCH, Doctor, cargo_headroom.sh, CI, UBS, Beads, Agent Mail, or required repo gates."
  },
  "cli_surface_contract": {
    "subcommand": "validation-broker",
    "actions": [
      "status",
      "plan",
      "acquire",
      "renew",
      "release"
    ],
    "format_modes": [
      "text",
      "json"
    ],
    "output_path_policy": "All --out-json and --out-text paths must refuse to overwrite existing files.",
    "plan_mode": {
      "read_only": true,
      "required_inputs": [
        "ValidationAdmissionRequestContext JSON",
        "ValidationBrokerInputSnapshot JSON",
        "ValidationSlotStore JSONL"
      ],
      "required_next_actions": [
        "run_now",
        "wait",
        "coalesce_with_reusable_slot",
        "narrow_scope",
        "surface_blocker",
        "recover_stale_slot_or_bead"
      ]
    },
    "lease_mutations": {
      "allowed_actions": [
        "acquire",
        "renew",
        "release"
      ],
      "mutation_shape": "append_slot_record_only",
      "degraded_store_policy": "Lease mutations must refuse to append when the slot store is degraded."
    }
  },
  "doctor_runpack_projection_contract": {
    "doctor_schema": "pi.doctor.validation_broker_posture.v1",
    "runpack_optional_source_id": "validation_broker",
    "autopilot_optional_source_id": "validation_broker",
    "required_projection_fields": [
      "source_status",
      "current_slots",
      "degraded_reasons",
      "duplicate_gate_opportunities",
      "stale_build_warnings",
      "recommended_next_actions",
      "guards"
    ],
    "required_guards": [
      "advisory_only",
      "no_live_mutation",
      "not_ci_success",
      "not_release_claim_evidence",
      "does_not_replace_rch_doctor_beads_agent_mail"
    ],
    "authority_boundary": "Doctor, runpack, and autopilot input-pack projections are advisory handoff summaries. They may surface source status, current slot counts, degraded reasons, duplicate-gate opportunities, stale build warnings, and recommended next actions, but they must not replace RCH, Doctor, Beads, Agent Mail, CI, UBS, cargo_headroom.sh, or release-claim gates."
  },
  "mutation_policy": {
    "plan_mode_live_mutation_allowed": false,
    "lease_mode_allowed_mutations": [
      "append_slot_record",
      "renew_own_slot",
      "release_own_slot",
      "record_decision_artifact"
    ],
    "forbidden_mutations": [
      "git_reset",
      "git_clean",
      "file_delete",
      "kill_other_agent_process",
      "stash_or_checkout_other_agent_work",
      "rewrite_mail_archive",
      "rewrite_beads_without_br"
    ]
  },
  "redaction_contract": {
    "required_redacted_classes": [
      "api_key",
      "bearer_token",
      "oauth_token",
      "mail_body",
      "private_prompt",
      "absolute_home_path_when_not_needed",
      "large_command_output_body"
    ],
    "safe_to_record": [
      "command_argv_fingerprint",
      "exit_code",
      "duration_ms",
      "artifact_path",
      "artifact_sha256",
      "source_status",
      "degraded_reason",
      "bead_id"
    ]
  },
  "overlap_boundaries": [
    {
      "surface": "rch",
      "boundary": "Broker may advise and coalesce validation requests, but RCH remains the remote execution system and worker source of truth."
    },
    {
      "surface": "cargo_headroom",
      "boundary": "Broker may consume preflight output, but cargo_headroom.sh remains the scratch-space guard for cargo commands."
    },
    {
      "surface": "doctor",
      "boundary": "Broker may project advisory posture into Doctor, but Doctor remains the environment diagnostic authority."
    },
    {
      "surface": "runpack",
      "boundary": "Broker may contribute handoff summaries, but runpacks remain operator bundles and not release-claim evidence."
    },
    {
      "surface": "swarm_replay_lab",
      "boundary": "Broker decisions may later be replayed offline, but this contract defines live advisory admission rather than replay simulation."
    },
    {
      "surface": "ci",
      "boundary": "Broker output is never CI success and cannot replace required release or claim-integrity gates."
    }
  ],
  "must_requirements": [
    {
      "id": "VALIDBROKER-MUST-001",
      "description": "The contract declares advisory purpose and replacement boundaries for RCH, cargo_headroom, Beads, Agent Mail, Doctor, runpacks, CI, UBS, and repo gates.",
      "validated_by": [
        "purpose",
        "non_goals",
        "overlap_boundaries"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-002",
      "description": "Every authoritative source has an explicit source_status shape with availability, freshness, hash, authority, redaction, degraded reasons, and suppressed claims.",
      "validated_by": [
        "required_source_ids",
        "source_status_contract"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-003",
      "description": "Missing, malformed, stale, partial, or unavailable sources fail closed and cannot be inferred into allow or coalesce decisions.",
      "validated_by": [
        "source_status_contract.missing_source_policy",
        "decision_contract.allowed_decisions"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-004",
      "description": "Validation requests carry command, scope, git, target/tmp, runner, dirty-worktree, and evidence requirements before admission.",
      "validated_by": [
        "request_contract.required_top_level_keys"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-005",
      "description": "Slot leases preserve command/environment fingerprints, owner, heartbeat, expiry, artifacts, and safe stale recovery states.",
      "validated_by": [
        "slot_lease_contract.required_top_level_keys",
        "slot_lease_contract.allowed_states",
        "slot_lease_contract.stale_policy"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-006",
      "description": "Coalesced gates require matching command, git, feature, target/tmp, runner, toolchain, environment, schema, and artifact hashes.",
      "validated_by": [
        "decision_contract.coalescing_equivalence_fields"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-007",
      "description": "Plan mode is read-only and forbidden mutations include destructive git/filesystem actions, killing other agents' processes, and rewriting sources without their normal tools.",
      "validated_by": [
        "mutation_policy"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-008",
      "description": "Broker evidence redacts secrets, mail bodies, private prompts, unnecessary home paths, and large command output bodies while preserving fingerprints and exit metadata.",
      "validated_by": [
        "redaction_contract"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-009",
      "description": "The CLI surface exposes status, read-only plan, and explicit lease mutation actions with stable text/JSON output and overwrite refusal for output artifacts.",
      "validated_by": [
        "cli_surface_contract",
        "mutation_policy"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-010",
      "description": "Build-storm, stale-slot, local-fallback, headroom, duplicate, and reusable-artifact faults are frozen in a golden corpus with event-log evidence and rejected-reuse diagnostics.",
      "validated_by": [
        "fault_corpus_contract",
        "decision_contract.required_top_level_keys"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-011",
      "description": "Doctor, runpack, and dry-run autopilot projections expose broker posture as advisory source status, slot counts, stale warnings, duplicate-gate opportunities, and next actions without replacing operational or release authorities.",
      "validated_by": [
        "doctor_runpack_projection_contract",
        "overlap_boundaries"
      ]
    },
    {
      "id": "VALIDBROKER-MUST-012",
      "description": "Large-host validation-broker stress budgets cover nominal, saturated, and missing-data profiles with deterministic schema-governed evidence, cache/provenance fields, and explicit non-release-claim caveats.",
      "validated_by": [
        "stress_budget_contract",
        "stress_budget_contract.report_path"
      ]
    }
  ],
  "downstream_dependencies": {
    "unblocked_by_this_contract": [
      "bd-gusp4.2",
      "bd-gusp4.3",
      "bd-gusp4.6",
      "bd-gusp4.7",
      "bd-gusp4.8",
      "bd-gusp4.9"
    ],
    "fault_corpus_bead": "bd-gusp4.6",
    "doctor_runpack_projection_bead": "bd-gusp4.7",
    "stress_budget_bead": "bd-gusp4.9",
    "final_closeout_bead": "bd-gusp4.11"
  }
}