176 lines
10 KiB
Markdown
176 lines
10 KiB
Markdown
# 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).
|