@ultimat3/flags 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -102,11 +102,17 @@ what lets `policy` (tier 2) call it from inside a predicate.
   alone honoured the PROCESS's zone for a clock-time form: `'2026-12-01T00:00:00'` measured as
   1796083200000 in UTC, 1796101200000 in America/New_York and 1796050800000 in Asia/Tokyo — fourteen
   hours of spread across a fleet, so `X_FLAG_EXPIRED` started on a different DAY on different pods,
-  against a comment claiming the opposite. `flag.ts` carries a local `CLOCK_TIME`/`UTC_OFFSET` pair
-  mirroring `@ultimat3/time`'s `fromIso`, restated rather than imported because this package is tier
-  1 and may import `@ultimat3/core` only. `scripts/test-setup.ts` pins the runner to UTC, so the
+  against a comment claiming the opposite. `flag.ts` asks `@ultimat3/core`'s `isIsoDateTime` — the
+  one predicate `t.date` and `fromIso` ask — `As of 2026-10`. It carried a local
+  `CLOCK_TIME`/`UTC_OFFSET` pair until then, two of the predicate's three patterns: with no SHAPE
+  check, `'December 1, 2026'` and `'12/01/2026'` parsed at the host's local midnight and
+  `'2026-02-30'` rolled over to March 2nd. All are `X_FLAG_EXPIRY_INVALID` now. **Breaking.**
+  `scripts/test-setup.ts` pins the runner to UTC, so the
   failure is invisible in process by construction and `flag.test.ts` spawns a `TZ=` subprocess per
   zone — the same reason `packages/time/src/plain-date.test.ts` does.
+- **`configureFlags` screens `reportEveryMs` with `finiteCount`, before it touches anything.**
+  `now - previous < NaN` is false, so a `NaN` interval reported on every evaluation; `Infinity`
+  muted the flag for good. `0` is legal — a caller may choose it.
 - **`configureFlags` clears the report watermarks when it swaps the clock, and only then.** A
   monotonic reading is meaningful only against the clock that produced it: a process that reported
   at monotonic 10,000,000 and then took a clock starting at 0 computed `now - previous` as

package/README.md

@@ -15,6 +15,10 @@ permanent set is a product surface; the temporary set is forced to shrink.
 | `permanent` | a real product or ops switch — a plan capability, a kill switch, a rollout that became the product | none; it legitimately lives forever |
 | `temporary` | scaffolding around an in-progress change | `expiresAt` and `owner` are **required**; past the expiry every evaluation reports `X_FLAG_EXPIRED` |
 
+`expiresAt` is ISO-8601 — a date (`2026-12-01`, UTC) or a date-time with `Z` or an offset, naming
+a day its month has. `'December 1, 2026'`, `'12/01/2026'`, `'2026-02-30'` and a clock time with no
+zone are `X_FLAG_EXPIRY_INVALID`: each parses, at an instant that depends on the host.
+
 Omitting `expiresAt` on a `temporary` flag is a **type** error, not a lint rule —
 `FlagExpiryIsMandatory` in `src/flag.ts` is a compile-time assertion that fails `tsc` if the union
 is ever loosened. `toFlag()` re-checks it at runtime, because a store snapshot and a plain-JS
@@ -157,7 +161,9 @@ configureErrorReporting({ reporter: sentryErrorReporter({ dsn }) });
 What this package adds is the rate limit core has no opinion about: one report per flag per
 `DEFAULT_REPORT_INTERVAL_MS` (1 hour), on the **monotonic** clock, so a flag read on every request
 does not become the loudest thing in the monitor — which is how a report that fires per call ends
-up muted and the debt invisible again. `configureFlags({ clock, reportEveryMs })` tunes it.
+up muted and the debt invisible again. `configureFlags({ clock, reportEveryMs })` tunes it;
+`reportEveryMs` is a whole number of milliseconds, 0 or more — `NaN`, `Infinity`, a fraction or a
+negative is refused (`X_INVARIANT`) and changes nothing.
 
 ## Projection
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/flags",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0"
+    "@ultimat3/core": "25.0.0"
   }
 }

package/src/bucket.ts

@@ -3,31 +3,19 @@
 // a rollout that re-rolls per call shows one user the new experience on one request and the old
 // one on the next, which is a worse product than no rollout at all — and untestable besides.
 
+import { fnv1a } from '@ultimat3/core';
+
 /** A rollout is declared as a percentage, so the bucket space is 100. */
 export const BUCKETS = 100;
 
