ADR 012 Portable Project Archive V1 - joeroberts/release-radar GitHub Wiki

  • ID: ADR-012
  • Status: Accepted
  • Date: 2026-08-25
  • Date meaning: Original dated decision/source section; extraction recorded 2026-10-02.
  • Implementation: No implementation information was recorded in the source status; tickets own progress.
  • Approval qualification: Recorded accepted decision; dated delivery conditions are historical, not new execution authorization.

Context

The original portable archive v1 defines compatibility and isolated import, not the later complete-package outcome.

Compatibility and import contract

The v1 format below retains its defined compatibility behavior. It is not the target for future complete-project export: the owner-approved complete-project package direction of 2026-09-06 supersedes its contents as the RM5/RM6 product requirement. No new format version or implementation is established by this decision.

Existing-project onboarding has two non-overlapping owner workflows:

  1. Attach Folder to Existing Project authorizes a canonical folder for an already-persisted project that has no root or bookmark. It reuses the app-owned first-root association transaction, preserves every delivery and history record, and adds only one root, one fresh local bookmark, and one project-scoped owner audit.
  2. Import Existing Project creates a new project from an authoritative portable Release Radar archive. It never attaches to, merges with, replaces, or updates an existing project.

Portable project archive version 1 is one bounded JSON file using the extension .release-radar-project.json, format value com.rekonlabs.release-radar.project-archive, and schemaVersion value 1. It contains exporter timestamp and producer bundle/app/store-schema metadata, plus exactly one project. Stable IDs are preserved without remapping for the project, phases and active phase, phase dependencies, tickets and lanes and outcomes, ticket dependencies, blockers, root-relative evidence, thread exclusions, observed threads and goals, thread links, ticket-goal links, review items and statuses, and completion records. Imported observations are labelled historical last-known context and never presented as live.

Version 1 represents exactly one source project root and requires one newly selected destination root. Multiple-root projects or evidence outside that one root are not representable and export must fail instead of omitting records. Absolute roots, root IDs, security-scoped bookmark bytes and stale flags, first_dashboard_opened, audits, notification events and delivery attempts, alert rules, agent-command replay records, credentials, Keychain data, live freshness, evidence availability, and onboarding markers are not portable. The destination receives a newly validated local bookmark, first_dashboard_opened resets to false, and evidence availability is recomputed under the destination root.

Preview strictly rejects unsupported versions, unknown or duplicate JSON fields, duplicate IDs or logical edges, any existing project or same-table ID collision, dangling or cross-project references, invalid states, dependency cycles, absolute or traversing evidence paths, symlinks, non-regular or oversized input, and source changes between preview and apply. Invalid archives do not degrade into partial records or generated Needs Review items. Import revalidates the exact source bytes and all database/root collisions, then creates the project, complete portable graph, destination root, fresh bookmark, and one release-radar-owner / Import portable Release Radar project archive audit in one store-owned transaction. Any failure rolls back the complete operation. Historical audits are never restored or fabricated, source bytes remain unchanged, and no notification, bridge request, onboarding marker, network request, or content execution is produced.

The existing Rekon docs/delivery/dashboard-status.json importer remains a partial one-time seed importer. Rekon JSON, arbitrary Markdown, repository state, and copied SQLite databases are not portable complete-project archives. Portable importer implementation remains blocked until an authoritative exporter produces the acceptance fixture.