@kumbatio/energy-system 1.0.1 → 2.0.5

package/CHANGELOG.md

@@ -7,16 +7,59 @@ and from `1.0.0` this project adheres to [Semantic Versioning](https://semver.or
 
 For this package, semver covers more than type signatures. **A shipped strategy
 table's values are API**: changing what `notificationStrategy` returns at level
-50 changes how every consumer behaves, so it is a major-version change — and a
+50 changes how every consumer behaves, so it is a major-version change - and a
 change to [SPEC.md](./SPEC.md), not only to this library. The same is true of the
 reconciliation rule, which two implementations must agree on to share state at
 all. Prose returned by `describe()` is not covered; wording is a product decision.
 
 ## [Unreleased]
 
-Corrections to `1.0.0`. No type signature changed, but two of these change
-runtime behavior and one narrows an install range — see the note at the top of
-this file on why that is more than a patch for this package.
+## [2.0.5] - 2026-08-21
+
+### Fixed
+
+- `api-surface.json` and `conformance.json` shipped in the package now carry the version of the release they belong to. Through 2.0.4 both files were published with the previous release's version stamp, so consumers reading the version from either artifact — or checking it against `package.json` — saw a mismatch. ([ec77e2d](https://github.com/kumbatio/energy-system/commit/ec77e2d), [a0f2dcb](https://github.com/kumbatio/energy-system/commit/a0f2dcb))
+
+## [2.0.4] - 2026-08-21
+
+### Miscellaneous Chores
+
+- update version to 2.0.3 in api-surface.json and conformance.json ([3a21713](https://github.com/kumbatio/energy-system/commit/3a21713))
+
+## [2.0.3] - 2026-08-21
+
+### Miscellaneous Chores
+
+- regenerate api-surface.json and conformance.json ([427d02d](https://github.com/kumbatio/energy-system/commit/427d02d))
+
+## [2.0.2] - 2026-08-21
+
+### Bug Fixes
+
+- update @entro314labs/release-kit to version 2.9.0 and standardize string quotes in CITATION.cff ([ea3d9c1](https://github.com/kumbatio/energy-system/commit/ea3d9c1))
+
+## [2.0.1] - 2026-08-21
+
+### Changed
+
+- **The Rest level description now opens with "Recovery." instead of
+  "Depleted."** Level-description prose is product copy, not semver-covered API
+  (see the note at the top of this file). "Depleted" implies damage, which
+  conflicts with the Neutral State Language principle the level copy is
+  supposed to embody: describe what the person can do at a level, not what they
+  cannot. [SPEC.md](./SPEC.md) §3.1 and `conformance.json` updated to match.
+
+## [2.0.0]
+
+Corrections to `1.0.0`. No type signature changed, which is exactly why this is
+a major: two of these change runtime behavior and one narrows an install range,
+and for this package behavior is API - see the note at the top of this file.
+
+Upgrading from `1.x`: the breaks are `react`/`@types/react` below 19.2 (which
+never worked with the React entry point), persisted or exchanged states carrying
+properties outside the published schema (previously trimmed in silence, now
+rejected), and any code depending on a batched notification being delivered
+after suppression started or after energy fell below its threshold.
 
 ### Fixed
 
@@ -34,7 +77,7 @@ this file on why that is more than a patch for this package.
   `createEnergyState()` accepted fractional timestamps, which
   [spec/energy-state.schema.json](./spec/energy-state.schema.json) does not
   allow, and persisted state carrying unknown properties was silently trimmed
-  to fit rather than rejected — so two implementations could exchange a state
+  to fit rather than rejected - so two implementations could exchange a state
   and disagree about what they had exchanged. Persistence loads, cross-context
   observations and `memoryPersistence` now share one strict boundary parser.
 - **A configured `originId` no longer corrupts the unproduced sentinel.**
@@ -46,7 +89,7 @@ this file on why that is more than a patch for this package.
   state the engine actually produces.
 - **`api-surface.json` includes `EnergyEngine.resolve()`.** The declaration
   parser did not recognise generic members, so a public method was missing from
-  the frozen surface — and a method absent from the freeze is a method nobody
+  the frozen surface - and a method absent from the freeze is a method nobody
   notices removing.
 
 ### Changed
@@ -57,13 +100,13 @@ this file on why that is more than a patch for this package.
   19.0 and 19.1.
 - **Generated artifacts are checked, not regenerated, during validation.**
   `pnpm test` used to run the full build first, so the drift guard compared
-  `conformance.json` against a copy it had just written — it could not fail,
+  `conformance.json` against a copy it had just written - it could not fail,
   whatever was committed. Generation now belongs to `pnpm run build`; both
   generators take `--check`, and both artifacts are verified by the suite.
 
 ### Added
 
-- **[spec/conformance.schema.json](./spec/conformance.schema.json)** — the
+- **[spec/conformance.schema.json](./spec/conformance.schema.json)** - the
   schema `conformance.json` has always pointed at via `$schema` and which did
   not exist. The generator now validates its own output against it before
   emitting, and it is exported from the package so the relative reference
@@ -79,20 +122,20 @@ The API is frozen. Everything below documents what that commitment now covers.
 
 ### Added
 
-- **[SPEC.md](./SPEC.md)** — the model specified independently of this
+- **[SPEC.md](./SPEC.md)** - the model specified independently of this
   implementation: levels, energy state, reconciliation, the strategy contract,
   autonomy, inbound demand, the runtime invariants, and the accessibility
   requirements. Language-independent and RFC 2119-worded, so an implementation in
   another language is an implementation of the same model rather than a port of
   this one.
-- **[spec/energy-state.schema.json](./spec/energy-state.schema.json)** — the
+- **[spec/energy-state.schema.json](./spec/energy-state.schema.json)** - the
   interchange format. Sharing one person's energy state across processes or
   languages is a wire-format problem, and this is the wire format.
-- **[conformance.json](./conformance.json)** — 252 vectors plus every strategy
+- **[conformance.json](./conformance.json)** - 252 vectors plus every strategy
   table, generated from the built library on each build and shipped in the
   package. An implementation passes by loading and replaying them; a stale file
   fails this package's own build.
-- `isPreferredEnergyState(candidate, current)` — the reconciliation rule, which
+- `isPreferredEnergyState(candidate, current)` - the reconciliation rule, which
   was internal to the engine. It is the hardest part of the model to reimplement
   correctly, so it is now readable, testable, and covered by vectors on its own.
 - Accessibility handling in the reference stylesheet for
@@ -101,7 +144,7 @@ The API is frozen. Everything below documents what that commitment now covers.
   properties inline, and a preference the person set must outrank a value the
   program computed.
 - Coverage across every one of the 20 level transitions, in both directions, and
-  across strategy composition — including the model's directional invariants
+  across strategy composition - including the model's directional invariants
   (protection never decreases and automation never gains discretion as capacity
   falls), which a future edit to one table would otherwise break silently.
 
@@ -118,13 +161,13 @@ The API is frozen. Everything below documents what that commitment now covers.
 
 ### Added
 
-- `autonomyStrategy` / `AutonomyConfig` — what automation may do unattended:
+- `autonomyStrategy` / `AutonomyConfig` - what automation may do unattended:
   confidence threshold, whether wording may be composed, and how many steps may
   chain. The mirror of interaction forgiveness, which protects against the
   _user's_ mistakes at low energy where this protects against the _agent's_.
   What narrows as energy falls is discretion, not action: at Rest the threshold
   is 1, admitting only certainty, and a single templated step is still allowed.
-- `demandAdmissionStrategy` and the pure `resolveDemandOutcome` — an
+- `demandAdmissionStrategy` and the pure `resolveDemandOutcome` - an
   energy-resolved policy for arrivals that ask something of the person: reach
   them now, acknowledge and queue, or queue silently. Originator tiers, the
   exempt-tier invariant, and escalation to silence when a classification is not
@@ -141,7 +184,7 @@ The API is frozen. Everything below documents what that commitment now covers.
 ## [0.4.0]
 
 Patterns studied in a field ADHD app and reimplemented as first-class, tested
-primitives — including guarantees against the two failure modes observed in the
+primitives - including guarantees against the two failure modes observed in the
 wild: suppressed reminders destroyed instead of deferred, and focus suppression
 that never auto-expired.
 
@@ -170,3 +213,16 @@ framework-agnostic engine with strategy resolution, the first three built-in
 strategies, the DOM adapter, the React provider and hooks, persistence adapters
 with external observation, deterministic clocks, derived metrics, and legacy
 level compatibility mapping.
+
+[Unreleased]: https://github.com/kumbatio/energy-system/compare/v2.0.5...HEAD
+[2.0.5]: https://github.com/kumbatio/energy-system/compare/v2.0.4...v2.0.5
+[2.0.4]: https://github.com/kumbatio/energy-system/compare/v2.0.3...v2.0.4
+[2.0.3]: https://github.com/kumbatio/energy-system/compare/v2.0.2...v2.0.3
+[2.0.2]: https://github.com/kumbatio/energy-system/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/kumbatio/energy-system/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/kumbatio/energy-system/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/kumbatio/energy-system/compare/v0.6.0...v1.0.0
+[0.6.0]: https://github.com/kumbatio/energy-system/compare/v0.5.4...v0.6.0
+[0.5.4]: https://github.com/kumbatio/energy-system/compare/v0.4.0...v0.5.4
+[0.4.0]: https://github.com/kumbatio/energy-system/compare/v0.1.0...v0.4.0
+[0.1.0]: https://github.com/kumbatio/energy-system/releases/tag/v0.1.0

package/README.md

@@ -76,7 +76,7 @@ This library gives applications a structured way to adapt to energy state instea
   - Energy-aware deferral ordering
   - Autonomy (how much automation may do unattended)
 - **Inbound demand admission**: an energy-resolved policy for arrivals that ask
-  something of the user — reach them now, acknowledge and queue, or queue
+  something of the user - reach them now, acknowledge and queue, or queue
   silently (`demandAdmissionStrategy`, `resolveDemandOutcome`)
 - **Presence annotation**: declare which energy levels a component/view belongs
   to (`defineEnergyPresence`, `presenceAtOrAbove`, `<EnergyGate>`, `data-energy-min`)
@@ -161,8 +161,8 @@ export function App() {
 ## Presence annotation (which energy states does this element belong to?)
 
 Every component/view can declare the energy levels it participates in. The
-declaration is a plain typed object — one presence (`'visible' | 'muted' |
-'hidden'`) per level — so the same annotation drives React, the engine, or
+declaration is a plain typed object - one presence (`'visible' | 'muted' |
+'hidden'`) per level - so the same annotation drives React, the engine, or
 plain CSS.
 
 ```ts
@@ -218,7 +218,7 @@ capacity dipped. `<EnergyGate>` hides through React 19.2's `<Activity>`:
 component state, DOM and scroll position survive, effects are torn down while
 hidden and re-run on reveal, and hidden content is not server-rendered.
 
-Opt out for subtrees whose cost is worth reclaiming — media, canvases, live
+Opt out for subtrees whose cost is worth reclaiming - media, canvases, live
 connections:
 
 ```tsx
@@ -227,12 +227,12 @@ connections:
 </EnergyGate>
 ```
 
-CSS-only path — annotate elements with the range they belong to and the
+CSS-only path - annotate elements with the range they belong to and the
 stylesheet handles hiding as `data-energy-level` changes:
 
 ```html
-<div data-energy-min="75">AI chat — needs 75+ energy</div>
-<div data-energy-max="25">Recovery hint — low energy only</div>
+<div data-energy-min="75">AI chat - needs 75+ energy</div>
+<div data-energy-max="25">Recovery hint - low energy only</div>
 ```
 
 ## Focus sessions and the notification gate
@@ -284,7 +284,7 @@ Two invariants are guaranteed by construction:
 
 Deferring is an energy statement. Presets are pure `(now) => Date` functions;
 `deferralStrategy` orders them by level so the one-tap default matches
-capacity — at low energy the default is "tomorrow morning", not "in 1 hour".
+capacity - at low energy the default is "tomorrow morning", not "in 1 hour".
 
 ```ts
 import {
@@ -307,13 +307,13 @@ attention or action: an email, a document comment, a review request, a task
 assignment, a collaboration invite.
 
 Every triage system in general use is organised around properties of the
-_message_ — who sent it, how urgent it claims to be, what category it fits.
+_message_ - who sent it, how urgent it claims to be, what category it fits.
 None is organised around the state of the _recipient_, which is the thing that
 actually decides whether an arrival is a small task or a crushing weight. This
 is that variable, applied to the queue.
 
 `demandAdmissionStrategy` resolves the policy; `resolveDemandOutcome` applies
-it. Both are pure. The library performs no effects here — acknowledging an
+it. Both are pure. The library performs no effects here - acknowledging an
 originator means sending mail, posting a comment, or updating a status chip
 depending on the app, and those are irreversible in ways an in-process runtime
 cannot make transactional. The orchestration, with its ordering, retries, and
@@ -343,7 +343,7 @@ switch (outcome.admission) {
   case 'acknowledge':
     // One act, never two. An acknowledgment without a capture is a promise
     // nobody kept; a capture without an acknowledgment leaves the originator in
-    // silence. Capture first — it is the reversible half.
+    // silence. Capture first - it is the reversible half.
     await tasks.capture(message, engine.resolve(deferralStrategy).defaultPresetId)
     return replies.acknowledge(message, outcome.acknowledgment)
   case 'silent':
@@ -356,14 +356,14 @@ Two rules are worth stating outright, because each blocks a specific failure:
 1. **The exempt tier is never handled by machine.** At every level, an exempt
    originator is admitted live. This is also what defuses the gaming risk: an
    originator who learns an acknowledgment means "deprioritised" and escalates
-   elsewhere only succeeds if their escalation is one the user cannot ignore —
+   elsewhere only succeeds if their escalation is one the user cannot ignore -
    which is what makes them exempt.
 2. **Acknowledgments report state, never intent.** "Received and queued,
    current response horizon early next week" is a fact. "I'll get back to you
    soon" is a promise the user's Tuesday self has to keep. The horizon comes
    from `deferralStrategy`, so the queue and the acknowledgment cannot disagree.
 
-Disclosure is the app's job in the app's own medium — an `Auto-Submitted:
+Disclosure is the app's job in the app's own medium - an `Auto-Submitted:
 auto-replied` header, an "auto-queued" badge, a system-attributed status. An
 automated action toward a third party must be identifiable as automated.
 
@@ -380,8 +380,8 @@ const { confidenceThreshold, allowGeneratedContent, maxUnattendedSteps } =
 ```
 
 What narrows as energy falls is _discretion_, not action. At rest the
-confidence threshold is `1`, which admits only certainty — rule-based actions,
-never a judgment call — and `maxUnattendedSteps` is `1`. Automation may still
+confidence threshold is `1`, which admits only certainty - rule-based actions,
+never a judgment call - and `maxUnattendedSteps` is `1`. Automation may still
 take a single, certain, template-only step, which is exactly the shape of an
 out-of-office reply. It may not chain steps or improvise wording. The system
 acts for the user precisely when they are least able to supervise it, so the
@@ -421,9 +421,9 @@ Then use classes like:
 
 And presence attributes:
 
-- `data-energy-min="75"` — element hides whenever the current level is below 75
-- `data-energy-max="25"` — element hides whenever the current level is above 25
-- `data-energy-presence="muted" | "hidden"` — hooks for JS-resolved presence
+- `data-energy-min="75"` - element hides whenever the current level is below 75
+- `data-energy-max="25"` - element hides whenever the current level is above 25
+- `data-energy-presence="muted" | "hidden"` - hooks for JS-resolved presence
   (`--energy-muted-opacity` controls the muted treatment)
 
 The stylesheet honours `prefers-reduced-motion` for its own transitions; apps
@@ -568,14 +568,14 @@ default state, and rejects rather than overwriting unread storage if that hydrat
 
 The model is specified independently of this implementation.
 
-- **[SPEC.md](./SPEC.md)** — the normative model: levels, state, reconciliation, the strategy
+- **[SPEC.md](./SPEC.md)** - the normative model: levels, state, reconciliation, the strategy
   contract, autonomy, inbound demand, the runtime invariants, and the accessibility requirements.
   Language-independent, RFC 2119 wording.
-- **[spec/energy-state.schema.json](./spec/energy-state.schema.json)** — the interchange format, so
+- **[spec/energy-state.schema.json](./spec/energy-state.schema.json)** - the interchange format, so
   two processes (or two languages) can share one person's energy state.
-- **[conformance.json](./conformance.json)** — every table and every decision above, as vectors.
+- **[conformance.json](./conformance.json)** - every table and every decision above, as vectors.
   Ships in the package.
-- **[spec/conformance.schema.json](./spec/conformance.schema.json)** — the shape of that vector
+- **[spec/conformance.schema.json](./spec/conformance.schema.json)** - the shape of that vector
   file, so a port can tell a file it can trust from one whose structure moved under it. Ships too,
   and the generator validates its own output against it.
 
@@ -588,20 +588,20 @@ package's own `test/conformance.test.ts` does exactly that and is a reasonable m
 
 The file is generated from the built library, so the vectors cannot drift from the behavior they
 describe. `pnpm run build` regenerates it; `pnpm test` recomputes it and fails if what is committed
-differs, without rewriting anything. The two are deliberately separate — a check that regenerates
+differs, without rewriting anything. The two are deliberately separate - a check that regenerates
 first is comparing a file to itself.
 
 Vectors cover the pure surface: tables, and functions of their arguments alone. The stateful
-guarantees — defer-never-drop, session auto-expiry, persistence ordering — are normative in SPEC.md
+guarantees - defer-never-drop, session auto-expiry, persistence ordering - are normative in SPEC.md
 and checked by this package's suite, because no vector can express _and it must never drop one_.
 
 ## Stability
 
-`1.0.0` is an API freeze. From here the package follows semver strictly, and for this package that
-means more than the type signatures:
+The API has been frozen since `1.0.0`. The package follows semver strictly, and for this package
+that means more than the type signatures:
 
 - **A shipped strategy table's values are API.** Changing what `notificationStrategy` returns at
-  level 50 changes how every consumer behaves, so it is a major-version change — and a change to
+  level 50 changes how every consumer behaves, so it is a major-version change - and a change to
   [SPEC.md](./SPEC.md), not just to this library.
 - **The reconciliation rule is API.** Two implementations that disagree about it cannot share state.
 - **The conformance vectors are the contract in machine-readable form.** Within a major version,
@@ -612,7 +612,7 @@ means more than the type signatures:
 ## Development
 
 ```bash
-pnpm run validate   # format, lint, types, tests, packaging — what CI runs
+pnpm run validate   # format, lint, types, tests, packaging - what CI runs
 ```
 
 Individually:
@@ -627,7 +627,7 @@ pnpm run pack:dry-run
 
 `build` is the only thing that writes `api-surface.json` and `conformance.json`.
 If a change to the library moves either, `pnpm test` fails and tells you to run
-`pnpm run build` and commit the result — that is the intended loop, not a
+`pnpm run build` and commit the result - that is the intended loop, not a
 warning to work around.
 
 ## Notes
@@ -637,20 +637,36 @@ adapters (e.g., SQLite-backed desktop stores) should live in consuming apps.
 
 ## Who uses this
 
-- **[Anasa](https://anasa.md)** — Kumbatio's local-first writing and thinking workspace, in public alpha. Runs its entire adaptive shell on the engine: custom settings-backed persistence, energy-gated AI surfaces, notification filtering, and task-complexity guidance.
-- **[Meltemi](https://meltemi.app)** — an email client in private beta from [entro314 labs](https://github.com/entro314-labs) (the studio behind Kumbatio), built outside the Kumbatio product line. Uses the notification gate (defer, never drop), focus sessions, deferral ordering, interaction forgiveness, and demand admission — integrated without the React adapter. Its demand binding is the reference one: originator tiers come from its VIP list, obligation is classified from RFC 3834 header evidence and its own sender lanes, acknowledgments go out as `Auto-Submitted: auto-replied` auto-replies, and the capture is a snooze to the horizon `deferralStrategy` picked.
-- **[kumbat.io](https://kumbat.io)** — the site itself runs on this model; change the energy level there and watch the interface adapt.
+- **[Anasa](https://anasa.md)** - Kumbatio's local-first writing and thinking workspace, in public alpha. Runs its entire adaptive shell on the engine: custom settings-backed persistence, energy-gated AI surfaces, notification filtering, and task-complexity guidance.
+- **[Meltemi](https://meltemi.app)** - an email client in private beta from [entro314 labs](https://github.com/entro314-labs) (the studio behind Kumbatio), built outside the Kumbatio product line. Uses the notification gate (defer, never drop), focus sessions, deferral ordering, interaction forgiveness, and demand admission - integrated without the React adapter. Its demand binding is the reference one: originator tiers come from its VIP list, obligation is classified from RFC 3834 header evidence and its own sender lanes, acknowledgments go out as `Auto-Submitted: auto-replied` auto-replies, and the capture is a snooze to the horizon `deferralStrategy` picked.
+- **[kumbat.io](https://kumbat.io)** - the site itself runs on this model; change the energy level there and watch the interface adapt.
 
 The integration patterns these apps proved out are documented in the [Production Patterns guide](https://docs.kumbat.io/docs/energy-system/guides/production-patterns). If you ship something with `energy-system`, tell us: [hello@kumbat.io](mailto:hello@kumbat.io).
 
 ## Kumbatio
 
-`energy-system` is the infrastructure layer of [Kumbatio](https://kumbat.io) — an ecosystem of open-source, neuroinclusive software built from lived experience with ADHD and depression. The position behind it, in one line: **energy ≠ time**, and software should adapt to real cognitive capacity instead of assuming a default brain.
+`energy-system` is the infrastructure layer of [Kumbatio](https://kumbat.io) - an ecosystem of open-source, neuroinclusive software built from lived experience with ADHD and depression. The position behind it, in one line: **energy ≠ time**, and software should adapt to real cognitive capacity instead of assuming a default brain.
 
-- The full argument: [kumbat.io/manifesto](https://kumbat.io/manifesto) — agree? [Sign it](https://kumbat.io/endorse)
+- The full argument: [kumbat.io/manifesto](https://kumbat.io/manifesto) - agree? [Sign it](https://kumbat.io/endorse)
 - Where this library is going: [ROADMAP.md](./ROADMAP.md)
 - How to help: [CONTRIBUTING.md](./CONTRIBUTING.md)
-- Live demo: [kumbat.io](https://kumbat.io) adapts its entire interface with this model — move the energy control and watch
+- Live demo: [kumbat.io](https://kumbat.io) adapts its entire interface with this model - move the energy control and watch
+
+## Research
+
+The thinking behind this library is documented in a five-paper preprint series,
+published on Zenodo under CC BY 4.0. Papers 1 and 4 below describe this library
+directly; the others give the evidence base, the self-report position, and the
+work-design framework. Badges link the concept DOI, which always resolves to
+the latest version.
+
+1. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21915159.svg)](https://doi.org/10.5281/zenodo.21915159) Energy as State, Not Time - the model this library implements
+2. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21915161.svg)](https://doi.org/10.5281/zenodo.21915161) The Myth of the Flat Workday - the cognitive-science evidence
+3. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21915163.svg)](https://doi.org/10.5281/zenodo.21915163) Self-Report Over Surveillance - why the state is declared, never inferred
+4. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21915165.svg)](https://doi.org/10.5281/zenodo.21915165) Capacity-Aware Software Design - the pattern language this library ships
+5. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21915167.svg)](https://doi.org/10.5281/zenodo.21915167) Energy > Time - the framework, from individuals to teams
+
+To cite the software itself, see [CITATION.cff](./CITATION.cff).
 
 ## License
 

package/SPEC.md

@@ -1,4 +1,4 @@
-# The Energy Model — Specification
+# The Energy Model - Specification
 
 **Version 1 · normative · language-independent**
 
@@ -6,7 +6,7 @@ This document specifies the energy model: what an energy state is, how two of
 them are ordered when they meet, and what each of the five levels means for the
 behaviors built on top. `@kumbatio/energy-system` is the reference
 implementation, not the definition. Anything that implements what is written
-here — in Swift, Kotlin, Rust, Python, Go, or another JavaScript library — is an
+here - in Swift, Kotlin, Rust, Python, Go, or another JavaScript library - is an
 implementation of the same model, and states produced by one may be read by
 another.
 
@@ -23,7 +23,7 @@ Key words follow RFC 2119: **MUST**, **MUST NOT**, **SHOULD**, **MAY**.
 ## 1. Why this exists as a spec at all
 
 The claim the model makes is not "here is a nice API". It is that **capacity is
-first-class application state** — as real as the current user or the current
+first-class application state** - as real as the current user or the current
 document, and as deserving of a stable representation.
 
 That claim only pays off if one person's energy state can be shared by
@@ -48,7 +48,7 @@ The model has exactly **five** levels, and they are discrete.
 | `75`  | `active` | Active | Good capacity. Focused execution, problem-solving.         |
 | `50`  | `steady` | Steady | Moderate capacity. Routine tasks, familiar work.           |
 | `25`  | `low`    | Low    | Limited capacity. Simple tasks, review, light work.        |
-| `0`   | `rest`   | Rest   | Depleted. Consumption only — reading, reflecting.          |
+| `0`   | `rest`   | Rest   | Recovery. Consumption only - reading, reflecting.          |
 
 An implementation **MUST** use exactly these five values and **MUST NOT** admit
 intermediate ones. This is a design commitment, not an arbitrary limit: a
@@ -56,8 +56,8 @@ continuous slider asks for precision nobody has about their own state, and it
 turns a one-second act into a judgement call at exactly the moment judgement is
 expensive. Five is also few enough to cycle through with one key.
 
-Each level carries a **cognitive profile** — `decisionCapacity`,
-`focusDuration`, `taskComplexity`, `interruptionTolerance` — enumerated in the
+Each level carries a **cognitive profile** - `decisionCapacity`,
+`focusDuration`, `taskComplexity`, `interruptionTolerance` - enumerated in the
 vectors under `levels`. Implementations **MUST** reproduce these values;
 consumers branch on them.
 
@@ -95,9 +95,9 @@ this with whatever their language offers.
 
 `source` is not decoration; §4 gives it authority.
 
-- `manual` — the person set it. **The default, and the trust anchor.**
-- `scheduled` — a rule the person configured applied it (a calendar, a time of day).
-- `inferred` — the system worked it out from behavior.
+- `manual` - the person set it. **The default, and the trust anchor.**
+- `scheduled` - a rule the person configured applied it (a calendar, a time of day).
+- `inferred` - the system worked it out from behavior.
 
 An implementation **MUST** support `manual`. Inference **MAY** be offered but
 **MUST** be opt-in, and a system that infers **SHOULD** present the result as a
@@ -125,7 +125,7 @@ some frameworks fail the build on outright.
 An implementation that accepts states from outside itself **SHOULD** reject any
 whose `timestamp` exceeds local time by more than a bounded skew budget. Without
 it, one context with a badly-set clock wins every comparison until real time
-catches up to its timestamp — which may be years.
+catches up to its timestamp - which may be years.
 
 The reference default is **5 minutes**. The budget **SHOULD** be configurable,
 including "accept anything finite" for controlled environments.
@@ -146,17 +146,17 @@ different values depending on timing, so two contexts disagree permanently.
 Given a `candidate` and a `current`, the candidate replaces the current if and
 only if the first differing key below favours it:
 
-1. **`timestamp`** — greater wins.
-2. **`revision`** — greater wins.
-3. **`source`** — `manual` (3) > `scheduled` (2) > `inferred` (1).
-4. **`origin`** — greater by lexicographic comparison of the string.
+1. **`timestamp`** - greater wins.
+2. **`revision`** - greater wins.
+3. **`source`** - `manual` (3) > `scheduled` (2) > `inferred` (1).
+4. **`origin`** - greater by lexicographic comparison of the string.
 
 If all four are equal, the states are equal: the candidate **MUST NOT** replace
 the current, and no change **MUST** be reported.
 
 Key 4 is arbitrary and deliberately so. When two producers write the same
 instant, the same revision, and the same class of source, there is no principled
-winner — and an arbitrary rule every context computes _identically_ beats a coin
+winner - and an arbitrary rule every context computes _identically_ beats a coin
 flip each context tosses separately. Convergence is the property that matters.
 
 An implementation **MUST** additionally treat a `level` difference as a
@@ -205,7 +205,7 @@ not every host has deferral or automation. Whatever it provides **MUST** match
 the vectors exactly.
 
 Implementations **MAY** ship additional strategies and **SHOULD** allow
-consumers to supply their own — the type is a contract, not a closed set.
+consumers to supply their own - the type is a contract, not a closed set.
 
 ### 5.1 Human-readable descriptions
 
@@ -242,8 +242,8 @@ come from fixed templates), and `maxUnattendedSteps` (how many automated steps
 may chain before control returns).
 
 The rule the numbers encode: **what narrows as energy falls is discretion, not
-action.** At Rest the threshold is `1`, admitting only certainty — rule-based
-decisions, never judgement calls — with one step and no composition. Automation
+action.** At Rest the threshold is `1`, admitting only certainty - rule-based
+decisions, never judgement calls - with one step and no composition. Automation
 **MAY** still take a single certain templated action there; an out-of-office
 reply is exactly that shape, and it is _safest_ at Rest precisely because it has
 stopped improvising.
@@ -261,7 +261,7 @@ attention or action: an email, a comment, a review request, an assignment, an
 invitation.
 
 This is where the model earns its keep. Every triage system in general use is
-organised around properties of the _message_ — who sent it, what it claims about
+organised around properties of the _message_ - who sent it, what it claims about
 its own urgency, what category it fits. None is organised around the state of
 the _recipient_, which is what actually decides whether an arrival is a small
 task or a crushing weight.
@@ -291,11 +291,11 @@ The decision is pure. Acting on it is not, and four rules bound what acting may
 look like. An implementation performing these effects **MUST** observe them.
 
 1. **Acknowledgment and capture are one act.** An acknowledgment without a
-   captured obligation is a promise nobody kept — strictly worse than silence,
+   captured obligation is a promise nobody kept - strictly worse than silence,
    because it converts ambient guilt into explicit written debt. A capture
    without an acknowledgment leaves the originator in silence, which is the
-   problem being solved. Where the two cannot be made atomic — and across a
-   network they cannot — the capture **MUST** be performed first, because it is
+   problem being solved. Where the two cannot be made atomic - and across a
+   network they cannot - the capture **MUST** be performed first, because it is
    the reversible half, and **MUST** be rolled back if the acknowledgment fails.
 2. **Acknowledgments state, never promise.** "Received and queued, current
    response horizon Thursday" is a fact. "I'll get back to you soon" is a
@@ -303,7 +303,7 @@ look like. An implementation performing these effects **MUST** observe them.
    NOT** emit commitments. The horizon **SHOULD** come from the deferral
    strategy, so the queue and the acknowledgment cannot disagree.
 3. **Automated action toward a third party MUST be disclosed as automated.** The
-   medium decides the mechanism — `Auto-Submitted: auto-replied` on email
+   medium decides the mechanism - `Auto-Submitted: auto-replied` on email
    (RFC 3834, which also prevents responder loops), a system-attributed badge in
    an app. Undisclosed automation speaking in a person's name is the failure
    this design exists to avoid.
@@ -319,7 +319,7 @@ org chart. The model consumes the tier and does not compute it.
 The exempt tier is also what defuses the obvious gaming risk. An originator who
 learns that an acknowledgment means "deprioritised" and escalates through
 another channel only succeeds if their escalation is one the person cannot
-ignore — which is what would have made them exempt in the first place.
+ignore - which is what would have made them exempt in the first place.
 
 ---
 
@@ -327,7 +327,7 @@ ignore — which is what would have made them exempt in the first place.
 
 Some requirements cannot be expressed as a vector, because they are about
 sequences rather than functions. They are normative regardless, and they are the
-requirements most often got wrong — each is here because it was observed failing
+requirements most often got wrong - each is here because it was observed failing
 in a shipped product.
 
 ### 9.1 Notification gating
@@ -346,7 +346,7 @@ entirely.
 
 Any suppression window **MUST** expire on its own. Expiry **MUST** be an emitted
 event, not a condition the host is expected to poll, and suppression **MUST** be
-lifted _before_ the end-of-window event is emitted — otherwise the window
+lifted _before_ the end-of-window event is emitted - otherwise the window
 swallows its own completion notice.
 
 _Why:_ focus modes that suppress until manually cleared strand the person on
@@ -354,7 +354,7 @@ exactly the day they forget, and the cost lands on someone who already had none.
 
 ### 9.3 Deferral
 
-Deferral presets **MUST** compute in the person's local time — "tomorrow
+Deferral presets **MUST** compute in the person's local time - "tomorrow
 morning" means their morning. The ordering **SHOULD** follow the level: at low
 capacity the one-tap default resurfaces work _later_, not in an hour, because
 resurfacing into the same depletion helps nobody.
@@ -364,7 +364,7 @@ UTC and an implementation replaying them **MUST** do the same.
 
 ### 9.4 Persistence
 
-Persisted state **MUST** round-trip verbatim — every field, not just the level.
+Persisted state **MUST** round-trip verbatim - every field, not just the level.
 An implementation that stores only the level and rebuilds the rest on read
 produces a new `timestamp` and `origin` on every load, which reads as a fresh
 write to §4 and causes contexts to fight.
@@ -430,10 +430,10 @@ this specification, not just to the library.
 
 - **Wording.** Every user-facing string is a product decision.
 - **Visual design.** The reference stylesheet is one interpretation.
-- **How a level is chosen.** A dial, a keystroke, a menu — the model requires
+- **How a level is chosen.** A dial, a keystroke, a menu - the model requires
   only that the person can set it directly.
 - **Classification.** How a host decides that an arrival bears an obligation, or
   what tier an originator is in, is the host's problem entirely. The model
   consumes the answer and the confidence attached to it.
-- **Transport.** How states reach each other — shared storage, IPC, a sync
-  server — is out of scope. The schema and §4 are what make any transport work.
+- **Transport.** How states reach each other - shared storage, IPC, a sync
+  server - is out of scope. The schema and §4 are what make any transport work.

package/api-surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.1",
+  "version": "2.0.5",
   "entryPoints": [
     {
       "specifier": "@kumbatio/energy-system",

package/conformance.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./spec/conformance.schema.json",
-  "version": "1.0.1",
+  "version": "2.0.5",
   "timezone": "UTC",
   "note": "Generated from the built library by scripts/extract-conformance.ts. See SPEC.md for the normative rules these vectors encode, including the runtime invariants that no vector can express.",
   "levels": [
@@ -56,7 +56,7 @@
       "value": 0,
       "key": "rest",
       "label": "Rest",
-      "description": "Depleted. Consumption only — reading, reflecting.",
+      "description": "Recovery. Consumption only — reading, reflecting.",
       "cognitiveProfile": {
         "decisionCapacity": "none",
         "focusDuration": "none",

package/dist/defer.d.ts

@@ -21,13 +21,13 @@ export declare const DEFERRAL_PRESET_IDS: Readonly<{
     readonly nextMonday: 'next-monday';
 }>;
 /**
- * Build the standard deferral presets. Times are computed in local time —
+ * Build the standard deferral presets. Times are computed in local time -
  * "tomorrow morning" means the user's morning.
  */
 export declare function createDeferralPresets(options?: DeferralPresetOptions): readonly DeferralPreset[];
 /**
  * Resolve a preset id to a resurface timestamp (epoch ms).
- * Returns null for an unknown id — callers decide whether that is an error.
+ * Returns null for an unknown id - callers decide whether that is an error.
  */
 export declare function resolveDeferral(presets: readonly DeferralPreset[], presetId: string, now?: Date): number | null;
 export interface DeferralConfig {

package/dist/defer.js

@@ -1,6 +1,6 @@
 import { getEnergyLevel } from './levels.js';
 /**
- * Deferral ("snooze") — the "not now" primitive. Deferring an item is an
+ * Deferral ("snooze") - the "not now" primitive. Deferring an item is an
  * energy statement: it declares insufficient capacity for it right now and
  * names when it should resurface. Presets are pure `(now) -> Date` functions;
  * the energy-aware strategy orders them so the default suggestion matches
@@ -33,7 +33,7 @@ function isWeekend(day) {
     return weekday === 0 || weekday === 6;
 }
 /**
- * Build the standard deferral presets. Times are computed in local time —
+ * Build the standard deferral presets. Times are computed in local time -
  * "tomorrow morning" means the user's morning.
  */
 export function createDeferralPresets(options = {}) {
@@ -98,7 +98,7 @@ export function createDeferralPresets(options = {}) {
 }
 /**
  * Resolve a preset id to a resurface timestamp (epoch ms).
- * Returns null for an unknown id — callers decide whether that is an error.
+ * Returns null for an unknown id - callers decide whether that is an error.
  */
 export function resolveDeferral(presets, presetId, now = new Date()) {
     const preset = presets.find((candidate) => candidate.id === presetId);

package/dist/demand.d.ts

@@ -7,7 +7,7 @@ import type { AdaptationStrategy } from './types.js';
  * - `known`: an established correspondent.
  * - `unknown`: no established relationship.
  *
- * Tier assignment is the app's job — a Screener approval, a contacts list, an
+ * Tier assignment is the app's job - a Screener approval, a contacts list, an
  * org chart. The policy only consumes the tier.
  */
 export type OriginatorTier = 'exempt' | 'known' | 'unknown';
@@ -18,7 +18,7 @@ export declare function isOriginatorTier(value: unknown): value is OriginatorTie
  *
  * - `live`: reaches the user now, untouched by this policy.
  * - `acknowledge`: the originator is acknowledged and the obligation is
- *   captured for later. The two are one act — an acknowledgment without a
+ *   captured for later. The two are one act - an acknowledgment without a
  *   capture is a promise nobody kept, a capture without an acknowledgment
  *   leaves the originator in silence.
  * - `silent`: captured for later with no acknowledgment.
@@ -26,7 +26,7 @@ export declare function isOriginatorTier(value: unknown): value is OriginatorTie
 export type DemandAdmission = 'live' | 'acknowledge' | 'silent';
 /** How much an acknowledgment may say */
 export type AcknowledgmentDetail = 'full' | 'brief' | 'minimal';
-/** Why the policy reached its decision — for audit trails and explanatory UI */
+/** Why the policy reached its decision - for audit trails and explanatory UI */
 export type DemandOutcomeReason = 'exempt-originator' | 'tier-admitted' | 'no-obligation' | 'acknowledgment-disabled' | 'below-confidence' | 'acknowledged';
 /**
  * What the acknowledgment is permitted to be. The two axes are independent:
@@ -49,8 +49,8 @@ export interface DemandOutcome {
 export interface DemandInput {
     readonly originatorTier: OriginatorTier;
     /**
-     * Whether this demand asks something of the user. Informational mail — a
-     * receipt, a newsletter, a build notification — is not this policy's
+     * Whether this demand asks something of the user. Informational mail - a
+     * receipt, a newsletter, a build notification - is not this policy's
      * business and passes through untouched.
      */
     readonly bearsObligation: boolean;
@@ -77,7 +77,7 @@ export interface DemandAdmissionConfig {
 export declare const demandAdmissionStrategy: AdaptationStrategy<DemandAdmissionConfig>;
 /**
  * The pure gating decision, extracted so apps can unit-test their demand
- * policy without wiring any effects — the counterpart of
+ * policy without wiring any effects - the counterpart of
  * `resolveNotificationOutcome`.
  *
  * Both configs are required because the two questions are genuinely separate:

package/dist/demand.js

@@ -1,6 +1,6 @@
 import { getEnergyLevel } from './levels.js';
 /**
- * Inbound demand — anything arriving from outside that asks for the user's
+ * Inbound demand - anything arriving from outside that asks for the user's
  * attention or action: an email, a document comment, a review request, a task
  * assignment, a collaboration invite.
  *
@@ -54,8 +54,8 @@ const ADMISSION_CONFIGS = freezeObject({
         acknowledgmentDetail: 'brief',
     }),
     // Rest: the acknowledgment survives, stripped to a fixed template. The
-    // originator's social debt still clears — that is the whole point of the
-    // loop — but nothing is composed on the user's behalf.
+    // originator's social debt still clears - that is the whole point of the
+    // loop - but nothing is composed on the user's behalf.
     0: freezeObject({
         originatorThreshold: 'exempt',
         acknowledge: true,
@@ -94,7 +94,7 @@ function isTierAdmitted(threshold, tier) {
 }
 /**
  * The pure gating decision, extracted so apps can unit-test their demand
- * policy without wiring any effects — the counterpart of
+ * policy without wiring any effects - the counterpart of
  * `resolveNotificationOutcome`.
  *
  * Both configs are required because the two questions are genuinely separate:
@@ -112,7 +112,7 @@ export function resolveDemandOutcome(config, autonomy, demand) {
     // The inner circle is never handled by machine. This is also what defuses the
     // gaming risk: an originator who learns that an acknowledgment means
     // "deprioritised" and escalates through another channel only succeeds if
-    // their escalation is one the user cannot ignore — which makes them exempt.
+    // their escalation is one the user cannot ignore - which makes them exempt.
     if (demand.originatorTier === 'exempt') {
         return freezeObject({
             admission: 'live',

package/dist/engine.d.ts

@@ -22,7 +22,7 @@ export interface EnergyEngineOptions {
      * to cross-context updates. Default: true.
      *
      * Pass false when the engine is constructed somewhere that may never be
-     * committed — a React render, most notably — and call `start()` from a
+     * committed - a React render, most notably - and call `start()` from a
      * lifecycle that only runs for trees React kept. Without this, a discarded
      * render leaves an engine nobody will ever dispose, holding a live
      * cross-context observer (a `storage` listener, for the localStorage

package/dist/engine.js

@@ -23,7 +23,7 @@ function isSameState(a, b) {
 /**
  * Validate state that arrived from outside this engine. `candidate` is typed
  * as `EnergyState`, but it crossed a process, tab or storage boundary to get
- * here, so nothing about its runtime shape is guaranteed — it is parsed
+ * here, so nothing about its runtime shape is guaranteed - it is parsed
  * against the published schema before anything else looks at it.
  */
 function normalizeState(candidate, nowMs, maxFutureSkewMs) {
@@ -63,7 +63,7 @@ export function createEnergyEngine(options = {}) {
      *
      * The origin is ALWAYS the sentinel, never `options.originId`. SPEC.md §3.2 requires the
      * untouched default to stay distinguishable from a real state, and `isUnproducedState()` tests
-     * exactly this pair — stamping a configured producer identity here turns "nobody has chosen
+     * exactly this pair - stamping a configured producer identity here turns "nobody has chosen
      * yet" into a state that looks chosen, which reads downstream as a level set at the epoch.
      * The configured identity belongs to the first state this engine actually produces.
      */

package/dist/gate.d.ts

@@ -71,7 +71,7 @@ export interface NotificationGate {
     flush(): void;
     /**
      * Release resources. Pending notifications are delivered as a final
-     * 'released' delivery first — a disposed gate never swallows intents.
+     * 'released' delivery first - a disposed gate never swallows intents.
      */
     dispose(): void;
 }

package/dist/gate.js

@@ -1,6 +1,6 @@
 import { notificationStrategy } from './strategies.js';
 /**
- * Notification gate — the runtime that ENFORCES `NotificationConfig` instead
+ * Notification gate - the runtime that ENFORCES `NotificationConfig` instead
  * of leaving it as guidance. Apps publish notification intents through the
  * gate; the gate resolves the current energy level's config and decides
  * whether each intent is delivered now, batched, or deferred.
@@ -152,7 +152,7 @@ export function createNotificationGate(engine, options) {
      * Classification happens when an intent is published, but both energy and
      * suppression move while a batch window is open. Without this pass a
      * notification batched at Focus is delivered after a focus session starts,
-     * and one batched at Focus is surfaced at Rest with every channel disabled —
+     * and one batched at Focus is surfaced at Rest with every channel disabled -
      * the gate's own policy, applied to the wrong moment.
      *
      * Batched intents the current policy no longer admits are demoted to
@@ -201,7 +201,7 @@ export function createNotificationGate(engine, options) {
         deliver(released, 'released');
     }
     function deliverBatch() {
-        // Flushing a window is not an override of the active policy — only of the
+        // Flushing a window is not an override of the active policy - only of the
         // wait. Anything no longer admissible leaves through `deferred` instead.
         reconcilePending();
         clearBatchTimer();

package/dist/levels.d.ts

@@ -3,7 +3,7 @@ import type { EnergyLevel, EnergyLevelDefinition, EnergySource, EnergyState } fr
 export declare function createEnergyOrigin(): string;
 export declare const UNPRODUCED_ORIGIN = "0-initial";
 export declare const UNPRODUCED_TIMESTAMP = 0;
-/** True for the untouched default state — its age and identity are not meaningful. */
+/** True for the untouched default state - its age and identity are not meaningful. */
 export declare function isUnproducedState(state: Pick<EnergyState, 'timestamp' | 'origin'>): boolean;
 /** Get all energy level definitions, ordered highest to lowest */
 export declare function getEnergyLevels(): ReadonlyArray<Readonly<EnergyLevelDefinition>>;
@@ -20,8 +20,8 @@ export declare function isHigherEnergy(a: EnergyLevel, b: EnergyLevel): boolean;
 /** Create an EnergyState for the current moment */
 export declare function createEnergyState(level: EnergyLevel, source?: EnergySource, timestamp?: number, revision?: number, origin?: string): EnergyState;
 /**
- * Parse a value that came from OUTSIDE this engine — persisted JSON, a
- * cross-context observation, a wire message — into an `EnergyState`.
+ * Parse a value that came from OUTSIDE this engine - persisted JSON, a
+ * cross-context observation, a wire message - into an `EnergyState`.
  *
  * This is the interchange boundary, so it enforces the published JSON Schema
  * exactly rather than approximately: `additionalProperties: false` means an

package/dist/levels.js

@@ -20,7 +20,7 @@ export function createEnergyOrigin() {
     return `${Date.now().toString(36)}-${originSequence.toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 /*
- * Markers for a state that has never been *produced* — the untouched default an engine starts with,
+ * Markers for a state that has never been *produced* - the untouched default an engine starts with,
  * as opposed to a level anyone actually chose.
  *
  * Both exist so engine construction reads neither the clock nor the random source. React providers
@@ -32,7 +32,7 @@ export function createEnergyOrigin() {
  */
 export const UNPRODUCED_ORIGIN = '0-initial';
 export const UNPRODUCED_TIMESTAMP = 0;
-/** True for the untouched default state — its age and identity are not meaningful. */
+/** True for the untouched default state - its age and identity are not meaningful. */
 export function isUnproducedState(state) {
     return state.timestamp === UNPRODUCED_TIMESTAMP && state.origin === UNPRODUCED_ORIGIN;
 }
@@ -106,7 +106,7 @@ const LEVELS = Object.freeze([
         value: 0,
         key: 'rest',
         label: 'Rest',
-        description: 'Depleted. Consumption only \u2014 reading, reflecting.',
+        description: 'Recovery. Consumption only \u2014 reading, reflecting.',
         cognitiveProfile: freezeObject({
             decisionCapacity: 'none',
             focusDuration: 'none',
@@ -179,8 +179,8 @@ export function createEnergyState(level, source = 'manual', timestamp = Date.now
 /** The exact key set `spec/energy-state.schema.json` permits. */
 const ENERGY_STATE_KEYS = ['level', 'timestamp', 'source', 'revision', 'origin'];
 /**
- * Parse a value that came from OUTSIDE this engine — persisted JSON, a
- * cross-context observation, a wire message — into an `EnergyState`.
+ * Parse a value that came from OUTSIDE this engine - persisted JSON, a
+ * cross-context observation, a wire message - into an `EnergyState`.
  *
  * This is the interchange boundary, so it enforces the published JSON Schema
  * exactly rather than approximately: `additionalProperties: false` means an

package/dist/metrics.js

@@ -31,7 +31,7 @@ export function getEnergyMetrics(state, now = Date.now()) {
     /*
      * The untouched default carries a sentinel timestamp rather than the moment its engine happened
      * to be constructed, so that construction stays prerender-safe. Subtracting from it would report
-     * an age measured from the epoch — decades — for a state nobody has set yet. It has no age.
+     * an age measured from the epoch - decades - for a state nobody has set yet. It has no age.
      */
     const stateAgeMs = isUnproducedState(state) ? 0 : Math.max(0, safeNow - state.timestamp);
     const definition = getEnergyLevel(state.level);

package/dist/persistence.js

@@ -18,7 +18,7 @@ function parsePersistedState(source, raw) {
     }
     try {
         // Shape, key set and field invariants are all one boundary rule, enforced
-        // to the letter of spec/energy-state.schema.json — including its
+        // to the letter of spec/energy-state.schema.json - including its
         // `additionalProperties: false`. Storage written by a newer or foreign
         // producer is rejected, not quietly trimmed to fit.
         return parseExternalEnergyState(parsed);

package/dist/presence.d.ts

@@ -34,7 +34,7 @@ export declare function defineEnergyPresence(spec?: EnergyPresenceSpec): EnergyP
  */
 export declare function presenceAtOrAbove(min: EnergyLevel, below?: EnergyPresence): EnergyPresenceMap;
 /**
- * Presence map for elements that only belong at low energy — recovery hints,
+ * Presence map for elements that only belong at low energy - recovery hints,
  * "one thing at a time" affordances. Above `max` the element is `above`
  * ('hidden' by default).
  */

package/dist/presence.js

@@ -59,7 +59,7 @@ export function presenceAtOrAbove(min, below = 'hidden') {
     return freezeObject(entries);
 }
 /**
- * Presence map for elements that only belong at low energy — recovery hints,
+ * Presence map for elements that only belong at low energy - recovery hints,
  * "one thing at a time" affordances. Above `max` the element is `above`
  * ('hidden' by default).
  */

package/dist/react.d.ts

@@ -16,7 +16,7 @@ export interface EnergyProviderProps {
      * Element the level is projected onto. Default: `document.body`.
      *
      * Pass `() => document.documentElement` when the stylesheet keys off
-     * `[data-energy-level]` at the root — resolved inside the effect, so the
+     * `[data-energy-level]` at the root - resolved inside the effect, so the
      * render phase never touches the DOM. Whatever the target, the provider
      * snapshots what was there, layers overlapping providers, and restores the
      * baseline on unmount.

package/dist/react.js

@@ -289,7 +289,7 @@ export function EnergyGate({ presence, min, max, fallback = null, whenHidden = '
      * render, hidden or not. That stability is the whole mechanism: reconciling the
      * same boundary is what carries state across the transition. Rendering Activity
      * only while hidden would swap the element type at that slot and remount the
-     * subtree on reveal — losing exactly the state this is here to keep.
+     * subtree on reveal - losing exactly the state this is here to keep.
      */
     return createElement(Fragment, null, isHidden ? fallback : null, createElement(Activity, {
         mode: isHidden ? 'hidden' : 'visible',

package/dist/reconcile.d.ts

@@ -4,12 +4,12 @@ import type { EnergyState } from './types.js';
  *
  * The comparison walks four keys in order, stopping at the first that differs:
  *
- * 1. **`timestamp`** — later wins. The ordinary case, and the only one most
+ * 1. **`timestamp`** - later wins. The ordinary case, and the only one most
  *    states ever reach.
- * 2. **`revision`** — higher wins. Two writes inside one clock tick are not
+ * 2. **`revision`** - higher wins. Two writes inside one clock tick are not
  *    simultaneous; the producer numbers them so they still order.
- * 3. **`source`** — `manual` > `scheduled` > `inferred`. See `sourcePriority`.
- * 4. **`origin`** — higher string wins. Not meaningful, and deliberately so:
+ * 3. **`source`** - `manual` > `scheduled` > `inferred`. See `sourcePriority`.
+ * 4. **`origin`** - higher string wins. Not meaningful, and deliberately so:
  *    when two producers write the same instant, the same revision, and the same
  *    kind of source, there is no principled winner, and an arbitrary rule every
  *    context computes identically beats a coin flip each context tosses

package/dist/reconcile.js

@@ -1,12 +1,12 @@
 /**
- * State reconciliation — how two `EnergyState` values that describe the same
+ * State reconciliation - how two `EnergyState` values that describe the same
  * user are ordered when they meet.
  *
  * They meet constantly: a second browser tab writes the shared store, a desktop
  * window and its detached child both hold an engine, a sync layer hands back
  * what another device recorded. Every one of those paths needs the same answer
  * to "which of these two is the current state?", and the answer has to be
- * *deterministic* — not "last write wins by arrival order", which converges on
+ * *deterministic* - not "last write wins by arrival order", which converges on
  * different values depending on network timing.
  *
  * This is the rule, extracted from the engine so it can be read, tested, and
@@ -36,12 +36,12 @@ function sourcePriority(source) {
  *
  * The comparison walks four keys in order, stopping at the first that differs:
  *
- * 1. **`timestamp`** — later wins. The ordinary case, and the only one most
+ * 1. **`timestamp`** - later wins. The ordinary case, and the only one most
  *    states ever reach.
- * 2. **`revision`** — higher wins. Two writes inside one clock tick are not
+ * 2. **`revision`** - higher wins. Two writes inside one clock tick are not
  *    simultaneous; the producer numbers them so they still order.
- * 3. **`source`** — `manual` > `scheduled` > `inferred`. See `sourcePriority`.
- * 4. **`origin`** — higher string wins. Not meaningful, and deliberately so:
+ * 3. **`source`** - `manual` > `scheduled` > `inferred`. See `sourcePriority`.
+ * 4. **`origin`** - higher string wins. Not meaningful, and deliberately so:
  *    when two producers write the same instant, the same revision, and the same
  *    kind of source, there is no principled winner, and an arbitrary rule every
  *    context computes identically beats a coin flip each context tosses

package/dist/session.d.ts

@@ -30,12 +30,12 @@ export interface FocusSessionControllerOptions {
     /**
      * Engine used for energy-aware defaults: session length from the level's
      * expected productivity window, break cadence from the task-complexity
-     * strategy. Optional — without it, defaults are 25 minutes / no breaks.
+     * strategy. Optional - without it, defaults are 25 minutes / no breaks.
      */
     engine?: EnergyEngine;
     /**
      * Suppression target (typically a NotificationGate). Suppressed on start,
-     * released on stop/end/dispose — the controller owns the flag for the
+     * released on stop/end/dispose - the controller owns the flag for the
      * session's lifetime, so it can never be left stuck on.
      */
     gate?: FocusSuppressible;

package/dist/session.js

@@ -1,7 +1,7 @@
 import { getEnergyMetrics } from './metrics.js';
 import { taskComplexityStrategy } from './strategies.js';
 /**
- * Focus sessions — time-boxed "one thing at a time" windows layered on top of
+ * Focus sessions - time-boxed "one thing at a time" windows layered on top of
  * the energy model. A session is a temporary commitment, not an energy level:
  * it suppresses interruptions for a bounded duration, surfaces break nudges,
  * and ALWAYS ends on time.
@@ -9,7 +9,7 @@ import { taskComplexityStrategy } from './strategies.js';
  * Two invariants come from field evidence (GingerMail shipped the opposite
  * and both were user-hostile):
  *   1. Sessions auto-expire. Expiry is an emitted event, not a predicate the
- *      app must remember to poll — suppression can never outlive the session.
+ *      app must remember to poll - suppression can never outlive the session.
  *   2. Suppression is lifted BEFORE the end event is emitted, so an
  *      end-of-session notification can never be swallowed by the session's
  *      own suppression.
@@ -114,7 +114,7 @@ export function createFocusSessionController(options = {}) {
         if (!engine)
             return DEFAULT_SESSION_MINUTES;
         const window = getEnergyMetrics(engine.getState(), now()).expectedProductivityWindowMinutes;
-        // At rest (0) the metrics window is 0 — an explicit session at rest still
+        // At rest (0) the metrics window is 0 - an explicit session at rest still
         // deserves a real bound rather than an instantly-expiring one.
         return window > 0 ? window : DEFAULT_SESSION_MINUTES;
     }

package/dist/strategies.d.ts

@@ -57,8 +57,8 @@ export declare const interactionForgivenessStrategy: AdaptationStrategy<Interact
  * supervise it, so the worst day is the wrong day for it to improvise.
  *
  * What narrows as energy falls is *discretion*, not action. At rest the
- * automation may still take a single, certain, template-only step — an
- * out-of-office reply is exactly that shape — but it may not chain steps,
+ * automation may still take a single, certain, template-only step - an
+ * out-of-office reply is exactly that shape - but it may not chain steps,
  * compose novel wording, or act on a judgment call.
  */
 export interface AutonomyConfig {

package/dist/strategies.js

@@ -239,7 +239,7 @@ const AUTONOMY_CONFIGS = freezeObject({
         allowGeneratedContent: false,
         maxUnattendedSteps: 1,
     }),
-    // Rest: one certain, templated step at most. Not zero — an automated action
+    // Rest: one certain, templated step at most. Not zero - an automated action
     // the user has standing consent for (an out-of-office reply is the classic)
     // is safest at rest precisely because it stops improvising.
     0: freezeObject({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumbatio/energy-system",
-  "version": "1.0.1",
+  "version": "2.0.5",
   "private": false,
   "description": "Framework-agnostic TypeScript library for energy-aware application behavior.",
   "license": "MIT",
@@ -47,23 +47,44 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build:ts": "tsc -p tsconfig.build.json",
+    "build": "pnpm run build:ts && pnpm run api:surface && pnpm run conformance",
+    "api:surface": "tsx scripts/extract-api-surface.ts",
+    "api:surface:check": "tsx scripts/extract-api-surface.ts --check",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "test": "pnpm run build:ts && node --test --import tsx",
+    "validate": "pnpm run format:check && pnpm run lint && pnpm run check-types && pnpm run test && pnpm run pack:dry-run",
+    "prepack": "pnpm run format:check && pnpm run lint && pnpm run check-types && pnpm run test",
+    "pack:dry-run": "pnpm pack --dry-run",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --import-plugin --type-aware --type-check --vitest-plugin .",
+    "lint:fix": "oxlint --import-plugin --type-aware --type-check --vitest-plugin --fix . && oxfmt --write .",
+    "lint:fix-unsafe": "oxlint --import-plugin --type-aware --type-check --vitest-plugin --fix --fix-suggestions --fix-dangerously . && oxfmt --write .",
+    "check:fix-suggestions": "oxlint --import-plugin   --type-aware --type-check --vitest-plugin --fix --fix-suggestions . && oxfmt --write .",
+    "conformance": "TZ=UTC tsx scripts/extract-conformance.ts",
+    "conformance:check": "TZ=UTC tsx scripts/extract-conformance.ts --check",
+    "release": "release-kit"
+  },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.2",
+    "@entro314labs/release-kit": "^2.9.0",
+    "@happy-dom/global-registrator": "^20.11.6",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "ajv": "8.20.0",
-    "oxfmt": "0.62.0",
-    "oxlint": "1.77.0",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
     "oxlint-tsgolint": "^7.0.2001",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tsx": "^4.23.12",
-    "typescript": "^7.0.2"
+    "typescript": "next"
   },
   "peerDependencies": {
-    "@types/react": ">=19.2.0",
-    "react": ">=19.2.0"
+    "@types/react": ">=19.2.18",
+    "react": ">=19.2.8"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -76,22 +97,5 @@
   "engines": {
     "node": ">=24.19.0"
   },
-  "scripts": {
-    "build:ts": "tsc -p tsconfig.build.json",
-    "build": "pnpm run build:ts && pnpm run api:surface && pnpm run conformance",
-    "api:surface": "tsx scripts/extract-api-surface.ts",
-    "api:surface:check": "tsx scripts/extract-api-surface.ts --check",
-    "check-types": "tsc --noEmit -p tsconfig.json",
-    "test": "pnpm run build:ts && node --test --import tsx",
-    "validate": "pnpm run format:check && pnpm run lint && pnpm run check-types && pnpm run test && pnpm run pack:dry-run",
-    "pack:dry-run": "pnpm pack --dry-run",
-    "format": "oxfmt --write .",
-    "format:check": "oxfmt --check .",
-    "lint": "oxlint --import-plugin --type-aware --type-check --vitest-plugin .",
-    "lint:fix": "oxlint --import-plugin --type-aware --type-check --vitest-plugin --fix . && oxfmt --write .",
-    "lint:fix-unsafe": "oxlint --import-plugin --type-aware --type-check --vitest-plugin --fix --fix-suggestions --fix-dangerously . && oxfmt --write .",
-    "check:fix-suggestions": "oxlint --import-plugin   --type-aware --type-check --vitest-plugin --fix --fix-suggestions . && oxfmt --write .",
-    "conformance": "TZ=UTC tsx scripts/extract-conformance.ts",
-    "conformance:check": "TZ=UTC tsx scripts/extract-conformance.ts --check"
-  }
-}
+  "packageManager": "pnpm@11.22.0"
+}

package/spec/conformance.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kumbat.io/spec/conformance.schema.json",
   "title": "EnergyConformance",
-  "description": "The shape of conformance.json: the executable half of SPEC.md. A port in any language passes by loading that file and asserting its own output against each vector. This schema is what lets that port know the file it loaded is the file it expects — vectors that silently changed shape are worse than vectors that failed to load. scripts/extract-conformance.ts validates its own output against this schema before writing, so the two cannot drift apart unnoticed.",
+  "description": "The shape of conformance.json: the executable half of SPEC.md. A port in any language passes by loading that file and asserting its own output against each vector. This schema is what lets that port know the file it loaded is the file it expects - vectors that silently changed shape are worse than vectors that failed to load. scripts/extract-conformance.ts validates its own output against this schema before writing, so the two cannot drift apart unnoticed.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -378,7 +378,7 @@
     },
 
     "externalLevelMapping": {
-      "description": "Percentages an external model might hand over, including both midpoints — 12.5 and 37.5 sit exactly between two levels, which is where rounding implementations disagree.",
+      "description": "Percentages an external model might hand over, including both midpoints - 12.5 and 37.5 sit exactly between two levels, which is where rounding implementations disagree.",
       "type": "array",
       "minItems": 1,
       "items": {

package/spec/energy-state.schema.json

@@ -29,7 +29,7 @@
       "maximum": 9007199254740991
     },
     "origin": {
-      "description": "Stable identity of the producer — an engine instance, a device, a process. Must be unique per producer and stable across that producer's writes. The final tiebreaker compares it lexicographically, so a producer that reuses one identity for different state breaks convergence.",
+      "description": "Stable identity of the producer - an engine instance, a device, a process. Must be unique per producer and stable across that producer's writes. The final tiebreaker compares it lexicographically, so a producer that reuses one identity for different state breaks convergence.",
       "type": "string",
       "minLength": 1
     }

package/src/energy.css

@@ -146,7 +146,7 @@
 
 /* A cursor is a HINT, and one only a pointer user receives. It changes nothing
  * about what is focusable or clickable, so an app that means "read only" at Rest
- * must also disable the controls — otherwise a keyboard user gets no signal at
+ * must also disable the controls - otherwise a keyboard user gets no signal at
  * all and a pointer user gets a signal that turns out to be false. */
 [data-energy-level='0'] .energy-content * {
   cursor: default !important;
@@ -156,8 +156,8 @@
  *
  * Annotate any element with the energy range it belongs to:
  *
- *   <div data-energy-min="75">AI chat — needs 75+ energy</div>
- *   <div data-energy-max="25">Recovery hint — low energy only</div>
+ *   <div data-energy-min="75">AI chat - needs 75+ energy</div>
+ *   <div data-energy-max="25">Recovery hint - low energy only</div>
  *
  * The element hides automatically whenever the root's data-energy-level
  * falls outside its declared range. This mirrors the JS presence API
@@ -218,7 +218,7 @@
  * Be honest about what the resting values are: chrome sits at 10% opacity at
  * level 25 and 5% at level 0, and neither meets WCAG 1.4.11 (Non-text Contrast,
  * 3:1 for UI components) in its resting state. That is a deliberate design
- * default for a receding interface, not a conformance claim — and it is why
+ * default for a receding interface, not a conformance claim - and it is why
  * every value here is a custom property an app can raise in one line.
  *
  * Two populations must not be left to do that themselves:
@@ -229,12 +229,12 @@
  *
  * `forced-colors: active` (Windows High Contrast and friends) overrides colors
  * but NOT opacity, so faded chrome stays faded while everything around it snaps
- * to a system palette — the fade is no longer a soft de-emphasis, it is the only
+ * to a system palette - the fade is no longer a soft de-emphasis, it is the only
  * thing still hiding content. Opacity comes off entirely.
  *
  * Both blocks declare `!important`, which is load-bearing rather than a shortcut.
  * `applyEnergyLevel()` writes these same custom properties as INLINE styles, and
- * an inline declaration outranks an ordinary rule — so without this, the JS path
+ * an inline declaration outranks an ordinary rule - so without this, the JS path
  * would silently defeat the user's stated contrast preference while the CSS-only
  * path honoured it. An important author declaration beats a normal inline one,
  * which is exactly the ordering wanted here: a preference the person set outranks