# 10 — Implementation Roadmap (14 Epics)

Implement sequentially; do not start provider-specific work before core contracts and transfer state are stable.

| Epic | Scope | Deliverables | Depends on |
|---|---|---|---|
| E01 Foundation | Composer, provider, config, CI, conventions | Installable Laravel 13 package | — |
| E02 Contracts & API | DTOs, exceptions, driver contracts, facade | Stable PHP API | E01 |
| E03 Persistence | migrations, models, repositories, state machine | Durable metadata | E01–02 |
| E04 Local Driver | streaming local storage, directories, stat/delete | First usable driver | E02 |
| E05 Basic Upload | upload sessions, validation, finalize | Basic upload flow | E03–04 |
| E06 Chunk Engine | deterministic planner, multipart driver contract, verified chunk records and bounded execution | Chunked transfer | E05 |
| E07 Resume & Idempotency | fingerprints, idempotency, session reconciliation | Resume without duplicate work | E06 |
| E08 Recovery & Retry | error classification, backoff, locks, cleanup | Fault recovery | E06–07 |
| E09 Download Engine | stream, range/chunk retrieval, integrity | Reliable downloads | E04, E03 |
| E10 Progress & Events | metrics, ETA, events, notifications hooks | Transfer observability | E05–09 |
| E11 Performance | benchmarks, tuning, quotas, load tests | Measured throughput | E06–10 |
| E12 Telegram Driver | official/local Bot API adapter after verification | Optional Telegram backend | E02–11 |
| E13 REST Adapter & Security | optional routes, auth, policies, rate limits, sharing | API integration | E03–10 |
| E14 Release & Operations | docs, CI matrix, compatibility, upgrade guide | Release candidate | E01–13 |

## Epic task detail

### E01 Foundation
- Set package metadata and PSR-4 namespace.
- Register service provider and publish config/migrations.
- Add CI for PHP 8.5 and Laravel 13.
- Add package installation smoke test.

### E02 Contracts & API
- Define typed DTOs and enums.
- Define driver capability model.
- Define stable exceptions and error codes.
- Implement facade and service bindings.

### E03 Persistence
- Implement the four core migrations: directories, files, transfers, and chunks.
- Implement UUID-backed Eloquent models and relationships.
- Define repository contracts and Eloquent implementations with SQL-level tenant/owner scoping.
- Implement the transfer state machine and atomic idempotency constraints.
- Test indexes, uniqueness, rollback, and supported database behavior.
- Follow [E03 Persistence specification](16-e03-persistence.md).

### E04 Local Driver
- Implement LocalStorageDriver against the E02 provider-neutral contract.
- Pass reusable StorageDriver contract tests against the local adapter.
- Register the Local driver through the Laravel service provider and configured root path.
- Stream writes in bounded chunks, calculate SHA-256, and finalize through a same-directory temporary file and rename.
- Stream full reads and bounded ranges; implement stat, exists, delete, and stable safe errors.
- Add optional DirectoryDriver operations for create, immediate listing, and safe deletion.
- Reject traversal/absolute keys and refuse to follow symbolic links.
- Test binary payloads, range reads, finalization, directories, symlinks, and error behavior.
- Follow [E04 Local Storage Driver specification](17-e04-local-driver.md).

### E05 Basic Upload
- Add typed UploadRequest/UploadResult and expose UploadManager through the facade.
- Stage readable streams with bounded memory; enforce a configurable 64 MiB initial single-upload limit.
- Validate names, MIME metadata, expected size, directory scope and driver capabilities.
- Create scoped file/transfer records and enforce idempotency replay/conflict semantics.
- Write one object through StorageDriver; independently verify stat, size and SHA-256 by streamed read-back.
- Finalize file availability and transfer completion atomically; compensate with safe deletion on failure.
- Add binary/empty-file, validation, idempotency, integrity and cleanup tests.
- Follow [E05 Basic Upload specification](18-e05-basic-upload.md).

### E06 Chunk Engine
- Add deterministic chunk planning with driver min/max size limits and a 10000-part ceiling.
- Add an optional multipart driver contract with begin, write-part, complete and abort operations.
- Persist chunk offsets, sizes, attempts, checksums, provider references and lifecycle states.
- Stage each part with bounded memory, verify part number/size/SHA-256, and only finalize after all parts pass.
- Compensate failures by aborting the multipart workspace, deleting any possibly published object, and marking unfinished chunks/file/transfer failed.
- Keep the Local adapter sequential with maxConcurrency = 1. Queued parallel workers, resume and retry remain E07–E08 work.

