---
product_area: platform
module: data-job-engine
revision: 1
status: draft
owned_by: MOD-PFM-DJE
synonyms:
  - upload session
  - data-job file
  - dataset file
supersedes: []
id: CON-PFM-DJE-003
name: Upload
feature: FEAT-PFM-DJE-04
product_intent: confirmed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
definition: >-
  An upload session records delivery of an input file to job storage, including its settled state, stored
  version, measured size and distinct declared or verified digest evidence.
not_to_be_confused_with:
  - Photos and document values belong to record-file and asset handling.
  - Generated export files are output rather than submitted job input.
facets:
  - name: Session condition
    meaning: 'Open sessions accept parts; completed, aborted and expired sessions describe settled delivery.'
    used_for: Determining whether input is available for a job.
  - name: Multipart delivery
    meaning: A file travels directly to storage in separately signed parts.
    used_for: Resuming interrupted delivery and distributing transfer work.
  - name: Declared and stored evidence
    meaning: 'Size claims, stored versions and declared or verified digests remain distinguishable.'
    used_for: Assessing integrity and selecting the input version.
  - name: Input format
    meaning: >-
      A supported upload content type describes stored input but does not guarantee every job can parse
      it.
    used_for: Choosing compatible record input.
  - name: Storage lifetime
    meaning: 'Lifecycle policies govern uploads, derived chunks and incomplete parts.'
    used_for: Planning reuse and cleanup.
relationships:
  - to: CON-PFM-DJE-001
    statement: A bulk job references its completed upload and stored version.
    provenance: documented
    source: 'services-crm:docs/data-jobs.md#The bulk lane'
  - to: CON-PFM-DJE-005
    statement: Migration registration compares manifest declarations with the recorded dataset upload evidence.
    provenance: observed
    source: 'services-platform:modules/data-jobs/services/runs/register-run.ts:resolveDatasetUploads'
lifecycle:
  - state: open
    meaning: The client can transfer parts and request destinations.
    how_it_changes: Completion or abort settles it; inspection can notice storage abandonment.
  - state: completed
    meaning: The assembled file has recorded evidence for job input.
    how_it_changes: It stays completed and cannot be aborted through the protocol.
  - state: 'aborted, expired'
    meaning: Delivery was abandoned or refused.
    how_it_changes: Another delivery requires a new session.
acted_on_by:
  - CAP-PFM-DJE-011
  - CAP-PFM-DJE-012
  - CAP-PFM-DJE-016
visible_to:
  - ACT-PFM-035
  - ACT-PFM-036
  - ACT-PFM-037
evidence:
  - >-
    Reviewed evidence: services-platform (ad3f6a65): docs/data-jobs/uploads.md;
    modules/data-jobs/db/data-job-uploads.table.ts; services/uploads/upload-sessions.ts;
    data-jobs.settings.ts.
  - 'Reviewed evidence: services-crm (a8d1364f): docs/data-jobs.md (The bulk lane).'
  - 'Reviewed evidence: react-console (baf6dae3): lib/api/data-jobs/uploads.ts, multipart.ts, sha256.ts.'
---

# Upload

## What It Is

An upload is the recorded delivery of a file that later work can use as input. It gives staff and integrations a durable reference to the file independently of the machine or browser that supplied it. A spreadsheet, migration manifest or dataset can each have an upload session. Finishing that session makes input available; it does not itself create contacts or run an import.

The client declares the file’s identity and size before sending its parts directly to storage. Rhythm coordinates that conversation and records the assembled version. Part receipts let the client establish what arrived and continue an interrupted transfer. The session’s identity is separate from the file name, so staff do not have to treat a name alone as proof of which input a job read.

## What It Is Not

A contact photo and a custom document value belong to record-file handling, even when an import eventually supplies them. An upload here is job input rather than a saved record detail. It is also different from an export produced for download. Its completed state proves that the delivery protocol settled, not that the file’s records satisfy their domain rules.

## How It Is Used

Administrators provide files through the job wizard. Integrations and implementation runners drive the upload conversation through the API. Migration staff upload manifests and datasets before registering their coordinated load.

Good use retains the session reference and inspects completion evidence before submission. A declared digest improves the available integrity information, but callers must distinguish a producer’s declaration from a measurement of stored bytes. A file that can be uploaded may still use a format the chosen record operation cannot read. That incompatibility needs attention at job submission rather than an assumption that completed delivery means valid input.

## Its Facets

**Session condition.** This tells a caller whether parts can still arrive, a file is available or delivery has been abandoned. Settled input is kept distinct from an unfinished transfer.

**Multipart delivery.** Parts separate network transfer from record processing. The client can recover received-part information and request new signed destinations without recreating the intended file input.

**Declared and stored evidence.** The declared size and digest are claims from the client. Stored size and version identify what arrived. Verified digest evidence is available only where the completion implementation can establish it.

**Input format.** Content type describes storage input, while the job’s supported parser determines whether that input can become records.

**Storage lifetime.** Retention affects reuse of old input and cleanup of unfinished transfers. A kept job reference is not a promise that its source file will remain available indefinitely.

## How It Relates

Data jobs read completed uploads by their recorded versions. Migration runs compare package declarations against dataset evidence during registration. Reset preserves input that staff may need for another load, while workspace deletion follows a different cleanup contract. The upload therefore supports processing and recovery without owning the resulting domain records.

## What It Could Become

Product must decide how large-file digest verification becomes dependable. Archive extraction and richer retention visibility are further open edges. Recovery after a storage-first completion crash also needs examination: commentary describes retry recovery that the inspected completion branch does not establish. Future improvements should make delivery evidence stronger without confusing it with record validation.