@opengroundplan/core 0.1.1

package/templates/layers/api-versioning/files/src/apiversion/settings.ts

@@ -0,0 +1,214 @@
+/**
+ * The only place an API-versioning default may appear. A version string, a header name,
+ * or a sunset date written at a call site is a bug — every other module reads this.
+ */
+
+export type VersionStrategy = 'path' | 'header' | 'query' | 'accept';
+
+export interface Deprecation {
+  version: string;
+  /** ISO date the deprecation was announced. Drives the RFC 9745 Deprecation header. */
+  announced: string;
+  /** ISO date the version may be removed. Drives the RFC 8594 Sunset header. */
+  sunset: string;
+}
+
+export interface ApiVersionSettings {
+  enabled: boolean;
+  strategy: VersionStrategy;
+  /** Oldest first. Declaration order is the ordering — no version grammar is parsed. */
+  supported: readonly string[];
+  /** Served when the client states none. Keep it the oldest supported version. */
+  defaultVersion: string;
+  strict: boolean;
+  headerName: string;
+  queryParam: string;
+  mediaType: string;
+  pathPrefix: string;
+  deprecations: readonly Deprecation[];
+  minSunsetDays: number;
+  policyUrl: string;
+  emitResponseHeader: boolean;
+  contractDir: string;
+}
+
+/** Exported so tooling can name a key without re-deriving the prefix. */
+export const ENV_PREFIX = '{{ apiVersionEnvPrefix }}';
+
+const PREFIX = ENV_PREFIX;
+
+const STRATEGIES: readonly VersionStrategy[] = ['path', 'header', 'query', 'accept'];
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+const MS_PER_DAY = 86_400_000;
+
+/** Typed defaults. Change a value here or in the environment, never at a call site. */
+const defaults: ApiVersionSettings = {
+  enabled: true,
+  strategy: '{{ apiVersionStrategy }}',
+  supported: '{{ apiVersionSupported }}'.split(','),
+  defaultVersion: '{{ apiVersionDefault }}',
+  strict: true,
+  headerName: '{{ apiVersionHeaderName }}',
+  queryParam: '{{ apiVersionQueryParam }}',
+  mediaType: '{{ apiVersionMediaType }}',
+  pathPrefix: '{{ apiVersionPathPrefix }}',
+  deprecations: [],
+  minSunsetDays: {{ apiVersionMinSunsetDays }},
+  policyUrl: '{{ apiVersionPolicyUrl }}',
+  emitResponseHeader: true,
+  contractDir: '{{ apiVersionContractDir }}',
+};
+
+type Env = Record<string, string | undefined>;
+
+export class ApiVersionConfigError extends Error {}
+
+function read(env: Env, key: string): string | undefined {
+  const value = env[`${PREFIX}_${key}`];
+  return value === undefined || value.trim() === '' ? undefined : value.trim();
+}
+
+/** Keys where "" is a real answer — no path prefix, no published policy — not "unset". */
+function readAllowEmpty(env: Env, key: string, fallback: string): string {
+  const value = env[`${PREFIX}_${key}`];
+  return value === undefined ? fallback : value.trim();
+}
+
+function bool(env: Env, key: string, fallback: boolean): boolean {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
+function integer(env: Env, key: string, fallback: number): number {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new ApiVersionConfigError(`${PREFIX}_${key} must be a non-negative integer, got "${raw}"`);
+  }
+  return parsed;
+}
+
+function list(env: Env, key: string, fallback: readonly string[]): readonly string[] {
+  const raw = read(env, key);
+  const source = raw === undefined ? fallback.join(',') : raw;
+  return source
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function strategy(env: Env, key: string, fallback: VersionStrategy): VersionStrategy {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  if (!STRATEGIES.includes(raw as VersionStrategy)) {
+    throw new ApiVersionConfigError(
+      `${PREFIX}_${key} must be one of ${STRATEGIES.join(', ')}, got "${raw}"`,
+    );
+  }
+  return raw as VersionStrategy;
+}
+
+/** `version:announced:sunset`, comma-separated. Both dates are mandatory by design. */
+function deprecations(env: Env, key: string, fallback: readonly Deprecation[]): readonly Deprecation[] {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  return raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [version, announced, sunset, ...rest] = entry.split(':').map((part) => part.trim());
+      if (!version || !announced || !sunset || rest.length > 0) {
+        throw new ApiVersionConfigError(
+          `${PREFIX}_${key} entry "${entry}" must be version:announced:sunset`,
+        );
+      }
+      for (const [label, value] of [
+        ['announcement', announced],
+        ['sunset', sunset],
+      ] as const) {
+        if (!ISO_DATE.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) {
+          throw new ApiVersionConfigError(
+            `${PREFIX}_${key}: ${version} has an invalid ${label} date "${value}", expected YYYY-MM-DD`,
+          );
+        }
+      }
+      return { version, announced, sunset };
+    });
+}
+
+export function epochSeconds(isoDate: string): number {
+  return Math.floor(Date.parse(`${isoDate}T00:00:00Z`) / 1000);
+}
+
+/**
+ * Rejects a policy that cannot be honoured, at startup. A default that is not in the
+ * supported set, or a sunset inside the notice window, is a promise already broken —
+ * finding it here costs a restart, finding it in the field costs the client.
+ */
+function validate(settings: ApiVersionSettings): ApiVersionSettings {
+  if (settings.supported.length === 0) {
+    throw new ApiVersionConfigError(`${PREFIX}_SUPPORTED must list at least one version`);
+  }
+  const duplicates = settings.supported.filter((v, i) => settings.supported.indexOf(v) !== i);
+  if (duplicates.length > 0) {
+    throw new ApiVersionConfigError(`${PREFIX}_SUPPORTED repeats: ${[...new Set(duplicates)].join(', ')}`);
+  }
+  if (!settings.supported.includes(settings.defaultVersion)) {
+    throw new ApiVersionConfigError(
+      `${PREFIX}_DEFAULT "${settings.defaultVersion}" is not in ${PREFIX}_SUPPORTED (${settings.supported.join(', ')})`,
+    );
+  }
+  for (const deprecation of settings.deprecations) {
+    if (!settings.supported.includes(deprecation.version)) {
+      throw new ApiVersionConfigError(
+        `${PREFIX}_DEPRECATED names "${deprecation.version}", which is not in ${PREFIX}_SUPPORTED`,
+      );
+    }
+    const notice =
+      (Date.parse(`${deprecation.sunset}T00:00:00Z`) - Date.parse(`${deprecation.announced}T00:00:00Z`)) /
+      MS_PER_DAY;
+    if (notice < settings.minSunsetDays) {
+      throw new ApiVersionConfigError(
+        `${deprecation.version} gives ${notice} days of notice, below ${PREFIX}_MIN_SUNSET_DAYS (${settings.minSunsetDays})`,
+      );
+    }
+  }
+  return settings;
+}
+
+export function loadApiVersionSettings(env: Env = process.env): ApiVersionSettings {
+  return validate({
+    enabled: bool(env, 'ENABLED', defaults.enabled),
+    strategy: strategy(env, 'STRATEGY', defaults.strategy),
+    supported: list(env, 'SUPPORTED', defaults.supported),
+    defaultVersion: read(env, 'DEFAULT') ?? defaults.defaultVersion,
+    strict: bool(env, 'STRICT', defaults.strict),
+    headerName: read(env, 'HEADER_NAME') ?? defaults.headerName,
+    queryParam: read(env, 'QUERY_PARAM') ?? defaults.queryParam,
+    mediaType: read(env, 'MEDIA_TYPE') ?? defaults.mediaType,
+    pathPrefix: readAllowEmpty(env, 'PATH_PREFIX', defaults.pathPrefix),
+    deprecations: deprecations(env, 'DEPRECATED', defaults.deprecations),
+    minSunsetDays: integer(env, 'MIN_SUNSET_DAYS', defaults.minSunsetDays),
+    policyUrl: readAllowEmpty(env, 'POLICY_URL', defaults.policyUrl),
+    emitResponseHeader: bool(env, 'EMIT_RESPONSE_HEADER', defaults.emitResponseHeader),
+    contractDir: read(env, 'CONTRACT_DIR') ?? defaults.contractDir,
+  });
+}
+
+let cached: ApiVersionSettings | undefined;
+
+/** Cached so the environment is read once and every caller shares one instance. */
+export function apiVersionSettings(): ApiVersionSettings {
+  cached ??= loadApiVersionSettings();
+  return cached;
+}
+
+/** Tests mutate the environment between cases; production never calls this. */
+export function resetApiVersionSettings(): void {
+  cached = undefined;
+}

