Obscura Flow Archive Package

This document defines the current Archive Package architecture used by Obscura Flow. An Archive Package is the business object that groups the compressed archive, the integrity manifest, the Ed25519 signature, local status, remote status and validation history.

Goals

The archive system is designed to be:

offline-first: local creation and validation work without the API;
integrity-centric: every new package is independently verifiable from its package folder;
remote-ready: backup uploads the archive, manifest and signature together;
failure-aware: interrupted archive and upload workflows keep actionable status and errors;
compatible: old single-file archives remain visible as legacy records.

Current Package Layout

Each new archive is created in its own folder under workspace.settings.paths.archiveDirectory. The folder name is derived from the project name or settings.archive.namingFormat.

ArchiveDirectory/
└── 2026-05-17_14-30_ProjectName/
    ├── ProjectName.zst
    ├── manifest.json
    └── signature.ed25519

When the naming format produces the archive name directly, the package still keeps the three files together:

ArchiveDirectory/
└── ProjectName/
    ├── ProjectName.zip
    ├── manifest.json
    └── signature.ed25519

archivePath is still persisted on ArchiveHistoryItem for compatibility with older records and existing UI/actions, but package-aware code uses packageDirectory, manifestPath and signaturePath when available.

Manifest

manifest.json is the package authority. It is canonicalized before signing and contains:

archiveId;
projectId;
workspaceId;
projectName;
archiveName;
archivePath;
archiveEngine;
compressionFormat;
createdAt;
createdBy;
sourceProjectPath;
archiveSize;
archiveChecksum;
checksumAlgorithm;
signatureAlgorithm;
publicKeyFingerprint;
fileCount;
totalSourceSize;
includedFiles;
applicationVersion;
manifestVersion.

File entries include the relative path, size, checksum, checksum algorithm and mtime:

{
  "path": "RAW/IMG_001.CR2",
  "size": 58283922,
  "checksum": "9a...",
  "checksumAlgorithm": "sha256",
  "mtime": "2026-05-16T12:00:00.000Z"
}

manifestVersion is the schema evolution point. Current packages use version 1.

Signature

Obscura Flow signs the canonical manifest with Ed25519 and writes the detached signature to signature.ed25519. Manifest signing is preferred because the manifest binds the archive checksum, source file inventory, package identity and application version in one canonical document.

Signature validation can report:

signed;
valid;
missing-manifest;
missing-signature;
hash-mismatch;
invalid-signature;
error;
unsigned.

Local Validation

Local integrity validation starts from the package folder. It verifies:

presence of the compressed archive;
presence of manifest.json;
presence of signature.ed25519;
archive checksum matches the manifest;
archive and manifest refer to the same package identity;
Ed25519 signature is valid;
archive is readable;
optional dry-run extraction when supported.

Validation maps to these local statuses:

valid;
invalid;
missing-files;
signature-invalid;
manifest-mismatch;
archive-corrupted;
unknown.

An archive is never marked valid without a complete package verification.

Transactional Workflow

Archive creation persists step state on the archive history item:

create-archive-folder
generate-archive
generate-manifest
sign-package
validate-local-package
persist-archive-metadata
upload-package
validate-remote-package
update-archive-status

Failed steps keep their error message and retryability flag where possible. Generated files are kept when they can help diagnose or retry the workflow.

Remote Backup

Remote backup uploads the package as three coordinated files, never the compressed archive alone:

archives/<workspaceId>/<projectId>/<archiveId>/archive.ext
archives/<workspaceId>/<projectId>/<archiveId>/manifest.json
archives/<workspaceId>/<projectId>/<archiveId>/signature.ed25519

After upload, Obscura Flow validates the remote package by checking remote presence, remote size, checksum when available and remote manifest correspondence with the local manifest.

Remote statuses include:

backup-pending;
uploading;
uploaded;
remote-integrity-valid;
remote-integrity-failed;
remote-missing-files.

Inventory

The Archive Center shows local and remote archives in one inventory. It exposes project, archive id, package folder, size, created date, upload date, local integrity, remote integrity, provider, target path and actions to refresh, validate, download, restore, delete, open location and view the manifest/signature status.

The Integrity Center surfaces invalid packages, missing files, invalid signatures and remote backups that have not been verified.

Legacy Compatibility

Archives created before Archive Packages may only have a single compressed file and adjacent or missing legacy metadata. During workspace normalization, records without packageDirectory, manifestPath, signaturePath or packageManifest are marked with packageStatus: "legacy" and localIntegrityStatus: "unknown" when no integrity status is present.

Legacy archives remain visible in the Archive Center. Manifest preview is available only when a manifest path exists. Integrity validation keeps fallback support for legacy manifest/signature paths when possible, and the user can regenerate a full Archive Package by archiving the project again from the current workflow.

Future Extensions

The package model intentionally leaves room for a future .ofa portable directory format with extra files such as lineage, restore maps, reports, logs and a standalone validation bundle. Those additions must preserve the current guarantee: archive, manifest and signature stay together and remain verifiable from the package folder.