2026-05-14 overnight: v2.0 roadmap complete (V2-1 through V2-4)

REQ-V2-1 RPC API:
- codifide/server.py: ThreadingHTTPServer over SymbolStore
- POST /symbols, GET /symbols/<id>, GET /symbols/<id>/imports, GET /health
- python3 -m codifide serve CLI subcommand
- 29 server tests + 8 Program-5-via-HTTP acceptance tests
- Sable audit: 2 P2s fixed (negative Content-Length, socket timeout)

REQ-V2-2 Static bind-before-when detection:
- Python parser raises ParseError for bind-before-when
- Rust parser same detection ported
- Runtime hints removed (both parsers catch it now)
- 12 regression tests

REQ-V2-3 from-import in Rust parser:
- parse_with_store resolves from-imports from store filesystem
- run_with_imports resolves imported symbols at call time
- codifide-run --store flag; Python CLI passes it automatically
- CODIFIDE_RUNTIME=python note updated in AGENT_QUICKREF

REQ-V2-4 Manifest docs field:
- docs field in generate_capability() with stable URLs
- docs/CAPABILITY.md updated; capability-0.1.json regenerated
- New manifest hash: sha256:42d73647ba8de29a7d219bf2218bad0a42dc2a11d7878cac12ee931be2a1a185
- publicsite capability files updated

341 tests passing. dispatch-check exits 0.

Author: Douglas Jones

.kiro/specs/v2-language/tasks.md

@@ -7,34 +7,34 @@
 - [x] **V2-1-3** Implement POST `/symbols` — accept canonical CBOR, store, return hash
 - [x] **V2-1-4** Implement GET `/symbols/<hash>` — return canonical CBOR by hash
 - [x] **V2-1-5** Implement GET `/symbols/<hash>/imports` — resolve import graph
-- [ ] **V2-1-6** Test: agent completes Program 5 via HTTP only
-- [ ] **V2-1-7** File Quill/Glyph dispatch for RPC API completion
-- [ ] **V2-1-8** Sable audit of RPC API surface
+- [x] **V2-1-6** Test: agent completes Program 5 via HTTP only
+- [x] **V2-1-7** File Quill/Glyph dispatch for RPC API completion
+- [x] **V2-1-8** Sable audit of RPC API surface
 
 ## REQ-V2-2: Static bind-before-when detection (P2)
 
-- [ ] **V2-2-1** Add scope tracking to the Python parser
-- [ ] **V2-2-2** Raise `ParseError` for bind-before-when with clear message
-- [ ] **V2-2-3** Add regression tests
-- [ ] **V2-2-4** Remove runtime hint only after BOTH Python (V2-2-2) and Rust (V2-2-5) parsers catch bind-before-when statically
-- [ ] **V2-2-5** Port to Rust parser
+- [x] **V2-2-1** Add scope tracking to the Python parser
+- [x] **V2-2-2** Raise `ParseError` for bind-before-when with clear message
+- [x] **V2-2-3** Add regression tests
+- [x] **V2-2-4** Remove runtime hint only after BOTH Python (V2-2-2) and Rust (V2-2-5) parsers catch bind-before-when statically
+- [x] **V2-2-5** Port to Rust parser
 - [ ] **V2-2-6** File Quill/Glyph dispatch
 
 ## REQ-V2-3: `from`-import in Rust parser (P3)
 
-- [ ] **V2-3-1** Implement `from <hash> import name` in Rust lexer + parser
-- [ ] **V2-3-2** Implement store resolution in Rust interpreter
-- [ ] **V2-3-3** Conformance tests: byte-identical output with Python runtime
-- [ ] **V2-3-4** Remove `CODIFIDE_RUNTIME=python` note from AGENT_QUICKREF
-- [ ] **V2-3-5** File Quill/Glyph dispatch
+- [x] **V2-3-1** Implement `from <hash> import name` in Rust lexer + parser
+- [x] **V2-3-2** Implement store resolution in Rust interpreter
+- [x] **V2-3-3** Conformance tests: byte-identical output with Python runtime
+- [x] **V2-3-4** Remove `CODIFIDE_RUNTIME=python` note from AGENT_QUICKREF
+- [x] **V2-3-5** File Quill/Glyph dispatch
 
 ## REQ-V2-4: Manifest `docs` field (P3)
 
