forterp 0.1.0__tar.gz

forterp-0.1.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+## 2026-06-24 — the monitor rename, override docs, and PyPI release wiring
+
+- **09:58** — Dropped the `@builtin` decorator alias — `@fcall`/`@uuo` are the two authoring decorators; "builtin" stays the registry noun (`register_builtins`/`builtins_in`/`BUILTINS`). Synced the guides + CHANGELOG to the host-layer work.
+- **10:23** — Reformatted this changelog as reverse-chronological day blocks (newest first), terse timed one-liners.
+- **10:44** — Renamed the interactive shell `Monitor` → `CommandProcessor` (`forterp.command`) and dropped the REPL's `MONITOR` reserved word — freeing "monitor" for the executive facade.
+- **10:59** — Renamed the `@uuo` facade `Host` → `Monitor` (`monitor(eng)`, `eng.monitor`, the `monitor=` builder kwarg) — `mon` now abbreviates its actual type.
+- **11:09** — API guide: how to override the `Monitor` facade with your own (subclass + inject via `monitor=` or `eng.monitor`; the bundled `uuolib` UUOs read the engine seam directly, not the facade).
+- **11:33** — `_load_builtins` no longer leaks `sys.path`/`sys.modules`; the `STR` arg mode strips a packed word's padding so it equals the literal text.
+- **11:38** — Documented the `hostlib.host_ppn`/`host_user` identity helpers alongside `mon.identity`.
+- **11:56** — PyPI release wiring: publish through the `forterp-pypi` environment, with a manual approval gate (the `release` environment + a required reviewer) fronting the tag-triggered publish.
+
+## 2026-06-23 — host services, terminal modes, and real binary files
+
+- **02:17** — `hostlib` `STR` arg mode: `args=(STR,)` gives the body a Python `str` (a quoted literal verbatim, or a packed word decoded via the target codec), lifting the StrLit-vs-packed resolution out of each body.
+- **04:05** — Real FOROTS binary files (opt-in `Engine(dec_files=True)`): on-disk word↔byte packing + LSCW framing (`forbin`), validated against the V5 D-7/D-8 example byte-for-byte; plus end-to-end host-routine docs (API `@fcall`/`@uuo` + arg modes + `raw`, DESIGN §7a).
+- **09:56** — Terminal echo-control seam (`Engine(set_echo=fn)` + `mon.tty.echo`); renamed the host-services facade `HostServices`/`host_services` → `Host`/`host`.
+- **12:24** — `run_source` installs a default terminal echo (`runtime.default_terminal_echo` flips the tty's termios `ECHO`, restored after); added the autowrap seam (`set_autowrap` + `mon.tty.autowrap`, `TRMOP.` `.TONFC`).
+- **17:50** — Host identity (`mon.identity` — uid/gid/login/PPN); `GETTAB` models the job tables (`.GTPPN` → guest `[0,0]`, `.GTJTC` → 0), with an `eng.gettab` registry and `UnmodeledMonitorTable` for the rest.
+- **21:14** — Review fixes: `OUTSTR` uses the target's `chars_per_word`; restored the `OPEN` read's `with`; a host `builtins=` table no longer shadows a program-defined unit; a stdlib-shadowing `.py` arg gives a clean `?`-diagnostic.
+- **21:52** — Two-word DOUBLE PRECISION binary I/O (the KL10 doubleword, lossless where the single rounded); `_bin_words`/`_assign_words` code per declared type, per element; a config-mismatched binary file fails loud (`OSError`) instead of a garbage text read.
+- **23:29** — FORTRAN-10 free CR-LF: `emit()` wraps terminal output at the carriage width host-side (`Engine(tty_width=80, tty_autowrap=True)`, deferred margin); strict F66 never wraps; CLI `--no-wrap`.
+
+## 2026-06-22 — host services for the embedder
+
+- **12:33** — `hostlib` host-services half: a baseline `HostServices` facade (`tty`/`files`/`clock`, over the engine's host seam) + an `@uuo` decorator that injects it — the counterpart to `@fcall` for routines that talk to the host; injectable via `eng.host_services`. `@builtin`/`@fcall`/`@uuo` gain `alias=`/`origin=`.
+- **13:17** — CLI `--recover-shifted-cols` (opt-in shifted-column recovery); a dropped-in `*.py` may define a `register(eng)` hook, and `run_source` gains `setup=fn(eng)`.
+- **14:43** — `OPEN` decodes a packed numeric `FILE=`/`NAME=` as a SIXBIT/ASCII filename (as it already does `DEVICE=`), not `str()` of the raw word.
+- **14:53** — `pyfortran10` defaults `--target pdp10` (and `pyf66` stays `native`), matching the prebuilt interpreters.
+- **16:21** — `uuolib`: the standard TOPS-10 monitor UUOs (`OUTSTR`/`OUTCHR`/`MSTIME`/`SLEEP`/`GETTAB`), installed under the FORTRAN-10 dialect on the engine's host seam.
+
+## 2026-06-21 — genuine-source demos, then the release-readiness sweep
+
+- **16:16** — `demos/`: genuine 1970s FORTRAN run as-is — netlib EISPACK/LINPACK/FFT/RKF45 with drivers, DECUS-tape sources, and Paul Boltwood's 1971 Game of Life.
+- **16:16** — `examples/`: short Python scripts driving forterp as a library.
+- **16:16** — Multi-file linking: several source files linked by unit name, like `f77 main.f lib.f`.
+- **16:16** — Dialect gaps closed (gated; F66 still rejects them): the optional comma before an I/O list, two-word `END FILE`, `DATA` as an array name.
+- **16:16** — `READ`/`ACCEPT` EOF fix: terminal input past end-of-stream branches to `END=` instead of looping.
+- **16:16** — Sequence-association fix: an array element passed where the dummy is an array is re-viewed as a based array (LINPACK/RKF45 work-vector passing).
+- **16:18** — Readability pass: clearer names, smaller focused dispatchers.
+- **16:40** — Error-handling pass: clean `?`-diagnostics in place of raw tracebacks.
+- **17:15** — Trimmed the evaluator hot path (~1.5× on tight loops).
+- **18:14** — Capped a single array/`COMMON` allocation; wrote down the interpreter-not-a-sandbox trust model.
+- **18:26** — Correctness vs `gfortran` (differential testing): per-record carriage control, list-directed grammar, three-digit exponents.
+- **18:52** — Extended the dual-run harness to compare terminal output; pinned the public-API contracts.
+- **20:00** — Packaging & CI: PyPI/distribution readiness — `build` + `twine`, a 3.9–3.13 test matrix.
+- **20:13** — Committed the built docs site, kept in sync automatically by a pre-commit hook.
+- **20:51** — Hardened the resource limits, `INCLUDE` resolution, and duplicate-unit detection.
+- **20:58** — Tag-triggered PyPI release via OIDC Trusted Publishing, gated on tests/lint/format and `tag == __version__`.
+- **21:42** — Docs hygiene: folded the origin history into this changelog; removed the HISTORY/HANDOFF/third-party files; recorded FCVS as public domain; trimmed the overuse of "faithful".
+- **22:41** — ruff maintained at commit time (a pre-commit hook), with import-sort and dead-`noqa` rules.
+- **23:06** — CLI `--version`; moved the engine builders into `forterp.runtime`.
+- **23:23** — Slimmed the package root to exactly `__all__` — dropped the back-compat aliases.
+- **23:33** — `forterp.debug.oob_census()`: a public OOB-access census, so consumers no longer poke engine internals.
+- **23:47** — New docs: a CLI reference and a `forterp.*` API programmer's guide.
+- **23:51** — Docs-site polish: a "Docs" breadcrumb, interpreter-design vocabulary on the home-page pipeline, a high-contrast beta stamp.
+- **23:58** — CLI loads `.py` host-routine modules beside FORTRAN source: a `*.py` argument is imported and its `@builtin` routines are discovered (`hostlib.builtins_in`) and registered — drop them in, no registry/`__init__`.
+
+## 2026-06-20 — real-machine defaults, host marshalling, docs site
+
+- **00:00** — The `fortran10` preset drops cols 73+ by default; shifted-column recovery is opt-in.
+- **17:03** — `hostlib`: a declarative marshalling layer for host builtins.
+- **23:25** — A GitHub Pages docs site: a `markdown-it-py` static-site generator (`gh-pages/`), Actions deploy.
+
+## 2026-06-19 — CLI, monitor, REPL, debugger, conformance
+
+- **00:00** — Three console front-ends: `pyf66`, `pyfortran10`, `forterp --std`.
+- **00:48** — Gated the DEC I/O surface, intrinsics, and random-access I/O under F66; added the V5 math/rotate intrinsics.
+- **01:11** — `--check`: parse and list diagnostics without running.
+- **10:16** — An interactive command monitor (a TOPS-10 `.`-prompt descendant).
+- **10:20** — An immediate-mode REPL, then refactored onto two reusable primitives.
+- **11:03** — Factored target/dialect config into shared registries + `engine_kwargs`.
+- **12:31** — An off-by-default per-statement tracer hook; on it, a debugger + profiler.
+- **14:24** — Formatted-input conformance; fixed the random-access write clobber; CLI error hygiene.
+- **21:10** — Exposed the embedding API; added the prebuilt `fortran10` / `f66` interpreters.
+- **21:47** — Gated every non-F66 feature behind a `Dialect` flag; dual-run F66 tests under both dialects.
+- **22:11** — Illegal `EQUIVALENCE` shapes now raise; documented the multi-word storage boundary.
+- **23:06** — list-directed/NAMELIST bad fields raise like formatted; `forbin` rejects unrepresentable floats.
+
+## 2026-06-18 — pluggable seams, then standalone
+
+- **08:58** — A pluggable `OPEN` device registry.
+- **09:23** — Extracted the machine value model behind a pluggable `Target`.
+- **09:43** — Parameterized the front-end dialect (`Dialect`).
+- **11:23** — A `fortran10` layer atop the `f66` core; moved FOROTS binary I/O into it.
+- **13:44** — **Split out to a standalone repo** — a `src/` package with a clean public API and the FCVS corpus.
+- **14:09** — Routed every wrap/pack/truthy site through `Target` (INT/LSH, the logical algebra, the char codec).
+- **14:47** — Added the `NATIVE` 64-bit target and made it the default; `PDP10` the opt-in machine.
+- **15:19** — A provisional, unvalidated `VAX` target.
+- **15:39** — Curated the FCVS corpus to F66-only (dropped the 140 F77/`CHARACTER` routines).
+- **16:25** — Adopted `ruff` lint + `ruff format`.
+- **23:59** — Renamed `f66` → `forterp`; made `F66` the default dialect.
+
+## 2026-06-17 — hardening for the next program
+
+- **22:49** — `COMMON` sizing, dummy procedures, continuation comments, lowercase `nH` Hollerith.
+
+## 2026-06-16 — and so it begins...
+
+- **15:29** — Initial FORTRAN-10 / F66 interpreter: lexer, parser, AST, tree-walking engine, the FORMAT runtime, the `forlib` library, diagnostics.
+- **16:07** — F66 §3.1.6 blanks-insignificance, via a tokenizer parse-retry.
+- **18:49** — `RAN`/`SETRAN`, COMPLEX formatted input, NAMELIST and random-access I/O, `%FTNLID` warnings.
+- **18:51** — FOROTS binary-record codec (LSCW framing + DEC-10 float), `MODE='BINARY'`.
+- **23:12** — Front-end: DEC TAB-format source, the bare main program, integer-vs-`.EQ.` lexing.

forterp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas J. Kisseberth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forterp-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+# What rides along in the source distribution (the wheel is the package alone).
+#
+# Without this file setuptools' legacy default shipped tests/test_*.py but neither
+# conftest.py (the shared run/out harness) nor tests/fcvs/ (the conformance corpus) --
+# i.e. a test tree that couldn't actually run. Make the sdist a complete, buildable and
+# testable snapshot: the full test suite plus the demo programs and prose docs that the
+# README and docs site point at.
+
+graft tests
+graft demos
+graft docs
+graft examples
+include CHANGELOG.md
+
+# never ship build/cache droppings
+global-exclude *.py[cod]
+global-exclude .DS_Store
+prune **/__pycache__

forterp-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: forterp
+Version: 0.1.0
+Summary: A FORTRAN-66 / DEC FORTRAN-10 interpreter in Python
+Author-email: "Nicholas J. Kisseberth" <nkissebe@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nyxcraft/forterp
+Project-URL: Documentation, https://nyxcraft.github.io/forterp/
+Project-URL: Source, https://github.com/nyxcraft/forterp
+Project-URL: Issues, https://github.com/nyxcraft/forterp/issues
+Project-URL: Changelog, https://github.com/nyxcraft/forterp/blob/main/CHANGELOG.md
+Keywords: fortran,fortran66,f66,fortran-10,pdp-10,interpreter,retrocomputing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: markdown-it-py; extra == "docs"
+Dynamic: license-file
+
+# forterp
+
+[![Tests](https://github.com/nyxcraft/forterp/actions/workflows/tests.yml/badge.svg)](https://github.com/nyxcraft/forterp/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/forterp.svg)](https://pypi.org/project/forterp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/forterp.svg)](https://pypi.org/project/forterp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+> **Software Architecture, Design & Engineering by Nicholas J. Kisseberth.**  
+> Code Synthesized via Anthropic Claude Code / Opus 4.8.  
+> Automated Code Review via OpenAI Codex / ChatGPT 5.5.
+
+A **configurable FORTRAN-66 interpreter** in Python: the machine value model and the
+front-end dialect are both pluggable, so one core runs FORTRAN against whatever
+representation you select.
+
+The value model is a `Target` — integer word width and overflow, the logical-truth
+convention, and how characters pack into words. Two ship:
+
+- **`NATIVE` (the default)** — a clean 64-bit host machine for running standard
+  FORTRAN-66 portably: 64-bit two's-complement integers, 8-bit ASCII, `.TRUE.`=1 with
+  boolean logical operators. `import forterp; forterp.run_source(...)` uses this.
+- **`PDP10`** — the DEC FORTRAN-10 model: 36-bit two's-complement words,
+  5×7-bit packed character storage, `.TRUE.`=−1 with bit-wise logicals. Select with
+  `Engine(..., target=forterp.PDP10)`.
+
+The PDP-10 target was extracted from an interpreter built to run real 1970s DEC FORTRAN
+unmodified, so it is exercised against real period code — not just toy snippets — and
+validated against the DEC FORTRAN-10 V5 manual and the **FCVS** conformance corpus.
+
+## Install
+
+```sh
+pip install forterp          # (once published)
+# or, from a checkout:
+pip install -e .
+```
+
+## Quick start
+
+```python
+import forterp
+
+# The default dialect is strict ANSI F66; FORTRAN10 enables the DEC niceties
+# (here the quoted-string FORMAT -- F66 itself uses Hollerith nH). Note fixed form:
+# the statement label sits in columns 1-5 and the body starts in column 7.
+eng = forterp.run_source('''      PROGRAM HELLO
+      WRITE(6,10)
+   10 FORMAT(' HELLO, WORLD')
+      END
+''', dialect=forterp.FORTRAN10, printer=print)
+```
+
+Lower-level building blocks (the expert surface lives under `forterp.runtime`):
+
+```python
+units = forterp.parse_source(src)              # {name: ProgramUnit}
+eng   = forterp.runtime.make_engine(units)     # Engine with the FORTRAN-10 runtime installed
+eng.run_program("MAIN")                         # or run_program() for the first unit
+```
+
+The package root exposes only the focused names above; the rest is organized into
+namespaces: `forterp.runtime` (the `Engine` and builders), `forterp.frontend` (lexer/parser
+stages), `forterp.format` (the FORMAT engine), `forterp.ast` (AST nodes), `forterp.hostlib`
+(host-builtin marshalling), and `forterp.debug` (the interactive tracer/profiler and the
+out-of-bounds census — `forterp.debug.oob_census()` counts or logs the faithful unchecked-array
+accesses without changing them).
+
+## Command line
+
+Installing puts three commands on your PATH — thin dialect front-ends over the engine
+(like `g77`/`gfortran` over gcc):
+
+```sh
+pyf66 prog.for              # run as strict ANSI FORTRAN-66 (rejects DEC extensions)
+pyfortran10 prog.for        # run as DEC FORTRAN-10 (the superset: octal, IMPLICIT, '...', …)
+forterp --std fortran10 prog.for   # general driver; --std f66|fortran10 (default: f66)
+```
+
+`--target native|pdp10|vax` selects the value model and `--program NAME` picks the main
+unit. `--check` parses and lists every diagnostic without running (a compile-check) — so
+`pyf66 --check prog.for` is a strict-ANSI-F66 conformance linter. `--version` prints the
+version, `--help` the usage. Before install, use `python -m forterp …`.
+
+Pass several source files and they are linked together by unit name, the way a compiler
+links separately-compiled units — so a driver and a separately-held library run as one program:
+
+```sh
+forterp main.for lib.for           # main.for's PROGRAM calls SUBROUTINEs in lib.for
+```
+
+Launched with **no file**, each command drops into an interactive command processor (a small,
+FORTRAN-focused descendant of the TOPS-10 `.` prompt — it operates on whole source
+files, not a statement REPL, since F66 has no incremental-execution model):
+
+```text
+f66> RUN prog.for            # compile + run (alias EXECUTE); CHECK = parse-only
+f66> SET STD fortran10       # switch dialect, target, or main unit between runs
+f10> LOAD prog.for           # parse into the session; START runs it
+f10> SHOW /BLOCK/            # inspect a COMMON block after a run; SHOW = settings
+f10> !cmd   @file   HELP   EXIT
+```
+
+The command set is identical across the three commands; only the starting dialect
+differs (`pyf66` → f66, `pyfortran10` → fortran10), and `SET STD` flips it.
+
+`IMMEDIATE` (alias `REPL`) drops into interactive FORTRAN — statements run as you type,
+a DO loop is collected across lines, and a bare expression is evaluated (so typing a
+name inspects it). After a `LOAD`, the REPL can call straight into the program:
+
+```text
+f66* NFAC = 1
+f66* DO 10 I=1,5
+cont> NFAC = NFAC * I
+cont> 10 CONTINUE
+f66* NFAC                    # -> 120
+f66* ISQ(9)                  # call a function from the LOADed program -> 81
+f66* 2 + 3 * 4               # calculator -> 14
+```
+
+(`COMMON`/`EQUIVALENCE` need a full program unit — put those in a file and `LOAD` it;
+F66 has no incremental model for control flow, so the unit of work is a statement or a
+DO block, never a bare `GOTO`.)
+
+The command processor also debugs and profiles a `RUN`/`START`. `BREAK <line>` + `STEP` drop into
+a `(dbg)` prompt where you step (`step`/`next`/`cont`), backtrace (`where`), and inspect
+any expression by typing it; `TRACE` echoes each statement; `PROFILE`/`COVERAGE` report
+per-line execution counts and which lines were reached. The profiler counts *statements*
+(deterministic), not wall-clock seconds. All of it rides one off-by-default hook, so a
+plain run pays nothing:
+
+```text
+f66> BREAK 6
+f66> RUN fac.for
+-- stopped at FAC:6 (Assign)
+(dbg) NF                     # inspect a variable by name -> 1
+(dbg) where                  # backtrace -> #0 FAC:6
+(dbg) cont
+f66> PROFILE                 #    5  FAC:6   (the loop body ran 5 times)
+```
+
+## What's pluggable
+
+- **Machine target** — `forterp.Target(word_bits, chars_per_word, logical_true, bitwise_logic,
+  bits_per_char, little_endian, truth)` fixes the value model. `forterp.NATIVE` (64-bit, 8-bit
+  ASCII, boolean logicals) is the default; `forterp.PDP10` (36-bit, 5×7-bit packed, `.TRUE.`=−1,
+  bit-wise logicals) is the DEC target; `forterp.VAX` (32-bit, little-endian, low-bit
+  logical) is a *provisional, unvalidated* guess. Pass `Engine(..., target=...)`.
+- **Front-end dialect** — `forterp.FORTRAN10` (DEC extensions on) vs `forterp.F66`
+  (ANSI). Threaded through the source reader and lexer.
+- **OPEN devices** — `eng.register_device(name, handler)` plugs in special devices.
+- **Unformatted I/O codec** — `forterp.runtime.install_runtime(eng)` wires the FOROTS binary-record +
+  DEC-10 float codec used by binary `READ`/`WRITE`.
+
+## Supported language
+
+Standard FORTRAN-66 (arithmetic/logical/relational expressions, the full control-flow
+set, `DO` loops with F66 one-trip semantics, `COMMON`/`EQUIVALENCE` storage association,
+`DATA`, subprograms + `ENTRY`, statement functions), formatted + list-directed +
+unformatted I/O with the complete `FORMAT` edit-descriptor set, `ENCODE`/`DECODE`, and
+the DEC FORTRAN-10 extensions (octal literals, Hollerith, `IAND`/`IOR`/shift intrinsics,
+tab-format source, random-access `READ(u'r)`). See [`docs/`](docs/).
+
+## Examples & demos
+
+Two directories of runnable material:
+
+- **[`examples/`](examples/)** — short Python scripts showing how to *use forterp as a
+  library*: running source and capturing output, choosing a dialect or target, feeding
+  input via `readline`, and reading results back out of `COMMON`. Start with
+  [`examples/run_and_capture.py`](examples/run_and_capture.py).
+- **[`demos/`](demos/)** — genuine 1970s FORTRAN to *run through* the interpreter:
+  verbatim netlib numerical libraries (EISPACK, LINPACK, FFT, RKF45) each with a small
+  driver, DECsystem-10 sources recovered from DECUS tapes, and a 1971 Game of Life. Every
+  one is real period source, run as-is — the corpus that flushes out interpreter gaps.
+
+## Tests & lint
+
+```sh
+pip install -e ".[dev]"
+pytest
+ruff check           # lint (config in pyproject.toml)
+ruff format --check  # formatting — run `ruff format` to apply
+```
+
+The suite is the interpreter's unit tests plus the **FCVS** (FORTRAN Compiler Validation
+System) conformance corpus — the standard-conformance audits — exercised through the
+real source-reader → lexer → parser → engine pipeline.
+
+## Security & trust model
+
+forterp is an **interpreter, not a sandbox**. A program it runs executes with the full
+privileges of the invoking process: FORTRAN `OPEN`/`READ`/`WRITE` reach the real
+filesystem, and an absolute path or one containing `..` reads or writes files *outside*
+the `save_root` base directory. There is no network access, Python `eval`, or subprocess
+reachable from a FORTRAN program — but file access alone means **you should not run
+untrusted source expecting containment.** To run code you don't trust, confine the process
+at the OS level (an unprivileged user, a container, a read-only filesystem, seccomp).
+
+Two guards keep an accidental or hostile program from taking down the host, each raising a
+clean error rather than hanging or OOM-ing: a statement budget (`eng.max_steps`, default
+50M) bounds execution, and `max_array_words` (default 50M, settable on the `Engine` /
+`make_engine`) bounds array/`COMMON` allocation — including DATA repetition counts and
+EQUIVALENCE extension, not just a bare `DIMENSION`. `INCLUDE` resolves only within its base
+directory (the CLI uses the source file's own directory; the library default is the current
+directory), and its `'FILE/SWITCH'` target is split on `/`, so it cannot escape via an
+absolute or `..` path. These bound resource use; they are not a security sandbox — file
+access via `OPEN` is unrestricted, so still confine genuinely untrusted source at the OS
+level.
+
+The interactive command processor additionally offers a `!` shell escape and `@file` command scripts
+(not reachable from a running FORTRAN program); these run with your shell's privileges, so
+treat a command script as trusted input and don't wire the command processor to an untrusted source.
+
+## Authorship & attribution
+
+- Software Architecture, Design & Engineering by Nicholas J. Kisseberth.
+- Code Synthesized via Anthropic Claude Code / Opus 4.8.
+- Automated Code Review via OpenAI Codex / ChatGPT 5.5.
+
+## License
+
+© 2026 Nicholas J. Kisseberth · forterp is [MIT-licensed](LICENSE).

forterp-0.1.0/README.md

@@ -0,0 +1,222 @@
+# forterp
+
+[![Tests](https://github.com/nyxcraft/forterp/actions/workflows/tests.yml/badge.svg)](https://github.com/nyxcraft/forterp/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/forterp.svg)](https://pypi.org/project/forterp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/forterp.svg)](https://pypi.org/project/forterp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+> **Software Architecture, Design & Engineering by Nicholas J. Kisseberth.**  
+> Code Synthesized via Anthropic Claude Code / Opus 4.8.  
+> Automated Code Review via OpenAI Codex / ChatGPT 5.5.
+
+A **configurable FORTRAN-66 interpreter** in Python: the machine value model and the
+front-end dialect are both pluggable, so one core runs FORTRAN against whatever
+representation you select.
+
+The value model is a `Target` — integer word width and overflow, the logical-truth
+convention, and how characters pack into words. Two ship:
+
+- **`NATIVE` (the default)** — a clean 64-bit host machine for running standard
+  FORTRAN-66 portably: 64-bit two's-complement integers, 8-bit ASCII, `.TRUE.`=1 with
+  boolean logical operators. `import forterp; forterp.run_source(...)` uses this.
+- **`PDP10`** — the DEC FORTRAN-10 model: 36-bit two's-complement words,
+  5×7-bit packed character storage, `.TRUE.`=−1 with bit-wise logicals. Select with
+  `Engine(..., target=forterp.PDP10)`.
+
+The PDP-10 target was extracted from an interpreter built to run real 1970s DEC FORTRAN
+unmodified, so it is exercised against real period code — not just toy snippets — and
+validated against the DEC FORTRAN-10 V5 manual and the **FCVS** conformance corpus.
+
+## Install
+
+```sh
+pip install forterp          # (once published)
+# or, from a checkout:
+pip install -e .
+```
+
+## Quick start
+
+```python
+import forterp
+
+# The default dialect is strict ANSI F66; FORTRAN10 enables the DEC niceties
+# (here the quoted-string FORMAT -- F66 itself uses Hollerith nH). Note fixed form:
+# the statement label sits in columns 1-5 and the body starts in column 7.
+eng = forterp.run_source('''      PROGRAM HELLO
+      WRITE(6,10)
+   10 FORMAT(' HELLO, WORLD')
+      END
+''', dialect=forterp.FORTRAN10, printer=print)
+```
+
+Lower-level building blocks (the expert surface lives under `forterp.runtime`):
+
+```python
+units = forterp.parse_source(src)              # {name: ProgramUnit}
+eng   = forterp.runtime.make_engine(units)     # Engine with the FORTRAN-10 runtime installed
+eng.run_program("MAIN")                         # or run_program() for the first unit
+```
+
+The package root exposes only the focused names above; the rest is organized into
+namespaces: `forterp.runtime` (the `Engine` and builders), `forterp.frontend` (lexer/parser
+stages), `forterp.format` (the FORMAT engine), `forterp.ast` (AST nodes), `forterp.hostlib`
+(host-builtin marshalling), and `forterp.debug` (the interactive tracer/profiler and the
+out-of-bounds census — `forterp.debug.oob_census()` counts or logs the faithful unchecked-array
+accesses without changing them).
+
+## Command line
+
+Installing puts three commands on your PATH — thin dialect front-ends over the engine
+(like `g77`/`gfortran` over gcc):
+
+```sh
+pyf66 prog.for              # run as strict ANSI FORTRAN-66 (rejects DEC extensions)
+pyfortran10 prog.for        # run as DEC FORTRAN-10 (the superset: octal, IMPLICIT, '...', …)
+forterp --std fortran10 prog.for   # general driver; --std f66|fortran10 (default: f66)
+```
+
+`--target native|pdp10|vax` selects the value model and `--program NAME` picks the main
+unit. `--check` parses and lists every diagnostic without running (a compile-check) — so
+`pyf66 --check prog.for` is a strict-ANSI-F66 conformance linter. `--version` prints the
+version, `--help` the usage. Before install, use `python -m forterp …`.
+
+Pass several source files and they are linked together by unit name, the way a compiler
+links separately-compiled units — so a driver and a separately-held library run as one program:
+
+```sh
+forterp main.for lib.for           # main.for's PROGRAM calls SUBROUTINEs in lib.for
+```
+
+Launched with **no file**, each command drops into an interactive command processor (a small,
+FORTRAN-focused descendant of the TOPS-10 `.` prompt — it operates on whole source
+files, not a statement REPL, since F66 has no incremental-execution model):
+
+```text
+f66> RUN prog.for            # compile + run (alias EXECUTE); CHECK = parse-only
+f66> SET STD fortran10       # switch dialect, target, or main unit between runs
+f10> LOAD prog.for           # parse into the session; START runs it
+f10> SHOW /BLOCK/            # inspect a COMMON block after a run; SHOW = settings
+f10> !cmd   @file   HELP   EXIT
+```
+
+The command set is identical across the three commands; only the starting dialect
+differs (`pyf66` → f66, `pyfortran10` → fortran10), and `SET STD` flips it.
+
+`IMMEDIATE` (alias `REPL`) drops into interactive FORTRAN — statements run as you type,
+a DO loop is collected across lines, and a bare expression is evaluated (so typing a
+name inspects it). After a `LOAD`, the REPL can call straight into the program:
+
+```text
+f66* NFAC = 1
+f66* DO 10 I=1,5
+cont> NFAC = NFAC * I
+cont> 10 CONTINUE
+f66* NFAC                    # -> 120
+f66* ISQ(9)                  # call a function from the LOADed program -> 81
+f66* 2 + 3 * 4               # calculator -> 14
+```
+
+(`COMMON`/`EQUIVALENCE` need a full program unit — put those in a file and `LOAD` it;
+F66 has no incremental model for control flow, so the unit of work is a statement or a
+DO block, never a bare `GOTO`.)
+
+The command processor also debugs and profiles a `RUN`/`START`. `BREAK <line>` + `STEP` drop into
+a `(dbg)` prompt where you step (`step`/`next`/`cont`), backtrace (`where`), and inspect
+any expression by typing it; `TRACE` echoes each statement; `PROFILE`/`COVERAGE` report
+per-line execution counts and which lines were reached. The profiler counts *statements*
+(deterministic), not wall-clock seconds. All of it rides one off-by-default hook, so a
+plain run pays nothing:
+
+```text
+f66> BREAK 6
+f66> RUN fac.for
+-- stopped at FAC:6 (Assign)
+(dbg) NF                     # inspect a variable by name -> 1
+(dbg) where                  # backtrace -> #0 FAC:6
+(dbg) cont
+f66> PROFILE                 #    5  FAC:6   (the loop body ran 5 times)
+```
+
+## What's pluggable
+
+- **Machine target** — `forterp.Target(word_bits, chars_per_word, logical_true, bitwise_logic,
+  bits_per_char, little_endian, truth)` fixes the value model. `forterp.NATIVE` (64-bit, 8-bit
+  ASCII, boolean logicals) is the default; `forterp.PDP10` (36-bit, 5×7-bit packed, `.TRUE.`=−1,
+  bit-wise logicals) is the DEC target; `forterp.VAX` (32-bit, little-endian, low-bit
+  logical) is a *provisional, unvalidated* guess. Pass `Engine(..., target=...)`.
+- **Front-end dialect** — `forterp.FORTRAN10` (DEC extensions on) vs `forterp.F66`
+  (ANSI). Threaded through the source reader and lexer.
+- **OPEN devices** — `eng.register_device(name, handler)` plugs in special devices.
+- **Unformatted I/O codec** — `forterp.runtime.install_runtime(eng)` wires the FOROTS binary-record +
+  DEC-10 float codec used by binary `READ`/`WRITE`.
+
+## Supported language
+
+Standard FORTRAN-66 (arithmetic/logical/relational expressions, the full control-flow
+set, `DO` loops with F66 one-trip semantics, `COMMON`/`EQUIVALENCE` storage association,
+`DATA`, subprograms + `ENTRY`, statement functions), formatted + list-directed +
+unformatted I/O with the complete `FORMAT` edit-descriptor set, `ENCODE`/`DECODE`, and
+the DEC FORTRAN-10 extensions (octal literals, Hollerith, `IAND`/`IOR`/shift intrinsics,
+tab-format source, random-access `READ(u'r)`). See [`docs/`](docs/).
+
+## Examples & demos
+
+Two directories of runnable material:
+
+- **[`examples/`](examples/)** — short Python scripts showing how to *use forterp as a
+  library*: running source and capturing output, choosing a dialect or target, feeding
+  input via `readline`, and reading results back out of `COMMON`. Start with
+  [`examples/run_and_capture.py`](examples/run_and_capture.py).
+- **[`demos/`](demos/)** — genuine 1970s FORTRAN to *run through* the interpreter:
+  verbatim netlib numerical libraries (EISPACK, LINPACK, FFT, RKF45) each with a small
+  driver, DECsystem-10 sources recovered from DECUS tapes, and a 1971 Game of Life. Every
+  one is real period source, run as-is — the corpus that flushes out interpreter gaps.
+
+## Tests & lint
+
+```sh
+pip install -e ".[dev]"
+pytest
+ruff check           # lint (config in pyproject.toml)
+ruff format --check  # formatting — run `ruff format` to apply
+```
+
+The suite is the interpreter's unit tests plus the **FCVS** (FORTRAN Compiler Validation
+System) conformance corpus — the standard-conformance audits — exercised through the
+real source-reader → lexer → parser → engine pipeline.
+
+## Security & trust model
+
+forterp is an **interpreter, not a sandbox**. A program it runs executes with the full
+privileges of the invoking process: FORTRAN `OPEN`/`READ`/`WRITE` reach the real
+filesystem, and an absolute path or one containing `..` reads or writes files *outside*
+the `save_root` base directory. There is no network access, Python `eval`, or subprocess
+reachable from a FORTRAN program — but file access alone means **you should not run
+untrusted source expecting containment.** To run code you don't trust, confine the process
+at the OS level (an unprivileged user, a container, a read-only filesystem, seccomp).
+
+Two guards keep an accidental or hostile program from taking down the host, each raising a
+clean error rather than hanging or OOM-ing: a statement budget (`eng.max_steps`, default
+50M) bounds execution, and `max_array_words` (default 50M, settable on the `Engine` /
+`make_engine`) bounds array/`COMMON` allocation — including DATA repetition counts and
+EQUIVALENCE extension, not just a bare `DIMENSION`. `INCLUDE` resolves only within its base
+directory (the CLI uses the source file's own directory; the library default is the current
+directory), and its `'FILE/SWITCH'` target is split on `/`, so it cannot escape via an
+absolute or `..` path. These bound resource use; they are not a security sandbox — file
+access via `OPEN` is unrestricted, so still confine genuinely untrusted source at the OS
+level.
+
+The interactive command processor additionally offers a `!` shell escape and `@file` command scripts
+(not reachable from a running FORTRAN program); these run with your shell's privileges, so
+treat a command script as trusted input and don't wire the command processor to an untrusted source.
+
+## Authorship & attribution
+
+- Software Architecture, Design & Engineering by Nicholas J. Kisseberth.
+- Code Synthesized via Anthropic Claude Code / Opus 4.8.
+- Automated Code Review via OpenAI Codex / ChatGPT 5.5.
+
+## License
+
+© 2026 Nicholas J. Kisseberth · forterp is [MIT-licensed](LICENSE).