Skip to content

[architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element #154

Closed

Description

@hivecommons-hive

Architecture Finding

Type: tech-debt / interface-violation (documented contract not backed by the build graph)
Affected area: files/bin/, elements/bluefin-server/os-stack.bst, docs/skills/system-containers.md, tests/unit/system-container_test.bats

Everything else under files/ is image payload that some element stages with a
kind: local source. The complete staged set today is:

element path:
elements/bluefin-server/os-creds-prov.bst files/os/sysusers.d
elements/bluefin-server/os-issue.bst files/os/issue.d
elements/bluefin-server/os-justfile.bst files/os/justfile
elements/bluefin-server/os-k0s-first-boot.bst files/os/systemd/system
elements/bluefin-server/os-k0s-sysupdate.bst files/os/sysupdate.k0s.d
elements/bluefin-server/os-kured-hook.bst files/os/systemd/systemd-sysupdate.service.d
elements/bluefin-server/os-networkd.bst files/os/systemd/network
elements/bluefin-server/os-sshd-config.bst files/os/ssh
elements/bluefin-server/os-sshd-preset.bst files/os/systemd/system-preset
elements/bluefin-server/os-sysupdate-keys.bst files/os/sysupdate-keys
elements/bluefin-server/os-sysupdate.bst files/os/sysupdate.d
elements/installer/installer-repart.bst files/installer/repart.d
elements/oci/k0s-sysext.bst files/k0s/sysext, files/k0s/manifests, files/k0s/kiosk, files/k0s/kubeflex, files/os/issue.d/40-kubestellar.issue

files/bin/ appears nowhere in that table. No element has a kind: local
source pointing at it, so nothing under files/bin/ reaches
oci/bluefin-server-ddi.bst, oci/bluefin-server-installer.bst, or
oci/k0s-sysext.bst.

Two files live there, and they are not the same kind of thing:

  • files/bin/bluefin-kubestellar — host-side developer CLI, executed from the
    repository checkout by Justfile (install-vm, line 544) and
    scripts/lima-e2e-kubestellar-test.sh. Correctly not image payload.
  • files/bin/system-container — claims to be image payload.
    docs/skills/system-containers.md states the helper is
    "/usr/bin/system-container ... shipped in the OS image" (line 18) and
    "The OS image ships a small helper at /usr/bin/system-container" (line 38),
    and documents sudo system-container start <name> as the operator-facing
    lifecycle. AGENTS.md line 65 routes operators to that skill.
    Nothing installs it. On a real DDI, /usr/bin/system-container does not exist.

The failure is silent in every gate we have:

  • tests/unit/system-container_test.bats executes the script straight out of
    the repo, so it passes whether or not the script ships.
  • The skills own acceptance checklist (docs/skills/system-containers.md
    line 100) only asserts files/bin/system-container exists in the repo.
  • .github/scripts/docs-checks.py validates front-matter, budgets, and link
    targets — it has no notion of whether a documented binary is staged.
  • just validate only runs bst show --deps all on the three OCI targets;
    an unreferenced source directory is invisible to it.

Impact

  • A documented, tested, operator-facing command is absent from the shipped OS.
    The first person to follow docs/skills/system-containers.md on real
    hardware gets system-container: command not found, after the docs gate,
    the unit suite, and the build all reported green.
  • The files/ tree has no stated rule separating image payload from host-side
    tooling, so the next helper dropped into files/bin/ inherits the same fate
    with no signal.
  • Any future rename of a staged directory (e.g. files/os/ssh) silently
    removes payload from the image: the path: in the element becomes stale and
    nothing cross-checks the two sides.

Recommendation

  1. Make the payload rule explicit and enforced: every path under files/ is
    either staged by an element kind: local source or is declared host-side
    tooling. A drift gate in tests/unit/ can assert this from the element
    graph, and can also assert the reverse direction — that every declared
    path: still exists on disk.
  2. Decide system-containers side of that line. Either stage it (an import
    element under elements/bluefin-server/ added to os-stack.bst, which is a
    behaviour change and belongs to a maintainer, not to this agent) or correct
    docs/skills/system-containers.md to stop promising a binary the image does
    not carry.

A follow-up PR adds (1) only — the gate, with files/bin/system-container
recorded as the single known waiver so the gate passes today and fails the
moment a second orphan appears. (2) is deliberately left to maintainers.


Filed by architect agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: architect | Instance: hosted-projectbluefin-knuckle-gjvq | SHA: 4c1e7a7

— hive: agent=architect backend=copilot model=claude-opus-5

Activity

  1. castrojo commented on Sep 20, 2026

    @castrojo
    Contributor

    The detection half landed in #155 — tests/unit/test_files_payload_reachability.py now fails on any new orphan under files/, with files/bin/system-container recorded as the single shrink-only waiver citing this issue.

    Verified against the Kubernetes cutover branch (#210) as well: the new files/cluster/**, files/kubernetes/** and files/os/libexec/** payload is all staged, so the waiver list stays at one entry.

    This issue stays open for the decision it actually asks for: does system-container ship (stage it from an element), or is docs/skills/system-containers.md wrong about /usr/bin/system-container? That is a maintainer call, not a test.

  2. hivecommons-hive commented on Sep 20, 2026

    @hivecommons-hive
    ContributorAuthor

    A merged PR referenced this issue without closing it. Carrying the remainder back here so the issue timeline shows what is still open.

    Remainder from the PR body:

    rather than closing it.

    This comment is edited in place by the task-list sweep on every cycle; it is not duplicated.

  3. repires commented on Sep 23, 2026

    @repires

    The actionable drift gate for this finding was merged in PR #155 (commit afea1e7), adding tests/unit/test_files_payload_reachability.py with files/bin/system-container recorded as the single shrink-only waiver citing this issue.

    As noted by @castrojo, all actionable automated verification has landed, and the issue remains open awaiting a maintainer product decision on whether to stage system-container into the OS image via an import element or amend docs/skills/system-containers.md to remove the reference to /usr/bin/system-container. No further agent code changes are actionable without that decision.

    — hive: backend=agy

    🐝 Hive Agent: contributor | SHA: unknown

  4. added
    hive/covered-by-prHive verified that an open PR references or claims this issue; still actionable until confirmed
    on Sep 29, 2026
  5. added a commit that references this issue on Sep 29, 2026
    32db0ec
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

    agent/architectFiled or owned by the architect agent.hive/covered-by-prHive verified that an open PR references or claims this issue; still actionable until confirmed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions