# Nucleic — Three-Layer Branding Rename Plan

> **Status: COMPLETE — all phases landed and verified (see §9). Website is out of scope
> (handled by a separate agent).**
> Goal: adopt the new three-layer conceptualization across code, wire/DB formats, UI,
> and docs.

## 9. Outcome (verification)

- **Covalence swap:** every network "Carbon" identifier/file/string renamed to Covalence
  (Swift, iOS, tests, cloud TS, docs, Makefile/Package.swift, CI workflows). Files renamed:
  `CarbonMeshViewerWindow.swift`→`CovalenceMeshViewerWindow.swift`, `docs/CARBON_RUNNER.md`
  →`COVALENCE_RUNNER.md`, `docs/CARBON_QUEUE.md`→`COVALENCE_QUEUE.md`.
- **Serialized migration:** GRDB **v30** renames `carbon_origin_device_id`→
  `covalence_origin_device_id` (v29 frozen as history); wire key renamed with legacy
  `carbonOriginDeviceID` dual-emit + fallback decode (`Dashboard.swift`,
  `TransferMessages.swift`), covered by new tests.
- **Carbon (data) brand:** `SessionTransferPackage`→`SessionCarbonCopy` (file renamed);
  `SessionMetadataStore` doc-branded as the Carbon data layer; three-layer section added to
  `NUCLEIC_CONCEPT.md`.
- **Control:** name kept; re-scoped as the system-control "brain" layer in the concept doc.
- **Infra IDs:** kept `nucleic-runner` (product-branded, not brand-stale; parallels
  `nucleic-edge`) — only human-facing prose became "Covalence Cloud Runner".
- **Excluded (correctly untouched):** Apple Carbon-framework key codes (`KeyMap.swift`,
  `MacVMSurface.swift`), all `third_party/`, `website/`.
- **Verified:** full Swift package compiles; NucleicProtocolTests (203) + affected
  Core suites (session transfer, GRDB v30, mesh dispatch, credential mesh, diagnostics)
  all green; both cloud workers `tsc --noEmit` clean.
- **User follow-up (operational, outside repo):** none required for infra (IDs kept).

## 1. The new conceptual model

| Layer | Brand | Tagline | What it covers |
| --- | --- | --- | --- |
| **Data** | **Carbon** | *Carbon Copy* | Persistence + replication of session/project data: metadata store (GRDB/SQLite), JSONL transcripts, session-transfer **payloads**, credential vault data. "Carbon Copy" = the data that gets copied/replicated. |
| **Network** | **Covalence** | sync · mesh | The mesh/sync fabric: sync protocol, relay, LAN/Tailnet transport, pairing, mesh dispatch + work queue, session *transfer transport*, the Cloud Runner. |
| **System control** | **Control** *(unchanged name)* | the "brain" | Virtualization & system control: MacVM/LinuxVM engines, containers, MDM, autoship/merge-queue, the control plane. Already "Nucleic Control" — **name kept, branding re-scoped** to explicitly own VMs/containers/autoship. |

**The core move is a SWAP:** today "Carbon" *is* the network layer. Every existing
"Carbon" reference is really a Covalence (network) reference and gets renamed to
**Covalence**. The name "Carbon" is then freed and re-applied to the (currently
unbranded) **data** layer.

---

## 2. Scope (per approved decisions)

- **Depth:** everything — user-facing UI/docs/website, code symbols/types/files, AND
  serialized wire fields + GRDB columns + Codable keys (with migrations + back-compat).
- **Swap:** full swap of existing network "Carbon" → "Covalence".
- **Control:** keep the name; re-scope branding in docs/UI only (no code rename).
- **Approach:** this plan first, then execute in verified phases.

---

## 3. EXCLUDE — false positives (do NOT touch)

- `guest/NucleicVMAgent/Sources/VMAgentCore/KeyMap.swift` — "Carbon" here = Apple's
  **Carbon framework** virtual key codes (HIToolbox), unrelated to branding.
- All of `third_party/` (containerization kernel configs, `archive.h`,
  `Capabilities.swift`) — vendored code, "carbon" is incidental.
- Generic MVC "Controller" types are **not** the Control brand and stay as-is:
  `SessionController`, `SidebarColumnController`, `MDMServerController`,
  `VMMonitorPiPController`, `MacVMOperatorAssistController`, etc.

---

## 4. Covalence rename (the bulk of the work)

### 4a. Code identifiers (`carbon* → covalence*`, `Carbon* → Covalence*`)

| Old | New | Notes |
| --- | --- | --- |
| `carbonOriginDeviceID` (51×) | `covalenceOriginDeviceID` | property; see wire/DB migration §4d |
| `carbon_origin_device_id` (GRDB col) | `covalence_origin_device_id` | migration §4d |
| `carbonEnabled` (7×) | *(removed — see note)* | **Superseded 2026-07-21:** Covalence is mandatory (COVALENCE_QUEUE §1, CARBON_SHARDING D17), so the gate is deleted rather than renamed; §4d item 3's key migration is moot |
| `CarbonSessionDiagnostic` (6×) | `CovalenceSessionDiagnostic` | type |
| `carbonSessions` / `carbonSessionCount` / `carbonSessionDiagnostics()` | `covalence…` | |
| `carbonRebalancingSessions`, `carbonRebalanceLastAttempt`, `carbonRebalanceCooldown`, `carbonRebalanceSweepTask`, `scheduleCarbonRebalanceSweep`, `rebalanceCarbonSession`, `sweepCarbonRebalance` | `covalence…` / `…CovalenceSession` | mesh rebalance machinery |
| `CarbonMeshViewerWindowController`, `CarbonMeshViewerView`, `CarbonSessionsSection`, `CarbonMesh`, `resetCarbonMeshConfig` | `Covalence…` | |
| test names `…CarbonOrigin…`, `carbonManagementRidesTheTransfer` | `…CovalenceOrigin…` | |

