@goodbones/core 0.1.0-beta.12 → 0.1.0-beta.13

package/schema/conformance.schema.json

@@ -776,11 +776,68 @@
                 },
                 "complete": {
                   "type": "boolean",
-                  "description": "No holdouts remain."
+                  "description": "No holdouts remain; for a scalar objective, every sector is at its target."
                 },
                 "ledgered": {
                   "type": "boolean",
                   "description": "Whether a ledger exists. An objective with none has been declared and not yet cleared."
+                },
+                "measure": {
+                  "type": "object",
+                  "properties": {
+                    "direction": {
+                      "type": "string",
+                      "enum": [
+                        "down",
+                        "up"
+                      ],
+                      "description": "Which way is better."
+                    },
+                    "value": {
+                      "type": "number",
+                      "allOf": [
+                        {
+                          "description": "The number measured now, every sector in window summed."
+                        }
+                      ]
+                    },
+                    "recorded": {
+                      "type": "number",
+                      "allOf": [
+                        {
+                          "description": "The number the ledger holds the sectors to, summed: the best `objectives clear` has written, plus conceded rises."
+                        }
+                      ]
+                    },
+                    "target": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The value at which the objective is met, or `null` for a standing measure that only ratchets."
+                    },
+                    "tolerance": {
+                      "type": "number",
+                      "allOf": [
+                        {
+                          "description": "How far either side of the record still counts as at it."
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "direction",
+                    "value",
+                    "recorded",
+                    "target",
+                    "tolerance"
+                  ],
+                  "additionalProperties": false,
+                  "description": "For a scalar objective: the number, where the holdout counts above are all 0."
                 }
               },
               "required": [
@@ -876,7 +933,7 @@
                   "additionalProperties": {
                     "type": "number"
                   },
-                  "description": "One dimension per objective in window for the sector: its holdouts there, never summed."
+                  "description": "One dimension per objective in window for the sector: its holdouts there, or a scalar's distance to its target, never summed."
                 },
                 "stalled": {
                   "type": "boolean",
@@ -961,7 +1018,7 @@
           },
           "complete": {
             "type": "boolean",
-            "description": "No holdouts remain in any objective."
+            "description": "No holdouts remain in any objective, and every scalar with a target has reached it."
           },
           "onComplete": {
             "type": "string",

package/src/core/bound.ts

@@ -0,0 +1,33 @@
+// A number held to a limit from one side: a coverage floor (`up`, the value
+// may not fall under it), a conformance ceiling (`down`, it may not rise over
+// it), or a campaign's scalar objective, whose limit is the value its ledger
+// last recorded. One comparison for all three, so "coverage ≥ N" has one
+// meaning whether the manifest owns the number or a ledger does.
+
+export type BoundDirection = "down" | "up";
+
+export type Bound = {
+  // Which way is better: `down` for a ceiling, `up` for a floor.
+  readonly direction: BoundDirection;
+  readonly limit: number;
+  // How far past the limit, either way, still counts as at it.
+  readonly tolerance: number;
+};
+
+// `breached`: worse than the limit by more than the tolerance. `surpassed`:
+// better by more than it. `within`: neither.
+export type Standing = "within" | "breached" | "surpassed";
+
+// How much worse than the limit the value is — negative when better.
+export const shortfallOf = (bound: Bound, value: number): number =>
+  bound.direction === "down" ? value - bound.limit : bound.limit - value;
+
+export const standingOf = (bound: Bound, value: number): Standing => {
+  const worse = shortfallOf(bound, value);
+  if (worse > bound.tolerance) return "breached";
+  if (-worse > bound.tolerance) return "surpassed";
+  return "within";
+};
+
+export const breaches = (bound: Bound, value: number): boolean =>
+  standingOf(bound, value) === "breached";

package/src/core/coverage.ts

@@ -1,4 +1,5 @@
 import { OPEN_LAYOUT } from "../domain/architecture-config.js";
+import { breaches } from "./bound.js";
 import type { CompiledGraph } from "./graph.js";
 import type { CompiledImportRule } from "./imports.js";
 import type { CompiledMemberRule } from "./members.js";
@@ -278,7 +279,8 @@ export const coverageShortfalls = (
   ];
   return families.flatMap((family) => {
     const floor = floors[family];
-    if (floor === undefined || actual[family] >= floor) return [];
+    if (floor === undefined) return [];
+    if (!breaches({ direction: "up", limit: floor, tolerance: 0 }, actual[family])) return [];
     return [{ family, actual: actual[family], floor }];
   });
 };

package/src/domain/snapshot.ts

@@ -172,11 +172,35 @@ export const SnapshotObjective = Schema.Struct({
     "When a holdout last left the ledger, ISO 8601 — the stall clock's reading; `null` with no ledger.",
   ),
   concessions: describe(Schema.Finite, "How many times a count was allowed to go up."),
-  complete: describe(Schema.Boolean, "No holdouts remain."),
+  complete: describe(
+    Schema.Boolean,
+    "No holdouts remain; for a scalar objective, every sector is at its target.",
+  ),
   ledgered: describe(
     Schema.Boolean,
     "Whether a ledger exists. An objective with none has been declared and not yet cleared.",
   ),
+  measure: Schema.optionalKey(
+    describe(
+      Schema.Struct({
+        direction: describe(Schema.Literals(["down", "up"]), "Which way is better."),
+        value: describe(Schema.Finite, "The number measured now, every sector in window summed."),
+        recorded: describe(
+          Schema.Finite,
+          "The number the ledger holds the sectors to, summed: the best `objectives clear` has written, plus conceded rises.",
+        ),
+        target: describe(
+          Schema.NullOr(Schema.Finite),
+          "The value at which the objective is met, or `null` for a standing measure that only ratchets.",
+        ),
+        tolerance: describe(
+          Schema.Finite,
+          "How far either side of the record still counts as at it.",
+        ),
+      }),
+      "For a scalar objective: the number, where the holdout counts above are all 0.",
+    ),
+  ),
 });
 
 // One phase of the ladder, and how many sectors stand at it.
@@ -203,7 +227,7 @@ export const SnapshotSector = Schema.Struct({
   files: describe(Schema.Finite, "How many files the sector claims."),
   residue: describe(
     Schema.Record(Schema.String, Schema.Finite),
-    "One dimension per objective in window for the sector: its holdouts there, never summed.",
+    "One dimension per objective in window for the sector: its holdouts there, or a scalar's distance to its target, never summed.",
   ),
   stalled: describe(
     Schema.Boolean,
@@ -261,7 +285,10 @@ export const SnapshotCampaign = Schema.Struct({
     Schema.Boolean,
     "Holdouts remain and nothing has been cleared, attested or noted within the campaign's `staleAfter`.",
   ),
-  complete: describe(Schema.Boolean, "No holdouts remain in any objective."),
+  complete: describe(
+    Schema.Boolean,
+    "No holdouts remain in any objective, and every scalar with a target has reached it.",
+  ),
   onComplete: describe(
     Schema.Literals(["keep", "remove"]),
     "What the manifest asks once complete: keep the campaign as a guard, or remove it.",

package/src/index.ts

@@ -23,6 +23,14 @@ export {
   staleEntriesOf,
   unbaselined,
 } from "./core/baseline.js";
+export {
+  type Bound,
+  type BoundDirection,
+  breaches,
+  shortfallOf,
+  type Standing,
+  standingOf,
+} from "./core/bound.js";
 export {
   type Coverage,
   type CoverageFamily,