---
id: STATE-PFM-SEC-008
title: Custom and built-in access definition
object: DOM-PFM-SEC-003
product_area: platform
module: security
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
- name: active
  meaning: The definition is available for composition, assignment and evaluation.
  provenance: observed
  source: services-platform:modules/security/services/catalog/catalog-plan.ts:planBuiltInPolicy
- name: archived
  meaning: The definition is retained for history but unavailable for new use or permission contribution.
  provenance: observed
  source: services-platform:modules/security/services/definitions/manage-roles.ts:archiveCustomRole
transitions:
- from: active
  to: archived
  trigger: A customer administrator archives an unused custom definition.
  guard: Management authority is required; a supplied version is checked, and assignments or policy references
    must not prevent archive.
  side_effects:
  - Record security history and request a post-commit flush
  who: Customer Administrator
  provenance: observed
  source: services-platform:modules/security/services/definitions/manage-roles.ts:archiveCustomRole
- from: active
  to: archived
  trigger: A release removes a built-in declaration.
  guard: Only release reconciliation may change the built-in.
  side_effects:
  - Withdraw its authority and record affected holders
  who: Platform System (release reconciliation)
  provenance: observed
  source: services-platform:modules/security/services/catalog/reconcile-catalog.ts:reconcileCatalog
- from: archived
  to: active
  trigger: A later release declares an archived built-in again.
  guard: Only release reconciliation may restore it.
  side_effects:
  - Reuse the built-in identity and references
  who: Platform System (release reconciliation)
  provenance: observed
  source: services-platform:modules/security/services/catalog/catalog-plan.ts:planBuiltInPolicy
- from: active
  to: active
  trigger: A customer edits a custom definition or a release changes built-in content.
  guard: Custom edits validate rules, check any supplied version, delegation and lockout; built-in edits require
    a material content change.
  side_effects:
  - Increment the changed record’s version, return impact and request flushing when permissions change
  who: Customer Administrator, or Platform System for built-ins
  provenance: observed
  source: services-platform:modules/security/services/definitions/manage-roles.ts:updateCustomRole
invalid:
- from: archived
  to: active
  why: Customers cannot unarchive definitions through an administration route; they can create or copy a replacement.
  provenance: observed
  source: services-platform:modules/security/services/catalog/catalog-plan.ts:planBuiltInPolicy
- from: active
  to: archived
  why: Archive is refused for built-ins outside reconciliation and for custom definitions that remain assigned
    or composed.
  provenance: observed
  source: services-platform:modules/security/services/definitions/manage-roles.ts:archiveCustomRole
concurrency: Supplied custom-definition versions are checked, but omission is currently accepted and remains
  debt against the record-write contract. Database safeguards limit built-in writes to reconciliation context.
  Catalog reconciliation uses a database transaction; registry activation in a separate store is outside that
  transaction.
invariants:
- INV-DOM-PFM-SEC-003-13
- INV-DOM-PFM-SEC-003-14
- INV-DOM-PFM-SEC-003-15
- INV-DOM-PFM-SEC-003-16
evidence:
- 'services-platform at ad3f6a65: modules/security/db/security-roles.table.ts, security-policies.table.ts;
  services/definitions/manage-roles.ts, manage-policies.ts, impact.ts; services/catalog/*.'
examined_at: '2026-10-23'
examiner: codex
---

# Custom and built-in access definition

## The Lifecycle

```mermaid
stateDiagram-v2
    state "Active" as active
    state "Archived" as archived
    active --> archived
    active --> archived
    archived --> active
    active --> active
```

The diagram summarizes the observed transition rows; declared edges without an observed writer remain outside the operational graph.

## Transitions Explained

Custom and built-in definitions share active and archived states but have different writers. Custom administration supports archive, while release reconciliation can restore a built-in identity.

Custom version checks are optional in the current routes. Built-in content equality avoids unnecessary version changes; it does not prove that every surrounding deployment action is a no-op.

## What Cannot Happen

Customers cannot unarchive definitions through an administration route; they can create or copy a replacement.

Archive is refused for built-ins outside reconciliation and for custom definitions that remain assigned or composed.

## Concurrency and Timing

Supplied custom-definition versions are checked, but omission is currently accepted and remains debt against the record-write contract. Database safeguards limit built-in writes to reconciliation context. Catalog reconciliation uses a database transaction; registry activation in a separate store is outside that transaction.