@human-synthesis/norns-tron 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Teodoroiu / Human Synthesis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PERFORMANCE.md

@@ -0,0 +1,179 @@
+# APITRON — ghid de performanță maximă
+
+Toate cifrele de mai jos sunt măsurate (Node v22, Xeon 2 nuclee, benchmark
+pereche-întrețesut față de JSON nativ, mediana a 15 runde). **Raportul este
+TRON/JSON — sub 1.00 înseamnă că TRON e mai rapid.**
+
+---
+
+## 1. Alege modul corect — asta contează cel mai mult
+
+| situație | folosește | decode | encode | round-trip | tokeni |
+|---|---|---:|---:|---:|---:|
+| API intern (ambele capete codul tău) | **`defineSchema`** | 0.40–0.87x | 0.66–0.93x | 0.57–0.91x | 11–61% |
+| Prompt LLM / consumator terț | **`encode`/`decode`** | 0.45–0.77x | 0.97–1.77x | 0.76–1.22x | 26–61% |
+| Date numerice/columnare | **`decodeColumnar`** | ~0.30x | — | — | 35% |
+| Payload sub ~1 KB | **JSON simplu** | — | — | — | 0% |
+
+Diferența dintre modul cu schemă și cel auto-descriptiv este **cea mai mare
+optimizare disponibilă** — mai mare decât orice reglaj fin. Modul cu schemă
+câștigă pe toate axele, la orice dimensiune.
+
+---
+
+## 2. PRELOAD o singură dată, la pornirea aplicației
+
+Greșeala numărul unu este să compilezi schema la fiecare cerere. `defineSchema`
+face muncă reală: rezolvă ordinea câmpurilor, tabelele de enum, calea și
+**compilează constructorul de rând cu `new Function`**. Fă asta o singură dată.
+
+```js
+// schemas.js — modul la nivel de aplicație, evaluat o singură dată
+const { defineSchema } = require('apitron');
+
+exports.users = defineSchema({
+  id: 'users.v1',
+  fields: ['id', 'name', 'role', 'region', 'score', 'active'],
+  enums: {
+    role: ['admin', 'user', 'editor'],
+    region: ['us-east-1', 'eu-west-1'],
+    active: [false, true],
+  },
+  path: '$.data',
+});
+```
+
+```js
+// handler — per cerere, doar encode/decode
+const { users } = require('./schemas');
+app.get('/users', (req, res) => {
+  res.type('text/plain').send(users.encode({ meta: {...}, data: rows }));
+});
+```
+
+**Efect măsurat** (envelope, 25 de rânduri): decode 1.21x → **0.63x**,
+encode 2.49x → **0.90x**. Pe payload-uri mici, compilarea per-cerere e diferența
+dintre a pierde și a câștiga.
+
+---
+
+## 3. Declară `enums` pentru coloanele cu puține valori distincte
+
+Orice coloană de string/boolean cu cardinalitate mică (status, rol, regiune,
+tip, flag-uri) devine un întreg pe fir.
+
+```js
+enums: { status: ['ok', 'retried', 'failed'], active: [false, true] }
+```
+
+Trei efecte simultane:
+1. **Mai puțini tokeni** — `events-10k`: 38% → **42%**.
+2. **Decode mai rapid** — nu se mai alocă string-uri pentru coloana aceea.
+3. **Deblochează WASM** — o coloană de tip dicționar este un întreg pe fir, deci
+   un tabel cu string-uri devine eligibil pentru scanerul WASM. `tabular-10k`
+   este *respins* de WASM fără dicționare și **acceptat** cu ele.
+
+**Restricție:** valorile din `enums` trebuie să fie string sau boolean.
+Valorile numerice sunt respinse explicit — ar fi ambigue cu indicii de dicționar
+și s-ar decoda ca `undefined`.
+
+---
+
+## 4. Nu codifica payload-uri mici
+
+`encode()` are deja un prag de 1 KB și returnează JSON simplu sub el; `decode()`
+îl citește transparent. Nu-l dezactiva fără motiv.
+
+| rânduri | JSON | decode | round-trip |
+|---:|---:|---:|---:|
+| 5 | 0.5 KB | 4.80x | 5.16x |
+| 25 | 2.1 KB | 1.21x | 1.70x |
+| 100 | 8.4 KB | **0.78x** | 1.16x |
+| 1000 | 86 KB | **0.68x** | **1.01x** |
+| 10000 | 881 KB | **0.67x** | **0.94x** |
+
+(Modul auto-descriptiv. Cu schemă preîncărcată pragul dispare — vezi §1.)
+
+---
+
+## 5. Când datele sunt numerice, ia banda columnară
+
+Cea mai rapidă cale din bibliotecă. Nu construiește deloc obiecte JS.
+
+**Atenție:** trebuie emis cu `encodeColumnar()`. Ieșirea implicită a lui
+`encode()` conține declarații `table` (corp JSON simplu), pe care scanerul WASM
+nu le acceptă — `decodeColumnar` va returna `undefined` pentru ea.
+
+```js
+const wire = encodeColumnar(rows);            // server
+const col  = decodeColumnar(wire, /* copy */ true);   // client
+if (col) {
+  // acces row-major: valoarea coloanei c din rândul r
+  const v = col.tape[r * col.cols + c];
+} else {
+  const obj = decode(wire);   // nu era eligibil, cale normală
+}
+```
+
+**~0.30x față de `JSON.parse`** (de ~3.3 ori mai rapid). `copy: true` detașează
+banda din memoria WASM — fără el, următorul apel de decode o invalidează.
+
+---
+
+## 6. Reține că `table: 'nested'` schimbă viteza pe tokeni
+
+Implicit (`table: true`) tabelizează doar rândurile plate: câștig pur, și mai
+rapid și mai puțini tokeni. `'nested'` acceptă și rânduri cu obiecte imbricate —
+mai rapid, dar formele interioare își pierd compresia proprie.
+
+Măsurat pe `nested-500`: round-trip 2.47x → **0.89x**, dar tokenii scad de la
+**26% → 11%**. Alege în funcție de ce plătești: latență sau tokeni.
+
+---
+
+## 7. Detalii de runtime care contează
+
+- **`new Function`** — trampolina și constructorii de rând îl folosesc. Sub un
+  CSP strict fără `unsafe-eval` biblioteca revine automat la scaner
+  (`parseFast`), ~1.1–1.5x. Funcționează corect, doar mai lent.
+- **WASM este opțional.** În Node se încarcă singur. În browser trimite tu
+  binarul: `setWasmBinary(await (await fetch('/parserTron2.wasm')).arrayBuffer())`.
+  Fără el nimic nu se strică — dispecerul pur și simplu nu ia calea WASM.
+- **Trimite `Content-Type: text/plain`** (sau un tip propriu, ex.
+  `application/vnd.tron`). Nu `application/json` — corpul poate conține un
+  preambul care nu e JSON valid.
+- **Compresia HTTP se aplică în continuare.** TRON reduce octeții *înainte* de
+  gzip/brotli; câștigurile se compun, dar mai puțin decât liniar.
+- **Nu re-encoda ce nu s-a schimbat.** Răspunsurile cacheabile se codifică o
+  dată; costul de encode dispare complet și rămâne doar câștigul la decode.
+
+---
+
+## 8. Listă de verificare
+
+- [ ] `defineSchema` apelat o singură dată, la pornire, nu per cerere
+- [ ] `enums` declarate pentru toate coloanele categorice și booleene
+- [ ] Payload-urile sub ~1 KB rămân JSON (pragul implicit se ocupă)
+- [ ] `encodeColumnar` + `decodeColumnar` folosite împreună acolo unde datele sunt numerice
+- [ ] `Content-Type` setat pe `text/plain`, nu `application/json`
+- [ ] În browser: `setWasmBinary` apelat, sau acceptat conștient fallback-ul
+- [ ] Măsoară cu propriile date înainte de a te baza pe aceste cifre
+
+---
+
+## 9. Metodologie (ca să poți reproduce)
+
+Benchmark-ul naiv dădea rezultate contradictorii — două căi de cod identice
+difereau cu 43% — pentru că rularea mai multor decodoare în același proces face
+inline cache-urile V8 polimorfe. Cifrele de aici sunt măsurate cu:
+
+- **un proces copil per set de date**, ca V8 să optimizeze pentru o singură formă;
+- **pereche întrețesută** față de echivalentul JSON nativ (A/B/A/B, cu ordinea
+  alternată), ca ambele părți să vadă aceleași condiții;
+- **mediana a 15 runde**.
+
+Milisecundele absolute depind de mașină; **rapoartele** sunt semnalul.
+
+Corectitudinea: **220.118 verificări** adversariale și fuzz pe suita completă,
+plus 22 de teste dedicate modului cu schemă și 1.500 de round-trip-uri fuzz — 0
+eșecuri.

