---
id: WF-PFM-SEC-012
title: Reconcile shared definitions, founding staff and principals on deploy
trigger: Deployment publishes a service’s route manifest through validation, staging and activation.
product_area: platform
module: security
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/proposals/security-authorization.md (authorization revision 2 §7, §7.2, §8.3);
  founding-staff standing access (Andrew, 2026-10-12)
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
- CAP-PFM-SEC-013
- CAP-PFM-SEC-015
- CAP-PFM-SEC-016
- CAP-PFM-SEC-018
- CAP-PFM-SEC-017
crosses:
- SVC-PFM-SEC-security
idempotency: Immutable releases reject conflicting content. Staging preserves an already active release. Activation
  always invokes catalog commit before checking whether registry state changed; unchanged registry activation
  skips flushing, and unchanged built-in content preserves its version.
concurrency: Catalog reconciliation transacts within Postgres, but route-registry activation uses a separate
  store afterward. During staging the authorizer reads active and staged requirements and applies both to shared
  routes. There is no atomic transaction across catalog and registry.
hops:
- n: 1
  actor_or_service: Deploy (check)
  action: Validate route and permission declarations, HQ restrictions, built-ins and release conflicts; prepare
    catalog changes without committing them.
  anchor: services-platform:modules/security/authorizer/registry/publish.ts
  seam: sync
  on_failure: Return all blocking problems and stop publication.
  left_inconsistent: Preparation makes no catalog change current.
  observer: Deployment output lists the blocking checks.
  provenance: observed
  source: services-platform:modules/security/authorizer/registry/publish.ts (header)
- n: 2
  actor_or_service: Deploy (stage)
  action: Persist the staged manifest before deploying its service code.
  anchor: services-platform:modules/security/aws/lambda/REGISTRY_CHECK.handler.ts
  seam: sync
  on_failure: Stop publication if staging fails.
  left_inconsistent: A successfully staged manifest is visible to authorizer requirement comparison.
  observer: Deployment logs and registry state show staging.
  provenance: observed
  source: services-platform:modules/security/authorizer/registry/publish.ts (header)
- n: 3
  actor_or_service: Deploy (activate) and release reconciliation
  action: Commit catalog permissions and built-ins with history, then activate the separate registry release.
  anchor: services-platform:modules/security/services/catalog/reconcile-catalog.ts:reconcileCatalog
  seam: sync
  on_failure: A catalog error prevents registry activation; a later registry error leaves the committed catalog
    intact.
  left_inconsistent: New catalog state can coexist with old active registry and a staged release.
  observer: Deployment errors, catalog history and registry rows expose the split.
  provenance: observed
  source: services-platform:modules/security/authorizer/ports.postgres.ts (commitCatalog)
- n: 4
  actor_or_service: Platform's own activation
  action: During Platform activation, register the console pool, reconcile founders and standing access, insert
    missing principals and reconcile export coverage.
  anchor: services-platform:modules/security/authorizer/ports.postgres.ts
  seam: sync
  on_failure: Founder/principal best-effort problems are logged without undoing catalog activation.
  left_inconsistent: Missing founder access or principal records can persist until another reconciliation.
  observer: Activation logs expose incomplete auxiliary work.
  provenance: observed
  source: services-platform:modules/security/services/provisioning/ensure-founding-staff.ts; ensure-service-principals.ts
- n: 5
  actor_or_service: Deploy (flush)
  action: Request a flush for the activated API stage.
  anchor: services-platform:modules/security/authorizer/ports.postgres.ts (flushAuthorizerCache)
  seam: state_machine
  on_failure: Report flush failure without unactivating the release.
  left_inconsistent: Earlier decisions retain their bounded cached/context validity.
  observer: The publication result and flush jobs expose the attempt.
  provenance: observed
  source: services-platform:modules/security/authorizer/registry/publish.ts (header)
branches:
- Deployment preserves suspended or revoked founding memberships rather than reinstating them.
- Existing service principals are neither renamed nor resumed by insert-missing reconciliation.
waits: []
evidence:
- 'services-platform at ad3f6a65: modules/security/authorizer/registry/*; authorizer/ports.postgres.ts; aws/lambda/REGISTRY_CHECK.handler.ts;
  services/catalog/*; services/provisioning/ensure-founding-staff.ts, ensure-service-principals.ts, founding-staff.ts;
  aws/api/platform.routes.ts (builtInPolicies).'
examined_at: '2026-10-23'
examiner: codex
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Reconcile shared definitions, founding staff and principals on deploy

## What It Does

Publication has three stages and two storage boundaries. Prepared catalog changes are not current; staged route requirements are visible; activation commits the catalog before switching the registry.

## The Flow

```mermaid
flowchart TD
    H1["Validate release"]
    H2["Stage manifest"]
    H3["Commit catalog then activate registry"]
    H4["Reconcile Platform auxiliary records"]
    H5["Request stage flush"]
    H1 --> H2
    H2 --> H3
    H3 -. Platform auxiliary work within catalog commit .-> H4
    H3 --> H5
```

The diagram separates the relevant success, alternative and failure paths. The numbered hop rows retain the detailed authority checks, delegated work and retry limits.

## When Something Fails

The storage gap can leave catalog and active registry on different releases. Repeating activation is the intended convergence path, but failure/recovery proof remains a finding. Unchanged built-in versions do not imply that every deployment step writes nothing.

Immutable releases reject conflicting content. Staging preserves an already active release. Activation always invokes catalog commit before checking whether registry state changed; unchanged registry activation skips flushing, and unchanged built-in content preserves its version.

Catalog reconciliation transacts within Postgres, but route-registry activation uses a separate store afterward. During staging the authorizer reads active and staged requirements and applies both to shared routes. There is no atomic transaction across catalog and registry.

## Open Design Questions

The recorded findings retain any stronger planning expectation, missing writer or unproved recovery path. Observed behavior does not approve those outstanding product choices.