### E07 Resume & Idempotency
- Persist opaque multipart session identifiers and chunk verification timestamps.
- Bind canonical request fingerprints to tenant/owner security scope and all upload attributes.
- Acquire idempotency records atomically; retain the database unique constraint as the concurrency invariant.
- Reconcile verified chunks against deterministic offsets, sizes, staged-byte digests and provider session identity.
- Resume only matching sessions; fail closed on changed payloads, scope, chunk layout or provider references.
- Recompute progress from verified chunks rather than incrementing counters during recovery.
- Test restart, duplicate request, concurrency, changed payload and stale-session scenarios.
- Follow [E07 Resume & Idempotency specification](20-e07-resume-idempotency.md).

### E08 Recovery & Retry
- Classify transient, rate-limited, permanent, and unknown failures without exposing provider details.
- Persist bounded exponential backoff deadlines with jitter and enforce them before an idempotent resume.
- Reuse token-owned transfer leases and periodic heartbeats during recovery.
- Recover a provider-published final object only after independent size and SHA-256 verification.
- Reconcile stale transfers and clean abandoned or terminal multipart workspaces through a bounded, dry-run-capable Artisan command.
- Preserve available file objects when cleaning terminal transfer sessions.
- Follow [E08 Recovery & Retry specification](21-e08-recovery-and-retry.md).

### E09 Download Engine
- Stream content.
- Implement range support where driver advertises it.
- Verify chunks and final checksum.
- Clean temp resources on all exits.

### E10 Progress & Events
- Expose bytes, percent, speed, ETA and chunk counts.
- Add lifecycle events.
- Throttle persistence/broadcast updates.
- Provide notification hooks without requiring a frontend.

### E11 Performance
- Benchmark chunk sizes and concurrency.
- Benchmark local key case/normalization collision checks and directory operations at high directory cardinality.
- Enforce memory and disk budgets.
- Add provider/tenant concurrency controls.
- Document measured results and test environment.

### E12 Telegram Driver
- Re-check official policy and API limits.
- Implement credentials safely.
- Map provider capabilities and errors.
- Run opt-in integration tests.

### E13 REST Adapter & Security
- Add optional versioned routes.
- Add request validation/resources.
- Add policies, tenant scoping and rate limits.
- Add secure share links only if included in release scope.

### E14 Release & Operations
- Complete docs and examples.
- Verify clean installation and upgrade path.
- Run security/performance suite.
- Tag version only after all release gates pass.

## Milestone policy

Verified GitHub state on 2026-11-01:

| Epic | Repository state | PR | Completion interpretation |
|---|---|---|---|
| E01–E04 | Merged into `main` | #1–#4 closed/merged | Complete |
| E05 Basic Upload | Merged into `main` | #5 closed/merged | Complete |
| E06 Chunk Engine | Merged into `main` | #6 merged | Complete |
| E07 Resume & Idempotency | Merged into `main` | #7 integrated through #15 | Complete |
| E08 Recovery & Retry | `integration/e08-on-main` | New integration PR pending | Implementation transplanted onto current `main`; final CI and review pending |

E06 and E07 are already integrated into `main`. E08 is being validated from a clean branch based on the E07 merge commit. Keep each PR's implementation evidence distinct; a green run on an earlier head does not verify later commits.

E08 includes failure classification, persisted backoff deadlines, retry-deadline enforcement, token-owned recovery leases and heartbeats, provider-published object recovery after independent size/SHA-256 verification, stale-session expiry, and terminal multipart cleanup. The Artisan command supports bounded candidate counts and aggregate-only dry-run. A recovery pass cannot recreate missing source bytes; callers must resubmit the original source stream after the persisted retry deadline. E08 is not complete until the final PR head passes the full database CI matrix, code review, security review, and migration rollback/reapply checks.

The E07 CI run recorded 102 tests / 424 assertions on SQLite, MySQL 8.4, and PostgreSQL 17. The original stacked E08 branch passed its then-current SQLite, MySQL 8.4 and PostgreSQL 17 matrix, but that evidence does not certify the clean integration branch. The integration PR must pass its own current-head CI matrix and review gates. Driver-call heartbeat during a single blocking provider operation, queue-based source re-submission, and remote-provider recovery semantics remain follow-up work.


Do not call E01/E02 a production engine. A first usable local-storage release requires at least E01–E05. A resumable/recoverable release requires E01–E10. Production readiness requires all applicable release gates and real deployment validation. E04 is complete only after the current CI workflow passes, all required code and security review findings are addressed, all review threads are resolved, and the work is merged into `main`.


---
