---
title: CRM → Entities design examination and OpenAI final text
examined_at: '2026-10-22'
examiner: codex
source_sha:
  services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f
  react-console: da63075876b2c5f4a6af07d457bb24ea8bf4c0c7
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  rhythm-v2-docs: 1e38b5d60c0d55ba628b711bfbaee8da7897a046
branch: agent/crm-entities-desi-exam-1
method: >-
  Independent static source examination, route-factory expansion and OpenAI
  final authoring; corpus checks executed, product integration and browser
  suites not executed.
examined:
  artifacts: 52
  invariants: 55
  states: 36
  transitions: 54
  hops: 63
  operations: 93
  screen_actions: 62
  screen_displays: 51
  alternatives: 31
new_findings:
  - FND-CRM-ENT-043
  - FND-CRM-ENT-044
  - FND-CRM-ENT-045
  - FND-CRM-ENT-046
  - FND-CRM-ENT-047
  - FND-CRM-ENT-048
resolved_draft_error: FND-CRM-ENT-046
existing_open_questions:
  - OQ-CRM-ENT-005
  - OQ-CRM-ENT-006
  - OQ-CRM-ENT-007
changes_by_artifact:
  DOM-CRM-ENT-001: >-
    Rewrote attributes and invariants; kept civic-district write refusal
    explicitly unproved and retained contact retry identity.
  DOM-CRM-ENT-002: >-
    Corrected separate numbering versus nonoverlap, recipient-batch
    deduplication, restriction validation layers and template ownership.
  DOM-CRM-ENT-003: >-
    Clarified contact ownership, pending assignment and catalogue facets without
    adding custom-field owners.
  DOM-CRM-ENT-033: >-
    Corrected per-lock audit cardinality, versioned-update scope, classification
    history scope and compliance watermark meaning.
  STATE-CRM-ENT-001: >-
    Separated archive from status, distinguished inactive/deceased/duplicate
    creation, removed universal versioned-delete and permanent-identity claims,
    and bound unarchive directly to the contact test.
  STATE-CRM-ENT-002: >-
    Separated archive from status and qualified creation status, unversioned
    deletion and possible identity reuse.
  STATE-CRM-ENT-003: >-
    Corrected batch submission semantics and current-state versus
    policy-snapshot claims.
  STATE-CRM-ENT-004: >-
    Removed redrive as a failed-run recovery path; retained current-policy batch
    semantics.
  STATE-CRM-ENT-005: >-
    Removed guaranteed five-minute settlement and universal deadlock freedom;
    distinguished calendar classification from primary designation.
  STATE-CRM-ENT-006: Separated dedicated resolution validation from console collection patches.
  STATE-CRM-ENT-007: >-
    Corrected element audit cardinality, accepted no-op requests and independent
    protection; retained the planning-approved ordinary role delete-lock
    exception.
  WF-CRM-ENT-001: >-
    Clarified shared-resource contention and distinguished reconciliation
    rereads from search snapshots.
  WF-CRM-ENT-002: >-
    Removed contradictory stale-retry exception and universal deadlock claim;
    retained complete-payload and explicit-relationship disagreements.
  WF-CRM-ENT-003: >-
    Retained organization retry gap and initial-only compliance evaluation;
    corrected projection and disconnection scope.
  WF-CRM-ENT-004: >-
    Corrected recipient batches, absent versus empty role selection, scheduled
    dispatch guarantees and delivery limitations.
  WF-CRM-ENT-005: >-
    Corrected terminal redrive handling and separated committed cursor progress
    from remaining work.
  WF-CRM-ENT-006: >-
    Corrected pending-link backlog versus settled watermark and dry-run external
    effects.
  WF-CRM-ENT-007: >-
    Corrected workspace-context failure boundary and schedule cadence versus
    deadline.
  WF-CRM-ENT-008: >-
    Removed nonexistent classification revision history and no-op preservation;
    included failed deletion compensation.
  WF-CRM-ENT-009: >-
    Qualified cleanup cadence and association switch behavior; retained
    unversioned deletion.
  WF-CRM-ENT-010: Distinguished console patches from dedicated disconnected-state checks.
  WF-CRM-ENT-011: >-
    Preserved snapshot forwarding and Platform ownership of stale-event
    interpretation.
  SVC-CRM-ENT-entities: >-
    Matched 48 route declarations including health, checked exact authorization,
    rewrote every operation intent and publication reason, and corrected
    compensation and the insert-only communication seam.
  SVC-CRM-ENT-configuration-types: >-
    Matched 45 route declarations including health and portal role reads;
    retained empty object ownership and corrected classification history and
    compensation scope.
  SCR-CRM-ENT-001: >-
    Added inert Assign Owner, mapped export to its real Platform operation and
    identified Recently Viewed as the starting view.
  SCR-CRM-ENT-002: 'Rewrote type chooser, form, retry intent and duplicate-block behavior.'
  SCR-CRM-ENT-003: >-
    Rewrote permission-aware view and distinct read failures; retained
    patch-based disconnection resolution.
  SCR-CRM-ENT-004: >-
    Rewrote original-version preservation, change review and session-proof
    limitation.
  SCR-CRM-ENT-005: Added the implemented export and clarified initial view.
  SCR-CRM-ENT-006: Rewrote configured creation and retained organization retry limitation.
  SCR-CRM-ENT-007: >-
    Corrected action placement and contact-side affiliation permission; retained
    hidden sample controls and missing editor/history findings.
  SCR-CRM-ENT-008: 'Rewrote catalogue replacement, ordering and layout inheritance.'
  SCR-CRM-ENT-009: >-
    Removed invented description; clarified composed template sections and empty
    recipient-role selection.
  SCR-CRM-ENT-010: Corrected alphabetical ordering and separate default-setting action.
  SCR-CRM-ENT-011: >-
    Clarified hidden first-contact control without clearing its value and the
    ordinary role-lock exception.
  SCR-CRM-ENT-012: >-
    Removed invented description and editable active state; distinguished
    console applicability default from API omission default.
  SCR-CRM-ENT-013: >-
    Removed invented description and editable active state; distinguished
    console applicability default from API omission default.
  ADR-CRM-ENT-001: Cited the answered ownership question without reopening it.
  ADR-CRM-ENT-002: Retained the explicit relationship-operation conflict as unresolved.
  ADR-CRM-ENT-003: >-
    Corrected the claim that every console save patches; the approved
    complete-payload decision remains a target.
  ADR-CRM-ENT-004: >-
    Qualified no-op scope and unversioned deletion without altering the approved
    version decision.
  ADR-CRM-ENT-005: Separated current-state reconciliation from search snapshot forwarding.
  ADR-CRM-ENT-006: >-
    Removed nonexistent classification revisions and qualified compensation
    failure.
  ADR-CRM-ENT-007: >-
    Verified registration capability declarations and retained the approved
    custom-field boundary.
  ADR-CRM-ENT-008: >-
    Replaced exactly-once delivery with transactional recipient-batch submission
    and bounded storage semantics.
  ADR-CRM-ENT-009: Retained workspace-date interpretation and qualified deferred effects.
  ADR-CRM-ENT-010: Qualified association activation and deletion dependency scope.
  ADR-CRM-ENT-011: >-
    Corrected universal lock-action wording to match the existing approved
    role-write exception.
  ADR-CRM-ENT-012: Distinguished source-value edits from removals that do write contacts.
  ADR-CRM-ENT-013: >-
    Verified database capture and application read-only history; excluded
    classification records.
  ADR-CRM-ENT-014: Replaced runtime assertions with pinned deployment-default evidence.
  ADR-CRM-ENT-015: >-
    Limited binding absence to scoped declarations and retained missing domain
    publication record.
  RESP-CRM: >-
    Rewrote the Entities row and module prose; retained shared product-area
    introduction, ownership, operations, guarantee references and delegate
    destinations.