### 4b. Files to rename

| Old path | New path |
| --- | --- |
| `Sources/NucleicApp/Panels/CarbonMeshViewerWindow.swift` | `CovalenceMeshViewerWindow.swift` |
| `docs/CARBON_RUNNER.md` | `docs/COVALENCE_RUNNER.md` |
| `docs/CARBON_QUEUE.md` | `docs/COVALENCE_QUEUE.md` |
| `website/features/carbon.html` | see §6 (repurpose vs. new) |

### 4c. User-facing strings / assets

- Settings tab `case carbon = 10` label `"Carbon"` → `"Covalence"` (enum case
  `covalence`; the raw value `= 10` **stays** to preserve tab ordering/persistence).
  Icon `circle.dotted.and.circle` kept unless you want a new one.
- All "Carbon mesh", "Carbon Cloud Runner", "Carbon job/queue/run target",
  composer "Carbon" run-target label → "Covalence".
- Cloud runner: `cloud/nucleic-runner/*`, `containers/nucleic-runner/*`,
  `containers/nucleic-sandbox/Dockerfile` doc/comment strings.
  **DECISION: rename infra IDs too** — image name `nucleic-runner`, registry path pins,
  and CI workflow names get the Covalence brand. NOTE: this requires operational follow-up
  outside the repo (re-publish images, update `registry.cloudflare.com/<ACCT>/…` pins and
  deploy secrets). Those external steps are the user's to run; the repo will reference the
  new names.
- iOS app: `ios/NucleicRemote/**` (RemoteStore, Composer, MeshInfoView, SettingsView,
  ProjectsView, HostConnection).

### 4d. Serialized formats — migration & back-compat (approved: yes)

1. **GRDB column** `carbon_origin_device_id` → `covalence_origin_device_id`:
   add migration **v30** using `ALTER TABLE session RENAME COLUMN` (SQLite supports it);
   existing rows preserved. Update `GRDBMetadataStore` read/write mapping.
2. **Wire Codable key** `carbonOriginDeviceID` in `Dashboard.swift`
   (`StartChatRequest`) and `TransferMessages.swift` (`SessionTransferRecord`):
   rename property + `CodingKeys` to `covalenceOriginDeviceID`, but **decode-fallback**
   from the legacy key so a mixed-version mesh (older Mac/phone/runner) still interops.
   `SyncProtocol.version` stays 1 (field-additive/tolerant, matching how it was added).
3. **`@AppStorage` key** behind `carbonEnabled` (`AppStore.remoteEnabledDefaultsKey`):
   ~~**DECISION: migrate the key too.** Rename the stored key to the Covalence-branded
   string and add a **one-time defaults migration** that copies the old key's value (if
   present) to the new key on first launch, then clears the old key.~~
   **Superseded 2026-07-21:** Covalence is mandatory (COVALENCE_QUEUE §1, CARBON_SHARDING
   D17) — delete the gate, its stored key, and the gated code paths instead of migrating.

---

## 5. Carbon (data layer) — NEW brand application

The data layer is currently **unbranded**. **DECISION: apply Carbon/Carbon Copy to code
symbols too (option B)** in addition to docs + UI copy.

Code homes for Carbon (data): `Sources/NucleicCore/Persistence/` (GRDBMetadataStore,
SessionMetadataStore), transcripts (JSONL) I/O, and the *payload* half of
`Sources/NucleicCore/Transfer/` (e.g. `SessionTransferPackage`). Guard the seam: the
transfer **transport/dispatch** stays Covalence; only the **data payload / persisted
copy** carries Carbon. This is applied conservatively to avoid re-labeling network code —
symbols get a `Carbon`/`CarbonCopy` name only where they clearly denote persisted/
replicated data, with doc comments naming the layer.

---

## 6. Docs  (website is OUT OF SCOPE — handled by a separate agent; do NOT touch `website/`)

- `NUCLEIC_CONCEPT.md` — add a short "Three layers: Carbon / Covalence / Control"
  section so the source-of-truth brief carries the model.
- Rename + update `docs/CARBON_RUNNER.md` → `COVALENCE_RUNNER.md`,
  `docs/CARBON_QUEUE.md` → `COVALENCE_QUEUE.md`; sweep mentions in
  `docs/MESH_TRANSFER.md`, `SYNC_PROTOCOL.md`, `CLOUD_*`, `AGENT_RESUSCITATION.md`,
  `RUNTIME_ARCHITECTURE.md`.

---

## 7. Execution phases (each phase built + tested before the next)

1. **Covalence code rename** (symbols + files, excluding serialized keys) → build macOS +
   iOS + Linux `nucleicd`, run test suites.
2. **Serialized migration** (GRDB v30 + wire key + decode-fallback) → run
   `WireMessageTests`, `SessionTransferTests`, GRDB metadata tests.
3. **UI/settings strings + assets** (Covalence tab, composer, panels) → build.
4. **Carbon (data) branding** at the chosen depth (§5).
5. **Control re-scope** copy (docs/UI framing only).
6. **Website + docs sweep** (§6).
7. Full green build (macOS app, `nucleicd` both arches, iOS xcodebuild) + test suites.

---

## 8. Resolved decisions

- **Q1 — Carbon (data) depth:** ✅ B — also code symbols (conservative seam, §5).
- **Q2 — website:** ✅ OUT OF SCOPE — a separate agent updates `website/`; do not touch it.
- **Q3 — `carbonEnabled` stored key:** ✅ migrate the key with a one-time defaults
  migration (§4d.3).
- **Q4 — Cloud runner infra IDs:** ✅ rename them too; external re-publish/secret updates
  are the user's operational follow-up (§4c).