-const FNV_OFFSET_BASIS = 0x811c_9dc5;
-const FNV_PRIME = 0x0100_0193;
-
-/**
- * 32-bit FNV-1a. Chosen over a cryptographic digest because bucketing is not a security decision
- * and this one is synchronous, dependency-free and identical in every process — which is the
- * property that matters: two nodes must agree about one actor without talking to each other.
- */
-export function fnv1a(text: string): number {
-  let hash = FNV_OFFSET_BASIS;
-  for (let index = 0; index < text.length; index += 1) {
-    hash ^= text.charCodeAt(index);
-    hash = Math.imul(hash, FNV_PRIME);
-  }
-  return hash >>> 0;
-}
-
 /**
  * The flag key is hashed WITH the subject id, not the subject id alone: hashing the subject by
  * itself would put the same unlucky cohort in the first 10% of every 10% rollout the app ever
  * runs, so one group of users — or one group of tenants — would meet every half-finished feature.
  *
+ * The hash is core's 32-bit FNV-1a: bucketing is not a security decision, and two nodes must
+ * agree about one actor without talking — a property a synchronous, published hash has.
+ *
  * `subjectId` is whatever axis the targeting buckets by: an actor id, or an org id when
  * `bucketBy: 'org'` keeps a tenant on one side of the boundary. Pure, so two nodes agree about a
  * subject without talking, and a restart does not re-roll anyone.

package/src/flag.ts

@@ -7,6 +7,7 @@
 // reports it (see `evaluate.ts`). The state space stays bounded because the temporary half is
 // forced to shrink.
 
+import { isIsoDateTime } from '@ultimat3/core';
 import { flagExpiryInvalid } from './errors';
 import type { FlagTargeting } from './targeting';
 import { assertTargeting } from './targeting-assert';
@@ -106,22 +107,21 @@ export function withTargeting(flag: Flag, targeting: FlagTargeting): Flag {
 }
 
 /**
- * A time of day, and the zone it is stated in. `2026-12-01T00:00:00` without one is resolved by
- * `Date.parse` through the PROCESS's zone: measured, that one string is 1796083200000 in UTC,
- * 1796101200000 in America/New_York and 1796050800000 in Asia/Tokyo — fourteen hours of spread
- * across a fleet, so `X_FLAG_EXPIRED` starts on a different DAY on different pods. A date-only
- * form carries no clock time and is UTC by specification, so it passes.
+ * `isIsoDateTime` is the framework's one rule for "a string whose instant is the same on every
+ * host and is the one written" — `t.date`, the HTTP coercion and `@ultimat3/time`'s `fromIso` all
+ * ask it. This file used to restate two of its three patterns, and the missing one was the shape:
+ * `'December 1, 2026'` and `'12/01/2026'` carry no clock time, so they passed the zone screen and
+ * `Date.parse` read them at the HOST's local midnight — the deadline moved with the pod's `TZ` —
+ * and `'2026-02-30'` rolled over to March 2nd. A clock time with no `Z` or offset is refused by
+ * the same predicate: `2026-12-01T00:00:00` measured fourteen hours apart between
+ * America/New_York and Asia/Tokyo. A date-only form is UTC by specification, so it passes.
  *
- * The same two patterns as `@ultimat3/time`'s `fromIso`, restated rather than imported: this
- * package is tier 1 and may import `@ultimat3/core` only — a deadline is one date, and one date is
- * not worth a tier edge. `flag.test.ts` spawns a `TZ=` subprocess per zone, because
- * `scripts/test-setup.ts` pins the runner to UTC and the failure is invisible in process.
+ * `typeof` first: a snapshot pushed from a store, or a plain-JS caller, has no types to be checked
+ * by. `flag.test.ts` spawns a `TZ=` subprocess per zone, because `scripts/test-setup.ts` pins the
+ * runner to UTC and the failure is invisible in process.
  */
-const CLOCK_TIME = /[t ]\d{1,2}:\d{2}/i;
-const UTC_OFFSET = /(?:z|[+-]\d{2}:?\d{2})$/i;
-
 function expiryMsOf(key: string, expiresAt: string): number {
-  if (CLOCK_TIME.test(expiresAt) && !UTC_OFFSET.test(expiresAt)) {
+  if (typeof expiresAt !== 'string' || !isIsoDateTime(expiresAt)) {
     throw flagExpiryInvalid(key, expiresAt);
   }
   const ms = Date.parse(expiresAt);

package/src/index.ts

@@ -1,6 +1,6 @@
 // Public API of @ultimat3/flags. Explicit re-exports only.
 
-export { BUCKETS, bucketOf, fnv1a } from './bucket';
+export { BUCKETS, bucketOf } from './bucket';
 export type { FlagSubjectVia, FlagsErrorCode } from './errors';
 export {
   FLAGS_ERROR_CODES,

package/src/runtime.ts

@@ -8,7 +8,7 @@
 // caught failure, while a flag is evaluated on every request.
 
 import type { Clock, UltimateError } from '@ultimat3/core';
-import { reportError, systemClock } from '@ultimat3/core';
+import { finiteCount, reportError, systemClock } from '@ultimat3/core';
 
 /**
  * One hour. Small enough that an overdue flag shows up the same day, large enough that a flag read
@@ -37,13 +37,23 @@ const lastReportedAt = new Map<string, number>();
  *
  * Only the clock. An interval change re-reads the SAME clock, so clearing there would let a report
  * through on every configure call and turn the rate limit into a suggestion.
+ *
+ * `reportEveryMs` is screened, and BEFORE the clock is touched so a refused call changes nothing.
+ * `now - previous < NaN` is false, so a `NaN` interval — `Number(process.env.X)` on an unset
+ * variable — removed the rate limit entirely and an overdue flag reported on every evaluation;
+ * `Infinity` did the opposite and muted it for good. `0` stays legal: every evaluation reporting
+ * is a decision a caller can make on purpose.
  */
 export function configureFlags(options: FlagsRuntimeOptions): void {
+  const interval =
+    options.reportEveryMs === undefined
+      ? reportEveryMs
+      : finiteCount('configureFlags', 'reportEveryMs', options.reportEveryMs);
   if (options.clock !== undefined && options.clock !== clock) {
     clock = options.clock;
     lastReportedAt.clear();
   }
-  if (options.reportEveryMs !== undefined) reportEveryMs = options.reportEveryMs;
+  reportEveryMs = interval;
 }
 
 export const flagsClock = (): Clock => clock;