package/README.md

@@ -0,0 +1,108 @@
+# @human-synthesis/norns-tron
+
+TRON serialization for the Norns ecosystem — a token-efficient, faster-than-JSON
+wire format for APIs and LLM-facing output. Zero runtime dependencies.
+
+TRON cuts **11–61% of tokens** vs JSON and, used correctly, beats
+`JSON.parse` / `JSON.stringify` on decode, encode, and round-trip. Plain JSON is
+valid TRON, so adoption is progressive and rollback is trivial. See
+[PERFORMANCE.md](./PERFORMANCE.md) for measured numbers and usage guidance.
+
+The encoder/decoder core is absorbed from the `apitron` research library; this
+package adds the Norns framework glue as subpath exports.
+
+```
+@human-synthesis/norns-tron           encode / decode / defineSchema / registry
+@human-synthesis/norns-tron/server    tronSerializer() for norns route()
+@human-synthesis/norns-tron/client    api fetch wrapper that speaks TRON
+@human-synthesis/norns-tron/valibot   derive wire schemas from valibot schemas
+```
+
+## Turn it on app-wide
+
+```coffee
+# src/hooks.server.c
+import { boot } from '@human-synthesis/norns/server'
+import { tronSerializer } from '@human-synthesis/norns-tron/server'
+
+app := await boot
+  features: import.meta.glob('./lib/*/server/module.c', eager: true)
+  serializer: tronSerializer()
+```
+
+Every `route()` response is now content-negotiated: clients that send
+`Accept: application/tron` get TRON, everyone else (curl, third parties,
+existing code) keeps getting JSON. Nothing breaks. Remove the `serializer`
+line to roll the whole thing back.
+
+Per-route control:
+
+```coffee
+export GET  := route serializer: tronSerializer({ schema: noteWire }), handler: ...
+export POST := route serializer: null, handler: ...   # force plain JSON
+```
+
+## Call it from the client
+
+```coffee
+import { api, createApi } from '@human-synthesis/norns-tron/client'
+
+users := await api.get '/api/users'          # sends Accept: application/tron
+await api.post '/api/notes', { title, body } # body goes out as TRON too
+
+# inside a load function, keep SvelteKit's fetch semantics:
+api := createApi { fetch }
+```
+
+The 1.7 KB WASM scanner ships embedded as base64 — no asset wiring, works in
+Node, Bun, and the browser. Under a strict CSP without `unsafe-eval` the
+decoder transparently falls back to the JS scanner (~1.1–1.5x).
+
+## Schema mode — the fastest path for internal endpoints
+
+Both ends already know the shape from the feature contract, so nothing
+descriptive needs to travel. Derive the wire schema from the valibot schema
+you already have in `shared/schema.c`:
+
+```coffee
+# src/lib/notes/shared/schema.c
+import * as v from 'valibot'
+import { tronSchemaFromValibot } from '@human-synthesis/norns-tron/valibot'
+
+export noteSchema := v.object
+  id: v.number()
+  title: v.string()
+  status: v.picklist ['draft', 'published']
+
+export noteWire := tronSchemaFromValibot noteSchema, { id: 'notes.v1', path: '$.data' }
+```
+
+`picklist`/`enum` fields become dictionary columns (integers on the wire),
+booleans become 0/1. Compile once at module scope — never per request.
+The `#notes.v1` tag makes version mismatches fail loudly instead of
+misdecoding; use `createRegistry()` on a client that consumes several shapes.
+
+## Semantics and limits
+
+- Same value semantics as JSON: `toJSON()` is honored, so a `Date` arrives as
+  its ISO string (not a `Date` — same as `response.json()`). `Map`/`Set`
+  serialize as `{}` and `BigInt` throws, exactly like `JSON.stringify`; dev
+  mode logs a warning when a route returns them.
+- **Not for `load` / form actions** — SvelteKit serializes those with devalue
+  (which preserves Dates, Maps, Sets). This package targets `route()`
+  endpoints, LLM-facing output, and service-to-service payloads.
+- Payloads under ~1 KB are emitted as plain JSON automatically (still decoded
+  transparently) — below that size TRON's fixed costs don't pay for themselves.
+- The wire content type is `application/tron`, not `application/json`: a TRON
+  body may carry a declaration preamble that is not valid JSON.
+- Schema mode uses `new Function` for the row constructor (server-side this is
+  a non-issue; in CSP-restricted browsers the fallback scanner takes over).
+
+## Development
+
+```sh
+bun test              # 38 tests: core roundtrips, Date regression, server/client glue, valibot derivation
+bun run embed-wasm    # regenerate src/core/wasm-bytes.js after replacing wasm/parserTron2.wasm
+```
+
+License: MIT.

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@human-synthesis/norns-tron",
+	"version": "0.0.1",
+	"description": "TRON serialization for the Norns ecosystem — token-efficient, faster-than-JSON wire format for APIs and LLM-facing output.",
+	"license": "MIT",
+	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/human-synthesis/norns-tron.git"
+	},
+	"files": [
+		"src",
+		"wasm",
+		"README.md",
+		"PERFORMANCE.md"
+	],
+	"scripts": {
+		"test": "bun test",
+		"embed-wasm": "bun scripts/embed-wasm.mjs"
+	},
+	"exports": {
+		".": "./src/index.js",
+		"./server": "./src/server.js",
+		"./client": "./src/client.js",
+		"./valibot": "./src/valibot.js",
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"valibot": ">=0.31.0"
+	},
+	"peerDependenciesMeta": {
+		"valibot": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/client.d.ts

@@ -0,0 +1,39 @@
+export const TRON_CONTENT_TYPE: 'application/tron';
+
+export class ApiError extends Error {
+	status: number;
+	body: unknown;
+	response: Response;
+}
+
+/** Decode a Response by its content-type (TRON, JSON, or raw text). */
+export function parseResponse(res: Response): Promise<unknown>;
+
+export interface ApiDefaults {
+	/** fetch impl — pass SvelteKit's `fetch` inside load functions. */
+	fetch?: typeof fetch;
+	/** URL prefix, e.g. 'https://api.example.com'. */
+	base?: string;
+	/** Headers sent on every request. */
+	headers?: Record<string, string>;
+}
+
+export interface RequestOptions {
+	fetch?: typeof fetch;
+	headers?: Record<string, string>;
+	init?: RequestInit;
+}
+
+export interface Api {
+	request(method: string, url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
+	get(url: string, opts?: RequestOptions): Promise<any>;
+	del(url: string, opts?: RequestOptions): Promise<any>;
+	post(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
+	put(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
+	patch(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
+}
+
+export function createApi(defaults?: ApiDefaults): Api;
+
+/** Default instance for browser code. In load functions use createApi({ fetch }). */
+export const api: Api;

package/src/client.js

@@ -0,0 +1,86 @@
+/**
+ * Client fetch wrapper that speaks TRON with a norns `route()` endpoint.
+ *
+ *   import { api } from '@human-synthesis/norns-tron/client';
+ *   const users = await api.get('/api/users');
+ *   await api.post('/api/notes', { title, body });
+ *
+ * In a load function, pass SvelteKit's fetch so relative URLs and SSR
+ * de-duplication keep working:
+ *   const api = createApi({ fetch });
+ *
+ * The WASM scanner ships embedded (~2.3 KB base64) and initializes lazily, so
+ * no asset wiring is needed in the browser. Under a strict CSP without
+ * `unsafe-eval` the decoder transparently falls back to the JS scanner.
+ */
+import { decode, encode } from './index.js';
+
+export const TRON_CONTENT_TYPE = 'application/tron';
+const ACCEPT = 'application/tron, application/json;q=0.9, */*;q=0.1';
+
+export class ApiError extends Error {
+	/**
+	 * @param {number} status
+	 * @param {any} body decoded error body (message/issues from route())
+	 * @param {Response} response
+	 */
+	constructor(status, body, response) {
+		super(body?.message ?? `HTTP ${status}`);
+		this.name = 'ApiError';
+		this.status = status;
+		this.body = body;
+		this.response = response;
+	}
+}
+
+/** Decode a Response by its content-type (TRON, JSON, or raw text). */
+export async function parseResponse(res) {
+	if (res.status === 204) return null;
+	const type = res.headers.get('content-type')?.split(';', 1)[0]?.trim() ?? '';
+	const text = await res.text();
+	if (text === '') return null;
+	if (type === TRON_CONTENT_TYPE) return decode(text);
+	if (type === 'application/json' || type.endsWith('+json')) return JSON.parse(text);
+	return text;
+}
+
+/**
+ * @param {object} [defaults]
+ * @param {typeof fetch} [defaults.fetch] fetch impl (pass SvelteKit's in load functions)
+ * @param {string} [defaults.base] URL prefix, e.g. 'https://api.example.com'
+ * @param {Record<string, string>} [defaults.headers] headers sent on every request
+ */
+export function createApi(defaults = {}) {
+	const base = defaults.base ?? '';
+
+	async function request(method, url, body, opts = {}) {
+		// Resolve fetch per call: in the browser `globalThis.fetch` must not be
+		// captured at module-import time (SSR would freeze the server's fetch).
+		const doFetch = opts.fetch ?? defaults.fetch ?? globalThis.fetch;
+		const headers = { accept: ACCEPT, ...defaults.headers, ...opts.headers };
+		/** @type {RequestInit} */
+		const init = { method, headers, ...opts.init };
+		if (body !== undefined) {
+			// encode() emits plain JSON under 1 KB — still valid TRON, and the
+			// server's parseBody reads both, so the content type stays stable.
+			headers['content-type'] = TRON_CONTENT_TYPE;
+			init.body = encode(body);
+		}
+		const res = await doFetch(base + url, init);
+		const parsed = await parseResponse(res);
+		if (!res.ok) throw new ApiError(res.status, parsed, res);
+		return parsed;
+	}
+
+	return {
+		request,
+		get: (url, opts) => request('GET', url, undefined, opts),
+		del: (url, opts) => request('DELETE', url, undefined, opts),
+		post: (url, body, opts) => request('POST', url, body, opts),
+		put: (url, body, opts) => request('PUT', url, body, opts),
+		patch: (url, body, opts) => request('PATCH', url, body, opts)
+	};
+}
+
+/** Default instance for browser code. In load functions use createApi({ fetch }). */
+export const api = createApi();

package/src/core/tron-auto.js

@@ -0,0 +1,85 @@
+// Auto-dispatching decoder. No single strategy wins on every shape, so pick
+// per document from cheap signals available in the prelude + a short probe:
+//
+//   numeric columnar, all classed        -> WASM tape (4x JSON.parse)
+//   single/multi-class uniform tables    -> trampoline (0.7-0.9x)
+//   nested / irregular / tiny            -> parseFast scanner (~1.2x)
+//
+// The probe reads only the class declarations and a small prefix of the body,
+// never the whole payload, so dispatch cost is O(prelude), not O(document).
+
+import * as TRON from './tron.js';
+import * as TRAMP from './tron-trampoline.js';
+import * as WASM from './tron-wasm.js';
+import * as TBL from './tron-table.js';
+
+const SMALL_DOC = 4096;         // below this, native JSON.parse setup dominates
+const PROBE_ROWS = 3;
+
+function pickStrategy(text) {
+  const pre = TRON.parsePrelude(text);
+  const names = Object.keys(pre.classes);
+  if (names.length === 0) return 'json';     // plain JSON body
+  if (text.length < SMALL_DOC) return 'fast';
+  if (text.indexOf('\u0001') !== -1) return 'fast';
+
+  // Several classes means heterogeneous, nesting-heavy data: the trampoline's
+  // generic walk loses badly there (measured 1.8x) while the scanner stays
+  // ~1.1x. One class means a dominant uniform run - the trampoline's home turf.
+  if (names.length > 1) return 'fast';
+
+  // Body must look like a root array of instances for the tight paths.
+  const body = text.slice(pre.end);
+  if (body.charCodeAt(0) !== 91 /* [ */) return 'tramp-generic';
+
+  // Probe the first few rows for non-scalar fields (nested objects/arrays).
+  let i = 1, rows = 0, sawNonScalar = false;
+  while (rows < PROBE_ROWS && i < body.length) {
+    const open = body.indexOf('(', i);
+    if (open === -1) break;
+    const close = body.indexOf(')', open);
+    if (close === -1) break;
+    const row = body.slice(open + 1, close);
+    if (row.indexOf('[') !== -1 || row.indexOf('{') !== -1) sawNonScalar = true;
+    i = close + 1; rows++;
+  }
+  if (sawNonScalar) return 'tramp-generic';
+  return 'tramp';
+}
+
+function decode(text, opts) {
+  // TABLE MODE first: if the document declares where its tables live, decoding
+  // is JSON.parse + a constructor loop with no text transform at all.
+  const pre = TRON.parsePrelude(text);
+  if (pre.tables && pre.tables.length > 0) {
+    const t = TBL.decode(text, pre);
+    if (t !== undefined) return t;
+  }
+  const strategy = (opts && opts.strategy) || pickStrategy(text);
+  switch (strategy) {
+    case 'json': return JSON.parse(text.slice(TRON.parsePrelude(text).end) || text);
+    case 'fast': return TRON.parseFast(text);
+    case 'tramp': {
+      // Try WASM first for uniform single-class rows. The WASM scanner
+      // validates and rejects anything it cannot represent exactly, so an
+      // undefined return is a definitive "not eligible", not a guess.
+      if (!(opts && opts.noWasm) && !(opts && opts.lazy)) {
+        const w = WASM.decode(text);
+        if (w !== undefined) return w;
+      }
+      return (opts && opts.lazy) ? TRAMP.decodeLazy(text) : TRAMP.decode(text);
+    }
+    case 'tramp-generic': return TRAMP.decode(text);
+    default: return TRON.parseFast(text);
+  }
+}
+
+// Columnar decode: returns a Float64Array view instead of JS objects for
+// all-numeric (or fully dictionary-encoded) tables. Undefined when the payload
+// is not eligible. This is the mode that runs ~4x faster than JSON.parse.
+function decodeColumnar(text, copy) {
+  return WASM.decodeColumnar(text, copy);
+}
+
+const wasmAvailable = () => WASM.available();
+export { decode, decodeColumnar, pickStrategy, wasmAvailable };