plum

# Cross-File Import Resolution Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make `import <path>` actually resolve to a file on disk and merge its declarations into the compiling program, so files split across `libs/std/*.plum` can reference each other.

**Architecture:** Add a `load_and_merge(entry, lib_path)` loader in `plum-core` that recursively resolves and parses `import` targets (tracking visited files so diamond imports and cycles both resolve cleanly) and merges every reachable file's items into one `ast::Source`, erroring on duplicate top-level names. `plum-checker::check_source` and `plum_wasm_codegen::compile_source` are completely unchanged — they only ever see the one merged `Source`. `plum-cli`'s `compile` subcommand routes through the loader and gains a `--lib-path` flag.

**Tech Stack:** Rust, tree-sitter (parsing, unchanged), std::fs/std::path for file resolution. No grammar changes — `import <path>` already parses into `ast::Import { path }`.

## Global Constraints

- Spec: `docs/superpowers/specs/2026-07-23-cross-file-imports-design.md`
- `import std/option` resolves to `<lib-path>/std/option.plum`. `--lib-path` defaults to `./libs` (relative to CWD).
- In scope: transitive imports, diamond imports (no duplication), import cycles (resolve without hanging or erroring), a clear error for an unresolvable import path, a clear error for two files declaring the same top-level name.
- Out of scope: selective/aliased imports, a package manager/registry, fixing OTHER `libs/std/*.plum` files' pre-existing broken `import` lines (e.g. `http.plum`'s `import std/path`), any new semantics for `module <name>`.
- **Known, deliberately accepted scope boundary**: the real `libs/std/list.plum` does NOT fully type-check standalone even after this plan — its `join` method calls `Buffer()`, which is declared nowhere in this repo, and `plum-checker` doesn't process `Item::Trait` at all (no trait-bounded dispatch). Both are separate, unscoped gaps. This plan proves the *loader mechanism* with small fixture files, not with the real, currently-broken `list.plum`.
- Run `cargo build --workspace` and `cargo test --workspace` after every task that touches Rust code — all pre-existing tests must keep passing throughout.

---

### Task 1: `plum-core` — `load_and_merge` loader

**Files:**
- Create: `plum-core/src/loader.rs`
- Modify: `plum-core/src/lib.rs` (export the new module)
- Modify: `plum-core/Cargo.toml` (add a dev-dependency for on-disk test fixtures)
- Test: `plum-core/tests/loader_test.rs`

**Interfaces:**
- Consumes: `crate::ast::{Source, Item, Import}` (existing), `crate::parser::AstParser` (existing), `tree_sitter`/`tree_sitter_plum` (existing dependencies of this crate).
- Produces: `pub fn load_and_merge(entry: &std::path::Path, lib_path: &std::path::Path) -> Result<ast::Source, String>`. Task 2 (`plum-cli`) calls this directly; Task 3's test also calls it.

- [ ] **Step 1: Add the `tempfile` dev-dependency**

`plum-core/Cargo.toml` currently has no `[dev-dependencies]` section. Add one:

```toml
[dev-dependencies]
tempfile = "3"
```

- [ ] **Step 2: Write the failing loader tests**

Create `plum-core/tests/loader_test.rs`:

