Porting Starlark to pure Python with Claude

You are porting the Java implementation of the Starlark configuration 
language to pure Python. The Java source lives in this repository, a 
fork of bazelbuild/bazel, at:

    src/main/java/net/starlark/java/         (post-2020)
    src/test/java/net/starlark/java/         (post-2020)

Plus historical paths whose history you may want when grepping with 
git log:

    src/main/java/com/google/devtools/build/lib/syntax/         (pre-2020)
    src/main/java/com/google/devtools/build/lib/skylarkinterface/

You may rewrite this fork's history freely — it's a fork. Be 
aggressive about deleting Bazel-specific code that isn't part of the 
core interpreter. Do NOT include starlarkbuildapi, depset, 
ctx.actions, select, BUILD-file glue, or anything Skyframe-related. 
These are Bazel built on top of Starlark, not the language.

## Goal

A pure-Python tree-walking Starlark interpreter that:
- Has zero non-stdlib runtime dependencies
- Imports cleanly under CPython 3.11+
- Runs as a zipapp
- Passes the .star conformance tests bundled with Bazel)

Performance is explicitly NOT a goal. Correctness, clarity, and zero 
deps are the goals. Choose simplicity over cleverness at every fork 
in the road.

## Target layout

    /
    ├── reference/            # the Bazel Java source, kept for grepping
    │   └── src/main/java/net/starlark/java/...
    ├── conformance/          # .star test files, copied verbatim
    │   └── *.star
    ├── src/starlark/         # the Python port (the actual deliverable)
    │   ├── __init__.py
    │   ├── syntax/           # mirrors net.starlark.java.syntax
    │   ├── eval/             # mirrors net.starlark.java.eval
    │   └── ...
    ├── tests/
    │   ├── test_conformance.py   # parameterized over conformance/*.star
    │   ├── test_lexer.py / test_parser.py / test_eval.py / ...
    │   └── test_cross_validation.py
    ├── STATUS.md             # your progress journal
    ├── ROADMAP.md            # implementation phases with rationale
    ├── pyproject.toml
    └── README.md

Delete every file in the fork that doesn't belong in this layout. 
After cleanup, the working tree should be a small fraction of the 
original size.

## Architectural decisions (settled — do not relitigate)

1. **Tree-walking interpreter.** Recursive evaluation over the AST, 
   mirroring net.starlark.java.eval.Eval. No bytecode, no compiler.

2. **Integers are Python int.** Drop the Java StarlarkInt union of 
   int32/int64/BigInteger. Python's int is arbitrary precision; that 
   IS the model. There is no overflow.

3. **Strings are Python str, indexed by code point.** This 
   intentionally diverges from Java's UTF-16 indexing for non-BMP 
   characters. Document the divergence in the README. The Starlark 
   spec leaves this implementation-defined.

4. **Mutability is a per-Module token object.** Implement 
   net.starlark.java.eval.Mutability as a Python class with a 
   `frozen: bool` flag. Every mutable value (list, dict, struct) 
   holds a reference to its Mutability. Mutating methods check 
   the flag and raise EvalError when frozen. `Module.freeze()` is O(1).

5. **Builtin registration is a decorator, not an annotation.** Define 
   `@starlark_method(name=..., parameters=[...])` that stores metadata 
   on the function object. The dispatcher reads it. Use inspect.signature 
   for parameter metadata where it suffices.

6. **EvalException is a Python exception.** Subclass Exception. Carry 
   a list of (location, function-name) frames. Raise from eval; catch 
   at the API boundary.

7. **The `assert` test-support module is part of the port.** The 
   conformance .star files load it via `load("assert.star", "asserts")`. 
   Look at starlark-go's starlarktest/assert.star and Bazel's 
   StarlarkTestFn for the surface area.

If you want to deviate from one of these: stop, write a 3-paragraph 
analysis in STATUS.md under "Decisions Pending", and continue on 
something else until I respond.

## Bootstrap sequence (run autonomously)

Don't stop to check in unless a Decision is Pending.

1. Reduce the fork to the target layout. Use git filter-repo OR a 
   single rm -rf + squash commit — your call based on whether 
   preserving history of the kept paths matters to you. Copy Java 
   source to reference/, .star testdata to conformance/, scaffold 
   src/ and tests/ as empty.

