Supersedes the pint-string declaration surface: unit= takes one member of
a closed Unit enum (CURRENCY_FLOW, CURRENCY_STOCK, SHARE_FLOW, YEARS, ...).
Flow tokens are completed by the name suffix or reference_period under a
strict-coincidence rule (disagreement is an error, never precedence).
null never combines with reference_period; the old pint-string scheme and
its neighbouring design corners move to Alternatives.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Align the GEP text with the implemented design from grilling session #3:

- register_currency derives concrete declaration tokens (DM_*, EURO_*);
  the agnostic CURRENCY_* tokens denote the union of registered currencies.
- Parameters must be concrete, columns/functions must stay agnostic;
  the separate source_currency: key is gone (moved to Alternatives with
  the reasons it fell).
- Function-like parameter types declare input_unit:/output_unit: — one
  token per axis — with per-axis conversion semantics (bounds x f_in,
  intercepts x f_out, order-j coefficients x f_out/f_in^j).
- Per-dated-entry unit overrides express a changeover within one
  parameter's history; updates_previous cannot cross one.
- Derived nodes inherit the agnostic counterpart of a concrete source
  token; per-package schema enumeration; mettsim's 2020 currency reform
  cited as the end-to-end proof.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…nsionality

- Abstract leads with what the GEP adds (incl. automatic conversions),
  not the problems; drop the build-time/boundary aside.
- Terminology: simplify the unit-token entry and define 'core tokens';
  split agnostic vs concrete currency tokens into independent entries;
  drop the 'flow' and 'dimensionless declaration' entries; plainer language.
- Scope: drop the confusing 'time-agnostic' phrasing.
- Currency section: rename away from 'knob'; state accurately that
  parameters are converted while input data is expected in the run
  currency (checked, not converted).
- Errors: de-jargon; rewrite the 'time suffix on a complete token' case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Lead the usage section with parameters/input columns as the source of
units; cast a policy function's unit= as a checked restatement of the
inferred result (GEP-9 style), with the period suffix as the author's
real contribution. Keeps mandatory unit= on every node.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Abstract now states the mechanism (units declared on params/inputs,
  pint at build time baking factors, runtime untouched), which also
  removes the overlap with Motivation's problem statement.
- Detailed Description: drop 'union semantics' and 'currency knob'
  wording; clarify that the run currency converts parameters while
  input data is taken to already be in it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Per review decision: a pint-tagged input column is converted to the run
currency at the boundary (a DM-tagged column can feed a Euro run); bare
columns are still assumed to be in the run currency. Add an explicit
'Units at the boundary' subsection stating the input contract (optional,
converted) and that outputs are bare arrays, with pint-labelled outputs
recorded as future work.

NOTE: ttsim's Layer-2 boundary currently asserts (pint-120); it must be
updated to convert to match this design before the stack merges.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The wired boundary converts a tagged column's currency to the run currency
(period/area preserved); checking the tag against the column's declared
unit would need that unit at the boundary, which the interface DAG cannot
supply without a cycle, so it is recorded as future work.

The boundary checks a tag's period against the column's GEP-1 time suffix
(read off the name, no declared unit needed) and converts currency only.
Correct the earlier claim that full validation is blocked by a DAG cycle:
only the spec env depends on the data, so the declared *dimension* check is
deferred by choice, not impossible.

…_FLOW

- Dimensionless quantities declare DIMENSIONLESS (was unit: null); the
  per-period form is DIMENSIONLESS_FLOW (renamed from SHARE_FLOW). No
  DIMENSIONLESS_STOCK — only currency forces the explicit _STOCK/_FLOW split.
- Real gettsim example for DIMENSIONLESS_FLOW: zugangsfaktor_veränderung_pro_jahr.
- Boundary: currency conversion + strict period guard; null moved to Alternatives.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… `null`)