```rust
use plum_core::load_and_merge;
use std::fs;
use tempfile::TempDir;

/// Writes `name` (without a directory prefix — always placed directly under
/// the temp dir's `lib_path` subdirectory) with `contents`, creating parent
/// directories as needed (so `"std/option"` works).
fn write_lib_file(lib_path: &std::path::Path, name: &str, contents: &str) -> std::path::PathBuf {
    let path = lib_path.join(format!("{}.plum", name));
    fs::create_dir_all(path.parent().unwrap()).unwrap();
    fs::write(&path, contents).unwrap();
    path
}

#[test]
fn import_sees_imported_declarations() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "helper", "module fixtures\n\nhelperFn() -> Int =\n  42\n");
    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport helper\n\nmain() -> Int =\n  helperFn()\n");

    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
        _ => None,
    }).collect();
    assert!(names.contains(&"main"), "expected 'main' in merged items, got {:?}", names);
    assert!(names.contains(&"helperFn"), "expected 'helperFn' in merged items, got {:?}", names);
}

#[test]
fn transitive_import_surfaces_grandchild_declarations() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "c", "module fixtures\n\ncFn() -> Int =\n  3\n");
    write_lib_file(&lib_path, "b", "module fixtures\n\nimport c\n\nbFn() -> Int =\n  cFn()\n");
    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\n\nmain() -> Int =\n  bFn()\n");

    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
        _ => None,
    }).collect();
    assert!(names.contains(&"cFn"), "expected transitively-imported 'cFn', got {:?}", names);
}

#[test]
fn diamond_import_includes_shared_dependency_once() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "d", "module fixtures\n\ndFn() -> Int =\n  4\n");
    write_lib_file(&lib_path, "b", "module fixtures\n\nimport d\n\nbFn() -> Int =\n  dFn()\n");
    write_lib_file(&lib_path, "c", "module fixtures\n\nimport d\n\ncFn() -> Int =\n  dFn()\n");
    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\nimport c\n\nmain() -> Int =\n  bFn() + cFn()\n");

    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
    let d_count = merged.items.iter().filter(|i| matches!(i, plum_core::ast::Item::Fn(f) if f.name == "dFn")).count();
    assert_eq!(d_count, 1, "expected 'dFn' exactly once in a diamond import, got {}", d_count);
}

#[test]
fn import_cycle_resolves_without_hanging_or_erroring() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "b", "module fixtures\n\nimport a\n\nbFn() -> Int =\n  1\n");
    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\n\nmain() -> Int =\n  bFn()\n");

    let merged = load_and_merge(&entry, &lib_path).expect("import cycle should resolve, not error");
    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
        _ => None,
    }).collect();
    assert!(names.contains(&"main"));
    assert!(names.contains(&"bFn"));
}

#[test]
fn unresolvable_import_is_a_clear_error() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport does_not_exist\n\nmain() -> Int =\n  0\n");

    let result = load_and_merge(&entry, &lib_path);
    assert!(result.is_err());
    let msg = result.unwrap_err();
    assert!(msg.contains("does_not_exist"), "expected error to name the missing import, got: {}", msg);
}

#[test]
fn duplicate_top_level_name_across_files_is_a_clear_error() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "helper", "module fixtures\n\nsharedFn() -> Int =\n  1\n");
    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport helper\n\nsharedFn() -> Int =\n  2\n");

    let result = load_and_merge(&entry, &lib_path);
    assert!(result.is_err());
    let msg = result.unwrap_err();
    assert!(msg.contains("sharedFn"), "expected error to name the duplicate 'sharedFn', got: {}", msg);
}

#[test]
fn same_method_name_on_different_receivers_across_files_is_not_a_collision() {
    let dir = TempDir::new().unwrap();
    let lib_path = dir.path().join("libs");
    write_lib_file(&lib_path, "cat", "\
module fixtures

type Cat =
  age: Int

length<Cat>(self) -> Int =
  self.age
");
    let entry = write_lib_file(&lib_path, "main", "\
module fixtures

import cat

type Box =
  items: Int

length<Box>(self) -> Int =
  self.items

main() -> Int =
  0
");

    let merged = load_and_merge(&entry, &lib_path).expect("same method name on different receivers should not collide");
    let method_count = merged.items.iter().filter(|i| matches!(i, plum_core::ast::Item::Fn(f) if f.name == "length")).count();
    assert_eq!(method_count, 2, "expected both 'length' methods to survive the merge, got {}", method_count);
}
```

- [ ] **Step 3: Run the tests to verify they fail**

Run: `cargo test -p plum-core --test loader_test 2>&1 | tail -60`
Expected: FAIL to compile — `plum_core::load_and_merge` doesn't exist yet.

