Handoff Schema — calc_debug_handoff/1 (Locked)
Every successful calc-debugger invocation emits this schema. Downstream calc-family peers consume it. Schema is versioned; unknown versions refused by downstream.
Full Schema
schema_version: calc_debug_handoff/1
datasource_name: {name}
original_calc_name: {name}
original_formula: {formula_text}
fixed_calc_name: {name}
fixed_formula: {formula_text}
error_pattern_id: {E-NULL | E-SYNTAX | E-TYPE | E-AGG | E-LOD | E-FIELD | E-PARAM | E-GRAIN | E-CIRC}
root_cause: {short_string}
fix_approach: {short_string}
calc_type: {row_level | aggregate | lod_fixed | lod_include | lod_exclude | table_calc}
return_type: {number | string | date | datetime | boolean | spatial}
references:
fields: [{field_name}, ...]
parameters: [{param_name} (cited, not resolved), ...]
sets: [{set_name} (cited, not resolved), ...]
nested_calcs: [{calc_name}, ...]
verified: {true | false}
sample_size: {N | "below_threshold" | "verification_skipped"}
integrity_gate_passed: {true | false}
perf_advisory:
flags: [{flag_id}, ...]
severity: {none | note | warning}
recommendation: {optional_free_text}
overwrites_original: {true | false}
notes: {optional_free_text}
Field-by-Field
- schema_version: always exactly
calc_debug_handoff/1. - datasource_name: the data source the fixed calc was authored on.
- original_calc_name / original_formula: the broken calc's name and formula, captured from the workbook.
- fixed_calc_name: default
[original name] Fixed; may equaloriginal_calc_nameifoverwrites_original: true. - fixed_formula: the corrected formula authored via
author-calc. - error_pattern_id: one of nine locked values from the error-pattern catalog. Never blank.
- root_cause: short string describing what went wrong (e.g., "NULL propagation from ZN-less denominator").
- fix_approach: short string describing the fix strategy (e.g., "wrapped denominator with ZN, added divide-by-zero guard").
- calc_type, return_type, references: same as calc-writer.
- verified, sample_size, integrity_gate_passed: same as calc-writer.
- perf_advisory: written at fix time, advisory-only. Same catalog as calc-writer: PA-COUNTD-HIGH-CARDINALITY, PA-REGEXP-IN-AGGREGATE, PA-CONTAINS-IN-AGGREGATE, PA-LOD-NESTED, PA-TABLE-CALC-WHERE-LOD-WOULD-WORK, PA-CROSS-DS-BLEND, PA-DATEDIFF-IN-FILTER, PA-NESTED-IF-DEEP, PA-STRING-ARITHMETIC. Never blocks delivery.
- overwrites_original:
trueif user opted in to overwrite the original broken calc;falseif fix was authored as[original name] Fixed. - notes: optional free-text. Common uses: R-LOD-03 filter-order acknowledgment; R-TC-01 partitioning intent; verification caveat; user-directed customization.
Downstream Consumer Expectations
calc-optimizerconsumes when user says "now optimize it": readsfixed_formula,calc_type,return_type,references; producescalc_optimize_handoff/1.calc-linterconsumes when user says "now lint it": readsfixed_formula,calc_type,fixed_calc_name; producescalc_lint_handoff/1.calc-inventoryconsumes when user says "include this in the catalog": reads all fields.calc-writerdoes NOT consume this schema (calc-writer starts fresh from the natural-language ask, not from a fix output).join-and-relationship-advisordoes NOT consume this schema directly; if E-GRAIN routes to it, the routing carries only the root_cause + original context, not the full handoff.
Refuse to Guess
If any required field can't be populated, populate the appropriate sentinel value and note in notes. Never leave a required field blank.