Development Process

Workspace Seeding

Workspace seeding prepares realistic runtime data for a Design Workspace before promotion. It lets builders and agents preview behavior against an isolated Workspace runtime source without changing Production data.

Status

Seed Sets are the planned product model for repeatable Workspace seeding. Until the Seed Set runner is available, use the same principle manually: execute the smallest useful command flow against the selected Workspace runtime source, then read Workspace projections to verify the result.

What seeding targets

Seeding is scoped to a Design Workspace. A Workspace runtime source is selected with a workspaceId, and runtime data lands in that Workspace-specific runtime state.

Seeded Workspace data is for:

  • page previews with realistic documents
  • projection and permission validation before promotion
  • agent-driven smoke tests
  • repeatable demo or review scenarios

Seeding is not for:

  • Production data changes
  • Sandbox provisioning
  • direct database mutation
  • importing historical event streams

Seed Sets

A Seed Set is a named set of runtime-data steps. Builders should be able to select one or more Seed Sets when preparing a Workspace.

Seed Sets are designed to be:

  • Named: so builders can choose demo-leads, invoice-review, or empty-account-with-user.
  • Ordered: so prerequisite data runs before dependent data.
  • Command-based: so normal command validation, events, and projections are produced.
  • Workspace-only: so the same app can have seeded preview data without changing Production.
  • Auditable: so a failed or skipped run is visible.
  • Rerunnable safely: so repeated preparation does not duplicate data by accident.

Seed Set shape

A Seed Set contains metadata, optional dependencies, optional fixture values, and ordered steps.

1type SeedSet = {
2  name: string;
3  label?: string;
4  description?: string;
5  dependsOn?: string[];
6  fixtures?: Record<string, unknown>;
7  steps: Array<{
8    id: string;
9    kind: "command";
10    commandName: string;
11    data: Record<string, unknown>;
12    capture?: Record<string, string>;
13    idempotencyKey?: string;
14  }>;
15};

Command steps are the first-class path. A step submits a command to the Workspace runtime, captures useful ids if later steps need them, and then lets the runtime produce events and projections normally.

How a run works

When Seed Sets are applied to a Workspace, the runner should:

  1. Load the target app and Design Workspace.
  2. Materialize the Workspace runtime config from the Workspace artifact graph.
  3. Resolve requested Seed Sets in dependency order.
  4. Resolve fixture values and captured values for each command step.
  5. Execute commands against the Workspace runtime source.
  6. Record the run status, selected Seed Sets, step results, correlation ids, and errors.
  7. Skip already completed Seed Sets with the same content hash unless a builder explicitly asks to rerun.

After the run, verify seeded data through Workspace runtime reads. Production projections should not show the Workspace seed data.

Reruns and failures

Seed runs should be idempotent by default. If the same Workspace already has a completed run for the same Seed Set content, the runner reports it as skipped or already completed instead of executing duplicate commands.

If a step fails, the run records the failed Seed Set, step id, command name, and error. A failed run must not be reported as completed.

Safe defaults

Workspace seeding should default to safe runtime behavior:

  • reject Production runtime sources
  • avoid live external calls unless explicitly enabled for a validation profile
  • use credential references instead of embedding secrets
  • prefer command-level idempotency keys where commands support stable semantic ids
  • keep seeded runtime data outside Changesets; Changesets carry model changes, not preview data