Add protocol layer for requirements, coverage, signals, and pool gap computation

[DarrenZal]

Summary

Additive protocol layer implementing Steps 1-5 of the Claims × Spore coordination protocol. Builds on existing claims/commitments/intents without rewrites.

New protocol tables:

• requirements (079) — normative expectations with cadence (frequency, freshness window, severity). Generic across pool/org/federation scopes.
• coverage_links (081) — explicit relational primitive: commitment covers requirement, claim covers condition, evidence covers commitment. Replaces ad-hoc absence inference with deterministic gap computation.
• signals (082) — raw observations and computed gaps. Junction table links signals → existing intent_registry.

Schema extensions:

• scope column on commitments and commitment_pools (080) — first-class, not metadata. Determines governance path.

New /protocol/* router:

• POST /protocol/requirements/create — declare a requirement (upserts mutable fields)
• GET /protocol/requirements/ — list with scope/type/severity filters
• POST /protocol/coverage/link — create coverage link (full upsert)
• GET /protocol/coverage/ — list with validity filtering
• POST /protocol/signals/create — record a signal
• GET /protocol/signals/ — list with type/scope/freshness filters
• GET /protocol/pools/{rid}/gaps — negative-space intelligence: computes unmet/stale requirements via coverage chain, emits gap_computed signals with next-move suggestions (surface_only, request_offer, propose_commitment, escalate_to_council)

Small API extensions:

• claims_router.py: since datetime filter on list endpoint (422 on malformed input)
• commitment_router.py: offer_type filter on list endpoint, scope in response models

Demo path (end-to-end test)

1. Create pool
2. Create requirement: "Monthly biodiversity survey" (frequency=monthly, severity=high)
3. GET /protocol/pools/{rid}/gaps → 1 unmet gap, next_move=propose_commitment
4. Verify gap_computed signal emitted
5. Add coverage (commitment covers requirement)
6. GET /protocol/pools/{rid}/gaps → 0 gaps, 1 covered

Test plan

• 14/14 tests passing (tests/test_protocol_layer.py)
• Requirement RID uniqueness across pools
• Requirement upsert updates mutable fields
• Gap signal recomputation upserts metadata
• Future-dated coverage does not suppress gap
• Wrong coverage type does not suppress gap
• Valid coverage suppresses gap
• Expired coverage produces stale gap (not unmet)
• Malformed since returns 422
• Commitment/pool responses include scope
• End-to-end gap path with signal emission and resolution
• Pool not found returns 404
• Commitment offer_type filter

🤖 Generated with Claude Code

[DarrenZal]

Quick review guide

The one endpoint to try: GET /protocol/pools/{pool_rid}/gaps

End-to-end flow (6 steps):

1. Create a pool
2. Create a requirement scoped to that pool (e.g., "quarterly monitoring", severity=high)
3. GET /protocol/pools/{pool_rid}/gaps → returns 1 unmet gap with next_move: propose_commitment
4. A gap_computed signal is emitted as audit trail
5. Add a coverage link (commitment covers requirement)
6. GET /protocol/pools/{pool_rid}/gaps → 0 gaps, 1 covered. Gap resolved.

Headline: The system computes what's absent — a requirement exists but no commitment covers it — and surfaces a structured gap signal with a suggested next move.

14/14 tests passing in tests/test_protocol_layer.py, including the full e2e path above.

A standalone demo script (curl sequence) is in a follow-up comment.

[DarrenZal]

Demo script

scripts/demo_protocol_gaps.sh reproduces the full e2e path:

bash scripts/demo_protocol_gaps.sh http://localhost:8351

Steps: create pool → create requirement (quarterly monitoring, severity=high) → compute gaps (1 unmet, next_move=propose_commitment) → verify signal emitted → add commitment + coverage → recompute gaps (0 unmet, 1 covered).

The script is not committed to the PR branch — it's a standalone artifact for reviewers. The same flow is validated by test_e2e_gap_path in tests/test_protocol_layer.py.