@ultimat3/flags 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -13,6 +13,7 @@ what lets `policy` (tier 2) call it from inside a predicate.
 | Errors | `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
 | Files | one responsibility each, < 200 lines, tests beside the source |
 | Subjects | `src/subject.ts` — one resolver; never a second allow list per record kind |
+| Validation | `src/targeting-assert.ts` — every declaration-time refusal. `targeting.ts` stays the evaluation path |
 
 ## Invariants
 
@@ -84,6 +85,35 @@ what lets `policy` (tier 2) call it from inside a predicate.
   `errors.test.ts` running the generated snippet through `new Function`.
 - **An unknown key throws.** Answering `false` is a branch that never runs and never says so.
 - `default: true` beside a `rollout` is refused: the two answer the same actors and disagree.
+- **`assertTargeting` establishes the argument is an OBJECT before reading a field, and every one
+  of the four lists goes through the same check** (`As of 2026-08`). It destructured first, so
+  `applyFlagSnapshot({ 'billing.new': null })` was a bare `TypeError` and `{ 'billing.new': 'off' }`
+  was ACCEPTED — `default`, `actors`, `rollout` and `subjects` are all `undefined` on a string.
+  `default` was the one required field with no shape check while `rollout` got `Number.isInteger`,
+  so `{}` answered `undefined` and `{ default: 'yes' }` answered `"yes"` through a declared
+  `boolean` return, silently changing the meaning of every `=== true` / `=== false` call site. And
+  the `Array.isArray` rule reached `subjects` only, while CLAUDE.md called the four lists one rank:
+  `actors: 'user_100'` matched by SUBSTRING (`isEnabled` answered `true` for `user_1`, `user_10`,
+  `ser_10` and `u`), `orgs` the same, and a non-array `roles` reached `.some()` as a bare
+  `TypeError` out of a path this file documents as pure and synchronous — inside a policy predicate.
+  `renderGiven` from `errors.ts` renders every rejected value; never `JSON.stringify` directly, for
+  the reason that file states.
+- **A temporary flag's `expiresAt` must carry no ambient zone** (`As of 2026-08`). `Date.parse`
+  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
+  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` 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.
+  An interval change re-reads the SAME clock and must NOT clear, or the rate limit becomes a
+  suggestion one configure call can bypass.
 
 ## Open
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/flags",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0"
+    "@ultimat3/core": "4.1.0"
   }
 }

package/src/errors.ts

