---
id: WF-PFM-MTD-002
title: Archive a custom field and bring search into line
trigger: Field archival retires current use without discarding values.
product_area: platform
module: metadata
revision: 1
status: draft
design_intent: confirmed
origin: "services-platform:docs/metadata.md#Custom fields: the rules (removal is archival) and custom objects architecture\
  \ D-20 (refuse the archive, Andrew 2026-10-18); docs/proposals/quick-search.md \xA78.5 (archival degrades and\
  \ rebuilds indexes)"
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
- CAP-PFM-MTD-005
- CAP-PFM-MTD-006
moves:
- STATE-PFM-MTD-002
crosses:
- SVC-PFM-MTD-metadata
idempotency: Repeated archival is refused after success. The field-row lock serializes archival and restoration
  without an expected version; search job starts remain outside their commit.
concurrency: Repeated archival is refused after success. The field-row lock serializes archival and restoration
  without an expected version; search job starts remain outside their commit.
hops:
- n: 1
  actor_or_service: Console Fields screen
  action: The Fields client requests archival for the selected definition.
  anchor: react-console:lib/configuration/fields/live-adapter.ts
  seam: sync
  on_failure: Display the API refusal or failure to the administrator.
  left_inconsistent: Before a committed archive there is no field change.
  observer: The initiating person or service and its operation logs.
  provenance: observed
  source: react-console:lib/configuration/fields/live-adapter.ts
- n: 2
  actor_or_service: Metadata archive capability
  action: Metadata locks and validates the field, stamps archival, removes its rules and records search degradation
    and rebuild requests transactionally.
  anchor: services-platform:modules/metadata/services/field-lifecycle/archive-field.ts:archiveField
  seam: sync
  on_failure: Stop and roll back on a lock, repeated archive or dependent-condition refusal.
  left_inconsistent: The definition and index-degradation records commit together.
  observer: The initiating person or service and its operation logs.
  provenance: test
  source: services-platform:modules/metadata/tests/integration/services/persistence/custom-fields.rules.integration.spec.js#refuses
    the archive naming each dependent prop
- n: 3
  actor_or_service: Metadata archive capability
  action: After archival commits, Metadata starts each requested search rebuild execution.
  anchor: services-platform:modules/quick-search/services/rebuild/request-rebuild.ts:startRequestedRebuild
  seam: state_machine
  on_failure: Propagate a start error to the request; reconciliation can settle the pending job as never started.
  left_inconsistent: The field remains archived while search documents can retain its old values.
  observer: The initiating person and job execution state.
  provenance: inferred
  source: services-platform:modules/metadata/services/field-lifecycle/archive-field.ts:archiveField
  note: The post-commit start has no recovery wrapper; the stated consequence follows from that call order and the
    documented reconciliation behavior.
- n: 4
  actor_or_service: Quick Search rebuild
  action: Quick Search runs the requested rebuild to exclude archived property content.
  anchor: services-platform:modules/quick-search/services/rebuild/request-rebuild.ts
  seam: state_machine
  on_failure: The job engine handles retry and final settlement.
  left_inconsistent: Old search content remains until a rebuild completes.
  observer: The initiating person and job execution state.
  provenance: observed
  source: services-platform:modules/metadata/services/field-lifecycle/archive-field.ts:archiveField
branches:
- An unindexed type or workspace undergoing deletion requires no search rebuild.
waits:
- Requested search rebuilding runs after the field archive transaction.
evidence:
- 'services-platform at ad3f6a65: modules/metadata/services/field-lifecycle/archive-field.ts; services/persistence/custom-fields.ts:archiveCustomField;
  modules/quick-search/services/configuration/degrade-fields.ts; services/rebuild/request-rebuild.ts; docs/jobs.md'
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Archive a custom field and bring search into line

## What It Does

Field archival retires current use without discarding values. The transaction also records which search indexes need rebuilding; starting those jobs is a later step.

## The Flow

```mermaid
sequenceDiagram
  participant Admin as Administrator (Fields screen)
  participant Meta as Metadata archive
  participant DB as Definitions and search configuration
  participant Jobs as Rebuild job
  Admin->>Meta: archive field
  Meta->>DB: lock, check dependants, archive, delete rules, record degradation
  DB-->>Meta: committed
  Meta->>Jobs: start each requested rebuild
  alt start fails
    Meta-->>Admin: error (archive already committed)
  else started
    Meta-->>Admin: archived field
    Jobs->>Jobs: rewrite documents without the field
  end
```

## When Something Fails

Display the API refusal or failure to the administrator. Before a committed archive there is no field change. Stop and roll back on a lock, repeated archive or dependent-condition refusal. The definition and index-degradation records commit together. Propagate a start error to the request; reconciliation can settle the pending job as never started. The field remains archived while search documents can retain its old values. The job engine handles retry and final settlement. Old search content remains until a rebuild completes.

## Open Design Questions

Automatic recovery of a never-started search rebuild needs a decision.