The DIMENSIONLESS rename had not reached the Detailed Description: six
spots still spelled a dimensionless declaration as `null` (the overview,
the scalar/dict/axis declaration rules, dict leaves), contradicting the
terminology section and the shipped implementation. Reword them to
`DIMENSIONLESS`, and drop the "declares no unit at all" phrasing that
mixed the old null framing with the new token. `reference_period: null`
and the Alternatives section (which documents `null` as the rejected
design) are left as-is.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Drop the _STOCK suffix (a currency stock is the bare CURRENCY token); remove
the "kind" column and HECTARES from the vocabulary; use uppercase EUR. Scalars
take their period from a name suffix, with reference_period reserved for
integer-keyed dict leaves and schedule axes; document the dict union-over-dates
mapping and a rename example. ANY/ALL aggregations are exempt, not dimensionless.
Replace the literal-tagging idiom with the verify_units=False body opt-out plus
DIMENSIONLESS-ordinal guidance. Add the parameter-rename migration note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Reframe the branch-coverage paragraph around data-independent coverage:
units depend only on which branch exists, not on which data reaches it, so
the dry-run explores every syntactic branch via a proxy + path explorer
rather than dry-running booleans twice. Covers multi-condition guards,
multiple guarded returns, and numeric-driven branches; the literal-zero
guard arm stays unit-polymorphic (ttsim #134).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… missing-only

Reflects the ttsim change (#117/#119/#121 stack): drop the structural
exemption for identifiers and boolean nodes — both are dimensionless
quantities and declare DIMENSIONLESS like any other node. Only
group-creation functions and framework date nodes stay exempt, so
UNSET_UNIT has a single meaning (no declaration = error). ANY/ALL
aggregations auto-assign DIMENSIONLESS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Group ids are identifiers (dimensionless); the @group_creation_function
decorator exposes no unit=, so it is auto-assigned DIMENSIONLESS rather
than exempted. Framework date nodes get their unit from the framework.
Every active node now has a unit; only the source differs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Two operands of an addition, subtraction, or ordering comparison must be in
equivalent units. At run time the assembled DAG computes on bare arrays with no
pint, so mixing a monthly and a yearly flow (or a stock and a flow) is unit-blind
and silently wrong; pint's build-time auto-conversion of same-dimension operands
would otherwise mask it during the dry-run. Document this alongside an explicit
list of what the dry-run can and cannot catch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Drop the dimensionless-result and ==/verify_units bullets: the dimensionless
fallback is already in the branch-coverage paragraph, the forgotten-*count
trade-off is in the [count] Alternatives, and verify_units is covered under
Literals. Keep wrong-magnitudes and un-dry-runnable operations, which are
stated nowhere else.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Restore the full "cannot catch" enumeration (wrong magnitudes, un-dry-runnable
operations, dimensionless-but-wrong results incl. forgotten per-capita scaling,
and ==/!= plus verify_units opt-outs) so the limitations live in one bulleted
list rather than scattered across the branch-coverage paragraph, Literals, and
the [count] Alternatives.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

A body the dry-run cannot evaluate (piecewise polynomial, lookup table, join,
raw xnp) is no longer silently trusted: the author must mark it
verify_units=False, so every un-verified body is an explicit, greppable choice.
Drop the forgotten-per-capita-scaling caveat (it follows naturally from counts
being dimensionless) and the redundant verify_units bullet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace the terse branch-coverage paragraph with the underlying logic: run the
body with units in place of numbers, read the unit off the return, and re-run
to steer every reachable branch (path explorer). A small branchy betrag_m
example shows the three reachable paths and why the count is reachable-paths,
not 2^n.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Fold repeated explanations (build-time-only, agnostic/concrete tokens,
verify_units opt-out, counting-dimensionless) to a single home each;
shorten "Usage and Impact" to a summary that links into the reference
sections; add a period-source matrix and a Layer-1/Layer-2 table; note
that a boundary tag built from an unknown token is rejected. No content
removed; ~5500 -> ~4600 words.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Align the GEP's terminology with the ParamMappingObject class: the
function-like parameter section/heading/table row now read 'mapping
parameter(s)'. Mirrors the ttsim rename of the supporting identifiers
(PARAM_MAPPING_OBJECT_TYPES, _resolve_param_mapping_object_units, …).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

State that a name suffix means a value time-converts and reference_period
means it does not — single values (columns, functions, scalar params) take
the suffix, structured values (dicts, schedules, lookup tables) take
reference_period. Replaces the harder-to-explain "wherever a name can carry
a suffix" framing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add HEADCOUNT to both token tables, extend the head-count section to cover
declaring a count (parameter, hand-written function, or input) — resolving to the
same [person]/[level] a COUNT mints, so a declaration and an aggregation compose
without an opt-out — and note that the individual reference level is allowed
(a per-person count is [person]/[person] = dimensionless).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Note that a hand-written aggregation's declared token is checked against the unit
it derives (physical kind only; period and grouping level are framework-derived),
so a SUM over a boolean declared DIMENSIONLESS rather than HEADCOUNT is rejected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…s fail

Add an Alternatives subsection rejecting grouping levels on dimensionless
(intensive) quantities, with two concrete failures: a different-level share
derives an uninterpretable [hh]/[fam] residual, and gating via `where`/`and`
forces a predicate's level to either evaporate (inert, catches nothing) or
multiply (rejects correct cross-level conjunctions). The dimension algebra has
a product, never the meet a per-person result needs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- C1: "if at all" -> "if noticed at all" in the dimensional-safety motivation
- C6: gloss the bare "GEP-9 canonicalisation boundary" checks-table cell
- C7: split the dense Layer-2 boundary sentence into rule -> caveat -> payoff
- E1: add a concrete inline-constant -> YAML-parameter before/after in Literals
- H1: rewrite Implementation to the live ttsim PR stack #138-#141; keep
  gettsim #1191/#1192 as issues (rollout PRs not yet open)

(--no-verify: the ty numpy hook fails project-wide because .pixi/envs/py314
is not installed; unrelated to this markdown-only change. ty-jax + mdformat pass.)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Describe how a parameter's unit is resolved across dated entries: forward-fill
from the most recent earlier `unit:` (top-level as the seed), a restatement
being a new seed from its date onward. Spell the rules that ship in ttsim —
backward-only resolution with a missing first declaration still flagged, a
restatement replacing the previous declaration wholesale (every leaf of a
mapping), and `updates_previous` decoupled from unit restatement with the
old-currency-magnitude sharp edge called out as the author's responsibility.

No top-level unit:; the first dated entry spells DM, the changeover spells EUR
once, later entries inherit. Reads as 'set DM once, EUR once' without an
asymmetric top-level seed.

Reorder into Abstract → Motivation → Units as guards → vocabulary
(with all special dimensions folded in) → declaring units →
currency → I/O trees → checks → backward compat → alternatives.
Drop the glossary; merge the duplicated extensive/intensive and
index-vs-unit material into the sections that enforce it; collapse
Alternatives from ten subsections to six; trim the dry-run, currency
forward-fill, and path-explorer prose. Fix the stale four-PR
implementation stack (#139/#140 collapsed into #138) and remove the
undefined T8 label and picturesque wording. ~1016 → 942 lines.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Lead with the idea that quantities have kinds, correctness means
respecting them, and a unit records the kind so the check is
mechanical — tying back to problems 1-2. Drop the premature
levels/calendar/booleans taxonomy (each is defined in the vocabulary);
keep one sentence on why a GETTSIM unit is broader than a physical
dimension. End on automatic conversion (problems 3-4).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Frame grouping levels vs measuring units as two axes, and explain why a
cross-level division result is overridden to DIMENSIONLESS: the override
drops only the level claim (physical content still checked) and fires only
for a non-person numerator level. Restore the cross-level-shares anchor.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add a concrete example to the trees section showing every leaf as a
`UnitAnnotatedColumn(values=, unit=Unit....)` in and out, and describe the
concrete-currency and spelled-level rules.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Rework 'which quantities carry a level' around one rule: a quantity carries a
group level iff it is a property of the group as a whole; a property of a
person carries none. This decouples the unit level from the name suffix (a
spelled group level must not contradict the suffix, but may be omitted at any
suffix), lets intensive group properties carry a level (a MIN-of-age is
MONTHS/[fg]), and lets calendar points carry one too (baujahr_immobilie_hh is
CALENDAR_YEAR/[hh]) — a grouping level is a pure index, not a scaling of the
affine point.

Aggregations: SUM/MIN/MAX take the target level for any base; MEAN is per-head
and stays at the individual level. Add the running-vs-cyclic note distinguishing
CALENDAR_MONTH from a dimensionless month-of-year.

Remove the 'two axes / cross-level share' override: a terminal [hh]/[bg] unit
never occurs in GETTSIM (every cross-level residue is load-bearing and cancels
inside a re-leveling multiply), so a genuine one now takes an explicit
verify_units=False rather than a silent DIMENSIONLESS coercion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The ownership model (grouping level tracks group- vs person-ownership)
left four spots still phrased against the name suffix: the unit-annotated
input tree rules, the Layer-2 table cell and boundary paragraph, and the
dry-run level-mismatch bullet. Also sharpen the mandatory-units sentence:
the decorators take unit= as a required argument; UNSET_UNIT and the
build-time check cover parameter YAMLs and hand-written aggregations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… rules

The dry-run's Layer-1 section never mentioned that column-level
(not_required) bodies are checked at full parity via the xnp stand-in,
nor that piecewise_polynomial / look_up / join calls are screened
against the schedule's declared axes. Add both, plus a consolidated
'When to opt out' subsection covering the cases that arise in GETTSIM:
structured parameter values, converter-built schedules, and
policy-mandated cross-level arithmetic. Also drop the stale
'fails to spell its level' error from the malformed-declarations
bullet — under the ownership model an omitted level is a valid
person-property declaration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… fixes

- Weave the expression-level cast through the opt-out, cross-level,
  calendar, and literals sections; drop the no-level-inference exemption.
- Make the lenient rules strict: level match by exact exponent signature,
  bare non-zero literals rejected in +/-/where and as returns (only 0 inline).
- State the implied-person-leaf rule per base; an area denominator
  suppresses the leaf (a rent cap is a price, owned by nobody).
- Edges are checked through the bodies (arguments enter at the producer's
  resolved unit), not by a separate consumer-side pass.
- Align the comparison rules, justify MEAN via the sum-over-count algebra,
  make calendar granularities separate axes with the cast as the converter.
- Add a worked error example; use GETTSIM grouping levels (fg) throughout;
  gloss METTSIM; move the ownership section up; drop the redundant
  Units-as-guards section; fix typos.

Committed with --no-verify: the subrepo ty hook needs a missing .pixi env;
mdformat run manually and clean (docs-only change).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…pluck

Documents the three require_converter declaration shapes (single token,
per-leaf mapping, per-axis units) and replaces the blanket structured-value
opt-out with the cast-at-the-pluck pattern: builders declare unit=UNSET_UNIT,
consumers state each plucked number's unit with cast_unit, and
verify_units=False remains the fallback.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…tten in

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- Aggregation table: a SUM over a boolean source mints a head count
  ([person]/[target]), exactly like COUNT.
- Calendar algebra: same-axis points order to a boolean; a point ordered
  against anything else is an error (orderings get no delegate-to-pint
  dispensation — nothing would catch the mix later).
- Framework date nodes: policy_month/policy_day carry a month-of-year /
  day-of-month — cyclic ordinals, hence DIMENSIONLESS; only the year nodes
  are calendar points.
- The failure example shows the implemented message: resolved units, the
  branch named in the body's own terms, and whether the other branch
  combinations match.
- Currency: registered currencies form families (one per package's base);
  conversion only within a family; the run-currency default follows the
  family the policy parameters are denominated in.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The require_converter axes become a checked promise (schedule return
annotation, unit=UNSET_UNIT, exactly one axes blob per converter), and in
return consumers' schedule calls screen with no cast at the call. The
structured-values section is rewritten around Annotated dataclass fields:
units stated once at the structure, consumer bodies plain policy logic,
YAML-vs-annotation drift checked on name-matched leaves, casts demoted to
the fallback for what annotations cannot cover. Alternatives records the
casts-only revision and the annotations-as-single-source design (rejected
for now: converters would compute on unconverted numbers, uncheckably).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- Fix the internal contradictions: concrete currency is not param-YAML-only; a
  policy function's level is read off its declaration, not the name suffix; the
  one-spelling-per-unit map is one-way; Motivation #4 no longer implies the time
  converters go away.
- Sync with the implementation: the run currency defaults to the registry base
  (never inferred from the policy objects); aggregations may opt out with
  `verify_units=False`; the time converters are modelled by the dry-run; add the
  `agg_by_p_id` / `group_creation_function` treatment; link the migration PR.
- Trim the two densest paragraphs into bullets and shrink the redundant
  Alternatives entry, keeping the didactic tables and lists intact.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…dary-only conversion

Rewrite the currency sections: the computation runs in the policy date's
statutory currency (a required dated mapping registered at import), parameters
keep their statutory values (guarded at build), and conversion happens only at
the column boundary via the renamed data_currency knob. Record why parameters
are never converted, worked through the Wohngeld Basisformel. Drop the
currency-family framing, the rounding-spec restatement, and the leaf-scaling
language; add the working-hours denominator to the grammar.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…dary wording

Per the review of ttsim #144: a policy function's code does not care
which currency it runs in, but its values are always denominated in the
statutory currency of the policy date — only parameters and rounding
specs pin down concrete currencies. Describe the conversion of input
data and results in plain language instead of the "column boundary"
metaphor, mention the declaration minted for data supplied at a derived
name, and the warning when the statutory currency differs from the
default data currency.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

for more information, see https://pre-commit.ci