feat(contracts): implement sequence-gap detection and dynamic capture profile introspection (#730) - #753

📌 Description

Implements Sequence-Gap Detection & Dynamic Capture Profile Introspection under Plane B (agentwatch/contracts/) to address Issue #730 assigned by @SHAURYASANYAL3.

Key Changes

1. Per-Sensor Sequence Tracking: Monotonically tracks sequence counters parsed from TemporalInfo.ordering_key ("{sensor_id}:{seq:012d}") with fallback to event.attributes["sensor_id"] and event.attributes["source_seq"].
2. Multi-Sensor Stream Isolation & Jitter Resilience: Partitions events by sensor instance, sorts arrivals by (seq, timestamp) to handle network jitter without false gaps, and deduplicates consecutive identical sequence numbers.
3. Missing Span Detection: Detects exact dropped intervals [seq_lost_start, seq_lost_end] with bounding timestamps t_before and t_after.
4. Dynamic Coverage Profiling: Adds SequenceGap model and extends CoverageSnapshot with drop_rate, has_gaps, sampling_rate, and sampling_policy.
5. Window-Aware Epistemic Refutation & Downgrades: Evaluates whether sequence gaps overlap the contract observation window ([target - window, target]). Safely transitions verdicts from REFUTED to INCONCLUSIVE when sequence gaps (MissingReason.SEQUENCE_GAP) or sampling (MissingReason.SAMPLED_OUT) make evidence insufficient. Only issues REFUTED when authoritative sensors attest 100% complete, unbroken coverage throughout the window.

Fixes #730

🏛️ Architectural Plane & Classification

Which architectural plane does this change target? (docs/v3/V3_ARCHITECTURE.md)

• Plane A: Evidence Plane (Sensors, RawObservation, Ingest, Redaction)
• Plane B: Interpretation Plane (Normalizers, ComputationalEvent, Entity Resolution, Contracts)
• Plane C: Structure Plane (Hyperedge Store, Execution/Information/Causal Graphs, Provenance)
• Plane D: Model Plane (Latent States, Motifs, Behavioral Genome, Drift)
• Plane E: Experiment Plane (Replay L0–L4, Timelines, Counterfactuals)
• Plane F: Interface Plane (API, Typer CLI, Next.js Frontend)
• Documentation / CI Maintenance

🧪 Verification & Evidence of Testing

Local Test Execution Output

pytest tests/contracts/ -v
============================= test session starts =============================
platform win32 -- Python 3.11.0, pytest-9.0.2, pluggy-1.6.0
collected 22 items

tests/contracts/test_evidence_sufficiency.py::test_preceding_event_supported_with_minimal_witness PASSED [  4%]
tests/contracts/test_evidence_sufficiency.py::test_missing_sensor_yields_inconclusive_never_false_alarm PASSED [  9%]
tests/contracts/test_evidence_sufficiency.py::test_authoritative_log_absence_yields_refuted PASSED [ 13%]
tests/contracts/test_evidence_sufficiency.py::test_preceding_event_window_exceeded_yields_refuted PASSED [ 18%]
tests/contracts/test_evidence_sufficiency.py::test_clock_ambiguity_yields_conflicting_evidence PASSED [ 22%]
tests/contracts/test_evidence_sufficiency.py::test_eventually_within_operator PASSED [ 27%]
tests/contracts/test_sequence_gaps.py::test_parse_event_sequence_ordering_key PASSED [ 31%]
tests/contracts/test_sequence_gaps.py::test_parse_event_sequence_attributes_fallback PASSED [ 36%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_contiguous_stream PASSED [ 40%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_single_missing_number PASSED [ 45%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_multiple_missing_spans PASSED [ 50%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_out_of_order_arrival PASSED [ 54%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_handles_duplicates PASSED [ 59%]
tests/contracts/test_sequence_gaps.py::test_sequence_tracker_stream_isolation PASSED [ 63%]
tests/contracts/test_sequence_gaps.py::test_contract_transitions_to_inconclusive_on_overlapping_gap PASSED [ 68%]
tests/contracts/test_sequence_gaps.py::test_contract_refutes_when_gap_is_outside_observation_window PASSED [ 72%]
tests/contracts/test_sequence_gaps.py::test_contract_transitions_to_inconclusive_on_sampled_out PASSED [ 77%]
tests/contracts/test_sequence_gaps.py::test_coverage_profile_registry PASSED [ 81%]
tests/contracts/test_sequence_gaps.py::test_coverage_snapshot_to_dict PASSED [ 86%]
tests/contracts/test_synthetic_packet_drop_transitions_to_inconclusive[0.01] PASSED [ 90%]
tests/contracts/test_synthetic_packet_drop_transitions_to_inconclusive[0.05] PASSED [ 95%]
tests/contracts/test_synthetic_packet_drop_transitions_to_inconclusive[0.2] PASSED [100%]
============================= 22 passed in 1.03s ==============================

• New unit tests or regression tests were added covering this logic (16 tests in tests/contracts/test_sequence_gaps.py including synthetic dropped-span benchmarks at 1%, 5%, and 20%).
• Existing test suite passes with zero regressions (pytest tests/contracts/). Core v3 suite passes 125 tests (5 skipped requiring external DB/credentials; optional Redis-dependent API tests were not run in the recorded validation).
• Test coverage across agentwatch.contracts is 88% (satisfies >= 70% coverage gate).

🛡️ Security & Linter Quality Checklist

• Bandit Scan Passed: Standalone Bandit was not run locally because the package is not installed in the local environment (ModuleNotFoundError: No module named bandit). Flake8-Bandit (Ruff S family) is active in Ruff and passed with 0 issues.
• No Baseline File: Confirmed bandit-baseline.json was NOT created or edited.
• Inline Suppressions (If applicable): PRNG usage in synthetic test harness is strictly scoped (# noqa: S311 # nosec B311 — deterministic PRNG with fixed seed for synthetic test stream generation).
• Ruff Format: Ran ruff format --check agentwatch/contracts/ tests/contracts/ (Clean pass).
• Ruff Check: Ran ruff check agentwatch/ tests/contracts/ (Clean pass).
• Plane Boundaries: Verified lower planes do not import from higher planes (pytest tests/v3/test_architecture_contracts.py passed 5/5).

✍️ Contributor Integrity Declaration

By submitting this pull request, I certify that:

1. I have been formally assigned to this issue by a maintainer (@SHAURYASANYAL3).
2. I personally understand and wrote or thoroughly verified every line of this code.
3. This PR contains no unreviewed, hallucinated, or unverified AI-generated slop.
4. My branch is cleanly based on the latest origin/main.