qubasic 0.11.1__tar.gz → 0.13.0__tar.gz

{qubasic-0.11.1 → qubasic-0.13.0}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 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
+adversarial audit. The quantum engine is unchanged.
+
+### Fixed
+- `SHARED` variables in a `SUB` now propagate their modifications back to the caller instead of being discarded when the call's scope is restored (an accumulator across two calls now sums correctly: `8`, not `3`).
+- `RESTORE` resets the `DATA` read pointer inside a program; it was a no-op, so a `READ` after `RESTORE` raised `OUT OF DATA`.
+- Writes to an explicitly `DIM`med array are bounds-checked like reads instead of silently auto-extending past the declared size. Implicit (undimensioned) arrays still grow on first assignment.
+- String arrays work: `LET s$(i) = ...` stores and reads string elements.
+- `SET_DENSITY` followed by inspection without a `MEASURE` no longer raises a raw "unable to translate" error from Aer; the density matrix is captured and shown by `DENSITY`.
+- A script that issues an explicit `RUN` and also contains a `MEASURE` no longer auto-runs (and prints) the program a second time.
+
+### Changed
+- `STATUS` reports the user-variable count only, excluding the internal `_DEPTH`/`_GATES`/`_TIME` set after a run.
+- `DEF FN name(x) = expr` now works at the prompt (immediate mode), matching the in-program form.
+- `HELP` refreshed (`STATUS`, `INT` floors / `FIX` truncates, implicit `LET`, `<>`/`XOR`, corrected `MEAS`); `--help` notes the `-q`/`-v`/`-h` short flags and `python -m qubasic_core`.
+
 ## 0.11.1 (2026-06-19)
 
 ### Fixed

{qubasic-0.11.1/qubasic.egg-info → qubasic-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.11.1
+Version: 0.13.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
 ```
 
@@ -255,11 +256,15 @@ Hex/binary literals: `&HFF`, `&B10110`
 DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
-REDIM data(20)          Resize (preserves existing data)
+LET names$(0) = "alice" String array (name$ elements hold strings)
+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
 ```
 
+`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.11.1 → qubasic-0.13.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
 ```
 
@@ -222,11 +223,15 @@ Hex/binary literals: `&HFF`, `&B10110`
 DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
-REDIM data(20)          Resize (preserves existing data)
+LET names$(0) = "alice" String array (name$ elements hold strings)
+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
 ```
 
+`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.11.1 → qubasic-0.13.0}/pyproject.toml

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

