@dg-superapp/scenario-schema

Versioned zod schema + loader for DG SuperApp simulator scenarios. The shared contract used by the simulator desktop app, @dg-superapp/bridge-testing, the admin portal Bridge Mock Preview, and the MCP simulator server.

Install

pnpm add @dg-superapp/scenario-schema

Use

import {
  type Scenario,
  loadScenario,
  scenarioSchema,
  serializeScenario,
  SCHEMA_VERSION,
} from "@dg-superapp/scenario-schema";

// 1. Validate an in-memory object
const scenario: Scenario = scenarioSchema.parse({
  schemaVersion: SCHEMA_VERSION,
  name: "offline",
  profile: { level: "1" },
  network: { throttle: "offline" },
});

// 2. Load from a URL, filesystem path, or object
const loaded = await loadScenario("./scenarios/offline.dg-scenario.json");

// 3. Serialize with stable key ordering for diffable on-disk files
await fs.writeFile("offline.dg-scenario.json", serializeScenario(loaded));

Schema

Scenario is a superset of v1.0 BridgeMockPreview state:

| Field | Purpose | | --------------- | ----------------------------------------------------------------- | | schemaVersion | Literal "1.0.0" (loader rejects incompatible majors) | | name | Display name | | description | Free-form description | | tags | Searchable labels | | profile | Maturity level "0" \| "1" \| "2" plus optional fixture data | | responses | Per-handler response config: default \| success \| error \| delay | | consent | Per-handler consent state + audit history | | network | Throttle preset + extra latency | | metadata | Opaque escape hatch (NOT covered by SemVer) |

Versioning

Any breaking change to the wire format bumps schemaVersion. loadScenario() rejects scenarios whose schemaVersion major differs from the package's SCHEMA_VERSION.

Closes

• v1.0 Phase 8.1 (response-config → handler-dispatch wiring) — SIM-17
• v3.0 KEYSTONE — SIM-02