Skip to content

fleet step 1: pkgs/fleet workspace skeleton — platform crates, registry + capability stubs, variant builds #5429

Closed

Description

@developing-today

Part of epic #5412. Design of record: #5425 (design note doc/2026-11-04T11-45-48Z_design_fleet_multicall_binary, §1, §2, §3, §7 step 1). Predecessor: the design ruling recorded on #5412 — D1–D8 approved as recommended, with refinements A and B. Gate for step 2: this step's per-variant smoke suites green and the D7 evidence reported.

Scope

Stand up pkgs/fleet/ in this repo as a self-contained Cargo workspace (the pkgs/atlas-search pattern: own Cargo.toml, Cargo.lock, rust-toolchain.toml, default.nix; no workspace relationship to the repo root):

  • Platform crates: fleet-registry (the full domain registry — names, one-line descriptions, argv0 aliases, help pointers; std-only; compiled into every variant), fleet-config (~/.config/fleet/fleet.toml + env resolution + the [domains] enable/disable table), fleet-secrets (the one secrets-by-name path: secrets-broker protocol first, bws CLI fallback; token files read per request, never stored, never logged), fleet-proxy-proto (length-prefixed JSON framing + the hello/capability frame types — the wire contract lives here and nowhere else).
  • The fleet bin crate: multicall dispatch (argv0 alias → compiled-in domain runs → known-but-absent domain stubs → unknown name is clap's normal error), the stub machinery, fleet version (workspace version + enabled capability list + source rev — the surface the census found missing), fleet capabilities (the registry as JSON for agents), and --help rendering the full registry on every variant with [not in this build] marks on absent domains.
  • Capability stubs exactly per §3: a stderr block naming the missing domain, the enabled capabilities, and the build identity; exit code 69 (EX_UNAVAILABLE, D3). A config-disabled domain takes the same path and code with disabled by config on this host wording.
  • Three variant builds (D2): flake attrs packages.fleet, packages.fleet-serve, packages.fleet-connect with the §2 feature sets. In this step the variants build empty-but-correct — domains stub or stay minimal until their own steps land.

Refinement A — name-scoped surfaces (Drew's ruling; lands in this step)

The hyphenated names (fleet-serve, fleet-connect) live at the package/attr level and on machines where multiple variants are installed side by side; wherever a variant is actually used, it is installed/renamed as plain fleet. Names are also semantic: invoking a binary under a hyphenated name scopes its surface to that profile — a name can only narrow the capability set, never widen it past the build's compiled features. Implement name-scoping in the dispatch layer (this is the argv0/multicall mechanism extended to variant names) and cover it in the smoke suites: a full build invoked as fleet-connect stubs non-connect domains at 69; the same artifact invoked as fleet does not. In NixOS, where the variants are made, the hyphenated versions may be kept when multiple binaries are installed.

Refinement B + D7 — linkage flavors and the measurement

Builds come in dynamic (glibc, nix-closure) and static (musl) flavors, chosen per install context: dynamic where the nix closure travels with the install, static for drop-anywhere locations. This step's D7 measurement covers both flavors of fleet-connect:

  • size of each flavor, stripped — target ≤ 1.5 MiB, hard budget ≤ 2 MiB, enforced as a nix build gate on the connect package so a size regression blocks a release instead of surprising a codespace;
  • runs-anywhere smoke for each flavor (env -i, plus a foreign container image).

Report both flavors' numbers on this issue as the evidence for Drew's D7 ruling. The full fleet build stays dynamic (ONNX is dlopen'd regardless). Prefer rustls-style pure-Rust dependencies in the small variants so the static builds stay clean.

Per-variant smoke suites (§2 — all live in this step)

  • All variants: version output; --help full-registry rendering with marks; known-but-absent domain exits 69 with the stub text.
  • fleet: queue health against a stub broker; search get-chunk against a fixture DB; proxy serve + connect round-trip on a scratch socket; each serve <role> binds a scratch port and answers /health.
  • fleet-serve: every serve role answers /health; client-only domains stub at 69.
  • fleet-connect: size ≤ budget (build gate); env -i run; init against a scratch broker materializes the shim dir; every domain except proxy stubs at 69.

Gate

  • All three variants (both connect flavors) build from the flake; the smoke suites are wired as nix checks or scripted post-build runs and pass.
  • D7 evidence (both linkage flavors, size + portability) reported on this issue.
  • No live call site changes in this step — migration starts at step 2.

Acceptance criteria

  • pkgs/fleet workspace skeleton exists with platform crates, registry + capability stubs, and variant builds passing.
  • No regression: existing tests/checks for the touched area remain green, and the change lands via PR referencing this issue.
  • Evidence (PR link, test/CI output, or verification note) is posted on this issue before it is closed.

Activity

  1. dezren39 commented on Nov 4, 2026

    @dezren39
    Member

    Intake review

    🤖 Agent note · state: filed

    • Agent: fleet monitor
    • Session / ID: repo-fleet-monitor run 2026-11-04 06:12 CST
    • Found via: monitor reconciliation
    • Task: Intake enrichment (protocol §5): verified still live in a bounded check this run (no merged PR or closed duplicate naming this fix), appended acceptance criteria, normalized labels.
    • Expectation: as labelled (effort class on the issue); done = acceptance criteria met with evidence linked here.

    Related: epic #5412 and steps #5429-#5433 form one set; #5413 is a sibling absorption task. Native sub-issue attachment per protocol §11 is recommended for the epic if not already done.
    Risks: Sequencing: the fleet steps are gated in order (notably #5433 on the #5350 step 6 cutover); starting out of order risks rework.
    Suggested approach: Triage through the queue in dependency order, verifying each step's acceptance evidence before closing.

  2. added
    meta/enrichedIntake review done: acceptance criteria, links, and normalized labels added
    on Nov 4, 2026
  3. added a commit that references this issue on Nov 4, 2026
  4. developing-today commented on Nov 4, 2026

    @developing-today
    ContributorAuthor

    Step 1 complete. PR #5446 merged — merge commit f6de75f7d636e937a0beee757c9461d31b967e4e (branch head 3af029618). Both CI checks green (production line limit, proxy port fallbacks).

    What landed

    • pkgs/fleet/ Cargo workspace (own Cargo.lock + rust-toolchain pin): platform crates fleet-registry (full domain registry compiled into every variant), fleet-config, fleet-secrets (by-name resolution: session broker first, bws fallback; values never in code/tests/errors/logs), fleet-proxy-proto (4-byte BE length + JSON frames, hello/capability shapes, major window N/N−1), and the fleet bin crate: multicall dispatch, capability stubs, version, capabilities, full-registry --help.
    • Surface = compiled features ∩ invocation-name profile ∩ config. Refinement (A) narrowing implemented and tested both directions (a hyphen name narrows, never widens). All four stub cases exit 69 with distinguishing wording (not-in-build per §3, narrowed-by-name, disabled-by-config, included-but-unimplemented).
    • Root flake attrs via make-fleet (lib/default.nix + one merge line in flake.nix): packages.fleet, packages.fleet-serve, packages.fleet-connect, packages.fleet-connect-static (Linux only). Every package installs bin/fleet; hyphen variants add the alias symlink.

    D7 sizes (nix artifacts, final stripped)

    variant flavor bytes
    fleet dynamic 533,880
    fleet-serve dynamic 533,880
    fleet-connect dynamic 529,768
    fleet-connect-static musl static-pie 640,208

    Connect gate ≤ 2 MiB (target ≤ 1.5 MiB): both flavors pass with >2.5× headroom; the gate is enforced in default.nix postFixup (build logs show the measured size) and re-asserted in smoke.sh. Trap recorded in the PR: nixpkgs fixup strips debug-only (-S), so the package strips fully itself, by-path binutils.

    Verification

    • cargo test --workspace: 22 pass; clippy clean; fmt applied. Each nix package also runs the suite in its check phase.
    • pkgs/fleet/smoke.sh on the four nix outputs: 36 passed, 0 failed — full-registry help with correct marks per variant, exact version capability sets, 69-stubs via subcommand + argv0 alias + hyphen name, name-narrowing on the full build invoked as fleet-connect, config-disabled wording, env -i runs of both connect flavors.
    • Static flavor in a FROM scratch container (binary only): version prints the connect set; queue stubs at 69 with the §3 wording.
    • No live installs, units, PATH changes or flips — packages only, as scoped.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/infraInfrastructure, deployment, and operationseffort/mMedium: expected under 1 day of workkind/enhancementmeta/enrichedIntake review done: acceptance criteria, links, and normalized labels addedpriority/normalOrdinary priority (the default)status/needs-triageNot yet triaged; needs a first look

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions