Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0010: External Ownership Boundaries

Status: accepted

Context

Dubnium is evolving into a machine orchestration and runtime policy layer for a hybrid workstation and AI-node environment.

The repository already integrates an external dotfiles source for Home Manager and user-scoped configuration. At the same time, the local k3s integration in Dubnium remains intentionally thin and partially placeholder while broader cluster automation work evolves separately.

Without an explicit ownership boundary, there is a risk that:

  • machine policy drifts into user-home concerns
  • cluster bootstrap logic becomes duplicated across repositories
  • recovery boundaries become unclear
  • operational responsibilities overlap
  • host rebuilds become fragile or non-reproducible

Decision

Dubnium adopts a layered ownership model.

Dubnium

Dubnium is the authoritative repository for:

  • machine identity
  • NixOS host composition
  • runtime mode control
  • systemd orchestration
  • hardware policy
  • GPU placement policy
  • runtime reconciliation
  • machine-scoped secrets and service contracts

Dubnium orchestrates external systems but should avoid duplicating their source of truth.

Dotfiles

ryjen/dotfiles is the authoritative repository for:

  • Home Manager configuration
  • user shell configuration
  • editor configuration
  • CLI tooling
  • user-scoped agent tooling
  • workstation UX preferences
  • user-scoped secrets materialization

Dubnium may consume dotfiles directly through flake inputs and local checkout paths.

Laboratory

hackelia-micrantha/laboratory is the intended authoritative repository for:

  • local cluster bootstrap
  • k3s deployment orchestration
  • Flux bootstrap and reconciliation
  • GitOps substrate configuration
  • cluster overlays and platform services
  • environment lifecycle workflows

Dubnium may invoke Laboratory entrypoints but should avoid embedding full cluster orchestration logic internally.

Consequences

Positive

  • cleaner recovery boundaries
  • reduced duplication
  • improved source-of-truth clarity
  • safer rebuild semantics
  • clearer operational ownership
  • easier future migration of cluster workflows

Negative

  • additional repository coordination
  • version pinning discipline becomes important
  • submodule or external checkout management complexity
  • bootstrap sequencing becomes more explicit

Current Implementation State

Current repository state:

  • dotfiles integration exists today
  • local k3s wiring remains host-local and intentionally thin
  • Laboratory integration is planned but not yet fully wired into runtime flows

The current v1 implementation keeps k3s operationally local while explicitly preparing for externalized cluster bootstrap ownership.

Operational Rules

  • machine boot must not depend on successful Laboratory reconciliation
  • machine boot must not depend on user-home customization success
  • dotfiles failure degrades user experience, not machine orchestration
  • Laboratory failure degrades cluster capabilities, not machine orchestration
  • Dubnium remains the root machine control plane

Follow-Up Work

  • add stable Laboratory bootstrap entrypoints
  • add optional external/laboratory checkout integration
  • add bootstrap and validation scripts
  • tighten version pinning and provenance validation
  • reduce placeholder local cluster assumptions over time