Step 257: token efficiency tests + benchmarks (Phase 9c complete)

Systematic validation of all Phase 9c token-saving features: compact AST
(6-7% of full size), lean scope (4% of detailed), diagnostic deltas, budget
pagination across 3 pages, batch queries, and combined 95% savings. Benchmark
confirms sub-millisecond parse->mutate->diagnose cycles. Also adds Environment
Layer feature request to docs/annotations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/annotations/Environment Layer.md

@@ -0,0 +1,159 @@
+# Feature Request: Environment Layer (Runtime / Host Semantics)
+
+## Summary
+
+Add a first-class Environment Layer to the AST-first pipeline so programs can be represented and transformed with explicit runtime/host context, not just syntax and pure computation.
+
+This is required for meaningful equivalence across languages whose semantics depend on a host runtime (browser, JVM, Python runtime, OS process model, Emacs runtime, etc.).
+
+## Motivation
+
+Many "languages" are inseparable from their environment:
+
+- **JavaScript in a browser** includes event loop, microtasks/macrotasks, DOM/Web APIs, sandbox constraints.
+- **Python** includes import system, module cache, object model, exceptions, refcount/GC behavior, venv packaging.
+- **JVM** includes class loading, verification, reflection, JIT, GC, bytecode semantics.
+
+If SemAnno only models AST/computation, the system will misrepresent equivalence and produce incorrect transpilation/runtime scaffolding.
+
+## Goals
+
+- Represent environment assumptions explicitly alongside AST/IR.
+- Allow transforms/transpilation to target either:
+  - a different language plus runtime scaffolding, or
+  - a different environment model (e.g., "browser-like event loop" in C++).
+- Provide an interface for agents to add environment-specific capabilities incrementally without rewriting core AST.
+
+## Non-Goals
+
+- Fully implementing a browser, JVM, or CPython.
+- Building a complete OS abstraction layer.
+- Perfect semantic equivalence across all edge cases (initially).
+- Standardizing on any single IR format beyond "must be able to attach env info."
+
+## Definitions
+
+- **Environment**: The execution context providing services and semantics beyond pure expression evaluation.
+- **Capability**: A named service the environment provides (I/O, timers, threads, module loading, reflection, etc.).
+- **Binding Time**: Whether a name/operation resolves at compile-time, link-time, load-time, or runtime.
+- **Scheduler Model**: Event loop vs threads vs fibers vs cooperative coroutines.
+- **Memory Model**: Ownership/RAII, tracing GC, ref-counting, region/arena, etc.
+
+## User Stories
+
+- As a SemAnno user, I want to mark that a program depends on event loop semantics so a C++ target can generate appropriate scheduling code.
+- As an agent generating C++ from Python-like semantics, I want to know whether imports are dynamic and how to model module caching and lookup.
+- As an agent generating code for a browser target, I want to know which capabilities are required (DOM, fetch, timers) and which are forbidden (filesystem).
+- As a developer debugging transpilation, I want the environment layer to explain why a transform chose threads vs event loop vs coroutines.
+
+## Requirements
+
+### R1. Environment Spec Object
+
+There must be a structured "Environment Spec" attached to a program/module and accessible during transformations.
+
+Minimum fields (names are suggestions; adapt to SemAnno conventions):
+
+| Field | Type | Description |
+|---|---|---|
+| `env.id` | string | identifier, e.g. `posix_process`, `browser`, `jvm`, `python_cpython_like`, `emacs_runtime` |
+| `env.version` | optional string | version of the environment spec |
+| `env.capabilities` | set/list | declared required capabilities |
+| `env.constraints` | set/list | forbidden or restricted behaviors |
+| `env.scheduler` | enum-ish | `event_loop`, `threads`, `fibers`, `coroutines`, `single_thread` |
+| `env.memory` | enum-ish | `manual`, `raii`, `refcount`, `tracing_gc`, `region` |
+| `env.binding_times` | mapping | per symbol class or feature: `compile`, `link`, `load`, `runtime` |
+| `env.exceptions` | model descriptor | unwind style / checked vs unchecked / typed vs untyped |
+| `env.ffi` | descriptor | C ABI available? dynamic linking? host-call boundary? |
+
+### R2. Capability Declarations
+
+Provide a small fixed vocabulary to start (expandable):
+
+- `io.fs`
+- `io.net`
+- `io.stdinout`
+- `clock.time`
+- `timers`
+- `event_loop`
+- `threads`
+- `process`
+- `signals`
+- `modules`
+- `dynamic_loading`
+- `reflection`
+- `gc`
+- `jit`
+- `ui.dom` (browser-like)
+- `editor.emacs` (hosted in Emacs runtime / elisp interop)
+- `host.imgui` (UI host integration)
+
+### R3. Transform Hooks Must Receive Env
+
+All major transforms must have read access to the environment spec:
+
+- AST -> IR lowering
+- IR -> target emission
+- optimization passes (esp. those unsafe across concurrency/GC boundaries)
+- runtime scaffolding generation
+
+### R4. Environment-Aware Lowering
+
+Certain constructs must lower differently depending on env. Examples:
+
+| Construct | Lowering varies by... |
+|---|---|
+| `async/await` | event loop tasks vs threads vs coroutines |
+| `imports/modules` | static linking vs dynamic loading vs runtime lookup |
+| `exceptions` | unwind vs error unions vs result objects |
+| `dynamic attribute access` | dictionary lookup vs vtable-like dispatch |
+
+(Exact mapping is a later task; requirement is that the architecture supports this.)
+
+### R5. Explicit Host Boundary Nodes (Optional but Recommended)
+
+To avoid hidden assumptions, represent host interactions as explicit IR/AST nodes:
+
+```
+HostCall(capability="io.net", name="fetch", args=...)
+ScheduleTask(queue="microtask", ...)
+ModuleLoad(name=..., mode=dynamic/static, ...)
+```
+
+This enables correct transpilation/scaffolding and helps debugging.
+
+## Implementation Notes (Low-Assumption)
+
+- Prefer adding an annotation schema (e.g., JSON/YAML/S-expression) that can be attached to modules and referenced by UUID/path.
+- The editor should surface the env spec as:
+  - a module-level panel (read/write), and
+  - per-node "requires capability" hints where relevant.
+- Keep the initial environment models coarse:
+  - "POSIX-ish native"
+  - "Browser-ish event loop"
+  - "Python-like dynamic runtime"
+  - "JVM-like managed runtime"
+  - "Emacs-hosted runtime"
+- Allow partial specs; missing fields should not crash transforms (fall back to conservative defaults).
+
+## Acceptance Criteria
+
+- There exists a persisted Environment Spec artifact (in annotations) that is loadable with the rest of SemAnno metadata.
+- A transform can query `env.scheduler` and `env.capabilities` and choose different lowering strategies.
+- The editor can display and edit the Environment Spec without requiring the AST editor to be complete.
+- At least one demo transformation uses env info (e.g., toggling `event_loop` vs `threads` changes generated scaffolding).
+
+## Suggested Deliverables
+
+1. EnvironmentSpec schema + parser/loader
+2. Editor UI panel to view/edit EnvironmentSpec
+3. Pass-through plumbing so all transforms receive EnvironmentSpec
+4. One example backend decision driven by env (scheduler or module loading)
+5. Documentation entry describing the field meanings and intended usage
+
+## Open Questions (Intentionally Not Assumed)
+
+- Where should env live? (program-level, module-level, per-subtree override?)
+- How should capabilities be namespaced/versioned?
+- What is SemAnno's canonical serialization format for annotations?
+- How should "mixed environments" work (e.g., native core + embedded JS VM)?