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

The current Design MCP vNext surface stays at five lifecycle tools: Begin, Inspect, Apply, Evaluate, and Finalize. Author seed-set artifacts with Apply, evaluate an exact immutable revision, and inspect the resulting evidence. That evaluation does not persist runtime data in a Workspace and does not currently import Production projection snapshots. A vNext-native, evaluation-only projection snapshot flow is tracked separately; it is not available today.

SeedSet delta checks execute changed SeedSets and their dependencies. A fresh browser Evaluation Session or Runtime Agent exercise initializes all SeedSets from the exact revision, including unchanged baseline definitions. Dependencies run once in order before the runtime is exposed. Reads and navigation do not reseed a live Session; a new Session rebuilds its isolated baseline without copying persistent Workspace or published runtime data.

The persistent Workspace flows below describe legacy Design MCP v1. In v1, create or update Seed Sets with upsert_seed_set, then apply them with apply_seed_sets. Use list_seed_sets(appId, workspaceId?) to discover existing definitions, and get_seed_set(appId, workspaceId?, name) to inspect a definition before applying it. Do not use these v1 tools when connected to the vNext five-tool surface.

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

Projection-only Production baselines

Legacy Design MCP v1 can also copy an exact existing Production read-model baseline into a Workspace with copy_projection_document_to_workspace. This is separate from command-based Seed Sets: it creates non-event-backed, Workspace-only test context.

For one bound page document, use the singular id in the copyAction returned by query_projection_data or diagnose_page. That path remains compatible and defaults overwrite to false.

For several documents, use one bounded call instead of parallel singular requests:

{
  "tool": "copy_projection_document_to_workspace",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "projectionName": "OrdersView",
    "ids": ["order-101", "order-102"],
    "idempotencyKey": "orders-baseline-2026-07-23",
    "expectedSourceHashes": {
      "order-101": "<copy-safe-sha256>",
      "order-102": "<copy-safe-sha256>"
    },
    "expectedSourceAggregateHash": "<sorted-id-hash-manifest-sha256>",
    "expectedTargetHashes": {
      "order-101": null,
      "order-102": null
    },
    "overwrite": false
  }
}

The ids manifest accepts 1 to 500 IDs of at most 1,024 UTF-16 code units each. Cessy de-duplicates and sorts the selection, then uses a process-wide shared two-permit FIFO scheduler. The idempotency key accepts 1 to 128 letters, numbers, dots, underscores, colons, and hyphens. The client should not create its own worker fan-out. Hash preconditions are lowercase 64-character SHA-256 hex values and may only name selected IDs.

“Exact” is manifest-scoped: the result, counts, and aggregate hashes cover exactly the requested IDs. The operation does not enumerate or delete unrelated documents already present in the destination collection.

Document hashes use projection-copy canonical JSON v1: SHA-256 over the UTF-8 bytes of the default-redacted document, with object keys sorted by UTF-16 code units at every depth. Arrays preserve order, undefined object properties are omitted, and undefined array entries become null. The aggregate applies the same algorithm to the UTF-16-code-unit-ID-sorted array of { "id": <id>, "hash": <document-hash> } objects. This exact form is the input for expectedSourceAggregateHash.

As a portable v1 check, { "é": 1, "z": 2, "😀": 3 } canonicalizes to {"z":2,"é":1,"😀":3} and hashes to 4177f29d85d48c133fea6e4531c5817e8ad4a86eca582296fe34d6322db0799c.

Cessy durably pins each first successful source hash and rechecks it before the target write and during final verification. Use the optional expected source hashes and aggregate hash to pin that first read to caller-known evidence. For target CAS, null requires absence and a hash pins the exact existing target that may be replaced with overwrite: true. An already-identical target is a deterministic no-op, including after a lost response. A missing source, source or aggregate mismatch, and a non-identical target conflict block the run.

The bulk run is durable and identified by idempotencyKey. After a client timeout, call the same tool with the original appId, workspaceId, projectionName, key, and operation: "status". Use operation: "resume" to continue an expired or retryable run. Omit id, ids, hashes, and overwrite for status/resume; the server already has the manifest. Reusing a key with different copy intent is rejected. Completed receipts are immutable point-in-time evidence; use a new key and current hash expectations to verify a target again after later Workspace mutations.

The result is content-free: it returns durable counts, per-ID status and source/target hashes, plus aggregate hashes when complete, but never document bodies. Hashes cover the default-redacted payload that is actually written, not the raw secret-bearing Production record.

This operation never changes Production. It dispatches zero commands and events, runs no policies, triggers, or subscriptions, and makes no external HTTP calls. The copied documents are transient Workspace fixture data and are not promoted as domain history. This tool is not available on the current vNext five-tool surface.

Seed Sets

A Seed Set is a named set of runtime-data steps. Builders and agents can 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. Persisted Seed Set artifacts must include at least one command step.

type SeedSet = {
  name: string;
  label?: string;
  description?: string;
  dependsOn?: string[];
  fixtures?: Record<string, unknown>;
  steps: Array<{
    id: string;
    kind: 'command';
    commandName: string;
    data: Record<string, unknown>;
    capture?: Record<string, string>;
    idempotencyKey?: string;
  }>;
};

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.

Do not store composition-only presets as Seed Set artifacts with steps: []. When you only need to apply existing Seed Sets together, pass the ordered seedSets array to Workspace creation or Seed Set apply instead.

Authoring and updating Seed Sets

Use upsert_seed_set to create or replace a named seed-set:<name> artifact in a Design Workspace. The tool derives dependency metadata from dependsOn and command step names, returns a diff preview, and can validate the resulting Workspace graph before saving.

{
  "tool": "upsert_seed_set",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "name": "demo-leads",
    "label": "Demo Leads",
    "dependsOn": ["base-users"],
    "fixtures": {
      "leadId": "lead-demo-1"
    },
    "steps": [
      {
        "id": "create-lead",
        "kind": "command",
        "commandName": "CreateLead",
        "data": {
          "leadId": "{{fixtures.leadId}}",
          "name": "Ada Lovelace"
        },
        "idempotencyKey": "demo-lead-1"
      }
    ],
    "dryRun": true,
    "validate": "changeset"
  }
}

Use dryRun: true to preview without mutating the Workspace. The default validate: "changeset" catches missing command dependencies, missing Seed Set dependencies, cycles, duplicate step ids, and other ChangeSet validation failures before the artifact is saved. Use validate: "artifact" only while drafting against an incomplete Workspace graph.

After a successful non-dry-run upsert, inspect diff_workspace before applying the Seed Set to runtime data. Applying a Seed Set writes Workspace runtime data only. Promoting the Seed Set definition is a separate ChangeSet decision, and seeded runtime events/documents are not promoted.

Discovering Seed Sets

Use list_seed_sets before applying by name. Without workspaceId, it lists Seed Sets from the published app model. With workspaceId, it lists the effective Workspace model and reports whether each Seed Set comes from the Workspace base or from Workspace edits.

Each listed Seed Set includes its name, label, description, dependencies, content hash, step count, and command names. Use get_seed_set to read the full normalized definition before running commands. If apply_seed_sets receives an unknown name, its error includes available candidates and points back to list_seed_sets.

Placeholders and literal template text

Seed step data supports the same placeholder resolver as design-time tests. Use {{fixtures.name}} or {{captures.name}} for exact values. Non-exact strings interpolate placeholders.

When a command value needs to store external template syntax that also uses double braces, wrap the value with $literal. The runner unwraps it before command execution and does not resolve placeholders inside it:

{
  "body": {
    "$literal": "Hallo {{lead_first_name}}, danke fuer deine Bewerbung bei {{location_name}}."
  },
  "assigneeId": "{{fixtures.recruiterId}}"
}

How a run works

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

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, resolved step inputs, command outputs, captures, 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. The failed step includes the safe runtime failure category and code plus execution and correlation IDs for diagnostic lookup; sensitive guard values and expressions remain in protected logs. Successful steps before the failure keep enough resume metadata for a later mode: "skip-completed" retry to skip those steps and continue from the first step that did not complete. The run-level recovery field reports whether that resume is proven safe, and the MCP error includes a ready-to-run resume action when it is. This keeps retries from replaying commands whose runtime effects already persisted.

If the Workspace contains partial seed effects from an older failed run that does not have per-step resume metadata, skip-completed fails with guidance instead of replaying those commands. Use a fresh disposable Workspace, or use mode: "rerun" / force: true only when duplicate command effects are intentional.

Applying Seed Sets

When the Seed Set definitions already exist in the Workspace base, apply them during Workspace creation:

{
  "tool": "create_workspace",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "fromRelease": "published",
    "name": "Demo review",
    "seedSets": ["demo-leads"],
    "seedMode": "skip-completed"
  }
}

The response includes seedRun when creation-time seeding runs. If seeding fails, the tool returns an error with the new workspaceId, Workspace status, and seed-run details so the run can be inspected or retried.

Use the standalone Design MCP tool when you create or change Seed Set definitions after the Workspace exists, or when you intentionally need a rerun:

1. Run upsert_seed_set to create or update the definition.
2. Run diff_workspace to preview the seed-set:<name> artifact change.
3. Run apply_seed_sets to write Workspace runtime data.

{
  "tool": "apply_seed_sets",
  "arguments": {
    "appId": "11111111-1111-1111-1111-111111111111",
    "workspaceId": "ws_demo",
    "seedSets": ["demo-leads"],
    "mode": "skip-completed"
  }
}

The runner stores a seed-run record with status, step details, hashes, resolved inputs, command outputs, captures, correlation ids, and any error. Reapplying the same Seed Set content to the same Workspace defaults to skipped steps. Use mode: "rerun" or force: true only when repeated command execution is intentional.

Policy-driven follow-ups

Seed command steps intentionally run with policies, triggers, and subscriptions disabled. The command still validates, emits events, stores them, and updates projections, but policy fan-out products are not created automatically.

If a Seed Set step runs a command whose produced events trigger policies in the full model, the seed run includes a policy_fanout_disabled warning on the run and affected step. The warning lists the triggered policies and any command names declared by those policies so authors can add explicit follow-up command steps when their projections or pages need those downstream documents.

For example, if AddContract emits ContractAdded and the full model normally uses policies to run PrepareDatasheetWhenContractAdded and ScheduleAccountingRegistrationOnContract, a Seed Set that only runs AddContract creates the contract projection but not the datasheet or accounting registration projections. Add explicit command steps for the required follow-up products.

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