---
id: WF-ACC-BAT-001
title: Write a batch with its automatic close and attention item
trigger: >-
  Ordinary persistence creates, edits, changes lifecycle or removes a batch;
  engine writes also synchronize attention.
product_area: accounting
module: batches
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
implements:
  - CAP-ACC-BAT-001
  - CAP-ACC-BAT-003
  - CAP-ACC-BAT-004
  - CAP-ACC-BAT-005
  - CAP-ACC-BAT-006
  - CAP-ACC-BAT-008
moves:
  - STATE-ACC-BAT-001
crosses:
  - SVC-ACC-BAT-batches
idempotency: >-
  Batch identity deduplicates attention publishing. Ordinary persistence
  maintains the linked single-occurrence schedule rather than allocating a new
  schedule on every edit.
concurrency: >-
  Existing ordinary mutations hold the batch row lock. Caller-supplied versions
  add stale-write protection. Engine writes run under their own request locks,
  and enabled attention writes share the accounting transaction.
hops:
  - 'n': 1
    actor_or_service: Batches persistence
    action: >-
      Apply ordinary name, calendar, status and lock validation before writing
      the batch.
    anchor: >-
      services-accounting:modules/batches/services/persistence/batches.ts:updateBatch
    seam: sync
    on_failure: Validation or conflict refusal aborts the mutation.
    left_inconsistent: No mutation survives the refused transaction.
    observer: The requesting user
    provenance: test
    source: >-
      services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#refuses
      a name another batch of the unit has 409, name_in_use, in 1.0’s sentence
      (D14)
  - 'n': 2
    actor_or_service: Batches persistence with the schedules library
    action: >-
      Manage the linked close schedule on ordinary create and edit paths. Manual
      retirement removes it; scheduled close retains the run schedule. Engine
      saves do not use this helper.
    anchor: >-
      services-accounting:modules/batches/services/persistence/batches.ts:syncAutoCloseSchedule
    seam: sync
    on_failure: Schedule failure aborts the ordinary mutation.
    left_inconsistent: Batch and schedule changes roll back together.
    observer: The requesting user
    provenance: observed
    source: >-
      services-accounting:modules/batches/services/persistence/batches.ts:insertBatch,
      changeBatch, closeBatchOnSchedule, saveBatches
  - 'n': 3
    actor_or_service: Batch attention items
    action: >-
      Synchronize enabled attention from the previous and resulting row,
      publishing waiting work and resolving retired work.
    anchor: >-
      services-accounting:modules/batches/services/persistence/batch-attention-items.ts:syncBatchAttention
    seam: sync
    on_failure: >-
      Enabled attention failure aborts the business transaction; the disabled
      publisher makes no Platform calls.
    left_inconsistent: >-
      Disabled publishing can leave absent or stale items until a later enabled
      sweep.
    observer: The posting responsibility in Platform attention
    provenance: test
    source: >-
      services-accounting:modules/batches/tests/integration/services/persistence/batch-attention-items.integration.spec.js#publishes
      one open item of the batch with every element mapped
  - 'n': 4
    actor_or_service: Database
    action: >-
      Remove a batch only after restrictive references permit deletion, clearing
      any stream intake pointer through its reference action.
    anchor: >-
      services-accounting:modules/batches/services/persistence/batches.ts:deleteBatch
    seam: sync
    on_failure: A restrictive reference produces a dependency conflict.
    left_inconsistent: The protected batch remains available as before.
    observer: The requesting user
    provenance: test
    source: >-
      services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#answers
      409 naming the batch for every table whose restrict foreign key names a
      batch, never a 500 (DEF-ACT-0012)
branches:
  - >-
    Attention synchronization makes no Platform writes when the publishing
    switch is disabled.
waits: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/batches/services/persistence/batches.ts, batch-attention-items.ts;
    services/rules/batch-attention-rules.ts; lib/attention.ts; aws/cdk.json
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-DAT-001, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-001, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005]
---

# Write a batch with its automatic close and attention item

## What It Does

Ordinary collection mutations coordinate the collection, its close schedule and enabled posting attention. This workflow distinguishes those ordinary persistence paths from the engine save path, which synchronizes attention without calling the close-schedule helper.

## The Flow

```mermaid
flowchart LR
  C[Ordinary mutation] --> V[Lock and validate]
  V --> S[Maintain close schedule]
  S --> A[Synchronize enabled attention]
  A --> D[Commit together]
```

## When Something Fails

Transactional failures preserve the prior business state. Turning attention off suppresses Platform work rather than making the business mutation fail; it leaves a catch-up obligation when publishing resumes.

## Open Design Questions

Production attention remains disabled in the pinned deployment configuration. Product must account for waiting work until that integration is enabled.