package/templates/layers/api-versioning/files/src/apiversion/tests/apiversion.spec.ts

@@ -0,0 +1,162 @@
+import { describe as suite, expect, test } from 'vitest';
+import { diffContracts, diffShapes } from '../contract/diff.js';
+import { describe as describeShape, describeAll } from '../contract/shape.js';
+import { versionResponseHeaders } from '../headers.js';
+import { resolveVersion } from '../negotiate.js';
+import { ApiVersionConfigError, ENV_PREFIX, loadApiVersionSettings } from '../settings.js';
+import { createVersionPolicy } from '../versions.js';
+import type { ContractSnapshot } from '../contract/shape.js';
+
+const env = (overrides: Record<string, string>): Record<string, string> => {
+  const prefixed: Record<string, string> = {};
+  for (const [key, value] of Object.entries(overrides)) prefixed[`${ENV_PREFIX}_${key}`] = value;
+  return prefixed;
+};
+
+const policyFor = (overrides: Record<string, string>) =>
+  createVersionPolicy(loadApiVersionSettings(env({ SUPPORTED: 'v1,v2', DEFAULT: 'v1', ...overrides })));
+
+suite('settings', () => {
+  test('rejects a default that is not supported', () => {
+    expect(() => loadApiVersionSettings(env({ SUPPORTED: 'v1,v2', DEFAULT: 'v3' }))).toThrow(
+      ApiVersionConfigError,
+    );
+  });
+
+  test('rejects a sunset inside the notice window', () => {
+    expect(() =>
+      loadApiVersionSettings(
+        env({
+          SUPPORTED: 'v1,v2',
+          DEFAULT: 'v1',
+          MIN_SUNSET_DAYS: '180',
+          DEPRECATED: 'v1:2026-01-01:2026-03-01',
+        }),
+      ),
+    ).toThrow(/below/);
+  });
+
+  test('accepts a deprecation that gives enough notice', () => {
+    const settings = loadApiVersionSettings(
+      env({
+        SUPPORTED: 'v1,v2',
+        DEFAULT: 'v1',
+        MIN_SUNSET_DAYS: '180',
+        DEPRECATED: 'v1:2026-01-01:2026-12-01',
+      }),
+    );
+    expect(settings.deprecations[0]?.sunset).toBe('2026-12-01');
+  });
+});
+
+suite('policy', () => {
+  test('orders by declaration, not by parsing', () => {
+    const policy = policyFor({ SUPPORTED: 'v9,v10', DEFAULT: 'v9' });
+    expect(policy.compare('v9', 'v10')).toBeLessThan(0);
+    expect(policy.latest).toBe('v10');
+  });
+});
+
+suite('negotiation', () => {
+  test('a client that states nothing keeps the default version', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    expect(resolveVersion({ path: '/orders', headers: {} }, policy)).toEqual({
+      version: 'v1',
+      source: 'default',
+    });
+  });
+
+  test('reads the path segment after the prefix', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    expect(resolveVersion({ path: '/api/v2/orders', headers: {} }, policy).version).toBe('v2');
+  });
+
+  test('an unversioned path is not read as a version request', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    expect(resolveVersion({ path: '/api/orders', headers: {} }, policy).source).toBe('default');
+  });
+
+  test('rejects a version-shaped segment this deployment does not serve', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    expect(() => resolveVersion({ path: '/api/v7/orders', headers: {} }, policy)).toThrow(/Unsupported/);
+  });
+
+  test('reads the header case-insensitively', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    const resolution = resolveVersion({ path: '/orders', headers: { 'x-api-version': 'v2' } }, policy);
+    expect(resolution.version).toBe('v2');
+    expect(resolution.source).toBe('header');
+  });
+
+  test('reads the media-type parameter', () => {
+    const policy = policyFor({ STRATEGY: 'accept' });
+    const headers = { accept: 'application/json; version=v2' };
+    expect(resolveVersion({ path: '/orders', headers }, policy).version).toBe('v2');
+  });
+
+  test('falls back instead of throwing when strict is off', () => {
+    const policy = policyFor({ STRATEGY: 'query', STRICT: 'false' });
+    const resolution = resolveVersion({ path: '/orders', search: '?api-version=v7', headers: {} }, policy);
+    expect(resolution.version).toBe('v1');
+    expect(resolution.requested).toBe('v7');
+  });
+});
+
+suite('response headers', () => {
+  test('deprecated versions carry Deprecation, Sunset and Link', () => {
+    const policy = policyFor({
+      DEPRECATED: 'v1:2026-01-01:2026-12-01',
+      POLICY_URL: 'https://example.test/deprecations',
+    });
+    const headers = versionResponseHeaders({ version: 'v1', source: 'default' }, policy);
+    expect(headers['Deprecation']).toBe('@1767225600');
+    expect(headers['Sunset']).toBe('Tue, 01 Dec 2026 00:00:00 GMT');
+    expect(headers['Link']).toMatch(/rel="sunset"/);
+  });
+
+  test('a current version carries no sunset', () => {
+    const policy = policyFor({ DEPRECATED: 'v1:2026-01-01:2026-12-01' });
+    expect(versionResponseHeaders({ version: 'v2', source: 'path' }, policy)['Sunset']).toBeUndefined();
+  });
+
+  test('header negotiation varies the cache key', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    expect(versionResponseHeaders({ version: 'v1', source: 'default' }, policy)['Vary']).toBe(
+      'X-API-Version',
+    );
+  });
+});
+
+suite('contract compatibility', () => {
+  const before = describeShape({ id: 'a', total: 1 });
+
+  test('a new response field is additive', () => {
+    const after = describeShape({ id: 'a', total: 1, currency: 'EUR' });
+    expect(diffShapes(before, after, 'response').map((change) => change.severity)).toEqual(['additive']);
+  });
+
+  test('a removed response field is breaking', () => {
+    const after = describeShape({ id: 'a' });
+    expect(diffShapes(before, after, 'response')[0]?.severity).toBe('breaking');
+  });
+
+  test('a new required request field is breaking', () => {
+    const after = describeShape({ id: 'a', total: 1, currency: 'EUR' });
+    expect(diffShapes(before, after, 'request')[0]?.severity).toBe('breaking');
+  });
+
+  test('direction decides whether relaxing a field breaks anyone', () => {
+    const after = describeAll([{ id: 'a', total: 1 }, { id: 'a' }]);
+    expect(diffShapes(before, after, 'response')[0]?.severity).toBe('breaking');
+    expect(diffShapes(before, after, 'request')[0]?.severity).toBe('additive');
+  });
+
+  test('a removed operation is breaking', () => {
+    const baseline: ContractSnapshot = {
+      version: 'v1',
+      operations: { 'GET /orders': { response: before } },
+    };
+    const current: ContractSnapshot = { version: 'v1', operations: {} };
+    expect(diffContracts(baseline, current)[0]?.severity).toBe('breaking');
+  });
+});