structured_changes:
  - >-
    Added new→deceased and new→duplicate contact creation transition rows, with
    observed or inferred pinned sources; existing state names and artifact ids
    remain unchanged.
  - >-
    Changed INV-DOM-CRM-ENT-002-11 enforced_at from api/service to
    api/service/database after checking rule-role references.
  - >-
    Changed the STATE-CRM-ENT-001 unarchive source from
    organizations.archive.integration.spec.js to
    contacts.archive.integration.spec.js#keeps the trimmed reason as
    unarchive_reason.
  - >-
    Added the Platform source pin to SCR-CRM-ENT-001 and SCR-CRM-ENT-005 after
    verifying startQueryExport; added export and inert-action rows as
    documented.
  - >-
    Changed SCR-CRM-ENT-001 export operation_id from Platform data export of the
    current view to startQueryExport (Platform Queries).
  - >-
    Removed the accepted unchanged-lock request from STATE-CRM-ENT-007 invalid
    transitions; accepted no-op behavior remains documented.
  - >-
    Removed inactive screen states from SCR-CRM-ENT-012 and SCR-CRM-ENT-013
    because those catalogues have no editable active field.
  - >-
    Repaired abbreviated services-crm evidence paths in ADR-CRM-ENT-002, 004,
    006, 007, 008, 009, 011, 012 and 013 to their modules/entities locations.
  - >-
    All existing ids, field names, operation identifiers, permission values,
    ownership refs, origins, provenance values, implementation evidence, design
    intent and source pins were preserved except the explicit source,
    operation-identifier and enforcement corrections above; new rows carry their
    own values.
