#Tesseract

#Features

• A lattice that is a shape, not a table
  side — how many cells each of the four axes has — is a value rather than a constant. Three per axis is the default (81 cells) because every existing .tsr and .db file was written under it; --side 4 gives 256 cells and digits 1..4. The range is 1..215, and the upper bound is storage rather than arithmetic: Array is indexed by a 32-bit Int, so side^4 cells have to stay addressable. lattice_of refuses a side it cannot address and says which rule it applied rather than truncating.

• A SQL surface that is its own parser, AST and executor
  lexer.mbt → parser.mbt → exec.mbt. Not SQLite, and not a hand-rolled scan either — the earlier version was 932 lines of repeated string scanning whose WHERE was a struct holding at most one predicate per field, and the shape of that struct was the bug. The rule the executor is built around: a clause the parser accepts is a clause the executor applies, or the statement is refused. The version it replaced parsed LIMIT 1 and ORDER BY key DESC as nothing, dropped them, and reported success. Twelve error codes, every one of them reachable, and nothing outside the set is produced.

• A memory with a lifetime, a budget and a policy
  TTL as absolute, sliding or never; a byte budget over the UTF-8 content; four eviction policies (LRU, LFU, oldest, largest) with pinned entries never thrown away; scopes as a partition of the keyspace; labels as filters; and a similarity that is exact — the same two texts always give the same score, with no model to drift. The clock is injected, so a test is byte-comparable between runs.

• A durable memory whose checkpoint is refused when it cannot be read
  The checkpoint is a file with a format: a header cell carrying a version and a clock, and one cell per entry after it. The format's own words are "a checkpoint that carries a version this build does not know is refused rather than half-read", and the code does that — a file with an unknown version, a foreign header key or no header at all is refused, and a reload checks the header before it clears the store, so a refused reload leaves the store holding exactly what it held.

• An index that is derivative, and says so
  The SQL index holds no word the entries do not, so a rebuild gives back the same thing. It is not maintained behind the caller's back: the writes go through the memory's own API, so the rebuild is the caller's to run, and a lookup checks the index against the store first rather than answering from a stale one. The rebuild costs less than the store it was built from.

• A window, and six executables
  cmd/main, cmd/persist, cmd/memory, cmd/memory_db, cmd/sa and cmd/gui — the command line, the file-backed store, the short-term memory, the durable memory, the scan database, and a proton window over the same library.

#What you get

#Install

moon add riantr/tesseract@0.1.15

import {
  "riantr/tesseract@0.1.15",
}

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

Cannot find import 'riantr/tesseract/src/tesseract@0.1.15' in my/app/src/thing@0.1.0

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

#What the release was checked on

#What changed in 0.1.15

• The license is MIT. It was Apache-2.0. MIT is the shorter and more permissive of the two, and it is what the sibling riantr/pyroduct uses. The change is in LICENSE and in moon.mod's license field, which is what the registry publishes — so 0.1.14 on the registry still says Apache-2.0, and only 0.1.15 says MIT. A consumer that reads the license off the registry has to read it off the version it actually depends on.
• There is a logo. tesseract.png is what the README shows and what the registry's docs page renders; tesseract_Logo.png is the same artwork at 1024×1024, for anyone who wants the full-resolution file. Both are published with the module, and the README's image path is relative, so the registry rewrites it to the asset URL.

#What changed in 0.1.14

• Lattice, Entry and Hit are opaque. Their fields are private now, and each field has an accessor: Lattice::side(), Lattice::total(), Lattice::first_position(), Lattice::last_position(), Lattice::max_digit(); Entry::scope(), Entry::key(), Entry::value(), Entry::added_at(), Entry::deadline(), Entry::window_ms(), Entry::sliding(), Entry::last_seen(), Entry::hits(); and on Hit, Hit::scope(), Hit::key(), Hit::value(), Hit::score(), Hit::importance() and Hit::metadata(). A caller that read entry.value now reads entry.value().
• Tesseract::write_cell and Tesseract::write_all are no longer public. They were internal machinery that a caller could reach, and a caller that could reach them could store a cell the library refuses to write anywhere else.
• sudoku_line_count was added — the number of lines in a lattice, in the package that owns the thing being counted.

#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
src/tesseract_memory_index/
  index.mbt      the SQL index: an inverted index of the entries' words