package/templates/layers/api-versioning/files/src/apiversion/tests/apiversion.test.ts

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict';
+import { describe as suite, test } from 'vitest';
+import { diffContracts, diffShapes } from '../contract/diff.js';
+import { describe as describeShape, describeAll } from '../contract/shape.js';
+import { versionResponseHeaders } from '../headers.js';
+import { resolveVersion } from '../negotiate.js';
+import { ApiVersionConfigError, ENV_PREFIX, loadApiVersionSettings } from '../settings.js';
+import { createVersionPolicy } from '../versions.js';
+import type { ContractSnapshot } from '../contract/shape.js';
+
+const env = (overrides: Record<string, string>): Record<string, string> => {
+  const prefixed: Record<string, string> = {};
+  for (const [key, value] of Object.entries(overrides)) prefixed[`${ENV_PREFIX}_${key}`] = value;
+  return prefixed;
+};
+
+const policyFor = (overrides: Record<string, string>) =>
+  createVersionPolicy(loadApiVersionSettings(env({ SUPPORTED: 'v1,v2', DEFAULT: 'v1', ...overrides })));
+
+suite('settings', () => {
+  test('rejects a default that is not supported', () => {
+    assert.throws(
+      () => loadApiVersionSettings(env({ SUPPORTED: 'v1,v2', DEFAULT: 'v3' })),
+      ApiVersionConfigError,
+    );
+  });
+
+  test('rejects a sunset inside the notice window', () => {
+    assert.throws(
+      () =>
+        loadApiVersionSettings(
+          env({
+            SUPPORTED: 'v1,v2',
+            DEFAULT: 'v1',
+            MIN_SUNSET_DAYS: '180',
+            DEPRECATED: 'v1:2026-01-01:2026-03-01',
+          }),
+        ),
+      /below/,
+    );
+  });
+
+  test('accepts a deprecation that gives enough notice', () => {
+    const settings = loadApiVersionSettings(
+      env({
+        SUPPORTED: 'v1,v2',
+        DEFAULT: 'v1',
+        MIN_SUNSET_DAYS: '180',
+        DEPRECATED: 'v1:2026-01-01:2026-12-01',
+      }),
+    );
+    assert.equal(settings.deprecations[0]?.sunset, '2026-12-01');
+  });
+});
+
+suite('policy', () => {
+  test('orders by declaration, not by parsing', () => {
+    const policy = policyFor({ SUPPORTED: 'v9,v10', DEFAULT: 'v9' });
+    assert.ok(policy.compare('v9', 'v10') < 0);
+    assert.equal(policy.latest, 'v10');
+  });
+});
+
+suite('negotiation', () => {
+  test('a client that states nothing keeps the default version', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    const resolution = resolveVersion({ path: '/orders', headers: {} }, policy);
+    assert.deepEqual(resolution, { version: 'v1', source: 'default' });
+  });
+
+  test('reads the path segment after the prefix', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    assert.equal(resolveVersion({ path: '/api/v2/orders', headers: {} }, policy).version, 'v2');
+  });
+
+  test('an unversioned path is not read as a version request', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    assert.equal(resolveVersion({ path: '/api/orders', headers: {} }, policy).source, 'default');
+  });
+
+  test('rejects a version-shaped segment this deployment does not serve', () => {
+    const policy = policyFor({ STRATEGY: 'path', PATH_PREFIX: '/api' });
+    assert.throws(() => resolveVersion({ path: '/api/v7/orders', headers: {} }, policy), /Unsupported/);
+  });
+
+  test('reads the header case-insensitively', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    const resolution = resolveVersion({ path: '/orders', headers: { 'x-api-version': 'v2' } }, policy);
+    assert.equal(resolution.version, 'v2');
+    assert.equal(resolution.source, 'header');
+  });
+
+  test('reads the media-type parameter', () => {
+    const policy = policyFor({ STRATEGY: 'accept' });
+    const headers = { accept: 'application/json; version=v2' };
+    assert.equal(resolveVersion({ path: '/orders', headers }, policy).version, 'v2');
+  });
+
+  test('falls back instead of throwing when strict is off', () => {
+    const policy = policyFor({ STRATEGY: 'query', STRICT: 'false' });
+    const resolution = resolveVersion({ path: '/orders', search: '?api-version=v7', headers: {} }, policy);
+    assert.equal(resolution.version, 'v1');
+    assert.equal(resolution.requested, 'v7');
+  });
+});
+
+suite('response headers', () => {
+  test('deprecated versions carry Deprecation, Sunset and Link', () => {
+    const policy = policyFor({
+      DEPRECATED: 'v1:2026-01-01:2026-12-01',
+      POLICY_URL: 'https://example.test/deprecations',
+    });
+    const headers = versionResponseHeaders({ version: 'v1', source: 'default' }, policy);
+    assert.equal(headers['Deprecation'], '@1767225600');
+    assert.equal(headers['Sunset'], 'Tue, 01 Dec 2026 00:00:00 GMT');
+    assert.match(headers['Link'] ?? '', /rel="sunset"/);
+  });
+
+  test('a current version carries no sunset', () => {
+    const policy = policyFor({ DEPRECATED: 'v1:2026-01-01:2026-12-01' });
+    const headers = versionResponseHeaders({ version: 'v2', source: 'path' }, policy);
+    assert.equal(headers['Sunset'], undefined);
+  });
+
+  test('header negotiation varies the cache key', () => {
+    const policy = policyFor({ STRATEGY: 'header' });
+    assert.equal(versionResponseHeaders({ version: 'v1', source: 'default' }, policy)['Vary'], 'X-API-Version');
+  });
+});
+
+suite('contract compatibility', () => {
+  const before = describeShape({ id: 'a', total: 1 });
+
+  test('a new response field is additive', () => {
+    const after = describeShape({ id: 'a', total: 1, currency: 'EUR' });
+    const changes = diffShapes(before, after, 'response');
+    assert.deepEqual(
+      changes.map((change) => change.severity),
+      ['additive'],
+    );
+  });
+
+  test('a removed response field is breaking', () => {
+    const after = describeShape({ id: 'a' });
+    assert.equal(diffShapes(before, after, 'response')[0]?.severity, 'breaking');
+  });
+
+  test('a new required request field is breaking', () => {
+    const after = describeShape({ id: 'a', total: 1, currency: 'EUR' });
+    assert.equal(diffShapes(before, after, 'request')[0]?.severity, 'breaking');
+  });
+
+  test('direction decides whether relaxing a field breaks anyone', () => {
+    const after = describeAll([{ id: 'a', total: 1 }, { id: 'a' }]);
+    assert.equal(diffShapes(before, after, 'response')[0]?.severity, 'breaking');
+    assert.equal(diffShapes(before, after, 'request')[0]?.severity, 'additive');
+  });
+
+  test('a removed operation is breaking', () => {
+    const baseline: ContractSnapshot = {
+      version: 'v1',
+      operations: { 'GET /orders': { response: before } },
+    };
+    const current: ContractSnapshot = { version: 'v1', operations: {} };
+    assert.equal(diffContracts(baseline, current)[0]?.severity, 'breaking');
+  });
+});

