@hraness/direct 0.7.5

package/src/core/query.ts

@@ -0,0 +1,230 @@
+import {
+  DEFAULT_MAX_FIXTURE_BYTES,
+  parseFixtureJson,
+  type FixtureParseOptions,
+} from "./fixture.js";
+import { parseScenarioId, type ScenarioId } from "./ids.js";
+import {
+  stableHash,
+  tagStableHash,
+  utf8ByteLength,
+  type TaggedStableHash,
+} from "./json.js";
+import type { JsonValue } from "./json-value.js";
+import { err, ok, type Result } from "./result.js";
+import type { LogicalRuntimeSnapshot } from "./runtime.js";
+import type { ScenarioCatalog } from "./scenario.js";
+
+export const SCENARIO_QUERY_KEY = "__direct_scenario" as const;
+export const FIXTURE_QUERY_KEY = "__direct_fixture" as const;
+const FIXTURE_QUERY_PREFIX_BYTES = utf8ByteLength(`?${FIXTURE_QUERY_KEY}=`);
+
+/** Worst-case percent-encoded query bytes for a bounded fixture JSON string. */
+export function maximumFixtureQueryBytes(maxFixtureBytes: number): number {
+  return (maxFixtureBytes * 3) + FIXTURE_QUERY_PREFIX_BYTES;
+}
+
+export const DEFAULT_MAX_QUERY_BYTES = maximumFixtureQueryBytes(DEFAULT_MAX_FIXTURE_BYTES);
+
+export interface ActiveDirect<World extends JsonValue, Route extends string> {
+  readonly kind: "active";
+  readonly source: "scenario" | "fixture";
+  readonly scenario: ScenarioId;
+  readonly route: Route;
+  readonly world: World;
+  readonly runtime: LogicalRuntimeSnapshot;
+  readonly activationHash: TaggedStableHash;
+}
+
+export interface InactiveDirect {
+  readonly kind: "inactive";
+}
+
+export type DirectActivation<World extends JsonValue, Route extends string> =
+  | InactiveDirect
+  | ActiveDirect<World, Route>;
+
+export type QueryErrorCode =
+  | "duplicate-parameter"
+  | "invalid-encoding"
+  | "invalid-fixture"
+  | "invalid-query"
+  | "invalid-scenario"
+  | "mismatched-scenario"
+  | "oversized-query"
+  | "unknown-parameter"
+  | "unknown-scenario";
+
+export interface QueryError {
+  readonly code: QueryErrorCode;
+  readonly message: string;
+}
+
+export interface DirectQueryOptions<World extends JsonValue, Route extends string>
+  extends FixtureParseOptions<World, Route> {
+  readonly maxQueryBytes?: number;
+}
+
+function queryError(code: QueryErrorCode, message: string): QueryError {
+  return { code, message };
+}
+
+function decodeQueryPart(value: string): Result<string, QueryError> {
+  try {
+    return ok(decodeURIComponent(value.replaceAll("+", " ")));
+  } catch {
+    return err(queryError("invalid-encoding", "Direct query contains invalid percent encoding"));
+  }
+}
+
+function queryBody(source: string): string {
+  const question = source.indexOf("?");
+  const candidate = question >= 0 ? source.slice(question + 1) : source.startsWith("?") ? source.slice(1) : source;
+  const fragment = candidate.indexOf("#");
+  return fragment >= 0 ? candidate.slice(0, fragment) : candidate;
+}
+
+interface ParsedActivationQuery {
+  readonly scenario: string | null;
+  readonly fixture: string | null;
+}
+
+function parseActivationParameters(source: string): Result<ParsedActivationQuery, QueryError> {
+  let scenario: string | null = null;
+  let fixture: string | null = null;
+  const body = queryBody(source);
+  if (body.length === 0) {
+    return ok({ scenario, fixture });
+  }
+  for (const part of body.split("&")) {
+    if (part.length === 0) {
+      continue;
+    }
+    const equals = part.indexOf("=");
+    const encodedKey = equals < 0 ? part : part.slice(0, equals);
+    const encodedValue = equals < 0 ? "" : part.slice(equals + 1);
+    const key = decodeQueryPart(encodedKey);
+    if (!key.ok) {
+      return key;
+    }
+    const reserved = key.value.startsWith("__direct_");
+    if (key.value !== SCENARIO_QUERY_KEY && key.value !== FIXTURE_QUERY_KEY) {
+      if (reserved) {
+        return err(queryError("unknown-parameter", `Unknown Direct query parameter: ${key.value}`));
+      }
+      continue;
+    }
+    const value = decodeQueryPart(encodedValue);
+    if (!value.ok) {
+      return value;
+    }
+    if (key.value === SCENARIO_QUERY_KEY) {
+      if (scenario !== null) {
+        return err(queryError("duplicate-parameter", `Duplicate ${SCENARIO_QUERY_KEY} parameter`));
+      }
+      scenario = value.value;
+    } else {
+      if (fixture !== null) {
+        return err(queryError("duplicate-parameter", `Duplicate ${FIXTURE_QUERY_KEY} parameter`));
+      }
+      fixture = value.value;
+    }
+  }
+  return ok({ scenario, fixture });
+}
+
+function activationHash<World extends JsonValue, Route extends string>(
+  source: "scenario" | "fixture",
+  scenario: ScenarioId,
+  route: Route,
+  world: World,
+  runtime: LogicalRuntimeSnapshot,
+): TaggedStableHash {
+  const hashed = stableHash({ source, scenario, route, world, runtime });
+  if (!hashed.ok) {
+    throw new Error(hashed.error.message);
+  }
+  return tagStableHash(hashed.value);
+}
+
+export function activateDirectScenario<World extends JsonValue, Route extends string>(
+  id: unknown,
+  scenarios: ScenarioCatalog<World, Route>,
+): Result<ActiveDirect<World, Route>, QueryError> {
+  const parsed = parseScenarioId(id);
+  if (!parsed.ok) {
+    return err(queryError("invalid-scenario", parsed.error.message));
+  }
+  const scenario = scenarios.get(parsed.value);
+  if (scenario === undefined) {
+    return err(queryError("unknown-scenario", `Unknown scenario: ${parsed.value}`));
+  }
+  return ok(Object.freeze({
+    kind: "active",
+    source: "scenario",
+    scenario: scenario.id,
+    route: scenario.route,
+    world: scenario.world,
+    runtime: scenario.runtime,
+    activationHash: activationHash("scenario", scenario.id, scenario.route, scenario.world, scenario.runtime),
+  }));
+}
+
+export function parseDirectQuery<World extends JsonValue, Route extends string>(
+  source: unknown,
+  options: DirectQueryOptions<World, Route>,
+): Result<DirectActivation<World, Route>, QueryError> {
+  const maxBytes = options.maxQueryBytes ?? DEFAULT_MAX_QUERY_BYTES;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new Error("Query maxQueryBytes must be a positive safe integer");
+  }
+  if (typeof source !== "string") {
+    return err(queryError("invalid-query", "Direct query source must be a string"));
+  }
+  if (utf8ByteLength(source) > maxBytes) {
+    return err(queryError("oversized-query", "Direct query exceeds its byte limit"));
+  }
+  const parameters = parseActivationParameters(source);
+  if (!parameters.ok) {
+    return parameters;
+  }
+  if (parameters.value.scenario === null && parameters.value.fixture === null) {
+    return ok(Object.freeze({ kind: "inactive" }));
+  }
+
+  const requestedScenario = parameters.value.scenario === null
+    ? null
+    : activateDirectScenario(parameters.value.scenario, options.scenarios);
+  if (requestedScenario !== null && !requestedScenario.ok) {
+    return requestedScenario;
+  }
+  if (parameters.value.fixture === null) {
+    return requestedScenario ?? err(queryError("invalid-scenario", "Missing scenario activation"));
+  }
+
+  const fixture = parseFixtureJson(parameters.value.fixture, options);
+  if (!fixture.ok) {
+    return err(queryError("invalid-fixture", fixture.error.message));
+  }
+  if (requestedScenario !== null && requestedScenario.value.scenario !== fixture.value.scenario) {
+    return err(queryError(
+      "mismatched-scenario",
+      `${SCENARIO_QUERY_KEY} does not match the fixture scenario`,
+    ));
+  }
+  return ok(Object.freeze({
+    kind: "active",
+    source: "fixture",
+    scenario: fixture.value.scenario,
+    route: fixture.value.route,
+    world: fixture.value.world,
+    runtime: fixture.value.runtime,
+    activationHash: activationHash(
+      "fixture",
+      fixture.value.scenario,
+      fixture.value.route,
+      fixture.value.world,
+      fixture.value.runtime,
+    ),
+  }));
+}

