@hviana/sema 0.1.0

package/src/alu/src/resonance.ts

@@ -0,0 +1,161 @@
+// resonance.ts — ALU's window onto meaning, and how the host pre-resolves it.
+//
+// ALU computes on bytes of any modality, but WHICH operation a byte span invokes
+// — and what the opposite of a symbol is — are questions of MEANING, and only
+// resonance can read meaning from an opaque span.  Two behaviours need it, and
+// BOTH are generic (any operation, any modality), not special cases:
+//
+//   • operation recognition — the operation a query asks for is, in general, NOT
+//     literally spelled.  "2+2" carries a "+", but "the integral of …", "the
+//     limit as …", "the derivative of …", or the analogous request expressed as
+//     an image / audio gesture carry NO operator symbol at all.  The operation
+//     must be recognised from the span's GIST resonating with the operation's
+//     CONCEPT.  This is the primary, generic recognition path; the literal
+//     symbol scan (alu.ts `scan`) is merely the easy special case layered under
+//     it.  Recognition is by gist, so it is modality-agnostic: a "+" drawn, a
+//     "plus" spoken, and the byte "+" all resonate toward the same `add`
+//     concept.
+//
+//   • the polymorphic inverse — the opposite of a SYMBOL (the bytes of a learnt
+//     form, any modality) is its RESONANT opposite, found in the resonance
+//     space, not by arithmetic.  The inverse of a number is its negation; the
+//     inverse of a form is its antonym/complement.
+//
+// Both are ASYNC in SEMA (they hit the gist / halo index), but the
+// lightest-derivation search is SYNCHRONOUS.  So — exactly as src/mind/pipeline.ts hoists
+// concept hops and connectors into Maps before the search and reads them
+// synchronously inside the rules — ALU splits each capability in two:
+//
+//   AluResonance (async)  — what the HOST implements over its resonance index.
+//                           Called only during pre-resolution.
+//   ResonanceSync (sync)  — the pre-resolved snapshot the op callbacks / rules
+//                           read (ResonanceSync is declared in operation.ts).
+//
+// {@link prefetchOpposites} and {@link prefetchRecognisedOps} turn the async side
+// into synchronous lookups for a known set of spans; the host calls them during
+// its pre-resolution pass.  This file is the ENTIRE coupling surface to SEMA —
+// ALU imports nothing from the mind or store; the host supplies a AluResonance
+// built over its own perception + resonance (gist nearness to the operation
+// vocabulary ALU exposes via `conceptForms`, and halo resonance for the
+// opposite).
+
+import type { ResonanceSync } from "./operation.js";
+
+/** A labelled concept form: the canonical operation name and one of its
+ *  surface forms, as bytes.  The host resonates opaque spans against these to
+ *  answer "which operation does this span MEAN?" (see parser.ts AluHost). */
+export interface ConceptAnchor {
+  name: string;
+  form: Uint8Array;
+}
+import { latin1 } from "../../bytes.js";
+
+/** The async resonance capability the host provides.  Both methods may return
+ *  null when resonance finds nothing above the host's own threshold — ALU then
+ *  declines to guess (operation unrecognised, inverse left unchanged).  This
+ *  keeps synthesis graph-evidenced: ALU never invents meaning resonance did not
+ *  supply. */
+export interface AluResonance {
+  /** The canonical operation a span's MEANING names, found by resonance over the
+   *  operation concepts — the GENERIC, modality-agnostic recognition path.  This
+   *  is how an operation that is NOT literally spelled (no "∫" for an integral,
+   *  no "+" for a sum drawn or spoken) is still recognised: the span's gist
+   *  resonates with the operation's concept.  Returns the canonical op name, or
+   *  null when nothing resonates above threshold. */
+  recogniseOp(bytes: Uint8Array): Promise<string | null>;
+  /** The resonant opposite of a symbol's bytes (its antonym / inverse in the
+   *  resonance space, any modality), or null.  The host finds it by halo
+   *  resonance over the negated concept. */
+  opposite(bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+
+/** A AluResonance that knows nothing — the default when the host wires none in,
+ *  so the kernel runs fully decoupled (operations resolve by literal forms only,
+ *  and a symbol inverse is left unchanged). */
+export const NO_ALU_RESONANCE: AluResonance = {
+  recogniseOp: async () => null,
+  opposite: async () => null,
+};
+
+/** Pre-resolve the resonant opposite of each symbol in `symbols`, awaiting the
+ *  host's async resonance once per distinct span, and return a SYNCHRONOUS
+ *  snapshot the op callbacks read during the search.  Keyed by the latin1 view
+ *  of the bytes (a lossless, stable string key — the same device the search's
+ *  chart uses).  This is the async→sync bridge for the polymorphic inverse,
+ *  mirroring how a concept hop's target is pre-resolved and read synchronously. */
+export async function prefetchOpposites(
+  resonance: AluResonance,
+  symbols: Iterable<Uint8Array>,
+): Promise<ResonanceSync> {
+  const table = new Map<string, Uint8Array>();
+  const seen = new Set<string>();
+  for (const bytes of symbols) {
+    const key = latin1(bytes);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const opp = await resonance.opposite(bytes);
+    if (opp) table.set(key, opp);
+  }
+  return {
+    opposite: (bytes: Uint8Array) => table.get(latin1(bytes)) ?? null,
+    // Opposites-only prefetch carries no op recognition; a higher-order nd op
+    // resolving through this falls back to literal forms / canonical names.
+    recogniseOp: () => null,
+  };
+}
+
+/** Pre-resolve BOTH capabilities a computation may need synchronously — the
+ *  resonant opposite of a symbol (for the polymorphic inverse) AND the operation
+ *  a symbol's MEANING names (for a higher-order nd op's function argument) — over
+ *  one set of candidate spans, and return a single {@link ResonanceSync}.  Each
+ *  distinct span is awaited once per capability.  This is the unified async→sync
+ *  bridge the host uses for an nd computation, where the same spans may serve as
+ *  inverse operands and as a reduce/map/filter operator.  Either lookup yields
+ *  null for a span that resonates with nothing, so callbacks decline rather than
+ *  guess. */
+export async function prefetchResonance(
+  resonance: AluResonance,
+  spans: Iterable<Uint8Array>,
+): Promise<ResonanceSync> {
+  const opposites = new Map<string, Uint8Array>();
+  const ops = new Map<string, string>();
+  const seen = new Set<string>();
+  for (const bytes of spans) {
+    const key = latin1(bytes);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const [opp, op] = await Promise.all([
+      resonance.opposite(bytes),
+      resonance.recogniseOp(bytes),
+    ]);
+    if (opp) opposites.set(key, opp);
+    if (op) ops.set(key, op);
+  }
+  return {
+    opposite: (bytes: Uint8Array) => opposites.get(latin1(bytes)) ?? null,
+    recogniseOp: (bytes: Uint8Array) => ops.get(latin1(bytes)) ?? null,
+  };
+}
+
+/** Pre-resolve, for each candidate span, the operation its MEANING names —
+ *  awaiting the host's async gist resonance once per distinct span — and return
+ *  a synchronous map keyed by the span's latin1 bytes → canonical op name.  This
+ *  is the async→sync bridge for the GENERIC operation-recognition path: a span
+ *  the literal scan could not classify (no operator symbol) but whose gist
+ *  resonates with an operation's concept.  Spans that resonate with nothing are
+ *  omitted, so the caller treats a miss as "not an operation". */
+export async function prefetchRecognisedOps(
+  resonance: AluResonance,
+  spans: Iterable<Uint8Array>,
+): Promise<Map<string, string>> {
+  const table = new Map<string, string>();
+  const seen = new Set<string>();
+  for (const bytes of spans) {
+    const key = latin1(bytes);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const op = await resonance.recogniseOp(bytes);
+    if (op) table.set(key, op);
+  }
+  return table;
+}

package/src/alu/src/text.ts

@@ -0,0 +1,83 @@
+// text.ts — the byte-class floor the ALU's lexing rests on.
+//
+// SEMA is byte-native and multimodal; the ALU keeps its knowledge of raw text
+// as small as possible.  What remains is the IRREDUCIBLE floor — the decimal
+// numeral grammar (digits ground a quantity exactly as the byte alphabet
+// grounds a symbol), whitespace as the universal spacing byte, and the list
+// grammar's delimiters — collected HERE, once, so no other module hardcodes a
+// character class of its own.  Everything above this floor (which spans name
+// operations, where terms begin and end, what an expression means) is resolved
+// from the operation registry, the host's geometric segmentation, or resonance.
+
+/** An ASCII decimal digit. */
+export const isDigitByte = (c: number): boolean => c >= 0x30 && c <= 0x39;
+
+/** The decimal point of a numeral. */
+export const DOT = 0x2e; // "."
+
+/** The explicit list container's delimiters — the canonical nd spelling the
+ *  codec emits, so a computed list feeds straight back in as an operand. */
+export const OPEN = 0x5b; // "["
+export const CLOSE = 0x5d; // "]"
+
+/** ASCII whitespace (space, tab, newline, carriage return) — the one spacing
+ *  convention bytes of every textual modality share. */
+export const isSpaceByte = (c: number): boolean =>
+  c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d;
+
+/** A byte that DELIMITS list elements inside an explicit container: whitespace,
+ *  a comma, or a semicolon.  Deliberately excludes anything that can sit inside
+ *  a numeral or a symbol token (letters, digits, sign/decimal `+ - .`) and the
+ *  brackets themselves, so an element's own bytes are never split. */
+export const isSepByte = (c: number): boolean =>
+  isSpaceByte(c) || c === 0x2c /* , */ || c === 0x3b /* ; */;
+
+/** The index of the first non-whitespace byte (or the length, if all space). */
+export function trimStart(b: Uint8Array): number {
+  let i = 0;
+  while (i < b.length && isSpaceByte(b[i])) i++;
+  return i;
+}
+
+/** The index one past the last non-whitespace byte (or 0, if all space). */
+export function trimEnd(b: Uint8Array): number {
+  let j = b.length;
+  const lo = trimStart(b);
+  while (j > lo && isSpaceByte(b[j - 1])) j--;
+  return j;
+}
+
+/** The index of the `]` matching the `[` at `open`, bracket-depth aware, or -1
+ *  when it is unbalanced — used to test whether a span is one explicit list
+ *  CONTAINER (its opening bracket closing exactly at its end). */
+export function matchBracket(b: Uint8Array, open: number): number {
+  let depth = 0;
+  for (let i = open; i < b.length; i++) {
+    if (b[i] === OPEN) depth++;
+    else if (b[i] === CLOSE && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The maximal non-whitespace runs of `bytes` within [from, to) — the spacing
+ *  floor's reading of "the tokens", shared by the structural host's segmenter
+ *  and the parser's term lexing so neither re-implements the walk. */
+export function nonSpaceRuns(
+  bytes: Uint8Array,
+  from = 0,
+  to = bytes.length,
+): Array<{ i: number; j: number }> {
+  const out: Array<{ i: number; j: number }> = [];
+  let i = from;
+  while (i < to) {
+    if (isSpaceByte(bytes[i])) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < to && !isSpaceByte(bytes[j])) j++;
+    out.push({ i, j });
+    i = j;
+  }
+  return out;
+}

package/src/alu/src/value.ts

@@ -0,0 +1,327 @@
+// value.ts — the ALU value model.
+//
+// One tagged union carries every kind of quantity the ALU computes on, so a
+// single Operation registry can dispatch on the tag rather than maintaining
+// disjoint kernels.  The four domains are exactly the strata the kernel needs:
+//
+//   • bit    — a logic value 0|1.  The completeness layer (nand and the gates
+//              derived from it) lives here.
+//   • int    — an EXACT integer (JS bigint).  The "everything derives from nand"
+//              bootstrap runs here: add is a ripple of full_adders, multiply is
+//              shift-add, and so on.  bigint keeps the proof exact past 2^53.
+//   • real   — an IEEE double.  The limit layer (converge, exp, sin, …) is
+//              intrinsically continuous, so it runs on the host's native reals
+//              rather than a fixed-point reimplementation atop bits.
+//   • symbol — a raw BYTE SPAN that is not a number.  SEMA is byte-native and
+//              multimodal: a symbol's bytes may name a written form, a region of
+//              an image, a fragment of audio — any learned form, in any
+//              modality.  ALU never interprets those bytes; it treats a symbol
+//              as an opaque token.  This is the carrier for the POLYMORPHIC
+//              inverse: the inverse of a number is its negation, but the inverse
+//              of a symbol is its RESONANT OPPOSITE — found in the resonance
+//              space, not by arithmetic (e.g. the bytes of "large" resolve to
+//              "small", but the mechanism is modality-agnostic — see
+//              resonance.ts).  Resonance is the only thing that can read meaning
+//              from a symbol, and ALU reaches it only through an injected
+//              capability, never directly.
+//
+//   • nd     — an N-DIMENSIONAL value: an ordered list of elements, each of which
+//              is ITSELF a Value of ANY domain — a scalar (bit/int/real/symbol)
+//              OR another nd.  So nd is recursive (a tensor is an nd of nds), it
+//              is RAGGED (rows need not be equal length — it is a list, not a
+//              rectangular array), and it is HETEROGENEOUS (a row may mix a
+//              number, a symbol, and a sub-list).  This one recursive case is the
+//              whole generalisation: there is no separate "vector" vs "matrix"
+//              type, only nd nesting, and the rank is read off the nesting depth.
+//              Every scalar operation lifts over it automatically (broadcast, see
+//              operation.ts), and the structural operations (the nd kernel) build
+//              the list-processing layer — map/reduce/filter/find/… — on a tiny
+//              core of nd/length/at, exactly as logic builds on nand.
+//
+// The module is pure: it knows nothing of SEMA, the store, or the search.  The
+// only host coupling is the injected ValueCodec, whose default lives here.
+
+/** Which stratum a {@link Value} belongs to.  Four scalar domains + the
+ *  recursive container `nd`. */
+export type Domain = "bit" | "int" | "real" | "symbol" | "nd";
+
+/** A quantity the ALU computes on — a tagged union over the scalar domains plus
+ *  the recursive n-dimensional container.  An `nd`'s `items` are themselves
+ *  Values of any domain, so nesting (a matrix = an nd of nd) and heterogeneity
+ *  (a list mixing numbers, symbols, sub-lists) are the same case. */
+export type Value =
+  | { domain: "bit"; b: 0 | 1 }
+  | { domain: "int"; n: bigint }
+  | { domain: "real"; x: number }
+  | { domain: "symbol"; bytes: Uint8Array }
+  | { domain: "nd"; items: Value[] };
+
+// ── constructors ──────────────────────────────────────────────────────────
+
+export const bit = (b: 0 | 1): Value => ({ domain: "bit", b });
+export const int = (n: bigint): Value => ({ domain: "int", n });
+export const real = (x: number): Value => ({ domain: "real", x });
+/** A symbolic value: an opaque byte span of any modality (see module note). */
+export const symbol = (bytes: Uint8Array): Value => ({
+  domain: "symbol",
+  bytes,
+});
+/** An n-dimensional value: an ordered list of element values (each any domain,
+ *  including a nested nd).  See the module note on nd. */
+export const nd = (items: Value[]): Value => ({ domain: "nd", items });
+
+/** The domain tag of a value. */
+export const tagOf = (v: Value): Domain => v.domain;
+
+/** Whether a value is a numeric SCALAR (bit, int, or real) — an nd is not, even
+ *  if every element is numeric (it is a container; reduce it to a scalar). */
+export function isNumeric(v: Value): boolean {
+  return v.domain === "bit" || v.domain === "int" || v.domain === "real";
+}
+
+/** Whether a value is the n-dimensional container. */
+export function isNd(v: Value): v is { domain: "nd"; items: Value[] } {
+  return v.domain === "nd";
+}
+
+/** Collect, into `out`, every SYMBOL byte span reachable inside a value — itself
+ *  when it is a symbol, or each element recursively when it is an nd.  These are
+ *  the spans whose MEANING (a resonant opposite, the operation a higher-order op
+ *  argument names) the host pre-resolves before a computation; numbers carry no
+ *  meaning to resolve, so they are skipped. */
+export function symbolSpans(v: Value, out: Uint8Array[]): void {
+  if (v.domain === "symbol") out.push(v.bytes);
+  else if (isNd(v)) { for (const e of v.items) symbolSpans(e, out); }
+}
+
+// ── coercions (the functor's object map between domains) ────────────────────
+
+/** A value as a JS number — bit→0|1, int→Number, real as-is.  Throws on a
+ *  symbol, because arithmetic on an opaque form is a programming error the
+ *  caller (or the graph adapter's try/catch) should surface, never silently
+ *  coerce to NaN. */
+export function asReal(v: Value): number {
+  switch (v.domain) {
+    case "bit":
+      return v.b;
+    case "int":
+      return Number(v.n);
+    case "real":
+      return v.x;
+    case "symbol":
+      throw new TypeError("asReal: a symbol value has no numeric reading");
+    case "nd":
+      // An nd has no scalar reading: a scalar primitive never sees one, because
+      // broadcast (operation.ts) lifts it element-wise first.  Reaching here
+      // means a structural op was mis-called on a list as if it were a scalar.
+      throw new TypeError("asReal: an nd value has no scalar numeric reading");
+  }
+}
+
+/** A value as an exact bigint — real is truncated toward zero (a real that is
+ *  not integral loses its fraction; callers wanting exactness keep it int). */
+export function asInt(v: Value): bigint {
+  switch (v.domain) {
+    case "bit":
+      return BigInt(v.b);
+    case "int":
+      return v.n;
+    case "real":
+      return BigInt(Math.trunc(v.x));
+    case "symbol":
+      throw new TypeError("asInt: a symbol value has no integer reading");
+    case "nd":
+      throw new TypeError("asInt: an nd value has no scalar integer reading");
+  }
+}
+
+/** A value as a logic bit — nonzero numbers read as 1, zero as 0.  Throws on a
+ *  symbol (an opaque form is not a truth value). */
+export function asBit(v: Value): 0 | 1 {
+  switch (v.domain) {
+    case "bit":
+      return v.b;
+    case "int":
+      return v.n === 0n ? 0 : 1;
+    case "real":
+      return v.x === 0 ? 0 : 1;
+    case "symbol":
+      throw new TypeError("asBit: a symbol value is not a truth value");
+    case "nd":
+      throw new TypeError("asBit: an nd value is not a scalar truth value");
+  }
+}
+
+/** Promote a value into a target numeric domain (bit ⊂ int ⊂ real).  Used when
+ *  a mixed-domain expression must agree on one domain before a primitive runs —
+ *  the rule is the natural lattice: any real operand pulls the whole expression
+ *  to real, otherwise any int pulls it to int, otherwise bit. */
+export function coerce(v: Value, domain: "bit" | "int" | "real"): Value {
+  if (v.domain === domain) return v;
+  switch (domain) {
+    case "bit":
+      return bit(asBit(v));
+    case "int":
+      return int(asInt(v));
+    case "real":
+      return real(asReal(v));
+  }
+}
+
+/** The common numeric domain of a list of operands, by the bit ⊂ int ⊂ real
+ *  lattice: real if any operand is real, else int if any is int, else bit.
+ *  Throws if any operand is a symbol.  This is how a polymorphic arithmetic op
+ *  decides whether to take the exact bigint path or the native-double path. */
+export function joinDomain(args: Value[]): "bit" | "int" | "real" {
+  let d: "bit" | "int" | "real" = "bit";
+  for (const a of args) {
+    if (a.domain === "symbol") {
+      throw new TypeError("joinDomain: cannot join a symbol value numerically");
+    }
+    if (a.domain === "nd") {
+      throw new TypeError("joinDomain: cannot join an nd value numerically");
+    }
+    if (a.domain === "real") return "real";
+    if (a.domain === "int" && d === "bit") d = "int";
+  }
+  return d;
+}
+
+// ── the byte ⇄ value codec ──────────────────────────────────────────────────
+
+/** The host's bridge between byte spans and values.  ALU emits and consumes
+ *  bytes only through this, so the surrounding system owns how a number is
+ *  spelled.  A default ({@link decimalCodec}) is provided. */
+export interface ValueCodec {
+  encode(v: Value): Uint8Array;
+  decode(bytes: Uint8Array): Value | null;
+}
+
+const ASCII = {
+  decode: (b: Uint8Array): string => {
+    let s = "";
+    for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]);
+    return s;
+  },
+  encode: (s: string): Uint8Array => {
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 0xff;
+    return out;
+  },
+};
+
+/** A decimal numeral, sign, optional fraction, optional exponent — the syntax
+ *  {@link parseScalar} accepts as a number.  Anything else is a symbol. */
+const NUMERAL = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** Concatenate byte arrays — used to build an nd literal's encoding without
+ *  routing a (possibly non-ASCII, multimodal) symbol's bytes through a string. */
+function concatBytes(arrs: Uint8Array[]): Uint8Array {
+  let len = 0;
+  for (const a of arrs) len += a.length;
+  const out = new Uint8Array(len);
+  let o = 0;
+  for (const a of arrs) {
+    out.set(a, o);
+    o += a.length;
+  }
+  return out;
+}
+
+/** Parse a SCALAR span: a clean integer numeral → exact int, a fractional/
+ *  exponent numeral → real, anything else → a symbol carrying `bytes` verbatim.
+ *  Strict, so it never hijacks a form that merely begins with a digit. */
+function parseScalar(bytes: Uint8Array, s: string): Value {
+  if (s.length > 0 && NUMERAL.test(s)) {
+    if (/[.eE]/.test(s)) {
+      const x = Number(s);
+      if (Number.isFinite(x)) return real(x);
+    } else {
+      // A clean integer: strip a leading '+' that BigInt rejects.
+      try {
+        return int(BigInt(s[0] === "+" ? s.slice(1) : s));
+      } catch {
+        /* fall through to symbol */
+      }
+    }
+  }
+  return symbol(bytes);
+}
+
+/** Parse a byte span into a SCALAR value: a clean integer numeral → exact int, a
+ *  fractional/exponent numeral → real, anything else → a symbol carrying its
+ *  bytes verbatim for the polymorphic inverse.
+ *
+ *  This is the IRREDUCIBLE FLOOR — and the ONLY structure read at the value
+ *  model's base: a number-form's digits ground a quantity, the exact analogue of
+ *  the byte alphabet grounding a symbol.  It does NOT read n-dimensional
+ *  STRUCTURE (no bracket/comma grammar); recognising a list — a run of element
+ *  values joined by a consistent separator — is layered ONE level up, in the
+ *  facade's {@link "./alu.js".Alu.recogniseValue} (over the operand scanner),
+ *  which calls this for each element.  So the codec's `decode` (which delegates
+ *  here) is scalar-only: a bracket literal decodes to an opaque symbol.
+ *
+ *  Numerals are ASCII by construction; for any other byte content the bytes are
+ *  preserved opaquely, so a symbol of any modality round-trips untouched. */
+export function parseValue(bytes: Uint8Array): Value {
+  return parseScalar(bytes, ASCII.decode(bytes));
+}
+
+/** Canonically format a real as a decimal string: round to `precision` places,
+ *  then trim trailing zeros (and a bare trailing point), normalising -0 to 0.
+ *  Determinism here is load-bearing — the search keys an output span by its
+ *  bytes, so two derivations of the same number MUST spell it identically. */
+export function formatReal(x: number, precision: number): string {
+  if (!Number.isFinite(x)) return String(x); // "Infinity" / "NaN" / "-Infinity"
+  let s = x.toFixed(precision);
+  if (s.indexOf(".") >= 0) s = s.replace(/\.?0+$/, "");
+  if (s === "-0" || s === "") s = "0";
+  return s;
+}
+
+/** The default codec: integers as exact decimals, reals canonically formatted,
+ *  bits as "0"/"1", symbols as their own bytes (verbatim, any modality), and an
+ *  nd as a bracket literal `[e0,e1,…]` of its element encodings (recursive, so a
+ *  nested list nests its brackets and a symbol element keeps its raw bytes).
+ *  `precision` controls real rounding (see {@link formatReal}).
+ *
+ *  The bracket layout is the CANONICAL OUTPUT spelling of an `nd` — one
+ *  deterministic form, the analogue of decimal for a number, so the search's
+ *  chart memoises identical results identically.  It is an ENCODE-only grammar:
+ *  {@link parseValue} (hence `decode`) reads only scalars, never structure — a
+ *  bracket literal decodes back to an opaque symbol.  Reading list STRUCTURE from
+ *  bytes is layered one level up, in {@link "./alu.js".Alu.recogniseValue}. */
+export function decimalCodec(precision: number): ValueCodec {
+  const enc = (v: Value): Uint8Array => {
+    switch (v.domain) {
+      case "bit":
+        return ASCII.encode(String(v.b));
+      case "int":
+        return ASCII.encode(v.n.toString());
+      case "real":
+        return ASCII.encode(formatReal(v.x, precision));
+      case "symbol":
+        return v.bytes;
+      case "nd": {
+        // [e0,e1,…] at the byte level, so a symbol element's arbitrary
+        // (possibly non-ASCII / multimodal) bytes pass through untouched.
+        const OPEN = ASCII.encode("[");
+        const CLOSE = ASCII.encode("]");
+        const COMMA = ASCII.encode(",");
+        const parts: Uint8Array[] = [OPEN];
+        for (let i = 0; i < v.items.length; i++) {
+          if (i > 0) parts.push(COMMA);
+          parts.push(enc(v.items[i]));
+        }
+        parts.push(CLOSE);
+        return concatBytes(parts);
+      }
+    }
+  };
+  return {
+    encode: enc,
+    decode(bytes: Uint8Array): Value | null {
+      return parseValue(bytes);
+    },
+  };
+}