Dev

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+!py/build/
+!py/build/**
+py/build/**/__pycache__/

AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+## Repo Overview
+
+- Module: `dappco.re/go/py`
+- Purpose: Python binding for Core primitives, with a Go-backed Tier 1 bootstrap runtime and a CPython package surface under `py/core/`.
+- Main surfaces: `bindings/`, `runtime/`, `py/core/`, `py/tests/`, and `examples/`.
+
+## First Reads
+
+- Read `README.md` first for the current layout, supported modules, and validation commands.
+- Read `CLAUDE.md` for the architecture split between Tier 1 and Tier 2.
+- Read `runtime/interpreter.go` before changing import behaviour, module registration, or the Tier 1 execution contract.
+- Read `py/tests/test_core.py` before changing observable Python behaviour, since it documents the current public surface well.
+- The README references an RFC outside this repo; if that spec is unavailable, trust the current implementation and tests.
+
+## Working Rules
+
+- Keep changes narrow and directly related to the task.
+- Preserve parity between the Go bindings/runtime contract and the Python package surface when changing primitive names, signatures, or import paths.
+- Prefer current code patterns over broad refactors or speculative abstractions.
+- Update nearby tests and docs when behaviour changes.
+- Avoid adding new Go or Python dependencies unless they are clearly required.
+- Preserve any user changes already present in the worktree.
+- Do not commit or rewrite history unless the user asks.
+
+## Project Layout
+
+- `bindings/`: Go-backed primitive bindings such as `config`, `data`, `echo`, `err`, `fs`, `json`, `log`, `math`, `medium`, `options`, `path`, `process`, `service`, and `strings`.
+- `bindings/typemap/`: Go-to-Python value conversion helpers used by the binding layer.
+- `runtime/`: Tier 1 bootstrap interpreter used to validate module registration, import shape, and simple execution.
+- `py/core/`: Python package surface for `core.*`, including docstrings and CPython fallbacks.
+- `py/core/math/`: Math submodules that must remain importable as `core.math.kdtree`, `core.math.knn`, and `core.math.signal`.
+- `py/tests/`: CPython validation for the package surface.
+- `examples/`: Example CorePy programs.
+
+## Coding Conventions
+
+- Match the style of the files you touch; keep Go and Python code straightforward and local.
+- Keep public import paths stable: Python users import `core` and `core.*`.
+- Maintain the existing module shape where both object-oriented and module-level helpers are exposed, such as in `config`, `data`, `medium`, `options`, and `service`.
+- Prefer example-driven doc comments and docstrings where the surrounding file already uses them.
+- Keep the Python package typed and consistent with the `pyproject.toml` target of Python 3.12+.
+- Avoid unrelated renames, formatting-only churn, and comment rewrites.
+- Leave the local `replace dappco.re/go/core => ../go` setup in `go.mod` alone unless the task explicitly requires changing dependency wiring.
+
+## Testing
+
+- Start with the narrowest relevant test surface, then widen scope.
+- Run `GOWORK=off go test ./...` after Go-side changes in `bindings/` or `runtime/`.
+- Run `PYTHONPATH=py python3 -m unittest discover -s py/tests -v` after Python package changes.
+- Run both validation commands when changing cross-surface behaviour or public module contracts.
+- Use `py/tests/test_core.py` as the reference for expected package parity and import behaviour.
+
+## Notes for Agents
+
+- This repo is intentionally bootstrap-oriented: the runtime validates the binding contract before the full embedded Python story lands.
+- When docs and code disagree, trust the current implementation and tests, then update the docs if needed.
+- If you discover a stable repo convention while working, update this file so future agents inherit it.

README.md

@@ -1,30 +1,61 @@
 # core/py — Python Binding for Core Primitives
 
-The fourth corner of the polyglot primitive stack. Python code imports `core` the
-way Go code imports `core/go`. Same primitives, same shape, same tests, different
-syntax surface.
-
-Two tiers:
-
-- **Tier 1 (gpython-embedded):** ships inside any CoreGO binary that imports
-  `dappco.re/go/py`. Pure-Go Python interpreter, no host CPython required.
-- **Tier 2 (CPython-via-uv):** managed CPython subprocess for code that needs
-  C extensions or 3.14 features beyond gpython's coverage.
+The fourth corner of the polyglot primitive stack. Python code imports `core`
+the way Go code imports `core/go`: same primitive names, same import paths,
+different syntax surface.
+
+## Current Implementation
+
+- `runtime/` contains a bootstrap Tier 1 interpreter that validates the CorePy
+  module contract, import shape, and Python-style list/dict type mapping
+  without waiting on the gpython dependency.
+- `runtime/tier2/` contains the CPython subprocess runner used for the Tier 2
+  escape hatch, with timeout, stdout/stderr streaming, and structured exit
+  results.
+- Tier 1 registers small stdlib-shaped shadows for common imports
+  (`json`, `os`, `os.path`, `subprocess`, `logging`, `hashlib`, `base64`, and
+  `socket`) so gpython scripts can use familiar import names while still
+  calling Core-backed primitives.
+- `corepy run -tier2-fallback` retries scripts in Tier 2 CPython when Tier 1
+  reports an unsupported import, preserving the explicit two-tier boundary.
+- `corepy repl` opens a stateful Tier 1 line session for quick primitive
+  experiments without leaving the CorePy runtime.
+- `bindings/` contains Go-backed bindings for the RFC v1 module surface:
+  `core.echo`, `core.fs`, `core.json`, `core.medium`, `core.options`,
+  `core.path`, `core.process`, `core.config`, `core.data`, `core.service`,
+  `core.log`, `core.err`, `core.strings`, `core.array`, `core.registry`,
+  `core.info`, `core.entitlement`, `core.action`, `core.task`, `core.i18n`,
+  the first `core.math` surface, plus initial RFC coverage for `core.cache`,
+  `core.crypto`, `core.dns`, and `core.scm`, and importable planned stubs for
+  `core.api`, `core.ws`, `core.store`, `core.container`, `core.agent`, and
+  `core.mcp`
+  (`mean`, `median`, `variance`, `stdev`, sorting, scaling, signal helpers,
+  and the `core.math.kdtree` / `core.math.knn` / `core.math.signal`
+  import paths).
+- `py/core/` contains the Python package surface for the RFC v1 modules,
+  including docstrings, concrete fallbacks for CPython validation, and
+  module-level helpers that mirror the Tier 1 binding shape.
+
+## Validation
+
+```bash
+GOWORK=off go mod tidy
+GOWORK=off go vet ./...
+GOWORK=off go test ./...
+GOWORK=off go test -tags gpython ./...
+python3 -m unittest discover -s py/tests -v
+```
 
 ## Layout
 
 | Path | Purpose |
 |------|---------|
-| `bindings/` | Go-side primitive bindings (fs, json, medium, options, process, service, math, typemap) |
-| `runtime/` | gpython host integration |
-| `py/core/` | Python-side package (installable via uv) |
-| `py/tests/` | Python test suite |
-| `examples/` | Polyglot example programs |
+| `bindings/` | Go-side primitive bindings and type conversion helpers |
+| `runtime/` | Tier 1 bootstrap interpreter and integration tests |
+| `py/core/` | Python package surface for `core.*` modules |
+| `py/tests/` | Python package validation |
+| `examples/` | Example CorePy programs |
 
 ## Spec
 
-`plans/code/core/py/RFC.md` in the spec tree — read first.
-
-## Status
-
-Bootstrap. Empty skeleton ready for factory dispatches.
+`/home/claude/Code/core/plans/code/core/py/RFC.md`