{ "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" } }