Add capture parity tooling and enforcement regressions

Author: Wood Cell Dev

ENGINEERING_LOG.md

@@ -412,3 +412,62 @@
 - Wired dendro import toolkit into the results page with format catalog + preview (`frontend/src/components/Analysis/DendroToolkitPanel.tsx`, `frontend/src/services/api.ts`, `frontend/src/services/analysisService.ts`).
 - Updated milestone alignment docs for new parity progress (`docs/multi_milestone_execution_plan.md`, `docs/milestone_4_5_readiness_audit.md`).
 - `.venv/bin/python -m pytest tests/test_api_v2.py::test_project_ring_summary_endpoint`
+
+## 2025-09-23 00:19 UTC
+- Authored remote capture architecture reference (`docs/capture/remote_twain_agent.md`) outlining agent pairing, presets, and health reporting.
+- Added remote capture agent package with Typer CLI and synthetic fallback (`agents/capture_agent`); implemented remote agent auth bypass for middleware and new capture stores.
+- Extended API with agent/preset/job endpoints plus JSON stores (`scripts/data_store.py`, `scripts/api_v2.py`), including remote upload path handling and preset CRUD.
+- Enhanced `cellctl` with `capture agents|presets|create-preset` commands and refreshed product blueprint + milestone 7 audit for remote capture progress.
+- Added regression tests covering agent lifecycle and preset CRUD (`tests/test_api_v2.py`), ran `.venv/bin/python -m pytest tests/test_api_v2.py` successfully.
+
+## 2025-09-23 01:12 UTC
+- Implemented TWAIN/SANE-enabled provider registry in the capture agent with retry, preview, and stitched path-scan support (`agents/capture_agent/providers/*`, `agents/capture_agent/main.py`).
+- Wired backend to persist path-scan metadata, active agent jobs, and capture summaries (`scripts/api_v2.py`, `scripts/data_store.py`), adding `/api/v2/capture/summary` and CLI summary view.
+- Updated docs to reflect remote-agent capabilities and outstanding validation work (`docs/product_blueprint.md`, `docs/milestone_7_gap_audit.md`).
+- Expanded pytest coverage with path-scan and capture summary flows (`tests/test_api_v2.py`), all passing via `.venv/bin/python -m pytest tests/test_api_v2.py`.
+
+## 2025-09-23 02:20 UTC
+- Surfaced WinCELL morphometrics in the React results console: hydraulic/ratio histograms, debris rollups, and per-cell-type summaries (`frontend/src/pages/Results.tsx`, `frontend/src/services/api.ts`).
+- Extended ring summary exports with per-ring series and hooked export actions in the UI (`scripts/api_v2.py`, `frontend/src/components/Analysis/RingSummaryPanel.tsx`).
+- Hardened regression coverage for ring exports and membership flows (`tests/test_api_v2.py`).
+- `.venv/bin/python -m pytest tests/test_api_v2.py`
+
+## 2025-09-23 02:45 UTC
+- Added project-level ring chronology aggregation + chronology exports for WinCELL parity (`scripts/api_v2.py`, `frontend/src/components/Analysis/RingSummaryPanel.tsx`).
+- Introduced inference anomaly heuristics (coverage, debris ratio, hydraulic bounds) to feed parity alerts (`scripts/api_v2.py`).
+- Wired chronology types through analysis services and UI, including new charts/tables (`frontend/src/services/api.ts`, `frontend/src/services/analysisService.ts`).
+- Updated milestone audit to reflect the analytics progress (`docs/milestone_7_gap_audit.md`).
+- `.venv/bin/python -m pytest tests/test_api_v2.py`
+
+## 2025-09-23 03:05 UTC
+- Carried calendar-year signals into ring summaries/exports and attached grouped morphometric stats + density summaries to WinDENDRO/XLCell bundles (`scripts/api_v2.py`).
+- Surfaced coverage/debris/hydraulic KPIs and density dashboards in the React results console (`frontend/src/pages/Results.tsx`).
+- Enriched chronology tooling with year-aware charts/tables (`frontend/src/components/Analysis/RingSummaryPanel.tsx`).
+- Tightened regression coverage for chronology/density exports (`tests/test_api_v2.py`).
+- `.venv/bin/python -m pytest tests/test_api_v2.py`
+
+## 2025-09-23 11:05 UTC
+- Added parity export helper + pytest marker to validate WinDENDRO/XLCell bundles (`tests/test_api_v2.py::test_inference_export_parity`), seeded via `_run_parity_export_job`.
+- Surfaced QA harness through `cellctl qa parity` (runs `pytest -m parity`) and registered marker metadata (`pytest.ini`).
+- Updated Milestone 7 QA plan and gap audit to reflect the new automation coverage.
+
+## 2025-09-23 11:40 UTC
+- Logged hardware validation matrix and path-scan QA protocol (`docs/capture/hardware_validation_matrix.md`, `docs/capture/path_scan_qa.md`).
+- Added parity harness tests + utility checklist (`tests/test_morphometrics_parity.py`, `docs/exports/reference_dataset_checklist.md`).
+- Authored specs for acquisition dashboard, debris tooling, region enforcement, vessel grouping, and results parity UI (`docs/capture/acquisition_dashboard_spec.md`, `docs/frontend_debris_tooling.md`, `docs/analysis_region_enforcement.md`, `docs/vessel_grouping_workflow.md`, `docs/frontend_results_parity.md`).
+## 2025-09-23 12:35 UTC
+- Added parity analytics pipeline: per-cell-type metrics, parity alert detection, export health caching, and bundle metadata storage (`scripts/api_v2.py`).
+- Extended parity pytest harness to validate analytics payloads and export health (`tests/test_morphometrics_parity.py`).
+- Upgraded Results dashboard with parity overview, export health panel, and density trend chart (`frontend/src/pages/Results.tsx`); refreshed API typings (`frontend/src/services/api.ts`).
+- Documented parity UI completion (`docs/frontend_results_parity.md`).
+## 2025-09-23 14:35 UTC
+- Implemented analysis-region enforcement pipeline: detections now carry structured rejection filters and analytics track accepted/rejected breakdowns (`scripts/api_v2.py`).
+- Added regression covering region enforcement scenarios and export metadata (`tests/test_api_v2.py::test_analysis_region_enforcement_flags_detections`).
+- Exposed detection filters and enforcement summary in API typings, and surfaced enforcement dashboards + per-image rejection chips in React results view (`frontend/src/services/api.ts`, `frontend/src/pages/Results.tsx`).
+- Updated enforcement plan doc with implementation status notes (`docs/analysis_region_enforcement.md`).
+
+## 2025-09-23 18:45 UTC
+- Added parity regression to ensure analysis-region edits propagate to analytics and WinDENDRO exports (`tests/test_morphometrics_parity.py::test_analysis_region_edits_refresh_exports`).
+- Injected deterministic image dimensions into dry-run fixtures so enforcement math aligns with edge thresholds (`tests/test_morphometrics_parity.py`).
+- Refreshed milestone 7 audit to capture delivered debris tooling/enforcement work and highlight remaining acquisition + automation gaps (`docs/milestone_7_gap_audit.md`).
+- `.venv/bin/python -m pytest tests/test_morphometrics_parity.py::test_analysis_region_edits_refresh_exports`

agents/__init__.py

@@ -0,0 +1 @@
+"""Agent utilities for bridging educator hardware with the Cell platform."""

agents/capture_agent/__init__.py

@@ -0,0 +1,3 @@
+"""Remote capture agent package."""
+
+__all__ = ['config', 'devices', 'main']

agents/capture_agent/config.py

@@ -0,0 +1,43 @@
+"""Configuration helpers for the remote capture agent."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Optional
+
+CONFIG_DIR = Path(os.getenv('CELL_AGENT_HOME', Path.home() / '.cell'))
+CONFIG_PATH = CONFIG_DIR / 'capture_agent.json'
+
+
+@dataclass
+class AgentConfig:
+    api_base: str
+    agent_id: str
+    token: str
+    label: Optional[str] = None
+
+
+def load_config(path: Path = CONFIG_PATH) -> AgentConfig:
+    if not path.exists():
+        raise FileNotFoundError(f"Capture agent is not paired; run 'capture-agent register' first ({path})")
+    payload = json.loads(path.read_text())
+    return AgentConfig(
+        api_base=payload['api_base'],
+        agent_id=payload['agent_id'],
+        token=payload['token'],
+        label=payload.get('label')
+    )
+
+
+def save_config(config: AgentConfig, path: Path = CONFIG_PATH) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    payload = asdict(config)
+    path.write_text(json.dumps(payload, indent=2))
+
+
+def delete_config(path: Path = CONFIG_PATH) -> None:
+    if path.exists():
+        path.unlink()

agents/capture_agent/devices.py

@@ -0,0 +1,35 @@
+"""Device enumeration helpers built on top of provider registry."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .providers import enumerate_all_devices, get_provider, ProviderCaptureError
+
+
+def enumerate_devices() -> List[Dict[str, str]]:
+    devices = enumerate_all_devices()
+    if not devices:
+        devices.append(
+            {
+                "device_id": "simulator-local",
+                "label": "Simulator (install TWAIN/SANE for hardware)",
+                "provider": "simulator",
+                "kind": "virtual",
+            }
+        )
+    return devices
+
+
+def capture_image(
+    provider_id: str,
+    device_id: str,
+    *,
+    settings: Dict[str, str] | None = None,
+    path_scan: Dict[str, str] | None = None,
+    retry: int = 1,
+):
+    provider = get_provider(provider_id)
+    if not provider.available():
+        raise ProviderCaptureError(f"Provider {provider_id} is not available on this host")
+    return provider.capture(device_id=device_id, settings=settings, path_scan=path_scan, retry=retry)