Files
cbb-refresh-verify-795/docs/superpowers/plans/2026-09-18-batch-status-bridge.md
T
阿白叔 11a2b2e46e Import CBB refresh verify r4 stability baseline
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.
2026-09-29 15:05:20 +08:00

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/LP maps to eReuseBlockType = 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 become READY.
  • Do not call FreeLibrary after 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 existing default_bridge_path() from status_bridge.py.

  • Produces: LmcFingerprint, BatchStatusRequest, BatchStatusRecord, BatchCheckpoint, and fingerprint_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, and block_type.

  • Produces: one JSON response per request; --server exits 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 --server JSONL protocol and BatchCheckpoint.

  • 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: BatchStatusSession and 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.exe and BatchStatusSession.

  • 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.