# Spec 006: coexistence and cutover

Status: draft revision 1 for review
Date: 2026-08-08
Depends on: all earlier specs

## Outcome

Godloop v2 can be built, tested, imported, and cut over without deleting v1
code, sharing mutable state, or losing user data. Every irreversible step has a
verified backup and rollback path.

This spec owns preservation, migration, deployment separation, cutover, and
recovery. It does not authorize a migration or production switch by itself.

## Preserve the source

The existing repository root remains the v1 reference. New application source
stays under `v2/` until an explicit repository split is useful.

During the rewrite:

- do not delete, rename, or mass-format v1 paths;
- preserve unrelated dirty work and never use broad stash, reset, or rebase;
- keep v2 commits narrow enough to review or cherry-pick;
- record the exact v1 commit and deployed asset hashes at every rehearsal;
- archive retired code only after v2 production acceptance and an explicit
  decision; archive is not deletion.

A clean release tag or preservation branch may be created only from a reviewed
commit. Current uncommitted work is never hidden merely to manufacture one.

## Separate environments

```text
v1: godloop.ai      :4200  /opt/godloop     existing database and service
v2: dev.godloop.ai  :4201  /opt/godloop-v2  independent database and service
```

They do not share a writable database, static root, process, port, service unit,
or deployment directory. V2 failures never restart v1. V1 remains the rollback
application until the retention gate expires.

External side effects are disabled in rehearsals unless a test connection is
explicitly selected. Production Telegram, webhooks, schedules, and agents must
not run from both versions.

## Inventory before mapping

Before writing import code, create a read-only inventory of v1:

- schema and migration level;
- users and authentication identities;
- projects and memberships;
- Spaces/runners and public connection metadata;
- conversations and messages;
- Masterplan nodes and revisions;
- Loop/Godloop definitions and runs;
- integrations, outbox state, approvals, and artifacts;
- secrets that must be reconnected rather than exported.

For each category, decide `import`, `archive and link`, `reconnect`, or `do not
migrate`. Unknown rows block cutover; they are not silently dropped.

## Export and import contract

V1 receives a bounded read-only exporter. It writes a versioned manifest,
record counts, stable source IDs, checksums, and typed data without plaintext
secrets.

V2 imports into a fresh database copy. Import is idempotent by source identity,
records every mapping, and produces a reconciliation report. It never imports
directly into the only v2 database.

Before each rehearsal:

1. copy the v1 database using its safe backup procedure;
2. run SQLite integrity checks;
3. prove the backup restores into an isolated path;
4. export from that copy;
5. import into a disposable v2 database;
6. compare counts, relationships, sample records, and authorization behavior;
7. retain the report and both checksums.

## Compatibility period

V1 and v2 may run side by side, but there is one writer for each account at a
time. There is no bidirectional sync and no dual-write code.

During dogfood, selected test accounts use v2 while v1 remains authoritative for
everyone else. Feedback fixes v2 or the importer; it does not introduce a
permanent compatibility layer.

Deep links that cannot exist in v2 yet return a clear compatibility link to v1.
They do not pretend the resource migrated.

## Cutover gate

Production switch requires all of the following:

- Specs 001-005 acceptance passes on production-like data;
- at least two successful import rehearsals from different recent backups;
- restore and rollback drills with measured time;
- verified user/project authorization and no cross-project data exposure;
- exact handling for every inventoried data category;
- side-effect ownership for agents, schedules, Telegram, and webhooks;
- health, logs, disk, certificates, backup retention, and operator runbook;
- explicit user approval for the cutover window.

The final window pauses v1 writes, takes and verifies a final backup/export,
imports once, runs reconciliation, switches routing, and keeps v1 stopped but
recoverable. The old database and static assets remain immutable.

## Rollback

Rollback stops v2 side effects, preserves its database for diagnosis, restores
v1 routing and side-effect ownership, and reopens v1 writes only after health and
integrity checks.

Data created only in v2 during the cutover window is exported and retained. It
is never silently discarded or back-written into v1 without a separate import
design and approval.

Rollback criteria and maximum decision time are written before cutover, not
invented during an incident.

## Acceptance

1. Build and deploy v2 without changing v1 hashes, service, database, or health.
2. Inventory a realistic v1 copy and classify every data category.
3. Restore the backup, export, import twice, and get identical mappings and
   counts without duplicates.
4. Verify Masterplan hierarchy, blank dates, conversations, Loop versions,
   membership, and redacted/reconnected integrations.
5. Run both versions with test accounts while proving only one owns each side
   effect.
6. Rehearse cutover, then rollback within the documented bound without losing
   either database.
7. Complete the final approved cutover and retain v1 for the agreed recovery
   period before any archival decision.

## Not in this spec

- automatic destructive migration, shared-database compatibility, dual writes,
  or indefinite bidirectional sync;
- deleting v1 code or data as part of the first v2 release;
- migrating secrets that should be reconnected by their owner.