@tehw0lf/yaft 0.0.12 → 0.0.15

package/README.md

@@ -100,6 +100,12 @@ export type Feature = {
 
 ## Evaluation rules
 
+These rules are not this library's own: they are
+[yaft-conformance](https://github.com/tehw0lf/yaft-conformance), the shared
+specification every YaFT implementation is checked against. This port passes
+the whole suite (see [Conformance](#conformance) below), so a feature evaluates
+identically here and in any other port.
+
 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.
 
@@ -142,6 +148,31 @@ const provider = new LocalStorageFeatureProvider(
 
 The clock defaults to the system time, so existing code needs no change.
 
+## Conformance
+
+The rules above are specified once, language-neutrally, in
+[yaft-conformance](https://github.com/tehw0lf/yaft-conformance), and this port
+is tested against that suite rather than only against its own expectations.
+
+The version is pinned in `conformance.lock`:
+
+```
+version=v1.1.0
+sha256=d83ff1c960ad29830c00b57727591da628f4323b777faea245f603565d1c9ae9
+```
+
+`npm test` fetches that release, verifies the checksum and unpacks it before
+Jest runs, so there is no separate step to forget and no way to get a green run
+against stale cases. Upgrading the suite is a one-line change to that file,
+visible in review.
+
+The checksum is not decoration: a Git tag can be moved, and without verifying
+the asset a port's tests could change with no diff at all.
+
+The adapter lives in `src/test/conformance-adapter/`. It fails loudly on a case
+whose `target`, `toggle` or `expected` it does not implement, rather than
+skipping it -- a silently skipped case is a rule that nothing enforces.
+
 # Licenses
 
 - Code: MIT License

package/conformance.lock

@@ -0,0 +1,2 @@
+version=v1.1.0
+sha256=d83ff1c960ad29830c00b57727591da628f4323b777faea245f603565d1c9ae9

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
   "scripts": {
     "build": "tsc && cp package.json README.md logo.svg dist/yaft/ && npm pkg delete devDependencies --prefix dist/yaft",
-    "test": "npx jest"
+    "test": "npx jest",
+    "conformance:fetch": "./scripts/fetch-conformance.sh src/test/conformance",
+    "pretest": "npm run conformance:fetch"
   },
   "repository": {
     "type": "git",

package/scripts/fetch-conformance.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Fetches the YaFT conformance suite pinned in conformance.lock.
+#
+# Copy this into a port, next to a conformance.lock of the form:
+#
+#   version=v1.0.0
+#   sha256=<checksum of cases.tar.gz>
+#
+# The checksum is not optional. A Git tag can be moved; verifying the asset is
+# what stops a port's tests from changing without a diff.
+#
+# Usage: scripts/fetch-conformance.sh [target-dir]   (default: src/test/conformance)
+#
+# Set the default to wherever the port's adapter reads the cases from. Ports
+# differ -- yaft-ts uses src/test/conformance -- and a default that does not
+# match leaves the next test run reporting missing cases.
+
+set -euo pipefail
+
+REPO="tehw0lf/yaft-conformance"
+LOCK="${LOCK:-conformance.lock}"
+TARGET="${1:-src/test/conformance}"
+
+if [[ ! -f "$LOCK" ]]; then
+  echo "error: $LOCK not found; run from the port's root" >&2
+  exit 1
+fi
+
+version="$(grep -E '^version=' "$LOCK" | cut -d= -f2-)"
+expected="$(grep -E '^sha256=' "$LOCK" | cut -d= -f2-)"
+
+if [[ -z "$version" || -z "$expected" ]]; then
+  echo "error: $LOCK needs both version= and sha256=" >&2
+  exit 1
+fi
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+url="https://github.com/${REPO}/releases/download/${version}/cases.tar.gz"
+echo "fetching conformance suite ${version}"
+curl --fail --location --silent --show-error --output "$tmp/cases.tar.gz" "$url"
+
+# sha256sum is GNU coreutils and is not present on macOS; shasum ships with
+# both. Preferring sha256sum keeps Linux CI on the faster binary.
+if command -v sha256sum >/dev/null 2>&1; then
+  actual="$(sha256sum "$tmp/cases.tar.gz" | cut -d' ' -f1)"
+elif command -v shasum >/dev/null 2>&1; then
+  actual="$(shasum -a 256 "$tmp/cases.tar.gz" | cut -d' ' -f1)"
+else
+  echo "error: neither sha256sum nor shasum found; cannot verify the download" >&2
+  exit 1
+fi
+if [[ "$actual" != "$expected" ]]; then
+  echo "error: checksum mismatch for cases.tar.gz" >&2
+  echo "  expected $expected" >&2
+  echo "  actual   $actual" >&2
+  echo "The tag may have been moved. Do not update the lock without reading the diff." >&2
+  exit 1
+fi
+
+rm -rf "$TARGET"
+mkdir -p "$TARGET"
+tar --extract --gzip --file "$tmp/cases.tar.gz" --directory "$TARGET"
+
+echo "conformance suite ${version} unpacked into ${TARGET}"

package/src/FeatureToggle.ts

@@ -34,14 +34,27 @@ export function FeatureToggle(key: string, fallback?: any) {
       // Method
       const originalMethod = descriptor.value;
 
+      // An async method must keep returning a promise when it is switched
+      // off, or `await` at the call site breaks on a plain undefined. The
+      // empty class shell below already makes this distinction; without it
+      // here, turning a feature off would throw inside unrelated code.
+      const isAsync =
+        originalMethod?.[Symbol.toStringTag] === "AsyncFunction";
+
       descriptor.value = function (...args: any[]) {
         const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
         if (isEnabled) {
           return originalMethod.apply(this, args);
         } else {
-          return fallback !== undefined
-            ? fallback.apply(this, args as [])
-            : (() => {}).apply(this, args as []);
+          if (fallback !== undefined) {
+            const result = fallback.apply(this, args as []);
+            // A synchronous fallback on an async method would otherwise hand
+            // back a plain value, breaking the promise the signature
+            // advertises. Promise.resolve passes an existing promise through
+            // unchanged, so an async fallback is unaffected.
+            return isAsync ? Promise.resolve(result) : result;
+          }
+          return isAsync ? Promise.resolve() : undefined;
         }
       };
       return descriptor;

package/src/examples/ApiServiceBooleanProvider.ts

@@ -1,6 +1,7 @@
 import axios from "axios";
 
 import { FeatureProvider } from "../FeatureToggle";
+import { normaliseCollection } from "../mapping";
 
 export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
   apiUrl: string;
@@ -30,22 +31,28 @@ export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
   async getConfig(configPathOrUrl: string): Promise<void> {
     try {
       const response = await axios.get(configPathOrUrl);
-      // Handle Go backend response format
-      const featuresArray = response.data.toggles || response.data.value || [];
-      
-      // Convert array to keyed boolean object and handle capitalized field names
+
+      // A keyed boolean object is already in this provider's shape and is
+      // taken as-is; anything else is a feature-shaped response and goes
+      // through the core normaliser, so the two providers cannot disagree
+      // about what a response means.
+      if (isKeyedBooleans(response.data)) {
+        this.data = response.data;
+        return;
+      }
+
+      // Only the value matters here. The boolean shape has no time logic by
+      // design (R21), so a feature collapses to whether its value is exactly
+      // "true" -- activeAt and disabledAt are dropped.
+      //
+      // That is a real trap when this provider is pointed at a backend that
+      // schedules toggles: the window is then enforced only by the backend's
+      // cron job, which lags by up to a minute, instead of being evaluated
+      // locally. Use ApiServiceFeatureProvider when the toggles carry dates.
+      const features = normaliseCollection(response.data);
       this.data = {};
-      if (Array.isArray(featuresArray)) {
-        featuresArray.forEach((feature: any) => {
-          const key = feature.key || feature.Key;
-          const value = feature.value || feature.Value;
-          if (key) {
-            this.data[key] = value === 'true' || value === true;
-          }
-        });
-      } else {
-        // Fallback for object format
-        this.data = featuresArray;
+      for (const [key, feature] of Object.entries(features)) {
+        this.data[key] = feature.value === 'true';
       }
     } catch (error) {
       console.error("Failed to fetch feature toggle from API:", error);
@@ -58,3 +65,18 @@ export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
     return feature;
   }
 }
+
+/**
+ * True when the payload is already `{ "myToggle": true }`.
+ *
+ * Distinguishing this from a feature-shaped response matters: running a keyed
+ * boolean object through the feature normaliser would look for a `key` field,
+ * find none and discard every entry.
+ */
+function isKeyedBooleans(data: unknown): data is Record<string, boolean> {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return false;
+  }
+  const values = Object.values(data as Record<string, unknown>);
+  return values.length > 0 && values.every((v) => typeof v === 'boolean');
+}

package/src/examples/ApiServiceFeatureProvider.ts

@@ -1,6 +1,7 @@
 import axios from "axios";
 
 import { Clock, evaluate, systemClock } from "../evaluate";
+import { normaliseCollection } from "../mapping";
 import { Feature, FeatureProvider } from "../FeatureToggle";
 
 export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
@@ -37,28 +38,9 @@ export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
   async getConfig(configPathOrUrl: string): Promise<void> {
     try {
       const response = await axios.get(configPathOrUrl);
-      // Handle Go backend response format
-      const featuresArray = response.data.toggles || response.data.value || [];
-      
-      // Convert array to keyed object and handle capitalized field names
-      this.data = {};
-      if (Array.isArray(featuresArray)) {
-        featuresArray.forEach((feature: any) => {
-          const normalizedFeature = {
-            key: feature.key || feature.Key,
-            value: feature.value || feature.Value,
-            activeAt: feature.activeAt || feature.ActiveAt,
-            disabledAt: feature.disabledAt || feature.DisabledAt,
-            tags: feature.tags || feature.Tags || [],
-          };
-          if (normalizedFeature.key) {
-            this.data[normalizedFeature.key] = normalizedFeature;
-          }
-        });
-      } else {
-        // Fallback for object format
-        this.data = featuresArray;
-      }
+      // The mapping rules live in the core, next to the evaluation rules,
+      // rather than being reimplemented per provider.
+      this.data = normaliseCollection(response.data);
     } catch (error) {
       console.error("Failed to fetch feature toggle from API:", error);
     }

package/src/index.ts

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

package/src/mapping.ts

@@ -0,0 +1,92 @@
+import { Feature } from './FeatureToggle';
+
+/**
+ * Turns a backend response into provider data.
+ *
+ * This is the single definition of YaFT's mapping rules, the way `evaluate` is
+ * the single definition of the evaluation rules. Providers call it instead of
+ * unpacking responses themselves, so every provider -- and every port that
+ * mirrors it -- agrees on what a response means.
+ */
+
+/** A raw entry as it arrives over the wire, in either field spelling. */
+type RawFeature = Record<string, unknown>;
+
+/**
+ * Reads a field by presence, not by truthiness.
+ *
+ * The obvious `raw.value || raw.Value` is wrong: a present but empty value
+ * falls through to the other spelling, so a feature stored as `""` reads as
+ * whatever the capitalised field holds. An off feature then reports on. The
+ * same trap applies to `tags: []`.
+ *
+ * Backends from 0.2.0 on send only the lowercase spelling; the capitalised one
+ * is read because instances before that are still around.
+ */
+function field(raw: RawFeature, lower: string, upper: string): unknown {
+  if (lower in raw) return raw[lower];
+  if (upper in raw) return raw[upper];
+  return undefined;
+}
+
+/**
+ * Normalises a date field. The backend sends `null` for an unset bound and
+ * local fixtures use `""`; both mean "no bound", and `evaluate` ignores either.
+ */
+function date(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+/** Normalises one entry into a `Feature`, whichever spelling it arrived in. */
+export function normaliseFeature(raw: RawFeature): Feature {
+  const tags = field(raw, 'tags', 'Tags');
+
+  return {
+    key: String(field(raw, 'key', 'Key') ?? ''),
+    value: String(field(raw, 'value', 'Value') ?? ''),
+    activeAt: date(field(raw, 'activeAt', 'ActiveAt')),
+    disabledAt: date(field(raw, 'disabledAt', 'DisabledAt')),
+    // Filtered rather than asserted: `as string[]` is a compile-time claim
+    // that a backend sending a mixed array would quietly break, handing
+    // callers a non-string through a field typed as string.
+    tags: Array.isArray(tags)
+      ? tags.filter((tag): tag is string => typeof tag === 'string')
+      : [],
+  };
+}
+
+/**
+ * Normalises a whole response into features keyed by their key.
+ *
+ * Three envelopes are accepted, because the backend uses all three:
+ *
+ * - `{ "toggles": [...] }` for a UUID group;
+ * - `{ "value": [...] }`, the same thing under a different name;
+ * - a flat object for a single toggle.
+ *
+ * An entry without a usable key is skipped rather than stored under `""`,
+ * where `isEnabled("")` could reach it.
+ */
+export function normaliseCollection(response: unknown): Record<string, Feature> {
+  if (response === null || typeof response !== 'object') return {};
+
+  const body = response as Record<string, unknown>;
+  const collection = Array.isArray(body['toggles'])
+    ? body['toggles']
+    : Array.isArray(body['value'])
+      ? body['value']
+      : undefined;
+
+  // A single toggle comes back flat, not wrapped. Older code only handled the
+  // collections and dropped this shape entirely.
+  const entries = collection ?? [body];
+
+  const data: Record<string, Feature> = {};
+  for (const entry of entries) {
+    if (entry === null || typeof entry !== 'object') continue;
+
+    const feature = normaliseFeature(entry as RawFeature);
+    if (feature.key !== '') data[feature.key] = feature;
+  }
+  return data;
+}

package/src/test/conformance-adapter/cases.ts

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Loads the conformance case files.
+ *
+ * The cases live in `cases/`, fetched by `scripts/fetch-conformance.sh` from
+ * the version pinned in `conformance.lock`. They are not checked in: the lock
+ * file plus its checksum is what makes a suite bump a reviewable one-line
+ * diff, and a committed copy would drift from the tag it claims to be.
+ */
+
+const CASES_DIR = join(__dirname, '..', 'conformance', 'cases');
+
+/** A rule id from SPEC.md, such as `R5` or `R22a`. */
+export type Rule = string;
+
+interface CaseFile<T> {
+  suite: string;
+  version: number;
+  cases: T[];
+}
+
+export interface EvaluationCase {
+  name: string;
+  rules: Rule[];
+  why?: string;
+  now: string;
+  features: Record<string, unknown>;
+  key: string;
+  expected: boolean;
+}
+
+export interface DecoratorCase {
+  name: string;
+  rules: Rule[];
+  why?: string;
+  target: 'class' | 'method' | 'async-method';
+  toggle: 'on' | 'off' | 'on-then-off' | 'off-then-on' | 'no-provider';
+  fallback: 'none' | 'class' | 'method';
+  expected:
+    | 'original'
+    | 'fallback'
+    | 'nothing'
+    | 'resolved-nothing'
+    | 'empty-shell'
+    | 'decoration-error';
+  assertions?: ('same-arguments' | 'same-receiver')[];
+}
+
+export interface MappingCase {
+  name: string;
+  rules: Rule[];
+  why?: string;
+  shape: 'feature' | 'boolean';
+  response: unknown;
+  expected: Record<string, unknown>;
+}
+
+function load<T>(suite: string): CaseFile<T> {
+  const path = join(CASES_DIR, `${suite}.json`);
+
+  if (!existsSync(path)) {
+    throw new Error(
+      `Conformance cases missing at ${path}.\n` +
+        'Run scripts/fetch-conformance.sh before the tests; CI does this in a ' +
+        'dedicated step.'
+    );
+  }
+
+  const file = JSON.parse(readFileSync(path, 'utf8')) as CaseFile<T>;
+  if (file.suite !== suite) {
+    throw new Error(`${path} declares suite "${file.suite}", expected "${suite}"`);
+  }
+  return file;
+}
+
+export const evaluationCases = () => load<EvaluationCase>('evaluation').cases;
+export const decoratorCases = () => load<DecoratorCase>('decorator').cases;
+export const mappingCases = () => load<MappingCase>('mapping').cases;
+
+/**
+ * Names a case for the test output, so a failure points at a rule without
+ * anyone having to open the case file.
+ */
+export function title(c: { name: string; rules: Rule[] }): string {
+  return `${c.name} [${c.rules.join(', ')}]`;
+}
+
+/**
+ * Rejects a value the adapter does not know how to handle.
+ *
+ * A case whose `target`, `toggle` or `expected` this adapter has never seen is
+ * a rule that nothing enforces here. Skipping it would leave the suite looking
+ * green while a requirement goes unchecked, so an unknown value is a failure
+ * instead -- it means the suite grew and the adapter has to catch up.
+ */
+export function unsupported(kind: string, value: string, caseName: string): never {
+  throw new Error(
+    `Case "${caseName}" uses ${kind} "${value}", which this adapter does not ` +
+      'implement. The conformance suite has gained a case this port does not ' +
+      'cover yet -- extend the adapter rather than skipping the case.'
+  );
+}

package/src/test/conformance-adapter/decorator.spec.ts

@@ -0,0 +1,376 @@
+import {
+  FeatureProvider,
+  FeatureToggle,
+  FeatureToggleBase,
+} from '../../FeatureToggle';
+import { DecoratorCase, decoratorCases, title, unsupported } from './cases';
+
+/**
+ * Runs the shared decorator cases against this port.
+ *
+ * Unlike the evaluation cases these are not input/output pairs -- "the
+ * fallback receives the same receiver" cannot be expressed as JSON. Each case
+ * names a scenario and an outcome in port-neutral terms, and this file maps
+ * those onto TypeScript decorators.
+ *
+ * The mapping is deliberately explicit: an unknown `target`, `toggle` or
+ * `expected` throws rather than being skipped, because a silently skipped case
+ * is a rule nothing enforces.
+ */
+
+const KEY = 'conformanceToggle';
+
+/** A provider whose answer can be changed between decoration and call. */
+class SwitchableProvider implements FeatureProvider<boolean> {
+  data: Record<string, boolean> = {};
+  constructor(private enabled: boolean) {}
+  getConfig(): void {
+    /* nothing to load */
+  }
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+  set(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+}
+
+/**
+ * Installs a provider and returns it, or clears the provider entirely for the
+ * `no-provider` case.
+ *
+ * `toggle` also encodes when the value changes: `on-then-off` is on while the
+ * class or method is decorated and off by the time it is used, which is what
+ * separates "evaluated once" from "evaluated per call".
+ */
+function setUp(toggle: DecoratorCase['toggle'], caseName: string) {
+  switch (toggle) {
+    case 'on':
+    case 'on-then-off':
+      return install(true);
+    case 'off':
+    case 'off-then-on':
+      return install(false);
+    case 'no-provider':
+      // The abstract base holds the provider statically; clearing it is how a
+      // misconfigured application looks.
+      (FeatureToggleBase as { featureProvider?: unknown }).featureProvider =
+        undefined;
+      return undefined;
+    default:
+      return unsupported('toggle', toggle, caseName);
+  }
+}
+
+function install(enabled: boolean): SwitchableProvider {
+  const provider = new SwitchableProvider(enabled);
+  FeatureToggleBase.featureProvider = provider;
+  return provider;
+}
+
+/** Applies the flip that `on-then-off` / `off-then-on` describe. */
+function flipIfTwoPhase(
+  toggle: DecoratorCase['toggle'],
+  provider: SwitchableProvider | undefined
+): void {
+  if (toggle === 'on-then-off') provider?.set(false);
+  if (toggle === 'off-then-on') provider?.set(true);
+}
+
+const ORIGINAL = 'original';
+const FALLBACK = 'fallback';
+
+describe('conformance: decorator', () => {
+  const cases = decoratorCases();
+  let savedProvider: FeatureProvider<unknown>;
+
+  beforeAll(() => {
+    savedProvider = FeatureToggleBase.featureProvider;
+  });
+
+  afterEach(() => {
+    FeatureToggleBase.featureProvider = savedProvider;
+  });
+
+  it('loads the suite', () => {
+    expect(cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of cases) {
+    it(title(c), async () => {
+      switch (c.target) {
+        case 'method':
+          await runMethodCase(c);
+          break;
+        case 'async-method':
+          await runAsyncMethodCase(c);
+          break;
+        case 'class':
+          runClassCase(c);
+          break;
+        default:
+          unsupported('target', c.target, c.name);
+      }
+    });
+  }
+});
+
+async function runMethodCase(c: DecoratorCase): Promise<void> {
+  if (c.toggle === 'no-provider') {
+    expectDecorationError(c);
+    return;
+  }
+
+  const provider = setUp(c.toggle, c.name) as SwitchableProvider;
+
+  // Recorded by whichever implementation runs, so the assertions can tell them
+  // apart and check what the fallback was handed.
+  let ran = '';
+  let sawArgs: unknown[] = [];
+  let sawThis: unknown;
+
+  function fallbackMethod(this: unknown, ...args: unknown[]) {
+    ran = FALLBACK;
+    sawArgs = args;
+    sawThis = this;
+    return FALLBACK;
+  }
+
+  const fallback = c.fallback === 'method' ? fallbackMethod : undefined;
+  if (c.fallback === 'class') {
+    unsupported('fallback', 'class on a method target', c.name);
+  }
+
+  class Subject {
+    marker = 'subject';
+
+    @FeatureToggle(KEY, fallback)
+    run(..._args: unknown[]) {
+      ran = ORIGINAL;
+      return ORIGINAL;
+    }
+  }
+
+  flipIfTwoPhase(c.toggle, provider);
+
+  const instance = new Subject();
+  const result = instance.run('a', 1);
+
+  switch (c.expected) {
+    case 'original':
+      expect(ran).toBe(ORIGINAL);
+      expect(result).toBe(ORIGINAL);
+      break;
+
+    case 'fallback':
+      expect(ran).toBe(FALLBACK);
+      expect(result).toBe(FALLBACK);
+      break;
+
+    case 'nothing':
+      // The language's empty result; in TypeScript that is undefined.
+      expect(ran).toBe('');
+      expect(result).toBeUndefined();
+      break;
+
+    default:
+      unsupported('expected', c.expected, c.name);
+  }
+
+  for (const assertion of c.assertions ?? []) {
+    switch (assertion) {
+      case 'same-arguments':
+        expect(sawArgs).toEqual(['a', 1]);
+        break;
+      case 'same-receiver':
+        expect(sawThis).toBe(instance);
+        break;
+      default:
+        unsupported('assertion', assertion, c.name);
+    }
+  }
+}
+
+async function runAsyncMethodCase(c: DecoratorCase): Promise<void> {
+  if (c.toggle === 'no-provider') {
+    expectDecorationError(c);
+    return;
+  }
+
+  const provider = setUp(c.toggle, c.name) as SwitchableProvider;
+  let ran = '';
+
+  class Subject {
+    @FeatureToggle(KEY)
+    async run() {
+      ran = ORIGINAL;
+      return ORIGINAL;
+    }
+  }
+
+  flipIfTwoPhase(c.toggle, provider);
+
+  const result = new Subject().run();
+
+  switch (c.expected) {
+    case 'original':
+      await expect(result).resolves.toBe(ORIGINAL);
+      expect(ran).toBe(ORIGINAL);
+      break;
+
+    case 'resolved-nothing':
+      // An await at the call site must not break, so the empty result has to
+      // be an already-resolved promise rather than a null value.
+      expect(result).toBeInstanceOf(Promise);
+      await expect(result).resolves.toBeUndefined();
+      expect(ran).toBe('');
+      break;
+
+    default:
+      unsupported('expected', c.expected, c.name);
+  }
+}
+
+function runClassCase(c: DecoratorCase): void {
+  if (c.toggle === 'no-provider') {
+    expectDecorationError(c);
+    return;
+  }
+
+  const provider = setUp(c.toggle, c.name) as SwitchableProvider;
+
+  class FallbackClass {
+    which() {
+      return FALLBACK;
+    }
+  }
+
+  const fallback = c.fallback === 'class' ? FallbackClass : undefined;
+  if (c.fallback === 'method') {
+    unsupported('fallback', 'method on a class target', c.name);
+  }
+
+  @FeatureToggle(KEY, fallback)
+  class Subject {
+    which() {
+      return ORIGINAL;
+    }
+  }
+
+  // A class is decided at decoration time, so this flip must have no effect --
+  // that is exactly what the two-phase cases check.
+  flipIfTwoPhase(c.toggle, provider);
+
+  const instance = new (Subject as unknown as new () => { which(): unknown })();
+
+  switch (c.expected) {
+    case 'original':
+      expect(instance.which()).toBe(ORIGINAL);
+      break;
+
+    case 'fallback':
+      expect(instance.which()).toBe(FALLBACK);
+      break;
+
+    case 'empty-shell':
+      // The shell still answers every method of the original, each returning
+      // nothing, so calling into a disabled class does not throw.
+      expect(instance.which()).toBeUndefined();
+      break;
+
+    default:
+      unsupported('expected', c.expected, c.name);
+  }
+}
+
+/**
+ * Cases the shared suite does not cover yet.
+ *
+ * R18 says an async method switched off must still return a promise, but the
+ * suite only states that for the no-fallback path. A synchronous fallback on
+ * an async method has the same problem -- the signature promises a promise and
+ * the caller gets a plain value -- so it is pinned down here until the suite
+ * grows a case for it.
+ */
+describe('async fallback keeps the promise contract', () => {
+  let saved: FeatureProvider<unknown>;
+
+  beforeAll(() => {
+    saved = FeatureToggleBase.featureProvider;
+  });
+  afterAll(() => {
+    FeatureToggleBase.featureProvider = saved;
+  });
+
+  it('wraps a synchronous fallback for an async method', async () => {
+    install(false);
+
+    function syncFallback() {
+      return FALLBACK;
+    }
+
+    class Subject {
+      @FeatureToggle(KEY, syncFallback)
+      async run() {
+        return ORIGINAL;
+      }
+    }
+
+    const result = new Subject().run();
+
+    expect(result).toBeInstanceOf(Promise);
+    await expect(result).resolves.toBe(FALLBACK);
+  });
+
+  it('passes an async fallback through without double-wrapping', async () => {
+    install(false);
+
+    async function asyncFallback() {
+      return FALLBACK;
+    }
+
+    class Subject {
+      @FeatureToggle(KEY, asyncFallback)
+      async run() {
+        return ORIGINAL;
+      }
+    }
+
+    await expect(new Subject().run()).resolves.toBe(FALLBACK);
+  });
+
+  it('leaves the fallback of a synchronous method untouched', () => {
+    install(false);
+
+    function syncFallback() {
+      return FALLBACK;
+    }
+
+    class Subject {
+      @FeatureToggle(KEY, syncFallback)
+      run() {
+        return ORIGINAL;
+      }
+    }
+
+    // Not a promise: wrapping here would change the contract of every
+    // synchronous fallback.
+    expect(new Subject().run()).toBe(FALLBACK);
+  });
+});
+
+/**
+ * The provider is missing, so decorating itself must fail.
+ *
+ * Deferring the error to the first call would turn a startup misconfiguration
+ * into a surprise in whichever code path happens to run first.
+ */
+function expectDecorationError(c: DecoratorCase): void {
+  setUp('no-provider', c.name);
+
+  if (c.expected !== 'decoration-error') {
+    unsupported('expected', c.expected, c.name);
+  }
+
+  expect(() => FeatureToggle(KEY)).toThrow('FeatureToggleProvider not set');
+}

package/src/test/conformance-adapter/evaluation.spec.ts

@@ -0,0 +1,31 @@
+import { Feature } from '../../FeatureToggle';
+import { evaluate } from '../../evaluate';
+import { evaluationCases, title } from './cases';
+
+/**
+ * Runs the shared evaluation cases against this port.
+ *
+ * These are the same cases every YaFT implementation has to pass, so a
+ * disagreement here is a disagreement with the spec, not a local test
+ * preference. Each case brings its own `now`, which is why the clock is
+ * injectable in the first place.
+ */
+describe('conformance: evaluation', () => {
+  const cases = evaluationCases();
+
+  it('loads the suite', () => {
+    expect(cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of cases) {
+    it(title(c), () => {
+      const now = Date.parse(c.now);
+      // A case whose own `now` does not parse would silently evaluate against
+      // NaN and pass or fail for the wrong reason.
+      expect(Number.isNaN(now)).toBe(false);
+
+      const feature = c.features[c.key] as Feature | null | undefined;
+      expect(evaluate(feature, now)).toBe(c.expected);
+    });
+  }
+});

package/src/test/conformance-adapter/mapping.spec.ts

@@ -0,0 +1,79 @@
+import { normaliseCollection, normaliseFeature } from '../../mapping';
+import { mappingCases, title, unsupported } from './cases';
+
+/**
+ * Runs the shared mapping cases against this port.
+ *
+ * These pin down how a backend response becomes provider data: which envelopes
+ * exist, how the two field spellings are reconciled, and that a present but
+ * empty value is kept rather than replaced.
+ */
+describe('conformance: mapping', () => {
+  const cases = mappingCases();
+
+  it('loads the suite', () => {
+    expect(cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of cases) {
+    it(title(c), () => {
+      switch (c.shape) {
+        case 'feature':
+          expect(normaliseCollection(c.response)).toEqual(c.expected);
+          break;
+
+        case 'boolean':
+          // The boolean shape is already keyed booleans; a provider stores it
+          // as-is and maps it straight onto isEnabled.
+          expect(c.response).toEqual(c.expected);
+          break;
+
+        default:
+          unsupported('shape', c.shape, c.name);
+      }
+    });
+  }
+});
+
+describe('normaliseFeature', () => {
+  it('keeps a present but empty value instead of falling through', () => {
+    // The reason this function exists: `f.value || f.Value` turns an off
+    // feature into an on one.
+    expect(
+      normaliseFeature({ key: 'f', value: '', Value: 'true' })
+    ).toEqual({
+      key: 'f',
+      value: '',
+      activeAt: '',
+      disabledAt: '',
+      tags: [],
+    });
+  });
+
+  it('drops a tag that is not a string', () => {
+    // `Feature.tags` is typed string[]; asserting rather than filtering would
+    // hand a caller a number through a field that promises a string.
+    expect(
+      normaliseFeature({ key: 'f', value: 'true', tags: ['ok', 42, null, 'fine'] })
+        .tags
+    ).toEqual(['ok', 'fine']);
+  });
+
+  it('reads the capitalised spelling older backends send', () => {
+    expect(
+      normaliseFeature({
+        Key: 'f',
+        Value: 'true',
+        ActiveAt: null,
+        DisabledAt: null,
+        Tags: ['beta'],
+      })
+    ).toEqual({
+      key: 'f',
+      value: 'true',
+      activeAt: '',
+      disabledAt: '',
+      tags: ['beta'],
+    });
+  });
+});