Files
CCLite/Python/checkers/audit_real_workers.py
T
2026-07-06 09:34:13 +08:00

513 lines
20 KiB
Python

from __future__ import annotations
import argparse
import json
import subprocess
from pathlib import Path
def run_command(command: list[str], timeout: float = 10.0) -> dict:
try:
completed = subprocess.run(command, text=True, capture_output=True, timeout=timeout)
except subprocess.TimeoutExpired as exc:
return {
"command": command,
"exit_code": None,
"stdout": exc.stdout or "",
"stderr": exc.stderr or "",
"status": "TIMEOUT",
}
return {
"command": command,
"exit_code": completed.returncode,
"stdout": completed.stdout,
"stderr": completed.stderr,
"status": "RAW",
}
def parse_key_value_output(text: str) -> dict[str, str]:
values: dict[str, str] = {}
for raw_line in text.splitlines():
line = raw_line.strip()
if not line or line.startswith("["):
continue
if "=" not in line:
continue
key, value = line.split("=", 1)
values[key.strip()] = value.strip()
return values
def is_yes(values: dict[str, str], key: str) -> bool:
return values.get(key, "").strip().lower() in {"yes", "true", "1", "on"}
def run_capabilities_probe(exe: Path) -> dict:
result = run_command([str(exe), "--cclite-capabilities"])
output = (result.get("stdout") or "") + "\n" + (result.get("stderr") or "")
capabilities = parse_key_value_output(output)
result["capabilities"] = capabilities
if result["exit_code"] == 0 and capabilities.get("cclite_worker", "").lower() == "yes":
result["status"] = "CAPABILITIES_AVAILABLE"
elif "unknown" in output.lower() and "capabilities" in output.lower():
result["status"] = "MISSING_CAPABILITIES_CLI"
else:
result["status"] = "CAPABILITIES_FAILED"
result["supports_real_ipc"] = is_yes(capabilities, "supports_real_ipc")
return result
def run_version_probe(exe: Path) -> dict:
result = run_command([str(exe), "--version"], timeout=5.0)
output = ((result.get("stdout") or "") + "\n" + (result.get("stderr") or "")).strip()
result["version"] = extract_version_label(output)
if result["exit_code"] == 0 and output:
result["status"] = "VERSION_AVAILABLE"
elif result["exit_code"] == 0:
result["status"] = "VERSION_EMPTY"
elif output and result["version"] != "unknown":
result["status"] = "VERSION_OUTPUT_WITH_NONZERO_EXIT"
else:
result["status"] = "VERSION_UNAVAILABLE"
return result
def extract_version_label(output: str) -> str:
for raw_line in output.splitlines():
line = raw_line.strip()
if not line or line.startswith("["):
continue
return line[:160]
return "unknown"
def run_standard_worker_probe(
exe: Path,
solver_id: str,
case_file: Path,
extra_args: list[str] | None = None,
) -> dict:
command = [
str(exe),
"--cclite-worker",
]
if extra_args:
command.extend(extra_args)
command.extend([
"--solver-id",
solver_id,
"--case",
str(case_file),
"--ipc-name",
"CCLITE_REAL_WORKER_AUDIT",
"--timeout-ms",
"100",
])
result = run_command(command)
output = (result.get("stdout") or "") + "\n" + (result.get("stderr") or "")
output_lower = output.lower()
recognized = "--solver-id" not in output and "unknown argument" not in output_lower and "unknown worker argument" not in output_lower
unsupported = "not implemented" in output.lower() or "unsupported" in output.lower()
attach_attempted = (
"ipc attach failed" in output_lower
or "failed to open cclite ipc transport" in output_lower
or ("failed to open" in output_lower and "ipc" in output_lower)
)
result["status"] = classify_standard_probe(recognized, unsupported, attach_attempted, result["exit_code"])
result["recognized_worker_cli"] = recognized
result["real_ipc_attach_attempted"] = recognized and attach_attempted
result["ready_without_external_resources"] = recognized and result["exit_code"] == 0 and not unsupported
return result
def run_femlite_mock_probe(exe: Path, case_file: Path, report_path: Path) -> dict:
output_dir = report_path.parent / "femlite_worker_mock"
log_file = report_path.parent / "femlite_worker_mock.log"
result = run_command([
str(exe),
"--cclite-worker",
"--case",
str(case_file),
"--ipc-name",
"CCLITE_FEMLITE_WORKER_MOCK_AUDIT",
"--log",
str(log_file),
"--output-dir",
str(output_dir),
"--mock-steps",
"1",
])
output = (result.get("stdout") or "") + "\n" + (result.get("stderr") or "")
output_lower = output.lower()
if result["exit_code"] == 0 and (
"worker mock completed" in output_lower or "worker completed: mock" in output_lower
):
result["status"] = "WORKER_MOCK_AVAILABLE"
elif "unknown worker argument" in output_lower or "unknown argument" in output_lower:
result["status"] = "MISSING_WORKER_MOCK_CLI"
else:
result["status"] = "WORKER_MOCK_FAILED"
result["log_file"] = str(log_file)
result["output_dir"] = str(output_dir)
return result
def classify_standard_probe(
recognized: bool,
unsupported: bool,
attach_attempted: bool,
exit_code: int | None,
) -> str:
if recognized and unsupported:
return "CONTROLLED_UNSUPPORTED"
if recognized and attach_attempted:
return "IPC_ATTACH_ATTEMPTED"
if recognized and exit_code == 0:
return "READY_FOR_REAL_IPC"
if not recognized:
return "MISSING_STANDARD_WORKER_ARGS"
return "FAILED"
def build_adapter_strategy() -> dict:
return {
"status": "HYBRID_TRANSITION_SELECTED",
"selected_strategy": "HYBRID_GENERIC_BLOCK_PLUS_SOLVER_ADAPTER",
"summary": (
"CCLite keeps the 05 ICD generic command/data blocks as the internal contract, "
"and uses solver-specific adapters at the external real-worker boundary until "
"SPHLite and FEMLite expose identical CCLite binary layouts."
),
"cclite_internal_contract": [
"CCLite generic command block v1",
"CCLite generic data block header with AoR v1 payloads",
"CCLite-owned shared memory and named-event lifecycle",
],
"external_worker_boundary": [
"SPHLite command/name adapter",
"FEMLite native-header/name adapter",
],
"why_not_generic_only_now": (
"The current worker packages report real IPC support, but their published "
"control object names and at least the FEMLite binary header differ from "
"CCLite generic blocks."
),
"why_not_solver_specific_only": (
"The controller, mock-worker acceptance path, diagnostics, and contact "
"algorithm already use a unified CCLite data model; replacing it with two "
"solver-native contracts would duplicate validation logic."
),
"required_adapter_fields": [
"command block name and event name mapping",
"command seq/ack and command-id mapping",
"data header magic/version/layout/role mapping",
"record stride and capacity mapping",
"empty and controlled load import mapping",
"worker error-code and timeout mapping",
],
}
def build_block_capabilities(capabilities: dict[str, str]) -> dict:
keys = [
"command_block_version",
"data_layout",
"supports_sph_to_ccl_particle",
"supports_ccl_to_sph_force",
"supports_fem_to_ccl_facet",
"supports_ccl_to_fem_load",
"max_particle_records",
"max_facet_records",
"max_load_records",
]
return {key: capabilities.get(key, "unknown") for key in keys if key in capabilities}
def build_worker_capability_summary(
exe: Path,
capability_probe: dict,
version_probe: dict,
gap_status: str,
) -> dict:
capabilities = capability_probe.get("capabilities", {})
return {
"worker_name": capabilities.get("solver", exe.stem),
"executable": str(exe),
"version": version_probe.get("version", "unknown"),
"version_probe_status": version_probe.get("status", "VERSION_UNAVAILABLE"),
"capability_probe_status": capability_probe.get("status", "CAPABILITIES_FAILED"),
"ipc": {
"backend": capabilities.get("ipc_backend", "unknown"),
"supports_real_ipc": bool(capability_probe.get("supports_real_ipc", False)),
},
"block_capabilities": build_block_capabilities(capabilities),
"gap_status": gap_status,
}
def build_protocol_alignment(fem_exe: Path) -> dict:
fem_include = fem_exe.parent.parent / "include" / "femlite_cclite_ipc.h"
fem_native_header = False
if fem_include.exists():
text = fem_include.read_text(encoding="utf-8", errors="ignore")
fem_native_header = (
"femlite_cclite_command_block" in text
and "femlite_cclite_data_header" in text
)
return {
"status": "CCLITE_PROTOCOL_ADAPTER_REQUIRED",
"cclite_current_protocol": {
"command_block": "CCLite generic command block v1",
"data_header": "CCLite generic data block header v0.1",
"control_names": [
"<prefix>_CCL_COMMAND_<solver>",
"<prefix>_EVENT_COMMAND_<solver>",
"<prefix>_EVENT_ACK_<solver>",
],
"data_names": [
"<prefix>_SPH_TO_CCL_PARTICLE",
"<prefix>_FEM_TO_CCL_FACET",
"<prefix>_CCL_TO_SPH_FORCE",
"<prefix>_CCL_TO_FEM_LOAD",
],
},
"sphlite_observed_protocol": {
"default_control_names": [
"<ipc_name>.command",
"<ipc_name>.command_event",
"<ipc_name>.done_event",
],
"supports_name_overrides": ["--command-block", "--data-prefix"],
"note": "SPHLite reports real IPC support, but true external CCLite process interop still requires a CCLite-side protocol/name adapter test.",
},
"femlite_observed_protocol": {
"native_header_detected": fem_native_header,
"header": str(fem_include),
"requires_worker_backend": "--worker-backend ipc",
"control_names": [
"<prefix>_COMMAND_BLOCK",
"<prefix>_COMMAND_EVENT",
"<prefix>_DONE_EVENT",
],
"data_names": [
"<data-prefix>_FEM_TO_CCL_FACET",
"<data-prefix>_CCL_TO_FEM_LOAD",
],
"note": "The current FEMLite package uses a native compact command block/data header that is not the same binary layout as CCLite 0.1.x generic blocks.",
},
}
def build_controlled_gap_path(
description: str,
probe: dict | None,
blocking_fields: list[str],
) -> dict:
result = {
"status": "CONTROLLED_PROTOCOL_GAP",
"description": description,
"blocking_fields": blocking_fields,
}
if probe is not None:
result.update({
"probe_status": probe.get("status", "UNKNOWN"),
"recognized_worker_cli": bool(probe.get("recognized_worker_cli", False)),
"real_ipc_attach_attempted": bool(probe.get("real_ipc_attach_attempted", False)),
"exit_code": probe.get("exit_code"),
})
return result
def build_v020_adapter_gate(
adapter_strategy: dict,
worker_summary: dict,
sph_standard: dict,
fem_standard: dict,
fem_explicit_ipc: dict,
) -> dict:
sph_blockers = [
"SPHLite default control names use <ipc_name>.command/.command_event/.done_event.",
"CCLite currently creates <prefix>_CCL_COMMAND_SPH and <prefix>_EVENT_COMMAND_SPH/<prefix>_EVENT_ACK_SPH.",
"The audit has not yet executed a CCLite-side command/data adapter with pre-created resources.",
]
fem_blockers = [
"FEMLite publishes a native compact femlite_cclite_command_block.",
"FEMLite default control names use <prefix>_COMMAND_BLOCK/<prefix>_COMMAND_EVENT/<prefix>_DONE_EVENT.",
"CCLite currently creates generic CCL_COMMAND_FEM and EVENT_COMMAND_FEM/EVENT_ACK_FEM resources.",
]
payload_blockers = [
"Real worker export headers are not yet mapped into CCLite generic data headers.",
"record_type, record_stride, capacity, role, and step_id cannot be validated through the current reader.",
]
load_blockers = [
"Real worker load headers are not yet mapped from CCLite generic load blocks.",
"IMPORT_LOADS acknowledgement cannot be validated until the command/data adapter is executable.",
]
return {
"gate_id": "V020_SINGLE_REAL_WORKER_SMOKE",
"status": "CONTROLLED_PROTOCOL_GAP",
"adapter_strategy": adapter_strategy["selected_strategy"],
"mock_algorithm_acceptance_independent": True,
"required_paths": [
"real SPHLite + mock FEMLite, 1 step empty coupling",
"mock SPHLite + real FEMLite, 1 step empty coupling",
"at least one single-real-worker path, 100 step empty coupling",
"real-worker payload header and stride validation",
"real-worker empty or controlled load import validation",
],
"pass_conditions": [
"worker process starts through the CCLite worker CLI",
"command seq/ack stays matched for all commands",
"worker exports an empty or controlled interface block that passes CCLite validation",
"worker consumes an empty or controlled load block and acknowledges IMPORT_LOADS",
"worker responds to ADVANCE and STOP without timeout or residual process",
],
"controlled_gap_conditions": [
"published command block layout differs from CCLite generic command block",
"published data header layout differs from CCLite generic data block header",
"resource naming cannot be mapped without an adapter",
"record stride or block role cannot be validated by the current CCLite reader",
],
"path_results": {
"real_sphlite_mock_fem_1step": build_controlled_gap_path(
"Real SPHLite plus mock FEMLite, 1 step empty coupling.",
sph_standard,
sph_blockers,
),
"mock_sphlite_real_femlite_1step": build_controlled_gap_path(
"Mock SPHLite plus real FEMLite, 1 step empty coupling.",
fem_explicit_ipc if fem_explicit_ipc.get("real_ipc_attach_attempted") else fem_standard,
fem_blockers,
),
"single_real_worker_100step": build_controlled_gap_path(
"At least one single-real-worker path, 100 step empty coupling.",
None,
[
"The 100 step gate depends on one executable 1 step real-worker adapter path.",
"No seq/ack, timeout, or resource-release claim is made before that adapter path exists.",
],
),
"payload_read_smoke": build_controlled_gap_path(
"Real worker exported interface block header and payload validation.",
None,
payload_blockers,
),
"load_import_smoke": build_controlled_gap_path(
"Real worker empty or controlled load block import validation.",
None,
load_blockers,
),
},
"worker_capability_summary": worker_summary,
}
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--sph-exe", required=True)
parser.add_argument("--fem-exe", required=True)
parser.add_argument("--case-dir", required=True)
parser.add_argument("--fem-case", required=True)
parser.add_argument("--report", required=True)
args = parser.parse_args()
case_dir = Path(args.case_dir)
report_path = Path(args.report)
sph_exe = Path(args.sph_exe)
fem_exe = Path(args.fem_exe)
sph_capabilities = run_capabilities_probe(sph_exe)
fem_capabilities = run_capabilities_probe(fem_exe)
sph_version = run_version_probe(sph_exe)
fem_version = run_version_probe(fem_exe)
sph_standard = run_standard_worker_probe(sph_exe, "SPH", case_dir / "mock_sph.inp")
fem_standard = run_standard_worker_probe(fem_exe, "FEM", Path(args.fem_case))
fem_explicit_ipc = run_standard_worker_probe(
fem_exe,
"FEM",
Path(args.fem_case),
["--worker-backend", "ipc", "--data-prefix", "CCLITE_REAL_WORKER_AUDIT"],
)
fem_mock = run_femlite_mock_probe(fem_exe, Path(args.fem_case), report_path)
protocol_alignment = build_protocol_alignment(fem_exe)
adapter_strategy = build_adapter_strategy()
worker_summary = {
"sphlite": build_worker_capability_summary(
sph_exe,
sph_capabilities,
sph_version,
"CONTROLLED_PROTOCOL_GAP",
),
"femlite": build_worker_capability_summary(
fem_exe,
fem_capabilities,
fem_version,
"CONTROLLED_PROTOCOL_GAP",
),
}
v020_adapter_gate = build_v020_adapter_gate(
adapter_strategy,
worker_summary,
sph_standard,
fem_standard,
fem_explicit_ipc,
)
both_report_real_ipc = sph_capabilities["supports_real_ipc"] and fem_capabilities["supports_real_ipc"]
both_attach_attempted = (
sph_standard["real_ipc_attach_attempted"]
and (fem_standard["real_ipc_attach_attempted"] or fem_explicit_ipc["real_ipc_attach_attempted"])
)
if both_report_real_ipc and both_attach_attempted:
status = "EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED"
elif both_report_real_ipc:
status = "EXTERNAL_WORKERS_REPORT_REAL_IPC"
elif fem_mock["status"] == "WORKER_MOCK_AVAILABLE":
status = "PARTIAL_EXTERNAL_WORKER_SUPPORT"
else:
status = "CONTROLLED_GAP"
report = {
"status": status,
"gate_status": v020_adapter_gate["status"],
"required_worker_args": [
"--cclite-worker",
"--solver-id <SPH|FEM>",
"--case <solver.inp>",
"--ipc-name <prefix>",
"--timeout-ms <milliseconds>",
],
"sphlite_capabilities": sph_capabilities,
"femlite_capabilities": fem_capabilities,
"sphlite_version": sph_version,
"femlite_version": fem_version,
"adapter_strategy": adapter_strategy,
"worker_capability_summary": worker_summary,
"sphlite_standard_ipc": sph_standard,
"femlite_standard_ipc": fem_standard,
"femlite_explicit_ipc_backend": fem_explicit_ipc,
"femlite_worker_mock": fem_mock,
"protocol_alignment": protocol_alignment,
"v020_adapter_gate": v020_adapter_gate,
"conclusion": [
"The current SPHLite package reports CCLite worker and Windows shared memory/named event support.",
"The current FEMLite package reports CCLite worker, worker mock, and Windows shared memory/named event support.",
"Both workers now attempt real IPC attach when launched without pre-created CCLite resources.",
"CCLite 0.2.9 records V020_SINGLE_REAL_WORKER_SMOKE as CONTROLLED_PROTOCOL_GAP until the CCLite-side protocol/name adapter passes process-level tests.",
"Mock-worker IPC integration remains the executable acceptance path until the adapter-level process tests pass.",
],
}
report_path.parent.mkdir(parents=True, exist_ok=True)
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"real worker audit -> {report_path}")
return 0
if __name__ == "__main__":
raise SystemExit(main())