- [ ] **Step 4: Implement `plum-core/src/loader.rs`**

```rust
use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};

use crate::ast::{Import, Item, Source};
use crate::parser::AstParser;

/// Resolves `entry`'s `import` statements (transitively, and tolerating
/// diamond imports and cycles) against `lib_path`, and merges every reachable
/// file's top-level items into a single `Source`. The result's `module` and
/// `imports` fields are `entry`'s own (imported files' `module`/`imports`
/// fields are not otherwise used once their `items` have been merged in) —
/// only `items` accumulates across files.
///
/// `import "std/option"` resolves to `<lib_path>/std/option.plum`.
pub fn load_and_merge(entry: &Path, lib_path: &Path) -> Result<Source, String> {
    let entry_canon = std::fs::canonicalize(entry)
        .map_err(|e| format!("cannot read entry file '{}': {}", entry.display(), e))?;
    let entry_source = parse_file(&entry_canon)?;

    let mut visited: HashSet<PathBuf> = HashSet::new();
    let mut items: Vec<Item> = Vec::new();
    let mut names: HashMap<String, PathBuf> = HashMap::new();

    visited.insert(entry_canon.clone());
    merge_items(&entry_canon, &entry_source, &mut items, &mut names)?;
    for import in &entry_source.imports {
        load_import(import, lib_path, &mut visited, &mut items, &mut names)?;
    }

    Ok(Source {
        module: entry_source.module,
        imports: entry_source.imports,
        items,
    })
}

fn load_import(
    import: &Import,
    lib_path: &Path,
    visited: &mut HashSet<PathBuf>,
    items: &mut Vec<Item>,
    names: &mut HashMap<String, PathBuf>,
) -> Result<(), String> {
    let target = lib_path.join(format!("{}.plum", import.path));
    let target_canon = std::fs::canonicalize(&target)
        .map_err(|_| format!("import '{}': no such file '{}'", import.path, target.display()))?;

    if !visited.insert(target_canon.clone()) {
        // Already loaded — a diamond import or a cycle. Either way, its items
        // are already in `items`; nothing more to do.
        return Ok(());
    }

    let source = parse_file(&target_canon)?;
    merge_items(&target_canon, &source, items, names)?;
    for nested in &source.imports {
        load_import(nested, lib_path, visited, items, names)?;
    }
    Ok(())
}

fn parse_file(path: &Path) -> Result<Source, String> {
    let text = std::fs::read_to_string(path)
        .map_err(|e| format!("cannot read '{}': {}", path.display(), e))?;
    let mut parser = tree_sitter::Parser::new();
    parser
        .set_language(&tree_sitter_plum::LANGUAGE.into())
        .map_err(|e| format!("language error: {}", e))?;
    let tree = parser
        .parse(&text, None)
        .ok_or_else(|| format!("parse failed for '{}'", path.display()))?;
    let ap = AstParser::new(&text);
    Ok(ap.parse_source(tree.root_node()))
}

fn merge_items(
    file: &Path,
    source: &Source,
    items: &mut Vec<Item>,
    names: &mut HashMap<String, PathBuf>,
) -> Result<(), String> {
    for item in &source.items {
        let key = item_name_key(item);
        if let Some(existing_file) = names.get(&key) {
            return Err(format!(
                "duplicate declaration '{}': declared in both '{}' and '{}'",
                key,
                existing_file.display(),
                file.display()
            ));
        }
        names.insert(key, file.to_path_buf());
        items.push(item.clone());
    }
    Ok(())
}

/// A collision key that mirrors `plum-checker`'s own separation of
/// namespaces: methods are keyed by `(receiver, name)` (so `length<Cat>` and
/// `length<Box>` never collide, exactly like `plum_checker::MethodEnv`),
/// while classes/traits/enums/consts/free-functions are each their own
/// flat, kind-qualified namespace.
fn item_name_key(item: &Item) -> String {
    match item {
        Item::Class(c) => format!("class::{}", c.name),
        Item::Trait(t) => format!("trait::{}", t.name),
        Item::Enum(e) => format!("enum::{}", e.name),
        Item::Const(c) => format!("const::{}", c.name),
        Item::Fn(f) => match &f.type_param {
            Some(recv) => format!("method::{}::{}", recv, f.name),
            None => format!("fn::{}", f.name),
        },
    }
}
```

