@ultimat3/flags 30.8.0 → 31.0.0

package/CLAUDE.md

@@ -113,13 +113,14 @@ what lets `policy` (tier 2) call it from inside a predicate.
 - **`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
-  -10,000,000, below every interval, so that key could never report again — on a frozen test clock,
-  never. `resetFlagReporting()` always did this; `configureFlags` is what apps and test kits call.
+- **The clock is core's `ambientClock()`, never this package's** (v31: `configureFlags({ clock })`
+  is gone; `clock` in `apps/<app>/runtime.ts`, or `installClock` in a test). **`flagsClock()` clears
+  the report watermarks when the ambient clock is a different object from the one they were read
+  on, 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 -10,000,000, below every interval — on a frozen test clock, never again.
   An interval change re-reads the SAME clock and must NOT clear, or the rate limit becomes a
-  suggestion one configure call can bypass.
+  suggestion one configure call can bypass (`runtime.test.ts`).
 
 ## Open
 
@@ -134,6 +135,6 @@ what lets `policy` (tier 2) call it from inside a predicate.
 ## Commands
 
 ```
-bun test packages/flags
+bun test ./packages/flags/
 bun run --filter @ultimat3/flags typecheck
 ```

package/README.md

@@ -165,16 +165,24 @@ work on the day it is needed.
 
 There is no reporter seam in this package. An overdue flag goes through `@ultimat3/core`'s
 `ErrorReporter` — the framework's one error-monitoring seam — as a `warning` from `source:
