@kumbatio/energy-system 0.5.4 → 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

@@ -32,6 +32,10 @@ This library gives applications a structured way to adapt to energy state instea
   - Task complexity guidance
   - Interaction forgiveness (undo windows, destructive-action confirmation)
   - 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
+  silently (`demandAdmissionStrategy`, `resolveDemandOutcome`)
 - **Presence annotation**: declare which energy levels a component/view belongs
   to (`defineEnergyPresence`, `presenceAtOrAbove`, `<EnergyGate>`, `data-energy-min`)
 - **Focus sessions**: time-boxed suppression windows with auto-expiry and break nudges
@@ -254,6 +258,93 @@ const { defaultPresetId, orderedPresetIds } = engine.resolve(deferralStrategy)
 const resurfaceAt = resolveDeferral(presets, defaultPresetId) // epoch ms
 ```
 
+## Inbound demand and autonomy
+
+**Inbound demand** is 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.
+
+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.
+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
+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
+deduplication, belongs to the app.
+
+```ts
+import {
+  autonomyStrategy,
+  deferralStrategy,
+  demandAdmissionStrategy,
+  resolveDemandOutcome,
+} from '@kumbatio/energy-system'
+
+const outcome = resolveDemandOutcome(
+  engine.resolve(demandAdmissionStrategy),
+  engine.resolve(autonomyStrategy),
+  {
+    originatorTier: 'unknown', // 'exempt' | 'known' | 'unknown', assigned by your app
+    bearsObligation: true, // does this ask something of the user?
+    confidence: 0.9, // how sure are you? a deterministic rule reports 1
+  },
+)
+
+switch (outcome.admission) {
+  case 'live':
+    return inbox.deliver(message)
+  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.
+    await tasks.capture(message, engine.resolve(deferralStrategy).defaultPresetId)
+    return replies.acknowledge(message, outcome.acknowledgment)
+  case 'silent':
+    return tasks.capture(message, engine.resolve(deferralStrategy).defaultPresetId)
+}
+```
+
+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 —
+   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:
+auto-replied` header, an "auto-queued" badge, a system-attributed status. An
+automated action toward a third party must be identifiable as automated.
+
+### Autonomy
+
+`autonomyStrategy` is the mirror of `interactionForgivenessStrategy`:
+forgiveness protects against the _user's_ mistakes at low energy, autonomy
+against the _agent's_. It is useful to any consumer with agentic surfaces, with
+or without demand admission.
+
+```ts
+const { confidenceThreshold, allowGeneratedContent, maxUnattendedSteps } =
+  engine.resolve(autonomyStrategy)
+```
+
+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
+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
+worst day is the wrong day for it to get creative.
+
 ## Quick start (DOM)
 
 ```ts
@@ -308,7 +399,8 @@ animating presence changes should do the same.
 - `mapToNearestDiscreteLevel(value, levels, fallback)`
 - `mapToNearestEnergyLevel(value)`
 - Strategies: `uiVisibilityStrategy`, `notificationStrategy`,
-  `taskComplexityStrategy`, `interactionForgivenessStrategy`, `deferralStrategy`
+  `taskComplexityStrategy`, `interactionForgivenessStrategy`, `deferralStrategy`,
+  `autonomyStrategy`, `demandAdmissionStrategy`
 - Presence: `defineEnergyPresence(spec)`, `presenceAtOrAbove(min, below?)`,
   `presenceAtOrBelow(max, above?)`, `resolveEnergyPresence(map, level)`,
   `isPresenceVisible(presence)`, `isEnergyPresence(value)`,
@@ -320,6 +412,8 @@ animating presence changes should do the same.
   `isNotificationPriority(value)`
 - Deferral: `createDeferralPresets(options?)`, `resolveDeferral(presets, id, now?)`,
   `DEFERRAL_PRESET_IDS`
+- Demand admission: `resolveDemandOutcome(config, autonomy, demand)`,
+  `isOriginatorTier(value)`
 - Types: `EnergyLevel`, `EnergyState`, `EnergyPresence`, `EnergyPresenceMap`,
   `AdaptationStrategy`, `FocusSession`, `NotificationDelivery`, etc.
 
@@ -419,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
@@ -442,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, 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).