CHAPTER 04HI Entries

Req. prefix: HEv0.2 draft

4.1Semantics

HE-01An entry is an override volume: "this modification amounts to value_su over this scope." It is not a delta on, or a replacement of, the baseline forecast — how it combines with anything else is downstream and out of scope (OV-07).

HE-02value_su is a non-negative integer in SU. Zero is legal (it disaggregates to an empty LO row set and states an explicit "no volume").

HE-03Typical entry archetypes the scope model MUST express: (a) brand-level campaign, all locations, no customer, one quarter; (b) customer inventory strategy on a category, one month; (c) promotion on a single product with a single customer, one week.

4.2Scope validation

HE-04On create/update the system MUST validate: referenced hierarchy node, location, customer and period exist (DM-01…DM-06); period lies within the calendar horizon. Validation failures reject the request — they never produce an InError entry.

HE-05Overlapping entries are permitted without warning or restriction — including identical scopes. Reasonability assessment happens downstream, outside HiLo.FM.

4.3State machine

State	Meaning	LO rows present?
Disaggregated	Current LO rows are consistent with the entry and current inputs	yes (possibly empty set for value 0)
InError	Disaggregation attempted and impossible under current rules; `error_message` set	no
RequiresDisaggregation	Inputs changed since last disaggregation; LO rows stale or absent	possibly stale

            create / update ─────► [attempt disaggregation]
                                              │ success        │ failure
                                              ▼                ▼
                                        Disaggregated       InError ── error_message
                                              │                │
     input regeneration (reset / DE-08) ──────┴───────────────►│
                                              ▼                │
                                   RequiresDisaggregation ◄────┘ (regeneration also resets InError)
                                              │
                              batch or per-entry re-run ──► [attempt disaggregation] …

HE-06Create and update MUST synchronously attempt disaggregation (OV-02). The response carries the resulting state; the caller never observes RequiresDisaggregation as the outcome of its own edit.

HE-07Wholesale replacement of the inputs — forecast regeneration (DE-08) or seed-profile change short of a full reset — MUST set all entries (including InError) to RequiresDisaggregation, since any of them may now resolve differently. The subsequent batch (Ch. 06) moves each to Disaggregated or InError. (A full reset deletes all entries and recreates seeds, so HE-07 is moot there — DE-04.)

HE-08error_message MUST name the failing stage and rule, with the offending scope element — e.g.

"Location split: no basis for P3/W1 — zero forecast, no split
table, phase-in factor 0"

. Vague messages ("disaggregation failed") are non-conforming.

HE-09While an entry is InError or RequiresDisaggregation, its (absent or stale) LO rows MUST be excluded from reporting by default; interfaces MAY offer an explicit "include stale" toggle that labels affected rows.

4.4Lifecycle operations

Operation	Effect
Create	Validate (HE-04) → persist → disaggregate → state per result
Update (scope, value, title)	Validate → persist → atomically replace own LO rows (DM-12) → state per result
Delete	Remove entry and exactly its own LO rows. Nothing else moves. Hard delete (no audit trail).
Re-disaggregate (single)	Manual per-entry re-run; same path as batch, one entry

HE-10All four operations MUST be available in UI, API and MCP alike (OV-04).