{qubasic-0.11.1 → qubasic-0.13.0/qubasic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.11.1
+Version: 0.13.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
 ```
 
@@ -255,11 +256,15 @@ Hex/binary literals: `&HFF`, `&B10110`
 DIM data(10)            1D array
 DIM matrix(3, 3)        Multi-dimensional (flat storage)
 LET data(0) = PI
-REDIM data(20)          Resize (preserves existing data)
+LET names$(0) = "alice" String array (name$ elements hold strings)
+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
 ```
 
+`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.11.1 → qubasic-0.13.0}/qubasic_core/__init__.py

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

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/analysis.py

@@ -109,6 +109,28 @@ 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.
+        dm = getattr(self, '_last_density', None)
+        if dm is not None and not rest.strip():
+            rho = np.ascontiguousarray(dm)
+            dim = rho.shape[0]
+            self.io.writeln(f"\n  Density matrix ({dim}x{dim}):\n")
+            if dim <= 16:
+                for i in range(dim):
+                    row = []
+                    for j in range(dim):
+                        v = complex(rho[i, j])
+                        if abs(v.imag) < 1e-6:
+                            row.append(f"{v.real:7.3f}")
+                        else:
+                            row.append(f"{v.real:+.2f}{v.imag:+.2f}j")
+                    self.io.writeln(f"    {'  '.join(row)}")
+            else:
+                self.io.writeln(f"    ({dim}x{dim}, too large to display)")
+            self.io.writeln(f"\n  Purity: {float(np.real(np.trace(rho @ rho))):.6f}")
+            self.io.writeln('')
+            return
         sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
             if self.locc_mode and self.locc and not self.locc.joint:

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/cli.py

@@ -38,8 +38,12 @@ def run_script(path: str, terminal: 'QBasicTerminal') -> None:
     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)
-    if terminal.program and terminal._program_has_measure(sorted(terminal.program)):
+    # 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()
 
 
@@ -53,8 +57,9 @@ def main():
     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'):
+    for flag in ('--quiet', '-q', '--json', '--agent', '--spec'):
         args = [a for a in args if a != flag]
     # Parse --seed N
     filtered = []
@@ -78,16 +83,48 @@ def main():
         print("Usage:")
         print("  qubasic                  Interactive REPL")
         print("  qubasic script.qb        Run a script file")
-        print("  qubasic --quiet script    Suppress banner and progress")
+        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")
-        print("  qubasic --help            Show this help")
+        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 _help1(mname):
+            doc = (getattr(getattr(QBasicTerminal, mname, None), '__doc__', '') or '').strip()
+            return doc.split('\n')[0].strip()
+
+        cmds = []
+        for tbl, takes in ((QBasicTerminal._CMD_WITH_ARG, True),
+                           (QBasicTerminal._CMD_NO_ARG, False)):
+            for cname, mname in tbl.items():
+                cmds.append({'name': cname, 'takes_arg': takes, 'help': _help1(mname)})
+        spec = {
+            'name': 'qubasic',
+            'version': __version__,
+            'bit_order': 'little-endian (qubit 0 = rightmost bit)',
+            'commands': sorted(cmds, key=lambda c: c['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

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/control_flow.py

@@ -75,7 +75,11 @@ class ControlFlowMixin:
         name, idx_expr, val_expr = parsed.name, parsed.index_expr, parsed.value_expr
         self._assert_assignable(name)
         base = getattr(self, '_option_base', 0)
-        val = self._eval_with_vars(val_expr, run_vars)
+        # String arrays (name$) hold string values; numeric arrays hold floats.
+        if name.endswith('$'):
+            val = self._eval_string_expr(val_expr, run_vars)
+        else:
+            val = self._eval_with_vars(val_expr, run_vars)
         parts = self._split_arg_list(idx_expr)
         if len(parts) > 1:
             # Multi-dimensional write: flatten with the same stride convention
@@ -97,10 +101,19 @@ class ControlFlowMixin:
         idx = int(self._eval_with_vars(idx_expr, run_vars)) - base
         if idx < 0:
             raise RuntimeError(f"ARRAY INDEX OUT OF RANGE: {name}({idx + base})")
+        dimmed = getattr(self, '_dimmed_arrays', set())
         if name not in self.arrays:
+            # Implicit array: created (and allowed to grow) on first assignment.
             self.arrays[name] = [0.0] * (idx + 1)
-        while idx >= len(self.arrays[name]):
-            self.arrays[name].append(0.0)
+        elif idx >= len(self.arrays[name]):
+            if name in dimmed:
+                # Explicitly DIMmed: writes are bounds-checked like reads,
+                # instead of silently auto-extending past the declared size.
+                raise RuntimeError(
+                    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][idx] = val
         return True, ExecResult.ADVANCE
 
@@ -171,6 +184,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.11.1 → qubasic-0.13.0}/qubasic_core/engine_state.py

@@ -54,6 +54,11 @@ class Engine:
         self.variables: dict[str, Any] = {}
         self.arrays: dict[str, Any] = {}
         self._array_dims: dict[str, list[int]] = {}
+        # 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.
+        self._last_density: Any = None
 
         # Subroutines and registers
         self.subroutines: dict[str, Any] = {}
@@ -112,6 +117,8 @@ class Engine:
         self.variables.clear()
         self.arrays.clear()
         self._array_dims.clear()
+        self._dimmed_arrays.clear()
+        self._last_density = None
         self.last_counts = None
         self.last_sv = None
         self.last_circuit = None

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/executor.py

@@ -113,6 +113,8 @@ 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).
+        self._last_density = None
         # Apply any qubit state preparation requested via POKE to $0100.
         if getattr(self, '_poke_state_prep', None):
             self._emit_poke_state_prep(qc)
@@ -289,6 +291,7 @@ class ExecutorMixin:
         # 3. Remaining statement handlers (not in control-flow dispatch)
         from qubasic_core.statements import RestoreStmt
         if isinstance(parsed, RestoreStmt):
+            self._data_ptr = 0   # reset the DATA read pointer (was a no-op)
             return ExecResult.ADVANCE
 
         # Multi-line IF block markers — no-ops during execution

{qubasic-0.11.1 → qubasic-0.13.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 = {
@@ -203,16 +215,18 @@ class ExpressionMixin:
                 result = op(result, self._ast_eval(val, ns))
             return result
         if isinstance(node, ast.Compare):
-            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))
-                if op is None:
-                    raise ValueError(f"UNSUPPORTED OP: {type(op_node).__name__}")
-                right = self._ast_eval(comparator, ns)
-                if not op(left, right):
-                    return False
-                left = right
-            return True
+            # A chained comparison (a < b < c) is ambiguous: Python reads it as
+            # (a<b) and (b<c), BASIC as the left-to-right (a<b)<c. Rather than
+            # pick one silently, require it to be written explicitly.
+            if len(node.ops) > 1:
+                raise ValueError(
+                    "AMBIGUOUS CHAINED COMPARISON: write it explicitly, "
+                    "e.g. (a < b) AND (b < c)")
+            op = self._AST_OPS.get(type(node.ops[0]))
+            if op is None:
+                raise ValueError(f"UNSUPPORTED OP: {type(node.ops[0]).__name__}")
+            return op(self._ast_eval(node.left, ns),
+                      self._ast_eval(node.comparators[0], ns))
         if isinstance(node, ast.Call):
             if not isinstance(node.func, ast.Name):
                 raise ValueError("ONLY SIMPLE FUNCTION CALLS ALLOWED")

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/help_text.py

@@ -42,7 +42,7 @@ REGISTERS & SUBROUTINES
   DEFS                List subroutines
 
 VARIABLES & LOOPS
-  LET angle = PI/4    Set a variable
+  LET angle = PI/4    Set a variable (LET optional: x = 5 also works)
   10 RX angle, 0      Use in gate parameters
   10 FOR I = 0 TO 3   Loop (variable substitution in body)
   20   H I
@@ -62,6 +62,7 @@ CONFIGURATION
   SHOTS n             Set number of shots (default: 1024)
   METHOD name         Set simulation method (automatic, statevector,
                       matrix_product_state, stabilizer, ...)
+  STATUS [JSON]       Show every active mode (qubits, method, LOCC, noise, ...)
 
 DEMOS
   DEMO LIST           List available demos
@@ -141,7 +142,7 @@ INLINE CIRCUIT INSTRUCTIONS (in programs, results available after RUN)
   SAVE_EXPECT ZZ 0,1 -> v   Expectation value -> variable
   SAVE_PROBS 0,1 -> p       Probability snapshot -> array
   SAVE_AMPS 0,3 -> a        Specific amplitudes -> array
-  MEAS qubit -> var          Mid-circuit measurement (LOCC mode)
+  MEAS qubit -> var          Mid-circuit measurement + IF feedforward (any mode)
   MEASURE_X/Y/Z qubit       Basis measurement
 
 FLOW CONTROL (in programs)
@@ -162,8 +163,8 @@ FLOW CONTROL (in programs)
   LET arr[i] = val        Array assignment
 
 EXPRESSIONS
-  PI, TAU, E, SQRT2, sin(), cos(), sqrt(), log(), etc.
-  Comparisons: ==, !=, <, >, <=, >=, AND, OR, NOT
+  PI, TAU, E, SQRT2, sin(), cos(), sqrt(), log(), int() floors, fix() truncates
+  Comparisons: ==, !=, <>, <, >, <=, >=    Logical/bitwise: AND, OR, NOT, XOR
   Arrays: arr(i) or arr[i]
   Example: LET theta = PI/4 + asin(0.5)
 """

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/patterns.py

@@ -18,13 +18,13 @@ 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_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)
 RE_CTRL = re.compile(r'CTRL\s+(\w+)\s+(.*)', re.IGNORECASE)
 RE_INV = re.compile(r'INV\s+(\w+)\s+(.*)', re.IGNORECASE)
-RE_LET_ARRAY = re.compile(r'LET\s+(\w+)\((.+?)\)\s*=\s*(.*)', re.IGNORECASE)
+RE_LET_ARRAY = re.compile(r'LET\s+(\w+\$?)\((.+?)\)\s*=\s*(.*)', re.IGNORECASE)
 RE_LET_VAR = re.compile(r'LET\s+(\w+(?:\.\w+)?)\s*=\s*(.*)', re.IGNORECASE)
 RE_PRINT = re.compile(r'PRINT\s+(.*)', re.IGNORECASE)
 RE_GOTO = re.compile(r'GOTO\s+(\d+)\s*$', re.IGNORECASE)

{qubasic-0.11.1 → qubasic-0.13.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.11.1 → qubasic-0.13.0}/qubasic_core/subs.py

@@ -27,6 +27,9 @@ class SubroutineMixin:
         self._static_vars: dict[str, dict[str, Any]] = {'_GLOBAL': {}}
         self._call_stack: list[dict[str, Any]] = []
         self._func_call_depth: int = 0
+        # Names declared SHARED in the current scope level, so their
+        # modifications survive _pop_scope instead of being discarded.
+        self._shared_stack: list[set[str]] = []
 
     def _scan_subs(self, sorted_lines: list[int]) -> None:
         """Scan program for SUB/FUNCTION blocks and build jump table."""
@@ -284,12 +287,15 @@ class SubroutineMixin:
             if vname in self._scope_stack[-1]:
                 run_vars[vname] = self._scope_stack[-1].get(vname, 0)
                 self.variables[vname] = run_vars[vname]
+                if self._shared_stack:
+                    self._shared_stack[-1].add(vname)
         return True, ExecResult.ADVANCE
 
     # ── Scope management ───────────────────────────────────────────────
 
     def _push_scope(self) -> None:
         self._scope_stack.append(dict(self.variables))
+        self._shared_stack.append(set())
 
     def _pop_scope(self, frame: dict[str, Any] | None = None) -> None:
         # Save STATIC vars for the current frame before restoring outer scope.
@@ -303,5 +309,13 @@ class SubroutineMixin:
                 for vname in list(self._static_vars[sub_name]):
                     self._static_vars[sub_name][vname] = self.variables.get(vname, 0)
         if self._scope_stack:
+            # SHARED variables must keep the modifications made inside the
+            # call; capture them before restoring the caller snapshot and
+            # write them back, instead of discarding them with the snapshot.
+            shared = self._shared_stack.pop() if self._shared_stack else set()
+            shared_vals = {v: self.variables.get(v) for v in shared}
             self.variables.clear()
             self.variables.update(self._scope_stack.pop())
+            for v, val in shared_vals.items():
+                if val is not None:
+                    self.variables[v] = val

{qubasic-0.11.1 → qubasic-0.13.0}/qubasic_core/terminal.py

@@ -915,6 +915,18 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         if upper.startswith('BEGIN'):
             return self._def_multiline(rest[5:].strip())
 
+        # DEF FN name(params) = expr — a user expression function, same as the
+        # in-program form, so it works at the prompt too.
+        if upper.startswith('FN'):
+            from qubasic_core.patterns import RE_DEF_FN
+            fm = RE_DEF_FN.match(f"DEF {rest}")
+            if fm:
+                fparams = [p.strip() for p in fm.group(2).split(',') if p.strip()]
+                self._user_fns['FN' + fm.group(1).upper()] = {
+                    'params': fparams, 'body': fm.group(3).strip()}
+                self.io.writeln(f"DEF FN {fm.group(1).upper()}({', '.join(fparams)})")
+                return
+
         m = RE_DEF_SINGLE.match(rest)
         if not m:
             self.io.writeln("?USAGE: DEF NAME[(params)] = GATE : GATE : ...")
@@ -1067,7 +1079,11 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
             parsed = LetArrayStmt(raw=f"LET {rest}", name=name,
                                   index_expr=idx_expr, value_expr=val_expr)
             self._cf_let_array(f"LET {rest}", self.variables, parsed)
-            self.io.writeln(f"{name}({idx_expr.strip()}) = {self.eval_expr(val_expr)}")
+            shown = (self._eval_string_expr(val_expr) if name.endswith('$')
+                     else self.eval_expr(val_expr))
+            self.io.writeln(f"{name}({idx_expr.strip()}) = {shown!r}"
+                            if isinstance(shown, str)
+                            else f"{name}({idx_expr.strip()}) = {shown}")
             return
         sm = RE_LET_STR.match(f"LET {rest}")
         if sm:
@@ -1122,7 +1138,7 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
             'trace_mode': bool(getattr(self, '_trace_mode', False)),
             'bank': getattr(self, '_current_slot', 0),
             'program_lines': len(self.program),
-            'variables': len(self.variables),
+            'variables': sum(1 for k in self.variables if not k.startswith('_')),
             'arrays': len(self.arrays),
             'subroutines': len(self.subroutines),
             'custom_gates': sorted(self._custom_gates.keys()),
@@ -1239,7 +1255,25 @@ 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. Capture the density matrix so
+            # DENSITY works after a measured run, not just a no-MEASURE one.
+            self.last_sv = None
+            if self.num_qubits <= self._SV_EXTRACT_MAX_QUBITS:
+                try:
+                    qc_sv.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
+                    dm_result = dm_backend.run(
+                        transpile(qc_sv, dm_backend,
+                                  optimization_level=self._transpile_opt_level),
+                        **_kw).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
             return
         if self.num_qubits > self._SV_EXTRACT_MAX_QUBITS:
             self.last_sv = None
@@ -1281,9 +1315,24 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         }
 
     def _run_no_measure(self, qc, qc_sv, t0: float) -> None:
-        """Execute the no-MEASURE path: statevector only, no shots."""
+        """Execute the no-MEASURE path: statevector (or density matrix), no shots."""
         too_large = self.num_qubits > self._SV_EXTRACT_MAX_QUBITS
-        if too_large:
+        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.
+            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
+        elif too_large:
             self.last_sv = None
         else:
             try:
@@ -1912,13 +1961,18 @@ 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
+        for s in sizes:
+            total *= s
         self.arrays[name] = [0.0] * total
-        if len(dims) > 1:
-            self._array_dims[name] = dims
+        if len(sizes) > 1:
+            self._array_dims[name] = sizes
+        self._dimmed_arrays.add(name)
         return True
 
     def _try_exec_dim_type(self, stmt: str) -> bool:
@@ -1943,20 +1997,27 @@ 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
 
     def _try_exec_erase(self, stmt: str) -> bool:
@@ -1967,6 +2028,8 @@ class QBasicTerminal(Engine, ExecutorMixin, ExpressionMixin, DisplayMixin, DemoM
         name = m.group(1)
         if name in self.arrays:
             del self.arrays[name]
+        self._array_dims.pop(name, None)
+        self._dimmed_arrays.discard(name)
         return True
 
     def _try_exec_get(self, stmt: str, run_vars: dict) -> bool:

{qubasic-0.11.1 → qubasic-0.13.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.11.1 → qubasic-0.13.0}/tests/test_qubasic.py

@@ -2096,6 +2096,114 @@ class TestConventionAndStateRegressions(unittest.TestCase):
         self.assertIsNotNone(t.last_counts)  # ran; not blocked as a "command"
 
 
+class TestDeepFixRegressions(unittest.TestCase):
+    """SHARED writeback, RESTORE, array write bounds, string arrays,
+    SET_DENSITY inspection, STATUS var count, immediate DEF FN."""
+
+    def _runp(self, lines, nq=1):
+        t = QBasicTerminal(); t.num_qubits = nq
+        for l in lines:
+            t.process(l, track_undo=False)
+        capture(t.cmd_run)
+        return t
+
+    def test_shared_writeback(self):
+        t = self._runp(['10 LET acc=0', '20 SUB ADD(n)', '30 SHARED acc',
+                        '40 LET acc=acc+n', '50 END SUB', '60 CALL ADD(5)',
+                        '70 CALL ADD(3)'])
+        self.assertEqual(t.variables.get('acc'), 8.0)
+
+    def test_restore_resets_data_pointer(self):
+        t = self._runp(['10 DATA 5', '20 READ a', '30 RESTORE', '40 READ b',
+                        '50 LET s=a+b'])
+        self.assertEqual(t.variables.get('s'), 10.0)
+
+    def test_dimmed_array_write_is_bounds_checked(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        for l in ['10 DIM a(3)', '20 LET a(99)=1']:
+            t.process(l, track_undo=False)
+        _, out = capture(t.cmd_run)
+        self.assertIn('OUT OF RANGE', out)
+        # An implicit (undimensioned) array still auto-grows on write.
+        t2 = self._runp(['10 LET b(50)=7', '20 LET v=b(50)'])
+        self.assertEqual(t2.variables.get('v'), 7.0)
+
+    def test_string_array(self):
+        t = self._runp(['10 LET s$(0)="he"+"llo"', '20 LET t$=s$(0)'])
+        self.assertEqual(t.variables.get('t$'), 'hello')
+
+    def test_set_density_no_measure_does_not_crash(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        t.process('SET_DENSITY [[0.5,0],[0,0.5]]', track_undo=False)
+        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))
+        _, dout = capture(t.cmd_density, '')
+        self.assertIn('Density matrix', dout)
+
+    def test_status_excludes_internal_vars(self):
+        t = self._runp(['10 H 0', '20 MEASURE'])
+        self.assertEqual(t._status_dict()['variables'], 0)
+
+    def test_immediate_def_fn(self):
+        t = QBasicTerminal(); t.num_qubits = 1
+        capture(t.cmd_def, 'FN sq(x) = x*x')
+        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_chained_comparison_raises(self):
+        self.assertTrue(bool(self.t._safe_eval('3 < 5')))
+        with self.assertRaises(ValueError):
+            self.t._safe_eval('1 < 2 < 3')
+
+    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)
+
+
 if __name__ == '__main__':
     if hasattr(sys.stdout, 'reconfigure'):
         sys.stdout.reconfigure(encoding='utf-8')