@blamejs/core 0.18.43 → 0.18.44

package/lib/time.js

@@ -34,8 +34,15 @@
  */
 var C = require("./constants");
 var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
+// Lazy: the drift report is the only thing that needs it, and loading the
+// observability stack at require-time would pull it into every consumer of a
+// date formatter.
+var observability = lazyRequire(function () { return require("./observability"); });
+
 var TimeError = defineClass("TimeError", { alwaysPermanent: true });
 
 var DEFAULT_TIMEZONE = "UTC";
@@ -821,6 +828,279 @@ function stripIsoMilliseconds(text) {
   return text.slice(0, at) + "Z";
 }
 
+// ---------------------------------------------------------------------------
+// Monotonic wall clock.
+// ---------------------------------------------------------------------------
+
+// How far ahead of the underlying source a clock may run before it says so.
+// One second buys a thousand stamps inside a single millisecond — well past
+// any realistic write burst — while keeping a recorded timestamp close enough
+// to true time that an auditor reading it is not misled.
+var DEFAULT_MAX_DRIFT_MS = C.TIME.seconds(1);
+
+/**
+ * @primitive b.time.monotonicClock
+ * @signature b.time.monotonicClock(opts?)
+ * @since     0.18.44
+ * @status    stable
+ * @related   b.time.monotonicNow, b.chainWriter.create, b.ntpCheck.checkDrift
+ *
+ * An isolated clock whose `now()` never returns a value less than or equal to
+ * the one before it.
+ *
+ * `Date.now()` gives neither guarantee. It repeats when two writes land in the
+ * same millisecond, and it moves BACKWARDS when NTP steps the clock — the
+ * correction `b.ntpCheck` exists to detect. Anything that orders records by a
+ * timestamp inherits both problems: an append-only chain gets a row that
+ * appears to precede its predecessor, and keyset pagination over a timestamp
+ * column drops or repeats rows that share a millisecond.
+ *
+ * Three things the four-line hand-rolled version leaves out, and this settles:
+ *
+ * - **An injectable source.** `opts.source` defaults to `Date.now` but a test
+ *   can hand over a scripted one, which a closure over `Date.now` cannot. It
+ *   must return a SAFE-INTEGER count of milliseconds. A fractional clock such
+ *   as `performance.timeOrigin + performance.now()` is refused rather than
+ *   rounded: this primitive's whole promise is that the next value exceeds the
+ *   last, and it keeps that promise by handing out `last + 1` when the source
+ *   has not moved — arithmetic that needs an integer to stay exact.
+ * - **A floor that survives a restart.** Process memory resets to zero on
+ *   restart or failover — precisely when a fresh node is syncing NTP and a
+ *   backwards step is most likely. `observeFloor(ms)` seeds the guarantee from
+ *   a value read back out of storage, and ignores anything below where the
+ *   clock already is. It takes a NUMBER and refuses anything else, including
+ *   the decimal string a Postgres `BIGINT` arrives as through most drivers:
+ *   coercing a floor silently would accept `"abc"` as `NaN` and every later
+ *   comparison against it as false, so the conversion is the caller's to make
+ *   and to get wrong loudly.
+ * - **A ceiling on how far ahead of the source it may run.** A burst inside
+ *   one millisecond walks the returned value into the future. Unbounded, that
+ *   is a silently wrong timestamp; `maxDriftMs` is what makes it not silent.
+ *
+ * Passing the cap REPORTS — through `onDrift` when given, otherwise as the
+ * `time.monotonic.drift_exceeded` observability event — and keeps returning
+ * monotonic values. For the framework's own consumer, an append-only audit
+ * chain, a timestamp a few milliseconds optimistic is a smaller harm than a
+ * dropped row, and a dropped row is what an attacker who can step the clock
+ * would be aiming for. A caller whose property is timestamp ACCURACY rather
+ * than completeness asks for `strict: true` and gets a
+ * `time/monotonic-drift-cap` throw instead.
+ *
+ * The report never goes through `b.audit`: a clock that stamps audit rows and
+ * audits its own drift would call itself.
+ *
+ * @opts
+ *   source:     function,   // default: Date.now — must return a SAFE-INTEGER number of ms
+ *   maxDriftMs: number,     // default: 1000 — lead over the source before it reports
+ *   onDrift:    function,   // ({ driftMs, maxDriftMs, value, sourceMs, label }) — replaces the observability event
+ *   strict:     boolean,    // default: false — true throws instead of reporting
+ *   label:      string,     // default: "default" — names this clock in drift reports
+ *
+ * @example
+ *   var clock = b.time.monotonicClock({ label: "device_event_log" });
+ *   // Number(...) is not decoration: a Postgres BIGINT arrives as a decimal
+ *   // STRING through most drivers, and observeFloor refuses one rather than
+ *   // coercing it — a floor is too important to guess at.
+ *   clock.observeFloor(Number(tipRow.recordedAt));   // durable, read from storage
+ *   var recordedAt = clock.now();
+ *   // → strictly greater than tipRow.recordedAt, whatever the wall clock did
+ */
+function monotonicClock(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["source", "maxDriftMs", "onDrift", "strict", "label"],
+    "b.time.monotonicClock");
+
+  validateOpts.shape(opts, {
+    source:     { rule: "optional-function",     code: "time/bad-source" },
+    maxDriftMs: { rule: "optional-non-negative", code: "time/bad-max-drift" },
+    onDrift:    { rule: "optional-function",     code: "time/bad-on-drift" },
+    strict:     { rule: "optional-boolean",      code: "time/bad-strict" },
+    label:      { rule: "optional-string",       code: "time/bad-label" },
+  }, "b.time.monotonicClock", TimeError, "time/bad-opts");
+
+  var source     = opts.source == null ? Date.now : opts.source;
+  var maxDriftMs = opts.maxDriftMs == null ? DEFAULT_MAX_DRIFT_MS : opts.maxDriftMs;
+  var onDrift    = opts.onDrift == null ? null : opts.onDrift;
+  var strict     = opts.strict === true;
+  var label      = opts.label == null ? "default" : opts.label;
+
+  var last = 0;
+  var lastSourceMs = 0;
+  var reporting = false;
+
+  function _report(info) {
+    // A reporter that calls now() re-enters here, and the re-entrant call drifts
+    // by construction - it is one millisecond further ahead than the call that
+    // triggered the report. Reporting that would recurse until the stack ran
+    // out, so the outermost report is the one that speaks for the burst.
+    if (reporting) return;
+    reporting = true;
+    try { _reportOnce(info); } finally { reporting = false; }
+  }
+
+  function _reportOnce(info) {
+    if (onDrift) {
+      // The caller's reporter is theirs to get wrong; a throw from it must not
+      // decide whether the timestamp was issued.
+      try { onDrift(info); } catch (_e) { /* drop-silent — see the block comment above */ }
+      return;
+    }
+    // Never b.audit: an audit row needs a timestamp, which needs this clock.
+    try {
+      observability().safeEvent("time.monotonic.drift_exceeded", info.driftMs, {
+        clock: info.label,
+      });
+    } catch (_e) { /* drop-silent — an observability failure must not stop the clock */ }
+  }
+
+  function now() {
+    // A drift report runs caller code in the middle of issuing a value. A
+    // reporter that asks this same clock for another one gets a HIGHER value
+    // and returns it BEFORE the call that triggered the report returns its
+    // lower one - so a callback that stamps its own log line records the drift
+    // at a later instant than the event it describes, which is time running
+    // backwards in the record this clock exists to keep straight.
+    //
+    // Refusing is the honest answer, and it costs the reporter nothing: the
+    // value being reported on is already in `info.value`. The throw is caught
+    // by _report's drop-silent wrapper, so it cannot fail the append that
+    // triggered the report. A DIFFERENT clock is unaffected - this is per
+    // instance, not a global lock.
+    if (reporting) {
+      throw new TimeError("time/monotonic-reentrant",
+        "b.time.monotonicClock(" + label + "): now() was called from this " +
+        "clock's own drift report. The value being reported on is in " +
+        "info.value; asking for a new one here would return a later " +
+        "timestamp than the event it describes.");
+    }
+    var t = source();
+    // Number.isSafeInteger, not isFinite: past 2^53 the value has ALREADY been
+    // rounded before it arrives, and `last + 1` stops increasing there - the
+    // addition saturates, two calls return the same number, and the one
+    // guarantee this primitive makes fails silently. Refuse instead.
+    if (typeof t !== "number" || !Number.isSafeInteger(t)) {
+      throw new TimeError("time/monotonic-bad-source",
+        "b.time.monotonicClock: the clock source returned " +
+        (typeof t === "number" ? String(t) : typeof t) +
+        " rather than a safe integer number of epoch milliseconds");
+    }
+    lastSourceMs = t;
+    var value = t > last ? t : last + 1;
+    // The invariant, checked rather than assumed. Reachable only at the
+    // safe-integer ceiling, which the input screens above already refuse - so
+    // this is the backstop that cannot be bypassed by a future caller finding
+    // another way to raise the floor.
+    if (!(value > last) || !Number.isSafeInteger(value)) {
+      throw new TimeError("time/monotonic-exhausted",
+        "b.time.monotonicClock(" + label + "): the next monotonic value would " +
+        "not exceed the last (" + last + "), so the guarantee cannot be kept. " +
+        "The clock has reached the safe-integer ceiling; a floor read from " +
+        "storage is the only way to get here.");
+    }
+    var driftMs = value - t;
+    if (driftMs > maxDriftMs) {
+      var info = {
+        driftMs: driftMs, maxDriftMs: maxDriftMs,
+        value: value, sourceMs: t, label: label,
+      };
+      if (strict) {
+        // Throw BEFORE advancing, so a caller that never received the value
+        // cannot have it walk the floor further out of reach on every retry.
+        throw new TimeError("time/monotonic-drift-cap",
+          "b.time.monotonicClock(" + label + "): the monotonic value is " + driftMs +
+          "ms ahead of the clock source, past the " + maxDriftMs + "ms cap. Either the " +
+          "write rate exceeds one row per millisecond or the system clock stepped " +
+          "backwards; b.ntpCheck.checkDrift() distinguishes them.");
+      }
+      // Advance BEFORE the reporter runs. _report hands control to caller code,
+      // and a reporter that calls now() re-enters this function; if the floor
+      // had not moved yet the re-entrant call would compute the SAME value from
+      // the same `last` and two callers would hold one timestamp - exactly the
+      // collision this clock exists to prevent. The strict throw above still
+      // precedes the advance, because there the value is never issued at all.
+      last = value;
+      _report(info);
+      return value;
+    }
+    last = value;
+    return value;
+  }
+
+  // Raise the floor to a value read back out of storage. Lower values are
+  // ignored rather than refused: a stale replica or an out-of-order read must
+  // not be able to rewind a clock that has already moved past it.
+  function observeFloor(ms) {
+    // A safe integer, not merely finite. This value comes from STORAGE - the
+    // chain writer seeds it from a persisted recordedAt column - so it is the
+    // one input a caller does not compose themselves, and a value past 2^53
+    // would push the clock to a ceiling where `last + 1` saturates and the
+    // monotonic guarantee quietly stops holding.
+    if (typeof ms !== "number" || !Number.isSafeInteger(ms)) {
+      throw new TimeError("time/bad-floor",
+        "b.time.monotonicClock.observeFloor: expected a safe-integer number of " +
+        "epoch milliseconds; got " + (typeof ms === "number" ? String(ms) : typeof ms));
+    }
+    if (ms < 0) {
+      throw new TimeError("time/bad-floor",
+        "b.time.monotonicClock.observeFloor: a floor cannot be negative; got " + ms);
+    }
+    // MAX_SAFE_INTEGER is itself a safe integer, so the check above admits it -
+    // and a clock sitting exactly there has no next value: MAX + 1 is not
+    // representable and rounds back to MAX. Refuse the boundary too, so the
+    // guarantee never depends on there being one more tick available.
+    if (ms >= Number.MAX_SAFE_INTEGER) {
+      throw new TimeError("time/bad-floor",
+        "b.time.monotonicClock.observeFloor: a floor at or past " +
+        "Number.MAX_SAFE_INTEGER leaves no representable next value, so the " +
+        "monotonic guarantee could not be kept; got " + ms);
+    }
+    if (ms > last) last = ms;
+    return last;
+  }
+
+  return {
+    now:          now,
+    observeFloor: observeFloor,
+    lastValue:    function () { return last; },
+    driftMs:      function () { return last > lastSourceMs ? last - lastSourceMs : 0; },
+    label:        label,
+  };
+}
+
+var _sharedMonotonic = monotonicClock({ label: "shared" });
+
+/**
+ * @primitive b.time.monotonicNow
+ * @signature b.time.monotonicNow()
+ * @since     0.18.44
+ * @status    stable
+ * @related   b.time.monotonicClock
+ *
+ * The process-wide monotonic clock: epoch milliseconds that never repeat and
+ * never move backwards, whatever `Date.now()` does. The shape most callers
+ * want — one shared sequence, so two unrelated call sites in the same process
+ * cannot mint the same value.
+ *
+ * Takes no arguments. A caller who needs an injectable source, a durable
+ * floor, a different drift cap, or a sequence isolated from everyone else's
+ * builds their own with `b.time.monotonicClock`; configuring a shared clock
+ * from one call site would silently change every other site's behaviour.
+ *
+ * @example
+ *   var a = b.time.monotonicNow();
+ *   var b2 = b.time.monotonicNow();
+ *   // → b2 > a, even inside the same millisecond
+ */
+function monotonicNow() {
+  if (arguments.length > 0) {
+    throw new TimeError("time/monotonic-now-takes-no-opts",
+      "b.time.monotonicNow() takes no arguments — it is one shared sequence, and " +
+      "configuring it from one call site would change every other. Use " +
+      "b.time.monotonicClock(opts) for a clock of your own.");
+  }
+  return _sharedMonotonic.now();
+}
+
 module.exports = {
   toParts:      toParts,
   format:       format,
@@ -836,5 +1116,7 @@ module.exports = {
   readDateTime: readDateTime,
   toIso8601NoMs: toIso8601NoMs,
   stripIsoMilliseconds: stripIsoMilliseconds,
+  monotonicClock: monotonicClock,
+  monotonicNow:   monotonicNow,
   TimeError:    TimeError,
 };

package/lib/vendor/MANIFEST.json

@@ -21,7 +21,7 @@
         "server": "sha256:f3325f480cb8eb814fcb0baaa19336cbbf2b993f48624c6aa9600ffd69d0be5e",
         "browser": "sha256:0ffd91540bcb586a29b56e52ee1c29df69097b50776beb4036a07558f7a4e12e"
       },
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     },
     "@noble/hashes": {
       "version": "2.3.0",
@@ -48,7 +48,7 @@
       "hashes": {
         "browser": "sha256:dfe4b7ae3c9880e388c8da4b68f44742b229b53afacd1e674179527e33da62b0"
       },
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     },
     "@noble/curves": {
       "version": "2.3.0",
@@ -70,7 +70,7 @@
       "hashes": {
         "server": "sha256:b5fe88d1ea780d0581dee6145d666f89d46fc9531b5db35db2e5b16627840890"
       },
-      "refreshedAt": "2026-08-20T15:14:48.311Z",
+      "refreshedAt": "2026-08-21T09:57:09.089Z",
       "components": {
         "@noble/hashes": {
           "url": "https://github.com/paulmillr/noble-hashes",
@@ -114,7 +114,7 @@
         "server": "sha256:fab7ebe5737793862c473444f4ee5912f79dd1edec86683acbb4eecbca0f5892",
         "browser": "sha256:cae1d5bbdc7184b202b6ca68df6e1db7b0d0f668c77809ded189ca7f271accc9"
       },
-      "refreshedAt": "2026-08-20T15:14:48.311Z",
+      "refreshedAt": "2026-08-21T09:57:09.089Z",
       "components": {
         "@noble/hashes": {
           "url": "https://github.com/paulmillr/noble-hashes",
@@ -148,7 +148,7 @@
       },
       "runtime_artifact": "lib/vendor/common-passwords-top-10000.data.js",
       "integrity_layers": "sha256 + sha3-512 + SLH-DSA-SHAKE-256f signature + in-payload canary (where applicable)",
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     },
     "bimi-trust-anchors": {
       "version": "operator-managed",
@@ -173,7 +173,7 @@
       },
       "runtime_artifact": "lib/vendor/bimi-trust-anchors.data.js",
       "integrity_layers": "sha256 + sha3-512 + SLH-DSA-SHAKE-256f signature + in-payload canary (where applicable)",
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     },
     "publicsuffix-list": {
       "version": "master",
@@ -193,10 +193,10 @@
       },
       "runtime_artifact": "lib/vendor/public-suffix-list.data.js",
       "integrity_layers": "sha256 + sha3-512 + SLH-DSA-SHAKE-256f signature + in-payload canary (where applicable)",
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     },
     "@blamejs/pki": {
-      "version": "0.5.17",
+      "version": "0.5.23",
       "license": "Apache-2.0",
       "author": "blamejs",
       "source": "https://github.com/blamejs/pki",
@@ -216,12 +216,12 @@
         "server": "lib/vendor/blamejs-pki.cjs"
       },
       "bundler": "esbuild --format=cjs --platform=node --external:crypto --external:node:crypto",
-      "bundledAt": "2026-08-20T00:00:00Z",
-      "cpe": "cpe:2.3:a:blamejs:pki:0.5.17:*:*:*:*:node.js:*:*",
+      "bundledAt": "2026-08-21T00:00:00Z",
+      "cpe": "cpe:2.3:a:blamejs:pki:0.5.23:*:*:*:*:node.js:*:*",
       "hashes": {
-        "server": "sha256:dbedb80e1725747a24fdbd3dec9fcab31b507ac048b923462382b6ac117937a0"
+        "server": "sha256:3e365ca7e4cd0a7d80b20690cb8901c31d1a9e841d95f73674f97e011466f7ed"
       },
-      "refreshedAt": "2026-08-20T15:14:48.311Z"
+      "refreshedAt": "2026-08-21T09:57:09.089Z"
     }
   }
 }