Skip to content

Rule star's session-root anchor #571

Open

Description

@David-Noble-at-work

Design question, split out of #568 step 3, where deleting the unconfined fsroot variant forced star's
session root to name an anchor for the first time.

The question

star builds its runtime environment with the session root at the working directory, unconfined
(cmd/star/star/application.go). With one confinement behaviour, that root must anchor somewhere — and the
choice encodes what star is. Star's charter pulls in two directions: "extensible build tool that operates
anywhere" wants the widest address space; the hermeticity direction (#563, module subsets) wants the narrowest
one the script declares.

A hard constraint either way: star must read and write the XDG trees, and XDG locations are only
conventionally under home — XDG_CONFIG_HOME/XDG_STATE_HOME overrides can point anywhere, so every fixed
anchor except the filesystem root can be escaped by a legitimate XDG configuration.

Candidates

  1. Current directory — what make/go build/bazel mean by context, and the narrowest. Fails: XDG
    unreachable; invoked from a subdirectory it cannot see the repo root; any "read a file from over there"
    script breaks.
  2. Repository root — the better build-tool mental model. Fails: XDG still unreachable; undefined outside a
    repo, so a fallback rule reintroduces the whole question one level down.
  3. Home — covers default XDG and most working trees. Fails: confinement theater — nearly everything the
    user owns is under home — while still breaking repos in /srv or /opt, XDG overrides outside home, and a
    Windows working tree on a different volume than the profile.
  4. Multiple roots — a work root (cwd or repo) plus XDG trees opened separately; roots as declared
    capabilities, the same shape as Every runtime loads every module, so planning can call file and platform immediately #563's module subset. The design already endorses it ("cross-tree work wants
    two confined roots rather than one granting unbounded reads"), and devlore's own config/state/cache access
    already flows through dedicated roots (cli.OpenTree at the XDG anchors), not the session root. Fails only
    in cost: the runtime environment mints exactly one root today, so this is a design effort, not an edit.

Interim (shipped with #568 step 3) — REVISED

Star anchors at the working directory, confined. The volume-root interim originally recorded here was
tried and failed: star scripts resolve relative paths against the session root's anchor, so a volume
anchor silently redefined every relative path in every script — the generator's go.mod walk
(compute_provider_import in generate.star) broke immediately. "Preserves today's behaviour" was true only of
absolute paths.

wd-confined preserves relative-path semantics — the dominant use; the entire generator toolchain — and drops
only unconfined absolute access, which no current star extension exercises (verified: no absolute filesystem
paths, no XDG references in star/extensions). Residuals accepted until this issue is ruled: XDG trees are
unreachable through the session root, and star invoked from a subdirectory cannot see the repository root —
both listed under candidate 1 above.

Where this must be answered

No later than #563's hermeticity design. If roots become declared capabilities there, this question dissolves
into it — option 4 is that design. Until then the volume-root interim holds, unless a Windows cross-volume
star use case forces it earlier.

Activity

  1. David-Noble-at-work commented on Aug 20, 2026

    @David-Noble-at-work
    ContributorAuthor

    The Interim section is revised in place: the volume anchor shipped for less than one gate run. Star scripts
    resolve relative paths against the root's anchor, so anchoring at / broke the generator's go.mod walk on the
    first make build. The interim is now wd, confined — relative semantics preserved, unconfined absolute
    access dropped (nothing in star/extensions uses it). The candidates and the forcing points are unchanged.

  2. David-Noble-at-work commented on Aug 20, 2026

    @David-Noble-at-work
    ContributorAuthor

    Second forcing data point: star has real cross-root consumers, today

    The wd-confined interim's justification said no current consumer addresses paths outside the working
    directory. CI falsified it on the first run after #573: the knowledge-extract workflow runs
    star devlore knowledge extract --target ../devlore-registry — a sibling tree — and failed with
    statat ../devlore-registry: path escapes from parent.

    It is not just the workflow. The Knowledge extension's own argument defaults are cross-root by design:
    _find_sibling("devlore-cli") and _find_sibling("devlore-registry") resolve ../<name> when --source /
    --target are omitted (extract.star:49–55, 76).

    The immediate fix (rides with #573) constrains the scenario — the registry is checked out inside the cli
    tree so the target lands inside star's root. Ruled by the user 2026-08-20: that is the wrong long-term
    direction — star should accommodate working across roots, not constrain it.
    This strengthens candidate 4
    (declared roots): a session that names both a source root and a target root is exactly this workflow's shape.

  3. David-Noble-at-work commented on Aug 21, 2026

    @David-Noble-at-work
    ContributorAuthor

    Cross-reference: candidate 4 here (multiple roots as declared capabilities) is now its own design question under #546 — #597, "the RuntimeEnvironment holds a named set of roots — (root-name, rel) identity", forced concretely by the writ-installs-package scenario. A ruling there dissolves this question's residuals (XDG unreachable through the session root; subdirectory invocation).

  4. David-Noble-at-work commented on Oct 3, 2026

    @David-Noble-at-work
    ContributorAuthor

    Lane 44 of #916, the writ lifecycle schedule, recorded 2026-10-03: PR C closes this issue with #597 (lane 33), whose named-roots design answers it. PR C's close named it on 2026-10-02, but the schedule had no row for it.

  5. added a commit that references this issue on Oct 4, 2026
    128f352
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

    Epic:ExecutionGraphThe execution graph epictaskImplementation work item

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions