@tehw0lf/yaft 0.0.10 → 0.0.12

package/.github/workflows/security-scan.yml

@@ -49,7 +49,7 @@ jobs:
 
     steps:
       - name: Download latest dist artifacts from CI
-        uses: dawidd6/action-download-artifact@v6
+        uses: dawidd6/action-download-artifact@bf251b5aa9c2f7eeb574a96ee720e24f801b7c11 # v6
         with:
           workflow: build.yml
           name: dist
@@ -58,7 +58,7 @@ jobs:
 
       - name: Upload artifacts for scanning
         if: hashFiles('dist/**/*') != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: build
           path: dist/

package/CLAUDE.md

@@ -58,18 +58,31 @@ npx jest -t "test name"      # Run specific test by name pattern
 - Support both boolean and Feature data types
 - Fallback to empty configuration on file load errors
 
+**Evaluation Core (`src/evaluate.ts`)**
+- `evaluate(feature, now)` is the single definition of the evaluation rules
+- Providers call it instead of implementing the logic themselves; before this
+  existed, the feature providers each carried their own copy
+- `Clock` is a `() => number`; providers take one and default to `systemClock`,
+  so tests and the conformance adapter can pin `now`
+- `parseTimestamp` accepts only RFC 3339 with an offset and returns
+  `undefined` for anything else, warning rather than throwing
+
 ### Feature Data Model
 
 ```typescript
 type Feature = {
-  key: string;       // Unique feature identifier
-  value: string;     // Boolean value as string
-  activeAt: string;  // ISO date when feature becomes active
-  disabledAt: string; // ISO date when feature gets disabled
+  key: string;        // Unique feature identifier
+  value: string;      // Boolean value as string; only "true" is on
+  activeAt: string;   // RFC 3339 with offset, or empty
+  disabledAt: string; // RFC 3339 with offset, or empty
+  tags?: string[];
 }
 ```
 
 Features support time-based activation/deactivation logic evaluated at runtime.
+The window is half-open: `now == activeAt` is on, `now == disabledAt` is off.
+Dates without an offset are ignored, because languages disagree on how to read
+them and a feature would otherwise flip at a different instant per port.
 
 ### Decorator Behavior
 

package/README.md