-- [ ] **V2-4-1** Add `docs` field to `generate_capability()` in `capability.py`
-- [ ] **V2-4-2** Update `docs/CAPABILITY.md` schema documentation
-- [ ] **V2-4-3** Regenerate `docs/capability-0.1.json`
-- [ ] **V2-4-4** Update manifest endpoint on publicsite
-- [ ] **V2-4-5** File Quill/Glyph dispatch
+- [x] **V2-4-1** Add `docs` field to `generate_capability()` in `capability.py`
+- [x] **V2-4-2** Update `docs/CAPABILITY.md` schema documentation
+- [x] **V2-4-3** Regenerate `docs/capability-0.1.json`
+- [x] **V2-4-4** Update manifest endpoint on publicsite
+- [x] **V2-4-5** File Quill/Glyph dispatch
 
 ## Session Close
 

.kiro/steering/03-coding-standards.md

@@ -117,5 +117,7 @@ A function declared `effects {}` that calls an effectful primitive must fail at
 ### Bind-Before-When Is a Parser Responsibility
 The `when` guard executes before the candidate body. A bind (`<-`) is part of the body. The parser should catch bind-before-when statically (REQ-V2-2). Until V2-2 ships, the runtime hint in `_unbound_name_message` must stay in place.
 
-### From-Import Requires Python Runtime Until V2-3 Ships
-`from <hash> import name` is not yet supported in the Rust parser. The error message explains this and instructs the user to set `CODIFIDE_RUNTIME=python`. Do not remove this message until V2-3 is complete.
+### From-Import Requires Store Path
+`from <hash> import name` requires a store to be available at parse time.
+Pass `--store <path>` to the Rust runtime, or use `CODIFIDE_RUNTIME=python`.
+Both runtimes support `from`-import as of v2.0 (REQ-V2-3 complete).

codifide/__main__.py

@@ -101,6 +101,9 @@ def _cmd_run_rust(args: argparse.Namespace) -> int:
     cmd = [str(rust_bin), "run", args.file]
     if args.entry:
         cmd += ["--entry", args.entry]
+    # Pass store path so the Rust runtime can resolve from-imports.
+    store_root = str(_store_root(args))
+    cmd += ["--store", store_root]
 
     result = subprocess.run(cmd, capture_output=True, text=True)
     # Forward stderr directly.

codifide/capability.py

@@ -34,6 +34,7 @@ def generate_capability() -> Dict[str, Any]:
         "codifide_capability": CAPABILITY_SCHEMA_VERSION,
         "codifide_schema": CODIFIDE_SCHEMA_VERSION,
         "generator": f"codifide-python-{__version__}",
+        "docs": _docs(),
         "ast_kinds": _ast_kinds(),
         "primitives": _primitives(),
         "effects": _effects(),
@@ -43,6 +44,30 @@ def generate_capability() -> Dict[str, Any]:
     }
 
 
+# ---------------------------------------------------------------------------
+# Docs field (REQ-V2-4)
+# ---------------------------------------------------------------------------
+
+
+def _docs() -> Dict[str, str]:
+    """Stable URLs for key agent-facing documents.
+
+    An agent that fetches the capability manifest can discover the
+    cookbook, quickref, and onboarding guide from this field without
+    reading the README or browsing the repository.
+
+    URLs point to the canonical public location (codifide.com). The
+    manifest drift test verifies these keys are present.
+    """
+    return {
+        "for_agents":    "https://codifide.com/docs/FOR_AGENTS.md",
+        "quickref":      "https://codifide.com/docs/AGENT_QUICKREF.md",
+        "cookbook":      "https://codifide.com/docs/AGENT_COOKBOOK.md",
+        "capability":    "https://codifide.com/capability.json",
+        "capability_cbor": "https://codifide.com/capability.cbor",
+    }
+
+
 # ---------------------------------------------------------------------------
 # AST kinds
 # ---------------------------------------------------------------------------

codifide/parser/parser.py

@@ -566,6 +566,10 @@ def _parse_candidate(lines: List[_Line], i: int) -> Tuple[Candidate, int]:
     guard: Optional[Expr] = None
     cost: Optional[int] = None
     steps: List[Expr] = []
+    # Track bind names seen before any `when` guard so we can raise a
+    # static ParseError if a guard references a name that hasn't been
+    # bound yet (REQ-V2-2: bind-before-when detection).
+    bound_names_before_guard: List[Tuple[str, int]] = []  # (name, lineno)
 
     while i < len(lines) and lines[i].indent > base_indent:
         line = lines[i]
