Local-shell data plane, Slice A: fleet routing mode, merged projection, hub credential (amicissimo#391)

[aarontrowbridge]

Implements Slice A of spec spec-20260905-193000-local-shell-data-plane (rev 2, design-of-record) — the transport slice of harmoniqs/amicissimo#391, per D1 (one service, three upstream modes), D2 (the merged projection; currency derived over what is fetched), D5 (three mints, one honesty rule). Composes amicissimo#394's resolver dispatch: the fleet mode is entitlement-staged, never hardcoded-on.

What lands

• Fleet routing mode (D1) — the service's dispatch gains a late-bound, data-driven routing mode (engine | fleet; Slice B owns degraded). In fleet mode, data + SSE route to the hub over the tunnel; the app shelf still serves the UI locally — zero UI assets cross the WAN (the founding diagnosis, fleet client: first-attach probe timeout (1500 ms) makes attach impossible on high-RTT links (plane wifi) — SSE override only covers post-attach #777). No silent fallback: a fleet boot with the tunnel down answers its own named 503, never the engine's.
• The merged projection (D2) — GET /amicode/fleet/sessions composes the hub store AND the local engine into ONE merged, provenance-tagged list (amicode_provenance; hub the store of record on conflicts, locals stay visible — the founding pain Read-only Fleet Sessions view: list hub sessions from a standalone client #779 dead in both directions). Currency is derived over what is actually fetched (count/max/sum + /global/health version per source) and tagged with its data sources — a token derived over one upstream is never compared against another. The hub-only read path that review rejected is not rebuilt.
• The hub credential (D5) — the hub mint's credential-store entry (~/.amico/fleet-hub.json, $AMICO_FLEET_HUB_FILE override) carries the lifecycle spec's F4 version stamp + base-reader guarantee (unknown keys tolerated on read, preserved on rewrite). Three mints, named and scoped (/amicode/fleet/status renders the registry); the hub mint is upstream-hop only and never accepted client-side; a missing credential is a named outcome (hub-credential-missing / projection credential-missing), never a silent fallback.
• Staging (the Stage whole skill dirs (companions resolve) + three skill-text fixes #394 composition) — fleet_staging.ts mirrors the resolver's dispatch: without the amicissimo entitlement the overlay source is never even read and nothing arms; with it, the fleet surfaces stage only through a lawful fleet-data-plane overlay manifest declaring the data-plane-routing surface (freeze-class checked, base-version stamped, skew named). Absence and rejection are named, never dead ends.

The staging fixture (H3)

The first describe block pins the no-entitlement byte identity: with the entitlement absent, the full client-visible request set (document, assets, manifest, API, proxied, unknown, fleet paths, anonymous) is byte-identical to the base service — the fleet mode does not exist.

Verification

• pnpm run typecheck clean; new suite green (25 tests).
• Full extension suite vs clean-main baseline: pre-existing failures only (terminal.test.ts ×2, editable_diffs_wiring.test.ts ×2 — identical on origin/main; cli_gate is environment-state-dependent and reproduces solo on clean main in this sandbox).

Out of scope (Slices B/C)

Degraded entry rule, write-failure contract, SSE liveness, revocation handoff, rejoin fixture (#392); the native merged view (#393); offline/mirror.

Closes the transport ACs of harmoniqs/amicissimo#391; the overlay manifest itself lands amicissimo-side (cross-referenced there).

---

Companion PR (amicissimo-side overlay content): harmoniqs/amicissimo#395 — the fleet-data-plane overlay manifest this staging gate consumes.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}