# 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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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