Skip to content

feat(0.4.48): owner-anchored shim dispatch (owner -> env -> default)#316

Merged
Sunrisepeak merged 1 commit into
mainfrom
feat/shim-owner-anchoring
Jun 4, 2026
Merged

feat(0.4.48): owner-anchored shim dispatch (owner -> env -> default)#316
Sunrisepeak merged 1 commit into
mainfrom
feat/shim-owner-anchoring

Conversation

@Sunrisepeak
Copy link
Copy Markdown
Member

What

A shim is an artifact of exactly one home. Dispatch now resolves against the home that owns the shim file first, instead of trusting ambient XLINGS_HOME:

shim dispatch home: owner home (exe-anchored) -> env XLINGS_HOME (deprecated, warns) -> ~/.xlings
  • XLINGS_HOME keeps exactly one meaning: the management target of the xlings CLI (install/update). CLI home resolution is untouched.
  • XLINGS_SHIM_ANCHOR=legacy restores pre-0.4.48 env-first dispatch (release insurance, one soak cycle).
  • Design + impact analysis: .agents/docs/2026-06-04-shim-owner-anchoring-design.md (updated to as-landed state in this PR).

Why

Any process tree that redirects XLINGS_HOME (e.g. mcpp's vendored registry sandbox) silently broke every shim-resolved tool on PATH — git, python, node… The git shim failing inside mcpp's environment deadlocked package-index sync (index needs git, git bootstrap needs index) and left Windows users with mcpp build / mcpp self init --force permanently failing while their terminal git --version worked fine. Reproduced end-to-end in mcpp-community/mcpp#114; probe:

XLINGS_HOME=~/.xlings        git --version -> git version 2.51.0.windows.2
XLINGS_HOME=~/.mcpp/registry git --version -> [error] xlings: 'git' is not installed

Changes

  • src/core/xvm/shim.cppmis_home_root (structural signature: .xlings.json + bin/xlings + subos/), resolve_owner_home (innermost-home upward walk), home_knows_program (lightweight versions-DB probe, no Config involvement), resolve_dispatch_home (the chain, legacy mode, deprecation/ambiguity warnings)
  • src/core/config.cppmConfig::override_home() pre-init hook; ctor honors it ahead of env/self-contained; version 0.4.48
  • src/main.cpp — run the chain for shim invocations before first Config use
  • src/core/xself/doctor.cppm — check 2.6 shim anchor (warning-only; scoped to binDirs physically inside the home so project-subos binDirs don't false-positive)
  • tests/unit/test_shim_anchor.cpp — 14 tests: home-root signature, owner walk (incl. nested innermost + orphan), DB probe, chain ordering
  • tests/e2e/shim_owner_anchoring_test.sh — owner-wins + warning / deprecated borrowing + warning / legacy mode / redirected-env (mcpp) regression; registered in linux + macos CI

Behavior changes

Only one: when both the owner home and the env home have the tool, the owner now wins (previously env won) — with a visible ambiguity warning. Borrowing (tool only in env home) still works, with a deprecation warning. Everything else is unchanged or was previously a hard error.

Verification

A shim is an artifact of exactly one home: dispatch now resolves against
the home that owns the shim file first, instead of trusting ambient
XLINGS_HOME. env XLINGS_HOME stays as a deprecated lower-priority
fallback (borrowing) for one transition window, with a visible warning;
~/.xlings covers orphan shims. XLINGS_SHIM_ANCHOR=legacy restores the
pre-0.4.48 env-first behavior as release insurance.

Fixes the embedder-redirect failure class: a process tree that redirects
XLINGS_HOME (e.g. mcpp's vendored registry) broke every shim-resolved
tool on PATH (git, python, ...) -> package-index sync deadlocked ->
'no package index'. Reproduced end-to-end in mcpp-community/mcpp PR #114.

- src/core/xvm/shim.cppm: is_home_root (structural signature),
  resolve_owner_home (innermost-home walk), home_knows_program
  (lightweight DB probe), resolve_dispatch_home (the chain + warnings)
- src/core/config.cppm: Config::override_home pre-init hook; bump 0.4.48
- src/main.cpp: run the chain for shim invocations before first Config use
- src/core/xself/doctor.cppm: check 2.6 'shim anchor' (warning-only,
  scoped to binDirs inside the home)
- tests: unit suite (14 tests) + e2e scenario test, registered in
  linux/macos CI
- design doc: .agents/docs/2026-06-04-shim-owner-anchoring-design.md
  updated to as-landed state
@Sunrisepeak Sunrisepeak merged commit a4b474b into main Jun 4, 2026
3 of 5 checks passed
@Sunrisepeak Sunrisepeak deleted the feat/shim-owner-anchoring branch June 4, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant