feat(core): route invocation presentations through grant validation obstruction

[flyingrobots]

Summary

Routes bound optic invocation capability presentations through a narrow CapabilityPresentationValidator so Echo can publish sharper grant-validation obstruction evidence while keeping invocation admission conservative.

Doctrine:

• validation evidence refines refusal; it does not create authority
• identity coverage is not invocation admission
• failed presentation validation is causal evidence, not a counterfactual

Behavior

• Adds CapabilityPresentationValidator as the narrow invocation-time validation boundary.
• Implements the validator for CapabilityGrantIntentGate using existing narrow identity coverage checks.
• Adds OpticArtifactRegistry::admit_optic_invocation_with_capability_validator(...).
• Publishes GraphFact::CapabilityGrantValidationObstructed for failed presentation validation.
• Still returns OpticInvocationObstruction::CapabilityValidationUnavailable for invocation admission.
• Proves identity-covered grants still do not admit invocation.

Non-goals

• no successful invocation admission
• no successful AdmissionTicket
• no LawWitness
• no accepted grant material
• no delegation validation
• no expiry parsing
• no scheduler work
• no execution
• no WASM ABI
• no Continuum schema

Verification

cargo test -p warp-core --test optic_invocation_admission_tests
cargo test -p warp-core --test capability_grant_validation_tests
cargo check -p warp-core
cargo fmt --all -- --check
git diff --check
scripts/ban-nondeterminism.sh
npx markdownlint-cli2 CHANGELOG.md docs/design/invocation-grant-validation-obstruction-routing.md

Pre-push also ran the critical local gate and passed: fmt, guards, clippy-core, tests-warp-core, rustdoc.

Summary by CodeRabbit

Release Notes

• New Features

  • Capability presentations can now be routed through a validation mechanism to publish grant-validation obstruction facts with conservative refusal-first behavior.

• Documentation

  • Added comprehensive design documentation for invocation grant validation obstruction routing, including architecture diagrams and operating rules.

• Tests

  • Added regression test suite covering validation scenarios including unknown grants, artifact hash mismatches, operation id mismatches, and requirements digest mismatches.

[coderabbitai]

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 8 minutes and 49 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9001b67a-c60d-454d-9d48-de7757413581

📥 Commits

Reviewing files that changed from the base of the PR and between 4bc167e and 43478ad.

📒 Files selected for processing (2)

• crates/warp-core/src/optic_artifact.rs
• docs/design/invocation-grant-validation-obstruction-routing.md

📝 Walkthrough

Walkthrough

This PR adds a capability presentation validation routing abstraction to optic invocation admission. A new CapabilityPresentationValidator trait enables external validators to inspect bound capability presentations and produce obstruction outcomes. The OpticArtifactRegistry::admit_optic_invocation_with_capability_validator method integrates this validator into the admission path while preserving refusal-first semantics; validation outcomes are discarded, and invocations remain obstructed. CapabilityGrantIntentGate implements the validator contract. Tests cover the full obstruction flow for various validation failure modes. Design documentation clarifies the routing boundary and operating rules.

Changes

Validator-Routed Invocation Admission

Layer / File(s)	Summary
Validator contract and registry integration crates/warp-core/src/optic_artifact.rs	Defines CapabilityPresentationValidator trait with validate_capability_presentation(...) returning CapabilityGrantValidationOutcome. Adds OpticArtifactRegistry::admit_optic_invocation_with_capability_validator to route bound presentations through the validator, classify structural posture, and return an obstructed result (CapabilityValidationUnavailable or structural obstruction). Updates OpticCapabilityPresentation::bound_grant_id documentation to clarify validator-aware validation publishes refusal evidence only. Implements the validator trait for CapabilityGrantIntentGate with explicit "expiry not evaluated" posture.
Test infrastructure and validator admission validation crates/warp-core/tests/optic_invocation_admission_tests.rs	Imports authority context and capability grant intent gate types. Adds fixtures for principals, grant intents, authority contexts, and populated gates. Provides helpers to retrieve latest grant validation obstruction facts and construct invocations with bound presentations. Introduces regression tests asserting admit_optic_invocation_with_capability_validator obstructs with CapabilityValidationUnavailable while publishing CapabilityGrantValidationObstructed facts for unknown grants, artifact hash mismatches, operation id mismatches, and requirements digest mismatches; verifies identity-covered grants still obstruct without gate facts.
Design documentation, changelog, and export adjustments docs/design/invocation-grant-validation-obstruction-routing.md, CHANGELOG.md, crates/warp-core/src/lib.rs	Adds design documentation defining the routing doctrine (validation provides refusal evidence, not admission authority), obstruction behavior, identity coverage semantics, and flowchart/sequence/class diagrams for registry, validator, and fact interactions. Updates changelog to note the new validator capability. Reformats pub use optic_artifact::{ ... } re-export list.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• flyingrobots/echo#331: Introduced the base optic invocation admission skeleton and admit_optic_invocation obstruction path; this PR extends it with validator routing.
• flyingrobots/echo#345: Added GraphFact::CapabilityGrantValidationObstructed and CapabilityGrantIntentGate validation machinery that this PR now routes through the validator abstraction.

