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

#Install

moon add riantr/tesseract@0.1.10

///|
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, characters
  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
src/tesseract_memory/
  memory.mbt     the memory: put, get, capacity, the statistics
  scope.mbt      the scopes: partitions of one keyspace, one budget, one clock
  spec.mbt       the spec of an entry: its lifetime, its weight, its labels
  entry.mbt      one remembered thing, and when its time is up
  metadata.mbt   the labels of an entry, and the filters that select them
  ttl.mbt        Never / Absolute / Sliding, and the deadline arithmetic
  clock.mbt      the injected clock, system or manual
  evict.mbt      LRU, LFU, soonest-expiry, oldest
  similar.mbt    the similarity policies and the recency weight
  score.mbt      tokenising, the four similarities, JSON leaf paths
  search.mbt     top-k over the live entries, filtered or not
  size.mbt       the UTF-8 size of a text, in bytes
cmd/main/        command line front end
cmd/memory/      the short-term memory, from a shell
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.

#The short-term memory

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

moon run cmd/memory -- "put greeting hello world" "get greeting"
moon run cmd/memory -- --capacity 3 "put a 1" "put b 2" "put c 3" "put d 4" "keys"
moon run cmd/memory -- --max-bytes 10 "put a 12345" "put b 12345" "put c 12345" "stats"
moon run cmd/memory -- --manual-clock "put a x --ttl 1000" "advance 1000" "get a"
moon run cmd/memory -- "put a x --meta kind=note" "entries --where kind=note"
moon run cmd/memory -- --capacity 2 "put keep kept --pinned" "put other dropped" "put new new" "keys"
moon run cmd/memory -- demo

#TTL

#Capacity and eviction

#A pinned entry is never thrown away

///|
let m = @tesseract_memory.new_memory(100)
ignore(
  m.put_spec(
    "keep",
    "the thing that must not be lost",
    @tesseract_memory.default_spec().with_pinned(true),
  ),
)

• A pinned entry still expires when its lifetime is up. "Do not evict me" and "never die" are two different promises.
• A pinned entry is still found by a search, and its score is unchanged.
• A pinned entry still takes up room: it is counted against the capacity and the byte budget like any other.
• The pin belongs to the entry, so it survives a read and a touch, and it is the store's eviction that respects it, not the scope's.

#The byte budget

///|
let m = @tesseract_memory.new_memory_with(
  @tesseract_memory.default_config().with_capacity(100).with_max_bytes(65536L), // 64 KiB of values
)

• A value larger than the whole budget is refused, even in an empty store. The budget is what the memory holds, and a value that does not fit in it does not fit in it. Refusing it loudly is better than accepting it and breaking the limit the caller asked for — and the refusal leaves the store as it was, because a write that fails must not empty the memory on its way out.
• A replacement can push the store over the budget, and then it makes room. Five bytes replaced by ten is ten bytes of content plus whatever else is there, not five. The key being written is never the one evicted to make room for itself.

#Scopes

///|
let m = @tesseract_memory.new_memory(100)
let work = m.scope("work")
ignore(work.put("todo", "ship 0.1.10"))
ignore(m.scope("notes").put("todo", "buy milk"))
// Two entries, one key.
assert_eq(work.get("todo"), Some("ship 0.1.10"))
assert_eq(m.scope("notes").get("todo"), Some("buy milk"))

• A scope is a handle, not a copy. Two handles on the same scope see the same entries and the same byte total, so the total cannot drift between them.
• A key is unique only within a scope. A hit from search_all says which scope it is in, and an Entry carries its scope — otherwise an entry could not be told from the same key in another scope.
• Memory::size is the store's count and Scope::size is one scope's. The number to compare with capacity is the store's, because the capacity is spent across the scopes; a scope's count would under-report how full the store is, and a caller who believed it would think there was room when there was none.

moon run cmd/memory -- --scope work "put todo ship 0.1.10" "keys"
moon run cmd/memory -- "put a the cat sat" "scope work" "put a the cat sat on the mat" "scopes"
moon run cmd/memory -- "put a the cat sat" "scope work" "put a the cat sat on the mat" "search-all cat"

#The order of keys is by their letters

#A configuration is either usable or it is refused

///|
if !config.is_valid() {
  // the memory will not hold this
}

#The store's internals are not part of the API

#Similarity retrieval

#Recency weighting

///|
let m = @tesseract_memory.new_memory_with(
  @tesseract_memory.default_config()
  .with_capacity(100)
  .with_recency(@tesseract_memory.recency_decay(3600000L)), // one hour
)

#How much an entry counts

///|
let m = @tesseract_memory.new_memory(100)
ignore(m.put("trivia", "the cat sat on the mat"))
ignore(
  m.put_spec(
    "important",
    "the cat",
    @tesseract_memory.default_spec().with_importance(0.2),
  ),
)
// "the cat" is the better match on its own, and the importance is what
// turns the order over.

• Zero would make the entry unfindable — stored, readable by key, and never matched by a search — and a zero-initialised field is the easiest way to get there by accident. An entry that should not be found is an entry that should be deleted.
• Above one would carry the score past the 0.0..1.0 it is documented to be in.

#Labels on an entry

///|
let m = @tesseract_memory.new_memory(100)
ignore(
  m.put_spec(
    "deploy",
    "the deploy failed",
    @tesseract_memory.default_spec()
    .with_metadata(@tesseract_memory.new_metadata([("kind", "deploy")])),
  ),
)

#Filtering a search

///|
let hits = m.search_filtered(
  "deploy",
  3,
  @tesseract_memory.filter_equals("kind", "deploy"),
)

#The clock is injected

#What it does not do

• Not SQL, and not a second query language. The memory has a native API. Putting it behind the core's SQL would mean the core's executor learned about a tier it does not own.
• Not embeddings. A semantic similarity needs a model, and a model is a dependency and a download.
• Not persistent. A short-term memory is the tier above the durable store, not a replacement for it. What is worth keeping is what the durable store is for.
• Not thread-safe, for the same reason the core is not: the runtime is single-threaded, and the store is mutated in place.
• Not eviction by importance. The importance weights retrieval — what a search finds — and not what the store throws away. That is the policy's business, and the four policies are about age, use and expiry.
• Not a soft pin. A pin is absolute. A store that broke a pin when it had to would make the promise depend on the state of the store, so a store that cannot make room refuses the write instead.
• Not immortality. A pinned entry still expires when its lifetime is up. "Do not evict me" and "never die" are two different promises.
• Not eviction by the labels. The labels say what an entry is, and a filter says what a search may look at. Neither is a weight, and a store that evicted by them would make the eviction depend on a field nobody promised anything about.
• Not per-scope budgets. A scope partitions one pool, and the capacity and the byte budget belong to the pool. A scope with a budget of its own would make the store's size a function of how many partitions a caller happened to use.

#Running it

#Command line

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

node cli-smoke.mjs          # the 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

# the short-term memory
moon run cmd/memory -- .help
moon run cmd/memory -- "put greeting hello world" "get greeting"
moon run cmd/memory -- --scope work "put todo ship 0.1.10" "keys" "scopes"
moon run cmd/memory -- "put a x --meta kind=note" "search x --where kind=note"
moon run cmd/memory -- "put a x --pinned" "pin a" "unpin a"
moon run cmd/memory -- demo

# 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.
• It is not a vector database. The memory's similarity is lexical and structural, computed at query time, and exact — the same two texts always give the same score. There is no embedding, no index, and no model to drift.
• 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. The memory tier adds @math.pow from moonbitlang/core/math, also the toolchain.