- [ ] **Step 5: Export the new module**

In `plum-core/src/lib.rs`, replace:

```rust
pub mod ast;
pub mod parser;
pub mod formatter;

pub use formatter::{format_source, format_source_with_opts, FormatterError};
pub use parser::AstParser;
```

with:

```rust
pub mod ast;
pub mod parser;
pub mod formatter;
pub mod loader;

pub use formatter::{format_source, format_source_with_opts, FormatterError};
pub use parser::AstParser;
pub use loader::load_and_merge;
```

- [ ] **Step 6: Run the tests to verify they pass**

Run: `cargo test -p plum-core --test loader_test 2>&1 | tail -80`
Expected: all 7 tests PASS.

- [ ] **Step 7: Run the full workspace test suite**

Run: `cargo test --workspace 2>&1 | tail -100`
Expected: all pre-existing tests still PASS (this task only adds a new module and a new dev-dependency; nothing existing is touched).

- [ ] **Step 8: Commit**

```bash
git add plum-core/src/loader.rs plum-core/src/lib.rs plum-core/Cargo.toml plum-core/tests/loader_test.rs Cargo.lock
git commit -m "feat(plum-core): add load_and_merge cross-file import loader"
```

---

### Task 2: `plum-cli` — `--lib-path` and loader integration

**Files:**
- Modify: `plum-cli/src/main.rs` (`Command::Compile` variant, `cmd_compile`)
- Test: `plum-cli/tests/compile_tests.rs`
- Test fixtures: `test/import_fixtures/helper.plum`, `test/import_fixtures/main.plum` (new)