src/tesseract_memory_db/
  format.mbt     the checkpoint container: the lattice that holds the entries
  store.mbt      the durable memory: open, checkpoint, reload
src/tesseract_memory_cli/
  cli.mbt        the command layer, shared by cmd/memory and cmd/memory_db
cmd/main/        command line front end
cmd/memory/      the short-term memory, from a shell
cmd/memory_db/   the durable memory, from a shell, with the index behind it
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.15"))
ignore(m.scope("notes").put("todo", "buy milk"))
// Two entries, one key.
assert_eq(work.get("todo"), Some("ship 0.1.15"))
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.15" "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 kinds

///|
let m = @tesseract_memory.new_memory(100)
ignore(
  m.put_spec(
    "todo",
    "ship 0.1.15",
    @tesseract_memory.default_spec()
    .with_metadata(@tesseract_memory.no_metadata().with_kind("task")),
  ),
)
assert_eq(m.entry("todo").unwrap().kind(), Some("task"))
assert_eq(m.kinds()[0].0, "task")

moon run cmd/memory -- "put todo ship 0.1.15 --kind task" "put note the cat sat --kind note" "kinds"
moon run cmd/memory -- "put todo ship 0.1.15 --kind task" "entries --kind task"

#The clock is injected

#The durable memory

///|
import {
  "riantr/tesseract/src/tesseract_memory" @tm,
  "riantr/tesseract/src/tesseract_memory_db" @tmdb,
}

let store = @tmdb.open("notes.db", @tm.default_config())
ignore(store.put("greeting", "hello"))

• A reload brings back exactly the entries that were live. An entry whose time was up when the checkpoint was written is not in the file, and an entry whose time is up by the time the file is read is dropped again. What comes back is the live set, not the written set.
• A refused write leaves the store unchanged — and the file with it. A write the store cannot honour is refused before anything is touched, and a refused write writes no checkpoint either.

• The deadline is absolute. The checkpoint stores the instant an entry dies, not the lifetime it was given. A lifetime is relative to the moment of the write, so a checkpoint that stored one would move every deadline forward by however long the store was closed — a store reopened after an hour would hold entries an hour younger than they were.
• The clock goes into the checkpoint too, and comes back with it. A store on a manual clock that was reopened on a fresh one would find its entries younger than they were, and an age of minus an hour is not a thing a store should report. A checkpoint that carries the system clock says nothing about the timeline — the host's clock is the host's clock — so the clock the store was opened with is the one in force.
• The checkpoint is swept before it is written. What goes into the file is what is live, so an expired entry cannot come back.

#The SQL index

SELECT scope, key FROM tesseract_memory_index WHERE token = 'cat';

///|
import {
  "riantr/tesseract/src/tesseract_memory" @tm,
  "riantr/tesseract/src/tesseract_memory_index" @tmi,
}

let m = @tm.new_memory(100)
ignore(m.put("note", "the cat sat"))
let index = @tmi.open("notes.idx").unwrap()
let report = index.rebuild(m).unwrap()
println(report.describe())

#The index is derivative

index notes.idx: 9 rows, 3 entries, 0 changed, 0 rows added, 0 rows removed

• The words are the content's words. The words of the value, and the words of the values of the labels. The keys of the labels are not words: "kind" is the name of a label, and every entry with a kind would then be found by the word "kind", which says nothing about the entry.
• The lookup is exact. "cat" finds the entry that says "cat"; "ca" and "cats" find nothing. The query is lowercased, because the index holds the words the tokenizer wrote and the tokenizer lowercases.
• The store decides. The rebuild reads the store's own scopes and entries, so the index covers every scope, and an entry the store has forgotten — or let die — has no rows.
• A verify changes nothing. It does not even create the file it was asked about: a read that wrote would be a read that lied.

#From a shell

moon run cmd/memory_db --target native -- --file notes.db --index notes.idx "index"
moon run cmd/memory_db --target native -- --file notes.db --index notes.idx "index-find cat"

#What it does not do

• Not SQL, and not a second query language. The memory has a native API; the index is a separate package with a table of its own. Putting the memory 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 by itself. The memory tier lives in the process. What survives the process is src/tesseract_memory_db's checkpoint, which is a different package and a different type: a Memory is not durable, and a caller who believed it was would lose entries on the strength of a promise the type never made.
• 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.
• Not maintained behind the caller's back. The index is rebuilt when the caller says so, because the writes go through the memory's own API and a store that kept a second index in step on every write would have to own those writes. A caller that wants the index fresh runs the rebuild; a caller that does not can ask how far the index is from the store instead.

