#Tesseract — 4D, 3 cells per axis by default

#Install

moon add riantr/tesseract@0.1.3

///|
import {
  "riantr/tesseract/src/tesseract",
}

#What the release was checked on

#Packages and targets

#The lattice

#Cells per axis is a value, not a constant

moon run cmd/main -- --side 4 .status
moon run cmd/main -- --side 4 .solve .verify

• coordinates (x, y, z, w) are 0-based, matching array indexing;
• positions 1..total are 1-based, matching the C# grid_position column, so stored SQL and .tsr files keep the same shape.

position = 1 + x*side^3 + y*side^2 + z*side + w      (row-major, x slowest)

#Importing across sides

#What the sudoku constraint is at this size

digit(x,y,z,w) = (x + y + z + w) mod 3 + 1

#Layout

src/tesseract/
  text.mbt       ASCII helpers: trim, case folding, integer parse, split/join
  coords.mbt     the lattice: coordinates, positions, neighbours, shares_line
  lattice.mbt    lines, slabs, planes, peers
  sudoku.mbt     digits, the line rule, slab balance, backtracking solver
  txn.mbt        transactions: the undo journal, savepoints, statement atomicity
  types.mbt      GridCell, Record, Computed, DBResponse, DBStatus, formatting
  logger.mbt     bounded log ring (100 entries, matching the C# logger)
  clock.mbt      the injected clock and its ISO-8601 rendering
  db.mbt         the store, and the in-place resize between shapes
  lexer.mbt      the SQL tokenizer
  ast.mbt        the parsed shape of a statement
  parser.mbt     recursive descent, precedence climbing
  exec.mbt       the executor: expressions, aggregates, ordering, transactions
  jsonpath.mbt   the JSON path: parsing it, walking it, reading a number from text
  serialize.mbt  .tsr JSON, .md table, .sql dump, lattice rendering
cmd/main/        command line front end
cmd/gui/         the proton desktop window
  main.mbt       the App: entry point, page asset, command registration
  state.mbt      the store the window drives, and its JSON projections
  commands.mbt   the seven typed commands the page can call
  web/index.html the page itself - inline CSS and JS, no build step
proton.project.json   bundle identity, backend package, packaging settings
gui-smoke.mjs         end-to-end smoke test driven through Chromium DevTools

#The window

• A position outside 1..side⁴ is an error, not "use the cursor." The page omits position only when the box is empty; anything the user actually typed goes through, so 999 gets INVALID_POSITION at side 3 instead of quietly landing on the cursor cell.
• delete needs a key or a position. With neither, the library means "empty the whole lattice", which is what 清空整个点阵 is for; the delete verb refuses that form with INVALID_INPUT rather than wiping 81 cells from an empty form.
• delete in the window is cell-scoped. A bare key is the library's "remove every cell carrying it" form, and this button sits in a form framed around one cell — so a key with no position (and nothing selected) is refused at the page rather than removing rows that are not on screen. Deleting all cells by key stays reachable in the SQL console, where the statement says so.

• Optional request fields are omitted, never sent as null. MoonBit's decoder for Int? accepts a number or no key at all, and treats an explicit null as a type error. Sending position: null fails the whole dispatch with InvalidPayload before the handler runs.
• is_solution means "no rule is broken", not "every cell is filled." The library's line and slab checks skip empty cells, so a lattice with one hole still reads as a solution. The window's chip shows the placed count alongside the verdict for exactly that reason.

#SQL

#What the surface does, and what it does not

• The column list is the cell anatomy and it is fixed. There is no CREATE TABLE, so a record's own attributes are never queryable as columns — only the eleven above, plus the whole value, which is text and is queryable inside with json_extract.
• A column name is checked against that list in every clause — WHERE, GROUP BY, ORDER BY and the select list — before a row is read, so an unknown column is an error whether or not the table has anything in it. It was not, and the answer it gave instead was the dangerous kind: GROUP BY nosuchcol evaluated the name to null on every row and reported one group holding the whole table, which is the same shape a legitimately uniform column reports; ORDER BYnosuchcol returned the rows in storage order; and a bare unknown column in a grouped select list was dropped without a word.

CREATE DATABASE tesseract;
INSERT INTO tesseract (key, value) VALUES ('user_001', '{"age": 25}');
SELECT * FROM tesseract WHERE key = 'user_001';
SELECT * FROM tesseract WHERE value LIKE '%age%';
UPDATE tesseract SET value = '{"age": 26}' WHERE key = 'user_001';
DELETE FROM tesseract WHERE key = 'user_001';

-- explicit address, as a position or as coordinates
INSERT INTO tesseract (key, value) VALUES ('k', 'v') AT 42;
INSERT INTO tesseract (key, value) VALUES ('k', 'v') AT (1,2,0,2);

-- sudoku digits, enforced against the lines through the cell
INSERT INTO tesseract (key, value, digit) VALUES ('k', 'v', 2);
UPDATE tesseract SET value = 'v', digit = 3 WHERE grid_position = 42;

-- coordinate predicates
SELECT * FROM tesseract WHERE x = 1 AND y = 2;
SELECT * FROM tesseract WHERE digit = 1;

-- geometry
SELECT * FROM tesseract WHERE line(42, 0);   -- the 3-cell axis-parallel line
SELECT * FROM tesseract WHERE slab(42, 1);   -- the 27-cell slab
SELECT * FROM tesseract WHERE peers(42);     -- the 8 cells sharing a line

SELECT * FROM tesseract WHERE peers(42) AND key = 'user_001';

#Expressions

OR  <  AND  <  NOT  <  = <> != < <= > >= LIKE IN IS NULL
    <  + -  <  * / %  <  unary -  <  literals, columns, ( ), functions

SELECT * FROM tesseract WHERE key = 'a' OR key = 'b';
SELECT * FROM tesseract WHERE digit = 1 + 1;
SELECT * FROM tesseract WHERE key IN ('a', 'b', 'c');
SELECT * FROM tesseract WHERE NOT (x = 1 AND y = 2);

#Reading inside a JSON value

SELECT json_extract(value, '$.name') FROM tesseract WHERE key = 'user_001';
SELECT key FROM tesseract WHERE json_extract(value, '$.age') > 30;
SELECT sum(json_extract(value, '$.amount')) FROM tesseract;

$            the whole document
$.name       a key
$.a.b        a key inside a key
$.tags[1]    the second element of an array
$["a b"]     a key that is not an identifier

• The path belongs to the statement. A malformed path is an error (INVALID_INPUT), never a null: the path is the same for every row, so it is not the data's business whether it is well formed. Answering null for it would be indistinguishable from a document that simply has no such field.
• The value belongs to the row. A row whose text is not JSON, or whose JSON has no such key, answers null. One row holding a plain string must not take the whole query down with it.

-- matched every row that mentioned the word, including one with no such key
SELECT key FROM tesseract WHERE value LIKE '%name%';

-- matched the rows that have the key
SELECT key FROM tesseract WHERE json_extract(value, '$.name') IS NOT NULL;

#Grouping, ordering, limits

SELECT digit, count(*) FROM tesseract GROUP BY digit;
SELECT sum(digit) FROM tesseract WHERE digit > 0;
SELECT key FROM tesseract ORDER BY key DESC, digit ASC;
SELECT key FROM tesseract ORDER BY key LIMIT 10 OFFSET 20;
SELECT DISTINCT value FROM tesseract;

#Transactions

BEGIN;
INSERT INTO tesseract (key, value) VALUES ('a', '1') AT 1;
SAVEPOINT sp;
INSERT INTO tesseract (key, value) VALUES ('b', '2') AT 2;
ROLLBACK TO sp;     -- the 'b' insert goes; the transaction stays open
COMMIT;

ROLLBACK;           -- or undo the whole thing

• Every statement is atomic, with or without BEGIN. Each one opens an implicit savepoint, so a multi-row UPDATE refused on its last row commits none of its earlier ones. This is the case the journal exists for.
• ROLLBACK TO sp keeps sp and drops only the savepoints after it, matching SQL. RELEASE sp forgets it and keeps the work — the opposite effect, under the same kind of name, which is why both have their own test.

#Running it

#Command line

moon check --target all     # type-check every backend
moon test                   # 240 tests
moon fmt --check            # canonical formatting

node cli-smoke.mjs          # both CLIs, as real processes (builds them first)
node gui-smoke.mjs          # the window, over CDP (needs `proton_cli dev` running)

moon run cmd/main -- .help
moon run cmd/main -- .status
moon run cmd/main -- .demo
moon run cmd/main -- .solve .verify
moon run cmd/main -- "INSERT INTO tesseract (key,value) VALUES ('a','1') AT 5;" "SELECT * FROM tesseract;"
moon run cmd/main -- .export tsr > dump.tsr

# 256 cells, digits 1..4
moon run cmd/main -- --side 4 .status
moon run cmd/main -- --side 4 .solve .verify

$ moon run cmd/main -- --side 999 .status
--side side 999 is above the maximum 215 (cells are stored in one flat array indexed by a 32-bit Int)

#Persistence

moon run cmd/persist --target native -- .open sudoku.db \
  "INSERT INTO tesseract (key,value,digit) VALUES ('user_001','{\"age\": 25}',1) AT 1;" \
  .save .status .verify

# a second process reads the same file back
moon run cmd/persist --target native -- .open sudoku.db .status

• It is a snapshot, not a mirror. The lattice lives in memory between .open and .save; nothing is written back on exit. A session that opens a file and never saves says so rather than losing the work quietly.
• Timestamps round trip. Each cell is written with its timestamp and loaded back through the public Tesseract::insert_stamped, the same call import_tsr makes, so a reopened .db carries the stamps it was saved with instead of ones minted from this process's log counter. What does not carry over is the log: sequence numbers continue from where the new process started, so stamps made after a load do not continue the saved file's numbering. .tsr is the format when that continuity matters — .db restores what it stored.
• A load replaces, it does not merge, the same way import_tsr clears first. Rows the store refuses — a hand-edited file can hold two cells with the same digit on a shared line — are reported as rejected rather than dropped, because "loaded 3 of 4" and "loaded 4" are different answers.

while read -r line; do moon run cmd/main -- "$line"; done

#Static analysis

moonx riantr/moonbit_static_analysis@0.4.1 . > scan.tsv
moon run cmd/sa --target native -- store scan.tsv scan.db
moon run cmd/sa --target native -- runs scan.db
moon run cmd/sa --target native -- show scan.db
moon run cmd/sa --target native -- files scan.db
moon run cmd/sa --target native -- unparsed scan.db

• Quote the coverage, not the finding count. The analyzer's frontend covers a subset of MoonBit, so most .mbt files come back unread and their findings are withheld — they measure what the analyzer does not understand, not what your code does wrong. actionable is the only column that describes the code.
• 0.4.0 splits every file into three outcomes. clean and found mean the file was read end to end; partial means it was read up to its first parse error and nothing after it was looked at. sa_files.read_up_to and sa_files.not_shown keep where that line was. On this project all 12 fully read files carry defects=0 and every actionable finding sits on a partially read file — so 30.7% coverage is the honest context for the number 4.
• Three of the four counters do not describe your code. notices are constructs outside the analyzed subset, unreliable are findings from a partial read, withheld are findings on files never read. They are stored in their own columns precisely so they cannot be summed into a defect count.
• The database keeps the truncation visible. The tool prints at most three examples per unparsed reason and only a few findings per file, so sa_files.defects/notices (what the header reported) and sa_files.shown (what was rendered) are both stored. A list shorter than the count is a sample, and the table says so.
• Withheld findings have nowhere to go on purpose. There is no column for them, because a database that held 1487 rows of them would read as 1487 problems.
• A run that did not finish is refused. The tool exits 0 even when it cannot find its target, printing only an ERROR line. parse treats a missing SUMMARY as the failure it is, so a failed scan cannot be stored as a clean one.

#The window

moon update                                        # refresh the registry index
moon install moonbit-community/proton_cli@0.5.1   # match the library version
proton_cli cef setup                               # CEF runtime + subprocess helper

proton_cli doctor                  # identity, toolchain and runtime
proton_cli dev                     # run the window
proton_cli build                   # native build
proton_cli package --dry-run       # check the packaging plan
proton_cli package                 # produce dist/

"resources": [ "cmd/gui/web" ]

node gui-smoke.mjs

#Verification

#Export formats

#Deliberate departures from the C# original

1. The grid is 81 cells, not 9, and is addressable by coordinate. The cell count per axis is a value rather than a constant, so 81 is the default rather than the only shape; --side 4 gives 256.
2. current_count is computed from occupancy, not accumulated. The C# counter saturated at 9 on the first wrap and then only decremented, so it drifted away from the number of stored records; reporting the real occupancy is what GetStatus was always asking for.
3. A malformed address never resolves to another cell. Out-of-range positions and unparsable coordinates are errors, not clamped values — a silent clamp would write to a cell the caller never asked for.
4. Out-of-range positions give a clean error code instead of the C# KeyNotFoundException surfacing as a generic failure. Which code depends on the verb, and the split is deliberate: POSITION_OUT_OF_RANGE for the verbs that address an existing record (update, delete, the geometry queries), and INVALID_POSITION for INSERT, whose position names a target to write rather than a record to find.
5. Timestamps are stamped, not read at the call site. The C# original put DateTime.UtcNow in the logger. MoonBit's core library does carry a clock — @env.now(), milliseconds since the Unix epoch, implemented for native, js and wasm — so a real one was available without a dependency and without pinning the package to a target. It is injected as a Clock rather than called inline because a clock read at the call site makes every stamp a function of when the process started. cmd/main, cmd/persist and the window read the host; the library default is a logical sequence number, which is what keeps the test suite byte-comparable between runs. So log lines and records show 2026-10-16T19:45:00.123Z, and a .tsr written by either clock still imports into the other.
6. There is a window, and it is not Avalonia. The C# original was Avalonia; this is a proton app — the same HTML/CSS page surface and native-window model, rebuilt on a different runtime. The CLI is still there and still shares the library.
7. The store lives in memory, and so does the window's copy of it. The C# app had the same in-memory model; there is no file backing either, so closing the window discards what is in it. The export formats are the way out — and, if you want a file that a SQL engine can read, cmd/persist below.

#What this is not

• It is not SQLite and does not embed one. The parser, AST and executor are in this repository — lexer.mbt, ast.mbt, parser.mbt, exec.mbt. There is no C library behind them and no FFI. moonbit-community/sqlite3 appears in this module's dependencies for exactly one package, src/tesseract_sqlite, which backs the .db file adapter in cmd/persist; the SQL surface does not go through it.
• It is not a graph database. The lattice is one flat Array indexed by a 32-bit Int. peers, slab and line are computed from coordinates at query time, not stored edges.
• It is not a wrapper around an existing store. There is no KV core being dressed up. The grid, the sudoku digit rule and the solver are the reason the package exists, and dropping them would leave a much smaller program.
• The window is Proton, not a native GUI toolkit. cmd/gui depends on moonbit-community/proton@0.5.1 and is therefore native-only. The library and cmd/main do not depend on it.
• The core library has no third-party dependencies. File I/O and stdin are not in this toolchain's core, so what the package needs is implemented here. The additions are @env.now() from moonbitlang/core/env and @json.parse from moonbitlang/core/json — both are the toolchain rather than mooncakes imports, and both were already here: the clock for the timestamps and the JSON parser for the .tsr reader.