**Interfaces:**
- Consumes: `plum_core::load_and_merge(entry: &Path, lib_path: &Path) -> Result<ast::Source, String>` (Task 1).
- Produces: `plum compile <file> --lib-path <dir>` resolves imports. No new public Rust functions (this is the CLI's own binary entry point).

- [ ] **Step 1: Write the failing CLI integration test and its fixtures**

Create `test/import_fixtures/helper.plum`:

```
module fixtures

helperValue() -> Int =
  42
```

Create `test/import_fixtures/main.plum`:

```
module fixtures

import helper

main() -> Int =
  helperValue()
```

Add to `plum-cli/tests/compile_tests.rs` (this file already has a `plum_bin()` helper — reuse it, don't redefine it):

```rust
#[test]
fn compile_with_import_resolves_via_lib_path() {
    let src_path = concat!(env!("CARGO_MANIFEST_DIR"), "/../test/import_fixtures/main.plum");
    let lib_path = concat!(env!("CARGO_MANIFEST_DIR"), "/../test/import_fixtures");
    let out_path = std::env::temp_dir().join(format!("plum_test_import_{}.wasm", std::process::id()));
    let out_path_str = out_path.to_str().unwrap();
    let status = Command::new(plum_bin())
        .args(["compile", src_path, "--lib-path", lib_path, "-o", out_path_str])
        .status()
        .expect("failed to run plum compile");
    assert!(status.success(), "plum compile exited with: {}", status);
    let bytes = std::fs::read(out_path).expect("output wasm not found");
    assert_eq!(&bytes[0..4], b"\0asm");
}
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `cargo test -p plum-cli compile_with_import_resolves_via_lib_path 2>&1 | tail -40`
Expected: FAIL — `--lib-path` isn't a recognized flag yet (clap error), or (if you haven't rebuilt) the import is silently dropped and `helperValue` is undefined, producing a type-check error.

- [ ] **Step 3: Add `--lib-path` and route `cmd_compile` through the loader**

In `plum-cli/src/main.rs`, the `Compile` variant currently reads:

```rust
    /// Compile a Plum source file to WASM
    Compile {
        /// Source file to compile
        file: std::path::PathBuf,
        /// Output path (default: input with .wasm extension)
        #[arg(short, long)]
        output: Option<std::path::PathBuf>,
    },
```

Replace it with:

```rust
    /// Compile a Plum source file to WASM
    Compile {
        /// Source file to compile
        file: std::path::PathBuf,
        /// Output path (default: input with .wasm extension)
        #[arg(short, long)]
        output: Option<std::path::PathBuf>,
        /// Root directory `import <path>` is resolved against (`import std/x` -> `<lib-path>/std/x.plum`)
        #[arg(long, default_value = "libs")]
        lib_path: std::path::PathBuf,
    },
```

The dispatch in `run()` currently reads:

```rust
        Command::Compile { file, output } => cmd_compile(file, output),
```

Replace with:

```rust
        Command::Compile { file, output, lib_path } => cmd_compile(file, output, lib_path),
```

`cmd_compile` currently reads (~line 106-137):

```rust
fn cmd_compile(file: std::path::PathBuf, output: Option<std::path::PathBuf>) -> Result<()> {
    let source = fs::read_to_string(&file)
        .with_context(|| format!("failed to read {}", file.display()))?;

    // Parse
    let mut parser = tree_sitter::Parser::new();
    parser
        .set_language(&tree_sitter_plum::LANGUAGE.into())
        .map_err(|e| anyhow::anyhow!("language error: {e}"))?;
    let tree = parser
        .parse(&source, None)
        .ok_or_else(|| anyhow::anyhow!("parse failed"))?;
    let ap = AstParser::new(&source);
    let ast = ap.parse_source(tree.root_node());

    // Type check
    if let Err(errors) = plum_checker::check_source(&ast) {
        for e in &errors {
            eprintln!("type error: {}", e.message);
        }
        process::exit(1);
    }

    // Codegen
    let wasm_bytes = plum_wasm_codegen::compile_source(&ast)
        .map_err(|e| anyhow::anyhow!("codegen error: {e}"))?;

    // Write output
    let out_path = output.unwrap_or_else(|| file.with_extension("wasm"));
    fs::write(&out_path, &wasm_bytes)
        .with_context(|| format!("failed to write {}", out_path.display()))?;
```

Replace the parse block (everything from `let source = fs::read_to_string...` through `let ast = ap.parse_source(tree.root_node());`) with a single call to the loader, and add the new `lib_path` parameter:

```rust
fn cmd_compile(
    file: std::path::PathBuf,
    output: Option<std::path::PathBuf>,
    lib_path: std::path::PathBuf,
) -> Result<()> {
    let ast = plum_core::load_and_merge(&file, &lib_path)
        .map_err(|e| anyhow::anyhow!("{e}"))?;

    // Type check
    if let Err(errors) = plum_checker::check_source(&ast) {
        for e in &errors {
            eprintln!("type error: {}", e.message);
        }
        process::exit(1);
    }

    // Codegen
    let wasm_bytes = plum_wasm_codegen::compile_source(&ast)
        .map_err(|e| anyhow::anyhow!("codegen error: {e}"))?;

    // Write output
    let out_path = output.unwrap_or_else(|| file.with_extension("wasm"));
    fs::write(&out_path, &wasm_bytes)
        .with_context(|| format!("failed to write {}", out_path.display()))?;
```

(Leave the rest of the function — whatever follows the `fs::write` call — unchanged.)

`AstParser`, `tree_sitter::Parser`, and `tree_sitter_plum::LANGUAGE` are used in `plum-cli/src/main.rs` ONLY inside the block you just replaced in `cmd_compile` — `cmd_format` does not use them. After this edit, remove the now-unused `use plum_core::AstParser;` import near the top of the file (~line 9). The `tree_sitter`/`tree_sitter_plum` crates were referenced only via their fully-qualified paths (`tree_sitter::Parser::new()`, `tree_sitter_plum::LANGUAGE`) with no `use` import for them, so there's no `use` line to remove for those — but confirm with `cargo build -p plum-cli 2>&1 | grep -i warning` that no unused-import warning remains after removing the `AstParser` import.

- [ ] **Step 4: Run the test to verify it passes**

Run: `cargo test -p plum-cli compile_with_import_resolves_via_lib_path 2>&1 | tail -40`
Expected: PASS.

- [ ] **Step 5: Run the full plum-cli test suite**

Run: `cargo test -p plum-cli 2>&1 | tail -60`
Expected: all tests PASS, including the pre-existing `compile_simple_add_produces_wasm` (which passes no `--lib-path`, exercising the new flag's default value — `simple_add.plum` has no imports, so the loader trivially returns just that one file, and the default `./libs` never needs to exist for a file with no imports since `load_and_merge` only ever touches `lib_path` when resolving an actual `import`).

- [ ] **Step 6: Run the full workspace test suite**

Run: `cargo test --workspace 2>&1 | tail -100`
Expected: all tests PASS.

- [ ] **Step 7: Commit**

```bash
git add plum-cli/src/main.rs plum-cli/tests/compile_tests.rs test/import_fixtures/
git commit -m "feat(plum-cli): resolve import via --lib-path using the new loader"
```

---

### Task 3: `libs/std/list.plum` — add the missing import

**Files:**
- Modify: `libs/std/list.plum`

**Interfaces:**
- Consumes: nothing new (this task doesn't touch Rust code).
- Produces: nothing new (this is a one-line library fix; Task 2's loader is already fully tested and proven).

- [ ] **Step 1: Add the import line**

In `libs/std/list.plum`, the file currently opens:

```
module std

# A node stores the data in a list and contains pointers to the previous and next sibling nodes
type Node(a) =
```

Change it to:

```
module std

import std/option

# A node stores the data in a list and contains pointers to the previous and next sibling nodes
type Node(a) =
```

- [ ] **Step 2: Confirm no test regresses**

Run: `cargo test --workspace 2>&1 | tail -100`
Expected: all tests PASS (no existing test currently compiles `libs/std/list.plum` at all — this is a one-line fix to a library file that isn't part of the Rust build, so nothing should change). This step exists to catch the unexpected case where something DOES already reference this file's exact text.

- [ ] **Step 3: Commit**

```bash
git add libs/std/list.plum
git commit -m "fix(libs/std): list.plum imports std/option instead of relying on unresolved cross-file references"
```

---

### Task 4: README — close the gap

**Files:**
- Modify: `README.md` (the "Known gaps" section)

**Interfaces:**
- Consumes: nothing.
- Produces: nothing (docs only).

- [ ] **Step 1: Update the Known gaps bullet**

Run: `grep -n "cross-file" README.md` to find the current bullet, which reads along the lines of:

```
- `libs/std`'s actual `List`/`Map` still don't fully compile — there's no cross-file import resolution yet, so a file that references a type/enum declared in a different `libs/std` file won't type-check standalone; separately, `List`'s methods beyond `get`/`length` (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) are still `todo` — variadic parameters (`values: ...a`) now work as a language feature, but wiring these methods up is separate, unstarted work
```

Replace it with:

```
- `libs/std`'s actual `List`/`Map` still don't fully compile — cross-file `import` resolution now works (`import <path>` resolves against `--lib-path`, defaulting to `./libs`), and variadic parameters work, but `List`'s methods beyond `get`/`length` (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) are still `todo`; separately, `List`'s own `join` method (and `Map`) reference a `Buffer` type and trait-bounded dispatch (`Stringable`) that don't exist yet — `plum-checker` doesn't process trait declarations at all currently
```

- [ ] **Step 2: Commit**

```bash
git add README.md
git commit -m "docs: cross-file import resolution is no longer a known gap"
```