Preserve tested Verify source, authoritative READY checks, bounded bridge retries, diagnostics and failure-only reporting. Include 336-test suite and packaging assets; exclude live Mentor samples, field logs, backups and distributions.
11 KiB
CBB Batch Status Bridge Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Read 180 to 3000 CBB Verify states through one resilient x86 Mentor bridge session with checkpoint recovery and authoritative READY/PENDING results.
Architecture: Extend the existing C++ bridge with a --server JSONL mode that loads LMCDLL70.dll once and serializes requests. Add a Python batch session that supervises the process, writes one checkpoint record per CBB, rotates the bridge periodically, resumes incomplete entries, and invalidates results when the LMC fingerprint changes. Keep the existing single-query API and default worker count at one.
Tech Stack: C++17, Win32/MFC/ATL, CMake, Python 3.12, JSONL, pytest.
Spec: docs/superpowers/specs/2026-09-18-batch-status-bridge-design.md
Global Constraints
RULP/LPmaps toeReuseBlockType = 0.- Mentor private DLL calls are read-only; no Verify/Unverify and no production-library writes.
- One active bridge session per LMC; requests are serialized.
UNKNOWN, timeout, malformed response, bridge crash, and unavailable bridge never becomeREADY.- Do not call
FreeLibraryafter entering Mentor private MFC code; let the one-shot or server process exit reclaim the module. - Default batch worker count is 1; concurrency is not enabled by this plan.
Task 1: Define Batch Protocol and Checkpoint Models
Files:
- Create:
src/cbb_refresh_verify/batch_status.py - Test:
tests/test_batch_status.py
Interfaces:
-
Consumes:
BridgeResult,StatusBridgeClient, and the existingdefault_bridge_path()fromstatus_bridge.py. -
Produces:
LmcFingerprint,BatchStatusRequest,BatchStatusRecord,BatchCheckpoint, andfingerprint_library(). -
Step 1: Write failing model and fingerprint tests
def test_fingerprint_changes_when_lmc_changes(tmp_path):
lmc = tmp_path / "mentor_lib.lmc"
lmc.write_bytes(b"one")
first = fingerprint_library(lmc)
lmc.write_bytes(b"two")
second = fingerprint_library(lmc)
assert first.sha256 != second.sha256
def test_checkpoint_ignores_truncated_json_line(tmp_path):
path = tmp_path / "scan.jsonl"
path.write_text('{"block_name":"A","status":"READY"}\n{"block_name":"B"', encoding="utf-8")
checkpoint = BatchCheckpoint.load(path)
assert checkpoint.completed_names == {"A"}
- Step 2: Run the focused tests and confirm collection failure
Run: pytest -q tests/test_batch_status.py
Expected: FAIL because the new models and loader do not exist.
- Step 3: Implement the models and fingerprinting
Implement fingerprint_library(lmc: Path) -> LmcFingerprint with file size, nanosecond mtime, SHA-256, and a deterministic recursive ReusableBlocksLP directory fingerprint. Implement BatchCheckpoint.load(path) by parsing only complete JSON objects and accepting only records whose status is READY, PENDING, or a terminal error.
- Step 4: Run the focused tests
Run: pytest -q tests/test_batch_status.py
Expected: PASS.
- Step 5: Record the task result
Save the test command and result in runs/batch-status-implementation-checkpoints.md; this repository is not a Git worktree, so use this artifact instead of a commit.
Task 2: Add Persistent JSONL Server Mode to the x86 Bridge
Files:
- Modify:
tools/status_bridge/CbbStatusBridge32.cpp - Modify:
tools/status_bridge/README.md - Test:
tests/test_status_bridge_server.py
Interfaces:
-
Consumes: one JSON request per stdin line with
op=is_verified,lmc_file,block_name, andblock_type. -
Produces: one JSON response per request;
--serverexits nonzero only for startup failure, while an individual request returns an error object and the server continues. -
Step 1: Write protocol tests using a fake executable
def test_server_response_is_one_line_per_request(fake_server):
result = run_server_client(fake_server, ["A", "B"])
assert [item["block_name"] for item in result] == ["A", "B"]
def test_one_bad_request_does_not_stop_following_request(fake_server):
result = run_server_client(fake_server, ["BAD", "GOOD"])
assert result[0]["ok"] is False
assert result[1]["ok"] is True
- Step 2: Run the protocol tests and confirm failure
Run: pytest -q tests/test_status_bridge_server.py
Expected: FAIL because --server and the client helper do not exist.
- Step 3: Implement the server loop
Refactor the current private query into queryOne(request) and add runServer(). Load the DLL and resolve IsVerifiedReuseBlock once before the loop. For each line, validate fields, call the function inside the existing CString lifetime scope, emit a flushed JSON response, and continue after request-level errors. Do not call FreeLibrary in server mode.
- Step 4: Build and run the real read-only smoke test
Run from tools/status_bridge:
cmake --build build-x86-final2 --config Release --parallel 2
$env:CBB_STATUS_BRIDGE_ALLOW_PRIVATE = '1'
$env:LMCDLL70_PATH = 'D:\Mentor\7.9.5EE\SDD_HOME\common\win32\lib\LMCDLL70.dll'
Send two requests to CbbStatusBridge32.exe --server and verify two responses, then terminate the server process. Do not send Verify or Unverify operations.
- Step 5: Update the bridge README and checkpoint
Document --server, one-line request/response behavior, serialized processing, and the no-FreeLibrary rule. Copy the verified executable to tools/status_bridge/bin/CbbStatusBridge32.exe and record the build output in runs/batch-status-implementation-checkpoints.md.
Task 3: Implement Supervised Batch Session and Checkpoint Resume
Files:
- Modify:
src/cbb_refresh_verify/status_bridge.py - Modify:
src/cbb_refresh_verify/batch_status.py - Test:
tests/test_batch_status.py
Interfaces:
-
Consumes: bridge
--serverJSONL protocol andBatchCheckpoint. -
Produces:
BatchStatusSession.scan(names, lmc_file, checkpoint_path, block_type="RULP") -> list[BatchStatusRecord]. -
Step 1: Write failing supervisor tests
def test_scan_reuses_checkpoint_and_queries_only_missing(fake_server, tmp_path):
checkpoint = tmp_path / "scan.jsonl"
checkpoint.write_text('{"block_name":"A","status":"READY"}\n', encoding="utf-8")
records = BatchStatusSession(bridge=fake_server).scan(["A", "B"], lmc, checkpoint)
assert fake_server.requests == ["B"]
assert {record.block_name for record in records} == {"A", "B"}
def test_timeout_restarts_bridge_and_continues(fake_server, tmp_path):
records = BatchStatusSession(bridge=fake_server, timeout_seconds=0.1).scan(["A", "B"], lmc, tmp_path / "scan.jsonl")
assert records[0].status == "TIMEOUT"
assert records[1].status in {"READY", "PENDING"}
- Step 2: Run the focused supervisor tests and confirm failure
Run: pytest -q tests/test_batch_status.py -k 'scan or timeout'
Expected: FAIL because BatchStatusSession is not implemented.
- Step 3: Implement one persistent subprocess session
Add StatusBridgeServer to status_bridge.py with start(), query(request), restart(), and close(). Use Popen(..., stdin=PIPE, stdout=PIPE, stderr=PIPE, CREATE_NO_WINDOW), flush each request, read exactly one response line, and enforce a per-request deadline. On timeout or malformed response, terminate the process, record the failure, and restart before the next item.
- Step 4: Implement checkpoint writes and rotation
BatchStatusSession must write a complete JSON record immediately after every response, skip names already completed under the same LMC fingerprint, and restart the bridge after 500 requests. Preserve terminal errors for resume, but never treat ERROR, TIMEOUT, or UNAVAILABLE as READY cache hits.
- Step 5: Run supervisor tests
Run: pytest -q tests/test_batch_status.py
Expected: PASS.
Task 4: Add Batch Fault Injection and Throughput Benchmarks
Files:
- Create:
tests/test_batch_status_faults.py - Create:
tools/benchmark_status_bridge.py - Modify:
README.md
Interfaces:
-
Consumes:
BatchStatusSessionand its JSONL checkpoint output. -
Produces: deterministic fault-injection coverage and a benchmark report for 180 and 3000 entries.
-
Step 1: Add failure-isolation tests
Test a malformed response, bridge exit between requests, a timeout on item 17, a truncated final checkpoint line, and an LMC fingerprint change. Assert that later items continue and no error record becomes READY.
- Step 2: Run fault tests and confirm they fail before benchmark wiring
Run: pytest -q tests/test_batch_status_faults.py
Expected: FAIL only for missing fault fixtures or unimplemented supervisor behavior.
- Step 3: Implement the deterministic fake bridge fixtures
Use a Python child process that reads JSONL, returns configured responses, sleeps for configured names, and exits at a configured request count. Do not use Mentor or UI automation in these tests.
- Step 4: Add the benchmark command
tools/benchmark_status_bridge.py must accept --count, --rotate-every, and --output, generate deterministic names, run the batch session, and write total time, completed count, error count, mean latency, p95 latency, and bridge restart count.
- Step 5: Run the benchmark and document the baseline
Run:
$env:PYTHONPATH = 'src'
python tools/benchmark_status_bridge.py --count 180 --output runs/benchmark-180.json
python tools/benchmark_status_bridge.py --count 3000 --output runs/benchmark-3000.json
Document measured results in README.md; do not promise a fixed wall-clock time until the real Mentor bridge benchmark is available.
Task 5: Package the Bridge and Prepare UI Integration Boundary
Files:
- Modify:
packaging/CbbRefreshVerify.spec - Modify:
packaging/Build-CbbRefreshVerify.ps1 - Modify:
src/cbb_refresh_verify/ui/main_window.py - Test:
tests/test_packaging_status_bridge.py
Interfaces:
-
Consumes:
tools/status_bridge/bin/CbbStatusBridge32.exeandBatchStatusSession. -
Produces: packaged bridge asset and an authoritative batch status hook enabled after acceptance.
-
Step 1: Write packaging tests
Assert that the packaged layout contains tools/status_bridge/bin/CbbStatusBridge32.exe, that the UI reports bridge unavailable instead of READY, and that the default worker count is 1.
- Step 2: Add the EXE as a PyInstaller data/binary asset
Copy the x86 bridge into the frozen distribution under tools/status_bridge/bin, and make default_bridge_path() prefer the packaged asset.
- Step 3: Add the authoritative batch status boundary
Expose the batch session to the application layer as the default UI status source. If the bridge is unavailable, show UNAVAILABLE; never infer READY from file or icon evidence. Keep the old reader only behind CBB_STATUS_BRIDGE_MODE=legacy.
- Step 4: Run packaging and targeted regression tests
Run:
$env:PYTHONPATH = 'src'
pytest -q tests/test_status_bridge.py tests/test_batch_status.py tests/test_batch_status_faults.py tests/test_packaging_status_bridge.py
Expected: PASS; the UI includes a local worker fallback when the optional replacement-tool package is absent.
- Step 5: Record final artifact and smoke output
Record the distribution path, bridge SHA-256, benchmark paths, and test summary in runs/batch-status-implementation-checkpoints.md.