APEX Download Manager (ADM)

Status: Partial

ADM is a local-first download manager workspace. The current codebase is primarily Rust, with a React/TypeScript desktop frontend running inside a Tauri 2 shell.

The repository is already organized around the target bounded contexts:

core/
adapters/
plugins/
apps/
shared/
docs/

This is not yet a fully verified stable release. Build, lint, test, and packaging status must be taken from GitHub Actions after the release workflow runs.

Current stack

Area	Location
Download engine	core/engine/download-engine
Domain layer	core/domain
Application/use-case boundary	core/application
Ports/contracts	core/ports
SQLite storage adapter	adapters/storage/sqlite
Network adapters and protocol drivers	adapters/network
Disk/filesystem adapter	adapters/filesystem/disk
Desktop UI	apps/desktop-ui
Tauri desktop shell	apps/desktop-ui/src-tauri
CLI	apps/cli
Daemon	apps/daemon
Local API	apps/local-api
Test server	apps/test-server
Browser companion integration	plugins/browser-extension/native-host, shared/contracts/extension; companion package lives in a separate repository
Shared protocol/types/diagnostics	shared

Implementation boundary

• Rust owns the core engine, application layer, ports, adapters, plugins, daemon, CLI, Local API, and shared contracts.
• TypeScript is limited to the desktop UI under apps/desktop-ui; the browser companion TypeScript package is maintained in a separate repository.
• UI, CLI, Local API handlers, and integrations must not contain download business logic.
• External I/O must go through ports/adapters or plugin-specific protocol drivers.
• Secrets must go through the Secret Vault boundary and must not appear in logs, diagnostics, URLs, or exports.

Current feature status

Capability	Status
Rust workspace architecture	Partial
Desktop shell	Partial
Download engine crate	Partial
Typed error taxonomy	Partial — core/domain contract added; runtime migration incomplete
Server capability probe	Partial — application use case plus HTTP adapter wiring for daemon task admission
Diagnostics redaction	Partial — shared policy and redacted export use case added; producer migration incomplete
SQLite persistence surface	Partial
Local API crate	Partial
CLI crate	Partial
Browser native host/extractor	Partial
Browser companion handoff outbox	Partial — /v1/add persists before engine intake; /captures, /v1/extract-page, /v1/site/mirror, and refresh-address operations persist to outbox; bounded authenticated add replay and safe summary exist; continuous worker not complete. Companion package source is external.
Rule/Profile persistence	Partial — core ports, SQLite adapters, application use cases, Local API CRUD, profile resolution, and rule dry-run conflict reports exist; runtime policy execution is not complete
HLS/DASH/Torrent/Metalink drivers	Partial/experimental
Telegram/webhooks	Planned/partial surfaces only
Full release packaging	Planned through CI; not locally verified in this pass
Signing/notarization	Not implemented yet

Do not state that a capability is implemented unless the code and tests prove it.

Requirements

For local development, install the project toolchains before running build or tests:

• Rust toolchain compatible with rust-toolchain.toml.
• Node.js compatible with the release workflow, currently Node 24 in CI.
• pnpm matching the root packageManager field.
• Platform-specific Tauri desktop dependencies.

This pass did not run package installation, build, lint, or tests.

Useful local commands

Run only when toolchains are installed and execution is allowed:

scripts/verify-architecture-layout.sh
cargo fmt --all -- --check
cargo check --locked --workspace --all-targets
cargo test --locked --workspace
cargo clippy --locked --workspace --all-targets -- -D warnings
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm desktop:build

Release process

There is exactly one build/release workflow:

.github/workflows/release.yml

Create a release with:

git tag vX.Y.Z
git push origin vX.Y.Z

or run workflow_dispatch from GitHub Actions and provide a version such as v1.4.0.

The workflow is designed to create real artifacts only. It fails if expected binaries or Tauri bundles are missing.

Expected release artifacts

Examples:

adm-vX.Y.Z-linux-x64.tar.gz
adm-vX.Y.Z-linux-arm64.tar.gz
adm-vX.Y.Z-windows-x64.zip
adm-vX.Y.Z-windows-arm64.zip   # experimental until validated in CI
adm-vX.Y.Z-macos-x64.zip
adm-vX.Y.Z-macos-arm64.zip
adm-vX.Y.Z-checksums.txt
adm-vX.Y.Z-release-manifest.json

Installer bundles are target-qualified when produced by Tauri, for example .deb, .rpm, .AppImage, .dmg, .msi, or .exe. The release manifest records os, arch, format, tier, and experimental for each real artifact; legacy 32-bit targets are listed as planned only until CI proves real support.

Documentation

Start here:

• docs/AUDIT.md
• docs/ARCHITECTURE.md
• docs/DOWNLOAD_ENGINE.md
• docs/LOCAL_API.md
• docs/CLI.md
• docs/SECURITY.md
• docs/DIAGNOSTICS.md
• docs/EXTENSION_INTEGRATION.md
• docs/TESTING.md
• docs/RELEASE.md
• docs/COMPATIBILITY.md
• docs/TROUBLESHOOTING.md

