remote-validation-proof-ledger-contract.json

{
  "schema": "pi.remote_validation.proof_ledger_contract.v1",
  "ledger_schema": "pi.remote_validation.proof_ledger.v1",
  "entry_schema": "pi.remote_validation.proof_entry.v1",
  "example_corpus_schema": "pi.remote_validation.proof_ledger.example_corpus.v1",
  "contract_version": "1.0.0",
  "bead_id": "bd-e5le6.1",
  "parent_bead_id": "bd-e5le6",
  "purpose": "operator_remote_validation_evidence_not_release_performance_claim",
  "summary": "Defines the machine-readable ledger shape for proving whether cargo, script, UBS, or Beads-ledger validation ran, which changed paths the proof covered, whether RCH execution or local fallback was observed, and whether build artifact retrieval completed cleanly. The ledger is operator evidence for bead closeout and runpack handoff; it is not release performance evidence and does not replace RCH, cargo_headroom.sh, CI, UBS, Beads, Agent Mail, or claim-integrity gates.",
  "non_goals": [
    "replace_rch_scheduler_or_worker_logs",
    "replace_cargo_headroom_admission",
    "replace_ci_or_release_claim_integrity_gates",
    "treat_local_fallback_as_remote_proof",
    "treat_artifact_retrieval_warnings_as_clean_remote_proof",
    "hide_queue_backoff_or_stale_progress",
    "store_raw_secrets_mail_tokens_or_full_unredacted_logs",
    "support_release_facing_speed_memory_or_dropin_claims"
  ],
  "claim_boundaries": {
    "release_performance_claims_allowed": false,
    "strict_dropin_claims_allowed": false,
    "operator_closeout_claims_allowed": true,
    "required_phrase": "operator evidence only; not release performance evidence",
    "policy": "A pass entry proves only that the named command met this contract for the current git/worktree/runner context. It must not be cited as speed, memory, throughput, drop-in, or benchmark support."
  },
  "required_ledger_top_level_keys": [
    "schema",
    "ledger_id",
    "generated_at_utc",
    "producer",
    "git",
    "worktree",
    "entries",
    "summary",
    "redaction_summary",
    "claim_boundaries"
  ],
  "required_entry_keys": [
    "schema",
    "entry_id",
    "bead_id",
    "command",
    "command_class",
    "runner",
    "timing",
    "exit",
    "paths",
    "artifact_retrieval",
    "warnings",
    "evidence_classification"
  ],
  "command_contract": {
    "required_fields": [
      "argv",
      "rendered",
      "cwd",
      "command_fingerprint",
      "feature_flags",
      "env_allowlist"
    ],
    "allowed_command_classes": [
      "cargo_check",
      "cargo_clippy",
      "cargo_test",
      "cargo_build",
      "cargo_fmt_check",
      "script_self_test",
      "ubs_staged",
      "beads_ledger_reconcile",
      "custom_validation"
    ],
    "fingerprint_policy": "command_fingerprint must include argv, cwd, git head, command_class, feature flags, CARGO_TARGET_DIR, TMPDIR, runner_requirement, and dirty-path policy."
  },
  "runner_contract": {
    "required_fields": [
      "requested_runner",
      "resolved_runner",
      "runner_requirement",
      "remote_execution",
      "local_fallback",
      "fallback_reason",
      "rch_job_id",
      "worker_id",
      "worker_host",
      "queue_state",
      "worker_state",
      "command_rewrite",
      "status_excerpt"
    ],
    "allowed_requested_runners": [
      "rch",
      "local",
      "read_only"
    ],
    "allowed_resolved_runners": [
      "rch_remote",
      "local",
      "not_run"
    ],
    "allowed_runner_requirements": [
      "rch_required",
      "local_allowed",
      "read_only",
      "no_compile"
    ],
    "allowed_local_fallback": [
      "none",
      "refused",
      "observed",
      "unknown"
    ],
    "remote_proof_policy": "For runner_requirement=rch_required, clean proof requires resolved_runner=rch_remote, remote_execution=true, and local_fallback=none. local_fallback=observed is never clean proof. local_fallback=refused is a correct fail-closed blocker, not a pass."
  },
  "timing_contract": {
    "required_fields": [
      "started_at_utc",
      "ended_at_utc",
      "duration_ms",
      "heartbeat_at_utc",
      "stale_progress_detected"
    ],
    "timestamp_policy": "Timestamps must be RFC3339 UTC strings ending in Z. duration_ms must be non-negative. stale_progress_detected=true degrades proof unless a later clean exit is recorded in the same entry."
  },
  "exit_contract": {
    "required_fields": [
      "exit_code",
      "success",
      "termination_reason",
      "stderr_excerpt",
      "stdout_excerpt"
    ],
    "allowed_termination_reasons": [
      "completed",
      "failed",
      "timed_out",
      "cancelled",
      "queue_backoff",
      "local_fallback_refused",
      "not_run"
    ]
  },
  "paths_contract": {
    "required_fields": [
      "cargo_target_dir",
      "tmpdir",
      "remote_target_dir",
      "remote_tmpdir",
      "artifact_paths"
    ],
    "path_policy": "Entries must name the target and temp directories used for the command. Dynamic user paths may be normalized, but missing target/TMPDIR data must be reported as degraded instead of inferred."
  },
  "artifact_retrieval_contract": {
    "required_fields": [
      "status",
      "retrieved_paths",
      "missing_paths",
      "warning_details",
      "retrieval_exit_code",
      "retrieval_elapsed_ms"
    ],
    "allowed_status": [
      "clean",
      "warning",
      "failed",
      "skipped",
      "not_applicable",
      "unknown"
    ],
    "retrieval_policy": "status=warning or failed must remain visible in operator handoff. A command may have exit.success=true while artifact_retrieval.status=warning; that is degraded remote proof, not clean proof."
  },
  "warning_contract": {
    "required_fields": [
      "warning_id",
      "severity",
      "message",
      "source",
      "redacted"
    ],
    "allowed_severity": [
      "info",
      "warning",
      "error"
    ],
    "required_warning_ids": [
      "local_fallback_observed",
      "local_fallback_refused",
      "queue_backoff",
      "artifact_retrieval_warning",
      "stale_progress",
      "unrelated_worktree_blocker",
      "worker_workspace_shadow",
      "proof_claim_coverage_mismatch"
    ]
  },
  "evidence_classification_contract": {
    "required_fields": [
      "status",
      "clean_remote_proof",
      "operator_evidence_only",
      "suppressed_claims",
      "coverage",
      "degraded_reasons",
      "next_actions"
    ],
    "allowed_status": [
      "pass",
      "degraded",
      "blocked",
      "fail"
    ],
    "required_suppressed_claims": [
      "release_performance",
      "strict_dropin",
      "benchmark_throughput",
      "memory_or_startup_claim"
    ],
    "classification_policy": "clean_remote_proof=true is allowed only when command exit succeeded, RCH remote execution is proven, no local fallback occurred, artifact retrieval is clean or not_applicable, and no error-severity warning is present. authoritative_for_bead=true is stricter: the proof must pass and cover every claimed changed path."
  },
  "coverage_contract": {
    "required_fields": [
      "changed_paths",
      "claimed_paths",
      "covered_paths",
      "uncovered_paths",
      "coverage_status",
      "coverage_rationale",
      "claimed_authoritative",
      "authoritative_for_bead"
    ],
    "allowed_coverage_status": [
      "covered",
      "partial",
      "uncovered",
      "blocked",
      "fail",
      "claimed_uncovered",
      "no_changed_paths",
      "no_claimed_paths"
    ],
    "fail_closed_policy": "If a proof explicitly claims authoritative bead coverage but any claimed path is not covered, the entry must classify as fail with warning_id=proof_claim_coverage_mismatch."
  },
  "golden_examples": {
    "path": "tests/golden_corpus/remote_validation_proof_ledger/examples.json",
    "required_case_ids": [
      "pass_remote_clean",
      "local_fallback_refusal",
      "queue_backoff",
      "retrieval_warning"
    ]
  },
  "operator_docs": {
    "runbook_path": "docs/swarm-operations-runbook.md",
    "readme_path": "README.md",
    "required_fragments": [
      "pi.remote_validation.proof_ledger.v1",
      "operator evidence only",
      "not release performance evidence",
      "local fallback",
      "artifact retrieval"
    ]
  }
}