entity

Import Run

One processing of one source artifact. Aggregate root; retry requeues the same run (ADR-0103).

Entity(Aggregate Root)Status: Implemented in api-v1Aggregate Root

Purpose

An import run is one attempt to turn a stored Revit export artifact into definition-graph nodes and a rematerialized summary. It is not the artifact itself and not a batch of runs.

Identity is ImportRunId. The aggregate references a Design project by ProjectId and does not create projects.

ArtifactReference, IdempotencyKey, ImportCounts, and ImportWarning are value objects on this entity, not separate catalog entities.

Invariants

  • Status path is queued → in_progress → ready | failed | deleted (IllegalImportRunTransitionError). Steward retry requeues the same run (failed | deleted → queued). Ready must delete-graph first (ADR-0103).
  • projectId required after trim (ImportRunProjectIdRequiredError).
  • sourceDocumentId required after trim (ImportRunSourceDocumentIdRequiredError).
  • sourceDocumentName and contractVersion required (ImportRunFieldRequiredError).
  • Reaching ready without counts is not a result (PDG-IM-INV-04).
  • SHA-256 on the artifact is of the uncompressed JSONL (ADR-0071).

Postgres CHECK is queued | in_progress | ready | failed | deleted. The HTTP import-run log and Airtable revit_import_runs label in_progress as processing. There is no persisted uploaded status.

Domain Events

None. The aggregate does not record domain events. Do not invent SourceImportRegistered or SourceImportProcessed catalog pages.

Edit this page