@akanjs/devkit 3.0.0-alpha.80 → 3.0.0-alpha.82

package/{fleetSpoke.ts → subspace.ts}

@@ -2,106 +2,93 @@ import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { AppExecutor, Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
-import type { FleetConfig, FleetSpokeDeclaration } from "./fleetConfig";
 import { LibSource } from "./libSource";
-import { SlicePlanner } from "./slicePlanner";
+import { type SlicePlan, SlicePlanner } from "./slicePlanner";
+import type { SubspaceConfig, SubspaceDeclaration } from "./subspaceConfig";
+import type { PackageJson } from "./types";
 
-export interface FleetIncomingCommit {
+export interface SubspaceIncomingCommit {
   sha: string;
   author: string;
   subject: string;
 }
 
-export interface FleetAnchor {
-  /** Spoke commit that last carried a push, located by the one file only a push writes. */
+export interface SubspaceAnchor {
+  /** Subspace commit that last carried a push, located by the one file only a push writes. */
   commit: string | null;
-  /** Commits the spoke gained since then — customer work that has never been in the hub. */
-  incoming: FleetIncomingCommit[];
+  /** Commits the subspace gained since then — customer work that has never been in the workspace. */
+  incoming: SubspaceIncomingCommit[];
 }
 
-export interface FleetSpokeStatus {
+export interface SubspaceStatus {
   name: string;
   branch: string;
-  /** False when the spoke has no such branch: a push refuses it rather than creating it. */
+  /** False when the subspace has no such branch: a push refuses it rather than creating it. */
   hasBranch: boolean;
-  anchor: FleetAnchor;
-  /** Slice paths where hub and spoke disagree — what a push would change. */
+  anchor: SubspaceAnchor;
+  /** Slice paths where workspace and subspace disagree — what a push would change. */
   behindPaths: string[];
-  /** Libraries the spoke edited on its own: the drift this mechanism exists to stop. */
+  /** Libraries the subspace edited on its own: the drift this mechanism exists to stop. */
   driftedLibs: string[];
 }
 
-export interface FleetDiffSection {
+export interface SubspaceDiffSection {
   files: string[];
   patch: string;
 }
 
-export interface FleetDiffResult {
+export interface SubspaceDiffResult {
   name: string;
   branch: string;
-  /** What `akan fleet push` would change in the spoke, split so library changes are impossible to miss. */
-  app: FleetDiffSection;
-  libs: FleetDiffSection;
+  /** What `akan subspace push` would change in the subspace, split so library changes are impossible to miss. */
+  app: SubspaceDiffSection;
+  libs: SubspaceDiffSection;
 }
 
-export interface FleetPushResult {
+export interface SubspacePushResult {
   name: string;
   outcome: "pushed" | "skipped" | "refused";
   reason?: string;
   commit?: string;
   changedFiles: number;
+  /** Workspace-root dependencies left out of this subspace's manifest, because its apps do not use them. */
+  prunedDependencies?: string[];
 }
 
-export interface FleetPullResult {
+export interface SubspacePullResult {
   name: string;
   applied: string[];
   /** Library hunks, left on disk as a patch instead of applied unless `adoptLibs` was passed. */
   libPatch: { path: string; files: string[] } | null;
   ignored: string[];
-  incoming: FleetIncomingCommit[];
+  incoming: SubspaceIncomingCommit[];
 }
 
 /**
- * One customer repo, mirrored from this hub.
+ * One customer repo, mirrored from this workspace.
  *
- * Push is a squashed snapshot of the hub's own tracked files, so a spoke's history never carries the
- * hub's — which is also what keeps one customer's commit messages out of another's repo. Pull is the
- * reverse and rare: it compares the spoke against the last push it received rather than against the hub,
- * so the diff is exactly the customer's own work however far the hub has moved on.
+ * Push is a squashed snapshot of the workspace's own tracked files, so a subspace's history never
+ * carries the workspace's — which is also what keeps one customer's commit messages out of another's
+ * repo. Pull is the reverse and rare: it compares the subspace against the last push it received rather
+ * than against the workspace, so the diff is exactly the customer's own work however far the workspace
+ * has moved on.
  */
-export class FleetSpoke {
-  static readonly anchorFile = "akan.fleet.json";
-  /** Never reaches a spoke: it names every other customer's repo. */
-  static readonly hubOnlyEntries = ["akan.fleet.ts"];
+export class Subspace {
+  static readonly anchorFile = "akan.subspace.json";
+  /** Never reaches a subspace: it names every other customer's repo. */
+  static readonly workspaceOnlyEntries = ["akan.subspace.ts"];
   /** Workspace members, which are replaced wholesale rather than overlaid. */
   static readonly memberDirs = ["apps", "libs"];
-  /** Spoke-owned in both directions: env values belong to the repo that deploys, not to the hub. */
-  static readonly spokeOwnedDirs = ["env"];
+  /** Subspace-owned in both directions: env values belong to the repo that deploys, not to the workspace. */
+  static readonly subspaceOwnedDirs = ["env"];
   static readonly secretsMarkers = ["# akan:secrets (managed by akan.config.ts — do not edit)", "# akan:secrets:end"];
-  static readonly holdDir = ".akan-fleet-hold";
-  static readonly guardHookLine = "bunx akan fleet check --staged --warn";
-  //? `fetch-depth: 0`: the guard locates the last push through history, which a shallow checkout lacks.
-  static readonly guardWorkflow = [
-    "name: akan fleet guard",
-    "on: [push, pull_request]",
-    "jobs:",
-    "  guard:",
-    "    runs-on: ubuntu-latest",
-    "    steps:",
-    "      - uses: actions/checkout@v4",
-    "        with:",
-    "          fetch-depth: 0",
-    "      - uses: oven-sh/setup-bun@v2",
-    "      - run: bun install",
-    "      - run: bunx akan fleet check",
-    "",
-  ].join("\n");
+  static readonly holdDir = ".akan-subspace-hold";
 
   #workspace: WorkspaceExecutor;
-  #config: FleetConfig;
-  #declaration: FleetSpokeDeclaration;
+  #config: SubspaceConfig;
+  #declaration: SubspaceDeclaration;
 
-  constructor(workspace: WorkspaceExecutor, config: FleetConfig, declaration: FleetSpokeDeclaration) {
+  constructor(workspace: WorkspaceExecutor, config: SubspaceConfig, declaration: SubspaceDeclaration) {
     this.#workspace = workspace;
     this.#config = config;
     this.#declaration = declaration;
@@ -114,10 +101,10 @@ export class FleetSpoke {
     return this.#declaration.apps;
   }
   get #remote() {
-    return `spoke-${this.#declaration.name}`;
+    return `subspace-${this.#declaration.name}`;
   }
   get #clonePath() {
-    return path.join(this.#workspace.workspaceRoot, ".akan/fleet", this.#declaration.name);
+    return path.join(this.#workspace.workspaceRoot, ".akan/subspace", this.#declaration.name);
   }
 
   async #git(args: string[]) {
@@ -132,7 +119,7 @@ export class FleetSpoke {
     return (await this.#git(["rev-parse", "--short", "HEAD"])).trim();
   }
 
-  /** Adds the spoke as a remote if absent, then fetches the branch into this hub's object store. */
+  /** Adds the subspace as a remote if absent, then fetches the branch into this workspace's object store. */
   async fetch(branch: string) {
     const remotes = (await this.#git(["remote"])).split("\n").map((line) => line.trim());
     if (remotes.includes(this.#remote)) await this.#git(["remote", "set-url", this.#remote, this.#declaration.repo]);
@@ -141,18 +128,18 @@ export class FleetSpoke {
       await this.#git(["fetch", "--quiet", this.#remote, branch]);
       return true;
     } catch {
-      //? A spoke that has never had this branch is not an error here — `push` refuses it by name.
+      //? A subspace that has never had this branch is not an error here — `push` refuses it by name.
       return false;
     }
   }
 
   /**
    * The last push, located by the one file only a push writes. A tag or a recorded sha would have to be
-   * kept in step by hand; this file is already in the spoke's history and cannot drift out of it.
+   * kept in step by hand; this file is already in the subspace's history and cannot drift out of it.
    */
-  async anchor(branch: string): Promise<FleetAnchor> {
+  async anchor(branch: string): Promise<SubspaceAnchor> {
     const ref = `${this.#remote}/${branch}`;
-    const commit = (await this.#git(["log", "-1", "--format=%H", ref, "--", FleetSpoke.anchorFile])).trim();
+    const commit = (await this.#git(["log", "-1", "--format=%H", ref, "--", Subspace.anchorFile])).trim();
     if (!commit) return { commit: null, incoming: [] };
     const log = await this.#git(["log", "--format=%H%x09%an%x09%s", `${commit}..${ref}`]);
     const incoming = log
@@ -165,7 +152,7 @@ export class FleetSpoke {
     return { commit, incoming };
   }
 
-  /** App and lib directories this spoke carries. Libraries come from each app's closure, never declared. */
+  /** App and lib directories this subspace carries. Libraries come from each app's closure, never declared. */
   async slice() {
     const plans = await Promise.all(
       this.#declaration.apps.map(
@@ -177,15 +164,15 @@ export class FleetSpoke {
     return { plans, libs, paths };
   }
 
-  #isSpokeOwned(file: string) {
+  #isSubspaceOwned(file: string) {
     const segments = file.split("/");
-    if (!FleetSpoke.memberDirs.includes(segments[0] ?? "")) return false;
-    return FleetSpoke.spokeOwnedDirs.includes(segments[2] ?? "");
+    if (!Subspace.memberDirs.includes(segments[0] ?? "")) return false;
+    return Subspace.subspaceOwnedDirs.includes(segments[2] ?? "");
   }
 
   /**
-   * A library manifest always differs: the spoke's copy carries the `akan.source` stamp a push writes and
-   * the hub's does not. Comparing it with that key removed is what keeps `status` and `diff` from
+   * A library manifest always differs: the subspace's copy carries the `akan.source` stamp a push writes and
+   * the workspace's does not. Comparing it with that key removed is what keeps `status` and `diff` from
    * reporting every library as changed forever.
    */
   #isStamped(file: string) {
@@ -217,11 +204,11 @@ export class FleetSpoke {
     return files.filter((_, index) => kept[index]);
   }
 
-  async status(branch: string): Promise<FleetSpokeStatus> {
+  async status(branch: string): Promise<SubspaceStatus> {
     const hasBranch = await this.fetch(branch);
     const [{ paths, libs }, anchor] = await Promise.all([
       this.slice(),
-      hasBranch ? this.anchor(branch) : Promise.resolve<FleetAnchor>({ commit: null, incoming: [] }),
+      hasBranch ? this.anchor(branch) : Promise.resolve<SubspaceAnchor>({ commit: null, incoming: [] }),
     ]);
     if (!hasBranch) return { name: this.name, branch, hasBranch, anchor, behindPaths: [], driftedLibs: [] };
     const ref = `${this.#remote}/${branch}`;
@@ -231,7 +218,7 @@ export class FleetSpoke {
       diff
         .split("\n")
         .filter((file) => !!file.trim())
-        .filter((file) => !this.#isSpokeOwned(file)),
+        .filter((file) => !this.#isSubspaceOwned(file)),
     );
     const driftedLibs = libs.filter((lib) => behindPaths.some((file) => file.startsWith(`libs/${lib}/`)));
     return { name: this.name, branch, hasBranch, anchor, behindPaths, driftedLibs };
@@ -243,23 +230,23 @@ export class FleetSpoke {
       await mkdir(path.dirname(this.#clonePath), { recursive: true });
       await this.#workspace.spawn("git", ["clone", "--quiet", this.#declaration.repo, this.#clonePath]);
     }
-    const clone = new Executor(`spoke-${this.name}`, this.#clonePath);
+    const clone = new Executor(`subspace-${this.name}`, this.#clonePath);
     await clone.spawn("git", ["fetch", "--quiet", "origin", branch]);
     await clone.spawn("git", ["checkout", "--quiet", "-B", branch, `origin/${branch}`]);
     await clone.spawn("git", ["clean", "-qfd"]);
     return clone;
   }
 
-  /** Moves the spoke's env trees aside, so replacing the members cannot take them with it. */
-  async #holdSpokeOwned() {
+  /** Moves the subspace's env trees aside, so replacing the members cannot take them with it. */
+  async #holdSubspaceOwned() {
     const held: { from: string; to: string }[] = [];
-    const holdRoot = path.join(this.#clonePath, FleetSpoke.holdDir);
+    const holdRoot = path.join(this.#clonePath, Subspace.holdDir);
     await rm(holdRoot, { recursive: true, force: true });
-    for (const member of FleetSpoke.memberDirs) {
+    for (const member of Subspace.memberDirs) {
       const memberRoot = path.join(this.#clonePath, member);
       if (!(await FileSys.dirExists(memberRoot))) continue;
       for (const name of await readdir(memberRoot)) {
-        for (const owned of FleetSpoke.spokeOwnedDirs) {
+        for (const owned of Subspace.subspaceOwnedDirs) {
           const from = path.join(memberRoot, name, owned);
           if (!(await FileSys.dirExists(from))) continue;
           const to = path.join(holdRoot, member, name, owned);
@@ -273,13 +260,13 @@ export class FleetSpoke {
   }
 
   /**
-   * Puts back only the files the hub does not ship. The hub still owns the tracked env switch files
+   * Puts back only the files the workspace does not ship. The workspace still owns the tracked env switch files
    * (`env.server.ts` / `env.client.ts`), which is what keeps them in step; everything else under `env/` —
-   * the per-environment values, which the hub gitignores and never had — belongs to the spoke and wins.
+   * the per-environment values, which the workspace gitignores and never had — belongs to the subspace and wins.
    */
-  async #restoreSpokeOwned(held: { from: string; to: string }[]) {
-    for (const { from, to } of held) await FleetSpoke.#copyMissing(to, from);
-    await rm(path.join(this.#clonePath, FleetSpoke.holdDir), { recursive: true, force: true });
+  async #restoreSubspaceOwned(held: { from: string; to: string }[]) {
+    for (const { from, to } of held) await Subspace.#copyMissing(to, from);
+    await rm(path.join(this.#clonePath, Subspace.holdDir), { recursive: true, force: true });
   }
 
   static async #copyMissing(from: string, to: string) {
@@ -287,7 +274,7 @@ export class FleetSpoke {
     for (const entry of await readdir(from, { withFileTypes: true })) {
       const source = path.join(from, entry.name);
       const target = path.join(to, entry.name);
-      if (entry.isDirectory()) await FleetSpoke.#copyMissing(source, target);
+      if (entry.isDirectory()) await Subspace.#copyMissing(source, target);
       else if (!(await FileSys.entryExists(target))) await rename(source, target);
     }
   }
@@ -307,9 +294,9 @@ export class FleetSpoke {
   }
 
   /**
-   * Verify-only, and an allowlist rather than a filter so no hub secret can reach a customer's clone even
-   * by accident. `AKAN_PUBLIC_*` values are the ones akan embeds in every client bundle, so they are public
-   * by construction; the workspace id is pinned to `local` so the hub's cloud workspace never travels.
+   * Verify-only, and an allowlist rather than a filter so no secret can reach a customer's clone even by
+   * accident. `AKAN_PUBLIC_*` values are the ones akan embeds in every client bundle, so they are public
+   * by construction; the cloud workspace id is pinned to `local` rather than copied.
    */
   #localEnv() {
     const { serveDomain } = WorkspaceExecutor.getBaseDevEnv();
@@ -326,9 +313,9 @@ export class FleetSpoke {
   /**
    * The CLI identifies a workspace root by `package.json` + `tsconfig.json` + `.env`, so a clone with no
    * `.env` cannot run `akan sync` at all — and one can never arrive with the slice, since every akan
-   * workspace gitignores it and the spoke's real values are spoke-owned. Excluded through the clone's own
-   * `.git/info/exclude` rather than trusting the hub's `.gitignore`: a hub that omitted the pattern would
-   * otherwise commit this file into the customer's repo.
+   * workspace gitignores it and the subspace's real values are its own. Excluded through the clone's
+   * `.git/info/exclude` rather than through the copied `.gitignore`: a workspace that omitted the pattern
+   * would otherwise commit this file into the customer's repo.
    */
   async #writeLocalEnv() {
     const excludePath = path.join(this.#clonePath, ".git/info/exclude");
@@ -343,38 +330,61 @@ export class FleetSpoke {
     await FileSys.writeText(envPath, `${lines.join("\n")}\n`);
   }
 
+  /**
+   * A workspace's root manifest is the union of every app it holds, so shipping it verbatim installs
+   * every other customer's dependency tree in this repo. It is rebuilt from this subspace's own slices
+   * instead, keeping the workspace's exact version specs.
+   */
+  async #rewriteManifest(plans: SlicePlan[]) {
+    const manifestPath = path.join(this.#clonePath, "package.json");
+    if (!(await FileSys.fileExists(manifestPath))) return [];
+    const rootPackageJson = (await FileSys.readJson(manifestPath)) as PackageJson;
+    const { packageJson, pruned, warnings } = await SlicePlanner.pruneDependencies(
+      this.#workspace,
+      rootPackageJson,
+      plans.flatMap((plan) => plan.requiredDependencies),
+    );
+    for (const warning of warnings) this.#workspace.logger.warn(warning);
+    await FileSys.writeJson(manifestPath, {
+      ...packageJson,
+      name: this.name,
+      description: `${this.name} workspace`,
+    });
+    return pruned;
+  }
+
   async #applySlice(clone: Executor, branch: string) {
-    const { libs, paths } = await this.slice();
-    const held = await this.#holdSpokeOwned();
-    for (const member of FleetSpoke.memberDirs)
+    const { libs, paths, plans } = await this.slice();
+    const held = await this.#holdSubspaceOwned();
+    for (const member of Subspace.memberDirs)
       await rm(path.join(this.#clonePath, member), { recursive: true, force: true });
 
-    //* The shell is overlaid, never reconciled: a spoke owns its deployment (its own CI files and
-    //* workflows live there), so a root entry the hub does not have is left alone rather than deleted.
+    //* The shell is overlaid, never reconciled: a subspace owns its deployment (its own CI files and
+    //* workflows live there), so a root entry the workspace does not have is left alone rather than deleted.
     await this.#extract(["."], ["apps/*", "libs/*", "pkgs/*"]);
     await this.#extract(paths);
-    await this.#restoreSpokeOwned(held);
+    await this.#restoreSubspaceOwned(held);
 
-    for (const entry of [...FleetSpoke.hubOnlyEntries, ...this.#config.exclude])
+    for (const entry of [...Subspace.workspaceOnlyEntries, ...this.#config.exclude])
       await rm(path.join(this.#clonePath, entry), { recursive: true, force: true });
 
     await this.#rewriteGitignore();
+    const pruned = await this.#rewriteManifest(plans);
     await this.#rewriteWorkspaceSection(libs);
-    await this.#writeGuards();
     await this.#writeLocalEnv();
     for (const lib of libs) await this.#stampLib(clone, lib, branch);
-    return { libs };
+    return { libs, pruned };
   }
 
   /**
-   * The `akan:secrets` block akan generates lists every app in the hub by name, so it is filtered down to
-   * this spoke's own apps. `bun.lock` is un-ignored because a spoke commits its lockfile — that is what
-   * makes two spokes on one branch resolve the same dependency tree rather than merely the same ranges.
+   * The `akan:secrets` block akan generates lists every app in the workspace by name, so it is filtered down to
+   * this subspace's own apps. `bun.lock` is un-ignored because a subspace commits its lockfile — that is what
+   * makes two subspaces on one branch resolve the same dependency tree rather than merely the same ranges.
    */
   async #rewriteGitignore() {
     const gitignorePath = path.join(this.#clonePath, ".gitignore");
     if (!(await FileSys.fileExists(gitignorePath))) return;
-    const [begin = "", end = ""] = FleetSpoke.secretsMarkers;
+    const [begin = "", end = ""] = Subspace.secretsMarkers;
     const lines = (await FileSys.readText(gitignorePath)).split("\n");
     const beginIdx = lines.indexOf(begin);
     const endIdx = lines.indexOf(end);
@@ -391,7 +401,7 @@ export class FleetSpoke {
     await FileSys.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join("\n"));
   }
 
-  /** The generated `## Workspace` block names every app and library in the hub. */
+  /** The generated `## Workspace` block names every app and library in the workspace. */
   async #rewriteWorkspaceSection(libs: string[]) {
     const replacements = [
       [/^- Repo: .*$/m, `- Repo: ${this.name}`],
@@ -409,9 +419,9 @@ export class FleetSpoke {
 
   /**
    * Written onto the clone's manifest directly rather than through `LibSource`, which addresses a library
-   * by its position in the *hub's* workspace. The hash follows the same rule — the library's own git files
+   * by its position in the *workspace's* workspace. The hash follows the same rule — the library's own git files
    * with `env/` and the stamp itself left out — and is only written when it would change, so an
-   * up-to-date spoke stays clean and the push is skipped.
+   * up-to-date subspace stays clean and the push is skipped.
    */
   async #stampLib(clone: Executor, lib: string, branch: string) {
     const manifestPath = path.join(this.#clonePath, "libs", lib, "package.json");
@@ -421,7 +431,7 @@ export class FleetSpoke {
     const [hash, previous] = await Promise.all([this.#hashLib(clone, lib), this.#committedStamp(clone, lib)]);
     const manifest = (await FileSys.readJson(manifestPath)) as Record<string, unknown>;
     const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
-    //* The extraction overwrote the manifest with the hub's, stamp and all, so the previous stamp has to
+    //* The extraction overwrote the manifest with the workspace's, stamp and all, so the previous stamp has to
     //* come from the clone's HEAD. Reusing its `syncedAt` when nothing else moved is what leaves the file
     //* byte-identical to what is committed — otherwise every push is dirty and none is ever skipped.
     const unchanged = previous?.origin === origin && previous.sha === sha && previous.hash === hash;
@@ -437,7 +447,7 @@ export class FleetSpoke {
       const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
       return akan.source as { origin: string; sha: string; hash: string; syncedAt: string } | undefined;
     } catch {
-      //? First push: the library is not in the spoke's history yet.
+      //? First push: the library is not in the subspace's history yet.
       return undefined;
     }
   }
@@ -454,7 +464,7 @@ export class FleetSpoke {
     ]);
     const files = listed
       .split("\0")
-      .filter((file) => !!file && !this.#isSpokeOwned(file))
+      .filter((file) => !!file && !this.#isSubspaceOwned(file))
       .sort();
     const hasher = new Bun.CryptoHasher("sha256");
     for (const file of files) {
@@ -471,9 +481,9 @@ export class FleetSpoke {
     return hasher.digest("hex").slice(0, 32);
   }
 
-  /** Direction is spoke → hub, so the patch reads as what a push would apply rather than its inverse. */
-  async diff(branch: string, filter?: string | null): Promise<FleetDiffResult> {
-    if (!(await this.fetch(branch))) throw new Error(`Spoke "${this.name}" has no branch "${branch}"`);
+  /** Direction is subspace → workspace, so the patch reads as what a push would apply rather than its inverse. */
+  async diff(branch: string, filter?: string | null): Promise<SubspaceDiffResult> {
+    if (!(await this.fetch(branch))) throw new Error(`Subspace "${this.name}" has no branch "${branch}"`);
     const { libs, paths } = await this.slice();
     const libPaths = libs.map((lib) => `libs/${lib}`);
     const appPaths = paths.filter((entry) => !libPaths.includes(entry));
@@ -484,7 +494,7 @@ export class FleetSpoke {
     return { name: this.name, branch, app, libs: libSection };
   }
 
-  async #diffSection(branch: string, paths: string[], filter?: string | null): Promise<FleetDiffSection> {
+  async #diffSection(branch: string, paths: string[], filter?: string | null): Promise<SubspaceDiffSection> {
     const scoped = filter ? paths.filter((entry) => entry.startsWith(filter) || filter.startsWith(entry)) : paths;
     if (!scoped.length) return { files: [], patch: "" };
     const from = `${this.#remote}/${branch}`;
@@ -495,7 +505,7 @@ export class FleetSpoke {
       names
         .split("\n")
         .filter((file) => !!file.trim())
-        .filter((file) => !this.#isSpokeOwned(file)),
+        .filter((file) => !this.#isSubspaceOwned(file)),
     );
     if (!files.length) return { files: [], patch: "" };
     //? argv, not a shell: a route path such as `page/(docs)/…` would need quoting through one.
@@ -503,32 +513,9 @@ export class FleetSpoke {
   }
 
   /**
-   * The spoke-side guard, which is one line calling `akan fleet check` rather than a script of its own —
-   * the logic lives in the CLI, so a spoke never carries a copy that can rot. Written after the shell
-   * overlay, since the hub's own `.husky/pre-commit` travels with it and would otherwise win.
-   */
-  async #writeGuards() {
-    const { ci, preCommit } = this.#config.guard;
-    if (ci === "github") {
-      const workflowPath = path.join(this.#clonePath, ".github/workflows/akan-fleet-guard.yml");
-      await mkdir(path.dirname(workflowPath), { recursive: true });
-      await FileSys.writeText(workflowPath, FleetSpoke.guardWorkflow);
-    }
-    if (!preCommit) return;
-    const hookPath = path.join(this.#clonePath, ".husky/pre-commit");
-    const existing = (await FileSys.fileExists(hookPath)) ? await FileSys.readText(hookPath) : "";
-    if (existing.includes(FleetSpoke.guardHookLine)) return;
-    await mkdir(path.dirname(hookPath), { recursive: true });
-    const content = existing.trim()
-      ? `${existing.replace(/\n*$/, "\n")}${FleetSpoke.guardHookLine}\n`
-      : `${FleetSpoke.guardHookLine}\n`;
-    await FileSys.writeText(hookPath, content);
-  }
-
-  /**
-   * Refuses the spoke rather than throwing, so one customer repo that fails to install or sync does not
-   * abort the push to the rest of the fleet. The env is passed explicitly so the child sees the values
-   * written into the clone instead of inheriting the hub's own.
+   * Refuses the subspace rather than throwing, so one customer repo that fails to install or sync does not
+   * abort the push to the rest of the subspaces. The env is passed explicitly so the child sees the values
+   * written into the clone instead of inheriting the workspace's own.
    */
   async #verify(clone: Executor) {
     const env = { ...process.env, ...this.#localEnv() };
@@ -541,18 +528,25 @@ export class FleetSpoke {
     }
   }
 
-  async push(branch: string, { verify = true }: { verify?: boolean } = {}): Promise<FleetPushResult> {
+  async push(branch: string, { verify = true }: { verify?: boolean } = {}): Promise<SubspacePushResult> {
     this.#config.assertPushable(branch);
     if (await this.#workspace.hasChanges())
-      return { name: this.name, outcome: "refused", reason: "hub working tree is dirty", changedFiles: 0 };
+      return { name: this.name, outcome: "refused", reason: "workspace working tree is dirty", changedFiles: 0 };
     if (!(await this.fetch(branch)))
-      return { name: this.name, outcome: "refused", reason: `spoke has no branch "${branch}"`, changedFiles: 0 };
+      return { name: this.name, outcome: "refused", reason: `subspace has no branch "${branch}"`, changedFiles: 0 };
 
     const clone = await this.#ensureClone(branch);
-    await this.#applySlice(clone, branch);
+    const { pruned } = await this.#applySlice(clone, branch);
 
     const dirty = (await clone.spawn("git", ["status", "--porcelain"])).trim();
-    if (!dirty) return { name: this.name, outcome: "skipped", reason: "already up to date", changedFiles: 0 };
+    if (!dirty)
+      return {
+        name: this.name,
+        outcome: "skipped",
+        reason: "already up to date",
+        changedFiles: 0,
+        prunedDependencies: pruned,
+      };
 
     const changedFiles = dirty.split("\n").length;
     if (verify) {
@@ -561,21 +555,22 @@ export class FleetSpoke {
     }
     await this.#writeAnchorFile(branch);
     await clone.spawn("git", ["add", "-A"]);
-    const message = `chore(fleet): sync from ${this.#workspace.repoName}@${await this.headSha()}`;
+    const message = `chore(subspace): sync from ${this.#workspace.repoName}@${await this.headSha()}`;
     await clone.spawn("git", ["commit", "--quiet", "-m", message]);
-    //* Never force: a diverged spoke holds customer commits, and `pull` is how those come back.
+    //* Never force: a diverged subspace holds customer commits, and `pull` is how those come back.
     await clone.spawn("git", ["push", "--quiet", "origin", branch]);
     return {
       name: this.name,
       outcome: "pushed",
       commit: (await clone.spawn("git", ["rev-parse", "--short", "HEAD"])).trim(),
       changedFiles,
+      prunedDependencies: pruned,
     };
   }
 
   async #writeAnchorFile(branch: string) {
-    await FileSys.writeJson(path.join(this.#clonePath, FleetSpoke.anchorFile), {
-      hub: this.#workspace.repoName,
+    await FileSys.writeJson(path.join(this.#clonePath, Subspace.anchorFile), {
+      workspace: this.#workspace.repoName,
       hubSha: await this.headSha(),
       branch,
       apps: this.#declaration.apps,
@@ -583,20 +578,20 @@ export class FleetSpoke {
     });
   }
 
-  async pull(branch: string, { adoptLibs = false }: { adoptLibs?: boolean } = {}): Promise<FleetPullResult> {
-    if (!(await this.fetch(branch))) throw new Error(`Spoke "${this.name}" has no branch "${branch}"`);
+  async pull(branch: string, { adoptLibs = false }: { adoptLibs?: boolean } = {}): Promise<SubspacePullResult> {
+    if (!(await this.fetch(branch))) throw new Error(`Subspace "${this.name}" has no branch "${branch}"`);
     const anchor = await this.anchor(branch);
     if (!anchor.commit)
-      throw new Error(`Spoke "${this.name}" carries no ${FleetSpoke.anchorFile} — it has never received a push`);
+      throw new Error(`Subspace "${this.name}" carries no ${Subspace.anchorFile} — it has never received a push`);
     if (!anchor.incoming.length) return { name: this.name, applied: [], libPatch: null, ignored: [], incoming: [] };
 
     const range = `${anchor.commit}..${this.#remote}/${branch}`;
     const changed = (await this.#git(["diff", "--name-only", range])).split("\n").filter((file) => !!file.trim());
     const appPrefixes = this.#declaration.apps.map((app) => `apps/${app}/`);
     const appFiles = changed.filter(
-      (file) => appPrefixes.some((prefix) => file.startsWith(prefix)) && !this.#isSpokeOwned(file),
+      (file) => appPrefixes.some((prefix) => file.startsWith(prefix)) && !this.#isSubspaceOwned(file),
     );
-    const libFiles = changed.filter((file) => file.startsWith("libs/") && !this.#isSpokeOwned(file));
+    const libFiles = changed.filter((file) => file.startsWith("libs/") && !this.#isSubspaceOwned(file));
     const ignored = changed.filter((file) => !appFiles.includes(file) && !libFiles.includes(file));
 
     const applied = adoptLibs ? [...appFiles, ...libFiles] : appFiles;
@@ -606,31 +601,31 @@ export class FleetSpoke {
     return { name: this.name, applied, libPatch, ignored, incoming: anchor.incoming };
   }
 
-  /** Left uncommitted in the hub's working tree: a conflict is a normal 3-way conflict for a person. */
+  /** Left uncommitted in the workspace's working tree: a conflict is a normal 3-way conflict for a person. */
   async #applyPatch(range: string, files: string[], label: string) {
     const { absolute } = await this.#savePatch(range, files, label);
     await this.#git(["apply", "--3way", absolute]);
   }
 
   /**
-   * A library hunk is never applied by default: the hub is the one copy every other spoke is pushed from,
+   * A library hunk is never applied by default: the workspace is the one copy every other subspace is pushed from,
    * so adopting one customer's edit silently would ship it to all of them.
    */
   async #savePatch(range: string, files: string[], label: string) {
-    const patchPath = path.join(this.#workspace.workspaceRoot, ".akan/fleet", `${this.name}-${label}.patch`);
+    const patchPath = path.join(this.#workspace.workspaceRoot, ".akan/subspace", `${this.name}-${label}.patch`);
     await mkdir(path.dirname(patchPath), { recursive: true });
     await FileSys.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
     return { path: path.relative(this.#workspace.workspaceRoot, patchPath), absolute: patchPath, files };
   }
 }
 
-export function formatFleetStatuses(statuses: FleetSpokeStatus[]) {
+export function formatSubspaceStatuses(statuses: SubspaceStatus[]) {
   const sections = [
-    "Akan Fleet Status",
+    "Akan Subspace Status",
     `branch: ${statuses[0]?.branch ?? "(none)"}`,
     "",
     ...statuses.flatMap((status) => {
-      if (!status.hasBranch) return [`  ${status.name}: no such branch in the spoke — push is refused`];
+      if (!status.hasBranch) return [`  ${status.name}: no such branch in the subspace — push is refused`];
       const behind = status.behindPaths.length ? `${status.behindPaths.length} file(s) behind` : "up to date";
       const incoming = status.anchor.incoming.length
         ? `${status.anchor.incoming.length} customer commit(s) to pull`
@@ -646,23 +641,30 @@ export function formatFleetStatuses(statuses: FleetSpokeStatus[]) {
   return sections.join("\n");
 }
 
-export function formatFleetPushResults(results: FleetPushResult[]) {
+export function formatSubspacePushResults(results: SubspacePushResult[]) {
   const sections = [
-    "Akan Fleet Push",
+    "Akan Subspace Push",
     "",
     ...results.flatMap((result) => {
       const detail =
         result.outcome === "pushed" ? `${result.commit} (${result.changedFiles} files)` : (result.reason ?? "");
       const [first = "", ...rest] = detail.split("\n");
-      return [`  ${result.outcome.padEnd(8)} ${result.name}  ${first}`, ...rest.map((line) => `    ${line}`)];
+      const pruned = result.prunedDependencies?.length
+        ? [`    ${result.prunedDependencies.length} unused root dependenc(ies) left out of package.json`]
+        : [];
+      return [
+        `  ${result.outcome.padEnd(8)} ${result.name}  ${first}`,
+        ...rest.map((line) => `    ${line}`),
+        ...pruned,
+      ];
     }),
   ];
   return sections.join("\n");
 }
 
-export function formatFleetPullResult(result: FleetPullResult) {
+export function formatSubspacePullResult(result: SubspacePullResult) {
   const sections = [
-    `Akan Fleet Pull — ${result.name}`,
+    `Akan Subspace Pull — ${result.name}`,
     "",
     `Customer commits since the last push (${result.incoming.length}):`,
     "",
@@ -681,24 +683,26 @@ export function formatFleetPullResult(result: FleetPullResult) {
           ...result.libPatch.files.map((file) => `  ${file}`),
           "",
           `  patch: ${result.libPatch.path}`,
-          "  adopt with: akan fleet pull <name> --adopt-libs",
+          "  adopt with: akan subspace pull <name> --adopt-libs",
         ]
       : []),
-    ...(result.ignored.length ? ["", `Ignored (hub-owned or spoke-owned): ${result.ignored.length} file(s)`] : []),
+    ...(result.ignored.length
+      ? ["", `Ignored (workspace-owned or subspace-owned): ${result.ignored.length} file(s)`]
+      : []),
   ];
   return sections.join("\n");
 }
 
-export function formatFleetDiff(result: FleetDiffResult) {
+export function formatSubspaceDiff(result: SubspaceDiffResult) {
   const total = result.app.files.length + result.libs.files.length;
   const sections = [
-    `Akan Fleet Diff — ${result.name} (${result.branch})`,
-    "what `akan fleet push` would change in the spoke",
+    `Akan Subspace Diff — ${result.name} (${result.branch})`,
+    "what `akan subspace push` would change in the subspace",
     "",
-    ...(total ? [] : ["  spoke is identical to the hub for this slice."]),
+    ...(total ? [] : ["  subspace is identical to the workspace for this slice."]),
     ...(result.libs.files.length
       ? [
-          `LIBRARY changes (${result.libs.files.length}) — the spoke edited shared code:`,
+          `LIBRARY changes (${result.libs.files.length}) — the subspace edited shared code:`,
           "",
           ...result.libs.files.map((file) => `  ${file}`),
           "",