Poem

Logic flows through validators clean,
Refusal facts are sharp and keen,
No tickets here, no delegates bind,
Just narrowed evidence, sharply designed. 🎯

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main architectural change: routing capability presentation validation through a narrow obstruction boundary validator.
Docstring Coverage	✅ Passed	Docstring coverage is 91.30% which is sufficient. The required threshold is 80.00%.
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 unit tests (beta)

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

---

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
CodeRabbit review unavailable due cooldown/rate limit	Gate	PR global comment	No code change	gh pr view 346 --json comments; gh pr checks 346	Merge gate remains locked

Local validation run:

cargo test -p warp-core --test optic_invocation_admission_tests
cargo test -p warp-core --test capability_grant_validation_tests
cargo check -p warp-core
cargo fmt --all -- --check
git diff --check
scripts/ban-nondeterminism.sh
npx markdownlint-cli2 CHANGELOG.md docs/design/invocation-grant-validation-obstruction-routing.md

All listed local checks passed. CI checks are green. Merge gate remains blocked by review policy (REVIEW_REQUIRED, zero approving reviews) and CodeRabbit cooldown/rate limit.

Cc: @codex

[chatgpt-codex-connector]

Summary

• I reviewed the trigger, PR metadata, and comments: there are no requested code changes and no unresolved review-thread defects to implement from this follow-up event, so I made no repository edits.
• I confirmed the working tree is clean (git status --short produced no file entries), so there was nothing to commit and therefore no new follow-up PR to open via make_pr. This aligns with the executable-claim “stop on green / report intentional non-actions” guidance in the repo instructions. AGENTS.mdL108-L115
• I also verified recent branch context with the latest commit history as requested by the context recovery protocol. AGENTS.mdL84-L88

Testing

• ✅ cd /workspace/echo && find .. -name AGENTS.md -print
• ✅ cd /workspace/echo && git status --short && git log -n 5 --oneline
• ✅ cd /workspace/echo && nl -ba AGENTS.md | sed -n '1,220p'

View task →

[flyingrobots]

@coderabbitai review please

[coderabbitai]

@flyingrobots Kicking off the review now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/warp-core/src/optic_artifact.rs`:
- Around line 1103-1105: The code clones a RegisteredOpticArtifact from
self.resolve_optic_artifact_handle(&invocation.artifact_handle) before
validation, causing an unnecessary allocation on the hot path; instead obtain a
reference (e.g. match to get registered as &registered or use .as_ref()) and
pass a &RegisteredOpticArtifact into your validation routine (or change the
validation function signature to accept &RegisteredOpticArtifact) so the clone
is removed; update any callees (validation functions/methods) that currently
take Owned RegisteredOpticArtifact to accept a borrow and adjust lifetimes/uses
accordingly (references: resolve_optic_artifact_handle, RegisteredOpticArtifact,
invocation.artifact_handle, and the validation function you call).

In `@docs/design/invocation-grant-validation-obstruction-routing.md`:
- Around line 47-50: Update the diagram so Validator invocation is shown as
conditional rather than unconditional: change the arrow from Presentation to
Validator to a conditional/guarded edge (e.g., annotate with “[if presentation
posture available]” or use a decision node) and add an alternative path for the
CapabilityValidationUnavailable case that bypasses Validator and leads to the
appropriate handling (e.g., Registry or ValidationFact path). Specifically
adjust the relations involving Presentation, Validator,
CapabilityValidationUnavailable, ValidationFact, and Registry so the flow only
goes through Validator when presentation posture is structurally available, and
mirror the same conditional change for the similar flow at lines referenced
(68-69).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 275c2d6b-2cb0-4586-b881-26055e29c6ca

📥 Commits

Reviewing files that changed from the base of the PR and between 2ce3e20 and 4bc167e.

📒 Files selected for processing (5)

• CHANGELOG.md
• crates/warp-core/src/lib.rs
• crates/warp-core/src/optic_artifact.rs
• crates/warp-core/tests/optic_invocation_admission_tests.rs
• docs/design/invocation-grant-validation-obstruction-routing.md

[flyingrobots]

Issue	Severity	Addressed by	Regression coverage	Outcome
Avoid cloning registered artifact on invocation validation hot path	Major	0beb53a	optic_invocation_admission_tests; cargo test -p warp-core --test optic_invocation_admission_tests; cargo check -p warp-core; cargo fmt --all -- --check	Resolved
Validator invocation diagrams implied unconditional routing	Minor	43478ad	markdownlint; npx markdownlint-cli2 docs/design/invocation-grant-validation-obstruction-routing.md CHANGELOG.md; git diff --check	Resolved