Known constraints

• Build/lint/tests were not run in this execution pass.
• Cargo.lock and pnpm-lock.yaml must stay synchronized with the desktop-only workspace.
• Linux arm64 and Windows arm64 release packaging are still marked experimental until CI validates them.
• Linux x86 and Windows x86 are not uploaded because current support is not proven; they remain planned legacy targets only.
• Protocol plugins and integrations are not all production-ready.
• Signing, notarization, encrypted backup/restore with secrets, and full update-channel hardening are not implemented yet.

Continuation pass 2

The current archive adds a real application-layer server probe contract and implementation while preserving the no-build/no-test/no-install constraint. The probe depends on NetworkClientPort, performs HEAD/GET metadata probing, verifies byte-range support, detects temporary URL markers, and returns typed non-fatal capability errors for degraded mode.

The domain error taxonomy now includes retry policy hints, suggested actions, HTTP status mapping, and structured diagnostics fields. Shared redaction now includes diagnostic key/value entry masking and expanded signed URL coverage. These changes are partial until CI compiles and runs the workspace tests.

Continuation pass 3

The current archive adds production-facing wiring instead of another planning-only layer:

• adapters/network/src/http/probe-network-client.adapter.rs implements NetworkClientPort with a bounded-body reqwest HTTP probe adapter.
• apps/daemon/src/kernel_runtime.rs now applies the server capability probe during HTTP/HTTPS task admission when ADM_DOWNLOAD_ENGINE_RUNTIME is active. The probe is enabled by default and can be disabled with ADM_SERVER_PROBE=0, false, no, off, or disabled.
• Probe output is stored as safe task metadata such as content length, content type, resume/range support, temporary-URL signal, and recommended strategy. Redirect chains and raw URLs are intentionally not copied into task metadata.
• adapters/filesystem/disk/src/core-ports.adapter.rs implements FileSystemPort and DiskSpacePort using the existing disk adapter, atomic rename, and disk-space guard.
• core/application/export-diagnostics/export-diagnostics.use-case.rs now contains a redacted diagnostics export use case that consumes DiagnosticsProviderPort sections and applies the shared redaction policy before JSON serialization.

Build, lint, and tests are still not claimed as passed because they were not run in this execution pass.

Continuation pass 4

This archive adds three incremental runtime-hardening changes:

• chunk planning now consumes safe pre-admission probe metadata and falls back to a single stream when the server probe recommends it.
• daemon persistence snapshots now have a diagnostic health report for obvious crash-recovery invariants, without mutating storage.
• Local API and CLI diagnostics now redact environment/path-style diagnostics through shared helpers before export.

These changes remain partial until GitHub Actions compiles and tests the workspace. Build, lint, and tests were not run locally in this execution pass.

Continuation phase 5 status

Phase 5 added partial but concrete crash-safe persistence seams:

• typed domain event serialization.
• SQLite-backed EventStorePort adapter.
• port-backed create-task use case that emits TaskCreated.
• SQLite outbox repository with idempotent enqueue and dead-letter promotion.
• Local API diagnostics for persisted runtime snapshot health.
• confirmed repair flow for stale outbox sending reset and exhausted failed-job dead-letter promotion.

These changes were not locally built or tested in this environment. CI remains the verification path.

Continuation phase 6 status

Phase 6 connects more of the target architecture to real storage code:

• SqliteTaskRepositoryAdapter implements TaskRepositoryPort over the existing downloads table.
• SqliteSegmentRepositoryAdapter implements SegmentRepositoryPort over the existing chunks table.
• TaskCreationStorePort adds an atomic task + first-event persistence boundary.
• SqliteTaskCreationStoreAdapter stores a task and its TaskCreated event in one SQLite transaction.
• TransactionalCreateTaskUseCase is now available for create-task flows that require a single storage boundary.

The daemon and Local API have not yet been fully migrated to the transactional use case. Build, lint, and tests were not run locally in this execution pass.

Continuation phase 7 notes

This phase added a real persist-before-send boundary for browser extension add requests. The Local API now writes a versioned outbox payload before handing the request to the engine, marks accepted handoffs as sent, marks rejected handoffs as failed with redacted details, and avoids duplicate task creation when the same idempotency key has already been accepted. Build, lint, and tests were not run locally.

Continuation pass 8

This archive adds a bounded authenticated outbox replay path for browser-extension add handoff jobs through POST /api/v1/outbox/process. The endpoint defaults to dry-run, claims a limited number of due jobs only when explicitly requested, replays only versioned browser-extension.add payloads, stores redacted failure details, schedules bounded retry backoff, and promotes exhausted jobs to dead-letter without deleting source payloads. Build, lint, and tests were not run locally.

Continuation phase 9 status

