Robert Allan JamesandClaude Sonnet 5
1aca77d55c
input_buffer/input_length/input_pos (include/vm.h:415-417) turned out to be plain per-VM array/scalar fields, not host pointers -- unlike almost every other input-adjacent gap in this suite. vm_parse_word (src/vm.c: 137-160) is a pure whitespace-delimited scan over them, now modelled as forth_parse_word in StarForth_Base.thy (is_ws + dropWhile/takeWhile, faithful to the C's skip-then-copy-with-truncation loop, including that input_pos only advances past a truncated token by what was actually copied, matching the C's `len < max_len - 1` bound exactly). dict_insert_entry (added last session) now takes the entry's name as a parameter instead of hardcoding the empty string. forth_constant_full composes forth_parse_word with dict_insert_entry end-to-end as a worked example: CONSTANT's real order (stack-underflow guard -> pop value -> parse name -> vm_create_word) is modelled in full up to the data-field write, which remains the one still-open gap. The other four entry-half definitions (:/CREATE/VARIABLE/DEFER) take the parsed name as a caller parameter for now rather than repeating the same composition four more times in one pass. Full suite (54 theories) verifies green. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# Isabelle/HOL Proof Suite — Coverage & Purpose
|
||
|
||
**Status:** 52 theory files under `proof/`, all verify with zero errors
|
||
(`isabelle build -D proof/`, ~35–40s full build). Covers all of
|
||
`src/word_source/*.c` (34 files) plus the 7 physics feedback loops, the
|
||
word-level ACL system, and core VM correctness/concurrency properties.
|
||
|
||
## What this proves, in one sentence
|
||
|
||
For every word in the FORTH dictionary that operates purely on modelled
|
||
per-VM state (stacks, dictionary, and the ~40 scalar fields this suite has
|
||
added to an abstract `vm_state` record as it went), the suite has a
|
||
machine-checked, literal transcription of the C implementation's stack
|
||
effect, guard conditions, and error behavior — and where a word's real
|
||
implementation reaches outside that model (raw pointers, file-scope
|
||
statics, TIB/stdio, an unmodelled subsystem like the block-window cache),
|
||
the theory says so explicitly rather than silently modelling something
|
||
else.
|
||
|
||
## Why this matters (the goal, per Bob's original framing)
|
||
|
||
Prove the StarForth VM system as close to bare metal as possible under
|
||
Isabelle/HOL, and — just as importantly — **identify precisely what cannot
|
||
be proven and why**. A clean pass/fail isn't the deliverable; the boundary
|
||
between "formally verified" and "not, for this specific reason" is. That
|
||
boundary is what `proof/FINDINGS.md` (the companion architectural write-up)
|
||
draws conclusions from.
|
||
|
||
## Structure
|
||
|
||
```
|
||
proof/
|
||
├── StarForth_Base.thy # the abstract vm_state record + shared
|
||
│ # helpers (vm_addr_ok, cell arithmetic,
|
||
│ # resolve_span, etc.) every other file builds on
|
||
├── StarForth_Correctness.thy # core interpreter properties
|
||
├── StarForth_Concurrent.thy,
|
||
│ StarForth_Mutex.thy,
|
||
│ StarForth_Transition.thy # cross-cutting VM/concurrency properties
|
||
│ # (predate this sweep, part of the earlier
|
||
│ # FABRIC-2.md item 5.2 toolchain work)
|
||
├── StarForth_Loop{1..7}_*.thy # the 7 physics feedback loops
|
||
├── StarForth_Q48_16.thy # Q48.16 fixed-point math library
|
||
├── ACL_*.thy (5 files) # word-level ACL policy properties
|
||
│ # (pin monotonicity, TTL bounds, no-escalation,
|
||
│ # inherit-clears-pin, emergency bypass)
|
||
└── StarForth_*_Words.thy (34 files) # one per src/word_source/*.c file — the
|
||
# word-by-word coverage sweep this document
|
||
# is summarizing
|
||
```
|
||
|
||
## Word-source coverage, file by file
|
||
|
||
Every `.c` file in `src/word_source/` has a matching `StarForth_*_Words.thy`,
|
||
except `q48_16_words.c` (deliberately skipped — it's the underlying Q48.16
|
||
math library, not a FORTH words file; its transcendental approximations need
|
||
numerical-analysis proofs unlike the rest of this sweep's style, and the
|
||
library itself is separately covered by `StarForth_Q48_16.thy`).
|
||
|
||
| Source file | Theory | Coverage |
|
||
|---|---|---|
|
||
| `dictionary_words.c` | `StarForth_Dictionary_Words.thy` | HERE/ALIGN/ALLOT/`,`/`C,`/`2,`/PAD/LATEST modelled; SP@/SP! unmodelled |
|
||
| `dictionary_manipulation_words.c` | `StarForth_Dictionary_Manipulation_Words.thy` | mode/flag half modelled; raw-pointer DictEntry navigation half unmodelled |
|
||
| `control_words.c` | `StarForth_Control_Words.thy` | runtime half fully modelled (BRANCH/0BRANCH/?DO/DO/LOOP/+LOOP/LEAVE/UNLOOP/I/J/EXIT); compile-time half unmodelled (file-scope statics, see FINDINGS.md §1) |
|
||
| `double_words.c` | `StarForth_Double_Words.thy` | all 20 registered words |
|
||
| `string_words.c` | `StarForth_String_Words.thy` | 10/25 (TIB/stdio/strtol clusters deferred) |
|
||
| `block_words.c` | `StarForth_Block_Words.thy` | 1/12 (SCR only; rest is the disk-backed block-window cache subsystem, its own proof project) |
|
||
| `io_words.c` | `StarForth_IO_Words.thy` | 7/9 (KEY, `."` deferred) |
|
||
| `editor_words.c` | `StarForth_Editor_Words.thy` | 0 tractable (all route through the block-window cache; EDIT is also an interactive stdin loop) |
|
||
| `format_words.c` | `StarForth_Format_Words.thy` | 17/19 (`#`/`#S` multi-precision division deferred) |
|
||
| `system_words.c` | `StarForth_System_Words.thy` | 10/16 + `(ABORT")` helper |
|
||
| `vocabulary_words.c` | `StarForth_Vocabulary_Words.thy` | 1/7 partial (entire subsystem is file-scope statics, see FINDINGS.md §1) |
|
||
| `defining_words.c` | `StarForth_Defining_Words.thy` | 4/19 full + 2 guard-only (`:`/`;`) + 4 entry-creation-half (`:`/CREATE/VARIABLE/CONSTANT, added 2026-08-14) |
|
||
| `acl_words.c` | `StarForth_ACL_Words.thy` | 7/12 (5 already covered by the pre-existing `ACL_*.thy` policy theories) |
|
||
| `dictionary_heat_diagnostic_words.c` | `StarForth_Dictionary_Heat_Diagnostic_Words.thy` | 4/6 full + 1 partial |
|
||
| `physics_freeze_words.c` | `StarForth_Physics_Freeze_Words.thy` | 6/9 |
|
||
| `physics_diagnostic_words.c` | `StarForth_Physics_Diagnostic_Words.thy` | 3/4 |
|
||
| `physics_benchmark_words.c` | `StarForth_Physics_Benchmark_Words.thy` | partial (hot-words cache unmodelled subsystem) |
|
||
| `physics_pipelining_diagnostic_words.c` | `StarForth_Physics_Pipelining_Diagnostic_Words.thy` | identity-only, explicit model-blind-spot caveat |
|
||
| `starforth_words.c` | `StarForth_StarForth_Words.thy` | 5/12 full + partial guards |
|
||
| `framebuffer_words.c`, `keyboard_words.c` | `StarForth_Framebuffer_Words.thy`, `StarForth_Keyboard_Words.thy` | hosted-build fallback branches fully modelled |
|
||
| `scroll_words.c`, `ttf_words.c` | `StarForth_Scroll_Words.thy`, `StarForth_TTF_Words.thy` | sentinel-only — words don't exist on hosted builds at all |
|
||
| `lifecycle_words_hosted.c` | `StarForth_Lifecycle_Words_Hosted.thy` | 100% — zero deferred remainder |
|
||
| `defer_words.c` | `StarForth_Defer_Words.thy` | live (see FINDINGS.md §3 correction); DEFER's entry-creation half modelled (added 2026-08-14) |
|
||
| `log_words.c` | `StarForth_Log_Words.thy` | 100% |
|
||
| `q48_words.c` | `StarForth_Q48_Words.thy` | 17/23 |
|
||
| `inference_words.c` | `StarForth_Inference_Words.thy` | 5 accessors full; rest guard/shape |
|
||
| plus: `arithmetic_words.c`, `stack_words.c`, `return_stack_words.c`, `logical_words.c`, `memory_words.c`, `mixed_arithmetic_words.c` | corresponding `StarForth_*_Words.thy` | pre-date this sweep, part of the original 23-theory FABRIC-2.md §5.2 base |
|
||
|
||
## What's structurally NOT provable without a bigger modelling project
|
||
|
||
These aren't gaps to close incrementally — each is its own subsystem-modelling
|
||
effort on the scale of what's already here:
|
||
|
||
- **The disk-backed block-window cache** (`block_subsystem.h` +
|
||
`blk_vm_lbn`/`blk_vm_cbuf`/`blk_vm_dirty`/`blk_vm_next`) — blocks
|
||
`block_words.c` and `editor_words.c` almost entirely.
|
||
- **The TIB / interactive input subsystem — partially closed 2026-08-14.**
|
||
`input_buffer`/`input_length`/`input_pos` turned out to be plain per-VM
|
||
array/scalar fields, not host pointers, and `vm_parse_word` (the
|
||
whitespace-delimited name-parse every CREATE/VARIABLE/CONSTANT/`:`/
|
||
DEFER-family word depends on) is a pure scan — now modelled as
|
||
`forth_parse_word` in `StarForth_Base.thy`, composed with
|
||
`dict_insert_entry` for CONSTANT in `StarForth_Defining_Words.thy` as a
|
||
worked example. Still blocked: words needing a *different* scan shape
|
||
over the same buffer — `(`/`\` comment (skip-to-delimiter, not
|
||
whitespace-delimited), `KEY` (single raw character, not a parsed
|
||
token), `."`/`S"` (delimiter-terminated string literal), `ABORT"`'s
|
||
compile-time half, `SEE` (raw pointer walk) — each would need its own
|
||
scan function modelled against the same fields, not automatically
|
||
unlocked by `forth_parse_word`.
|
||
- **Real stdio/file I/O** — `SAVE-SYSTEM`, parts of `string_words.c`.
|
||
- **Raw C-string/strtol-backed words** — the rest of `string_words.c`.
|
||
- **Raw-pointer DictEntry navigation** (`>BODY`/`>NAME`/CFA-style words) —
|
||
the abstract `dict_entry` model is word-id-indexed, not addressed; no
|
||
independent `dsp` register exists to model `SP@`/`SP!` against either.
|
||
- **Dictionary insertion** (`vm_create_word`, used by `:`, CREATE, VARIABLE,
|
||
CONSTANT, DEFER) — **partially closed 2026-08-14.** `dict_insert_entry`
|
||
(`StarForth_Defining_Words.thy`) now models the word_id-assignment/
|
||
dictionary-table/`latest_id`/`word_id_next`-counter portion, reused by
|
||
all five words' `forth_*_entry_half` definitions, which take the parsed
|
||
name as a caller-supplied parameter. `forth_constant_full` composes
|
||
`forth_parse_word` (the TIB gap above) in directly for CONSTANT, as a
|
||
worked example not yet repeated for the other four. Still not modelled
|
||
for any of the five: `vm->compiling_word` tracking (no vm_state field),
|
||
the data-field (DF) write each word does afterward (still gap (b)
|
||
below), and the pin-shadow name-scan guard (sidestepped via an explicit
|
||
`pinned_conflict :: bool` parameter, same technique as the XT-pop gap
|
||
elsewhere in this suite).
|
||
- **The vocabulary chain mechanics** (VOCABULARY/DEFINITIONS/CONTEXT/CURRENT/
|
||
FORTH) — file-scope statics, see FINDINGS.md §1, instance #5.
|
||
- **The hot-words cache** (`physics_benchmark_words.c`) and **the bucket/
|
||
lookup-table structure** (`REORG-BUCKETS`) — each its own subsystem.
|
||
- **Three divergent L8 mode-selector representations** — see FINDINGS.md §4.
|
||
|
||
## How to reproduce
|
||
|
||
```bash
|
||
/home/rajames/CLionProjects/Isabelle2011-1/bin/isabelle build -v -D proof/
|
||
```
|
||
|
||
(The directory is misleadingly named `Isabelle2011-1` — it's actually
|
||
Isabelle2025-2.) A clean run (no `FAILED` in the output) means every theory
|
||
in the suite verified — Isabelle sessions fail atomically, so partial
|
||
success isn't a state that exists. Full build is ~35–40s warm, ~16 minutes
|
||
cold (only relevant if the heap cache is cleared with `-c`, which should not
|
||
be done routinely — see `.claude/` session memory on this).
|
||
|
||
## Companion document
|
||
|
||
`proof/FINDINGS.md` — the cross-cutting architectural findings this sweep
|
||
surfaced (file-scope statics standing in for per-VM state, missing overflow
|
||
guards, duplicate word registration/shadowing, and several one-off findings
|
||
including a highest-severity unchecked-pointer-cast in `EXECUTE`).
|
||
|
||
*Generated 2026-08-14, commit `346c793`.*
|