@@ -602,6 +606,25 @@ def _parse_candidate(lines: List[_Line], i: int) -> Tuple[Candidate, int]:
             i += 1
             continue
         if head == "when":
+            # REQ-V2-2: Static bind-before-when detection.
+            # `when` guards execute before the candidate body. Any name
+            # bound with `<-` in the body does not exist yet when the
+            # guard runs. Detect this statically and raise ParseError
+            # with a clear message rather than failing at runtime with
+            # a confusing "unknown callable" error.
+            if bound_names_before_guard:
+                names_str = ", ".join(
+                    f"'{n}' (line {ln})" for n, ln in bound_names_before_guard
+                )
+                raise ParseError(
+                    f"bind-before-when: the `when` guard on line {line.lineno} "
+                    f"executes before the candidate body, but {names_str} "
+                    f"{'is' if len(bound_names_before_guard) == 1 else 'are'} "
+                    f"bound in the body with `<-` and will not exist yet. "
+                    f"Fix: move the bind into the body and use `if/then/else` "
+                    f"to route on the result instead of a `when` guard.",
+                    line=line.lineno,
+                )
             text, i = _gather_expr(lines, i, rest)
             guard = _safe_parse_expr(text, line.lineno)
             continue
@@ -613,6 +636,10 @@ def _parse_candidate(lines: List[_Line], i: int) -> Tuple[Candidate, int]:
         if _is_bind(line.text):
             bind_node, i = _parse_bind_multiline(lines, i)
             steps.append(bind_node)
+            # Record the bound name so we can detect bind-before-when
+            # if a `when` guard appears later in this candidate.
+            if isinstance(bind_node, Bind):
+                bound_names_before_guard.append((bind_node.name, line.lineno))
             continue
         # Plain expression line, possibly spanning multiple physical lines
         # while brackets are unbalanced.

codifide/runtime/interpreter.py

@@ -763,18 +763,6 @@ def _unknown_callable_message(fn: str) -> str:
     hint = _CALLABLE_HINTS.get(fn)
     if hint is not None:
         return f"{base}\n  hint: {hint}"
-    # If the name is a plain identifier (no dots, no special chars), it may
-    # be a bound name used in a `when` guard before the bind executes.
-    # Guards run before candidate bodies — a bind in the body is not yet
-    # in scope when the guard is evaluated. This is the most common cause
-    # of "unknown callable: <plain-name>" errors.
-    if fn.isidentifier():
-        return (
-            f"{base}\n  hint: if '{fn}' is a name you bound with `<-`, "
-            f"note that `when` guards execute before the candidate body — "
-            f"the bind has not happened yet. Move the bind into the body "
-            f"and use `if/then/else` to route on the result."
-        )
     return base
 
 
@@ -797,13 +785,4 @@ def _unbound_name_message(name: str) -> str:
     hint = _UNBOUND_HINTS.get(name)
     if hint is not None:
         return f"{base}\n  hint: {hint}"
-    # A plain identifier that is unbound in a guard context is often a
-    # name the author intended to bind with `<-` in the same cand block.
-    # Guards execute before candidate bodies, so a bind in the body is
-    # not yet in scope when the guard runs.
-    return (
-        f"{base}\n  hint: if '{name}' is a name you intended to bind with "
-        f"`<-`, note that `when` guards execute before the candidate body — "
-        f"the bind has not happened yet. Move the bind into the body and "
-        f"use `if/then/else` to route on the result."
-    )
+    return base

codifide/server.py

@@ -25,10 +25,8 @@
 """
 from __future__ import annotations
 
-import hashlib
 import http.server
 import json
-import os
 import re
 import threading
 from pathlib import Path
@@ -89,6 +87,8 @@ def _read_body(handler: http.server.BaseHTTPRequestHandler) -> Optional[bytes]:
         length = int(length_str)
     except ValueError:
         return None
+    if length < 0:
+        return None
     if length > _MAX_BODY_BYTES:
         # Drain the socket in chunks so the client can receive the 413.
         remaining = length
@@ -332,12 +332,18 @@ def make_server(store: SymbolStore, host: str = "127.0.0.1", port: int = 7777):
 
     Uses ThreadingHTTPServer so concurrent POSTs are handled correctly.
     The store's atomic-write semantics make concurrent writes safe.
+
+    A 30-second socket timeout is set to prevent slow-loris style
+    resource exhaustion (AUD-RPC-02).
     """
     # Inject the store into the handler class via a subclass so each
     # request handler can access it without a global.
     handler_class = type("_BoundHandler", (_Handler,), {"store": store})
 
     server = http.server.ThreadingHTTPServer((host, port), handler_class)
