feat(core): publish capability grant validation obstruction facts

[flyingrobots]

Summary

• add GraphFact::CapabilityGrantValidationObstructed with deterministic digest coverage for grant validation refusals
• add narrow identity-only capability grant validation against registered optic artifact material
• document the refusal-first boundary and backlog the future accepted grant/admission integration

Non-goals preserved

• no successful AdmissionTicket
• no LawWitness
• no execution or scheduler integration
• no delegation, quorum, governance, or Continuum protocol

Validation

• cargo test -p warp-core --test capability_grant_validation_tests
• cargo test -p warp-core --test capability_grant_validation_tests --test capability_grant_intent_tests --test optic_invocation_admission_tests --test causal_fact_publication_tests
• cargo check -p warp-core --all-targets
• cargo clippy -p warp-core --all-targets -- -D warnings
• npx prettier --check CHANGELOG.md docs/design/capability-grant-validation-obstruction-facts.md docs/design/invocation-obstruction-graph-facts.md backlog/bad-code/RE-031-capability-grant-validation-admission-integration.md
• git diff --check
• pre-commit hook
• pre-push full local gate

Summary by CodeRabbit

• New Features

  • Capability grant validation now publishes obstruction facts when grant material fails validation against expected artifact hash, operation ID, requirements digest, and expiry status.
  • Added validation outcome mechanism for capability presentations against registered grants.

• Documentation

  • Added design documentation for capability grant validation obstruction facts and validation flows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 33071667-3a3d-4ab4-b069-611af33abf45

📥 Commits

Reviewing files that changed from the base of the PR and between 6d5a6f4 and ddafe71.

📒 Files selected for processing (9)

• CHANGELOG.md
• backlog/bad-code/RE-031-capability-grant-validation-admission-integration.md
• crates/warp-core/src/causal_facts.rs
• crates/warp-core/src/lib.rs
• crates/warp-core/src/optic_artifact.rs
• crates/warp-core/tests/capability_grant_validation_tests.rs
• crates/warp-core/tests/optic_invocation_admission_tests.rs
• docs/design/capability-grant-validation-obstruction-facts.md
• docs/design/invocation-obstruction-graph-facts.md

---

📝 Walkthrough

Walkthrough

Adds capability grant validation as a pre-admission obstruction fact. Introduces CapabilityGrantValidationObstructionKind enum, GraphFact::CapabilityGrantValidationObstructed variant, validation API in CapabilityGrantIntentGate, deterministic fact digest, regression tests, and design documentation clarifying refusal-first semantics without success admission, work, or execution.

Changes

Capability Grant Validation Obstruction Implementation

Layer / File(s)	Summary
Validation obstruction fact model and types crates/warp-core/src/causal_facts.rs, crates/warp-core/src/lib.rs	Defines CapabilityGrantValidationObstructionKind enum with variants for malformed/unbound presentations, unknown grants, and hash/id/digest mismatches. Adds GraphFact::CapabilityGrantValidationObstructed variant carrying presentation/grant identifiers, expected vs actual artifact/operation/requirements digests. Implements digest_label() and extends GraphFact::digest() for deterministic serialization. Re-exports new kind from lib.rs.
Validation API types and surface crates/warp-core/src/optic_artifact.rs, crates/warp-core/src/lib.rs	Introduces CapabilityGrantExpiryPosture, CapabilityGrantValidationObstruction, CapabilityGrantIdentityCoverage, CapabilityGrantValidationPosture, and CapabilityGrantValidationOutcome types. Adds CAPABILITY_GRANT_VALIDATION_POSTURE_KIND constant. Updates module and type documentation to clarify placeholder posture behavior and admission boundary semantics.
Validation implementation and state management crates/warp-core/src/optic_artifact.rs, crates/warp-core/tests/optic_invocation_admission_tests.rs	Extends CapabilityGrantIntentGate with published_graph_facts field and implements validate_capability_presentation_for_artifact() method performing refusal-first checks on presentation binding, grant lookup, and artifact/operation/requirements digest matching with optional expiry obstruction. Adds obstructed_capability_grant_validation(), publish_capability_grant_validation_obstruction(), and validation_grant_id() helpers. Updates admission test function names to reflect validation context.
Regression tests crates/warp-core/tests/capability_grant_validation_tests.rs	Provides fixture helpers and comprehensive tests verifying that validation obstructs on artifact hash/operation id/requirements digest mismatch and expiry. Validates correct obstruction fact publication with expected/granted identifiers and digests. Confirms deterministic digest for identical facts.
Design documentation and changelog CHANGELOG.md, backlog/bad-code/RE-031-capability-grant-validation-admission-integration.md, docs/design/capability-grant-validation-obstruction-facts.md, docs/design/invocation-obstruction-graph-facts.md	Documents the obstruction-facts doctrine, fact model, validation flow, and non-goals (no success admission, tickets, law witness, execution, delegation/quorum, Continuum, invocation success). Adds RE-031 backlog document describing follow-up work. Clarifies that admit_optic_invocation does not perform grant validation.

Possibly Related PRs

• flyingrobots/echo#331: Adds admit_optic_invocation skeleton that currently blocks with CapabilityValidationUnavailable obstruction—this PR supplies the missing validation layer.
• flyingrobots/echo#344: Extends OpticAdmissionRequirements with stable digest/codec fields that this PR's validation logic depends on for requirements digest comparison.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

Obstruction facts, before tickets flow,
Grant validation says "no, just no."
Digests compared with steady hand,
Refusal-first: the law of the land.
Evidence burned in the graph's refrain,
Permission denied—deterministic pain. 🔐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 67.65% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly and specifically describes the main change: adding publication of capability grant validation obstruction facts as a new GraphFact variant in the warp-core crate.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/capability-grant-validation-obstruction-facts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flyingrobots]

🔍 Code Lawyer Audit Summary

Issue	Severity	Source	Addressed by	Regression coverage	Outcome
No unresolved review threads found	N/A	GitHub reviewThreads	No new commit	GraphQL review-thread query	Clean
No blocking self-audit defects found	N/A	Self-audit of origin/main...HEAD	No new commit	git diff --check; targeted local validation	Clean

Local validation run:

cargo test -p warp-core --test capability_grant_validation_tests
cargo test -p warp-core --test optic_invocation_admission_tests
cargo test -p warp-core --lib
cargo check -p warp-core
scripts/ban-nondeterminism.sh
npx markdownlint-cli2 CHANGELOG.md docs/design/capability-grant-validation-obstruction-facts.md backlog/bad-code/RE-031-capability-grant-validation-admission-integration.md docs/design/invocation-obstruction-graph-facts.md

All listed local checks passed. CI checks are green. Merge gate remains blocked only by review policy (REVIEW_REQUIRED, zero approving reviews). Cc: @codex

[chatgpt-codex-connector]

Summary

No follow-up code action is required from this trigger.

The trigger reports:

• no unresolved review threads,
• no blocking self-audit defects,
• local validation passing,
• CI green,
• merge blocked only by review policy (REVIEW_REQUIRED, zero approvals).

I also verified the working tree is clean and there are no uncommitted changes on the current branch, so there is nothing to commit and therefore no new PR to create in this run.

Checks run

• ✅ cd /workspace/echo && find .. -name AGENTS.md -print
• ✅ cd /workspace/echo && git status --short && git log -n 5 --oneline

View task →