qubasic 0.12.0__tar.gz → 0.14.0__tar.gz

{qubasic-0.12.0 → qubasic-0.14.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.14.0 (2026-06-19)
+
+Second audit-gap round: a complete agent contract, BASIC truth values, range
+comparisons, louder mid-circuit-bit handling, string-array defaults, and lazy
+density inspection. The quantum engine is unchanged.
+
+### Added
+- `qubasic --spec` now reports the full language surface: a `statements` section (QFT, MEAS, SYNDROME, EVOLVE, QADD, CTRL/INV, the control-flow keywords, ...) alongside commands, each with a `signature` field, plus `true_value: -1`.
+- `DIM s$(n)` declares a string array; unread elements default to `""` instead of `0.0`.
+
+### Changed
+- Comparisons return BASIC truth values: `-1` for true, `0` for false (so `LET t = (a > b)` is `-1`).
+- Comparison chaining is Python-style, so `0 <= x <= 10` reads as `(0 <= x) AND (x <= 10)`.
+- Reading a mid-circuit measurement bit (`MEAS`/`SYNDROME -> var`) in a classical expression now raises a clear error instead of silently using the placeholder 0; `IF <bit>` feedforward is unaffected.
+- `DENSITY` solves the density matrix lazily, on demand, instead of on every measured `SET_DENSITY` run.
+
+## 0.13.0 (2026-06-19)
+
+Closes the remaining audit gaps in the classic-BASIC layer (conventions,
+inspection, and an agent contract). The quantum engine is unchanged.
+
+### Added
+- `qubasic --spec` emits a machine-readable JSON contract (version, commands with arg flag and one-line help, gates, functions, constants, bit order) so an agent can load the exact surface of the installed version.
+- `REDIM PRESERVE name(n)` keeps existing elements; plain `REDIM` clears to zeros (QBASIC semantics).
+- `DENSITY` shows the density matrix after a measured `SET_DENSITY` run, not only a no-MEASURE one.
+
+### Changed
+- `DIM` uses inclusive sizing: `DIM a(n)` spans indices base..n (the declared top index is valid), matching QBASIC instead of the previous C-style element count.
+- `round()` rounds half away from zero (`round(2.5)` = 3), not Python's banker's rounding.
+- `STR$(n)` reserves a leading space for non-negative numbers (`STR$(42)` = " 42").
+- A chained comparison such as `a < b < c` now raises a clear "ambiguous" error instead of silently using Python chaining; write `(a < b) AND (b < c)`.
+- `PRINT`ing a mid-circuit measurement bit (`MEAS`/`SYNDROME -> var`) shows "mid-circuit bit, resolved per shot" rather than the placeholder 0.
+
 ## 0.12.0 (2026-06-19)
 
 Correctness and robustness pass on the classic-BASIC layer, from an extended

{qubasic-0.12.0/qubasic.egg-info → qubasic-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.12.0
+Version: 0.14.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -78,6 +78,7 @@ python -m qubasic_core         Same, without installing
 qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
+qubasic --spec                Print a JSON contract (commands, gates, functions)
 qubasic --help                Show CLI help
 ```
 
@@ -244,7 +245,7 @@ Functions and keywords are case-insensitive (`SQRT` and `sqrt` both work).
 
 ### Operators
 Arithmetic: `+`, `-`, `*`, `/`, `//`, `%`, `**`
-Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=`
+Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=` (yield -1 for true, 0 for false; chain Python-style, so `0 <= x <= 10` works)
 Logical: `AND`, `OR`, `NOT`, `XOR`
 Bitwise: `AND`, `OR`, `XOR` on integers (`6 AND 3` = 2); `NOT` is logical
 Hex/binary literals: `&HFF`, `&B10110`
@@ -256,12 +257,13 @@ DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
 LET names$(0) = "alice" String array (name$ elements hold strings)
-REDIM data(20)          Resize (preserves existing data)
+REDIM data(20)          Resize, clearing to zeros
+REDIM PRESERVE data(20) Resize, keeping existing data
 ERASE data              Delete array
 OPTION BASE 1           Set array index base
 ```
 
-A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
+`DIM a(n)` is inclusive: it spans indices base..n, so the declared top index is valid. A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
 
 ## Control flow
 

{qubasic-0.12.0 → qubasic-0.14.0}/README.md

@@ -45,6 +45,7 @@ python -m qubasic_core         Same, without installing
 qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
+qubasic --spec                Print a JSON contract (commands, gates, functions)
 qubasic --help                Show CLI help
 ```
 
@@ -211,7 +212,7 @@ Functions and keywords are case-insensitive (`SQRT` and `sqrt` both work).
 
 ### Operators
 Arithmetic: `+`, `-`, `*`, `/`, `//`, `%`, `**`
-Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=`
+Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=` (yield -1 for true, 0 for false; chain Python-style, so `0 <= x <= 10` works)
 Logical: `AND`, `OR`, `NOT`, `XOR`
 Bitwise: `AND`, `OR`, `XOR` on integers (`6 AND 3` = 2); `NOT` is logical
 Hex/binary literals: `&HFF`, `&B10110`
@@ -223,12 +224,13 @@ DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
 LET names$(0) = "alice" String array (name$ elements hold strings)
-REDIM data(20)          Resize (preserves existing data)
+REDIM data(20)          Resize, clearing to zeros
+REDIM PRESERVE data(20) Resize, keeping existing data
 ERASE data              Delete array
 OPTION BASE 1           Set array index base
 ```
 
-A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
+`DIM a(n)` is inclusive: it spans indices base..n, so the declared top index is valid. A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
 
 ## Control flow
 

{qubasic-0.12.0 → qubasic-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qubasic"
-version = "0.12.0"
+version = "0.14.0"
 description = "Quantum BASIC Interactive Terminal"
 readme = "README.md"
 requires-python = ">=3.10"

{qubasic-0.12.0 → qubasic-0.14.0/qubasic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.12.0
+Version: 0.14.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -78,6 +78,7 @@ python -m qubasic_core         Same, without installing
 qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
+qubasic --spec                Print a JSON contract (commands, gates, functions)
 qubasic --help                Show CLI help
 ```
 
@@ -244,7 +245,7 @@ Functions and keywords are case-insensitive (`SQRT` and `sqrt` both work).
 
 ### Operators
 Arithmetic: `+`, `-`, `*`, `/`, `//`, `%`, `**`
-Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=`
+Comparison: `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=` (yield -1 for true, 0 for false; chain Python-style, so `0 <= x <= 10` works)
 Logical: `AND`, `OR`, `NOT`, `XOR`
 Bitwise: `AND`, `OR`, `XOR` on integers (`6 AND 3` = 2); `NOT` is logical
 Hex/binary literals: `&HFF`, `&B10110`
@@ -256,12 +257,13 @@ DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
 LET names$(0) = "alice" String array (name$ elements hold strings)
-REDIM data(20)          Resize (preserves existing data)
+REDIM data(20)          Resize, clearing to zeros
+REDIM PRESERVE data(20) Resize, keeping existing data
 ERASE data              Delete array
 OPTION BASE 1           Set array index base
 ```
 
-A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
+`DIM a(n)` is inclusive: it spans indices base..n, so the declared top index is valid. A `DIM`med array enforces its declared bounds on write; an undimensioned array grows on first assignment.
 
 ## Control flow
 

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/__init__.py

@@ -28,7 +28,7 @@ __all__ = [
     'GATE_TABLE', 'GATE_ALIASES',
 ]
 
-__version__ = '0.12.0'
+__version__ = '0.14.0'
 
 def __getattr__(name):
     """Lazy import heavy modules on first access."""

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/analysis.py

@@ -109,9 +109,12 @@ class AnalysisMixin:
 
     def cmd_density(self, rest: str = '') -> None:
         """Show density matrix (DENSITY [reg]); summarizes for large systems."""
-        # A mixed state set via SET_DENSITY has a stored density matrix and no
-        # statevector; display it directly.
+        # A mixed state set via SET_DENSITY has no statevector; solve its
+        # density matrix on demand (cached) from the captured circuit.
         dm = getattr(self, '_last_density', None)
+        if dm is None and getattr(self, '_last_density_qc', None) is not None:
+            dm = self._density_from_qc(self._last_density_qc)
+            self._last_density = dm
         if dm is not None and not rest.strip():
             rho = np.ascontiguousarray(dm)
             dim = rho.shape[0]

qubasic-0.14.0/qubasic_core/cli.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+QUBASIC — command-line entry point.
+
+Usage:
+    qubasic                       Interactive REPL (installed console script)
+    python -m qubasic_core        Same, run as a module
+    qubasic script.qb             Run a script file
+"""
+
+import sys
+import os
+
+# Force UTF-8 output on Windows
+if sys.stdout and hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+if sys.stderr and hasattr(sys.stderr, 'reconfigure'):
+    try:
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+from qubasic_core.terminal import QBasicTerminal
+from qubasic_core.program_mgmt import ProgramMgmtMixin
+
+# Statement-level operations that are parsed inline rather than dispatched as
+# REPL commands or gates, so they are absent from the command tables and the
+# gate table. Listed in --spec (name, signature, description) for agents.
+_SPEC_STATEMENTS = [
+    ('MEAS', 'MEAS <qubit> -> <bit>', 'mid-circuit measurement into a classical bit (drives IF feedforward)'),
+    ('MEASURE', 'MEASURE [qubit list]', 'measure all qubits, or a subset, into the result histogram'),
+    ('MEASURE_X', 'MEASURE_X <qubit>', 'measure in the X basis (result in mx_<q>)'),
+    ('MEASURE_Y', 'MEASURE_Y <qubit>', 'measure in the Y basis (result in my_<q>)'),
+    ('MEASURE_Z', 'MEASURE_Z <qubit>', 'measure in the Z basis (result in mz_<q>)'),
+    ('SYNDROME', 'SYNDROME <paulis> <qubits> -> <var>', 'non-destructive stabilizer measurement via an ancilla'),
+    ('RESET', 'RESET <qubit>', 'reset a qubit to |0>'),
+    ('BARRIER', 'BARRIER', 'optimization barrier'),
+    ('QFT', 'QFT <lo>-<hi>', 'quantum Fourier transform over a qubit range'),
+    ('IQFT', 'IQFT <lo>-<hi>', 'inverse quantum Fourier transform'),
+    ('DIFFUSE', 'DIFFUSE <lo>-<hi>', 'Grover diffusion operator'),
+    ('MCX', 'MCX <ctrl,...>, <target>', 'multi-controlled X'),
+    ('MCZ', 'MCZ <ctrl,...>', 'multi-controlled Z'),
+    ('MCP', 'MCP <theta>, <ctrl,...>, <target>', 'multi-controlled phase'),
+    ('QADD', 'QADD <a-range>, <b-range>', 'in-place register add A += B (mod 2^n)'),
+    ('QADDC', 'QADDC <k>, <range>', 'in-place constant add A += k (mod 2^n)'),
+    ('QPE', 'QPE <range> <target> <UGATE>', 'quantum phase estimation of a unitary'),
+    ('AMPLIFY', 'AMPLIFY <marked>', 'one amplitude-amplification (Grover) step'),
+    ('GRAPHSTATE', 'GRAPHSTATE <a-b, b-c, ...>', 'prepare a graph/cluster state'),
+    ('FEATUREMAP', 'FEATUREMAP <x0> <x1> ...', 'ZZ feature-map data encoding'),
+    ('EVOLVE', 'EVOLVE <H>, <time>, <steps>', 'Trotterized Hamiltonian time evolution'),
+    ('APPLYCHANNEL', 'APPLYCHANNEL <name> <qubit>', 'apply a defined Kraus channel'),
+    ('SAVE_EXPECT', 'SAVE_EXPECT <obs> <qubits> -> <var>', 'record an expectation value into a variable after RUN'),
+    ('SAVE_PROBS', 'SAVE_PROBS <qubits> -> <array>', 'record a probability snapshot into an array after RUN'),
+    ('SAVE_AMPS', 'SAVE_AMPS <lo>,<hi> -> <array>', 'record amplitudes into an array after RUN'),
+    ('CTRL', 'CTRL <gate> <ctrl>, <target>', 'controlled version of any gate'),
+    ('INV', 'INV <gate> <args>', 'inverse/dagger of a gate'),
+    ('UNITARY', 'UNITARY <NAME> = [[...]]', 'define a custom gate from a unitary matrix'),
+    ('GOTO', 'GOTO <line>', 'jump to a line number'),
+    ('GOSUB', 'GOSUB <line>', 'call a line block; RETURN resumes'),
+    ('FOR', 'FOR <v> = <a> TO <b> [STEP <s>]', 'counted loop, closed by NEXT'),
+    ('WHILE', 'WHILE <cond>', 'pre-test loop, closed by WEND'),
+    ('DO', 'DO [WHILE|UNTIL <cond>]', 'loop, closed by LOOP [WHILE|UNTIL]'),
+    ('IF', 'IF <cond> THEN <stmt> [ELSE <stmt>]', 'conditional (single-line, or block ending in END IF)'),
+    ('SELECT', 'SELECT CASE <expr>', 'multi-way branch (CASE / CASE ELSE / END SELECT)'),
+    ('DATA', 'DATA <v1>, <v2>, ...', 'inline data consumed by READ'),
+    ('READ', 'READ <var>, ...', 'read the next DATA values'),
+    ('DEF', 'DEF <NAME>[(p)] = <gates>', 'define a gate-sequence subroutine (also DEF FN, DEF BEGIN)'),
+    ('SUB', 'SUB <name>(<args>)', 'structured subroutine (END SUB; LOCAL/STATIC/SHARED)'),
+    ('FUNCTION', 'FUNCTION <name>(<args>)', 'function returning a value (END FUNCTION)'),
+    ('DIM', 'DIM <name>(<size>[,...])', 'declare an array (name$ for strings; inclusive sizing)'),
+    ('REDIM', 'REDIM [PRESERVE] <name>(<size>)', 'resize an array; PRESERVE keeps existing data'),
+]
+
+
+def run_script(path: str, terminal: 'QBasicTerminal') -> None:
+    """Run a .qb script file. Supports multi-line DEF blocks.
+
+    After loading all lines, auto-runs the program if it contains
+    numbered lines with a MEASURE statement.
+    """
+    with open(path, 'r') as f:
+        lines = [l.rstrip('\n\r') for l in f.readlines()]
+    ProgramMgmtMixin._load_lines_with_defs(
+        lines, lambda line: terminal.process(line, track_undo=False))
+
+    # Auto-run if the program has a reachable MEASURE (incl. in subs / IF
+    # clauses), unless the script already issued an explicit RUN (which would
+    # otherwise execute and print the program twice).
+    explicit_run = any(l.strip().upper() == 'RUN' for l in lines)
+    if (terminal.program and not explicit_run
+            and terminal._program_has_measure(sorted(terminal.program))):
+        terminal.cmd_run()
+
+
+def main():
+    import json as _json
+    os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
+
+    from qubasic_core import __version__
+
+    args = sys.argv[1:]
+    quiet = '--quiet' in args or '-q' in args
+    json_mode = '--json' in args
+    agent_mode = '--agent' in args
+    spec_mode = '--spec' in args
+    seed_val = None
+    for flag in ('--quiet', '-q', '--json', '--agent', '--spec'):
+        args = [a for a in args if a != flag]
+    # Parse --seed N
+    filtered = []
+    i = 0
+    while i < len(args):
+        if args[i] == '--seed' and i + 1 < len(args):
+            seed_val = int(args[i + 1])
+            i += 2
+        else:
+            filtered.append(args[i])
+            i += 1
+    args = filtered
+
+    if any(a in ('-v', '--version') for a in args):
+        print(f"QUBASIC {__version__}")
+        sys.exit(0)
+
+    if any(a in ('-h', '--help') for a in args):
+        print(f"QUBASIC {__version__} — Quantum BASIC Interactive Terminal")
+        print()
+        print("Usage:")
+        print("  qubasic                  Interactive REPL")
+        print("  qubasic script.qb        Run a script file")
+        print("  qubasic --quiet script    Suppress banner and progress (also -q)")
+        print("  qubasic --json script     Output results as JSON")
+        print("  qubasic --agent script    Confine file writes to the working dir")
+        print("  qubasic --seed N script   Set random seed for reproducibility")
+        print("  qubasic --version         Show version (also -v)")
+        print("  qubasic --help            Show this help (also -h)")
+        print("  python -m qubasic_core    Run without the installed console script")
+        print()
+        print("Type HELP inside the REPL for full command reference.")
+        sys.exit(0)
+
+    if spec_mode:
+        # Machine-readable contract for agents: commands, gates, functions,
+        # constants, and conventions for the installed version.
+        from qubasic_core.engine import GATE_TABLE
+        from qubasic_core.expression import ExpressionMixin
+
+        def _doc_parts(mname):
+            doc = (getattr(getattr(QBasicTerminal, mname, None), '__doc__', '') or '').strip()
+            line = doc.split('\n')[0].strip()
+            # Docstrings format the first line as "SIGNATURE — description".
+            for sep in ('—', ' - '):
+                if sep in line:
+                    sig, _, hlp = line.partition(sep)
+                    return sig.strip(), hlp.strip()
+            return '', line
+
+        cmds = []
+        for tbl, takes in ((QBasicTerminal._CMD_WITH_ARG, True),
+                           (QBasicTerminal._CMD_NO_ARG, False)):
+            for cname, mname in tbl.items():
+                sig, hlp = _doc_parts(mname)
+                cmds.append({'name': cname, 'takes_arg': takes,
+                             'signature': sig or cname, 'help': hlp})
+        statements = [{'name': n, 'signature': s, 'help': h}
+                      for (n, s, h) in _SPEC_STATEMENTS]
+        spec = {
+            'name': 'qubasic',
+            'version': __version__,
+            'bit_order': 'little-endian (qubit 0 = rightmost bit)',
+            'true_value': -1,
+            'commands': sorted(cmds, key=lambda c: c['name']),
+            'statements': sorted(statements, key=lambda s: s['name']),
+            'gates': sorted(GATE_TABLE.keys()),
+            'functions': sorted(
+                set(ExpressionMixin._SAFE_FUNCS)
+                | {'RND', 'TIMER', 'POS', 'PEEK', 'USR', 'EOF', 'FRE',
+                   'LEFT$', 'RIGHT$', 'MID$', 'CHR$', 'STR$', 'HEX$', 'BIN$',
+                   'ASC', 'VAL', 'INSTR', 'LEN'}),
+            'constants': sorted(ExpressionMixin._SAFE_CONSTS.keys()),
+        }
+        print(_json.dumps(spec, indent=2))
+        sys.exit(0)
+
+    term = QBasicTerminal()
+    # JSON mode implies agent use, so confine file writes to the working dir.
+    term.agent_mode = agent_mode or json_mode
+    if seed_val is not None:
+        import numpy as _np
+        term._seed = seed_val
+        _np.random.seed(seed_val)
+
+    if args:
+        path = args[0]
+        if not os.path.isfile(path):
+            if json_mode:
+                print(_json.dumps({'error': f'FILE NOT FOUND: {path}'}, indent=2))
+            else:
+                print(f"?FILE NOT FOUND: {path}")
+            sys.exit(1)
+        if quiet or json_mode:
+            import io
+            buf = io.StringIO()
+            old = sys.stdout
+            sys.stdout = buf
+            err = None
+            try:
+                run_script(path, term)
+            except Exception as e:  # surface as structured error in JSON mode
+                err = str(e)
+            finally:
+                sys.stdout = old
+            if json_mode:
+                if err is not None:
+                    print(_json.dumps({'error': err}, indent=2))
+                    sys.exit(1)
+                print(_json.dumps(term.result(), indent=2))
+            else:
+                # --quiet (no --json): the banner was never emitted into the
+                # buffer (only the non-captured path calls print_banner), so the
+                # captured text is exactly the results. Print them, matching the
+                # documented "suppress banner, output results only" behavior.
+                print(buf.getvalue(), end='')
+                if err is not None:
+                    print(f"?ERROR: {err}")
+                    sys.exit(1)
+        else:
+            term.print_banner()
+            run_script(path, term)
+        # Exit 0 on success; 1 if a measured program produced no counts.
+        expects_measure = bool(term.program) and term._program_has_measure(sorted(term.program))
+        sys.exit(0 if term.last_counts is not None or not expects_measure else 1)
+    else:
+        term.repl()
+
+
+if __name__ == '__main__':
+    main()

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/control_flow.py

@@ -102,9 +102,10 @@ class ControlFlowMixin:
         if idx < 0:
             raise RuntimeError(f"ARRAY INDEX OUT OF RANGE: {name}({idx + base})")
         dimmed = getattr(self, '_dimmed_arrays', set())
+        fill = '' if name.endswith('$') else 0.0   # string arrays default to ""
         if name not in self.arrays:
             # Implicit array: created (and allowed to grow) on first assignment.
-            self.arrays[name] = [0.0] * (idx + 1)
+            self.arrays[name] = [fill] * (idx + 1)
         elif idx >= len(self.arrays[name]):
             if name in dimmed:
                 # Explicitly DIMmed: writes are bounds-checked like reads,
@@ -113,7 +114,7 @@ class ControlFlowMixin:
                     f"ARRAY INDEX OUT OF RANGE: {name}({idx + base}), "
                     f"size {len(self.arrays[name])}")
             while idx >= len(self.arrays[name]):
-                self.arrays[name].append(0.0)
+                self.arrays[name].append(fill)
         self.arrays[name][idx] = val
         return True, ExecResult.ADVANCE
 
@@ -184,6 +185,12 @@ class ControlFlowMixin:
         # Quoted literal: emit verbatim (no substitution, no SPC/TAB).
         if (item[0] == '"' and item[-1] == '"') or (item[0] == "'" and item[-1] == "'"):
             return item[1:-1]
+        # A mid-circuit measurement bit (MEAS/SYNDROME -> var) has no single
+        # value in standard mode; it is resolved per shot inside the if_test.
+        # Show that instead of the placeholder 0.
+        cb = getattr(self, '_classical_bits', None)
+        if cb and item in cb:
+            return f"<{item}: mid-circuit bit, resolved per shot>"
         text = self._substitute_vars(item, run_vars)
 
         def _spaces(m):

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/engine_state.py

@@ -57,8 +57,10 @@ class Engine:
         # Arrays declared with DIM/REDIM enforce their bounds on write;
         # arrays created implicitly by first assignment keep auto-growing.
         self._dimmed_arrays: set[str] = set()
-        # Density matrix captured by a no-MEASURE run with SET_DENSITY.
+        # Density matrix (and the measure-free circuit to solve it lazily)
+        # for a run with SET_DENSITY, computed on demand by DENSITY.
         self._last_density: Any = None
+        self._last_density_qc: Any = None
 
         # Subroutines and registers
         self.subroutines: dict[str, Any] = {}
@@ -119,6 +121,7 @@ class Engine:
         self._array_dims.clear()
         self._dimmed_arrays.clear()
         self._last_density = None
+        self._last_density_qc = None
         self.last_counts = None
         self.last_sv = None
         self.last_circuit = None

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/executor.py

@@ -113,8 +113,10 @@ class ExecutorMixin:
         self._classical_bits = {}
         # Partial-measurement subset (None = measure all at the end).
         self._measure_subset = None
-        # Density matrix captured by a no-MEASURE run (None unless set).
+        # Density matrix (and circuit) captured by a SET_DENSITY run; the
+        # matrix is solved lazily by DENSITY from the stored circuit.
         self._last_density = None
+        self._last_density_qc = None
         # Apply any qubit state preparation requested via POKE to $0100.
         if getattr(self, '_poke_state_prep', None):
             self._emit_poke_state_prep(qc)

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/expression.py

@@ -124,6 +124,18 @@ def _basic_xor(a: Any, b: Any) -> int:
     return _as_int(a) ^ _as_int(b)
 
 
+def _basic_round(x: Any, ndigits: Any = None) -> float:
+    """Round half away from zero (BASIC convention), not Python's half-to-even.
+
+    round(2.5) == 3, round(-2.5) == -3, round(2.345, 2) == 2.35.
+    """
+    nd = int(ndigits) if ndigits is not None else 0
+    f = 10 ** nd
+    y = float(x) * f
+    r = math.floor(y + 0.5) if y >= 0 else math.ceil(y - 0.5)
+    return (r / f) if nd else float(r)
+
+
 class ExpressionMixin:
     """AST-based safe expression evaluation. No eval().
 
@@ -138,7 +150,7 @@ class ExpressionMixin:
         # INT floors toward negative infinity, as in QBASIC (INT(-3.2) = -4).
         # FIX truncates toward zero (FIX(-3.2) = -3) for the other convention.
         'abs': abs, 'int': math.floor, 'fix': math.trunc, 'float': float,
-        'min': min, 'max': max, 'round': round, 'len': len,
+        'min': min, 'max': max, 'round': _basic_round, 'len': len,
         'ceil': math.ceil, 'floor': math.floor,
     }
     _SAFE_CONSTS = {
@@ -178,6 +190,15 @@ class ExpressionMixin:
                 return node.value
             raise ValueError(f"UNSUPPORTED CONSTANT: {node.value!r}")
         if isinstance(node, ast.Name):
+            # A mid-circuit measurement bit has no classical value (it is
+            # resolved per shot); reading it outside an IF feedforward is an
+            # error rather than a silent placeholder 0.
+            cb = getattr(self, '_classical_bits', None)
+            if cb and node.id in cb:
+                raise ValueError(
+                    f"'{node.id}' is a mid-circuit measurement bit; its value is "
+                    f"per-shot, so it can't be read in a classical expression "
+                    f"(use IF {node.id} for feedforward, or LOCC mode for a live value)")
             if node.id in ns:
                 return ns[node.id]
             raise ValueError(f"UNDEFINED: {node.id}")
@@ -203,6 +224,9 @@ class ExpressionMixin:
                 result = op(result, self._ast_eval(val, ns))
             return result
         if isinstance(node, ast.Compare):
+            # Python-style chaining (a < b < c means (a<b) and (b<c)) so range
+            # checks like 0 <= x <= 10 work as written; results use BASIC truth
+            # values (-1 for true, 0 for false).
             left = self._ast_eval(node.left, ns)
             for op_node, comparator in zip(node.ops, node.comparators):
                 op = self._AST_OPS.get(type(op_node))
@@ -210,9 +234,9 @@ class ExpressionMixin:
                     raise ValueError(f"UNSUPPORTED OP: {type(op_node).__name__}")
                 right = self._ast_eval(comparator, ns)
                 if not op(left, right):
-                    return False
+                    return 0
                 left = right
-            return True
+            return -1
         if isinstance(node, ast.Call):
             if not isinstance(node.func, ast.Name):
                 raise ValueError("ONLY SIMPLE FUNCTION CALLS ALLOWED")

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/patterns.py

@@ -17,8 +17,8 @@ RE_SHARE = re.compile(r'SHARE\s+([A-Z])\s+(\d+)\s*,?\s*([A-Z])\s+(\d+)', re.IGNO
 RE_MEAS = re.compile(r'MEAS\s+(\S+)\s*->\s*(\w+)', re.IGNORECASE)
 RE_RESET = re.compile(r'RESET\s+(\S+)', re.IGNORECASE)
 RE_UNITARY = re.compile(r'UNITARY\s+(\w+)\s*=\s*(\[.+\])', re.IGNORECASE)
-RE_DIM = re.compile(r'DIM\s+(\w+)\((\d+)\)', re.IGNORECASE)
-RE_REDIM = re.compile(r'REDIM\s+(\w+)\((\d+)\)', re.IGNORECASE)
+RE_DIM = re.compile(r'DIM\s+(\w+\$?)\((\d+)\)', re.IGNORECASE)
+RE_REDIM = re.compile(r'REDIM\s+(PRESERVE\s+)?(\w+)\((\d+)\)', re.IGNORECASE)
 RE_ERASE = re.compile(r'ERASE\s+(\w+)', re.IGNORECASE)
 RE_GET = re.compile(r'GET\s+(\w+\$?)', re.IGNORECASE)
 RE_INPUT = re.compile(r'INPUT\s+(?:"([^"]*)"\s*,\s*)?(\w+)', re.IGNORECASE)
@@ -100,7 +100,7 @@ RE_SCREEN = re.compile(r'SCREEN\s+(\d+)', re.IGNORECASE)
 RE_LPRINT = re.compile(r'LPRINT\s+(.*)', re.IGNORECASE)
 RE_ON_MEASURE = re.compile(r'ON\s+MEASURE\s+GOSUB\s+(\d+)', re.IGNORECASE)
 RE_ON_TIMER = re.compile(r'ON\s+TIMER\s*\((\d+)\)\s+GOSUB\s+(\d+)', re.IGNORECASE)
-RE_DIM_MULTI = re.compile(r'DIM\s+(\w+)\((\d+(?:\s*,\s*\d+)*)\)', re.IGNORECASE)
+RE_DIM_MULTI = re.compile(r'DIM\s+(\w+\$?)\((\d+(?:\s*,\s*\d+)*)\)', re.IGNORECASE)
 RE_LET_STR = re.compile(r'LET\s+(\w+\$)\s*=\s*(.*)', re.IGNORECASE)
 # Implicit LET: an assignment written without the LET keyword (x = 5, s$ = "hi",
 # a(1) = 5, p.x = 3). Anchored lvalue followed by a single '=' that is not part

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/strings.py

@@ -29,8 +29,11 @@ def _chr_fn(n: float) -> str:
     return chr(int(n))
 
 def _str_fn(n: float) -> str:
+    # BASIC reserves a leading space for the sign of a non-negative number,
+    # so STR$(42) is " 42" and STR$(-5) is "-5".
     v = float(n)
-    return str(int(v)) if v == int(v) else str(v)
+    s = str(int(v)) if v == int(v) else str(v)
+    return s if v < 0 else ' ' + s
 
 def _val_fn(s: str) -> float:
     try:

{qubasic-0.12.0 → qubasic-0.14.0}/qubasic_core/terminal.py

@@ -1244,6 +1244,28 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
     # it skip extraction; STATE/BLOCH then report no state.
     _SV_EXTRACT_MAX_QUBITS = 24
 
+    def _density_from_qc(self, qc_sv):
+        """Solve the density matrix of a measure-free circuit, for DENSITY.
+
+        Computed on demand (not on every run) from the circuit captured when a
+        SET_DENSITY state was prepared.
+        """
+        try:
+            q2 = qc_sv.copy()
+            q2.save_density_matrix()
+            dm_backend = self._make_backend('density_matrix', include_noise=True)
+            _kw = {}
+            if self._seed is not None:
+                _kw['seed_simulator'] = self._seed
+            res = dm_backend.run(
+                transpile(q2, dm_backend, optimization_level=self._transpile_opt_level),
+                **_kw).result()
+            data = res.data(0)
+            dm = data.get('density_matrix') if hasattr(data, 'get') else None
+            return np.array(dm) if dm is not None else None
+        except Exception:
+            return None
+
     def _extract_statevector(self, qc_sv) -> None:
         """Run the measurement-free circuit copy to get last_sv.
 
@@ -1255,7 +1277,13 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         2^n statevector that cannot be displayed anyway.
         """
         if getattr(self, '_pending_set_density', None) is not None:
-            self.last_sv = None   # mixed state: no pure statevector to extract
+            # Mixed state: no pure statevector. Defer the density-matrix solve
+            # to DENSITY (lazy) so a measured run does not pay for it unused;
+            # keep the measure-free circuit to solve from.
+            self.last_sv = None
+            self._last_density = None
+            self._last_density_qc = (qc_sv if self.num_qubits <= self._SV_EXTRACT_MAX_QUBITS
+                                     else None)
             return
         if self.num_qubits > self._SV_EXTRACT_MAX_QUBITS:
             self.last_sv = None
@@ -1300,20 +1328,12 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         """Execute the no-MEASURE path: statevector (or density matrix), no shots."""
         too_large = self.num_qubits > self._SV_EXTRACT_MAX_QUBITS
         if getattr(self, '_pending_set_density', None) is not None and not too_large:
-            # A mixed state has no statevector, so capture the density matrix
-            # for DENSITY instead. Saving a statevector here used to raise an
-            # untranslatable-circuit error from Aer.
+            # A mixed state has no statevector. Defer the density solve to
+            # DENSITY (lazy); keep the measure-free circuit. Saving a statevector
+            # here used to raise an untranslatable-circuit error from Aer.
             self.last_sv = None
-            try:
-                qc_sv.save_density_matrix()
-                dm_backend = self._make_backend('density_matrix', include_noise=True)
-                dm_result = dm_backend.run(
-                    transpile(qc_sv, dm_backend, optimization_level=self._transpile_opt_level)).result()
-                data = dm_result.data(0)
-                dm = data.get('density_matrix') if hasattr(data, 'get') else None
-                self._last_density = np.array(dm) if dm is not None else None
-            except Exception:
-                self._last_density = None
+            self._last_density = None
+            self._last_density_qc = qc_sv
         elif too_large:
             self.last_sv = None
         else:
@@ -1943,13 +1963,17 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         if not m:
             return False
         name = m.group(1)
+        base = getattr(self, '_option_base', 0)
         dims = [int(d.strip()) for d in m.group(2).split(',')]
+        # Inclusive sizing (QBASIC): DIM a(n) spans indices base..n, so the
+        # declared top index n is valid (n - base + 1 slots per dimension).
+        sizes = [max(0, d - base + 1) for d in dims]
         total = 1
-        for d in dims:
-            total *= d
-        self.arrays[name] = [0.0] * total
-        if len(dims) > 1:
-            self._array_dims[name] = dims
+        for s in sizes:
+            total *= s
+        self.arrays[name] = [('' if name.endswith('$') else 0.0)] * total
+        if len(sizes) > 1:
+            self._array_dims[name] = sizes
         self._dimmed_arrays.add(name)
         return True
 
@@ -1975,20 +1999,26 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         return True
 
     def _try_exec_redim(self, stmt: str) -> bool:
-        """Handle REDIM name(size) — resize an existing array."""
+        """Handle REDIM [PRESERVE] name(size) — resize an array.
+
+        Plain REDIM clears to zeros (QBASIC semantics); REDIM PRESERVE keeps the
+        existing elements. Sizing is inclusive (REDIM a(n) spans indices base..n).
+        """
         m = RE_REDIM.match(stmt)
         if not m:
             return False
-        name = m.group(1)
-        new_size = int(m.group(2))
+        preserve = bool(m.group(1))
+        name = m.group(2)
+        base = getattr(self, '_option_base', 0)
+        new_len = max(0, int(m.group(3)) - base + 1)
         old = self.arrays.get(name, [])
-        if isinstance(old, list):
-            if new_size > len(old):
-                self.arrays[name] = old + [0.0] * (new_size - len(old))
+        if preserve and isinstance(old, list):
+            if new_len > len(old):
+                self.arrays[name] = old + [0.0] * (new_len - len(old))
             else:
-                self.arrays[name] = old[:new_size]
+                self.arrays[name] = old[:new_len]
         else:
-            self.arrays[name] = [0.0] * new_size
+            self.arrays[name] = [0.0] * new_len
         self._dimmed_arrays.add(name)
         return True
 

{qubasic-0.12.0 → qubasic-0.14.0}/tests/test_features.py

@@ -487,8 +487,9 @@ class TestStrings(unittest.TestCase):
         self.assertEqual(_instr("HELLO", "XYZ"), 0.0)
         self.assertEqual(_hex_fn(255), "FF")
         self.assertEqual(_bin_fn(5), "101")
-        self.assertEqual(_str_fn(42.0), "42")
-        self.assertEqual(_str_fn(3.14), "3.14")
+        self.assertEqual(_str_fn(42.0), " 42")    # leading space for non-negative
+        self.assertEqual(_str_fn(3.14), " 3.14")
+        self.assertEqual(_str_fn(-5.0), "-5")
         self.assertEqual(_val_fn("42"), 42.0)
         self.assertEqual(_val_fn("abc"), 0.0)
         self.assertEqual(_len_fn("HELLO"), 5.0)
@@ -1048,7 +1049,7 @@ class TestProgramManagement(unittest.TestCase):
         _, out = capture(t_dim.cmd_run)
         self.assertIn('matrix', t_dim.arrays)
         self.assertIsInstance(t_dim.arrays['matrix'], list)
-        self.assertEqual(len(t_dim.arrays['matrix']), 9)
+        self.assertEqual(len(t_dim.arrays['matrix']), 16)  # inclusive: (0..3)^2
 
         # DIM single
         t_dim2 = QBasicTerminal()
@@ -1056,7 +1057,7 @@ class TestProgramManagement(unittest.TestCase):
         t_dim2.process('20 END')
         capture(t_dim2.cmd_run)
         self.assertIn('arr', t_dim2.arrays)
-        self.assertEqual(len(t_dim2.arrays['arr']), 5)
+        self.assertEqual(len(t_dim2.arrays['arr']), 6)   # inclusive: indices 0..5
 
         # IMPORT namespace
         with tempfile.NamedTemporaryFile(mode='w', suffix='.qb', dir='.', delete=False) as f:
@@ -2305,20 +2306,26 @@ class TestGapCoverage(unittest.TestCase):
 
     # 16 REDIM
     def test_redim(self):
-        """REDIM resizes an existing array, preserving or truncating data."""
-        # DIM first
+        """REDIM resizes (inclusive sizing); plain clears, PRESERVE keeps."""
+        # DIM a(5) spans indices 0..5 -> 6 slots (inclusive sizing).
         self.t._try_exec_dim('DIM arr(5)')
-        self.assertEqual(len(self.t.arrays['arr']), 5)
-        # REDIM larger
+        self.assertEqual(len(self.t.arrays['arr']), 6)
+        self.t.arrays['arr'][2] = 99.0
+        # Plain REDIM clears to zeros.
         self.t._try_exec_redim('REDIM arr(8)')
-        self.assertEqual(len(self.t.arrays['arr']), 8)
-        self.assertEqual(self.t.arrays['arr'][:5], [0.0] * 5)
-        # REDIM smaller
-        self.t._try_exec_redim('REDIM arr(3)')
-        self.assertEqual(len(self.t.arrays['arr']), 3)
-        # REDIM non-existent array creates it
+        self.assertEqual(len(self.t.arrays['arr']), 9)
+        self.assertEqual(self.t.arrays['arr'][2], 0.0)
+        # REDIM PRESERVE keeps existing data.
+        self.t.arrays['arr'][1] = 7.0
+        self.t._try_exec_redim('REDIM PRESERVE arr(10)')
+        self.assertEqual(len(self.t.arrays['arr']), 11)
+        self.assertEqual(self.t.arrays['arr'][1], 7.0)
+        # PRESERVE smaller truncates.
+        self.t._try_exec_redim('REDIM PRESERVE arr(3)')
+        self.assertEqual(len(self.t.arrays['arr']), 4)
+        # REDIM on a non-existent array creates it.
         self.t._try_exec_redim('REDIM newary(4)')
-        self.assertEqual(len(self.t.arrays['newary']), 4)
+        self.assertEqual(len(self.t.arrays['newary']), 5)
 
 
 # =====================================================================

{qubasic-0.12.0 → qubasic-0.14.0}/tests/test_qubasic.py

@@ -2138,7 +2138,9 @@ class TestDeepFixRegressions(unittest.TestCase):
         t.process('10 ID 0', track_undo=False)
         _, out = capture(t.cmd_run)
         self.assertNotIn('Unable to translate', out)
-        self.assertIsNotNone(getattr(t, '_last_density', None))
+        # Density is solved lazily: the measure-free circuit is captured now,
+        # and DENSITY computes the matrix on demand.
+        self.assertIsNotNone(getattr(t, '_last_density_qc', None))
         _, dout = capture(t.cmd_density, '')
         self.assertIn('Density matrix', dout)
 
@@ -2152,6 +2154,79 @@ class TestDeepFixRegressions(unittest.TestCase):
         self.assertEqual(t.eval_expr('sq(5)'), 25.0)
 
 
+class TestConventionFixesV2(unittest.TestCase):
+    """round half-away, chained-comparison guard, inclusive DIM, REDIM
+    PRESERVE, MEAS print hint, DENSITY after MEASURE."""
+
+    def setUp(self):
+        self.t = QBasicTerminal(); self.t.num_qubits = 1
+
+    def _runp(self, lines, nq=1):
+        t = QBasicTerminal(); t.num_qubits = nq
+        for l in lines:
+            t.process(l, track_undo=False)
+        _, out = capture(t.cmd_run)
+        t._out = out
+        return t
+
+    def test_round_half_away_from_zero(self):
+        self.assertEqual(self.t.eval_expr('round(2.5)'), 3.0)
+        self.assertEqual(self.t.eval_expr('round(3.5)'), 4.0)
+        self.assertEqual(self.t.eval_expr('round(-2.5)'), -3.0)
+        self.assertAlmostEqual(self.t.eval_expr('round(2.345, 2)'), 2.35)
+
+    def test_comparison_truth_and_chaining(self):
+        # Comparisons yield BASIC truth values: -1 for true, 0 for false.
+        self.assertEqual(self.t._safe_eval('3 < 5'), -1)
+        self.assertEqual(self.t._safe_eval('3 > 5'), 0)
+        # Python-style chaining, so range checks work as written.
+        self.assertEqual(self.t._safe_eval('0 <= 5 <= 10'), -1)
+        self.assertEqual(self.t._safe_eval('0 <= 50 <= 10'), 0)
+
+    def test_dim_inclusive_top_index(self):
+        t = self._runp(['10 DIM a(5)', '20 LET a(5)=7', '30 LET v=a(5)'])
+        self.assertEqual(t.variables.get('v'), 7.0)
+        t2 = self._runp(['10 DIM a(5)', '20 LET a(6)=1'])
+        self.assertIn('OUT OF RANGE', t2._out)
+
+    def test_redim_clear_vs_preserve(self):
+        t = self._runp(['10 DIM a(3)', '20 LET a(1)=9', '30 REDIM a(5)', '40 LET v=a(1)'])
+        self.assertEqual(t.variables.get('v'), 0.0)
+        t2 = self._runp(['10 DIM a(3)', '20 LET a(1)=9', '30 REDIM PRESERVE a(5)', '40 LET v=a(1)'])
+        self.assertEqual(t2.variables.get('v'), 9.0)
+
+    def test_meas_print_hint(self):
+        t = self._runp(['10 X 0', '20 MEAS 0 -> m', '30 PRINT m', '40 MEASURE'])
+        self.assertIn('mid-circuit', t._out)
+
+    def test_density_after_measure(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        t.process('SET_DENSITY [[0.5,0],[0,0.5]]', track_undo=False)
+        for l in ['10 H 0', '20 MEASURE']:
+            t.process(l, track_undo=False)
+        capture(t.cmd_run)
+        _, dout = capture(t.cmd_density, '')
+        self.assertIn('Density matrix', dout)
+
+    def test_meas_bit_classical_use_errors(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        for l in ['10 X 0', '20 MEAS 0 -> m', '30 LET y = m + 1', '40 MEASURE']:
+            t.process(l, track_undo=False)
+        _, out = capture(t.cmd_run)
+        self.assertIn('mid-circuit', out)
+
+    def test_string_array_default_empty(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        t.process('DIM s$(3)', track_undo=False)
+        self.assertEqual(t._safe_eval('s$(1)'), '')
+
+    def test_spec_statements_present(self):
+        from qubasic_core.cli import _SPEC_STATEMENTS
+        names = {n for (n, _s, _h) in _SPEC_STATEMENTS}
+        for op in ('QFT', 'MEAS', 'SYNDROME', 'EVOLVE', 'QADD'):
+            self.assertIn(op, names)
+
+
 if __name__ == '__main__':
     if hasattr(sys.stdout, 'reconfigure'):
         sys.stdout.reconfigure(encoding='utf-8')

qubasic-0.12.0/qubasic_core/cli.py

@@ -1,149 +0,0 @@
-#!/usr/bin/env python3
-"""
-QUBASIC — command-line entry point.
-
-Usage:
-    qubasic                       Interactive REPL (installed console script)
-    python -m qubasic_core        Same, run as a module
-    qubasic script.qb             Run a script file
-"""
-
-import sys
-import os
-
-# Force UTF-8 output on Windows
-if sys.stdout and hasattr(sys.stdout, 'reconfigure'):
-    try:
-        sys.stdout.reconfigure(encoding='utf-8')
-    except Exception:
-        pass
-if sys.stderr and hasattr(sys.stderr, 'reconfigure'):
-    try:
-        sys.stderr.reconfigure(encoding='utf-8')
-    except Exception:
-        pass
-
-from qubasic_core.terminal import QBasicTerminal
-from qubasic_core.program_mgmt import ProgramMgmtMixin
-
-
-def run_script(path: str, terminal: 'QBasicTerminal') -> None:
-    """Run a .qb script file. Supports multi-line DEF blocks.
-
-    After loading all lines, auto-runs the program if it contains
-    numbered lines with a MEASURE statement.
-    """
-    with open(path, 'r') as f:
-        lines = [l.rstrip('\n\r') for l in f.readlines()]
-    ProgramMgmtMixin._load_lines_with_defs(
-        lines, lambda line: terminal.process(line, track_undo=False))
-
-    # Auto-run if the program has a reachable MEASURE (incl. in subs / IF
-    # clauses), unless the script already issued an explicit RUN (which would
-    # otherwise execute and print the program twice).
-    explicit_run = any(l.strip().upper() == 'RUN' for l in lines)
-    if (terminal.program and not explicit_run
-            and terminal._program_has_measure(sorted(terminal.program))):
-        terminal.cmd_run()
-
-
-def main():
-    import json as _json
-    os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
-
-    from qubasic_core import __version__
-
-    args = sys.argv[1:]
-    quiet = '--quiet' in args or '-q' in args
-    json_mode = '--json' in args
-    agent_mode = '--agent' in args
-    seed_val = None
-    for flag in ('--quiet', '-q', '--json', '--agent'):
-        args = [a for a in args if a != flag]
-    # Parse --seed N
-    filtered = []
-    i = 0
-    while i < len(args):
-        if args[i] == '--seed' and i + 1 < len(args):
-            seed_val = int(args[i + 1])
-            i += 2
-        else:
-            filtered.append(args[i])
-            i += 1
-    args = filtered
-
-    if any(a in ('-v', '--version') for a in args):
-        print(f"QUBASIC {__version__}")
-        sys.exit(0)
-
-    if any(a in ('-h', '--help') for a in args):
-        print(f"QUBASIC {__version__} — Quantum BASIC Interactive Terminal")
-        print()
-        print("Usage:")
-        print("  qubasic                  Interactive REPL")
-        print("  qubasic script.qb        Run a script file")
-        print("  qubasic --quiet script    Suppress banner and progress (also -q)")
-        print("  qubasic --json script     Output results as JSON")
-        print("  qubasic --agent script    Confine file writes to the working dir")
-        print("  qubasic --seed N script   Set random seed for reproducibility")
-        print("  qubasic --version         Show version (also -v)")
-        print("  qubasic --help            Show this help (also -h)")
-        print("  python -m qubasic_core    Run without the installed console script")
-        print()
-        print("Type HELP inside the REPL for full command reference.")
-        sys.exit(0)
-
-    term = QBasicTerminal()
-    # JSON mode implies agent use, so confine file writes to the working dir.
-    term.agent_mode = agent_mode or json_mode
-    if seed_val is not None:
-        import numpy as _np
-        term._seed = seed_val
-        _np.random.seed(seed_val)
-
-    if args:
-        path = args[0]
-        if not os.path.isfile(path):
-            if json_mode:
-                print(_json.dumps({'error': f'FILE NOT FOUND: {path}'}, indent=2))
-            else:
-                print(f"?FILE NOT FOUND: {path}")
-            sys.exit(1)
-        if quiet or json_mode:
-            import io
-            buf = io.StringIO()
-            old = sys.stdout
-            sys.stdout = buf
-            err = None
-            try:
-                run_script(path, term)
-            except Exception as e:  # surface as structured error in JSON mode
-                err = str(e)
-            finally:
-                sys.stdout = old
-            if json_mode:
-                if err is not None:
-                    print(_json.dumps({'error': err}, indent=2))
-                    sys.exit(1)
-                print(_json.dumps(term.result(), indent=2))
-            else:
-                # --quiet (no --json): the banner was never emitted into the
-                # buffer (only the non-captured path calls print_banner), so the
-                # captured text is exactly the results. Print them, matching the
-                # documented "suppress banner, output results only" behavior.
-                print(buf.getvalue(), end='')
-                if err is not None:
-                    print(f"?ERROR: {err}")
-                    sys.exit(1)
-        else:
-            term.print_banner()
-            run_script(path, term)
-        # Exit 0 on success; 1 if a measured program produced no counts.
-        expects_measure = bool(term.program) and term._program_has_measure(sorted(term.program))
-        sys.exit(0 if term.last_counts is not None or not expects_measure else 1)
-    else:
-        term.repl()
-
-
-if __name__ == '__main__':
-    main()