Platform well-known actor seed recovery

Use this runbook only for a local/demo installation where the five well-known Authority principals exist but Platform renders their opaque a000... actor references instead of display names.

Why a forward repair is required

S078_SeedWellKnownActorIdentity.sql selected a tenant through shared.tenants.is_default=true. Platform’s request resolver instead resolves the active tenant_id slug. An installation can therefore have the canonical active default row while no row is marked is_default; S078 then succeeds as a no-op and may already be recorded in platform.schema_migrations.

Forward-only S079_RecoverWellKnownActorIdentity.sql selects the active case-insensitive default slug. It does not create or reclassify a tenant. Its ON CONFLICT DO NOTHING contract preserves self-upserted identities and erased rows.

Preconditions

  1. Freeze and build a committed Platform candidate containing S079. Embedded SQL requires a new platform image; restarting the old image cannot add it.
  2. Confirm shared.tenants contains exactly one active default slug before the seed pass. If it is absent or suspended, reconcile the Authority-owned tenant lifecycle first. Do not set is_default merely to make this seed run.
  3. Inspect pending Platform seed migrations. Enabling bootstrap applies every pending S-prefix Platform migration, not only S079. Confirm that the other local/demo seeds are acceptable for this installation.
  4. Capture the current Platform container image id, build info, health, restart count, and the current PLATFORM_BOOTSTRAP_ENABLED value.

Useful read-only database checks:

SELECT id, tenant_id, is_default, status
FROM shared.tenants
WHERE lower(tenant_id) = 'default';

SELECT migration_name, category, applied_at
FROM platform.schema_migrations
WHERE migration_name IN (
  'S078_SeedWellKnownActorIdentity.sql',
  'S079_RecoverWellKnownActorIdentity.sql'
)
ORDER BY migration_name;

One-time seed pass

  1. Set the operator-owned runtime value PLATFORM_BOOTSTRAP_ENABLED=true. This is a deployment setting, not a source-code or image change.
  2. Force-recreate only the platform compose service from the frozen candidate with --no-deps. Do not restart Router, Authority, PostgreSQL, or unrelated services.
  3. Wait for Platform to become healthy and verify its running image id and /buildinfo.json still identify the frozen candidate.
  4. Verify S079_RecoverWellKnownActorIdentity.sql is recorded as category seed and exactly five a0000003-... rows exist for the UUID belonging to the active default slug.
  5. With a valid tenant-bound Console token, call GET /api/v1/platform/actor-identity/{actorRef} for one seeded actor and verify the projection returns its display name rather than the raw UUID.

Restore the clean default

  1. Restore PLATFORM_BOOTSTRAP_ENABLED=false immediately after the successful seed pass.
  2. Force-recreate only platform again with --no-deps from the same image.
  3. Verify the image id/build info did not change, health is green, restart count is expected, and the actor-identity projection remains resolved.
  4. Retain the pre/post migration rows and forcing-function response in the QA run evidence. Do not rewrite S078 or delete migration-history rows.

If S079 is recorded but the five identities are absent, stop. That means its precondition was not true during the one-time pass; author another forward migration after diagnosing tenant lifecycle state rather than editing an applied migration or hand-writing actor PII rows.