package/templates/layers/api-versioning/files/src/apiversion/versions.ts

@@ -0,0 +1,66 @@
+/**
+ * The version policy: what is supported, what order versions are in, and what is on the
+ * way out. Ordering is the position in the supported list, so callers never parse a
+ * version string and `v10` never sorts before `v9`.
+ */
+import { apiVersionSettings } from './settings.js';
+import type { ApiVersionSettings, Deprecation } from './settings.js';
+
+export interface VersionPolicy {
+  readonly settings: ApiVersionSettings;
+  readonly supported: readonly string[];
+  readonly latest: string;
+  readonly oldest: string;
+  readonly defaultVersion: string;
+  has(version: string): boolean;
+  /** Negative when `a` is older, positive when newer, 0 when equal. Throws on unknown. */
+  compare(a: string, b: string): number;
+  deprecationFor(version: string): Deprecation | undefined;
+  /** Versions whose sunset date has passed but that are still being served. */
+  overdue(now?: Date): readonly Deprecation[];
+}
+
+export function createVersionPolicy(settings: ApiVersionSettings = apiVersionSettings()): VersionPolicy {
+  const order = new Map(settings.supported.map((version, index) => [version, index]));
+  const byVersion = new Map(settings.deprecations.map((d) => [d.version, d]));
+
+  const rank = (version: string): number => {
+    const index = order.get(version);
+    if (index === undefined) throw new UnknownVersionError(version, settings.supported);
+    return index;
+  };
+
+  return {
+    settings,
+    supported: settings.supported,
+    latest: settings.supported[settings.supported.length - 1]!,
+    oldest: settings.supported[0]!,
+    defaultVersion: settings.defaultVersion,
+    has: (version) => order.has(version),
+    compare: (a, b) => rank(a) - rank(b),
+    deprecationFor: (version) => byVersion.get(version),
+    overdue: (now = new Date()) =>
+      settings.deprecations.filter((d) => Date.parse(`${d.sunset}T00:00:00Z`) <= now.getTime()),
+  };
+}
+
+/** Raised by policy lookups. Request handling uses UnsupportedApiVersionError instead. */
+export class UnknownVersionError extends Error {
+  constructor(
+    readonly version: string,
+    readonly supported: readonly string[],
+  ) {
+    super(`Unknown API version "${version}"; supported: ${supported.join(', ')}`);
+  }
+}
+
+let cached: VersionPolicy | undefined;
+
+export function versionPolicy(): VersionPolicy {
+  cached ??= createVersionPolicy();
+  return cached;
+}
+
+export function resetVersionPolicy(): void {
+  cached = undefined;
+}