main.py

"""WCM CLI — scenario runner and quality-gate dispatcher.

Entry point for all headless and interactive WCM sessions.  Parses CLI
arguments, selects a scenario, and delegates to the appropriate runner
in scenarios/scenario_runners.py or scenarios/waveil_flow_gates.py.

Scenario families:
  - Demos & unit tests:  quick headless runs that exercise a single
    subsystem (substrate, storage, windowing, boot, apps).
  - Desktop-live:        interactive GUI sessions (Tkinter window) with
    optional strict-WaveIL-only mode and session-restore.
  - Quality gates:       automated pass/fail checks (ownership, ABI,
    HAL boundary, sparse substrate, production-strict).
  - CI sweep:            full regression sweep bundling all gates.
  - SDK:                 WaveLang package build/install/run pipeline.

Architectural note (see docs/DEV_MODE.md §2.1):
  This file is pure dispatch plumbing — it never touches the substrate,
  the shell, or any WaveIL state.  All physics and policy live in the
  modules it delegates to.
"""

import argparse

import scenarios.scenario_runners as runners
import scenarios.waveil_flow_gates as flow


def main():
	"""Parse CLI arguments and dispatch to the selected scenario runner."""
	parser = argparse.ArgumentParser(description="WaveOS scenario runner")

	# --- Scenario selection --------------------------------------------------
	# Grouped: demos/unit → desktop-live → gates → CI/milestones → SDK.
	parser.add_argument(
		"--scenario",
		default="demo",
		choices=[
			# Demos & unit-level scenarios
			"demo",
			"stress",
			"burst",
			"spawn",
			"fs",
			"fs-batch",
			"windowing",
			"runtime",
			"boot",
			"boot-hardening",
			"threshold-demo",
			"abi-smoke",
			"driver-bridge",
			"driver-kpi-gate",
			"shell-desktop",
			"explorer-desktop",
			# Desktop-live (interactive GUI)
			"desktop-live",
			"desktop-live-empty",
			"desktop-live-strict",
			"desktop-live-strict-empty",
			"desktop-live-restore",
			"desktop-live-strict-restore",
			"desktop-live-gate",
			"desktop-resolution-perf",
			"desktop-resolution-perf-sparse",
			"desktop-tick-probe-tmp",
			# Quality gates
			"semantic-ownership-gate",
			"semantic-ownership-horizon-gate",
			"python-off-gate",
			"storage-backend-gate",
			"storage-backends-gate",
			"production-strict-gate",
			"hal-boundary-gate",
			"substrate-sparse-gate",
			"substrate-sparse-grid-scaling",
			"strict-waveil-first-gate",
			"desktop-shell-inspector",
			"app-surface-contract",
			"waveil-desktop-flow",
			"waveil-explorer-flow",
			"minimum-selfhosted-baseline-gate",
			# CI sweeps & milestones
			"milestone10-gate",
			"ci-sweep",
			"milestone11-sdk",
			"milestone11-conformance",
			# SDK pipeline
			"sdk-cli",
		],
		help="Scenario to execute",
	)

	# --- General timing ------------------------------------------------------
	parser.add_argument("--ticks", type=int, default=2000, help="Tick count for applicable scenarios")
	parser.add_argument("--cycles", type=int, default=10, help="Cycle count for hardening scenario")
	parser.add_argument("--repeats", type=int, default=3, help="Repeat count for repeated gate scenarios")

	# --- Driver-bridge knobs -------------------------------------------------
	parser.add_argument(
		"--replay-log",
		type=str,
		default="artifacts/wcm_driver_replay.json",
		help="Path for driver bridge replay artifact",
	)
	parser.add_argument(
		"--use-replay-log",
		action="store_true",
		help="Use existing replay artifact for driver-bridge scenario",
	)
	parser.add_argument(
		"--input-burst",
		action="store_true",
		help="Enable burst input stress mode in driver-bridge scenario",
	)
	parser.add_argument("--burst-period", type=int, default=240, help="Burst period in ticks for driver-bridge")
	parser.add_argument("--burst-len", type=int, default=40, help="Burst length in ticks for driver-bridge")
	parser.add_argument("--burst-mult", type=int, default=8, help="Extra pointer events injected per burst tick")

	# --- Desktop-live tuning -------------------------------------------------
	parser.add_argument("--frame-ms", type=int, default=33, help="Frame interval in ms for desktop-live scenarios")
	parser.add_argument("--live-stride", type=int, default=1, help="Compositor stride for desktop-live scenarios")
	parser.add_argument("--present-mode", type=str, default="delta", choices=["full", "delta"], help="Present path mode for desktop perf scenarios")
	parser.add_argument("--delta-tile-size", type=int, default=16, help="Tile size for delta present mode")
	parser.add_argument("--delta-pixel-eps", type=float, default=0.02, help="Pixel epsilon threshold for delta present mode")
	parser.add_argument("--delta-max-dirty-tiles", type=int, default=0, help="Max dirty tiles committed per tick in delta present mode (0=unbounded)")

	# --- Sparse substrate knobs ----------------------------------------------
	parser.add_argument("--sparse-active-eps", type=float, default=0.05, help="Active epsilon threshold for sparse substrate gate")
	parser.add_argument("--sparse-delta-only", action="store_true", help="Use delta-only frontier update in sparse substrate gate")
	parser.add_argument("--sparse-eventized-ops", action="store_true", help="Eventize sparse operator outputs for localized injection behavior")
	parser.add_argument("--sparse-frontier-budget-ratio", type=float, default=0.0, help="Max admitted sparse frontier as ratio of total cells (0 disables budget)")
	parser.add_argument("--sparse-passive-relax-interval", type=int, default=4, help="Sparse passive relax cadence in ticks (0 disables passive relax)")
	parser.add_argument("--sparse-contract", type=str, default="chipset", choices=["parity", "chipset"], help="Sparse gate contract: legacy-parity or sparse-chipset readiness")
	parser.add_argument("--sparse-grid-scales", type=str, default="1,2,3", help="Comma-separated grid scale multipliers for sparse grid scaling gate")
	parser.add_argument("--restore-tick", type=int, default=12000, help="Tick to trigger restore flow in desktop-live-restore")
	parser.add_argument("--headless-live", action="store_true", help="Run desktop-live scenarios without opening host GUI window")
	parser.add_argument("--host-ui-raster", action="store_true", help="Enable legacy host semantic raster overlay for debugging")

	# --- Threshold / baseline ------------------------------------------------
	parser.add_argument(
		"--baseline-log",
		type=str,
		default="artifacts/wcm_threshold_baseline.json",
		help="Path for threshold demo KPI artifact",
	)

	# --- SDK pipeline --------------------------------------------------------
	parser.add_argument(
		"--sdk-command",
		type=str,
		default="workflow",
		choices=["init", "build", "install", "run", "workflow"],
		help="SDK CLI command when --scenario sdk-cli is selected",
	)
	parser.add_argument("--sdk-dir", type=str, default="sdk_apps/demo", help="SDK app workspace directory")
	parser.add_argument("--app-id", type=str, default="demo.app", help="App id for SDK init/workflow")
	parser.add_argument(
		"--primary-domain",
		type=str,
		default="p12",
		help="Primary domain name in generated manifest resource scope",
	)
	parser.add_argument("--manifest", type=str, default="", help="Path to manifest.json")
	parser.add_argument("--module", type=str, default="", help="Path to module.waveil.json")
	parser.add_argument("--package", type=str, default="", help="Path to package.wpk.json")
	args = parser.parse_args()

	# === Scenario dispatch ===================================================

	# --- Core demos & unit tests ---------------------------------------------
	if args.scenario == "demo":
		runners.run_demo()
	elif args.scenario == "stress":
		runners.run_stress_test(max_ticks=max(1, args.ticks))
	elif args.scenario == "burst":
		runners.run_burst_test(max_ticks=max(1, args.ticks))
	elif args.scenario == "spawn":
		runners.run_spawn_scenario(max_ticks=max(1, args.ticks))
	elif args.scenario == "fs":
		runners.run_attractor_fs_test(max_ticks=max(1, args.ticks))
	elif args.scenario == "fs-batch":
		runners.run_attractor_fs_batch_benchmark(max_ticks=max(1, args.ticks))
	elif args.scenario == "windowing":
		runners.run_windowing_scenario(max_ticks=max(1, args.ticks))
	elif args.scenario == "runtime":
		runners.run_runtime_apps_scenario(max_ticks=max(1, args.ticks))
	elif args.scenario == "boot":
		runners.run_boot_sequence_scenario(max_ticks=max(1, args.ticks))
	elif args.scenario == "boot-hardening":
		runners.run_boot_hardening(cycles=max(1, args.cycles))
	elif args.scenario == "threshold-demo":
		runners.run_real_os_threshold_demo(runtime_ticks=max(1, args.ticks), baseline_log_path=args.baseline_log)
	elif args.scenario == "abi-smoke":
		runners.run_abi_conformance_smoke(max_ticks=max(100, min(args.ticks, 1000)))
	elif args.scenario == "driver-bridge":
		runners.run_driver_bridge_scenario(
			max_ticks=max(300, args.ticks),
			replay_log_path=args.replay_log,
			use_replay_log=args.use_replay_log,
			input_burst=args.input_burst,
			burst_period=max(1, int(args.burst_period)),
			burst_len=max(0, int(args.burst_len)),
			burst_mult=max(0, int(args.burst_mult)),
		)
	elif args.scenario == "driver-kpi-gate":
		runners.run_driver_kpi_gate(
			replay_log_path=args.replay_log,
			ticks=max(300, args.ticks),
			input_burst=args.input_burst,
			burst_period=max(1, int(args.burst_period)),
			burst_len=max(0, int(args.burst_len)),
			burst_mult=max(0, int(args.burst_mult)),
		)
	elif args.scenario == "shell-desktop":
		runners.run_shell_desktop_scenario(max_ticks=max(800, args.ticks))
	elif args.scenario == "explorer-desktop":
		runners.run_explorer_desktop_scenario(max_ticks=max(900, args.ticks))

	# --- Desktop-live variants (interactive GUI) -----------------------------
	elif args.scenario == "desktop-live":
		runners.run_desktop_live_scenario(
			max_ticks=max(300, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=False,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=False,
			boot_empty_desktop=False,
		)
	elif args.scenario == "desktop-live-empty":
		runners.run_desktop_live_scenario(
			max_ticks=max(300, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=False,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=False,
			boot_empty_desktop=True,
		)
	elif args.scenario == "desktop-live-strict":
		runners.run_desktop_live_scenario(
			max_ticks=max(300, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=False,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=True,
			boot_empty_desktop=False,
		)
	elif args.scenario == "desktop-live-strict-empty":
		runners.run_desktop_live_scenario(
			max_ticks=max(300, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=False,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=True,
			boot_empty_desktop=True,
		)
	elif args.scenario == "desktop-live-restore":
		runners.run_desktop_live_scenario(
			max_ticks=max(500, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=True,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=False,
			boot_empty_desktop=False,
		)
	elif args.scenario == "desktop-live-strict-restore":
		runners.run_desktop_live_scenario(
			max_ticks=max(500, int(args.ticks)),
			frame_ms=max(1, int(args.frame_ms)),
			stride=max(1, int(args.live_stride)),
			headless=bool(args.headless_live),
			with_restore=True,
			restore_tick=max(100, int(args.restore_tick)),
			host_ui_raster=bool(args.host_ui_raster),
			python_off=True,
			boot_empty_desktop=False,
		)
	elif args.scenario == "desktop-live-gate":
		runners.run_desktop_live_gate(
			repeats=max(1, int(args.repeats)),
			ticks=max(400, int(args.ticks)),
			restore_ticks=max(600, int(args.ticks) + 400),
			restore_tick=max(100, int(args.restore_tick)),
		)
	elif args.scenario == "desktop-resolution-perf":
		runners.run_desktop_resolution_perf_gate(
			ticks=max(200, int(args.ticks)),
			target_fps=max(1, int(round(1000.0 / max(1, int(args.frame_ms))))),
			compose_stride=max(1, int(args.live_stride)),
			present_mode=str(args.present_mode),
			delta_tile_size=max(1, int(args.delta_tile_size)),
			delta_pixel_eps=float(args.delta_pixel_eps),
			delta_max_dirty_tiles=max(0, int(args.delta_max_dirty_tiles)),
			sparse_enabled=True,
			active_eps=float(args.sparse_active_eps),
			delta_only_frontier=bool(args.sparse_delta_only),
			eventized_operators=bool(args.sparse_eventized_ops),
			frontier_budget_ratio=float(args.sparse_frontier_budget_ratio),
			passive_relax_interval=max(0, int(args.sparse_passive_relax_interval)),
		)
	elif args.scenario == "desktop-resolution-perf-sparse":
		runners.run_desktop_resolution_perf_gate(
			ticks=max(200, int(args.ticks)),
			target_fps=max(1, int(round(1000.0 / max(1, int(args.frame_ms))))),
			compose_stride=max(1, int(args.live_stride)),
			present_mode=str(args.present_mode),
			delta_tile_size=max(1, int(args.delta_tile_size)),
			delta_pixel_eps=float(args.delta_pixel_eps),
			delta_max_dirty_tiles=max(0, int(args.delta_max_dirty_tiles)),
			sparse_enabled=True,
			active_eps=float(args.sparse_active_eps),
			delta_only_frontier=bool(args.sparse_delta_only),
			eventized_operators=bool(args.sparse_eventized_ops),
			frontier_budget_ratio=float(args.sparse_frontier_budget_ratio),
			passive_relax_interval=max(0, int(args.sparse_passive_relax_interval)),
		)
	elif args.scenario == "desktop-tick-probe-tmp":
		runners.run_desktop_tick_probe_tmp(
			ticks=max(120, int(args.ticks)),
			compose_stride=max(1, int(args.live_stride)),
			delta_tile_size=max(1, int(args.delta_tile_size)),
			delta_pixel_eps=float(args.delta_pixel_eps),
			delta_max_dirty_tiles=max(0, int(args.delta_max_dirty_tiles)),
			active_eps=float(args.sparse_active_eps),
			delta_only_frontier=bool(args.sparse_delta_only),
			eventized_operators=bool(args.sparse_eventized_ops),
			frontier_budget_ratio=float(args.sparse_frontier_budget_ratio),
			passive_relax_interval=max(0, int(args.sparse_passive_relax_interval)),
		)

	# --- Quality gates -------------------------------------------------------
	elif args.scenario == "semantic-ownership-gate":
		runners.run_semantic_ownership_gate(ticks=max(500, int(args.ticks)))
	elif args.scenario == "semantic-ownership-horizon-gate":
		runners.run_semantic_ownership_horizon_gate(short_ticks=1000, long_ticks=5000)
	elif args.scenario == "python-off-gate":
		flow.run_python_off_gate(ticks=max(700, int(args.ticks)))
	elif args.scenario == "storage-backend-gate":
		runners.run_storage_backend_gate(ticks=max(900, int(args.ticks)))
	elif args.scenario == "storage-backends-gate":
		runners.run_storage_backends_gate(ticks=max(900, int(args.ticks)))
	elif args.scenario == "production-strict-gate":
		flow.run_production_strict_gate(ticks=max(700, int(args.ticks)))
	elif args.scenario == "hal-boundary-gate":
		runners.run_hal_boundary_gate(ticks=max(700, int(args.ticks)))
	elif args.scenario == "substrate-sparse-gate":
		runners.run_substrate_sparse_gate(
			ticks=max(500, int(args.ticks)),
			active_eps=float(args.sparse_active_eps),
			delta_only_frontier=bool(args.sparse_delta_only),
			eventized_operators=bool(args.sparse_eventized_ops),
			frontier_budget_ratio=float(args.sparse_frontier_budget_ratio),
			passive_relax_interval=max(0, int(args.sparse_passive_relax_interval)),
			sparse_contract=str(args.sparse_contract),
		)
	elif args.scenario == "substrate-sparse-grid-scaling":
		scales = []
		for token in str(args.sparse_grid_scales).split(","):
			t = token.strip()
			if not t:
				continue
			try:
				scales.append(max(1, int(t)))
			except ValueError:
				continue
		if not scales:
			scales = [1, 2, 3]
		runners.run_substrate_sparse_grid_scaling_gate(
			ticks=max(120, int(args.ticks)),
			scales=scales,
			active_eps=float(args.sparse_active_eps),
			delta_only_frontier=bool(args.sparse_delta_only),
			eventized_operators=bool(args.sparse_eventized_ops),
			frontier_budget_ratio=float(args.sparse_frontier_budget_ratio),
			passive_relax_interval=max(0, int(args.sparse_passive_relax_interval)),
		)
	elif args.scenario == "strict-waveil-first-gate":
		flow.run_strict_waveil_first_gate(ticks=max(700, int(args.ticks)))
	elif args.scenario == "desktop-shell-inspector":
		runners.run_desktop_shell_inspector_scenario(ticks=max(500, int(args.ticks)))
	elif args.scenario == "app-surface-contract":
		runners.run_app_surface_contract_scenario(ticks=max(500, int(args.ticks)))
	elif args.scenario == "waveil-desktop-flow":
		flow.run_waveil_desktop_flow_scenario(ticks=max(300, int(args.ticks)))
	elif args.scenario == "waveil-explorer-flow":
		runners.run_waveil_explorer_flow_scenario(ticks=max(400, int(args.ticks)))
	elif args.scenario == "minimum-selfhosted-baseline-gate":
		runners.run_minimum_selfhosted_baseline_gate(
			ticks=max(500, int(args.ticks)),
			repeats=max(1, int(args.repeats)),
			restore_tick=max(100, int(args.restore_tick)),
		)

	# --- CI sweeps & milestones ----------------------------------------------
	elif args.scenario == "milestone10-gate":
		flow.run_milestone10_gate(repeats=max(1, int(args.repeats)), ticks=max(900, int(args.ticks)))
	elif args.scenario == "ci-sweep":
		flow.run_ci_regression_sweep(ticks=max(900, int(args.ticks)))
	elif args.scenario == "milestone11-sdk":
		flow.run_milestone11_sdk_scenario(max_ticks=max(300, int(args.ticks)))
	elif args.scenario == "milestone11-conformance":
		flow.run_milestone11_conformance_scenario(max_ticks=max(200, int(args.ticks)))
	# --- SDK pipeline --------------------------------------------------------
	elif args.scenario == "sdk-cli":
		flow.run_sdk_cli(
			command=str(args.sdk_command),
			sdk_dir=str(args.sdk_dir),
			app_id=str(args.app_id),
			primary_domain=str(args.primary_domain),
			manifest_path=str(args.manifest),
			module_path=str(args.module),
			package_path=str(args.package),
			ticks=max(1, int(args.ticks)),
		)


if __name__ == "__main__":
	main()