---
id: WF-COM-CAT-004
title: Sweep and settle released catalog files
trigger: >-
  Background work removes files no saved record retains. A scheduled sweep queues due work and a
  reference-aware consumer settles it without deleting still-used assets.
product_area: commerce
module: catalog
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
implements:
  - CAP-COM-CAT-006
  - CAP-COM-CAT-005
  - CAP-COM-CAT-003
moves:
  - STATE-COM-CAT-004
crosses:
  - SVC-COM-CAT-catalog
idempotency: >-
  Sweeps claim due work, and settlement rechecks references. Redelivery can settle an already removed asset
  without repeating an unsafe deletion.
concurrency: >-
  One sweep runs at a time and the consumer permits two simultaneous invocations. This limits background
  connection demand but does not guarantee it never overlaps interactive work.
hops:
  - 'n': 1
    actor_or_service: Asset cleanup sweep
    action: 'Run the cross-workspace scheduled sweep, claim due asset rows and publish individual cleanup messages.'
    anchor: 'services-commerce:modules/catalog/services/assets/clean-up-catalog-assets.ts:cleanUpCatalogAssets'
    seam: schedule
    on_failure: >-
      Fail the run and allow later sweeps to recover due work; invocation and queue alarms support
      investigation.
    left_inconsistent: Due files remain until cleanup can claim and settle them.
    observer: Request feedback and service logs expose failures where the caller returns them.
    provenance: documented
    source: 'services-commerce:modules/catalog/aws/logic/catalog-asset-cleanup.lambda.ts'
  - 'n': 2
    actor_or_service: Cleanup queue consumer
    action: >-
      In each asset’s workspace, recheck owner references and retire released assets or delete abandoned
      copies.
    anchor: 'services-commerce:modules/catalog/services/assets/clean-up-one-catalog-asset.ts:cleanUpOneCatalogAsset'
    seam: queue
    on_failure: >-
      Report individual failed receipts for retry; the final permitted receive records failure and the message
      reaches the dead-letter queue.
    left_inconsistent: Failed assets remain stored with their failure trace.
    observer: Request feedback and service logs expose failures where the caller returns them.
    provenance: documented
    source: 'services-commerce:modules/catalog/aws/lambda/ASSET_CLEANUP_CONSUMER.ts'
branches:
  - Settlement retains any file still referenced by an owner record.
waits:
  - >-
    Scheduling can add up to fifteen minutes before queueing; delivery follows, and retired files remain for
    thirty days.
evidence:
  - >-
    services-commerce at c8b66a98: modules/catalog/services/assets/clean-up-catalog-assets.ts,
    clean-up-one-catalog-asset.ts; aws/lambda/ASSET_CLEANUP.ts, ASSET_CLEANUP_CONSUMER.ts;
    aws/logic/catalog-asset-cleanup.lambda.ts; aws/resources/catalog-asset-cleanup-queue.sqs.ts.
controls: [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-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-004, TC-LOG-005, 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, TC-PRV-001, TC-PRV-002]
---

# Sweep and settle released catalog files

## What It Does

Background work removes files no saved record retains. A scheduled sweep queues due work and a reference-aware consumer settles it without deleting still-used assets.

## The Flow

```mermaid
sequenceDiagram
  participant E as Schedule (15 min)
  participant W as Sweep
  participant Q as Cleanup queue
  participant C as Consumer
  participant R as Record reference check
  participant F as File storage
  E->>W: run
  W->>Q: one message per due file
  Q->>C: batch of ten
  C->>R: is the file still referenced?
  alt unreferenced
    C->>F: retire or delete
  else referenced
    C-->>C: keep
  end
  C-->>Q: report failures only
```

## When Something Fails

Fail the run and allow later sweeps to recover due work; invocation and queue alarms support investigation. Due files remain until cleanup can claim and settle them. Report individual failed receipts for retry; the final permitted receive records failure and the message reaches the dead-letter queue. Failed assets remain stored with their failure trace.

## Open Design Questions

The implemented recovery and concurrency behaviour above defines the current boundary. Any change to transaction scope or product authority requires a recorded decision.