@kumbatio/energy-system 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to `@kumbatio/energy-system` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and from `1.0.0` this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+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
+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.
+
+## [1.0.0]
+
+The API is frozen. Everything below documents what that commitment now covers.
+
+### Added
+
+- **[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
+  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
+  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
+  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
+  `prefers-contrast: more` and `forced-colors: active`. Both declare
+  `!important` deliberately: `applyEnergyLevel()` writes the same custom
+  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
+  (protection never decreases and automation never gains discretion as capacity
+  falls), which a future edit to one table would otherwise break silently.
+
+### Changed
+
+- The reference stylesheet is explicit that its resting chrome opacities at Low
+  and Rest do not meet WCAG 1.4.11, that this is a design default rather than a
+  conformance claim, and that every value is an overridable custom property.
+  Saying so is more useful than quietly shipping numbers that imply otherwise.
+- `readOnlyCursor` is documented as a hint that reaches pointer users only, and
+  which must be paired with actually disabling controls if "read only" is meant.
+
+## [0.6.0]
+
+### Added
+
+- `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
+  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
+  confident enough to speak. Policy only; the effects it implies leave the
+  process and cannot be made transactional by an in-process runtime, so the
+  orchestration belongs to the consuming app.
+
+## [0.5.4]
+
+### Added
+
+- `createEnergyOrigin` exported from the index.
+
+## [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
+wild: suppressed reminders destroyed instead of deferred, and focus suppression
+that never auto-expired.
+
+### Added
+
+- Presence annotation: `defineEnergyPresence`, `presenceAtOrAbove`,
+  `presenceAtOrBelow`, `createPresenceStrategy`, `useEnergyPresence`,
+  `<EnergyGate>`, and the CSS-only `data-energy-min` / `data-energy-max` path.
+- Notification gate: runtime enforcement of `NotificationConfig` with a
+  defer-not-drop guarantee.
+- Focus sessions: time-boxed suppression with auto-expiry events and break nudges.
+- Deferral presets with energy-aware ordering (`deferralStrategy`).
+- Interaction forgiveness strategy.
+- `prefers-reduced-motion` handling for the stylesheet's own transitions.
+
+## [0.1.0]
+
+### Changed
+
+- Renamed to `@kumbatio/energy-system`; the previous package name is deprecated.
+
+## [0.0.x]
+
+Foundations: the 5-level model with immutable revisioned state, the
+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.

package/README.md

@@ -513,11 +513,54 @@ The engine orders concurrent writes by timestamp, logical revision, source prior
 origin. This gives every context the same deterministic winner even when two writes share a wall
 clock timestamp. Local writes advance the logical revision when the clock does not advance.
 
+The rule is exported as `isPreferredEnergyState(candidate, current)` and specified normatively in
+[SPEC.md §4](./SPEC.md). It is the hardest part of the model to reimplement correctly, so it is
+readable, testable, and covered by conformance vectors on its own rather than buried in the engine.
+
 `setLevel()` updates in-memory subscribers synchronously. Persistence runs in the background with
 bounded exponential backoff. Call `await engine.flush()` when a workflow must wait for durable
 storage before reporting completion. An initial `flush()` waits for hydration before writing the
 default state, and rejects rather than overwriting unread storage if that hydration read failed.
 
+## Specification and conformance
+
+The model is specified independently of this implementation.
+
+- **[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
+  two processes (or two languages) can share one person's energy state.
+- **[conformance.json](./conformance.json)** — every table and every decision above, as vectors.
+  Ships in the package.
+
+```ts
+import conformance from '@kumbatio/energy-system/conformance.json' with { type: 'json' }
+```
+
+An implementation in another language passes by loading the vectors and replaying them; this
+package's own `test/conformance.test.ts` does exactly that and is a reasonable model to copy. The
+file is generated from the built library, so the vectors cannot drift from the behavior they
+describe — and a stale `conformance.json` fails the build.
+
+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
+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:
+
+- **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
+  [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,
+  existing vectors do not change meaning; new sections and new vectors may be added.
+- Prose from `describe()` is _not_ covered. Wording is a product decision and may change in a patch.
+- Adding a strategy, an option with a default, or a new export is a minor release.
+
 ## Development
 
 ```bash
@@ -536,7 +579,7 @@ 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, and interaction forgiveness — integrated without the React adapter.
+- **[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).

package/SPEC.md

@@ -0,0 +1,439 @@
+# The Energy Model — Specification
+
+**Version 1 · normative · language-independent**
+
+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
+implementation of the same model, and states produced by one may be read by
+another.
+
+There is a machine-readable half. [`conformance.json`](./conformance.json) ships
+in this package and encodes every table and every decision below as vectors.
+Load it, replay it, and you have a conformance suite without writing one. It is
+generated from the built library, so the vectors and the reference
+implementation cannot disagree.
+
+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
+document, and as deserving of a stable representation.
+
+That claim only pays off if one person's energy state can be shared by
+everything they use: a mail client, a writing tool, a coordination app, a phone.
+Sharing state across processes and languages is an interchange problem, and
+interchange needs a specification rather than a port. Five hand-written ports of
+the same tables will drift within two releases, and on the day they disagree the
+promise quietly becomes false.
+
+So the portable artifact is this document plus the vectors. An implementation is
+then a small amount of local code around a shared, checkable definition.
+
+---
+
+## 2. Levels
+
+The model has exactly **five** levels, and they are discrete.
+
+| Value | Key      | Label  | Meaning                                                    |
+| ----- | -------- | ------ | ---------------------------------------------------------- |
+| `100` | `peak`   | Peak   | High capacity. Planning, complex decisions, creative work. |
+| `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.          |
+
+An implementation **MUST** use exactly these five values and **MUST NOT** admit
+intermediate ones. This is a design commitment, not an arbitrary limit: a
+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
+vectors under `levels`. Implementations **MUST** reproduce these values;
+consumers branch on them.
+
+**Cycling** is `100 → 75 → 50 → 25 → 0 → 100`. Downward by default, because the
+common act is admitting depletion, and the wrap gives one control both
+directions. See `cycle` in the vectors.
+
+### 2.1 What the levels are not
+
+They are not a scale of worth, and an implementation **SHOULD NOT** present them
+as a score, a streak, or something to optimise. Rest is a valid state to be in
+and the interface **SHOULD** be usable there. An implementation **MUST NOT**
+make Rest a degraded or punitive mode.
+
+---
+
+## 3. Energy state
+
+The unit of interchange is an **energy state**: one producer's point-in-time
+claim about a person's capacity. Its serialized form is specified by
+[`spec/energy-state.schema.json`](./spec/energy-state.schema.json).
+
+| Field       | Type                              | Role                                         |
+| ----------- | --------------------------------- | -------------------------------------------- |
+| `level`     | `0 \| 25 \| 50 \| 75 \| 100`      | The declared capacity.                       |
+| `timestamp` | integer, epoch milliseconds       | When it was produced. Primary ordering key.  |
+| `source`    | `manual \| scheduled \| inferred` | How it was arrived at.                       |
+| `revision`  | non-negative safe integer         | Sequence among states sharing one timestamp. |
+| `origin`    | non-empty string                  | Stable identity of the producer.             |
+
+A state **MUST** be immutable once produced. Implementations **SHOULD** enforce
+this with whatever their language offers.
+
+### 3.1 Source
+
+`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.
+
+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
+suggestion the person confirms rather than applying it silently. A model of
+someone's capacity that overrides what they said about it recreates the loss of
+control the model exists to answer.
+
+### 3.2 The unproduced sentinel
+
+An implementation needs a state before anyone has set one. That default **MUST**
+be distinguishable from a real state, because "nobody has chosen yet" and
+"someone chose Peak" are different facts and only the second should survive
+reconciliation.
+
+The sentinel is `timestamp = 0` together with `origin = "0-initial"`. Both sort
+below any real value, so §4 replaces the default unconditionally.
+
+Producing the sentinel **MUST NOT** require reading the clock or a random
+source. This is not a micro-optimisation: constructing a state during a
+server-side render otherwise bakes an unstable value into static output, which
+some frameworks fail the build on outright.
+
+### 3.3 Rejecting implausible states
+
+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.
+
+The reference default is **5 minutes**. The budget **SHOULD** be configurable,
+including "accept anything finite" for controlled environments.
+
+---
+
+## 4. Reconciliation
+
+> This is the section to get right. Everything else is a table.
+
+Two states for the same person meet constantly: a second tab writes shared
+storage, two windows each hold a producer, a sync layer returns what another
+device recorded. Every path needs the same answer to _which of these is
+current_, and the answer **MUST** be a deterministic function of the two states
+alone. "Last write wins by arrival order" is not acceptable: it converges on
+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.
+
+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
+flip each context tosses separately. Convergence is the property that matters.
+
+An implementation **MUST** additionally treat a `level` difference as a
+tiebreaker below key 4 (greater wins). This is unreachable for conforming
+producers, since it requires one `origin` to have produced two different states
+with identical timestamps and revisions. It exists so a buggy producer causes a
+wrong answer rather than an oscillation.
+
+**Antisymmetry is required.** For any two states, both directions **MUST NOT**
+report "preferred". Two contexts observing each other would otherwise swap
+states forever. The vectors assert both directions of every pair for this
+reason.
+
+Reference: `isPreferredEnergyState`; vectors under `reconciliation`.
+
+---
+
+## 5. Adaptation strategies
+
+A **strategy** is a pure total function from level to a configuration value. It
+**MUST** be free of side effects, **MUST** be defined for all five levels, and
+**MUST** return the same value for the same level every time.
+
+The distinction that keeps the model honest is **strategies describe, runtimes
+enforce**. A strategy says "at Steady, notifications batch every five minutes";
+something else does the batching. Keeping the description pure is what makes it
+portable, testable, and readable by a person deciding whether to trust it.
+
+Seven strategies are specified. Their complete per-level tables are in the
+vectors under `strategies`; they are not reproduced here, because a table
+duplicated in prose is a table that will disagree with itself.
+
+| Name                      | Governs                                                            |
+| ------------------------- | ------------------------------------------------------------------ |
+| `ui-visibility`           | Which chrome is shown, its opacity, content width and font scale.  |
+| `notifications`           | Channels, batching interval, and minimum priority.                 |
+| `task-complexity`         | Ceiling on surfaced task complexity; break cadence.                |
+| `interaction-forgiveness` | Undo window, destructive-action confirmation, autosave cadence.    |
+| `deferral`                | Ordering of "not now" presets, and the one-tap default.            |
+| `autonomy`                | What automation may do unattended (§7).                            |
+| `demand-admission`        | What happens to an arrival that asks something of the person (§8). |
+
+An implementation **MUST** provide `ui-visibility`, `notifications`, and
+`interaction-forgiveness` to claim conformance; the rest are **SHOULD**, since
+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.
+
+### 5.1 Human-readable descriptions
+
+The reference implementation pairs each strategy with a `describe(level)`
+returning English prose. This is **NOT** normative and conformance does not
+check it. Wording is a product and localisation decision.
+
+---
+
+## 6. Direction
+
+Two rules constrain every table, and an implementation adding a strategy
+**SHOULD** obey them:
+
+1. **Lower energy means less demanded of the person, not less capability.**
+   Chrome recedes, notifications batch, defaults lengthen. Features are not
+   removed as punishment. The one exception is destructive capability, which
+   §5's forgiveness table deliberately makes _harder_ to reach.
+2. **Protection scales inversely with capacity.** Undo windows widen,
+   confirmations appear, autosave quickens as energy falls. Slower error
+   detection is met with more room to catch errors.
+
+---
+
+## 7. Autonomy
+
+`autonomy` governs what automated systems may do on the person's behalf without
+being asked. It is the mirror of interaction forgiveness: forgiveness protects
+against the _person's_ mistakes at low energy, autonomy against the _agent's_.
+
+Three fields: `confidenceThreshold` (0–1, the minimum confidence to act
+unattended), `allowGeneratedContent` (whether wording may be composed or must
+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
+**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.
+
+A comparison against the threshold **MUST** admit equality: confidence `0.8` at
+a threshold of `0.8` acts. Vectors sample every threshold boundary for this
+reason.
+
+---
+
+## 8. Inbound demand
+
+**Inbound demand** is anything arriving from outside that asks for the person's
+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
+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.
+
+### 8.1 The decision
+
+Given the level's `demand-admission` config, its `autonomy` config, and an
+arrival described by `originatorTier` (`exempt` / `known` / `unknown`),
+`bearsObligation`, and `confidence` (default `1`), the outcome **MUST** be
+computed in this order:
+
+1. `originatorTier` is `exempt` → **live**, no acknowledgment. Unconditional, at
+   every level.
+2. The tier passes the level's `originatorThreshold` → **live**.
+3. `bearsObligation` is false → **live**. Informational arrivals ask nothing;
+   whether they should _interrupt_ is the notification question, not this one.
+4. The level does not acknowledge → **silent** (captured, no acknowledgment).
+5. `confidence` is below the autonomy threshold → **silent**.
+6. Otherwise → **acknowledge**, at the level's detail, composed only if autonomy
+   permits generated content.
+
+Reference: `resolveDemandOutcome`; 180 vectors under `decisions.demand`.
+
+### 8.2 Invariants for anything acting on the decision
+
+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,
+   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
+   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
+   commitment the person's Tuesday self has to keep. Implementations **MUST
+   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
+   (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.
+4. **At most once per originator, per window.** Five arrivals from one sender
+   while someone is depleted are one social debt, not five. Answering each is
+   the volume asymmetry the model is trying to correct.
+
+### 8.3 Tiers
+
+Tier assignment is the host's: an approved-senders list, a contacts database, an
+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.
+
+---
+
+## 9. Runtime invariants
+
+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
+in a shipped product.
+
+### 9.1 Notification gating
+
+An implementation that gates notifications by level **MUST NOT** silently drop
+one. Anything not deliverable now is **deferred** and released when the level
+rises, suppression lifts, or the gate is torn down. A gate being disposed
+**MUST** surface what it still holds.
+
+_Why:_ a field client's scheduler destroyed reminders that came due while
+suppressed. From the user's side that is indistinguishable from the app losing
+their data, and it is the fastest way to lose trust in adaptive behavior
+entirely.
+
+### 9.2 Time-boxed suppression
+
+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
+swallows its own completion notice.
+
+_Why:_ focus modes that suppress until manually cleared strand the person on
+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
+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.
+
+Because presets are local-time, conformance vectors for them are generated under
+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.
+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.
+
+---
+
+## 10. Accessibility requirements
+
+Adaptive interfaces can fail people in ways static ones cannot. These are
+requirements, not suggestions.
+
+1. **Hiding MUST remove from the accessibility tree.** A level-hidden element
+   **MUST NOT** remain focusable or reachable by assistive technology. Visual
+   hiding alone leaves a keyboard trap into content that isn't there.
+2. **Focus MUST survive a level change.** If the focused element is hidden by a
+   transition, focus **MUST** be moved somewhere sensible and **MUST NOT** be
+   left on a removed node.
+3. **Faded chrome MUST reveal on focus, not only on hover.** A control at 10%
+   opacity that a keyboard user can tab into but cannot see fails WCAG 2.4.7.
+   Every hover-reveal rule **MUST** have a `:focus-within` twin.
+4. **Level transitions MUST be announceable.** A person using a screen reader
+   **MUST** have some way to know the interface changed. The host chooses the
+   mechanism; silence is not an option.
+5. **Reduced motion MUST be honored.** Transitions between levels **MUST** be
+   suppressed under `prefers-reduced-motion: reduce`.
+6. **Contrast obligations are the host's and MUST be reachable.** The reference
+   opacity values are a design default, not a conformance claim: at Low and Rest
+   the resting chrome opacity does not meet WCAG 1.4.11 for non-text contrast.
+   An implementation **MUST** make these values overridable and **SHOULD**
+   raise them under `prefers-contrast: more`.
+
+---
+
+## 11. Conformance
+
+An implementation conforms if:
+
+1. It represents state per §3 and serializes per the schema.
+2. It reconciles per §4, including antisymmetry.
+3. It provides at least the required strategies of §5, matching the vectors exactly.
+4. It observes the runtime invariants of §9 for whichever runtimes it provides.
+5. It meets §10 for whichever surfaces it renders.
+
+The vectors are the mechanical part. Load `conformance.json`, replay each
+section against your implementation, and compare. The reference implementation
+does exactly this in `test/conformance.test.ts`, which is a reasonable model for
+a port's own suite.
+
+Vector sections: `levels`, `cycle`, `strategies`, `presence`,
+`decisions.notification`, `decisions.demand`, `deferral`, `reconciliation`,
+`metrics`, `externalLevelMapping`.
+
+### 11.1 Versioning
+
+The vectors carry the reference implementation's version. Within a major
+version, existing vectors **MUST NOT** change meaning; sections and vectors
+**MAY** be added. A change to a shipped table's values is a breaking change to
+this specification, not just to the library.
+
+---
+
+## 12. What is deliberately not specified
+
+- **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
+  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.

package/api-surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0",
+  "version": "1.0.0",
   "entryPoints": [
     {
       "specifier": "@kumbatio/energy-system",
@@ -34,6 +34,7 @@
         "isHigherEnergy",
         "isNotificationPriority",
         "isOriginatorTier",
+        "isPreferredEnergyState",
         "isPresenceVisible",
         "isSessionExpired",
         "isUnproducedState",