2. `uv init` to scaffold. Zero runtime deps. Add pytest and ruff 
   as dev deps. Configure pytest to find tests/.

3. Write tests/test_smoke.py: assert `import starlark` works and 
   `starlark.eval("1 + 1") == 2`. Mark xfail. Run pytest, confirm 
   it xfails for the right reason.

4. Read these, in this order:
   - https://github.com/bazelbuild/starlark/blob/master/spec.md (full)
   - reference/src/main/java/net/starlark/java/eval/Starlark.java 
     (the public API)
   - reference/src/main/java/net/starlark/java/eval/Eval.java 
     (the evaluator, top to bottom)
   - reference/src/main/java/net/starlark/java/syntax/{Lexer,Parser,Resolver}.java
   - reference/src/main/java/net/starlark/java/eval/{StarlarkValue,
     StarlarkList,Dict,Tuple,StarlarkInt,StarlarkFunction,Module,
     Mutability}.java
   - A handful of .star files in conformance/ to see the test idiom
   You do not need to read the entire reference tree.

5. Write ROADMAP.md with phases in dependency order. For each phase 
   list (a) the relevant Java source files, (b) the conformance .star 
   files it should unlock. Suggested phases — adjust as needed:
     1. Lexer
     2. Parser + AST
     3. Resolver
     4. Value model + Mutability
     5. Evaluator: statements
     6. Evaluator: expressions
     7. Core builtins (len, type, range, print, etc.)
     8. String methods
     9. List/dict/tuple methods
    10. Function calls, closures, *args/**kwargs
    11. load() statement
    12. assert.star module
    13. Conformance suite turn-on
    14. Cleanup, docs, README, zipapp packaging

6. Write STATUS.md as a journal with today's date and "Bootstrap 
   complete." Append to it after every phase boundary or every ~10 
   commits, whichever comes first. Each entry: date, what landed, 
   what's next, any Decisions Pending.

7. Commit and push: "Scaffolding, roadmap, status."

8. Begin Phase 1. Implement, test, commit, append to STATUS.md, move 
   to Phase 2. Continue through all phases without stopping unless a 
   Decision is Pending or a stopping condition fires.

## Working agreements

- **Commit cadence.** One concept per commit. Semantic message. The 
  history should read like a tutorial.
- **Test cadence.** Every commit either adds a passing test, flips an 
  xfail to xpass, or adds an xfail for known-future work. No commits 
  without a test delta.
- **Conformance suite as progress dashboard.** From Phase 5 onward, 
  parameterize a pytest over conformance/*.star. Mark all xfail 
  initially. As features land, files flip to passing. The pytest 
  summary line is your progress signal.
- **Cross-validation.** tests/test_cross_validation.py: when 
  `starlark` (starlark-go CLI) is on PATH, run each .star file under 
  both implementations and assert matching success/failure status and 
  matching printed output. Skip the test cleanly when the binary is 
  absent.
- **Reference priority order.** When unsure about an edge case: 
  (1) spec.md, (2) the Java reference, (3) starlark-go's behavior, 
  (4) ask me. Don't guess.
- **Phase-end self-review.** At the end of each phase, before the 
  final commit, read every file you changed during the phase. Look 
  for half-finished work, dead code, inconsistent naming, missing 
  docstrings on public APIs, error messages that won't help users. 
  Fix in a cleanup commit.
- **STATUS.md is your memory.** Long sessions get compacted; 
  STATUS.md doesn't. Write it for the future Claude (or future you) 
  who'll resume work.
- **Don't ask permission for safe destructive ops on this fork.** 
  Rewriting history, deleting files, force-pushing your branch are 
  fine. Ask only before merging to main.

## Stopping conditions

Stop and ask me when:
- A Decision is Pending per the architectural rules.
- The conformance suite stops gaining passing tests for two 
  consecutive phases — something structural is wrong.
- The conformance pass rate exceeds 95%. We'll decide together how 
  to handle the long tail.

Do NOT stop because:
- A phase is hard. Read more reference code.
- A test fails. Fix it or xfail it with explanation.
- You're uncertain about a small detail. Pick the obvious option, 
  document the choice in STATUS.md, move on.

Begin.