@@ -94,9 +94,54 @@ export type Feature = {
   value: string;
   activeAt: string;
   disabledAt: string;
+  tags?: string[];
 };
 ```
 
+## Evaluation rules
+
+A feature is on when all of the following hold. `evaluate` is exported, so the
+rules can be applied directly to a feature without going through a provider.
+
+- The value is exactly `"true"`. `"TRUE"`, `"1"` and `""` are off -- the value
+  is stored as a string, and anything else would be a silent disagreement
+  between backend and client.
+- `activeAt` has passed, if set. The bound is inclusive: at exactly `activeAt`
+  the feature is on.
+- `disabledAt` has not been reached, if set. This bound is exclusive: at
+  exactly `disabledAt` the feature is off.
+
+A missing feature is off. Unset, `null` or unparseable dates are ignored rather
+than treated as an error, and never throw.
+
+### Date format
+
+Dates must be **RFC 3339 with an offset** (`2026-09-18T15:00:00Z` or
+`2026-09-18T15:00:00+02:00`). Anything else -- a bare date such as
+`2026-09-18`, or a timestamp without an offset -- is ignored and logged as a
+warning.
+
+This is stricter than `Date.parse`, on purpose: JavaScript reads a bare date as
+UTC midnight and an offset-less timestamp as local time, while most other
+languages read both as local. Accepting them would make a feature flip at a
+different instant depending on which client evaluated it.
+
+## Testing with a fixed time
+
+Both `Feature` providers take an optional clock, so a test can evaluate against
+a fixed instant instead of the current time:
+
+```ts
+import { LocalStorageFeatureProvider } from "./provider";
+
+const provider = new LocalStorageFeatureProvider(
+  "./test-feature.json",
+  () => Date.parse("2026-09-18T12:00:00Z")
+);
+```
+
+The clock defaults to the system time, so existing code needs no change.
+
 # Licenses
 
 - Code: MIT License

package/logo.svg

@@ -1,4 +1,4 @@
-<svg viewBox="0 0 60 60" stroke="" fill="grey" xmlns="http://www.w3.org/2000/svg">
+<svg viewBox="0 0 60 60" stroke="" fill="#8e8e8e" xmlns="http://www.w3.org/2000/svg">
     <title>YaFT Logo</title>
     <desc>Yet Another Feature Toggle - Copyright 2025 tehw0lf</desc>
     <metadata>
@@ -11,8 +11,8 @@
         </rdf:RDF>
     </metadata>
     <!-- Y -->
-    <path d="M5,5 L30,28" stroke="grey" stroke-width="4" fill="none" />
-    <path d="M55,5 L30,28" stroke="grey" stroke-width="4" fill="none" />
+    <path d="M5,5 L30,28" stroke="#8e8e8e" stroke-width="4" fill="none" />
+    <path d="M55,5 L30,28" stroke="#8e8e8e" stroke-width="4" fill="none" />
     <!-- A -->
     <rect x="19" y="17.5" width="22" height="3" />
     <!-- F -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
   "scripts": {

package/src/evaluate.ts

@@ -0,0 +1,122 @@
+import { Feature } from "./FeatureToggle";
+
+/**
+ * A source of the current time, in milliseconds since the epoch.
+ *
+ * Everything that evaluates a feature takes one of these instead of calling
+ * `Date.now()` directly, so tests -- and the conformance suite, which supplies
+ * a `now` with every case -- can evaluate against a fixed instant.
+ */
+export type Clock = () => number;
+
+/** The default clock: the system time. */
+export const systemClock: Clock = () => Date.now();
+
+/**
+ * Matches RFC 3339 timestamps that carry an explicit offset (`Z` or `±hh:mm`).
+ *
+ * Only this format is accepted. A bare date such as `2026-09-18` or a
+ * timestamp without an offset is rejected, because languages disagree on how
+ * to read them -- JavaScript treats a bare date as UTC midnight and an
+ * offset-less timestamp as local time, while most other languages read both as
+ * local. A feature would then flip at a different instant depending on which
+ * port evaluated it, so such values are ignored rather than guessed at.
+ */
+const RFC3339_WITH_OFFSET =
+  /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+/** Days per month, index 1-12; February is handled by the leap-year branch. */
+const DAYS_IN_MONTH = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function isLeapYear(year: number): boolean {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+function isRealDate(year: number, month: number, day: number): boolean {
+  if (month < 1 || month > 12 || day < 1) return false;
+  const max = month === 2 && isLeapYear(year) ? 29 : DAYS_IN_MONTH[month];
+  return day <= max;
+}
+
+function isRealTime(hour: number, minute: number, second: number): boolean {
+  // RFC 3339 permits second 60 for a leap second; it is allowed through here
+  // and then rejected by the NaN guard, because Date.parse cannot represent
+  // one. The value ends up ignored either way.
+  return hour <= 23 && minute <= 59 && second <= 60;
+}
+
+/**
+ * Parses an RFC 3339 timestamp with an offset.
+ *
+ * Returns `undefined` for anything unset, malformed or in another format;
+ * callers treat that as "no bound", never as an error. An invalid value is
+ * warned about but never throws, so a bad timestamp in the backend cannot take
+ * an application down.
+ */
+export function parseTimestamp(value: string | null | undefined): number | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+
+  const match = RFC3339_WITH_OFFSET.exec(value);
+  if (!match) {
+    console.warn(
+      `YaFT: ignoring "${value}", expected RFC 3339 with an offset (e.g. 2026-09-18T15:00:00Z)`
+    );
+    return undefined;
+  }
+
+  // The pattern only checks the shape, and Date.parse does not reject an
+  // impossible calendar date -- it rolls it over, turning 2027-02-30 into
+  // 2027-03-02. Silently shifting a bound by days is worse than ignoring it,
+  // so the components are range-checked first.
+  const [, year, month, day, hour, minute, second] = match;
+  if (!isRealDate(+year, +month, +day) || !isRealTime(+hour, +minute, +second)) {
+    console.warn(`YaFT: ignoring "${value}", not a valid date or time`);
+    return undefined;
+  }
+
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) {
+    console.warn(`YaFT: ignoring "${value}", not a valid timestamp`);
+    return undefined;
+  }
+
+  return parsed;
+}
+
+/**
+ * Decides whether a feature is on at the instant `now`.
+ *
+ * This is the single definition of YaFT's evaluation rules. Providers call it
+ * rather than implementing the logic themselves, so every provider -- and
+ * every port that mirrors this function -- agrees on the same answer.
+ *
+ * The rules:
+ *
+ * - A missing feature is off.
+ * - Only the exact string `"true"` is on. `"TRUE"`, `"1"` and `""` are off,
+ *   because the backend stores the value as a string and anything else would
+ *   be a silent disagreement between backend and client.
+ * - `activeAt` and `disabledAt` are optional bounds. Unset, null or
+ *   unparseable values are ignored rather than treated as an error.
+ * - The window is half-open: at exactly `activeAt` the feature is on
+ *   (`now < activeAt` is off), at exactly `disabledAt` it is off
+ *   (`now >= disabledAt` is off).
+ * - `activeAt` after `disabledAt` is not special-cased; it simply yields a
+ *   window that is never open.
+ */
+export function evaluate(
+  feature: Feature | null | undefined,
+  now: number
+): boolean {
+  if (feature === undefined || feature === null) return false;
+
+  if (feature.value !== "true") return false;
+
+  const activeAt = parseTimestamp(feature.activeAt);
+  if (activeAt !== undefined && now < activeAt) return false;
+
+  const disabledAt = parseTimestamp(feature.disabledAt);
+  if (disabledAt !== undefined && now >= disabledAt) return false;
+
+  return true;
+}

package/src/examples/ApiServiceFeatureProvider.ts

@@ -1,5 +1,6 @@
 import axios from "axios";
 
+import { Clock, evaluate, systemClock } from "../evaluate";
 import { Feature, FeatureProvider } from "../FeatureToggle";
 
 export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
@@ -7,8 +8,14 @@ export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
   baseUUID: string;
   data: Record<string, Feature> = {};
   collectionHash = "";
+  private readonly clock: Clock;
 
-  constructor(apiUrl: string, baseUUID: string) {
+  /**
+   * @param clock source of the current time; override it to evaluate against a
+   *              fixed instant in tests
+   */
+  constructor(apiUrl: string, baseUUID: string, clock: Clock = systemClock) {
+    this.clock = clock;
     this.apiUrl = apiUrl;
     this.baseUUID = baseUUID;
     this.getCollectionHash(`${this.apiUrl}/collectionHash/${this.baseUUID}`);
@@ -58,30 +65,6 @@ export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
   }
 
   isEnabled(key: string): boolean {
-    const feature = this.data[key];
-
-    if (feature === undefined || feature === null) return false;
-
-    // First check: value must be "true"
-    if (feature.value !== "true") return false;
-
-    // Second check: if activeAt is set and in future, not yet active
-    if (feature.activeAt && feature.activeAt !== "") {
-      const activeTime = Date.parse(feature.activeAt);
-      if (!isNaN(activeTime) && Date.now() < activeTime) {
-        return false;
-      }
-    }
-
-    // Third check: if disabledAt is set and in past, already disabled
-    if (feature.disabledAt && feature.disabledAt !== "") {
-      const disabledTime = Date.parse(feature.disabledAt);
-      if (!isNaN(disabledTime) && Date.now() >= disabledTime) {
-        return false;
-      }
-    }
-
-    // All checks passed, feature is enabled
-    return true;
+    return evaluate(this.data[key], this.clock());
   }
 }

package/src/examples/LocalStorageFeatureProvider.ts

@@ -1,9 +1,17 @@
+import { Clock, evaluate, systemClock } from "../evaluate";
 import { Feature, FeatureProvider } from "../FeatureToggle";
 
 export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
   data: Record<string, Feature> = {};
-
-  constructor(configPath: string) {
+  private readonly clock: Clock;
+
+  /**
+   * @param configPath path passed to `require()`
+   * @param clock source of the current time; override it to evaluate against a
+   *              fixed instant in tests
+   */
+  constructor(configPath: string, clock: Clock = systemClock) {
+    this.clock = clock;
     this.getConfig(configPath);
   }
 
@@ -18,30 +26,6 @@ export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
   }
 
   isEnabled(key: string): boolean {
-    const feature = this.data[key] as Feature;
-
-    if (feature === undefined || feature === null) return false;
-
-    // First check: value must be "true"
-    if (feature.value !== "true") return false;
-
-    // Second check: if activeAt is set and in future, not yet active
-    if (feature.activeAt && feature.activeAt !== "") {
-      const activeTime = Date.parse(feature.activeAt);
-      if (!isNaN(activeTime) && Date.now() < activeTime) {
-        return false;
-      }
-    }
-
-    // Third check: if disabledAt is set and in past, already disabled
-    if (feature.disabledAt && feature.disabledAt !== "") {
-      const disabledTime = Date.parse(feature.disabledAt);
-      if (!isNaN(disabledTime) && Date.now() >= disabledTime) {
-        return false;
-      }
-    }
-
-    // All checks passed, feature is enabled
-    return true;
+    return evaluate(this.data[key], this.clock());
   }
 }

package/src/index.ts

@@ -4,3 +4,4 @@ export {
   FeatureToggleBase,
   FeatureProvider,
 } from "./FeatureToggle";
+export { Clock, evaluate, parseTimestamp, systemClock } from "./evaluate";

package/src/test/evaluate.spec.ts

@@ -0,0 +1,260 @@
+import { Feature } from '../FeatureToggle';
+import { Clock, evaluate, parseTimestamp, systemClock } from '../evaluate';
+
+/**
+ * Tests for the central evaluation rules.
+ *
+ * Every case carries its own `now`, so nothing here depends on when the suite
+ * runs. This mirrors how the conformance suite supplies a `now` per case, and
+ * is the reason the clock had to become injectable.
+ */
+describe('evaluate', () => {
+  const NOW = Date.parse('2026-09-18T12:00:00Z');
+
+  const feature = (overrides: Partial<Feature> = {}): Feature => ({
+    key: 'f',
+    value: 'true',
+    activeAt: '',
+    disabledAt: '',
+    ...overrides,
+  });
+
+  describe('missing features', () => {
+    it('treats undefined as off', () => {
+      expect(evaluate(undefined, NOW)).toBe(false);
+    });
+
+    it('treats null as off', () => {
+      expect(evaluate(null, NOW)).toBe(false);
+    });
+  });
+
+  describe('value', () => {
+    it('is on for exactly "true"', () => {
+      expect(evaluate(feature({ value: 'true' }), NOW)).toBe(true);
+    });
+
+    // The backend stores the value as a string. Anything but "true" must read
+    // as off, or backend and client would silently disagree.
+    it.each(['false', 'TRUE', 'True', '1', '', 'yes'])(
+      'is off for %p',
+      (value) => {
+        expect(evaluate(feature({ value }), NOW)).toBe(false);
+      }
+    );
+
+    it('is off when the value is missing entirely', () => {
+      const withoutValue = { key: 'f', activeAt: '', disabledAt: '' } as Feature;
+      expect(evaluate(withoutValue, NOW)).toBe(false);
+    });
+  });
+
+  describe('activeAt', () => {
+    it('is off before activeAt', () => {
+      expect(
+        evaluate(feature({ activeAt: '2026-09-18T13:00:00Z' }), NOW)
+      ).toBe(false);
+    });
+
+    it('is on after activeAt', () => {
+      expect(
+        evaluate(feature({ activeAt: '2026-09-18T11:00:00Z' }), NOW)
+      ).toBe(true);
+    });
+
+    // The window is half-open: the comparison is `now < activeAt`.
+    it('is on at exactly activeAt', () => {
+      expect(
+        evaluate(feature({ activeAt: '2026-09-18T12:00:00Z' }), NOW)
+      ).toBe(true);
+    });
+  });
+
+  describe('disabledAt', () => {
+    it('is on before disabledAt', () => {
+      expect(
+        evaluate(feature({ disabledAt: '2026-09-18T13:00:00Z' }), NOW)
+      ).toBe(true);
+    });
+
+    it('is off after disabledAt', () => {
+      expect(
+        evaluate(feature({ disabledAt: '2026-09-18T11:00:00Z' }), NOW)
+      ).toBe(false);
+    });
+
+    // The comparison is `now >= disabledAt`, so the boundary is off -- the
+    // opposite of the activeAt boundary.
+    it('is off at exactly disabledAt', () => {
+      expect(
+        evaluate(feature({ disabledAt: '2026-09-18T12:00:00Z' }), NOW)
+      ).toBe(false);
+    });
+  });
+
+  describe('both bounds', () => {
+    const windowed = feature({
+      activeAt: '2026-09-18T10:00:00Z',
+      disabledAt: '2026-09-18T14:00:00Z',
+    });
+
+    it('is on inside the window', () => {
+      expect(evaluate(windowed, NOW)).toBe(true);
+    });
+
+    it('is off before the window', () => {
+      expect(evaluate(windowed, Date.parse('2026-09-18T09:00:00Z'))).toBe(false);
+    });
+
+    it('is off after the window', () => {
+      expect(evaluate(windowed, Date.parse('2026-09-18T15:00:00Z'))).toBe(false);
+    });
+
+    // Not a special case: the bounds simply never overlap.
+    it('is off everywhere when activeAt is after disabledAt', () => {
+      const inverted = feature({
+        activeAt: '2026-09-18T14:00:00Z',
+        disabledAt: '2026-09-18T10:00:00Z',
+      });
+
+      for (const at of [
+        '2026-09-18T09:00:00Z',
+        '2026-09-18T12:00:00Z',
+        '2026-09-18T16:00:00Z',
+      ]) {
+        expect(evaluate(inverted, Date.parse(at))).toBe(false);
+      }
+    });
+  });
+
+  describe('timezone offsets', () => {
+    it('converts an offset to the same instant as UTC', () => {
+      // 14:00+02:00 is 12:00Z, which is exactly NOW, so the activeAt boundary
+      // is inclusive and the feature is on.
+      expect(
+        evaluate(feature({ activeAt: '2026-09-18T14:00:00+02:00' }), NOW)
+      ).toBe(true);
+    });
+
+    it('respects a negative offset', () => {
+      // 08:00-05:00 is 13:00Z, one hour after NOW, so it is not active yet.
+      expect(
+        evaluate(feature({ activeAt: '2026-09-18T08:00:00-05:00' }), NOW)
+      ).toBe(false);
+    });
+  });
+
+  describe('unset and invalid bounds are ignored', () => {
+    it.each([
+      ['empty string', ''],
+      ['null', null],
+      ['undefined', undefined],
+    ])('ignores %s', (_label, value) => {
+      const f = feature({
+        activeAt: value as string,
+        disabledAt: value as string,
+      });
+      expect(evaluate(f, NOW)).toBe(true);
+    });
+
+    // Rejected on purpose: JavaScript reads a bare date as UTC midnight and an
+    // offset-less timestamp as local time, while most other languages read
+    // both as local. Accepting them would make a feature flip at a different
+    // instant depending on the port.
+    it.each([
+      ['a bare date', '2026-09-18'],
+      ['no offset', '2026-09-18T15:00:00'],
+      ['garbage', 'not-a-date'],
+      ['a unix timestamp', '1758196800'],
+      ['a slash date', '2026/09/18'],
+    ])('ignores %s in activeAt', (_label, value) => {
+      // Would be off if parsed as a future bound; ignoring it leaves the
+      // feature on.
+      expect(evaluate(feature({ activeAt: value }), NOW)).toBe(true);
+    });
+
+    // Date.parse does not reject an impossible calendar date, it rolls it
+    // over: 2027-02-30 becomes 2027-03-02. The date must therefore be in the
+    // future, or the rolled-over value lands in the past and the activeAt
+    // check passes for the wrong reason.
+    it.each([
+      ['a day past the end of February', '2027-02-30T00:00:00Z'],
+      ['the 31st of a 30-day month', '2027-04-31T00:00:00Z'],
+      ['month 13', '2027-13-01T00:00:00Z'],
+      ['day zero', '2027-01-00T00:00:00Z'],
+      ['February 29 in a non-leap year', '2027-02-29T00:00:00Z'],
+      ['hour 24', '2027-01-01T24:00:00Z'],
+      ['minute 60', '2027-01-01T00:60:00Z'],
+    ])('ignores %s', (_label, value) => {
+      expect(evaluate(feature({ activeAt: value }), NOW)).toBe(true);
+      expect(parseTimestamp(value)).toBeUndefined();
+    });
+
+    it('accepts February 29 in a leap year', () => {
+      expect(parseTimestamp('2028-02-29T00:00:00Z')).toBe(
+        Date.parse('2028-02-29T00:00:00Z')
+      );
+    });
+
+    // RFC 3339 permits second 60 for a leap second, but Date.parse returns
+    // NaN for it, so the value is ignored like any other unusable bound. The
+    // range check lets it through and the NaN guard catches it; asserted here
+    // so the two stay consistent.
+    it('ignores a leap second, which Date.parse cannot represent', () => {
+      expect(parseTimestamp('2026-12-31T23:59:60Z')).toBeUndefined();
+      expect(
+        evaluate(feature({ activeAt: '2026-12-31T23:59:60Z' }), NOW)
+      ).toBe(true);
+    });
+
+    it('never throws on malformed input', () => {
+      expect(() =>
+        evaluate(feature({ activeAt: 'x', disabledAt: 'y' }), NOW)
+      ).not.toThrow();
+    });
+  });
+
+  describe('fractional seconds', () => {
+    it('accepts them', () => {
+      expect(
+        evaluate(feature({ disabledAt: '2026-09-18T12:00:00.001Z' }), NOW)
+      ).toBe(true);
+    });
+  });
+});
+
+describe('parseTimestamp', () => {
+  it('returns the epoch milliseconds for a valid timestamp', () => {
+    expect(parseTimestamp('2026-09-18T12:00:00Z')).toBe(
+      Date.parse('2026-09-18T12:00:00Z')
+    );
+  });
+
+  it.each([undefined, null, ''])('returns undefined for %p', (value) => {
+    expect(parseTimestamp(value)).toBeUndefined();
+  });
+
+  it('returns undefined for a format without an offset', () => {
+    expect(parseTimestamp('2026-09-18T12:00:00')).toBeUndefined();
+  });
+
+  it('accepts a lowercase t and z', () => {
+    expect(parseTimestamp('2026-09-18t12:00:00z')).toBe(
+      Date.parse('2026-09-18T12:00:00Z')
+    );
+  });
+});
+
+describe('systemClock', () => {
+  it('reports the current time', () => {
+    const before = Date.now();
+    const reading = systemClock();
+    expect(reading).toBeGreaterThanOrEqual(before);
+    expect(reading).toBeLessThanOrEqual(Date.now());
+  });
+
+  it('is the default, so a provider works without one', () => {
+    const clock: Clock = () => 0;
+    expect(typeof clock()).toBe('number');
+  });
+});

package/src/test/injectable-clock.spec.ts

@@ -0,0 +1,112 @@
+import { Clock } from '../evaluate';
+import { Feature } from '../FeatureToggle';
+import { ApiServiceFeatureProvider } from '../examples/ApiServiceFeatureProvider';
+import { LocalStorageFeatureProvider } from '../examples/LocalStorageFeatureProvider';
+
+/**
+ * The clock has to be injectable for the conformance suite: every case there
+ * carries its own `now`, and an adapter cannot set it if the providers read
+ * `Date.now()` directly.
+ *
+ * These tests pin that down, and pin down that both feature-shaped providers
+ * answer identically -- the point of moving the logic into evaluate().
+ */
+describe('injectable clock', () => {
+  const windowed: Feature = {
+    key: 'windowed',
+    value: 'true',
+    activeAt: '2026-09-18T10:00:00Z',
+    disabledAt: '2026-09-18T14:00:00Z',
+  };
+
+  const at = (iso: string): Clock => () => Date.parse(iso);
+
+  /** A provider holding `windowed`, without touching the filesystem. */
+  const localAt = (iso: string) => {
+    const provider = new LocalStorageFeatureProvider('', at(iso));
+    provider.data = { windowed };
+    return provider;
+  };
+
+  /** The same, for the API provider, without touching the network. */
+  const apiAt = (iso: string) => {
+    const provider = new ApiServiceFeatureProvider('', '', at(iso));
+    provider.data = { windowed };
+    return provider;
+  };
+
+  describe('LocalStorageFeatureProvider', () => {
+    it('is off before the window', () => {
+      expect(localAt('2026-09-18T09:59:59Z').isEnabled('windowed')).toBe(false);
+    });
+
+    it('is on inside the window', () => {
+      expect(localAt('2026-09-18T12:00:00Z').isEnabled('windowed')).toBe(true);
+    });
+
+    it('is off after the window', () => {
+      expect(localAt('2026-09-18T14:00:00Z').isEnabled('windowed')).toBe(false);
+    });
+  });
+
+  describe('ApiServiceFeatureProvider', () => {
+    it('is off before the window', () => {
+      expect(apiAt('2026-09-18T09:59:59Z').isEnabled('windowed')).toBe(false);
+    });
+
+    it('is on inside the window', () => {
+      expect(apiAt('2026-09-18T12:00:00Z').isEnabled('windowed')).toBe(true);
+    });
+
+    it('is off after the window', () => {
+      expect(apiAt('2026-09-18T14:00:00Z').isEnabled('windowed')).toBe(false);
+    });
+  });
+
+  // Before this change each provider carried its own copy of the logic, so
+  // they could drift apart unnoticed. Now they must agree everywhere.
+  it('both feature providers agree at every instant', () => {
+    for (const iso of [
+      '2026-09-18T09:00:00Z',
+      '2026-09-18T10:00:00Z',
+      '2026-09-18T12:00:00Z',
+      '2026-09-18T13:59:59Z',
+      '2026-09-18T14:00:00Z',
+      '2026-09-18T20:00:00Z',
+    ]) {
+      expect(localAt(iso).isEnabled('windowed')).toBe(
+        apiAt(iso).isEnabled('windowed')
+      );
+    }
+  });
+
+  it('the same provider answers differently as its clock advances', () => {
+    let now = Date.parse('2026-09-18T09:00:00Z');
+    const provider = new LocalStorageFeatureProvider('', () => now);
+    provider.data = { windowed };
+
+    expect(provider.isEnabled('windowed')).toBe(false);
+
+    now = Date.parse('2026-09-18T12:00:00Z');
+    expect(provider.isEnabled('windowed')).toBe(true);
+
+    now = Date.parse('2026-09-18T15:00:00Z');
+    expect(provider.isEnabled('windowed')).toBe(false);
+  });
+
+  it('defaults to the system clock when none is given', () => {
+    const provider = new LocalStorageFeatureProvider('');
+    provider.data = {
+      open: { key: 'open', value: 'true', activeAt: '', disabledAt: '' },
+      expired: {
+        key: 'expired',
+        value: 'true',
+        activeAt: '',
+        disabledAt: '2000-01-01T00:00:00Z',
+      },
+    };
+
+    expect(provider.isEnabled('open')).toBe(true);
+    expect(provider.isEnabled('expired')).toBe(false);
+  });
+});