-'process'`, so an app wires its monitor in exactly one place:
+'process'`, so an app wires its monitor in exactly one place, `apps/web/runtime.ts` (or sets
+`SENTRY_DSN` and lets the boot add the transport):
 
 ```ts
-configureErrorReporting({ reporter: sentryErrorReporter({ dsn }) });
+import type { RuntimeOverrides } from '@ultimat3/cli/serve';
+import { sentryErrorReporter } from '@ultimat3/core';
+
+declare const dsn: string;
+
+export const runtime = { errorReporter: sentryErrorReporter({ dsn }) } satisfies RuntimeOverrides;
 ```
 
 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({ reportEveryMs })` tunes it — the clock is
+`@ultimat3/core`'s process clock (`ambientClock()`), set by `clock` in `apps/<app>/runtime.ts`, so
+`configureFlags` takes none since 31.0.0;
 `reportEveryMs` is a whole number of milliseconds, 0 or more — `NaN`, `Infinity`, a fraction or a
 negative is refused (`X_INVARIANT`) and changes nothing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/flags",
-  "version": "30.8.0",
+  "version": "31.0.0",
   "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
   "keywords": [
     "ultimate",
@@ -41,6 +41,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.8.0"
+    "@ultimat3/core": "31.0.0"
   }
 }

package/src/index.ts

@@ -1,36 +1,17 @@
 // Public API of @ultimat3/flags. Explicit re-exports only.
 
-export { BUCKETS, bucketOf } from './bucket';
-export type { FlagSubjectVia, FlagsErrorCode } from './errors';
-export {
-  FLAGS_ERROR_CODES,
-  FLAGS_ERROR_TITLES,
-  FlagsError,
-  flagDuplicate,
-  flagExpired,
-  flagExpiryInvalid,
-  flagSubjectRequired,
-  flagTargetingInvalid,
-  flagUnknown,
-} from './errors';
+export { BUCKETS } from './bucket';
+export type { FlagsErrorCode } from './errors';
+export { FlagsError, flagExpiryInvalid } from './errors';
 export { isEnabled } from './evaluate';
-export type {
-  Flag,
-  FlagDef,
-  FlagExpiryIsMandatory,
-  FlagKind,
-  PermanentFlagDef,
-  TemporaryFlagDef,
-} from './flag';
-export { FLAG_KINDS } from './flag';
+export type { Flag, FlagDef, FlagKind, PermanentFlagDef, TemporaryFlagDef } from './flag';
 export type { FlagFacts, FlagsReport } from './projection';
 export { flagsReport } from './projection';
 export type { SnapshotResult } from './registry';
-export { allFlags, applyFlagSnapshot, defineFlag, hasFlag, resetFlags } from './registry';
+export { applyFlagSnapshot, defineFlag } from './registry';
 export type { FlagsRuntimeOptions } from './runtime';
 // The reporter seam is `@ultimat3/core`'s `ErrorReporter`, wired once with
-// `configureErrorReporting()`. This package deliberately re-exports none of it.
-export { configureFlags, DEFAULT_REPORT_INTERVAL_MS, resetFlagReporting } from './runtime';
-export type { BuiltInSubjectKind, FlagSubjects } from './subject';
-export { BUILT_IN_SUBJECT_KINDS } from './subject';
+// `runtime.ts`'s `errorReporter`. This package deliberately re-exports none of it.
+export { configureFlags } from './runtime';
+export type { FlagSubjects } from './subject';
 export type { FlagTargeting } from './targeting';

package/src/runtime.ts

@@ -1,5 +1,6 @@
-// Single responsibility: the two ambient things an evaluation needs that the declaration cannot
-// carry — what "now" is, and how often the same overdue flag may report.
+// Single responsibility: how often the same overdue flag may report, and the watermarks that rate
+// limit keeps. "Now" is not this package's: it is core's `ambientClock()`, which the boot fills
+// from `clock` in `apps/<app>/runtime.ts` and a test from `@ultimat3/testing` (v31).
 //
 // The reporter itself is NOT here. `@ultimat3/core`'s `ErrorReporter` is the framework's one
 // error-monitoring seam; a second one in this package would be a second place an app has to wire
@@ -8,7 +9,7 @@
 // caught failure, while a flag is evaluated on every request.
 
 import type { Clock, UltimateError } from '@ultimat3/core';
-import { finiteCount, recordFailureFact, reportError, systemClock } from '@ultimat3/core';
+import { ambientClock, finiteCount, recordFailureFact, reportError } from '@ultimat3/core';
 
 /**
  * One hour. Small enough that an overdue flag shows up the same day, large enough that a flag read
@@ -18,27 +19,36 @@ import { finiteCount, recordFailureFact, reportError, systemClock } from '@ultim
 export const DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1000;
 
 export interface FlagsRuntimeOptions {
-  readonly clock?: Clock | undefined;
   /** Minimum gap between two reports of the SAME flag key. */
   readonly reportEveryMs?: number | undefined;
 }
 
-let clock: Clock = systemClock;
 let reportEveryMs = DEFAULT_REPORT_INTERVAL_MS;
 const lastReportedAt = new Map<string, number>();
+/** The clock every watermark in `lastReportedAt` was read from. */
+let watermarkClock: Clock | undefined;
 
 /**
- * Swapping the clock CLEARS the watermarks, because a monotonic reading is only meaningful 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 -10_000_000 — below every interval, so that key
- * could never report again until the new clock passed the old one's reading, which on a frozen
- * test clock is never. `resetFlagReporting()` always did this; `configureFlags` is what apps and
- * test kits actually call.
+ * The process clock, and the watermarks forgotten whenever it is a DIFFERENT clock from the one
+ * they were read on: a monotonic reading is only meaningful 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 -10_000_000 — below every interval, so that key could never report again
+ * until the new clock passed the old one's reading, which on a frozen test clock is never.
  *
- * 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.
+ * Only on a clock change. 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.
+ */
+export const flagsClock = (): Clock => {
+  const clock = ambientClock();
+  if (clock !== watermarkClock) {
+    lastReportedAt.clear();
+    watermarkClock = clock;
+  }
+  return clock;
+};
+
+/**
+ * `reportEveryMs` is screened, and BEFORE anything 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
@@ -49,15 +59,9 @@ export function configureFlags(options: FlagsRuntimeOptions): void {
     options.reportEveryMs === undefined
       ? reportEveryMs
       : finiteCount('configureFlags', 'reportEveryMs', options.reportEveryMs);
-  if (options.clock !== undefined && options.clock !== clock) {
-    clock = options.clock;
-    lastReportedAt.clear();
-  }
   reportEveryMs = interval;
 }
 
-export const flagsClock = (): Clock => clock;
-
 /**
  * Report `build()`'s error through core's seam at most once per `reportEveryMs` for this key, and
  * say whether it did. The rate limit is keyed on the MONOTONIC clock: a wall-clock jump — an NTP
@@ -71,7 +75,7 @@ export const flagsClock = (): Clock => clock;
  * happened to evaluate it first.
  */
 export function reportOnce(key: string, build: () => UltimateError): boolean {
-  const now = clock.monotonic();
+  const now = flagsClock().monotonic();
   const previous = lastReportedAt.get(key);
   if (previous !== undefined && now - previous < reportEveryMs) return false;
   lastReportedAt.set(key, now);
@@ -92,7 +96,7 @@ export function recordEvaluation(key: string, on: boolean): boolean {
 
 /** Test-only, and the counterpart to every other reset in the framework. */
 export function resetFlagReporting(): void {
-  clock = systemClock;
+  watermarkClock = undefined;
   reportEveryMs = DEFAULT_REPORT_INTERVAL_MS;
   lastReportedAt.clear();
 }