Phase 9 extends durable extension intake to deferred operations and adds a safe outbox summary endpoint. The new endpoint reports aggregate counts only; it does not expose raw payloads. Replay remains limited to browser-extension.add; capture, extract-page, site-mirror, and refresh-address jobs are persisted for later worker/use-case implementation.

Continuation phase 10 status

Phase 10 adds a safe outbox review endpoint and strengthens Local API token handling without changing lockfiles or running build/test/install:

• GET /api/v1/outbox/review returns bounded outbox job metadata, status, attempts, kind, timestamps, redacted last error, and a payload_sha256 fingerprint.
• The review endpoint does not expose raw payloads, URLs, headers, cookies, bearer tokens, signed query values, or browser-extension request bodies.
• Local API configured-token comparison now uses a constant-time helper instead of direct string equality.
• Query-string token rejection now covers api_key, apikey, bearer, and auth in addition to the earlier token names.

Replay remains intentionally limited to browser-extension.add; non-add payload execution still requires dedicated use cases.

Phase 11 update: rule/profile persistence seams

Status: Partial. The current package now includes concrete target-layout repository ports for profiles and rules, SQLite adapters over the existing profiles and automation_rules tables, and application-layer use cases for profile resolution and rule dry-run matching. These additions are storage/application seams only; runtime rule execution, UI management, import/export, and conflict reporting are not complete.

Continuation pass 12

This pass links the target-layout profile and rule repositories to Local API endpoints without replacing the existing /api/v1/automation/rules compatibility surface. Added endpoints include /api/v1/profiles, /api/v1/profiles/resolve, /api/v1/rules, and /api/v1/rules/dry-run. Rule dry-run now reports action-key conflicts for matched rules but still does not execute actions.

Current continuation status: plugin guard and local fixtures

Recent continuation work added a partial plugin runtime guard and a deterministic local HTTP fixture route surface. These are architectural foundations, not completed user-facing features.

• Plugin runtime guard: partial. It tracks healthy/degraded/disabled/failed states and is integrated into the runtime plugin registry. Real plugin hook call sites still need timeout wrapping.
• Local fixture server: partial. The fixture router exists for tests and CI but is not yet exposed as a dedicated CLI mode.
• Diagnostics redaction check: partial. A structural CI script now verifies that required redaction markers and probe redaction hooks remain present.

Rust build and tests must be verified through GitHub Actions in this environment.

Additional safety documentation: File Safety. Status: Partial.

Continuation phase 30-31

This archive adds read-only file safety surfaces and storage overwrite policy hardening:

• Local API: POST /api/v1/file-safety/evaluate.
• CLI: adm-cli file-safety ....
• Desktop UI: optional fileSafety warnings in task details when available.
• Local API task responses can include file_safety for filename-only warnings.
• Local API: GET /api/v1/feature-flags exposes the disabled-by-default high-risk feature catalog.
• Storage Guard: duplicate-safe rename planning and explicit overwrite reporting.

No quarantine mover, external scanner adapter, or runtime feature enablement is added by this pass.

Phase 34-37 update

Status: Partial. This continuation wires StorageGuard into DiskWriter::prepare(...), adds explicit overwrite/rename handling at the writer boundary, adds bounded magic-byte detection in the disk filesystem adapter, and extends Local API/CLI file-safety evaluation with optional path evidence. Build/test verification remains pending in GitHub Actions because the local environment lacks Rust and Node package-manager toolchains.

Continuation phase 38-39 status

Implemented in this package:

• Path-safety planning for final download targets.
• Storage target preview endpoint: POST /api/v1/storage/target-plan.
• CLI storage target preview: adm-cli storage-target-plan.
• Non-mutating quarantine planning endpoint: POST /api/v1/file-safety/quarantine-plan.
• CLI quarantine planning: adm-cli file-safety-quarantine-plan.

These are planning/safety surfaces. They do not move, delete, scan, or mutate files.

• docs/FILENAME_TEMPLATES.md — safe nested target template planning and preview.

• Experimental gated quarantine move: POST /api/v1/file-safety/quarantine-move and adm-cli file-safety-quarantine-move, disabled unless ADM_ENABLE_QUARANTINE_MOVE=1 and confirm=true.

Continuation phase 47-50 status

Implemented in this package:

• Quarantine move now rejects symbolic-link sources.
• Quarantine move supports cross-device fallback through copy, fsync, atomic rename, byte-count validation, and source removal.
• Quarantine move reports AtomicRename or CopyThenRemoveSource.
• enable_quarantine_move is now part of the disabled-by-default kill-switch catalog.
• Kernel task intake can apply target templates from metadata keys: adm.storage.target_template, adm.storage.template_value.*, and adm.storage.overwrite_policy.

Build, lint, and tests were not run locally; GitHub Actions remains the verification path.

Implementation status discipline

ADM documentation uses four statuses only: Implemented, Partial, Experimental, Planned. Release, CI, packaging, Rust compile, and pnpm typecheck are not claimed complete until the official release workflow proves them. See docs/DOCUMENTATION_STATUS.md.