---
id: WF-PFM-OPS-011
title: Bring an application into operation for a workspace
product_area: platform
module: operations
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
inference: []
origin: >-
  services-platform:docs/proposals/application-access-and-entitlements.md#6.2 (built and accepted by Andrew
  2026-10-15)
trigger: >-
  A grant or development seed prepares a missing application, or staff retry failed preparation; core
  activation and backfill use direct insertion.
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-OPS-011
  - CAP-PFM-OPS-015
moves:
  - STATE-PFM-OPS-006
crosses:
  - SVC-PFM-OPS-licensing
idempotency: >-
  An enabled row is returned unchanged. Participant work depends on its lifecycle seed contract for repeat
  safety. Core activation and backfill add missing rows only.
concurrency: >-
  Row insertion resolves collisions, but preparation checks precede the lock and participants execute outside
  transactions. Competing preparations can both run work and overwrite an outcome.
hops:
  - 'n': 1
    actor_or_service: Licensing service
    action: Persist provisioning in a separate transaction with system rather than staff change attribution.
    anchor: >-
      services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState
    seam: sync
    on_failure: Propagate a persistence error to the caller.
    left_inconsistent: 'The preceding commercial grant can already exist, though preparation has not begun.'
    observer: Caller’s error is the observation surface.
    provenance: observed
    source: >-
      services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState
  - 'n': 2
    actor_or_service: Licensing service
    action: 'Enter the workspace and initialize declared participants in order, stopping at the first caught error.'
    anchor: >-
      services-platform:modules/licensing/services/enablement/provision-tenant-application.ts:provisionTenantApplication
    seam: sync
    on_failure: Convert a participant error into the preparation explanation.
    left_inconsistent: Earlier participants can have completed while later participants have not run.
    observer: Participant-refused log line is the observation surface.
    provenance: observed
    source: 'services-platform:modules/tenants/services/provisioning/initialize-tenant.ts:initializeTenant'
  - 'n': 3
    actor_or_service: Licensing service
    action: 'Write enabled with first enablement if needed, or provisioning_failed with the participant explanation.'
    anchor: >-
      services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState
    seam: sync
    on_failure: Propagate an unsuccessful outcome write.
    left_inconsistent: The row can remain provisioning without a supported repair or staff retry.
    observer: Staff panel can remain in provisioning without a repair signal is the observation surface.
    provenance: observed
    source: >-
      services-platform:modules/licensing/services/persistence/tenant-applications.ts:setTenantApplicationState
  - 'n': 4
    actor_or_service: Calling operation
    action: >-
      For staff retry, request cache refresh after state change; the route then attempts security-history
      insertion.
    anchor: >-
      services-platform:modules/licensing/services/enablement/provision-tenant-application.ts:retryTenantApplicationProvisioning
    seam: sync
    on_failure: Propagate history persistence failure after recording state and requesting refresh.
    left_inconsistent: The application move can lack its security-history account.
    observer: Request’s error is the observation surface.
    provenance: observed
    source: 'services-platform:modules/licensing/aws/api/licensing.routes.ts:retryTenantApplicationProvisioning'
branches:
  - condition: The application lists no participants (every licensed application today)
    path: Preparation records enabled state immediately.
  - condition: Workspace provisioning activation or deploy backfill
    path: >-
      Core initialization inserts enabled rows only where missing and preserves existing states, including
      suspension.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/licensing/services/enablement/provision-tenant-application.ts,
    services/persistence/tenant-applications.ts, catalog/application-participants.ts;
    modules/tenants/services/provisioning/initialize-tenant.ts, provision-tenant-operations.ts;
    docs/licensing.md §3, §6.
  - >-
    codex examination 2026-10-23: checked the pinned source anchors, planning references and enforcement
    boundaries; unresolved limits are recorded in module findings.
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-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-006, 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-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Bring an application into operation for a workspace

## What It Does

Preparation records its start before invoking the services responsible for an application. It then records a ready state or a participant failure. The caller’s commercial decision is preserved, and enabled applications require no repeat preparation.

## The Flow

```mermaid
flowchart TD
  H0["Persist provisioning in a separate transaction with system rather than staff change attribution."]
  H1["Enter the workspace and initialize declared participants in order, stopping at the first caught error."]
  H0 --> H1
  H2["Write enabled with first enablement if needed, or provisioning_failed with the participant explanation."]
  H1 --> H2
  H3["For staff retry, request cache refresh after state change; the route then attempts security-history insertion."]
  H2 --> H3
```

## When Something Fails

Participant errors produce a reason naming the unsuccessful participant. Earlier work remains and any retry repeats initialization under the participants’ own repeat-safety contract. Preparation uses an initial and outcome write in separate transactions, leaving an interruption window with no recovery path. Every licensed application currently has an empty participant list, but interruption between the writes is still possible.

## Open Design Questions

The existing product question covers recovery of provisioning left behind by an interrupted process.