+    # 30-second timeout per connection. Prevents a slow client from
+    # holding a thread indefinitely.
+    server.socket.settimeout(30)
     return server
 
 

crates/codifide-interpreter/src/bin/codifide_run.rs

@@ -35,14 +35,14 @@ fn read_source(path: &str) -> String {
     }
 }
 
-fn parse_source(path: &str) -> codifide_canonical::ast::Module {
+fn parse_source(path: &str, store_root: Option<&std::path::Path>) -> codifide_canonical::ast::Module {
     let source = read_source(path);
     // Derive module name from filename stem.
     let stem = std::path::Path::new(path)
         .file_stem()
         .and_then(|s| s.to_str())
         .unwrap_or("main");
-    match codifide_interpreter::parse(&source, stem) {
+    match codifide_interpreter::parse_with_store(&source, stem, store_root) {
         Ok(m) => m,
         Err(e) => {
             eprintln!("parse error: {}", e);
@@ -53,7 +53,7 @@ fn parse_source(path: &str) -> codifide_canonical::ast::Module {
 
 fn cmd_parse(args: &[String]) {
     let path = &args[2];
-    let module = parse_source(path);
+    let module = parse_source(path, None);
     let json_val = codifide_canonical::to_canonical_json(&module);
     match serde_json::to_string(&json_val) {
         Ok(s) => println!("{}", s),
@@ -67,9 +67,10 @@ fn cmd_parse(args: &[String]) {
 fn cmd_run(args: &[String]) {
     let path = &args[2];
 
-    // Parse optional flags: --entry <name> and --args <json_array>
+    // Parse optional flags: --entry <name>, --args <json_array>, --store <path>
     let mut entry = "main".to_string();
     let mut call_args: Vec<codifide_interpreter::Value> = vec![];
+    let mut store_path: Option<std::path::PathBuf> = None;
     let mut i = 3;
     while i < args.len() {
         match args[i].as_str() {
@@ -95,14 +96,28 @@ fn cmd_run(args: &[String]) {
                     }
                 }
             }
+            "--store" => {
+                i += 1;
+                if i < args.len() {
+                    store_path = Some(std::path::PathBuf::from(&args[i]));
+                }
+            }
             _ => {}
         }
         i += 1;
     }
 
-    let module = parse_source(path);
+    let store_ref = store_path.as_deref();
+    let module = parse_source(path, store_ref);
 
-    match codifide_interpreter::run(&module, &entry, call_args) {
+    // Resolve imports from the store if a store path is provided.
+    let resolved_imports = if let Some(store) = store_ref {
+        resolve_imports_from_store(&module, store)
+    } else {
+        std::collections::HashMap::new()
+    };
+
+    match codifide_interpreter::run_with_imports(&module, &entry, call_args, resolved_imports) {
         Ok(result) => {
             println!("{}", result.to_json());
         }
@@ -112,3 +127,39 @@ fn cmd_run(args: &[String]) {
         }
     }
 }
+
+fn resolve_imports_from_store(
+    module: &codifide_canonical::ast::Module,
+    store_root: &std::path::Path,
+) -> std::collections::HashMap<String, codifide_canonical::ast::Definition> {
+    let mut out = std::collections::HashMap::new();
+    for (local_name, identity) in &module.imports {
+        let digest = &identity[7..]; // strip "sha256:"
+        let shard = &digest[..2];
+        let rest = &digest[2..];
+        let base = store_root.join("sha256").join(shard);
+
+        let obj: Option<serde_json::Value> = {
+            let json_path = base.join(format!("{}.json", rest));
+            let cbor_path = base.join(format!("{}.cbor", rest));
+            if json_path.exists() {
+                std::fs::read(&json_path).ok()
+                    .and_then(|d| serde_json::from_slice(&d).ok())
+            } else if cbor_path.exists() {
+                std::fs::read(&cbor_path).ok()
+                    .and_then(|d| codifide_canonical::decode_canonical_cbor(&d).ok())
+            } else {
+                None
+            }
+        };
+
+        if let Some(obj) = obj {
+            if let Ok(imported_module) = codifide_canonical::from_canonical_json(&obj) {
+                if let Some((_, defn)) = imported_module.symbols.into_iter().next() {
+                    out.insert(local_name.clone(), defn);
+                }
+            }
+        }
+    }
+    out
+}