evidence:
  - >-
    rhythm-v2-docs:AGENTS.md; specs/CONVENTIONS.md §§6,9; specs/templates/*;
    specs/crm/entities/MODULE.md; specs/crm/entities/planning/**;
    briefs/design/crm-entities.brief.md; specs/crm/entities/FINDINGS.md;
    specs/crm/entities/ID_REGISTRY.md.
  - >-
    services-crm:modules/entities/aws/api/*.routes.ts and
    modules/configuration-types/aws/api/configuration-types.routes.ts expanded
    at the pinned commit; authorization.access, permission, anyOf and evaluates
    compared with every Service Contract operation.
  - >-
    services-crm:modules/entities/db/*.table.ts and *.view.ts;
    metadata/{contacts,organizations}.object.ts; services/persistence/**;
    services/{contacts,organizations,affiliations,templates,quick-search,assets}/**;
    the 115 cited test-title references, 18 document-heading references and 99
    symbol references were opened at the pin.
  - >-
    services-crm:aws/crm.change-events.ts; aws/crm.names.ts;
    aws/lambda/JOB_RECONCILER.ts;
    aws/cdk/resources/affiliation-date-reconciliation.ts;
    modules/entities/aws/logic/entities-asset-cleanup.lambda.ts;
    modules/entities/aws/resources/entities-asset-cleanup-queue.sqs.ts;
    db/change-event-tables.ts.
  - >-
    react-console:the registered CRM routes and referenced editor, explorer,
    record-view, configuration, authorization, affiliation, data-job and
    query-export dependencies at the pinned commit.
  - >-
    services-platform:docs/standards/{custom-field-capability,record-write-contracts,submission-compatible-operations}.md;
    docs/communications/architecture.md; docs/jobs.md;
    docs/proposals/record-change-history.md;
    modules/queries/aws/api/query-exports.routes.ts.
coverage:
  business_operations: >-
    91/91, plus 2/2 health operations; 48 main-host operations and 45
    classification-host operations.
  table_files: 26/26
  tables: >-
    27/27 module-declared tables, including two tables in the organization-types
    declaration.
  physical_relations: '36/36 named relations: 27 module tables, 3 capture tables and 6 views.'
  screens: 13/13 contracted route/screen surfaces.
  state_models: >-
    7/7; 36 named states and 54 transition rows, including illustrative status
    rows rather than invented guarded graphs.
  state_machines: >-
    0 Entities-owned AWS state machines; hosted bulk work delegates to CRM Data
    Jobs.
  queues: >-
    1/1 Entities asset cleanup queue plus its DLQ covered by deletion and asset
    hops; shared CRM event queue covered by compliance, scan and search flows;
    Platform send queue delegated through the notice workflow.
---
# CRM → Entities Design Examination

The examination covers every design artifact and the Entities responsibility boundary against the pinned implementation and approved planning. All final design prose and descriptive fields were written by OpenAI, with verification commits separated from artifact rewrite commits. A final structure pass restored every required section and authored the state and workflow diagrams.

## Counts Examined

| Artifact or row | Count |
|---|---:|
| Domain Objects | 4 |
| State Models | 7 |
| Workflows | 11 |
| Service Contracts | 2 |
| Screen Contracts | 13 |
| Decision Records | 15 |
| Entities responsibility row | 1 |
| Invariant rows | 55 |
| Named states / transitions | 36 / 54 |
| Workflow hops | 63 |
| Operation rows | 93 |
| Screen displays / actions | 51 / 62 |
| Decision alternatives | 31 |
| Structured source and anchor references | 286 |
| Direct pinned-file references / derived screen sources | 234 / 52 |
| Distinct files reached by direct references | 88 |
| Missing direct paths, symbols or literal test titles | 0 |
| New findings / still open / corrected draft error | 6 / 5 / 1 |

These counts measure examined declarations and evidence homes. They do not report passing execution of the CRM integration suite or console browser suite. Static assertions and implementation were examined; the corpus acceptance commands are the executed checks.

## Coverage

| Inventory | Covered / total | Qualification |
|---|---:|---|
| Business operations | 91 / 91 | Every expanded operation has access, permission, capability and publication annotations. |
| Health operations | 2 / 2 | Public deployment checks are also contracted. |
| Module table files | 26 / 26 | Each has a Domain Object home. |
| Module tables | 27 / 27 | The organization-type file declares the type and its policy rows. |
| Named physical relations | 36 / 36 | Includes three capture tables and six query or effective-value views. |
| Contracted screens | 13 / 13 | Choosers and dialogs remain within their screen contract. |
| State models | 7 / 7 | Archive and protection are independent dimensions; calendar states are derived. |
| Entities cleanup queue | 1 / 1 | Its consumer, failures and dead-letter path are covered. |
| Shared event queue | 1 / 1 integration | Compliance, scan continuation and search have named workflows. |
| Entities-owned AWS state machines | 0 / 0 | Hosted bulk state-machine work belongs to Data Jobs. |

The two expanded route hosts contain additional delegated Data Jobs operations. They are outside Entities ownership and were excluded from the business-operation denominator. The shared managed-asset table serves both contact and organization file facets; it does not introduce another business owner.

## Changes by Artifact

| Artifact | Examination result |
|---|---|
| `DOM-CRM-ENT-001` | Rewrote attributes and invariants; kept civic-district write refusal explicitly unproved and retained contact retry identity. |
| `DOM-CRM-ENT-002` | Corrected separate numbering versus nonoverlap, recipient-batch deduplication, restriction validation layers and template ownership. |
| `DOM-CRM-ENT-003` | Clarified contact ownership, pending assignment and catalogue facets without adding custom-field owners. |
| `DOM-CRM-ENT-033` | Corrected per-lock audit cardinality, versioned-update scope, classification history scope and compliance watermark meaning. |
| `STATE-CRM-ENT-001` | Separated archive from status, distinguished inactive/deceased/duplicate creation, removed universal versioned-delete and permanent-identity claims, and bound unarchive directly to the contact test. |
| `STATE-CRM-ENT-002` | Separated archive from status and qualified creation status, unversioned deletion and possible identity reuse. |
| `STATE-CRM-ENT-003` | Corrected batch submission semantics and current-state versus policy-snapshot claims. |
| `STATE-CRM-ENT-004` | Removed redrive as a failed-run recovery path; retained current-policy batch semantics. |
| `STATE-CRM-ENT-005` | Removed guaranteed five-minute settlement and universal deadlock freedom; distinguished calendar classification from primary designation. |
| `STATE-CRM-ENT-006` | Separated dedicated resolution validation from console collection patches. |
| `STATE-CRM-ENT-007` | Corrected element audit cardinality, accepted no-op requests and independent protection; retained the planning-approved ordinary role delete-lock exception. |
| `WF-CRM-ENT-001` | Clarified shared-resource contention and distinguished reconciliation rereads from search snapshots. |
| `WF-CRM-ENT-002` | Removed contradictory stale-retry exception and universal deadlock claim; retained complete-payload and explicit-relationship disagreements. |
| `WF-CRM-ENT-003` | Retained organization retry gap and initial-only compliance evaluation; corrected projection and disconnection scope. |
| `WF-CRM-ENT-004` | Corrected recipient batches, absent versus empty role selection, scheduled dispatch guarantees and delivery limitations. |
| `WF-CRM-ENT-005` | Corrected terminal redrive handling and separated committed cursor progress from remaining work. |
| `WF-CRM-ENT-006` | Corrected pending-link backlog versus settled watermark and dry-run external effects. |
| `WF-CRM-ENT-007` | Corrected workspace-context failure boundary and schedule cadence versus deadline. |
| `WF-CRM-ENT-008` | Removed nonexistent classification revision history and no-op preservation; included failed deletion compensation. |
| `WF-CRM-ENT-009` | Qualified cleanup cadence and association switch behavior; retained unversioned deletion. |
| `WF-CRM-ENT-010` | Distinguished console patches from dedicated disconnected-state checks. |
| `WF-CRM-ENT-011` | Preserved snapshot forwarding and Platform ownership of stale-event interpretation. |
| `SVC-CRM-ENT-entities` | Matched 48 route declarations including health, checked exact authorization, rewrote every operation intent and publication reason, and corrected compensation and the insert-only communication seam. |
| `SVC-CRM-ENT-configuration-types` | Matched 45 route declarations including health and portal role reads; retained empty object ownership and corrected classification history and compensation scope. |
| `SCR-CRM-ENT-001` | Added inert Assign Owner, mapped export to its real Platform operation and identified Recently Viewed as the starting view. |
| `SCR-CRM-ENT-002` | Rewrote type chooser, form, retry intent and duplicate-block behavior. |
| `SCR-CRM-ENT-003` | Rewrote permission-aware view and distinct read failures; retained patch-based disconnection resolution. |
| `SCR-CRM-ENT-004` | Rewrote original-version preservation, change review and session-proof limitation. |
| `SCR-CRM-ENT-005` | Added the implemented export and clarified initial view. |
| `SCR-CRM-ENT-006` | Rewrote configured creation and retained organization retry limitation. |
| `SCR-CRM-ENT-007` | Corrected action placement and contact-side affiliation permission; retained hidden sample controls and missing editor/history findings. |
| `SCR-CRM-ENT-008` | Rewrote catalogue replacement, ordering and layout inheritance. |
| `SCR-CRM-ENT-009` | Removed invented description; clarified composed template sections and empty recipient-role selection. |
| `SCR-CRM-ENT-010` | Corrected alphabetical ordering and separate default-setting action. |
| `SCR-CRM-ENT-011` | Clarified hidden first-contact control without clearing its value and the ordinary role-lock exception. |
| `SCR-CRM-ENT-012` | Removed invented description and editable active state; distinguished console applicability default from API omission default. |
| `SCR-CRM-ENT-013` | Removed invented description and editable active state; distinguished console applicability default from API omission default. |
| `ADR-CRM-ENT-001` | Cited the answered ownership question without reopening it. |
| `ADR-CRM-ENT-002` | Retained the explicit relationship-operation conflict as unresolved. |
| `ADR-CRM-ENT-003` | Corrected the claim that every console save patches; the approved complete-payload decision remains a target. |
| `ADR-CRM-ENT-004` | Qualified no-op scope and unversioned deletion without altering the approved version decision. |
| `ADR-CRM-ENT-005` | Separated current-state reconciliation from search snapshot forwarding. |
| `ADR-CRM-ENT-006` | Removed nonexistent classification revisions and qualified compensation failure. |
| `ADR-CRM-ENT-007` | Verified registration capability declarations and retained the approved custom-field boundary. |
| `ADR-CRM-ENT-008` | Replaced exactly-once delivery with transactional recipient-batch submission and bounded storage semantics. |
| `ADR-CRM-ENT-009` | Retained workspace-date interpretation and qualified deferred effects. |
| `ADR-CRM-ENT-010` | Qualified association activation and deletion dependency scope. |
| `ADR-CRM-ENT-011` | Corrected universal lock-action wording to match the existing approved role-write exception. |
| `ADR-CRM-ENT-012` | Distinguished source-value edits from removals that do write contacts. |
| `ADR-CRM-ENT-013` | Verified database capture and application read-only history; excluded classification records. |
| `ADR-CRM-ENT-014` | Replaced runtime assertions with pinned deployment-default evidence. |
| `ADR-CRM-ENT-015` | Limited binding absence to scoped declarations and retained missing domain publication record. |
| `RESP-CRM` | Rewrote the Entities row and module prose; retained shared product-area introduction, ownership, operations, guarantee references and delegate destinations. |

The structured change record retains the exact evidence corrections and added rows. Existing approval and intent values were not promoted from code observation. No planning artifact, application source, reader, deployment or workflow configuration was rewritten. Existing identifiers were not renumbered or reused.

## Open Disagreements

The approved complete-replacement contract remains a target rather than the implemented omission behavior. The existing questions about stale no-op retries, explicit relationship ending and deployment activation remain unanswered; answered replacement and ownership questions were cited without being re-decided.

The new open findings distinguish empty recipient selections, pending-link backlog hidden by a settled watermark, classification no-op writes, terminal scan recovery and notification submission versus delivery. The role delete-lock finding was corrected and closed during examination because approved planning already states that exception.

Earlier findings about template compensation, dry-run storage effects, attention publication and timing, hidden organization controls, missing history entry and absent domain publication records remain relevant. Deployment statements describe pinned defaults; live configuration and operator-created protection data were not inspected.

## Validation

Every verification and final artifact commit was preceded by a zero-error corpus check. Dependency installation completed and all four corpus tests passed. Conformance passes with the examination report withheld, but rejects the required report filename under the current recognition rule. Final acceptance and the report commit await authorization to extend that rule or change the requested filename. Source existence, route authorization, required headings, diagram presence, unchanged identifiers and immutable planning are audited separately because the corpus checker does not prove source semantics.

The checker recognizes examination reports only under its existing filename convention. Changing the checker is outside this job’s permitted paths, so the requested report has been prepared without changing that rule.

## Verdict for Andrew

The examined design is a faithful static account of Entities at the pinned commits, with implementation gaps and product disagreements stated explicitly instead of treated as approved behavior. Its weakest areas are deferred cross-service recovery and console evidence, particularly notice delivery, template compensation, pending date work and organization editing or history access. Before implementation preparation, decide the existing retry, relationship-operation and activation questions, clarify empty notice-role and recipient-batch semantics, and require direct regression proof for backlog settlement and compensation failures.