@@ -111,7 +111,7 @@ export const flagSubjectRequired = (init: {
  * something that is not `X_FLAG_EXPIRY_INVALID`. A cause only has to describe, so a value that
  * defeats rendering degrades to its type rather than destroying the refusal.
  */
-const renderGiven = (given: unknown): string => {
+export const renderGiven = (given: unknown): string => {
   if (given === undefined) return 'undefined';
   if (typeof given === 'bigint') return `${given}n`;
   if (typeof given === 'symbol') return String(given);

package/src/flag.ts

@@ -9,7 +9,7 @@
 
 import { flagExpiryInvalid } from './errors';
 import type { FlagTargeting } from './targeting';
-import { assertTargeting } from './targeting';
+import { assertTargeting } from './targeting-assert';
 
 export const FLAG_KINDS = ['permanent', 'temporary'] as const;
 
@@ -87,10 +87,7 @@ export function toFlag(def: FlagDef): Flag {
       owner: null,
     });
   }
-  // A bare ISO date parses as UTC midnight, so the deadline is the same instant on every node —
-  // no ambient zone, which is the framework's rule about dates applied to a deadline.
-  const expiresAtMs = Date.parse(def.expiresAt);
-  if (Number.isNaN(expiresAtMs)) throw flagExpiryInvalid(def.key, def.expiresAt);
+  const expiresAtMs = expiryMsOf(def.key, def.expiresAt);
   return Object.freeze({
     key: def.key,
     kind: def.kind,
@@ -107,3 +104,27 @@ export function withTargeting(flag: Flag, targeting: FlagTargeting): Flag {
   assertTargeting(flag.key, targeting);
   return Object.freeze({ ...flag, targeting });
 }
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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)) {
+    throw flagExpiryInvalid(key, expiresAt);
+  }
+  const ms = Date.parse(expiresAt);
+  if (Number.isNaN(ms)) throw flagExpiryInvalid(key, expiresAt);
+  return ms;
+}

package/src/registry.ts

@@ -5,7 +5,8 @@
 import { flagDuplicate, flagUnknown } from './errors';
 import type { Flag, FlagDef } from './flag';
 import { toFlag, withTargeting } from './flag';
-import { assertTargeting, type FlagTargeting } from './targeting';
+import type { FlagTargeting } from './targeting';
+import { assertTargeting } from './targeting-assert';
 
 const flags = new Map<string, Flag>();
 

package/src/runtime.ts

@@ -27,8 +27,22 @@ let clock: Clock = systemClock;
 let reportEveryMs = DEFAULT_REPORT_INTERVAL_MS;
 const lastReportedAt = new Map<string, number>();
 
+/**
+ * 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.
+ *
+ * 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.
+ */
 export function configureFlags(options: FlagsRuntimeOptions): void {
-  if (options.clock !== undefined) clock = options.clock;
+  if (options.clock !== undefined && options.clock !== clock) {
+    clock = options.clock;
+    lastReportedAt.clear();
+  }
   if (options.reportEveryMs !== undefined) reportEveryMs = options.reportEveryMs;
 }
 

package/src/targeting-assert.ts

@@ -0,0 +1,156 @@
+// Single responsibility: declaration-time validation of a `FlagTargeting`, the way `can()`
+// validates its permission rather than waiting for a request. Split from `targeting.ts` so that
+// file stays the evaluation path — the one that runs inside a policy predicate and must not grow.
+
+import { BUCKETS } from './bucket';
+import { flagTargetingInvalid, renderGiven } from './errors';
+import { BUILT_IN_SUBJECT_KINDS, isBuiltInSubjectKind } from './subject';
+import type { FlagTargeting } from './targeting';
+
+/**
+ * The three flat allow lists, all checked by the same loop. They are ONE rank with `subjects` at
+ * evaluation time, and CLAUDE.md says so — so a validation rule that reached only `subjects` made
+ * three quarters of that rank unchecked.
+ */
+const ID_LISTS = ['actors', 'roles', 'orgs'] as const;
+
+type IdListField = (typeof ID_LISTS)[number];
+
+const LIST_EXAMPLE: Readonly<Record<IdListField, string>> = {
+  actors: 'user_100',
+  roles: 'admin',
+  orgs: 'org_acme',
+};
+
+/**
+ * Each rule closes a way for a flag to look wired and decide something other than what it says:
+ *
+ * | Rejected | Why |
+ * |---|---|
+ * | `rollout: 0.5` | read as a fraction it means "half", read as a percentage it means "nobody" |
+ * | `default: true` with a `rollout` | the two answer the same actors and disagree; there is no reading of "on for everyone, and also on for 10%" |
+ * | `bucketBy` with no `rollout` | it names what a rollout divides, and there is no rollout to divide |
+ * | a blank `bucketBy` | names no kind at all |
+ * | `subjects.actor` / `subjects.org` | `actors` and `orgs` are the one spelling; two would disagree |
+ * | a `subjects` entry that is not a list of non-empty ids | reachable from a store snapshot, and it matches nothing while reading as an allow list |
+ *
+ * The checks narrow by hand rather than through a schema: this package's other runtime re-checks
+ * (`Number.isInteger`, the expiry pattern in `flag.ts`) do the same, and a dependency here would
+ * buy one validation on a path that must stay allocation-free.
+ */
+export function assertTargeting(key: string, targeting: FlagTargeting): void {
+  const declared = assertObject(key, targeting);
+  const { bucketBy, rollout } = declared;
+  assertDefault(key, declared.default);
+  for (const field of ID_LISTS) assertIdList(key, field, declared[field]);
+  if (declared.subjects !== undefined) assertSubjects(key, declared.subjects);
+  if (bucketBy !== undefined) {
+    if (typeof bucketBy !== 'string' || bucketBy.trim() === '') {
+      throw flagTargetingInvalid(
+        key,
+        `bucketBy is ${JSON.stringify(bucketBy)}, which names no subject kind`,
+        `set bucketBy to a subject kind — '${BUILT_IN_SUBJECT_KINDS.join("', '")}', or one your call site passes — in defineFlag({ key: '${key}' })`,
+      );
+    }
+    if (rollout === undefined) {
+      throw flagTargetingInvalid(
+        key,
+        `bucketBy is '${bucketBy}' with no rollout, so it divides nothing`,
+        `add a rollout to defineFlag({ key: '${key}' }), or remove bucketBy`,
+      );
+    }
+  }
+  if (rollout === undefined) return;
+  if (!Number.isInteger(rollout)) {
+    const problem = `rollout is ${rollout}; a rollout is a whole percentage, not a fraction`;
+    throw flagTargetingInvalid(key, problem);
+  }
+  if (rollout < 0 || rollout > BUCKETS) {
+    throw flagTargetingInvalid(key, `rollout is ${rollout}, outside 0-${BUCKETS}`);
+  }
+  if (declared.default) {
+    throw flagTargetingInvalid(key, `default is true and rollout is ${rollout}; the two disagree`);
+  }
+}
+
+/**
+ * The argument is a targeting AT ALL, established before any field is read.
+ *
+ * The declared parameter type is a promise the CALLER makes, and this function exists for the case
+ * nobody made it: `applyFlagSnapshot` lands a store payload no type ever saw, so a `null` used to
+ * reach the destructure as a bare `TypeError` and a bare string used to pass every check —
+ * `default`, `actors`, `rollout` and `subjects` are all `undefined` on a string — and then answer
+ * `undefined` from a function declared to return `boolean`.
+ */
+function assertObject(key: string, targeting: FlagTargeting): FlagTargeting {
+  const given: unknown = targeting;
+  if (typeof given !== 'object' || given === null || Array.isArray(given)) {
+    throw flagTargetingInvalid(
+      key,
+      `targeting is ${renderGiven(given)}, which is not a targeting object`,
+      `give the flag a targeting object — { default: false } — in defineFlag({ key: '${key}' })`,
+    );
+  }
+  return given as FlagTargeting;
+}
+
+/**
+ * `default` is the one REQUIRED field, and it was the one field with no shape check while
+ * `rollout` got `Number.isInteger`. `isEnabled` is declared to return `boolean`: a missing default
+ * answered `undefined` through that type and `{ default: 'yes' }` answered the string, so every
+ * `=== true` / `=== false` call site silently changed meaning without a single failure anywhere.
+ */
+function assertDefault(key: string, value: boolean): void {
+  if (typeof value === 'boolean') return;
+  throw flagTargetingInvalid(
+    key,
+    `default is ${renderGiven(value)}; a flag answers true or false and nothing else`,
+    `set default to true or false in defineFlag({ key: '${key}' })`,
+  );
+}
+
+/**
+ * A list of non-empty ids, or absent. The check that matters is `Array.isArray`, and its absence
+ * was a silent grant: `includes` on a STRING matches by substring, so `actors: 'user_100'` answered
+ * `true` for `user_1`, `user_10`, `ser_10` and `u`. `roles` failed the other way — a string has no
+ * `.some()`, so it threw a bare `TypeError` out of `evaluateTargeting`, which runs inside policy
+ * predicates and render passes.
+ */
+function assertIdList(key: string, field: IdListField, list: unknown): void {
+  if (list === undefined) return;
+  const fix = `set ${field} to a list of ids — ${field}: ['${LIST_EXAMPLE[field]}'] — in defineFlag({ key: '${key}' })`;
+  if (!Array.isArray(list)) {
+    throw flagTargetingInvalid(
+      key,
+      `${field} is ${renderGiven(list)}, not a list of ids — a bare string is matched by substring, so it claims every id inside it`,
+      fix,
+    );
+  }
+  for (const id of list as readonly unknown[]) {
+    if (typeof id !== 'string' || id === '') {
+      throw flagTargetingInvalid(key, `${field} holds ${renderGiven(id)}, which is not an id`, fix);
+    }
+  }
+}
+
+function assertSubjects(key: string, subjects: Readonly<Record<string, readonly string[]>>): void {
+  const fix = `give each subjects entry a kind and a list of ids — { bank: ['bank_integration:bbva'] } — in defineFlag({ key: '${key}' })`;
+  for (const [kind, ids] of Object.entries<unknown>(subjects)) {
+    if (kind.trim() === '') throw flagTargetingInvalid(key, 'a subjects kind is blank', fix);
+    if (isBuiltInSubjectKind(kind)) {
+      throw flagTargetingInvalid(
+        key,
+        `subjects.${kind} restates a built-in kind`,
+        `use ${kind === 'org' ? 'orgs' : 'actors'} instead of subjects.${kind} in defineFlag({ key: '${key}' })`,
+      );
+    }
+    if (!Array.isArray(ids)) {
+      throw flagTargetingInvalid(key, `subjects.${kind} is not a list of ids`, fix);
+    }
+    for (const id of ids as readonly unknown[]) {
+      if (typeof id !== 'string' || id === '') {
+        throw flagTargetingInvalid(key, `subjects.${kind} holds an id that is not a string`, fix);
+      }
+    }
+  }
+}

package/src/targeting.ts

@@ -3,10 +3,9 @@
 // touches a clock. Loading the store is somebody else's job (`applyFlagSnapshot`).
 import type { Actor } from '@ultimat3/core';
 import { hasRole } from '@ultimat3/core';
-import { BUCKETS, bucketOf } from './bucket';
-import { flagTargetingInvalid } from './errors';
+import { bucketOf } from './bucket';
 import type { FlagSubjects } from './subject';
-import { BUILT_IN_SUBJECT_KINDS, isBuiltInSubjectKind, subjectIdOf } from './subject';
+import { subjectIdOf } from './subject';
 
 export interface FlagTargeting {
   /** The answer when no allow list and no rollout claims this actor. `false` is off, `true` is on. */
@@ -39,77 +38,6 @@ export interface FlagTargeting {
   readonly bucketBy?: string | undefined;
 }
 
-/**
- * Declaration-time validation, the way `can()` validates its permission rather than waiting for a
- * request. Each rule closes a way for a flag to look wired and decide nothing:
- *
- * | Rejected | Why |
- * |---|---|
- * | `rollout: 0.5` | read as a fraction it means "half", read as a percentage it means "nobody" |
- * | `default: true` with a `rollout` | the two answer the same actors and disagree; there is no reading of "on for everyone, and also on for 10%" |
- * | `bucketBy` with no `rollout` | it names what a rollout divides, and there is no rollout to divide |
- * | a blank `bucketBy` | names no kind at all |
- * | `subjects.actor` / `subjects.org` | `actors` and `orgs` are the one spelling; two would disagree |
- * | a `subjects` entry that is not a list of non-empty ids | reachable from a store snapshot, and it matches nothing while reading as an allow list |
- *
- * The `subjects` checks narrow by hand rather than through a schema: this package's other runtime
- * re-checks (`Number.isInteger`, `Date.parse`) do the same, and a dependency here would buy one
- * validation on a path that must stay allocation-free.
- */
-export function assertTargeting(key: string, targeting: FlagTargeting): void {
-  const { bucketBy, rollout } = targeting;
-  if (targeting.subjects !== undefined) assertSubjects(key, targeting.subjects);
-  if (bucketBy !== undefined) {
-    if (typeof bucketBy !== 'string' || bucketBy.trim() === '') {
-      throw flagTargetingInvalid(
-        key,
-        `bucketBy is ${JSON.stringify(bucketBy)}, which names no subject kind`,
-        `set bucketBy to a subject kind — '${BUILT_IN_SUBJECT_KINDS.join("', '")}', or one your call site passes — in defineFlag({ key: '${key}' })`,
-      );
-    }
-    if (rollout === undefined) {
-      throw flagTargetingInvalid(
-        key,
-        `bucketBy is '${bucketBy}' with no rollout, so it divides nothing`,
-        `add a rollout to defineFlag({ key: '${key}' }), or remove bucketBy`,
-      );
-    }
-  }
-  if (rollout === undefined) return;
-  if (!Number.isInteger(rollout)) {
-    const problem = `rollout is ${rollout}; a rollout is a whole percentage, not a fraction`;
-    throw flagTargetingInvalid(key, problem);
-  }
-  if (rollout < 0 || rollout > BUCKETS) {
-    throw flagTargetingInvalid(key, `rollout is ${rollout}, outside 0-${BUCKETS}`);
-  }
-  if (targeting.default) {
-    throw flagTargetingInvalid(key, `default is true and rollout is ${rollout}; the two disagree`);
-  }
-}
-
-function assertSubjects(key: string, subjects: Readonly<Record<string, readonly string[]>>): void {
-  const fix = `give each subjects entry a kind and a list of ids — { bank: ['bank_integration:bbva'] } — in defineFlag({ key: '${key}' })`;
-  for (const [kind, ids] of Object.entries<unknown>(subjects)) {
-    if (kind.trim() === '') throw flagTargetingInvalid(key, 'a subjects kind is blank', fix);
-    if (isBuiltInSubjectKind(kind)) {
-      throw flagTargetingInvalid(
-        key,
-        `subjects.${kind} restates a built-in kind`,
-        `use ${kind === 'org' ? 'orgs' : 'actors'} instead of subjects.${kind} in defineFlag({ key: '${key}' })`,
-      );
-    }
-    if (!Array.isArray(ids)) {
-      throw flagTargetingInvalid(key, `subjects.${kind} is not a list of ids`, fix);
-    }
-    for (const id of ids as readonly unknown[]) {
-      if (typeof id !== 'string' || id === '') {
-        throw flagTargetingInvalid(key, `subjects.${kind} holds an id that is not a string`, fix);
-      }
-    }
-  }
-}
-
 /**
  * Allow lists first, rollout second, declared default last. That order is the contract: a subject
  * an operator explicitly named must not depend on where a hash happened to put it, which is the