Jean-Pierre

Appearance

View Markdown
References035076079D35D43

RFD D61: Root-Qualified Extends Paths ​

Summary ​

This RFD lets an extends entry name the config root its path is resolved against:

toml
extends = [{ root = "workspace", path = "crates/my-project/.jp/config.toml" }]

Today every extends path resolves relative to the directory of the declaring file, so a config file in one root cannot reliably reach a file in another.

Motivation ​

JP resolves the two load-time path mechanisms against different anchors:

MechanismResolved relative to
config_load_pathsthe workspace root
extendsthe directory of the declaring file

That asymmetry is invisible until a user wants a higher-precedence root to pull in a file that lives in the workspace. The concrete case: a second project is developed inside another workspace, in a directory excluded from the repository. Its workspace config lives with it, and the user-workspace config makes it reachable:

toml
# user-workspace config.toml
config_load_paths = ["crates/my-project/.jp/config"]

jp q -c my-project then finds my-project.toml there, and the project's config can be edited in place by the assistant, because it sits inside the workspace.

What that cannot express is a fragment that must load on every invocation rather than on -c my-project. Deferred loading only happens when --cfg names an entry (RFD 079), so an always-on fragment has to come from an implicitly loaded source, and the only non-committed one is the user-workspace config. The user therefore has to inline those settings into the user-workspace config itself, which is:

  • outside the workspace, so the assistant cannot read or edit it;
  • outside version control of any kind, so the settings are unbacked;
  • separated from the rest of the project's config, which lives together in the workspace.

The natural expression is for the user-workspace config to extend the workspace-relative file, but extends cannot address it. Relative paths from $XDG_DATA_HOME/jp/<workspace_id>/ to a checkout are neither stable nor knowable, and ExtendingRelativePath is typed as RelativePathBuf, so an absolute path is not expressible either.

This is an ergonomics gap, not a capability gap ​

The workspace file can be reached today, by symlinking it into the workspace and granting an external = true access rule (RFD 076, RFD D43). Approvals are keyed on (rule_path, canonical_target) with no tool dimension, so a single --mount seeds an approval that every tool's rules then compile against, and a bare mount expands over the whole enabled-local tool set. Once RFD D43 Phase 3 lands (the deferred trust-on-first-use prompt), even that bootstrap disappears: a hand-authored external = true rule prompts once and is remembered.

So this RFD unlocks nothing. It removes indirection: no symlink, no external grant, no approval record, and no per-machine artifact, for what is only JP reading its own config file. The cost of doing nothing is a config layout harder to read and explain than the thing it expresses, not one that is impossible.

Design ​

User-facing configuration ​

extends accepts a third entry form: a table with root and path.

toml
extends = [
    # Unchanged: relative to this file's directory.
    "fragments/tools.toml",

    # Unchanged: relative, with an explicit merge strategy.
    { path = "fragments/model.toml", strategy = "after" },

    # New: resolved against a named config root.
    { root = "workspace", path = "crates/my-project/.jp/config.toml" },
    { root = "workspace", path = "crates/my-project/.jp/config.toml", strategy = "after" },
]

root accepts the implicitly loaded sources named in RFD 079:

rootAnchor
workspacethe workspace root (the directory holding .jp/)
user-workspace$XDG_DATA_HOME/jp/<workspace_id>/
user-globalthe platform user config dir for jp

path stays a relative path; root decides what it is relative to. Omitting root preserves today's behavior exactly, so every existing config file is unaffected.

Type change ​

ExtendingRelativePath gains a variant alongside Path and WithStrategy:

rust
pub enum ExtendingRelativePath {
    Path(RelativePathBuf),
    WithStrategy(RelativePathWithStrategy),
    WithRoot(RelativePathWithRoot),
}

pub struct RelativePathWithRoot {
    pub root: ConfigRoot,
    pub path: RelativePathBuf,
    pub strategy: ExtendingStrategy,
}

ConfigRoot is a ConfigEnum over the three roots above. The enum is #[serde(untagged)] already, so { root, path } is distinguished from { path, strategy } by the presence of root.

Resolution moves from "join onto the declaring file's directory" to "join onto the anchor named by the entry, defaulting to the declaring file's directory". load_config_file_with_extends in jp_config::util is the single place that resolves these paths; it needs the anchor set passed in.

Failure behavior ​

A root that cannot be resolved for the current invocation is an error naming the root and the path, not a silent skip. The workspace root is absent when JP runs outside a workspace, and user-workspace requires a workspace id; both are knowable at resolution time.

A missing file at a resolved root-qualified path follows the existing extends failure behavior (RFD 079) rather than inventing a second rule.

Cycles and depth ​

