spaps 0.7.6 → 0.7.8

package/src/fixture-kernel.js

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const axios = require('axios');
 
 const { DEFAULT_PORT } = require('./config');
 const { buildBaseUrl, getServerRuntime } = require('./local-runtime');
@@ -27,7 +28,11 @@ const COMPAT_STORAGE_KEYS = {
   legacy_user: 'spaps_user',
 };
 
-const DEFAULT_PERSONAS = [
+function cloneValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+const BASE_PERSONAS = [
   {
     code: 'user',
     display_name: 'Local User',
@@ -95,16 +100,521 @@ const DEFAULT_PERSONAS = [
   },
 ];
 
+function getBasePersona(code) {
+  const persona = BASE_PERSONAS.find((entry) => entry.code === code);
+  if (!persona) {
+    throw new Error(`Unknown base persona "${code}"`);
+  }
+  return persona;
+}
+
+function makeDerivedPersona(code, displayName, fromCode, overrides = {}) {
+  const base = getBasePersona(fromCode);
+  const {
+    selector,
+    profile,
+    permissions,
+    browser,
+    ...rest
+  } = overrides;
+
+  return {
+    ...cloneValue(base),
+    ...cloneValue(rest),
+    code,
+    display_name: displayName,
+    selector: selector ? cloneValue(selector) : cloneValue(base.selector),
+    profile: {
+      ...cloneValue(base.profile),
+      ...(profile ? cloneValue(profile) : {}),
+    },
+    permissions: permissions ? [...permissions] : [...(base.permissions || [])],
+    browser: {
+      local_storage: {
+        ...(base.browser?.local_storage || {}),
+        ...((browser && browser.local_storage) || {}),
+      },
+    },
+  };
+}
+
+const DEFAULT_PERSONAS = [
+  ...BASE_PERSONAS,
+  makeDerivedPersona('dayrate-guest', 'Dayrate Guest', 'user', {
+    profile: {
+      username: 'dayrate-guest',
+    },
+    scenario: {
+      dayrate: {
+        mode: 'paid',
+        policy_key: null,
+        sample_request: {
+          date: '2026-05-01',
+          slot: 'AM',
+          clientEmail: 'guest-fixture@example.com',
+          clientName: 'Fixture Guest',
+          successUrl: 'https://example.com/dayrate/success',
+          cancelUrl: 'https://example.com/dayrate/cancel',
+        },
+      },
+    },
+  }),
+  makeDerivedPersona('dayrate-entitled', 'Dayrate Entitled', 'user', {
+    permissions: ['view_products', 'book_dayrate_free'],
+    profile: {
+      username: 'dayrate-entitled',
+    },
+    scenario: {
+      dayrate: {
+        mode: 'free',
+        policy_key: 'fixture-dayrate-free-{{global.run_id}}',
+        entitlement_key: 'fixture.dayrate.free.{{global.run_id}}',
+        free_bookings_remaining: 2,
+        sample_request: {
+          date: '2026-05-02',
+          slot: 'AM',
+          clientEmail: 'entitled-fixture@example.com',
+          clientName: 'Fixture Entitled',
+          successUrl: 'https://example.com/dayrate/success',
+          cancelUrl: 'https://example.com/dayrate/cancel',
+          policyKey: 'fixture-dayrate-free-{{global.run_id}}',
+          userId: '{{persona.profile.user_id}}',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'PUT',
+        path: '/api/dayrate/admin/config',
+        body: {
+          base_rate: 12000,
+          available_days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
+          horizon_weeks: 8,
+          min_notice_hours: 1,
+          hold_duration_minutes: 15,
+          timezone: 'America/Toronto',
+          currency: 'usd',
+          product_name: 'Fixture Dayrate',
+          slot_definitions: {
+            AM: { start: '09:00', end: '12:00' },
+            PM: { start: '13:00', end: '16:00' },
+          },
+        },
+      },
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/dayrate/admin/policies',
+        expected_statuses: [201, 409],
+        body: {
+          policyKey: 'fixture-dayrate-free-{{global.run_id}}',
+          entitlementKey: 'fixture.dayrate.free.{{global.run_id}}',
+          freeBookingsPerPeriod: 2,
+          periodDays: 28,
+          overageRate: null,
+          overageCurrency: 'usd',
+          overageProductName: 'Fixture Dayrate Overage',
+          rescheduleIsFree: true,
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'dayrate-entitled',
+          },
+        },
+      },
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/entitlements/manual',
+        expected_statuses: [201, 409],
+        body: {
+          beneficiary_user_id: '{{persona.profile.user_id}}',
+          beneficiary_email: '{{persona.profile.email}}',
+          entitlement_key: 'fixture.dayrate.free.{{global.run_id}}',
+          resource_type: 'user',
+          reason: 'spaps fixture seed',
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'dayrate-entitled',
+          },
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('dayrate-overage', 'Dayrate Overage', 'premium', {
+    permissions: ['view_products', 'book_dayrate_free'],
+    profile: {
+      username: 'dayrate-overage',
+    },
+    scenario: {
+      dayrate: {
+        mode: 'overage',
+        policy_key: 'fixture-dayrate-overage-{{global.run_id}}',
+        entitlement_key: 'fixture.dayrate.overage.{{global.run_id}}',
+        overage_rate: 1500,
+        free_bookings_remaining: 0,
+        sample_request: {
+          date: '2026-05-03',
+          slot: 'PM',
+          clientEmail: 'overage-fixture@example.com',
+          clientName: 'Fixture Overage',
+          successUrl: 'https://example.com/dayrate/success',
+          cancelUrl: 'https://example.com/dayrate/cancel',
+          policyKey: 'fixture-dayrate-overage-{{global.run_id}}',
+          userId: '{{persona.profile.user_id}}',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/dayrate/admin/policies',
+        expected_statuses: [201, 409],
+        body: {
+          policyKey: 'fixture-dayrate-overage-{{global.run_id}}',
+          entitlementKey: 'fixture.dayrate.overage.{{global.run_id}}',
+          freeBookingsPerPeriod: 0,
+          periodDays: 28,
+          overageRate: 1500,
+          overageCurrency: 'usd',
+          overageProductName: 'Fixture Dayrate Overage',
+          rescheduleIsFree: true,
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'dayrate-overage',
+          },
+        },
+      },
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/entitlements/manual',
+        expected_statuses: [201, 409],
+        body: {
+          beneficiary_user_id: '{{persona.profile.user_id}}',
+          beneficiary_email: '{{persona.profile.email}}',
+          entitlement_key: 'fixture.dayrate.overage.{{global.run_id}}',
+          resource_type: 'user',
+          reason: 'spaps fixture seed',
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'dayrate-overage',
+          },
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('email-local-safe', 'Email Local Safe', 'user', {
+    profile: {
+      username: 'email-local-safe',
+    },
+    scenario: {
+      email: {
+        template_key: 'fixture-email-safe-{{global.run_id}}',
+        send_request: {
+          template_key: 'fixture-email-safe-{{global.run_id}}',
+          to: 'recipient@example.com',
+          context: {
+            name: 'Fixture Recipient',
+          },
+        },
+        expected_status: 'short_circuited',
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/email/templates',
+        expected_statuses: [201, 409],
+        body: {
+          name: 'Fixture Local Safe Email',
+          template_key: 'fixture-email-safe-{{global.run_id}}',
+          subject: 'Hello {{name}}',
+          html_body: '<p>Hello {{name}}</p>',
+          text_body: 'Hello {{name}}',
+          from_email: 'noreply@example.com',
+          category: 'fixture',
+          sample_context: {
+            name: 'Fixture Recipient',
+          },
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('webhook-signature-invalid', 'Webhook Signature Invalid', 'admin', {
+    profile: {
+      username: 'webhook-signature-invalid',
+    },
+    scenario: {
+      webhooks: {
+        invalid_request: {
+          path: '/api/webhooks/mailgun/events',
+          expected_status: 401,
+          body: {
+            signature: {
+              timestamp: '{{global.epoch}}',
+              token: 'fixture-invalid-token',
+              signature: 'not-a-real-signature',
+            },
+            'event-data': {
+              event: 'delivered',
+              timestamp: '2026-05-04T09:00:00Z',
+              message: {
+                headers: {
+                  'message-id': 'fixture-invalid-msg',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+  makeDerivedPersona('webhook-replay', 'Webhook Replay', 'admin', {
+    profile: {
+      username: 'webhook-replay',
+    },
+    scenario: {
+      webhooks: {
+        replay_request: {
+          path: '/api/webhooks/mailgun/events',
+          expected_status: 409,
+          signing_key: 'test-key',
+          token: 'fixture-replay-token',
+          body_template: {
+            signature: {
+              timestamp: '{{global.epoch}}',
+              token: 'fixture-replay-token',
+              signature: '{{scenario_signature}}',
+            },
+            'event-data': {
+              event: 'delivered',
+              timestamp: '2026-05-04T09:05:00Z',
+              message: {
+                headers: {
+                  'message-id': 'fixture-replay-msg',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+  makeDerivedPersona('policy-admin-allow', 'Policy Admin Allow', 'admin', {
+    scenario: {
+      policies: {
+        policy_name: 'fixture-admin-read-{{global.run_id}}',
+        authorize_request: {
+          policy_name: 'fixture-admin-read-{{global.run_id}}',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/policies',
+        expected_statuses: [201, 409],
+        body: {
+          name: 'fixture-admin-read-{{global.run_id}}',
+          description: 'Allow admin-only fixture policy',
+          effect: 'allow',
+          conditions: {
+            has_role: {
+              role: 'admin',
+            },
+          },
+          priority: 100,
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'policy-admin-allow',
+          },
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('policy-denied-no-wallet', 'Policy Denied No Wallet', 'user', {
+    permissions: ['view_products'],
+    scenario: {
+      policies: {
+        policy_name: 'fixture-requires-wallet-{{global.run_id}}',
+        expected_decision: 'deny',
+        authorize_request: {
+          policy_name: 'fixture-requires-wallet-{{global.run_id}}',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/policies',
+        expected_statuses: [201, 409],
+        body: {
+          name: 'fixture-requires-wallet-{{global.run_id}}',
+          description: 'Require a Solana wallet for access',
+          effect: 'allow',
+          conditions: {
+            has_wallet: {
+              chain: 'solana',
+            },
+          },
+          priority: 100,
+          metadata: {
+            source: 'spaps-fixture-seed',
+            persona: 'policy-denied-no-wallet',
+          },
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('issue-reporter', 'Issue Reporter', 'user', {
+    permissions: ['view_products'],
+    scenario: {
+      issue_reporting: {
+        expected_status: 201,
+        create_request: {
+          target: {
+            component_key: 'feedback-button',
+            component_label: 'Feedback Button',
+            page_url: 'https://example.com/app',
+            surface_ref: 'feedback-fab',
+            metadata: {
+              screenshots: [
+                {
+                  url: 'https://example.com/screenshots/fixture-1.png',
+                  timestamp: '2026-05-05T09:00:00Z',
+                },
+              ],
+            },
+          },
+          note: 'Fixture issue report with screenshots for local issue-reporting flows.',
+          reporter_role_hint: 'member',
+        },
+        reply_request: {
+          note: 'Fixture follow-up after a support response.',
+          reporter_role_hint: 'member',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'persona',
+        method: 'POST',
+        path: '/api/v1/issue-reports',
+        expected_statuses: [201],
+        body: {
+          target: {
+            component_key: 'feedback-button',
+            component_label: 'Feedback Button',
+            page_url: 'https://example.com/app',
+            surface_ref: 'feedback-fab',
+            metadata: {
+              screenshots: [
+                {
+                  url: 'https://example.com/screenshots/fixture-1.png',
+                  timestamp: '2026-05-05T09:00:00Z',
+                },
+              ],
+            },
+          },
+          note: 'Fixture issue report with screenshots for local issue-reporting flows.',
+          reporter_role_hint: 'member',
+        },
+        capture: {
+          existing_issue_report_id: 'id',
+          existing_issue_case_id: 'linked_case.case_id',
+        },
+      },
+    ],
+  }),
+  makeDerivedPersona('issue-reporter-blocked', 'Issue Reporter Blocked', 'user', {
+    permissions: [],
+    selector: {
+      query_param: { _user: 'user' },
+      headers: {
+        'X-Test-User': 'user',
+        'X-API-Key': '{{seed.blocked_app_api_key}}',
+      },
+    },
+    application: {
+      application_id: '{{seed.blocked_app_id}}',
+      application_slug: '{{seed.blocked_app_slug}}',
+      api_key: '{{seed.blocked_app_api_key}}',
+    },
+    scenario: {
+      issue_reporting: {
+        expected_status: 403,
+        required_capability: 'issue_reporting',
+        create_request: {
+          target: {
+            component_key: 'feedback-button',
+            component_label: 'Feedback Button',
+            page_url: 'https://example.com/app',
+            surface_ref: 'feedback-fab',
+            metadata: {},
+          },
+          note: 'Blocked issue reporter fixture should fail until capability is granted.',
+          reporter_role_hint: 'member',
+        },
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/admin/create-app',
+        expected_statuses: [201],
+        body: {
+          name: 'Fixture Issue Reporting Blocked {{global.run_id}}',
+          slug: 'fixture-ir-blocked-{{global.run_id}}',
+          settings: {
+            issue_reporting_required_capability: 'issue_reporting',
+          },
+        },
+        capture: {
+          blocked_app_api_key: 'api_key',
+          blocked_app_id: 'application.id',
+          blocked_app_slug: 'application.slug',
+        },
+      },
+    ],
+  }),
+];
+
 const DEFAULT_ROLE_GRANTS = {
   user: ['user'],
   admin: ['admin', 'super_admin'],
   premium: ['user'],
+  'dayrate-guest': ['user'],
+  'dayrate-entitled': ['user'],
+  'dayrate-overage': ['user'],
+  'email-local-safe': ['user'],
+  'webhook-signature-invalid': ['admin', 'super_admin'],
+  'webhook-replay': ['admin', 'super_admin'],
+  'policy-admin-allow': ['admin', 'super_admin'],
+  'policy-denied-no-wallet': ['user'],
+  'issue-reporter': ['user'],
+  'issue-reporter-blocked': ['user'],
 };
 
 const DEFAULT_ENTITLEMENT_GRANTS = {
   user: [],
   admin: ['paid_access', 'admin_console'],
   premium: ['paid_access'],
+  'dayrate-guest': [],
+  'dayrate-entitled': ['fixture.dayrate.free.{{global.run_id}}'],
+  'dayrate-overage': ['fixture.dayrate.overage.{{global.run_id}}'],
+  'email-local-safe': [],
+  'webhook-signature-invalid': [],
+  'webhook-replay': [],
+  'policy-admin-allow': [],
+  'policy-denied-no-wallet': [],
+  'issue-reporter': [],
+  'issue-reporter-blocked': [],
 };
 
 function createCliError(code, message) {
@@ -256,7 +766,7 @@ Repo-local SPAPS auth fixtures live here.
 What to edit:
 
 - \`app.json\`: local SPAPS server and browser target settings
-- \`users.json\`: personas, profile data, selector hints, and custom browser storage
+- \`users.json\`: personas, profile data, scenario metadata, optional seed steps, selector hints, and custom browser storage
 - \`roles.json\`: persona-to-role grants
 - \`entitlements.json\`: persona-to-entitlement grants
 
@@ -272,8 +782,14 @@ Common workflow:
 1. Run \`npx spaps fixtures init\`
 2. Edit \`.spaps/users.json\`, \`.spaps/roles.json\`, or \`.spaps/entitlements.json\`
 3. Run \`npx spaps fixtures apply\`
-4. Point Playwright or local scripts at the generated browser artifacts
-5. Include \`/${DEFAULT_BRIDGE_SCRIPT_NAME}\` before your app boots if you want frontend-only persona switching
+4. Run \`npx spaps fixtures apply --seed --persona <code>\` when a domain persona needs real local DB state
+5. Point Playwright or local scripts at the generated browser artifacts
+6. Include \`/${DEFAULT_BRIDGE_SCRIPT_NAME}\` before your app boots if you want frontend-only persona switching
+
+Notes:
+
+- \`--seed\` only runs against a reachable SPAPS server with local mode active
+- Seed steps use the persona metadata already in \`.spaps/users.json\`; no extra backend-only fixture routes are required
 `;
 }
 
@@ -405,6 +921,322 @@ function ensurePersona(usersConfig, code) {
   return persona;
 }
 
+function buildFixtureRunState(appConfig, runtime) {
+  const now = new Date();
+  const generatedAt = now.toISOString();
+  return {
+    global: {
+      generated_at: generatedAt,
+      epoch: Math.floor(now.getTime() / 1000),
+      run_id: generatedAt
+        .replace(/[-:]/g, '')
+        .replace(/\.\d+Z$/, 'z')
+        .replace('T', 't'),
+    },
+    runtime: {
+      api_url: appConfig.server.api_url,
+      application_id: appConfig.server.application_id,
+      application_slug: appConfig.server.application_slug,
+      local_mode_active: appConfig.server.local_mode_active,
+      running: appConfig.server.running,
+      environment: runtime?.local_mode?.environment || appConfig.server.environment || null,
+    },
+    seed: {},
+  };
+}
+
+function getNestedValue(source, dottedPath) {
+  if (!source || typeof source !== 'object' || !dottedPath) {
+    return undefined;
+  }
+
+  return String(dottedPath)
+    .split('.')
+    .filter(Boolean)
+    .reduce((current, segment) => {
+      if (current === undefined || current === null) {
+        return undefined;
+      }
+
+      if (Array.isArray(current)) {
+        const index = Number(segment);
+        return Number.isInteger(index) ? current[index] : undefined;
+      }
+
+      return current[segment];
+    }, source);
+}
+
+function resolveTemplateLookup(context, expression) {
+  const lookup = String(expression || '').trim();
+  if (!lookup) {
+    return undefined;
+  }
+
+  if (!lookup.includes('.') && Object.prototype.hasOwnProperty.call(context, lookup)) {
+    return context[lookup];
+  }
+
+  return getNestedValue(context, lookup);
+}
+
+function renderTemplateValue(value, context) {
+  if (typeof value === 'string') {
+    const matches = [...value.matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)];
+    if (matches.length === 0) {
+      return value;
+    }
+
+    if (matches.length === 1 && matches[0][0] === value) {
+      const resolved = resolveTemplateLookup(context, matches[0][1]);
+      return resolved === undefined ? value : cloneValue(resolved);
+    }
+
+    return value.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, expression) => {
+      const resolved = resolveTemplateLookup(context, expression);
+      return resolved === undefined ? match : String(resolved);
+    });
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => renderTemplateValue(entry, context));
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, renderTemplateValue(entry, context)])
+    );
+  }
+
+  return value;
+}
+
+function unwrapEnvelope(payload) {
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    payload.success === true &&
+    Object.prototype.hasOwnProperty.call(payload, 'data')
+  ) {
+    return payload.data;
+  }
+
+  return payload;
+}
+
+function describeStatuses(statuses = []) {
+  if (!Array.isArray(statuses) || statuses.length === 0) {
+    return '2xx';
+  }
+  return statuses.join(', ');
+}
+
+function buildApplicationSummary(appConfig, persona = {}) {
+  const override = persona.application || {};
+  return {
+    api_url: override.api_url || appConfig.server.api_url,
+    application_id: override.application_id || override.id || appConfig.server.application_id || null,
+    application_slug: override.application_slug || override.slug || appConfig.server.application_slug || null,
+    api_key: override.api_key || null,
+    local_mode_active: appConfig.server.local_mode_active,
+  };
+}
+
+function buildPersonaTemplateContext(appConfig, persona, fixtureRunState) {
+  return {
+    global: fixtureRunState.global,
+    runtime: fixtureRunState.runtime,
+    seed: fixtureRunState.seed,
+    persona,
+    application: buildApplicationSummary(appConfig, persona),
+    scenario: persona.scenario || {},
+  };
+}
+
+function resolvePersonaDefinition(appConfig, persona, fixtureRunState) {
+  return renderTemplateValue(cloneValue(persona), buildPersonaTemplateContext(appConfig, persona, fixtureRunState));
+}
+
+function resolveConfigTemplates(config, fixtureRunState) {
+  return renderTemplateValue(cloneValue(config), fixtureRunState);
+}
+
+function resolveSeedActor({ appConfig, usersConfig, persona, actor = 'persona', fixtureRunState }) {
+  const actorCode = actor === 'persona' ? persona.code : actor;
+  const actorPersona = ensurePersona(usersConfig, actorCode);
+  return resolvePersonaDefinition(appConfig, actorPersona, fixtureRunState);
+}
+
+function buildSeedUrl(apiUrl, requestPath, queryParams = {}) {
+  const url = new URL(requestPath, apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`);
+  for (const [key, value] of Object.entries(queryParams || {})) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+function assertSeedingRuntime(runtime, port) {
+  if (!runtime?.running) {
+    throw createCliError(
+      'ESEED',
+      `Fixture seeding requires a running SPAPS server on port ${port}. Start it with "npx spaps local --port ${port}" or omit --seed.`
+    );
+  }
+
+  if (runtime.local_mode?.active !== true) {
+    throw createCliError(
+      'ESEED',
+      'Fixture seeding requires SPAPS local mode so persona routing can use X-Test-User headers. Enable local mode or omit --seed.'
+    );
+  }
+}
+
+async function runSeedSequence({
+  appConfig,
+  usersConfig,
+  persona,
+  fixtureRunState,
+}) {
+  const steps = Array.isArray(persona.seed) ? persona.seed : [];
+  if (steps.length === 0) {
+    return null;
+  }
+
+  const requests = [];
+  const captures = {};
+
+  for (const step of steps) {
+    const resolvedPersona = resolvePersonaDefinition(appConfig, persona, fixtureRunState);
+    const actor = resolveSeedActor({
+      appConfig,
+      usersConfig,
+      persona,
+      actor: step.as || 'persona',
+      fixtureRunState,
+    });
+    const templateContext = buildPersonaTemplateContext(appConfig, resolvedPersona, fixtureRunState);
+    const resolvedStep = renderTemplateValue(cloneValue(step), templateContext);
+    const application = buildApplicationSummary(appConfig, actor);
+    const headers = {
+      Accept: 'application/json',
+      ...(resolvedStep.body ? { 'Content-Type': 'application/json' } : {}),
+      ...(actor.selector?.headers || {}),
+    };
+
+    if (application.api_key && !headers['X-API-Key']) {
+      headers['X-API-Key'] = application.api_key;
+    }
+
+    const url = buildSeedUrl(
+      appConfig.server.api_url,
+      resolvedStep.path,
+      actor.selector?.query_param || {}
+    );
+
+    let response;
+    try {
+      response = await axios({
+        method: resolvedStep.method || 'GET',
+        url,
+        data: resolvedStep.body || null,
+        headers,
+        timeout: 5000,
+        validateStatus: () => true,
+      });
+    } catch (error) {
+      throw createCliError(
+        'ESEED',
+        `Fixture seed request for persona "${persona.code}" failed at ${resolvedStep.method || 'GET'} ${resolvedStep.path}: ${error.message}`
+      );
+    }
+
+    const expectedStatuses =
+      Array.isArray(resolvedStep.expected_statuses) && resolvedStep.expected_statuses.length > 0
+        ? resolvedStep.expected_statuses
+        : null;
+    const ok = expectedStatuses
+      ? expectedStatuses.includes(response.status)
+      : response.status >= 200 && response.status < 300;
+
+    if (!ok) {
+      throw createCliError(
+        'ESEED',
+        `Fixture seed request for persona "${persona.code}" failed at ${resolvedStep.method || 'GET'} ${resolvedStep.path}: expected ${describeStatuses(expectedStatuses)}, received ${response.status}.`
+      );
+    }
+
+    const payload = unwrapEnvelope(response.data);
+    const captured = {};
+    for (const [key, lookup] of Object.entries(resolvedStep.capture || {})) {
+      const capturedValue = getNestedValue(payload, lookup);
+      if (capturedValue === undefined) {
+        throw createCliError(
+          'ESEED',
+          `Fixture seed request for persona "${persona.code}" could not capture "${key}" from "${lookup}" at ${resolvedStep.method || 'GET'} ${resolvedStep.path}.`
+        );
+      }
+
+      fixtureRunState.seed[key] = capturedValue;
+      captures[key] = capturedValue;
+      captured[key] = capturedValue;
+    }
+
+    requests.push({
+      as: actor.code,
+      method: resolvedStep.method || 'GET',
+      path: resolvedStep.path,
+      status: response.status,
+      expected_statuses: expectedStatuses,
+      captured,
+    });
+  }
+
+  return {
+    persona: persona.code,
+    request_count: requests.length,
+    captures,
+    requests,
+  };
+}
+
+async function runFixtureSeeding({
+  appConfig,
+  runtime,
+  usersConfig,
+  personaCode = null,
+  fixtureRunState,
+  port,
+}) {
+  assertSeedingRuntime(runtime, port);
+
+  const selectedPersonas = personaCode
+    ? [ensurePersona(usersConfig, personaCode)]
+    : usersConfig.personas;
+  const seeded = [];
+
+  for (const persona of selectedPersonas) {
+    const result = await runSeedSequence({
+      appConfig,
+      usersConfig,
+      persona,
+      fixtureRunState,
+    });
+
+    if (result) {
+      seeded.push(result);
+    }
+  }
+
+  return {
+    enabled: true,
+    personas: seeded,
+    captures: { ...fixtureRunState.seed },
+  };
+}
+
 function stringifyStorageValue(value) {
   if (typeof value === 'string') {
     return value;
@@ -440,6 +1272,7 @@ function base64UrlEncodeJson(value) {
 function buildFixtureTokens(appConfig, persona, roles) {
   const now = Math.floor(Date.now() / 1000);
   const primaryRole = roles[0] || 'user';
+  const application = buildApplicationSummary(appConfig, persona);
   const header = base64UrlEncodeJson({ alg: 'none', typ: 'JWT' });
   const payload = base64UrlEncodeJson({
     sub: persona.profile?.user_id,
@@ -448,8 +1281,8 @@ function buildFixtureTokens(appConfig, persona, roles) {
     role: primaryRole,
     roles,
     tier: persona.profile?.tier || 'free',
-    app_id: appConfig.server.application_id,
-    aud: appConfig.server.application_slug || 'spaps-fixture',
+    app_id: application.application_id,
+    aud: application.application_slug || 'spaps-fixture',
     iss: 'spaps-fixture',
     iat: now,
     exp: now + (60 * 60 * 24 * 30),
@@ -465,10 +1298,11 @@ function buildFixtureTokens(appConfig, persona, roles) {
 
 function buildEntitlementRecords(appConfig, persona, entitlementsConfig) {
   const entitlementKeys = entitlementsConfig.grants?.[persona.code] || [];
+  const application = buildApplicationSummary(appConfig, persona);
 
   return entitlementKeys.map((entitlementKey, index) => ({
     id: `fixture-${persona.code}-${index + 1}`,
-    application_id: appConfig.server.application_id,
+    application_id: application.application_id,
     beneficiary_user_id: persona.profile?.user_id || null,
     beneficiary_email: persona.profile?.email || null,
     entitlement_key: entitlementKey,
@@ -490,6 +1324,7 @@ function buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig) {
   const entitlements = entitlementsConfig.grants?.[persona.code] || [];
   const permissions = Array.isArray(persona.permissions) ? persona.permissions : [];
   const primaryRole = roles[0] || 'user';
+  const application = buildApplicationSummary(appConfig, persona);
 
   return {
     id: persona.profile?.user_id || null,
@@ -503,7 +1338,7 @@ function buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig) {
     is_super_admin: roles.includes('super_admin'),
     entitlements,
     active_entitlements: entitlements.map((entitlementKey) => ({ key: entitlementKey })),
-    application_id: appConfig.server.application_id || null,
+    application_id: application.application_id || null,
     fixture_persona: persona.code,
   };
 }
@@ -544,6 +1379,7 @@ function buildBridgeConfig(appConfig, users, rolesConfig, entitlementsConfig) {
       display_name: persona.display_name,
       selector: persona.selector || {},
       route_hint: buildRouteHint(appConfig, persona),
+      application: buildApplicationSummary(appConfig, persona),
       user: buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig),
       tokens: buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []),
       entitlement_keys: entitlementsConfig.grants?.[persona.code] || [],
@@ -605,7 +1441,7 @@ function buildDevAuthBridgeScript(config) {
     localStorage.setItem(STORAGE_KEYS.profile, JSON.stringify(persona.user));
     localStorage.setItem(STORAGE_KEYS.roles, JSON.stringify(persona.user.roles || []));
     localStorage.setItem(STORAGE_KEYS.entitlements, JSON.stringify(persona.entitlement_keys || []));
-    localStorage.setItem(STORAGE_KEYS.application, JSON.stringify(CONFIG.application));
+    localStorage.setItem(STORAGE_KEYS.application, JSON.stringify(persona.application || CONFIG.application));
     localStorage.setItem(STORAGE_KEYS.runtime, JSON.stringify({
       auth_mode: CONFIG.auth_mode,
       local_mode_active: CONFIG.local_mode_active
@@ -841,6 +1677,7 @@ function buildDevAuthBridgeScript(config) {
 function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlementsConfig) {
   const user = buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig);
   const tokens = buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []);
+  const application = buildApplicationSummary(appConfig, persona);
   const localStorage = [
     {
       name: FIXTURE_KEYS.active_persona,
@@ -864,11 +1701,7 @@ function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlements
     },
     {
       name: FIXTURE_KEYS.application,
-      value: stringifyStorageValue({
-        api_url: appConfig.server.api_url,
-        application_id: appConfig.server.application_id,
-        application_slug: appConfig.server.application_slug,
-      }),
+      value: stringifyStorageValue(application),
     },
     {
       name: FIXTURE_KEYS.runtime,
@@ -921,6 +1754,7 @@ function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlements
 function buildPersonaContext(appConfig, persona, rolesConfig, entitlementsConfig, paths) {
   const user = buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig);
   const tokens = buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []);
+  const application = buildApplicationSummary(appConfig, persona);
   return {
     persona: persona.code,
     display_name: persona.display_name,
@@ -928,16 +1762,12 @@ function buildPersonaContext(appConfig, persona, rolesConfig, entitlementsConfig
     route_hint: buildRouteHint(appConfig, persona),
     selector: persona.selector || {},
     profile: persona.profile || {},
+    scenario: persona.scenario || {},
     roles: rolesConfig.grants?.[persona.code] || [],
     entitlements: entitlementsConfig.grants?.[persona.code] || [],
     user,
     tokens,
-    application: {
-      api_url: appConfig.server.api_url,
-      application_id: appConfig.server.application_id,
-      application_slug: appConfig.server.application_slug,
-      local_mode_active: appConfig.server.local_mode_active,
-    },
+    application,
     artifacts: {
       storage_state_path: path.join(paths.browserDir, `${persona.code}.storage-state.json`),
       headers_path: path.join(paths.browserDir, `${persona.code}.headers.json`),
@@ -946,7 +1776,16 @@ function buildPersonaContext(appConfig, persona, rolesConfig, entitlementsConfig
   };
 }
 
-function writePersonaArtifacts({ rootDir, paths, appConfig, users, roles, entitlements, personaCode = null }) {
+function writePersonaArtifacts({
+  rootDir,
+  paths,
+  appConfig,
+  users,
+  roles,
+  entitlements,
+  personaCode = null,
+  seedResultsByPersona = {},
+}) {
   const selectedCodes = personaCode ? [ensurePersona(users, personaCode).code] : users.personas.map((persona) => persona.code);
   const generated = [];
 
@@ -955,6 +1794,7 @@ function writePersonaArtifacts({ rootDir, paths, appConfig, users, roles, entitl
     const storageState = buildStorageStateArtifact(appConfig, persona, roles, entitlements);
     const headers = buildHeaderArtifact(appConfig, persona);
     const context = buildPersonaContext(appConfig, persona, roles, entitlements, paths);
+    context.seed = seedResultsByPersona[code] || null;
 
     writeJson(context.artifacts.storage_state_path, storageState);
     writeJson(context.artifacts.headers_path, headers);
@@ -1000,6 +1840,8 @@ async function applyFixtures({
   baseUrl = null,
   version = '0.0.0',
   persona = null,
+  seed = false,
+  subcommand = 'apply',
 } = {}) {
   const rootDir = resolveRepoRoot(dir);
   const paths = resolveFixturePaths(rootDir);
@@ -1029,32 +1871,55 @@ async function applyFixtures({
     files_skipped: [],
   });
 
+  const fixtureRunState = buildFixtureRunState(appConfig, runtime);
+  const seeding = seed
+    ? await runFixtureSeeding({
+        appConfig,
+        runtime,
+        usersConfig: kernel.users,
+        personaCode: persona,
+        fixtureRunState,
+        port,
+      })
+    : null;
+  const resolvedUsers = {
+    ...kernel.users,
+    personas: kernel.users.personas.map((entry) => resolvePersonaDefinition(appConfig, entry, fixtureRunState)),
+  };
+  const resolvedRoles = resolveConfigTemplates(kernel.roles, fixtureRunState);
+  const resolvedEntitlements = resolveConfigTemplates(kernel.entitlements, fixtureRunState);
+  const seedResultsByPersona = Object.fromEntries(
+    (seeding?.personas || []).map((entry) => [entry.persona, entry])
+  );
+
   const generated = writePersonaArtifacts({
     rootDir,
     paths,
     appConfig,
-    users: kernel.users,
-    roles: kernel.roles,
-    entitlements: kernel.entitlements,
+    users: resolvedUsers,
+    roles: resolvedRoles,
+    entitlements: resolvedEntitlements,
     personaCode: persona,
+    seedResultsByPersona,
   });
   const bridge = writeDevAuthBridge({
     rootDir,
     paths,
     appConfig,
-    users: kernel.users,
-    roles: kernel.roles,
-    entitlements: kernel.entitlements,
+    users: resolvedUsers,
+    roles: resolvedRoles,
+    entitlements: resolvedEntitlements,
   });
 
   return {
     success: true,
     command: 'fixtures',
-    subcommand: persona ? 'storage-state' : 'apply',
+    subcommand,
     root_dir: rootDir,
     fixture_dir: paths.fixtureDir,
     bootstrapped,
     runtime,
+    seeding,
     generated: {
       personas: generated,
       bridge,
@@ -1074,7 +1939,7 @@ async function applyFixtures({
 }
 
 async function exportStorageState(options = {}) {
-  const result = await applyFixtures(options);
+  const result = await applyFixtures({ ...options, subcommand: 'storage-state' });
   const personaArtifact = result.generated.personas[0];
   return {
     success: true,
@@ -1089,6 +1954,7 @@ async function exportStorageState(options = {}) {
     route_hint: personaArtifact.route_hint,
     bridge: result.generated.bridge,
     runtime: result.runtime,
+    seeding: result.seeding,
     next_steps: result.next_steps,
   };
 }
@@ -1098,6 +1964,7 @@ async function resetFixtures({
   port = DEFAULT_PORT,
   baseUrl = null,
   version = '0.0.0',
+  seed = false,
 } = {}) {
   const rootDir = resolveRepoRoot(dir);
   const paths = resolveFixturePaths(rootDir);
@@ -1114,6 +1981,7 @@ async function resetFixtures({
     port,
     baseUrl,
     version,
+    seed,
   });
 
   return {
@@ -1127,6 +1995,7 @@ async function resetFixtures({
     files_overwritten: initResult.files_overwritten,
     generated: applyResult.generated,
     runtime: applyResult.runtime,
+    seeding: applyResult.seeding,
     next_steps: applyResult.next_steps,
   };
 }