nucleic/nucleic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
694108571a3dbdab402790da5c0744f8142089a9
nucleic/docs/BRANDING_LAYERS_PLAN.md
T

10 KiB
Raw Blame History

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).
Reference in New Issue View Git Blame Copy Permalink