package/src/core/reason.ts

@@ -0,0 +1,16 @@
+/** Render a foreign thrown value without trusting its prototype, getters, or coercion hooks. */
+export function renderUnknownReason(reason: unknown, fallback = "Unknown failure"): string {
+  try {
+    if ((typeof reason === "object" && reason !== null) || typeof reason === "function") {
+      const message = Reflect.get(reason, "message") as unknown;
+      if (typeof message === "string") return message;
+    }
+  } catch {
+    // Fall through to guarded primitive coercion.
+  }
+  try {
+    return String(reason);
+  } catch {
+    return fallback;
+  }
+}

package/src/core/resource.ts

@@ -0,0 +1,10 @@
+import type { JsonValue } from "./json-value.js";
+
+export type ResourceState<Value extends JsonValue, Failure extends JsonValue = string> =
+  | { readonly status: "idle" }
+  | { readonly status: "loading" }
+  | { readonly status: "ready"; readonly value: Value }
+  | { readonly status: "empty" }
+  | { readonly status: "error"; readonly error: Failure }
+  | { readonly status: "offline"; readonly error: Failure | null }
+  | { readonly status: "unauthorized"; readonly reason: Failure | null };

package/src/core/result.ts

@@ -0,0 +1,19 @@
+/** An explicit success-or-failure value whose failure path stays visible. */
+export type Result<Value, Failure = Error> =
+  | { readonly ok: true; readonly value: Value }
+  | { readonly ok: false; readonly error: Failure };
+
+export type UnknownRecord = Record<string, unknown>;
+
+export function ok<Value>(value: Value): Result<Value, never> {
+  return { ok: true, value };
+}
+
+export function err<Failure>(error: Failure): Result<never, Failure> {
+  return { ok: false, error };
+}
+
+/** Narrow a foreign value before reading named fields from it. */
+export function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/core/runtime.ts

@@ -0,0 +1,229 @@
+import { parseOperationId, type OperationId } from "./ids.js";
+import { parseJsonValue } from "./json.js";
+import { renderUnknownReason } from "./reason.js";
+import { err, isRecord, ok, type Result } from "./result.js";
+
+export const LOGICAL_RUNTIME_SCHEMA = "direct.runtime/v1" as const;
+export const MAX_HOST_TIMER_MILLISECONDS = 2_147_483_647;
+
+export interface LogicalRuntimeSnapshot {
+  readonly schema: typeof LOGICAL_RUNTIME_SCHEMA;
+  readonly nowMs: number;
+  readonly nextOperation: number;
+  readonly acceleration: number;
+}
+
+export const DEFAULT_LOGICAL_RUNTIME_SNAPSHOT = Object.freeze({
+  schema: LOGICAL_RUNTIME_SCHEMA,
+  nowMs: 0,
+  nextOperation: 1,
+  acceleration: 100,
+}) satisfies LogicalRuntimeSnapshot;
+
+export type RuntimeErrorCode =
+  | "invalid-duration"
+  | "invalid-runtime"
+  | "sleep-failed"
+  | "time-overflow"
+  | "wait-cancelled";
+
+export interface RuntimeError {
+  readonly code: RuntimeErrorCode;
+  readonly message: string;
+}
+
+export type LogicalSleep = (wallMilliseconds: number, signal?: AbortSignal) => Promise<void>;
+
+export interface LogicalRuntime {
+  readonly now: () => number;
+  readonly snapshot: () => LogicalRuntimeSnapshot;
+  readonly nextOperationId: (namespace?: string) => OperationId;
+  readonly advance: (logicalMilliseconds: number) => Result<number, RuntimeError>;
+  readonly wait: (
+    logicalMilliseconds: number,
+    signal?: AbortSignal,
+  ) => Promise<Result<number, RuntimeError>>;
+}
+
+const RUNTIME_KEYS = new Set(["schema", "nowMs", "nextOperation", "acceleration"]);
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+
+export function parseLogicalRuntimeSnapshot(input: unknown): Result<LogicalRuntimeSnapshot, RuntimeError> {
+  const parsedJson = parseJsonValue(input);
+  if (!parsedJson.ok || !isRecord(parsedJson.value)) {
+    return err({ code: "invalid-runtime", message: "Logical runtime must be an object" });
+  }
+  for (const key of Object.keys(parsedJson.value)) {
+    if (!RUNTIME_KEYS.has(key)) {
+      return err({ code: "invalid-runtime", message: `Unknown logical runtime key: ${key}` });
+    }
+  }
+  const record = parsedJson.value;
+  if (record.schema !== LOGICAL_RUNTIME_SCHEMA) {
+    return err({ code: "invalid-runtime", message: `Logical runtime schema must be ${LOGICAL_RUNTIME_SCHEMA}` });
+  }
+  if (typeof record.nowMs !== "number" || !Number.isSafeInteger(record.nowMs) || record.nowMs < 0) {
+    return err({ code: "invalid-runtime", message: "Logical nowMs must be a non-negative safe integer" });
+  }
+  if (
+    typeof record.nextOperation !== "number"
+    || !Number.isSafeInteger(record.nextOperation)
+    || record.nextOperation < 1
+  ) {
+    return err({ code: "invalid-runtime", message: "Logical nextOperation must be a positive safe integer" });
+  }
+  if (
+    typeof record.acceleration !== "number"
+    || !Number.isFinite(record.acceleration)
+    || record.acceleration < 1
+    || record.acceleration > 1_000_000
+  ) {
+    return err({ code: "invalid-runtime", message: "Logical acceleration must be in [1, 1000000]" });
+  }
+  return ok(Object.freeze({
+    schema: LOGICAL_RUNTIME_SCHEMA,
+    nowMs: record.nowMs,
+    nextOperation: record.nextOperation,
+    acceleration: record.acceleration,
+  }));
+}
+
+function sleepTimerChunk(wallMilliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted === true) {
+      resolve();
+      return;
+    }
+    let timeout: ReturnType<typeof setTimeout> | null = null;
+    let settled = false;
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== null) clearTimeout(timeout);
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    };
+    signal?.addEventListener("abort", finish, { once: true });
+    timeout = setTimeout(finish, wallMilliseconds);
+  });
+}
+
+async function defaultSleep(wallMilliseconds: number, signal?: AbortSignal): Promise<void> {
+  let remaining = wallMilliseconds;
+  while (remaining > 0 && signal?.aborted !== true) {
+    const chunk = Math.min(remaining, MAX_HOST_TIMER_MILLISECONDS);
+    await sleepTimerChunk(chunk, signal);
+    remaining -= chunk;
+  }
+}
+
+function parseDuration(logicalMilliseconds: number): Result<number, RuntimeError> {
+  return Number.isSafeInteger(logicalMilliseconds) && logicalMilliseconds >= 0
+    ? ok(logicalMilliseconds)
+    : err({ code: "invalid-duration", message: "Logical durations must be non-negative safe integers" });
+}
+
+function isWaitCancelled(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+function waitCancelled(): Result<never, RuntimeError> {
+  return err({
+    code: "wait-cancelled",
+    message: "Logical wait was cancelled",
+  });
+}
+
+function nextLogicalTime(nowMs: number, duration: number): Result<number, RuntimeError> {
+  const nextNow = nowMs + duration;
+  return Number.isSafeInteger(nextNow)
+    ? ok(nextNow)
+    : err({ code: "time-overflow", message: "Logical time exceeds the safe integer range" });
+}
+
+export function createLogicalRuntime(
+  initial: LogicalRuntimeSnapshot = DEFAULT_LOGICAL_RUNTIME_SNAPSHOT,
+  sleep: LogicalSleep = defaultSleep,
+): LogicalRuntime {
+  const parsed = parseLogicalRuntimeSnapshot(initial);
+  if (!parsed.ok) {
+    throw new Error(parsed.error.message);
+  }
+  let nowMs = parsed.value.nowMs;
+  let nextOperation = parsed.value.nextOperation;
+  const acceleration = parsed.value.acceleration;
+  let waitTail = Promise.resolve();
+
+  const snapshot = (): LogicalRuntimeSnapshot => Object.freeze({
+    schema: LOGICAL_RUNTIME_SCHEMA,
+    nowMs,
+    nextOperation,
+    acceleration,
+  });
+
+  const advance = (logicalMilliseconds: number): Result<number, RuntimeError> => {
+    const duration = parseDuration(logicalMilliseconds);
+    if (!duration.ok) {
+      return duration;
+    }
+    const nextNow = nextLogicalTime(nowMs, duration.value);
+    if (!nextNow.ok) {
+      return nextNow;
+    }
+    nowMs = nextNow.value;
+    return ok(nowMs);
+  };
+
+  const wait = (
+    logicalMilliseconds: number,
+    signal?: AbortSignal,
+  ): Promise<Result<number, RuntimeError>> => {
+    const duration = parseDuration(logicalMilliseconds);
+    if (!duration.ok) {
+      return Promise.resolve(duration);
+    }
+    const run = waitTail.then(async () => {
+      if (isWaitCancelled(signal)) return waitCancelled();
+      const target = nextLogicalTime(nowMs, duration.value);
+      if (!target.ok) return target;
+      const wallMilliseconds = Math.ceil(duration.value / acceleration);
+      try {
+        if (wallMilliseconds > 0) {
+          await sleep(wallMilliseconds, signal);
+        }
+      } catch (reason) {
+        if (isWaitCancelled(signal)) return waitCancelled();
+        return err<RuntimeError>({
+          code: "sleep-failed",
+          message: renderUnknownReason(reason, "Logical sleep failed"),
+        });
+      }
+      if (isWaitCancelled(signal)) return waitCancelled();
+      return advance(duration.value);
+    });
+    waitTail = run.then(() => undefined, () => undefined);
+    return run;
+  };
+
+  return Object.freeze({
+    now: () => nowMs,
+    snapshot,
+    nextOperationId: (namespace = "operation") => {
+      if (!NAMESPACE_PATTERN.test(namespace) || namespace.length > 48) {
+        throw new Error("Operation namespaces must be lowercase hyphen-separated ASCII identifiers");
+      }
+      if (!Number.isSafeInteger(nextOperation) || nextOperation >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("Operation sequence exceeds the safe integer range");
+      }
+      const candidate = `${namespace}-${String(nextOperation).padStart(6, "0")}`;
+      nextOperation += 1;
+      const parsedOperation = parseOperationId(candidate);
+      if (!parsedOperation.ok) {
+        throw new Error(parsedOperation.error.message);
+      }
+      return parsedOperation.value;
+    },
+    advance,
+    wait,
+  });
+}

package/src/core/scenario.ts

@@ -0,0 +1,149 @@
+import { parseScenarioId, type ScenarioId } from "./ids.js";
+import { parseAndCloneWorld, type WorldParser } from "./json.js";
+import type { JsonValue } from "./json-value.js";
+import { err, ok, type Result } from "./result.js";
+import {
+  DEFAULT_LOGICAL_RUNTIME_SNAPSHOT,
+  parseLogicalRuntimeSnapshot,
+  type LogicalRuntimeSnapshot,
+} from "./runtime.js";
+
+/** Maximum scenarios retained by one definition and discovery manifest. */
+export const MAX_DIRECT_SCENARIOS = 256 as const;
+
+export interface ScenarioDefinitionInput<World extends JsonValue, Route extends string> {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly route: Route;
+  readonly world: World;
+  readonly runtime?: LogicalRuntimeSnapshot;
+}
+
+export interface ScenarioDefinition<World extends JsonValue, Route extends string> {
+  readonly id: ScenarioId;
+  readonly title: string;
+  readonly description: string | null;
+  readonly route: Route;
+  readonly world: World;
+  readonly runtime: LogicalRuntimeSnapshot;
+}
+
+export type ScenarioCatalogErrorCode =
+  | "duplicate-scenario"
+  | "invalid-description"
+  | "invalid-route"
+  | "invalid-runtime"
+  | "invalid-scenario"
+  | "invalid-title"
+  | "invalid-world"
+  | "too-many-scenarios"
+  | "unknown-scenario";
+
+export interface ScenarioCatalogError {
+  readonly code: ScenarioCatalogErrorCode;
+  readonly scenario: unknown;
+  readonly message: string;
+}
+
+export interface ScenarioCatalog<World extends JsonValue, Route extends string> {
+  readonly size: number;
+  readonly list: () => readonly ScenarioDefinition<World, Route>[];
+  readonly get: (id: ScenarioId) => ScenarioDefinition<World, Route> | undefined;
+  readonly resolve: (id: unknown) => Result<ScenarioDefinition<World, Route>, ScenarioCatalogError>;
+}
+
+function validText(value: string, maximum: number): boolean {
+  if (value.trim().length === 0 || value.length > maximum) {
+    return false;
+  }
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if ((code < 32 && code !== 9 && code !== 10 && code !== 13) || code === 127) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function validRoute(value: string): boolean {
+  if (value.trim().length === 0 || value.length > 256) return false;
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code < 32 || code === 127) return false;
+  }
+  return true;
+}
+
+function scenarioError(code: ScenarioCatalogErrorCode, scenario: unknown, message: string): ScenarioCatalogError {
+  return { code, scenario, message };
+}
+
+export function createScenarioCatalog<World extends JsonValue, Route extends string>(
+  inputs: readonly ScenarioDefinitionInput<World, Route>[],
+  parseWorld: WorldParser<World>,
+): Result<ScenarioCatalog<World, Route>, ScenarioCatalogError> {
+  if (inputs.length > MAX_DIRECT_SCENARIOS) {
+    return err(scenarioError(
+      "too-many-scenarios",
+      inputs.length,
+      `Direct definitions support at most ${String(MAX_DIRECT_SCENARIOS)} scenarios`,
+    ));
+  }
+  const definitions: ScenarioDefinition<World, Route>[] = [];
+  const byId = new Map<ScenarioId, ScenarioDefinition<World, Route>>();
+
+  for (const input of inputs) {
+    const id = parseScenarioId(input.id);
+    if (!id.ok) {
+      return err(scenarioError("invalid-scenario", input.id, id.error.message));
+    }
+    if (byId.has(id.value)) {
+      return err(scenarioError("duplicate-scenario", id.value, `Duplicate scenario: ${id.value}`));
+    }
+    if (!validText(input.title, 160)) {
+      return err(scenarioError("invalid-title", id.value, "Scenario titles must contain 1-160 visible characters"));
+    }
+    if (input.description !== undefined && !validText(input.description, 2_000)) {
+      return err(scenarioError("invalid-description", id.value, "Scenario descriptions must contain 1-2000 visible characters"));
+    }
+    if (!validRoute(input.route)) {
+      return err(scenarioError("invalid-route", id.value, "Scenario routes must contain 1-256 visible characters"));
+    }
+    const runtime = parseLogicalRuntimeSnapshot(input.runtime ?? DEFAULT_LOGICAL_RUNTIME_SNAPSHOT);
+    if (!runtime.ok) {
+      return err(scenarioError("invalid-runtime", id.value, runtime.error.message));
+    }
+    const world = parseAndCloneWorld(input.world, parseWorld);
+    if (!world.ok) {
+      return err(scenarioError("invalid-world", id.value, world.error.message));
+    }
+    const definition = Object.freeze({
+      id: id.value,
+      title: input.title,
+      description: input.description ?? null,
+      route: input.route,
+      world: world.value,
+      runtime: runtime.value,
+    });
+    definitions.push(definition);
+    byId.set(id.value, definition);
+  }
+
+  const frozenDefinitions = Object.freeze(definitions);
+  return ok(Object.freeze({
+    size: frozenDefinitions.length,
+    list: () => frozenDefinitions,
+    get: (id: ScenarioId) => byId.get(id),
+    resolve: (input: unknown) => {
+      const id = parseScenarioId(input);
+      if (!id.ok) {
+        return err(scenarioError("invalid-scenario", input, id.error.message));
+      }
+      const definition = byId.get(id.value);
+      return definition === undefined
+        ? err(scenarioError("unknown-scenario", id.value, `Unknown scenario: ${id.value}`))
+        : ok(definition);
+    },
+  }));
+}