Architecture & principles

Semanticus is one process that both doors attach to. Under the hood: a single-writer model dispatcher, one undoable broadcast transaction per edit, and deterministic gates that prove a change before it ships.

#One process, two doors

The VS Code extension (TypeScript) talks to the engine over JSON-RPC on a named pipe. Your Claude talks to the same engine over MCP on stdio. Inside, a single-writer model dispatcher owns the TOM (Tabular Object Model): every read and write, from either door, is serialized into one total order, so the human and the agent can never race the model into an inconsistent state.

# the MCP door: your Claude attaches over stdio
<engine> mcp --workspace <project root>

# the RPC door: the VS Code extension attaches over a named pipe

The engine is organised into a few projects:

The TOM comes from a vendored copy of Tabular Editor's TOMWrapper: the valuable headless logic (change-tracking, undo, formula fixup) carried forward, with all new UI built the modern way as a React webview.

#The write chokepoint

Every mutation, from either door, funnels through one chokepoint that wraps the work in an undoable, broadcast transaction. That gives three guarantees: one shared undo timeline, live model/didChange deltas tagged with their origin, and last-writer-wins resolution that is visible, never a silent merge.

Writes take one of three routes, and all three land on that same dispatcher, undoable and broadcast:

TMDL apply refuses to create a top-level object on purpose: it captures the object's "before" so the edit is fully reversible, and a brand-new object has no "before" to restore. Rather than punch a hole in the undo timeline, it rejects the case and routes you to the typed create op. The one invariant the engine will not break is that every model edit is undoable.

#Deterministic gates: evidence, not vibes

Semanticus is the independent referee for what an edit did to your model, and the referee is deterministic. It does not ask the model to grade itself. Instead it runs checks whose answers are facts:

• Equivalence proofs (verify_dax_equivalence): evaluate the original and the rewrite side by side across a group-by matrix, where each row is a distinct filter context, and report whether every value matches.
• Probes against known-good numbers (probe_measure): run a measure across many filter contexts to gather evidence (value, blank, error, additivity) before you trust it. Bugs that are invisible in one context show up here.
• Best-practice diffs (bpa_scan): compare active violations before and after a change, so a fix is judged on the violations it actually moved.

These gates are the spine of Verified Edits and the enforced Workflows (both Pro). A gate that fails does not silently block you: it pauses and states the rule, and a reasoned override is always available and recorded in the audit trail. Accountable, never a hard wall.

#The no-inference principle

The engine runs no AI and holds no AI credentials. It never calls an inference API, and nothing about your model leaves it to a model vendor. "AI" in Semanticus is your own Claude subscription driving the MCP tools, which has two consequences worth stating plainly:

• Zero per-call cost to run. There is no metered API spend behind the tool calls; the engine is plumbing, not an inference product.
• Your data stays with you. The engine does not ship model contents to a third party to do its work.

For MCP subscription billing, ANTHROPIC_API_KEY must be unset in that environment, so the tools run against your subscription rather than a metered key. This is the first and firmest design rule: the referee never generates, and the engine never infers.

#The honest-result contract

Semanticus treats itself as an agent harness, where the tool result is the real instruction channel to the agent, read at full attention on every call. So every operation is held to a result contract, and the load-bearing rule is honesty about what was and was not verified.

• Offline checks report skipped, never a fabricated pass. If a gate needs a live connection it does not have, it says so; it does not invent a green result.
• Failures teach the recovery. An error names what happened, the rule behind it, and the exact next step to take, rather than a bare exception.
• Results are structured and self-describing. They are token-budgeted, carry stable ids and counts rather than repeated blobs, and name the drill-down op to call for more detail.