Root-qualified entries join the same ExtendsStack used for relative entries, so the existing cycle and depth checks cover them. Cycles across roots are now expressible (a workspace file extending a user-workspace file that extends it back) and are caught by the same mechanism, because detection keys on the resolved absolute path.

Drawbacks ​

It widens the reach of implicitly loaded config. Today a user-workspace config can only pull in files near itself. After this change it can pull in arbitrary workspace files, including committed ones. That is the point, but it means a workspace file can become load-bearing for an invocation without appearing in the workspace's own config chain.

Precedence becomes harder to read. A root-qualified entry is merged at the declaring file's position in the order, not its target's. A workspace-rooted file extended from the user-workspace config is therefore merged after the real workspace config, which is the opposite of where its path suggests it sits. The strategy field already exposes this hazard for relative entries; this change makes the surprise more available.

Three roots is a vocabulary the user has to learn for a feature most users will never need. It also hardcodes the current source list: adding a fifth implicit source later means extending the enum.

Alternatives ​

Absolute paths in extends. Changing RelativePathBuf to accept absolute paths is a smaller diff, and would solve the motivating case immediately. It was rejected because it makes config files machine-specific and non-portable, and because the relative-path type is a deliberate constraint that keeps config shareable. A root qualifier keeps paths portable within a role.

Make extends workspace-relative everywhere. Consistent with config_load_paths, and simpler to explain. Rejected as a breaking change to every existing extends directive, for no gain in the common case where a fragment sits next to its parent.

A config_load_paths entry that always loads. An "eager" flag on a search path would also make an in-workspace fragment load unconditionally. Rejected because it conflates two mechanisms: search paths answer "where do I look for named entries", extends answers "what else does this file pull in". Loading eagerly from a search path would make --cfg resolution and implicit loading share a list with per-entry semantics.

Symlink the out-of-workspace file into the workspace. Requires no JP change, and is the recommended interim answer. The fs tools canonicalize paths and reject targets outside the workspace root, so the symlink needs an external = true rule with an approved target (RFD 076, RFD D43). The approval is tool-agnostic, so one --mount covers every tool, and RFD D43 Phase 3 would remove that step as well. Not adopted as the permanent shape because it spends a symlink, an external grant and a trust-on-first-use record on reaching JP's own config file, and because the resulting mount path says nothing about what it points at.

Non-Goals ​

  • Not changing the default resolution of existing extends entries.
  • Not introducing a way to extend a path outside all known roots. Arbitrary absolute paths stay unexpressible.
  • Not changing the implicit source order or precedence rules from RFD 079. This RFD only changes how a path inside an extends entry is anchored.
  • Not addressing cross-workspace config inheritance (a second workspace inheriting a first workspace's personas, skills and tool config). That is a larger question about workspace relationships; this RFD is only about addressing a file.

Risks and Open Questions ​

  • Does root belong on the entry or the list? A per-list default (extends_root = "workspace") would cut repetition when several entries share a root. Per-entry is proposed because mixed lists are the expected case.
  • Interaction with RFD D35. D35 renames extends to loader.extends and introduces { root = "workspace", path = ... } as a source identifier for loader.overrides.extends. This RFD uses the same shape as a locator. The two should share one type and one root enum. Whichever lands second must adopt the other's naming; ideally D35 absorbs this design rather than the two shipping separate vocabularies.
  • Is user-global worth including? It completes the set, but there is no known use for it. Shipping only workspace and user-workspace would be narrower and still solve the motivating case.
  • Precedence surprise. Whether the merge position described under Drawbacks needs a diagnostic (a warning when a workspace-rooted entry is extended from a higher-precedence root) or just documentation.

Implementation Plan ​

Phase 1: type and resolution. Add ConfigRoot and the WithRoot variant to ExtendingRelativePath; thread an anchor set into load_config_file_with_extends; resolve root-qualified entries against it. Existing entries keep the current anchor. Independently mergeable, with unit tests over the resolver.

Phase 2: diagnostics. Errors for an unresolvable root, and the cycle message updated to render root-qualified entries in the form the user wrote. Depends on Phase 1.

Phase 3: documentation. docs/configuration.md and the RFD 079 source table, including the precedence note from Drawbacks. Depends on Phase 1.

No measurable cost implications: resolution happens once per config file per invocation, and the work is a path join.

References ​

  • RFD 079 — config sources and load order; the four implicit sources and the existing extends semantics.
  • RFD D35 — loader namespace and entry-scoped extends overrides; origin of the { root, path } shape.
  • RFD D43 — tool access to external paths via workspace symlinks; the external rule, the approval store, and the deferred Phase 3 prompt that makes the symlink route self-bootstrapping.
  • RFD 035 — multi-root config load path resolution.
  • crates/jp_config/src/types/extending_path.rs — ExtendingRelativePath.
  • crates/jp_config/src/util.rs — load_config_file_with_extends.