@hraness/direct 0.7.5

package/src/core/definition.ts

@@ -0,0 +1,378 @@
+import {
+  DIRECT_COVERAGE_SCHEMA,
+  createCoverageCatalog,
+  parseCoverageCatalogSnapshot,
+  type CoverageCatalog,
+  type CoverageEntryInput,
+  type CoverageError,
+} from "./coverage.js";
+import {
+  DEFAULT_MAX_FIXTURE_BYTES,
+  createFixtureEnvelope,
+  parseFixtureEnvelope,
+  parseFixtureJson,
+  serializeFixtureJson,
+  type FixtureCreateInput,
+  type FixtureEnvelope,
+  type FixtureError,
+} from "./fixture.js";
+import type { ScenarioId } from "./ids.js";
+import { parseJsonValue, type WorldParser } from "./json.js";
+import type { JsonValue } from "./json-value.js";
+import { renderUnknownReason } from "./reason.js";
+import {
+  DEFAULT_MAX_QUERY_BYTES,
+  activateDirectScenario,
+  maximumFixtureQueryBytes,
+  parseDirectQuery,
+  type ActiveDirect,
+  type QueryError,
+} from "./query.js";
+import { err, isRecord, ok, type Result } from "./result.js";
+import { parseLogicalRuntimeSnapshot } from "./runtime.js";
+import {
+  createScenarioCatalog,
+  type ScenarioCatalog,
+  type ScenarioCatalogError,
+  type ScenarioDefinition,
+  type ScenarioDefinitionInput,
+} from "./scenario.js";
+
+export interface DirectDefinitionInput<World extends JsonValue, Route extends string> {
+  readonly parseWorld: WorldParser<World>;
+  readonly defaultScenario: ScenarioId | string;
+  readonly scenarios: readonly ScenarioDefinitionInput<World, Route>[];
+  readonly coverage: readonly CoverageEntryInput[];
+  readonly maxFixtureBytes?: number;
+  readonly maxQueryBytes?: number;
+}
+
+export type DirectDefinitionError =
+  | {
+    readonly code: "invalid-options";
+    readonly message: string;
+    readonly scenarioError: null;
+    readonly coverageError: null;
+  }
+  | {
+    readonly code: "invalid-scenarios";
+    readonly message: string;
+    readonly scenarioError: ScenarioCatalogError;
+    readonly coverageError: null;
+  }
+  | {
+    readonly code: "invalid-default-scenario";
+    readonly message: string;
+    readonly scenarioError: ScenarioCatalogError;
+    readonly coverageError: null;
+  }
+  | {
+    readonly code: "invalid-coverage";
+    readonly message: string;
+    readonly scenarioError: null;
+    readonly coverageError: CoverageError;
+  }
+  | {
+    readonly code: "invalid-limits";
+    readonly message: string;
+    readonly scenarioError: null;
+    readonly coverageError: null;
+  };
+
+export interface DirectDefinitionLimits {
+  readonly maxFixtureBytes: number;
+  readonly maxQueryBytes: number;
+}
+
+export interface DirectDefinition<World extends JsonValue, Route extends string> {
+  readonly defaultScenario: ScenarioDefinition<World, Route>;
+  readonly scenarios: ScenarioCatalog<World, Route>;
+  readonly coverage: CoverageCatalog;
+  readonly parseWorld: WorldParser<World>;
+  readonly limits: DirectDefinitionLimits;
+  /** Parse a foreign query. An empty query activates the validated default scenario. */
+  readonly activate: (source: unknown) => Result<ActiveDirect<World, Route>, QueryError>;
+  /** Activate a named catalog scenario without going through a browser URL. */
+  readonly activateScenario: (scenario: unknown) => Result<ActiveDirect<World, Route>, QueryError>;
+  /** Parse a foreign fixture under this definition's catalog, parser, and byte limit. */
+  readonly parseFixture: (input: unknown) => Result<FixtureEnvelope<World, Route>, FixtureError>;
+  /** Parse fixture JSON under this definition's catalog, parser, and byte limit. */
+  readonly parseFixtureJson: (source: unknown) => Result<FixtureEnvelope<World, Route>, FixtureError>;
+  /** Create a fixture under this definition's catalog, parser, and byte limit. */
+  readonly createFixture: (
+    input: FixtureCreateInput<World>,
+  ) => Result<FixtureEnvelope<World, Route>, FixtureError>;
+  /** Serialize a fixture that this definition can activate. */
+  readonly serializeFixture: (input: FixtureCreateInput<World>) => Result<string, FixtureError>;
+}
+
+function definitionError(
+  code: DirectDefinitionError["code"],
+  message: string,
+  causes: {
+    readonly scenarioError?: ScenarioCatalogError;
+    readonly coverageError?: CoverageError;
+  } = {},
+): DirectDefinitionError {
+  if (code === "invalid-scenarios" || code === "invalid-default-scenario") {
+    const scenarioError = causes.scenarioError;
+    if (scenarioError === undefined) throw new Error(`${code} requires a scenario error`);
+    return Object.freeze({ code, message, scenarioError, coverageError: null });
+  }
+  if (code === "invalid-coverage") {
+    const coverageError = causes.coverageError;
+    if (coverageError === undefined) throw new Error("invalid-coverage requires a coverage error");
+    return Object.freeze({ code, message, scenarioError: null, coverageError });
+  }
+  return Object.freeze({ code, message, scenarioError: null, coverageError: null });
+}
+
+function validPositiveLimit(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 1;
+}
+
+function activeFromParsed<World extends JsonValue, Route extends string>(
+  parsed: ReturnType<typeof parseDirectQuery<World, Route>>,
+): Result<ActiveDirect<World, Route>, QueryError> {
+  if (!parsed.ok) return parsed;
+  if (parsed.value.kind === "active") return ok(parsed.value);
+  return err({ code: "invalid-scenario", message: "Direct activation did not select a scenario" });
+}
+
+/**
+ * Validate the product-owned world parser, scenarios, default activation, and
+ * proof catalog once, then expose one fail-closed activation boundary.
+ */
+function tryDefineDirectUnchecked<World extends JsonValue, Route extends string>(
+  input: DirectDefinitionInput<World, Route>,
+): Result<DirectDefinition<World, Route>, DirectDefinitionError> {
+  const parseWorld = input.parseWorld;
+  const defaultScenarioInput = input.defaultScenario;
+  const scenarioInputs = input.scenarios;
+  const coverageInputs = input.coverage;
+  const maxFixtureBytes = input.maxFixtureBytes ?? DEFAULT_MAX_FIXTURE_BYTES;
+  const maxQueryBytes = input.maxQueryBytes ?? DEFAULT_MAX_QUERY_BYTES;
+  if (!validPositiveLimit(maxFixtureBytes) || !validPositiveLimit(maxQueryBytes)) {
+    return err(definitionError(
+      "invalid-limits",
+      "Direct query and fixture limits must be positive safe integers",
+    ));
+  }
+  const requiredQueryBytes = maximumFixtureQueryBytes(maxFixtureBytes);
+  if (!Number.isSafeInteger(requiredQueryBytes) || maxQueryBytes < requiredQueryBytes) {
+    return err(definitionError(
+      "invalid-limits",
+      `Direct maxQueryBytes must be at least ${String(requiredQueryBytes)} to carry every bounded fixture`,
+    ));
+  }
+
+  const scenarios = createScenarioCatalog(scenarioInputs, parseWorld);
+  if (!scenarios.ok) {
+    return err(definitionError("invalid-scenarios", scenarios.error.message, {
+      scenarioError: scenarios.error,
+    }));
+  }
+  const defaultScenario = scenarios.value.resolve(defaultScenarioInput);
+  if (!defaultScenario.ok) {
+    return err(definitionError("invalid-default-scenario", defaultScenario.error.message, {
+      scenarioError: defaultScenario.error,
+    }));
+  }
+  const coverage = createCoverageCatalog(coverageInputs, scenarios.value);
+  if (!coverage.ok) {
+    return err(definitionError("invalid-coverage", coverage.error.message, {
+      coverageError: coverage.error,
+    }));
+  }
+
+  const limits = Object.freeze({ maxFixtureBytes, maxQueryBytes });
+  const fixtureOptions = Object.freeze({
+    scenarios: scenarios.value,
+    parseWorld,
+    maxBytes: maxFixtureBytes,
+  });
+  const queryOptions = Object.freeze({
+    ...fixtureOptions,
+    maxQueryBytes,
+  });
+  const activateScenario = (
+    scenario: unknown,
+  ): Result<ActiveDirect<World, Route>, QueryError> => activateDirectScenario(
+    scenario,
+    scenarios.value,
+  );
+  const activate = (source: unknown): Result<ActiveDirect<World, Route>, QueryError> => {
+    const parsed = parseDirectQuery(source, queryOptions);
+    if (!parsed.ok || parsed.value.kind === "active") return activeFromParsed(parsed);
+    return activateScenario(defaultScenario.value.id);
+  };
+
+  return ok(Object.freeze({
+    defaultScenario: defaultScenario.value,
+    scenarios: scenarios.value,
+    coverage: coverage.value,
+    parseWorld,
+    limits,
+    activate,
+    activateScenario,
+    parseFixture: (fixture: unknown) => parseFixtureEnvelope(fixture, fixtureOptions),
+    parseFixtureJson: (source: unknown) => parseFixtureJson(source, fixtureOptions),
+    createFixture: (fixture: FixtureCreateInput<World>) => createFixtureEnvelope(fixture, fixtureOptions),
+    serializeFixture: (fixture: FixtureCreateInput<World>) => serializeFixtureJson(fixture, fixtureOptions),
+  }));
+}
+
+/** Validate a typed dynamically assembled definition without throwing. */
+export function tryDefineDirect<World extends JsonValue, Route extends string>(
+  input: DirectDefinitionInput<World, Route>,
+): Result<DirectDefinition<World, Route>, DirectDefinitionError> {
+  try {
+    return tryDefineDirectUnchecked(input);
+  } catch (reason) {
+    return err(definitionError(
+      "invalid-options",
+      renderUnknownReason(reason, "Direct definition options could not be inspected"),
+    ));
+  }
+}
+
+const DEFINITION_INPUT_KEYS = new Set([
+  "coverage",
+  "defaultScenario",
+  "maxFixtureBytes",
+  "maxQueryBytes",
+  "parseWorld",
+  "scenarios",
+]);
+const SCENARIO_INPUT_KEYS = new Set([
+  "description",
+  "id",
+  "route",
+  "runtime",
+  "title",
+  "world",
+]);
+
+/**
+ * Parse a genuinely foreign definition value. Its world and route types remain
+ * broad because unknown configuration cannot supply compile-time refinements.
+ */
+export function parseDirectDefinition(
+  input: unknown,
+): Result<DirectDefinition<JsonValue, string>, DirectDefinitionError> {
+  try {
+    if (!isRecord(input)) throw new Error("Direct definition must be an object");
+    for (const key of Object.keys(input)) {
+      if (!DEFINITION_INPUT_KEYS.has(key)) throw new Error(`Unknown Direct definition key: ${key}`);
+    }
+    const rawParser = input.parseWorld;
+    if (typeof rawParser !== "function") throw new Error("Direct parseWorld must be a function");
+    const parseWorld: WorldParser<JsonValue> = (candidate) => {
+      const parsedCandidate: unknown = Reflect.apply(rawParser, undefined, [candidate]);
+      const parsedJson = parseJsonValue(parsedCandidate);
+      if (!parsedJson.ok) throw new Error(parsedJson.error.message);
+      return parsedJson.value;
+    };
+    if (typeof input.defaultScenario !== "string") {
+      throw new Error("Direct defaultScenario must be a string");
+    }
+    if (!Array.isArray(input.scenarios)) throw new Error("Direct scenarios must be an array");
+    const scenarios: ScenarioDefinitionInput<JsonValue, string>[] = [];
+    for (const [index, candidate] of input.scenarios.entries()) {
+      if (!isRecord(candidate)) throw new Error(`Direct scenario ${String(index)} must be an object`);
+      for (const key of Object.keys(candidate)) {
+        if (!SCENARIO_INPUT_KEYS.has(key)) {
+          throw new Error(`Unknown Direct scenario key at ${String(index)}: ${key}`);
+        }
+      }
+      if (
+        typeof candidate.id !== "string"
+        || typeof candidate.title !== "string"
+        || typeof candidate.route !== "string"
+        || (candidate.description !== undefined && typeof candidate.description !== "string")
+      ) {
+        throw new Error(`Direct scenario ${String(index)} has an invalid shape`);
+      }
+      const world = parseJsonValue(candidate.world);
+      if (!world.ok) throw new Error(`Direct scenario ${String(index)} world is invalid: ${world.error.message}`);
+      const runtime = candidate.runtime === undefined
+        ? undefined
+        : parseLogicalRuntimeSnapshot(candidate.runtime);
+      if (runtime !== undefined && !runtime.ok) {
+        throw new Error(`Direct scenario ${String(index)} runtime is invalid: ${runtime.error.message}`);
+      }
+      scenarios.push({
+        id: candidate.id,
+        title: candidate.title,
+        ...(candidate.description === undefined ? {} : { description: candidate.description }),
+        route: candidate.route,
+        world: world.value,
+        ...(runtime === undefined ? {} : { runtime: runtime.value }),
+      });
+    }
+    const coverage = parseCoverageCatalogSnapshot({
+      schema: DIRECT_COVERAGE_SCHEMA,
+      entries: input.coverage,
+    });
+    if (!coverage.ok) {
+      return err(definitionError("invalid-coverage", coverage.error.message, {
+        coverageError: coverage.error,
+      }));
+    }
+    const maxFixtureBytes = input.maxFixtureBytes;
+    const maxQueryBytes = input.maxQueryBytes;
+    if (maxFixtureBytes !== undefined && typeof maxFixtureBytes !== "number") {
+      throw new Error("Direct maxFixtureBytes must be a number");
+    }
+    if (maxQueryBytes !== undefined && typeof maxQueryBytes !== "number") {
+      throw new Error("Direct maxQueryBytes must be a number");
+    }
+    return tryDefineDirectUnchecked({
+      parseWorld,
+      defaultScenario: input.defaultScenario,
+      scenarios,
+      coverage: coverage.value.entries,
+      ...(maxFixtureBytes === undefined ? {} : { maxFixtureBytes }),
+      ...(maxQueryBytes === undefined ? {} : { maxQueryBytes }),
+    });
+  } catch (reason) {
+    return err(definitionError(
+      "invalid-options",
+      renderUnknownReason(reason, "Direct definition options could not be inspected"),
+    ));
+  }
+}
+
+/**
+ * Define an authored Direct composition.
+ *
+ * Configuration failures are programming errors at this boundary, so this
+ * concise path throws with the structured definition error as its cause. Use
+ * `tryDefineDirect` for typed dynamic assembly and
+ * `parseDirectDefinition` for a genuinely unknown value.
+ */
+export function defineDirect<
+  World extends JsonValue,
+  const Scenarios extends readonly {
+    readonly id: string;
+    readonly route: string;
+  }[],
+>(
+  input: {
+    readonly parseWorld: WorldParser<World>;
+    readonly defaultScenario: NoInfer<Scenarios>[number]["id"];
+    readonly scenarios: Scenarios & readonly ScenarioDefinitionInput<
+      World,
+      Scenarios[number]["route"]
+    >[];
+    readonly coverage: readonly CoverageEntryInput<NoInfer<Scenarios>[number]["id"]>[];
+    readonly maxFixtureBytes?: number;
+    readonly maxQueryBytes?: number;
+  },
+): DirectDefinition<World, Scenarios[number]["route"]> {
+  const defined = tryDefineDirect(input);
+  if (!defined.ok) {
+    throw new Error(defined.error.message, { cause: defined.error });
+  }
+  return defined.value;
+}

package/src/core/effects.ts

@@ -0,0 +1,88 @@
+import { parseOperationId, type OperationId } from "./ids.js";
+import { cloneJson, freezeJson } from "./json.js";
+import type { JsonValue } from "./json-value.js";
+
+export interface QueuedEffect<Effect extends JsonValue> {
+  readonly id: OperationId;
+  readonly effect: Effect;
+  readonly remaining: number;
+}
+
+export type QueuedFault<Fault extends JsonValue> = QueuedEffect<Fault>;
+
+export type ConsumedEffect<Effect extends JsonValue> =
+  | {
+    readonly kind: "consumed";
+    readonly effect: Effect;
+    readonly queue: readonly QueuedEffect<Effect>[];
+  }
+  | {
+    readonly kind: "empty";
+    readonly queue: readonly QueuedEffect<Effect>[];
+  };
+
+function ownQueuedEffect<Effect extends JsonValue>(
+  entry: QueuedEffect<Effect>,
+): QueuedEffect<Effect> {
+  const id = parseOperationId(entry.id);
+  if (!id.ok) throw new Error(id.error.message);
+  if (!Number.isSafeInteger(entry.remaining) || entry.remaining < 1) {
+    throw new Error("Queued effect remaining uses must be a positive safe integer");
+  }
+  const cloned = cloneJson(entry.effect);
+  if (!cloned.ok) throw new Error(cloned.error.message);
+  return Object.freeze({
+    id: id.value,
+    effect: freezeJson(cloned.value) as Effect,
+    remaining: entry.remaining,
+  });
+}
+
+function ownEffectQueue<Effect extends JsonValue>(
+  queue: readonly QueuedEffect<Effect>[],
+): readonly QueuedEffect<Effect>[] {
+  return Object.freeze(queue.map((entry) => ownQueuedEffect(entry)));
+}
+
+export function enqueueEffect<Effect extends JsonValue>(
+  queue: readonly QueuedEffect<Effect>[],
+  id: OperationId,
+  effect: Effect,
+  uses = 1,
+): readonly QueuedEffect<Effect>[] {
+  if (!Number.isSafeInteger(uses) || uses < 1) {
+    throw new Error("Queued effect uses must be a positive safe integer");
+  }
+  const ownedQueue = ownEffectQueue(queue);
+  const appended = ownQueuedEffect({ id, effect, remaining: uses });
+  return Object.freeze([...ownedQueue, appended]);
+}
+
+export function consumeEffect<Effect extends JsonValue>(
+  queue: readonly QueuedEffect<Effect>[],
+  matches: (entry: QueuedEffect<Effect>) => boolean = () => true,
+): ConsumedEffect<Effect> {
+  const ownedQueue = ownEffectQueue(queue);
+  const index = ownedQueue.findIndex(matches);
+  if (index < 0) {
+    return Object.freeze({ kind: "empty", queue: ownedQueue });
+  }
+  const matched = ownedQueue[index];
+  if (matched === undefined) {
+    return Object.freeze({ kind: "empty", queue: ownedQueue });
+  }
+  const next = [...ownedQueue];
+  if (matched.remaining === 1) {
+    next.splice(index, 1);
+  } else {
+    next[index] = Object.freeze({ ...matched, remaining: matched.remaining - 1 });
+  }
+  return Object.freeze({
+    kind: "consumed",
+    effect: matched.effect,
+    queue: Object.freeze(next),
+  });
+}
+
+export const enqueueFault = enqueueEffect;
+export const consumeFault = consumeEffect;

package/src/core/fixture.ts

@@ -0,0 +1,185 @@
+import { parseScenarioId, type ScenarioId } from "./ids.js";
+import {
+  canonicalJson,
+  parseAndCloneWorld,
+  parseExactJsonSource,
+  utf8ByteLength,
+  type WorldParser,
+} from "./json.js";
+import type { JsonValue } from "./json-value.js";
+import { err, isRecord, ok, type Result } from "./result.js";
+import { parseLogicalRuntimeSnapshot, type LogicalRuntimeSnapshot } from "./runtime.js";
+import type { ScenarioCatalog } from "./scenario.js";
+
+export const FIXTURE_SCHEMA = "direct.fixture/v1" as const;
+export const DEFAULT_MAX_FIXTURE_BYTES = 65_536;
+
+export interface FixtureEnvelope<World extends JsonValue, Route extends string> {
+  readonly schema: typeof FIXTURE_SCHEMA;
+  readonly scenario: ScenarioId;
+  readonly route: Route;
+  readonly world: World;
+  readonly runtime: LogicalRuntimeSnapshot;
+}
+
+export type FixtureErrorCode =
+  | "duplicate-key"
+  | "invalid-fixture"
+  | "invalid-json"
+  | "invalid-runtime"
+  | "invalid-scenario"
+  | "invalid-world"
+  | "mismatched-route"
+  | "oversized-fixture"
+  | "unknown-key"
+  | "unknown-scenario";
+
+export interface FixtureError {
+  readonly code: FixtureErrorCode;
+  readonly message: string;
+}
+
+export interface FixtureParseOptions<World extends JsonValue, Route extends string> {
+  readonly scenarios: ScenarioCatalog<World, Route>;
+  readonly parseWorld: WorldParser<World>;
+  readonly maxBytes?: number;
+}
+
+export interface FixtureCreateInput<World extends JsonValue> {
+  readonly scenario: ScenarioId | string;
+  readonly world: World;
+  readonly runtime?: LogicalRuntimeSnapshot;
+}
+
+const FIXTURE_KEYS = new Set(["schema", "scenario", "route", "world", "runtime"]);
+
+function fixtureError(code: FixtureErrorCode, message: string): FixtureError {
+  return { code, message };
+}
+
+function maxFixtureBytes(value: number | undefined): number {
+  const maximum = value ?? DEFAULT_MAX_FIXTURE_BYTES;
+  if (!Number.isSafeInteger(maximum) || maximum < 1) {
+    throw new Error("Fixture maxBytes must be a positive safe integer");
+  }
+  return maximum;
+}
+
+export function parseFixtureEnvelope<World extends JsonValue, Route extends string>(
+  input: unknown,
+  options: FixtureParseOptions<World, Route>,
+): Result<FixtureEnvelope<World, Route>, FixtureError> {
+  const maximum = maxFixtureBytes(options.maxBytes);
+  const serialized = canonicalJson(input);
+  if (!serialized.ok) {
+    return err(fixtureError("invalid-fixture", serialized.error.message));
+  }
+  if (utf8ByteLength(serialized.value) > maximum) {
+    return err(fixtureError("oversized-fixture", "Fixture exceeds its byte limit"));
+  }
+  const foreign = JSON.parse(serialized.value) as unknown;
+  if (!isRecord(foreign)) {
+    return err(fixtureError("invalid-fixture", "Fixture must be an object"));
+  }
+  for (const key of Object.keys(foreign)) {
+    if (!FIXTURE_KEYS.has(key)) {
+      return err(fixtureError("unknown-key", `Unknown fixture key: ${key}`));
+    }
+  }
+  if (foreign.schema !== FIXTURE_SCHEMA) {
+    return err(fixtureError("invalid-fixture", `Fixture schema must be ${FIXTURE_SCHEMA}`));
+  }
+  const id = parseScenarioId(foreign.scenario);
+  if (!id.ok) {
+    return err(fixtureError("invalid-scenario", id.error.message));
+  }
+  const scenario = options.scenarios.get(id.value);
+  if (scenario === undefined) {
+    return err(fixtureError("unknown-scenario", `Unknown fixture scenario: ${id.value}`));
+  }
+  if (typeof foreign.route !== "string" || foreign.route !== scenario.route) {
+    return err(fixtureError("mismatched-route", `Fixture route must match scenario ${id.value}`));
+  }
+  const runtime = foreign.runtime === undefined
+    ? ok(scenario.runtime)
+    : parseLogicalRuntimeSnapshot(foreign.runtime);
+  if (!runtime.ok) {
+    return err(fixtureError("invalid-runtime", runtime.error.message));
+  }
+  const world = parseAndCloneWorld(foreign.world, options.parseWorld);
+  if (!world.ok) {
+    return err(fixtureError("invalid-world", world.error.message));
+  }
+  const envelope = Object.freeze({
+    schema: FIXTURE_SCHEMA,
+    scenario: id.value,
+    route: scenario.route,
+    world: world.value,
+    runtime: runtime.value,
+  });
+  const normalized = canonicalJson(envelope);
+  if (!normalized.ok) {
+    return err(fixtureError("invalid-fixture", normalized.error.message));
+  }
+  if (utf8ByteLength(normalized.value) > maximum) {
+    return err(fixtureError("oversized-fixture", "Normalized fixture exceeds its byte limit"));
+  }
+  return ok(envelope);
+}
+
+export function parseFixtureJson<World extends JsonValue, Route extends string>(
+  source: unknown,
+  options: FixtureParseOptions<World, Route>,
+): Result<FixtureEnvelope<World, Route>, FixtureError> {
+  if (typeof source !== "string") {
+    return err(fixtureError("invalid-json", "Fixture JSON source must be a string"));
+  }
+  if (utf8ByteLength(source) > maxFixtureBytes(options.maxBytes)) {
+    return err(fixtureError("oversized-fixture", "Fixture exceeds its byte limit"));
+  }
+  const input = parseExactJsonSource(source);
+  if (!input.ok) {
+    return err(fixtureError(
+      input.error.code === "duplicate-key" ? "duplicate-key" : "invalid-json",
+      input.error.code === "duplicate-key" ? input.error.message : "Fixture is not valid JSON",
+    ));
+  }
+  return parseFixtureEnvelope(input.value, options);
+}
+
+/** Create an exact fixture envelope while deriving its route from the catalog. */
+export function createFixtureEnvelope<World extends JsonValue, Route extends string>(
+  input: FixtureCreateInput<World>,
+  options: FixtureParseOptions<World, Route>,
+): Result<FixtureEnvelope<World, Route>, FixtureError> {
+  const id = parseScenarioId(input.scenario);
+  if (!id.ok) return err(fixtureError("invalid-scenario", id.error.message));
+  const scenario = options.scenarios.get(id.value);
+  if (scenario === undefined) {
+    return err(fixtureError("unknown-scenario", `Unknown fixture scenario: ${id.value}`));
+  }
+  return parseFixtureEnvelope({
+    schema: FIXTURE_SCHEMA,
+    scenario: id.value,
+    route: scenario.route,
+    world: input.world,
+    runtime: input.runtime ?? scenario.runtime,
+  }, options);
+}
+
+/** Serialize a validated fixture with canonical key ordering. */
+export function serializeFixtureJson<World extends JsonValue, Route extends string>(
+  input: FixtureCreateInput<World>,
+  options: FixtureParseOptions<World, Route>,
+): Result<string, FixtureError> {
+  const fixture = createFixtureEnvelope(input, options);
+  if (!fixture.ok) return fixture;
+  const serialized = canonicalJson(fixture.value);
+  if (!serialized.ok) {
+    return err(fixtureError("invalid-fixture", serialized.error.message));
+  }
+  if (utf8ByteLength(serialized.value) > maxFixtureBytes(options.maxBytes)) {
+    return err(fixtureError("oversized-fixture", "Normalized fixture exceeds its byte limit"));
+  }
+  return ok(serialized.value);
+}