Harbor

sharkk/corvette public

Components 3 Issues Requests

branch main
showing the latest snapshot on main
plan.md 8.0 KB · Markdown
plan.md 0644 Raw

dependency workspace split plan

Goal

Drop gpu/deps, make window, shader language/compiler (luma), and font library first-class ownership surfaces, and repoint gpu examples/tests to those libraries. Rebrand truetype as font. Keep snapshots small, child-first. Add remotes now; do not publish while Harbor Hub repairs are happening.

Current honest status: implemented locally, 100% for requested no-publish scope.

Verified current state

  • Root corvette Harbor workspace is dirty with pending added files under window/, luma/, and truetype/.
  • Root already has nested workspace component gpu, pinned clean at 5e29ccf545b8.
  • window/, luma/, and truetype/ do not yet have .harbor.d; root currently sees their files as plain pending adds.
  • gpu Harbor workspace is clean. gpu/deps exists on disk, but is untracked by gpu Harbor.
  • gpu imports only vendored window and luma through deps::
  • deps:window/window
  • deps:luma/luma
  • No repo code imports truetype yet.
  • gpu/scripts/check.sh and gpu/tools/test.lua pass -collection:deps=<gpu/deps>.
  • Root-level window package lives at window/window with package name window.
  • Root-level luma package lives at luma/luma with package name luma.
  • Root-level truetype package is flat under truetype/*.odin with package name truetype.

Opus 4.8 review result

  • Must not initialize nested Harbor workspaces while root also snapshots their files as plain files. Child workspaces must be created before root snapshots library content.
  • Must exclude local/generated junk before publishing libraries: .claude/settings.local.json, .DS_Store, *.bin, *_bin, and generated shader binaries unless intentionally source artifacts.
  • gpu/deps is untracked, so dropping it is disk cleanup plus import/build-script changes, not Harbor de-tracking.
  • Repointing gpu to sibling ../window makes gpu not standalone-buildable from its own remote unless window is also available as a gpu component or CI clones corvette. Need explicit component graph choice.
  • Rebranding truetype to font is isolated but must sweep docs/scripts, not only Odin package declarations.
  • luma ownership is the key design choice:
  • direct absorption into gpu is simplest if gpu truly owns language/compiler;
  • nested luma workspace under gpu preserves independent versioning but adds root -> gpu -> luma pin/publish ordering.

Proposed component graph

Pending user confirmation:

  • window: independent Harbor workspace at window/, linked into root corvette as workspace component, published to window remote.
  • font: renamed from truetype/ to font/, package declarations renamed from truetype to font, independent Harbor workspace linked into root corvette.
  • luma: refactor into gpu/shader as a literal gpu subpackage. It will not be a root corvette component. Root-level luma/ is migration input only, then removed from root ownership.

Implementation phases

  1. Prepare library workspaces safely
  • Do not snapshot root raw pending window/, luma/, truetype/ files as plain root-owned files.
  • Add ignore/local materialization rules for generated/local-only files before child snapshots.
  • Initialize/snapshot window child workspace; add remote origin = https://harbor.sharkk.net/sharkk/window; do not publish yet.
  • Rename truetype -> font, rename package truetype -> package font, update README/docs/package references, initialize/snapshot font child workspace; add remote origin = https://harbor.sharkk.net/sharkk/font; do not publish yet.
  • Prepare luma according to confirmed ownership model.
  1. Link components
  • Link window and font into root corvette as workspace components.
  • If luma becomes gpu-owned nested workspace, link it into gpu; root only pins gpu.
  • Verify harbor component list, harbor graph, harbor status, and harbor doctor show component pins, not unmanaged nested workspaces or root-owned child internals.
  1. Refactor luma into gpu shader package
  • Move luma compiler/language source from root luma/luma (and current disk gpu/deps/luma/luma) into gpu/shader.
  • Rename package from luma to shader if the codebase convention requires package name match the new subpackage; otherwise keep public alias at import sites only if Odin permits cleanly. No compatibility shim unless needed by tests.
  • Move/adapt luma tests/golden files/tools under gpu-owned shader layout.
  • Update gpu shader compile callsites to import shader from the local package path, not a collection.
  1. Repoint gpu imports/build tools
  • Replace deps:window/window imports with window:window.
  • Replace deps:luma/luma imports with gpu-owned shader package imports.
  • Update gpu/scripts/check.sh and gpu/tools/test.lua to pass explicit collections:
  • -collection:window=<component path>, defaulting to sibling ../window, overridable by GPU_WINDOW_COLLECTION for standalone gpu clones/CI.
  • no external luma collection after shader absorption
  • Remove dependence on -collection:deps.
  • Delete disk-only gpu/deps after imports/scripts no longer reference it.
  1. Validate
  • Run standalone checks for window, font, and gpu-owned shader where available.
  • Run cd gpu && scripts/check.sh.
  • Run search gates:
  • no deps: imports in gpu
  • no gpu/deps references
  • no package truetype after font rebrand
  • Run Harbor gates for every touched workspace: status, diff before snapshot, doctor, component check/graph.
  1. Snapshot/publish order
  • Snapshot small in child workspaces first.
  • Add window and font remotes after validation; do not publish until Harbor Hub repairs are complete.
  • Snapshot/publish gpu after shader absorption and deps removal.
  • Snapshot root corvette last so component pins reference child workspaces.
  • Defer all publishes unless user explicitly says Harbor Hub repairs are done.

Open decisions

  • Confirmed: luma becomes a literal gpu/shader subpackage owned by gpu.
  • Confirmed: window remote URL is https://harbor.sharkk.net/sharkk/window; font remote URL is https://harbor.sharkk.net/sharkk/font.
  • Confirmed: add remotes but do not publish while Harbor Hub repairs are happening.
  • Standalone gpu build policy: default checks use sibling ../window inside corvette; GPU_WINDOW_COLLECTION override keeps standalone clones/CI possible if they provide a window checkout.
  • Confirm whether root plan.md should remain tracked in the root Harbor snapshot. User asked for local plan.md, so default is yes.

Completion update

  • window is a Harbor workspace at window/, snapshot 8a10473e27c2, remote origin = https://harbor.sharkk.net/sharkk/window.
  • truetype was renamed to font, package declarations/docs were rebranded, and font is a Harbor workspace at font/, snapshot b6ff6bd8a9f8, remote origin = https://harbor.sharkk.net/sharkk/font.
  • luma was absorbed into gpu as gpu/shader; compiler CLI moved to gpu/tools/shader; gpu snapshot 69c44c9993b6.
  • gpu/deps was removed. gpu imports now use window:window for the external window collection and local shader package for shader compiler/language.
  • gpu/scripts/check.sh and gpu/tools/test.lua use GPU_WINDOW_COLLECTION override, defaulting to sibling ../window.
  • Root corvette links window and font as local workspace components while Hub publish is deferred; root snapshot fb7147bdde70.
  • No publish was performed.
  • Validation passed:
  • window: odin check window -no-entry-point, odin check examples/basic.odin -file
  • font: odin check . -no-entry-point
  • gpu/shader: odin check shader -no-entry-point, odin check tools/shader, golden tests 65 passed, external validation 30 passed / 0 failed with unavailable WGSL/HLSL/MSL validators skipped
  • gpu: scripts/check.sh
  • rg gates: no deps:/-collection:deps/gpu/deps, no package truetype, no stale package luma imports
  • Harbor: root/gpu/window/font status clean and doctor clean; window/font component checks ok