Migrations

Migrations

This document defines how the Upload Engine may evolve over time without breaking correctness.

Migrations exist to preserve invariants while allowing the system to grow.
Any change described here must be deliberate, explicit, and reviewable.

Migration Philosophy

The engine prioritizes:

• backward compatibility
• resumability guarantees
• invariant preservation

Breaking uploads in progress is unacceptable.

Current Contracts That Constrain Migrations

Public Surface (from index.ts)

These are the types exposed to consumers. Removing or changing them is a breaking change:

export { UploadEngine } from './UploadEngine';
export type {
  UploadContext, // Upload metadata — industry, category, etc.
  UploadMeta, // Generic intent payload
  StartUploadOptions, // Input to start()
  UploadSessionSnapshot, // Read-only view of upload state
  UploadEvent, // 7-variant event union
  UploadCompletionHandler, // onComplete callback type
  UploadSessionId, // Branded string ID
} from './UploadTypes';

Persistence Format (from UploadTypes.ts:210-244)

Persisted uploads must survive page reload. The current PersistedUploadState shape is:

type PersistedUploadState = {
  key: string; // tenant-scoped: <siteId>:<site>:<timestamp>
  tenant: { site: string; siteId: string };
  createdAt: number;
  uploadId: UploadSessionId;
  fileMeta: { name: string; size: number; type: string };
  context: UploadContext;
  uploadServiceData?: { uploadId; key; bucket; prefixUrl; chunkSize; totalChunks };
  completedParts: CompletedPart[];
  progress: number;
  state: 'paused' | 'uploading' | 'needs-attention';
  chunkConfig?: { chunkSize: number; windowSize: number };
  internalFlags?: Record<string, unknown>;
};

State Machine (from UploadStateMachine.ts)

The 9-state machine and its transitions are a hard contract:

idle → initializing → uploading → completing → completed
                   uploading → paused → resuming → uploading
                   uploading → aborting → aborted
                   uploading → failed
                   completing → completion_failed

Safe Migration Patterns

Adding New API Options

Adding New UploadContext Fields

Event Contract Evolution

Snapshot Shape Changes

Persistence Migrations

Persistence migrations are the most sensitive because they affect uploads that are already in progress across page reloads.

Safe Persistence Changes

Forbidden Persistence Changes

Migration Strategy

State Machine Migrations

Adding New States

Adding New Transitions

Must update:

1. STATE_TRANSITIONS map in UploadStateMachine.ts
2. UploadSession methods that call transition()
3. UploadWorker catch blocks if new error paths
4. Test file UploadStateMachine.test.ts
5. This document's state machine diagram

Adapter Layer Migrations

The persistence.adapter.ts file maps between internal and public types. Changes here must update four adapters simultaneously:

:::warning
Changing one adapter without the others will cause data loss or type errors at runtime.
:::

Migration Testing Requirements

Any migration must include:

If a migration cannot be tested safely, it must not ship.