@kumbatio/energy-system 0.6.0 → 1.0.1

package/spec/conformance.schema.json

@@ -0,0 +1,395 @@
+{
+  "$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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "timezone",
+    "note",
+    "levels",
+    "cycle",
+    "strategies",
+    "presence",
+    "decisions",
+    "deferral",
+    "reconciliation",
+    "metrics",
+    "externalLevelMapping"
+  ],
+  "$defs": {
+    "level": {
+      "description": "The five discrete capacities. Never a continuum.",
+      "type": "integer",
+      "enum": [0, 25, 50, 75, 100]
+    },
+    "presence": {
+      "description": "What a projected element does at a level. `unmounted` is a host/adapter choice rather than a table value, so it does not appear in these vectors.",
+      "type": "string",
+      "enum": ["visible", "muted", "hidden", "unmounted"]
+    },
+    "strategyTable": {
+      "description": "One strategy's resolved config at every level. Keys are strings because JSON object keys are strings, and all five must be present: a gap in a port's table falls through silently at exactly the level it mishandles.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["0", "25", "50", "75", "100"],
+      "properties": {
+        "0": { "type": "object", "minProperties": 1 },
+        "25": { "type": "object", "minProperties": 1 },
+        "50": { "type": "object", "minProperties": 1 },
+        "75": { "type": "object", "minProperties": 1 },
+        "100": { "type": "object", "minProperties": 1 }
+      }
+    },
+    "presenceRow": {
+      "description": "What each level resolves to for one helper threshold.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["0", "25", "50", "75", "100"],
+      "properties": {
+        "0": { "$ref": "#/$defs/presence" },
+        "25": { "$ref": "#/$defs/presence" },
+        "50": { "$ref": "#/$defs/presence" },
+        "75": { "$ref": "#/$defs/presence" },
+        "100": { "$ref": "#/$defs/presence" }
+      }
+    },
+    "presenceTable": {
+      "description": "Keyed by the helper's threshold level, then by the current level.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["0", "25", "50", "75", "100"],
+      "properties": {
+        "0": { "$ref": "#/$defs/presenceRow" },
+        "25": { "$ref": "#/$defs/presenceRow" },
+        "50": { "$ref": "#/$defs/presenceRow" },
+        "75": { "$ref": "#/$defs/presenceRow" },
+        "100": { "$ref": "#/$defs/presenceRow" }
+      }
+    },
+    "instant": {
+      "description": "An epoch-millisecond instant paired with its ISO rendering, so a port can compare either without re-deriving one from the other.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["epochMs", "iso"],
+      "properties": {
+        "epochMs": { "type": "integer", "minimum": 0 },
+        "iso": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+        }
+      }
+    }
+  },
+  "properties": {
+    "$schema": {
+      "description": "Reference to this schema, relative to the package root so it resolves inside the published tarball as well as in the repository.",
+      "type": "string",
+      "const": "./spec/conformance.schema.json"
+    },
+    "version": {
+      "description": "The package version these vectors were generated from. Always equal to api-surface.json's version.",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+"
+    },
+    "timezone": {
+      "description": "The zone the deferral vectors were computed in. The presets are local-time by design, so the vectors only mean anything alongside the zone that produced them.",
+      "const": "UTC"
+    },
+    "note": { "type": "string", "minLength": 1 },
+
+    "levels": {
+      "description": "Level definitions, including the cognitive profile a port must reproduce.",
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["value", "key", "label", "description", "cognitiveProfile"],
+        "properties": {
+          "value": { "$ref": "#/$defs/level" },
+          "key": { "type": "string", "minLength": 1 },
+          "label": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "cognitiveProfile": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "decisionCapacity",
+              "focusDuration",
+              "taskComplexity",
+              "interruptionTolerance"
+            ],
+            "properties": {
+              "decisionCapacity": { "type": "string", "minLength": 1 },
+              "focusDuration": { "type": "string", "minLength": 1 },
+              "taskComplexity": { "type": "string", "minLength": 1 },
+              "interruptionTolerance": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+
+    "cycle": {
+      "description": "100 -> 75 -> 50 -> 25 -> 0 -> 100.",
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to"],
+        "properties": {
+          "from": { "$ref": "#/$defs/level" },
+          "to": { "$ref": "#/$defs/level" }
+        }
+      }
+    },
+
+    "strategies": {
+      "description": "Every built-in strategy's resolved config at every level. Config shapes differ per strategy; their field-level meaning is fixed by SPEC.md and re-asserted by replaying each table through the public API in test/conformance.test.ts.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ui-visibility",
+        "notifications",
+        "task-complexity",
+        "interaction-forgiveness",
+        "deferral",
+        "autonomy",
+        "demand-admission"
+      ],
+      "properties": {
+        "ui-visibility": { "$ref": "#/$defs/strategyTable" },
+        "notifications": { "$ref": "#/$defs/strategyTable" },
+        "task-complexity": { "$ref": "#/$defs/strategyTable" },
+        "interaction-forgiveness": { "$ref": "#/$defs/strategyTable" },
+        "deferral": { "$ref": "#/$defs/strategyTable" },
+        "autonomy": { "$ref": "#/$defs/strategyTable" },
+        "demand-admission": { "$ref": "#/$defs/strategyTable" }
+      }
+    },
+
+    "presence": {
+      "description": "Presence helpers, which are pure maps over the level set.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["atOrAbove", "atOrAboveMuted", "atOrBelow"],
+      "properties": {
+        "atOrAbove": { "$ref": "#/$defs/presenceTable" },
+        "atOrAboveMuted": { "$ref": "#/$defs/presenceTable" },
+        "atOrBelow": { "$ref": "#/$defs/presenceTable" }
+      }
+    },
+
+    "decisions": {
+      "description": "The full decision matrix of both pure gating functions.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["notification", "demand"],
+      "properties": {
+        "notification": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["level", "priority", "suppressed", "outcome"],
+            "properties": {
+              "level": { "$ref": "#/$defs/level" },
+              "priority": { "type": "string", "enum": ["normal", "high", "critical"] },
+              "suppressed": { "type": "boolean" },
+              "outcome": { "type": "string", "enum": ["delivered", "batched", "deferred"] }
+            }
+          }
+        },
+        "demand": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["level", "originatorTier", "bearsObligation", "confidence", "outcome"],
+            "properties": {
+              "level": { "$ref": "#/$defs/level" },
+              "originatorTier": { "type": "string", "enum": ["exempt", "known", "unknown"] },
+              "bearsObligation": { "type": "boolean" },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+              "outcome": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["admission", "acknowledgment", "reason"],
+                "properties": {
+                  "admission": { "type": "string", "enum": ["live", "acknowledge", "silent"] },
+                  "acknowledgment": {
+                    "description": "null when the policy admits or drops without acknowledging.",
+                    "type": ["object", "null"],
+                    "additionalProperties": false,
+                    "required": ["detail", "allowGeneratedContent"],
+                    "properties": {
+                      "detail": { "type": "string", "enum": ["full", "brief", "minimal"] },
+                      "allowGeneratedContent": { "type": "boolean" }
+                    }
+                  },
+                  "reason": {
+                    "type": "string",
+                    "enum": [
+                      "exempt-originator",
+                      "tier-admitted",
+                      "acknowledged",
+                      "no-obligation",
+                      "below-confidence"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "deferral": {
+      "description": "Deferral arithmetic, resolved against fixed reference instants. Local-time by design, hence the `timezone` field above.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["morningHour", "eveningHour", "references"],
+      "properties": {
+        "morningHour": { "type": "integer", "minimum": 0, "maximum": 23 },
+        "eveningHour": { "type": "integer", "minimum": 0, "maximum": 23 },
+        "references": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "iso", "epochMs", "resolved"],
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "iso": {
+                "type": "string",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+              },
+              "epochMs": { "type": "integer", "minimum": 0 },
+              "resolved": {
+                "description": "Every shipped preset, resolved against this reference instant.",
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "in-1-hour",
+                  "this-evening",
+                  "tomorrow-morning",
+                  "next-workday",
+                  "next-monday"
+                ],
+                "properties": {
+                  "in-1-hour": { "$ref": "#/$defs/instant" },
+                  "this-evening": { "$ref": "#/$defs/instant" },
+                  "tomorrow-morning": { "$ref": "#/$defs/instant" },
+                  "next-workday": { "$ref": "#/$defs/instant" },
+                  "next-monday": { "$ref": "#/$defs/instant" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "reconciliation": {
+      "description": "The ordering rule two independent producers converge on. Each pair is stated in both directions: a rule that is not antisymmetric does not converge.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourcePriority", "pairs"],
+      "properties": {
+        "sourcePriority": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["manual", "scheduled", "inferred"],
+          "properties": {
+            "manual": { "const": 3 },
+            "scheduled": { "const": 2 },
+            "inferred": { "const": 1 }
+          }
+        },
+        "pairs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["rule", "candidate", "current", "expected", "expectedReversed"],
+            "properties": {
+              "rule": { "type": "string", "minLength": 1 },
+              "candidate": { "$ref": "https://kumbat.io/spec/energy-state.schema.json" },
+              "current": { "$ref": "https://kumbat.io/spec/energy-state.schema.json" },
+              "expected": { "type": "boolean" },
+              "expectedReversed": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+
+    "metrics": {
+      "description": "Derived metrics at a fixed state age, so a port checks its arithmetic rather than its clock.",
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["level", "stateTimestamp", "now", "metrics"],
+        "properties": {
+          "level": { "$ref": "#/$defs/level" },
+          "stateTimestamp": { "type": "integer", "minimum": 0 },
+          "now": { "type": "integer", "minimum": 0 },
+          "metrics": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "stateAgeMs",
+              "stateAgeMinutes",
+              "expectedProductivityWindowMinutes",
+              "suggestedBreakIntervalMinutes",
+              "recommendedTaskComplexity",
+              "sustainable"
+            ],
+            "properties": {
+              "stateAgeMs": { "type": "integer", "minimum": 0 },
+              "stateAgeMinutes": { "type": "integer", "minimum": 0 },
+              "expectedProductivityWindowMinutes": { "type": "integer", "minimum": 0 },
+              "suggestedBreakIntervalMinutes": { "type": "integer", "minimum": 0 },
+              "recommendedTaskComplexity": { "type": "string", "minLength": 1 },
+              "sustainable": { "type": "boolean" },
+              "recoveryHintMinutes": {
+                "description": "Present only at the levels that have a recovery hint (50 and below); absent, not null, where there is nothing to suggest.",
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "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.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["input", "level"],
+        "properties": {
+          "input": { "type": "number" },
+          "level": { "$ref": "#/$defs/level" }
+        }
+      }
+    }
+  }
+}

package/spec/energy-state.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kumbat.io/spec/energy-state.schema.json",
+  "title": "EnergyState",
+  "description": "One producer's point-in-time claim about a person's cognitive capacity. This is the interchange format: the shape an implementation writes to shared storage, sends over a wire, or hands to another process. Two implementations that agree on this schema and on the reconciliation rule in SPEC.md converge on the same current state without further coordination.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["level", "timestamp", "source", "revision", "origin"],
+  "properties": {
+    "level": {
+      "description": "The declared capacity. Five discrete values, never a continuum: a slider invites precision nobody has about their own state, and five is the most a depleted person should have to choose between.",
+      "type": "integer",
+      "enum": [0, 25, 50, 75, 100]
+    },
+    "timestamp": {
+      "description": "When this state was produced, in milliseconds since the Unix epoch. The primary ordering key. 0 is reserved for the unproduced sentinel (see SPEC.md).",
+      "type": "integer",
+      "minimum": 0
+    },
+    "source": {
+      "description": "How the level was arrived at. Load-bearing during reconciliation: manual outranks scheduled outranks inferred, so nothing the system worked out on its own overwrites what the person said.",
+      "type": "string",
+      "enum": ["manual", "scheduled", "inferred"]
+    },
+    "revision": {
+      "description": "Logical sequence number among states sharing one timestamp. Two writes inside a clock tick are not simultaneous, and this is what keeps them ordered.",
+      "type": "integer",
+      "minimum": 0,
+      "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.",
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "examples": [
+    {
+      "level": 50,
+      "timestamp": 1786060800000,
+      "source": "manual",
+      "revision": 0,
+      "origin": "a4f1c2e8-0f3b-4a91-9f2d-6c1b2e5d8a70"
+    },
+    {
+      "level": 100,
+      "timestamp": 0,
+      "source": "manual",
+      "revision": 0,
+      "origin": "0-initial"
+    }
+  ]
+}

package/src/energy.css

@@ -18,6 +18,10 @@
  * applyEnergyLevel() sets the same properties as inline styles, which take
  * precedence but resolve to identical values, so the JS and CSS-only paths
  * always agree.
+ *
+ * The single exception is the accessibility block at the end of this file, which
+ * declares `!important` deliberately so a user's contrast preference outranks
+ * both paths. See the comment there.
  */
 
 /* ── Custom properties per level (mirror of uiVisibilityStrategy) ── */
@@ -129,6 +133,8 @@
   opacity: var(--energy-chrome-opacity-hover, 0.8);
 }
 
+/* `font-size` scales relative to the parent, so this expects ONE .energy-content
+ * per tree. Nesting them compounds the scale (1.1 inside 1.1 is 1.21). */
 [data-energy-level='0'] .energy-content {
   max-width: var(--energy-content-max-width, 75ch);
   margin-inline: auto;
@@ -138,6 +144,10 @@
   cursor: default !important;
 }
 
+/* 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
+ * all and a pointer user gets a signal that turns out to be false. */
 [data-energy-level='0'] .energy-content * {
   cursor: default !important;
 }
@@ -202,3 +212,70 @@
     transition: none;
   }
 }
+
+/* ── Contrast obligations ──
+ *
+ * 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
+ * every value here is a custom property an app can raise in one line.
+ *
+ * Two populations must not be left to do that themselves:
+ *
+ * `prefers-contrast: more` is a person explicitly asking the OS for more
+ * contrast. Fading their chrome to 5% is answering the opposite of the question.
+ * Chrome still recedes with energy, but never below a legible floor.
+ *
+ * `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
+ * 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
+ * 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
+ * a value the program computed. */
+@media (prefers-contrast: more) {
+  [data-energy-level='75'] {
+    --energy-chrome-opacity: 0.9 !important;
+  }
+
+  [data-energy-level='50'] {
+    --energy-chrome-opacity: 0.8 !important;
+  }
+
+  [data-energy-level='25'] {
+    --energy-chrome-opacity: 0.7 !important;
+  }
+
+  [data-energy-level='0'] {
+    --energy-chrome-opacity: 0.7 !important;
+    --energy-chrome-opacity-hover: 1 !important;
+  }
+
+  [data-energy-level] {
+    --energy-muted-opacity: 0.85 !important;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-energy-level] {
+    --energy-chrome-opacity: 1 !important;
+    --energy-chrome-opacity-hover: 1 !important;
+    --energy-muted-opacity: 1 !important;
+  }
+
+  [data-energy-level] .energy-chrome {
+    opacity: 1 !important;
+  }
+
+  /* `hidden` presence stays hidden: it is display, not contrast, and the
+   * element is meant to be absent from the tree at this level. */
+  [data-energy-presence='muted'] {
+    opacity: 1 !important;
+  }
+}