{
  "$schema": "autocode-verification-input-v1",
  "feature_id": "F003",
  "spec_path": "specs/F003-IMPLEMENTATION_SPEC.md",
  "generated": "2026-03-27T12:00:00Z",
  "verification_mode": "mvp",

  "overview": {
    "summary": "Dense 3-layer reward system for SQLEnv. Layer 1 provides operational signals (exec_ok, new_info, repeat penalty, step_cost). Layer 2 computes progress-to-target for QUERY actions using fixed weighted average of cardinality (0.25), value overlap (0.50), and numeric range proximity (0.25), binned to 5 levels with improvement-only gating. Layer 3 is the existing terminal correctness signal. Total step rewards clamped to [-0.2, +0.5].",
    "goal": "Agents get meaningful per-step feedback during exploration so GRPO training converges. Random exploration yields ~0.1 cumulative reward, targeted queries ~0.3, correct answer ~1.3."
  },

  "interfaces": {
    "types": [
      {
        "name": "EpisodeContext",
        "fields": [
          {"name": "gold_rows", "type": "list[tuple]", "optional": false, "description": "Gold SQL result rows cached at reset(), used by Layer 2 progress metrics"},
          {"name": "query_hashes", "type": "set[str]", "optional": false, "description": "Set of hashes of previously executed SQL strings for repeat detection"},
          {"name": "best_progress", "type": "float", "optional": false, "description": "Best binned progress score seen so far (improvement-only gating)"},
          {"name": "cumulative_step_reward", "type": "float", "optional": false, "description": "Running total of step rewards for clamping to [-0.2, +0.5]"},
          {"name": "cumulative_new_info_reward", "type": "float", "optional": false, "description": "Running total of new_info rewards for capping at 0.10"}
        ],
        "description": "Per-episode server-side state extended with reward-tracking fields"
      }
    ],
    "functions": [
      {
        "name": "compute_step_reward",
        "params": [
          {"name": "ctx", "type": "EpisodeContext", "description": "Episode context (mutated: updates tracking fields)"},
          {"name": "action_type", "type": "str", "description": "One of DESCRIBE, SAMPLE, QUERY"},
          {"name": "sql", "type": "str", "description": "SQL string executed (for repeat detection)"},
          {"name": "rows", "type": "list[tuple] | None", "description": "Result rows from query, or None if error"},
          {"name": "error", "type": "str | None", "description": "Error message if action failed, else None"}
        ],
        "returns": "float",
        "description": "Main entry point. Combines Layer 1 + Layer 2 signals, clamps running total to [-0.2, +0.5]."
      },
      {
        "name": "_layer1_operational",
        "params": [
          {"name": "ctx", "type": "EpisodeContext", "description": "Episode context"},
          {"name": "action_type", "type": "str", "description": "Action type string"},
          {"name": "sql", "type": "str", "description": "SQL string for repeat detection"},
          {"name": "rows", "type": "list[tuple] | None", "description": "Result rows"},
          {"name": "error", "type": "str | None", "description": "Error message if failed"}
        ],
        "returns": "float",
        "description": "Layer 1 operational signals: exec_ok(+0.02), new_info(+0.01 capped 0.10), repeat(-0.01), step_cost(-0.005)."
      },
      {
        "name": "_layer2_progress",
        "params": [
          {"name": "ctx", "type": "EpisodeContext", "description": "Episode context with gold_rows"},
          {"name": "rows", "type": "list[tuple]", "description": "Query result rows"}
        ],
        "returns": "float",
        "description": "Layer 2 progress-to-target for QUERY only. Weighted avg of sub-metrics, binned to 5 levels, improvement-only, scaled by 0.15."
      },
      {
        "name": "_cardinality_score",
        "params": [
          {"name": "pred_rows", "type": "list[tuple]", "description": "Predicted result rows"},
          {"name": "gold_rows", "type": "list[tuple]", "description": "Gold result rows"}
        ],
        "returns": "float",
        "description": "Row count similarity: 1 - |len(pred) - len(gold)| / max(len(pred), len(gold), 1). Returns [0.0, 1.0]."
      },
      {
        "name": "_value_overlap_score",
        "params": [
          {"name": "pred_rows", "type": "list[tuple]", "description": "Predicted result rows"},
          {"name": "gold_rows", "type": "list[tuple]", "description": "Gold result rows"}
        ],
        "returns": "float",
        "description": "Jaccard overlap of flattened cell values as strings. Returns [0.0, 1.0]."
      },
      {
        "name": "_numeric_range_score",
        "params": [
          {"name": "pred_rows", "type": "list[tuple]", "description": "Predicted result rows"},
          {"name": "gold_rows", "type": "list[tuple]", "description": "Gold result rows"}
        ],
        "returns": "float",
        "description": "Log-distance proximity for numeric cells. mean(1/(1+log(1+|pred-gold|))). Returns 1.0 if no numerics in gold. Returns [0.0, 1.0]."
      },
      {
        "name": "_bin_progress",
        "params": [
          {"name": "raw_score", "type": "float", "description": "Raw progress score in [0.0, 1.0]"}
        ],
        "returns": "float",
        "description": "Bin to {0, 0.25, 0.5, 0.75, 1.0}. Thresholds at 0.125, 0.375, 0.625, 0.875."
      }
    ],
    "api_endpoints": []
  },

  "data_flow": {
    "primary_flow": [
      "step() receives SQLAction with action_type and argument",
      "step() dispatches to handler (_handle_query, _handle_describe, _handle_sample)",
      "For non-terminal actions, step() calls compute_step_reward(ctx, action_type, sql, rows, error)",
      "compute_step_reward calls _layer1_operational for all action types",
      "compute_step_reward calls _layer2_progress for QUERY actions only (when rows is not None and gold_rows is not empty)",
      "_layer2_progress computes weighted average of _cardinality_score(0.25), _value_overlap_score(0.50), _numeric_range_score(0.25)",
      "_layer2_progress bins result via _bin_progress, rewards only improvement over best_progress, scales by 0.15",
      "compute_step_reward sums Layer 1 + Layer 2, clamps cumulative to [-0.2, +0.5], returns step reward"
    ],
    "alternative_flows": [
      {
        "name": "SQL error on QUERY",
        "trigger": "Query execution raises sqlite3.Error",
        "steps": [
          "step() catches error, sets error string",
          "compute_step_reward called with error set and rows=None",
          "Layer 1 returns step_cost only (-0.005)",
          "Layer 2 skipped"
        ]
      },
      {
        "name": "Empty gold_rows",
        "trigger": "Gold SQL returned no rows at reset()",
        "steps": [
          "gold_rows stored as empty list in EpisodeContext",
          "Layer 2 returns 0.0 (skipped)",
          "Layer 1 operates normally"
        ]
      },
      {
        "name": "Repeated query",
        "trigger": "SQL hash already in ctx.query_hashes",
        "steps": [
          "Layer 1 applies repeat penalty (-0.01) in addition to step_cost",
          "No exec_ok bonus for repeated query",
          "Layer 2 still computes progress (may still show improvement)"
        ]
      }
    ]
  },

  "error_handling": {
    "error_types": [
      {
        "name": "SQL execution error",
        "when": "Invalid query syntax or runtime SQL error during QUERY action",
        "message_template": "Layer 1 returns step_cost only; Layer 2 skipped"
      },
      {
        "name": "Empty gold rows",
        "when": "Gold SQL returns no rows at episode reset",
        "message_template": "Layer 2 returns 0.0; Layer 1 operates normally"
      }
    ],
    "retry_strategy": null
  },

  "dependencies": {
    "external": [],
    "internal": [
      "models.py (EpisodeContext dataclass)",
      "server/sql_environment.py (step() and reset() integration)",
      "tests/test_smoke.py (existing tests need assertion updates)"
    ]
  }
}