#Running it

#Command line

moon check --target all     # type-check every backend
moon test                   # 422 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.15" "keys" "scopes"
moon run cmd/memory -- "put a x --meta kind=note" "search x --where kind=note"
moon run cmd/memory -- "put todo ship 0.1.15 --kind task" "kinds"
moon run cmd/memory -- "put a x --pinned" "pin a" "unpin a"
moon run cmd/memory -- demo

# the durable memory: the same commands, and a file behind them
moon run cmd/memory_db --target native -- --file notes.db "put greeting hello world"
moon run cmd/memory_db --target native -- --file notes.db "get greeting"
moon run cmd/memory_db --target native -- --file notes.db --manual-clock "put a x --ttl 1000" "advance 1000" "get a"

# the SQL index of the same store: rebuild it, then look a word up in it
moon run cmd/memory_db --target native -- --file notes.db --index notes.idx "index"
moon run cmd/memory_db --target native -- --file notes.db --index notes.idx "index-find cat"

# 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

#The durable memory

moon run cmd/memory_db --target native -- --file notes.db "put greeting hello world"
moon run cmd/memory_db --target native -- --file notes.db "get greeting"

# a second process reads the same file back
moon run cmd/memory_db --target native -- --file notes.db "keys"

# the file holds what is live, and the clock comes back with it
moon run cmd/memory_db --target native -- --file notes.db --manual-clock \
  "put soon x --ttl 1000" "advance 1000" "keys"

#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.6.0   # 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.6.0 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.

#Quick Start

moon add riantr/tesseract

moon test             # Total tests: 422, passed: 422, failed: 0.

moon run cmd/main -- .demo                        # a store, a statement, a report
moon run cmd/main -- .solve .verify               # the sudoku solver, and the check
moon run cmd/memory -- demo                       # the short-term memory
moon run cmd/memory_db --target native -- --file notes.db "put greeting hello world" "get greeting"
moon run cmd/persist --target native -- .open sudoku.db "INSERT INTO tesseract (key,value) VALUES ('a','1') AT 1;" .save .status
moon run cmd/sa --target native -- store scan.tsv scan.db

#Example

// The lattice: four axes, 81 cells by default, up to 215 per axis
let lat   = @tesseract.lattice_of(3).unwrap()
let cells : Int64 = @tesseract.Lattice::total(lat)     // 81
let lines : Int64 = @tesseract.sudoku_line_count(lat)  // 108  (4 · side³)

// The SQL surface: its own lexer, parser, AST and executor
let db  = @tesseract.new_db("demo", lat, @tesseract.new_logger("demo"))
let put = @tesseract.execute(db, "INSERT INTO tesseract (key,value) VALUES ('a','1') AT 5;")
let got = @tesseract.execute(db, "SELECT * FROM tesseract WHERE key = 'a';")

// The memory: TTL, a byte budget, scopes, labels, and an exact similarity
let mem  = @tesseract_memory.new_memory(100)
let work = @tesseract_memory.Memory::scope(mem, "work")
ignore(work.put("todo", "ship 0.1.15"))
let hits : Array[@tesseract_memory.Hit] = @tesseract_memory.Memory::search(mem, "todo", 10)

// The durable memory: the same store, with a checkpoint file behind it
let dur = @tesseract_memory_db.open("notes.db", @tesseract_memory.default_config()).unwrap()
ignore(@tesseract_memory_db.DurableMemory::put(dur, "greeting", "hello world"))

#Gates and drift detectors

#Used By

• cmd/main, cmd/persist, cmd/memory, cmd/memory_db, cmd/sa and cmd/gui — the six executables in this module, each one a different surface over the same library: the command line, the .db adapter, the short-term memory, the durable memory, the scan database and the window.
• qa/fuzz and qa/contract_probe — two nested modules that build against the published package rather than the tree, so their tests are the only ones that can see a release breaking a consumer.
• The C#/Avalonia tesseract project — the original this is a port of, and the other half of the 26-statement parity comparison.

#Attribution

• License: MIT (see LICENSE).
• Ported from: the C#/Avalonia tesseract project — the same 4D lattice, the same .tsr format, the same export shapes. Every place the MoonBit version answers differently from the C# original is recorded in Deliberate departures, with the reason for each one.