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"

```