#570 Measures: typed quantities on moments and durations, totalled in every summary
–
- github
- github/openchronology/timeline-app
- github/openchronology/timeline-app#570
- issue
- state:open
Moments and durations carry **measures**: named, typed quantities that add up. Every summary then keeps the **total** of each measure beneath it, beside the count it keeps today. For example, a moment for an invoice carries `cost: 1250` (cents), and a cluster of 40 invoices shows its count and its total, `$1,234.56`. ## Types: mpz and mpq only The summary trees keep each subtree's total and rebuild it from its children after inserts and rotations. A rotation regroups a sum, `(a+b)+c` becomes `a+(b+c)`, so addition has to be a **monoid**: associative, with zero for an empty subtree. Commutativity isn't needed, because order by time is fixed. | Type | Values | Why | | --- | --- | --- | | `mpz` | unbounded integers | exact and associative | | `mpq` | unbounded rationals | exact and associative | Left out: - **f32 and f64:** not associative. Totals would depend on the tree's rotation history and differ between engines. - **Machine integers:** checked or saturating overflow depends on grouping. Wrapping is associative, but it's useless on an unbounded timeline. Every engine already has exact rational addition (pgmp's `mpq`, GMP in `sqlite-rational`, `Q` in the browser), so totals are stored as `mpq`. An `mpz` total is just an integral `mpq`. ## Declaring measures A timeline declares its measures in its settings, beside its presentation: ```json "measures": { "cost": { "type": "mpz", "presentation": { "mode": "fixed", "scale": "1/100", "decimals": 2, "prefix": "$" } }, "hours": { "type": "mpq", "presentation": { "mode": "decimal", "significantDigits": 4, "unit": "h" } } } ``` - **Names:** like metadata keys, from a limited set of characters, up to a few dozen per timeline. - **Values:** a moment or duration gives values under `metadata.measures`, as canonical text: `{"cost": "1250"}` for an `mpz`, `{"hours": "3/2"}` for an `mpq`. **No entry is zero.** Values are exact. An `mpz` value must be an integer. - **Validation:** in the core (`validateDocument`), the server and the native store, like times, with size limits like a time's (digits, and the server's own limit). - **Changes to a declaration:** - **Renaming:** rewrites the values in place. - **Widening `mpz` to `mpq`:** always allowed. - **Narrowing `mpq` to `mpz`:** only when every value is an integer. - **Removing a measure:** removes its values (or leaves them as plain metadata, to be decided). - **Index:** each of these rebuilds that measure's totals. - **Display settings save like the time display's:** in place, as a settings change. ## Presentation and parsing, per measure This is the analogue of the [time presentation](docs/time-presentation.md) system. Each measure has its own **printer and parser**: how a value or a total is shown, and how what someone types becomes a stored value. They're exact, and never pass through binary floating point. | Mode | Stored | Shown and typed | Example | | --- | --- | --- | --- | | Exact | `mpz`/`mpq` | the fraction | `3/2` | | Fixed decimals | `mpz` × scale | a fixed number of decimals, with a prefix or suffix | `cost = 123456`, scale `1/100` → `$1,234.56` | | Decimal / scientific | `mpq` | significant digits, like numeric times | `1.5 h` | | SI prefixes | `mpq` | `1.5 kWh` | | | Units | either | `displayed = stored × scale`, label | hours stored as seconds | | Custom | either | a plugin's printer and parser, as custom time code is | | - **Fixed decimals:** the currency case. `$12.34` parses to `1234` with scale `1/100`. `$12.345` is refused rather than rounded, and the parser says why. - **Totals:** use the same printer as values, so a cluster's total reads as money. - **Unchanged text keeps its exact value:** as with times, editing a label that was rounded for display doesn't change what's stored. - **Context:** the printer gets a purpose (value, total, input, tooltip, axis), like `PresentationContext`, so totals can be abbreviated (`$1.2M`) where space is short. - **Where it applies:** the moment and duratio……
Related
- #122 journald & other import formats severity colorization
- #157 Plugins validate their own metadata; the server compiles scripts only in a sandbox
- #289 background chart plugin
- #434 Background chart: a chart per category (such as log severity) beside the total
- #538 Work-item sources: aggregate GitHub assignments, then Planner and kanban boards
- #572 Measures 1: declarations, values, validation and formats
- #573 Measures 2: presentation and parsing per measure, with editor fields
- #574 Measures 3: totals in the summary trees (browser, PostgreSQL, SQLite)
- #575 Measures 4: totals in overviews, cluster labels, the plugin API and the background chart
- #576 Measures 5: durations' measures counted where they start
- #577 Measures: declarations, exact values, validation and formats (#572)
- #578 Measures: presentation and parsing per measure, and editor fields (#573)
- #579 Measures: totals in the editor's index and its overview groups (#574)
- #580 Measures: totals in the PostgreSQL moment tree and its overviews (#574)
- #581 Measures: totals in the desktop file's SQLite index (#574)
- #582 Measures: totals on summaries, values on hover cards, and plugins (#575)
- #583 Measures: durations count where they start (#576)
- #584 Keep every setting in time-display saves and after following a save
- #585 Measures: an official library of formats by type; no plugin formats
- #586 Measures: comparisons keep totals per timeline, never added across them
- #587 Measures: plugin scripts and derived metadata read a summary's totals
- #588 Measures: the desktop store validates declarations and values
- #589 The desktop store validates measures and their values (#588)
- #590 Measures: an official library of formats by type (#585)
- #591 Measures: comparisons keep totals per timeline, never added across them (#586)
- #592 Measures: plugin scripts and derived metadata read a summary's totals (#587)
- #595 Measures: running balances from changes, and one change index per timeline
- Measures: declarations, exact values, validation and formats (#572)