@rhizomes/rhizomatic 0.1.0

package/src/cbor.ts

@@ -0,0 +1,280 @@
+// Deterministic CBOR encoder — the Rhizomatic v0 canonicalization profile (RFC 8949 §4.2.1,
+// as refined in spec/01-delta.ERRATA.md). Hand-rolled on purpose: this must reproduce the Rust
+// encoder byte-for-byte, and the only way to guarantee that is to own every byte.
+//
+// Supported data items (exactly what the delta model needs): text string, float (numbers),
+// bool, definite-length array, definite-length map (text-string keys, sorted).
+
+export type CborValue =
+  | { readonly t: "tstr"; readonly v: string }
+  | { readonly t: "float"; readonly v: number }
+  | { readonly t: "bool"; readonly v: boolean }
+  | { readonly t: "array"; readonly v: readonly CborValue[] }
+  | { readonly t: "map"; readonly v: ReadonlyArray<readonly [string, CborValue]> };
+
+export const tstr = (v: string): CborValue => ({ t: "tstr", v });
+export const float = (v: number): CborValue => ({ t: "float", v });
+export const bool = (v: boolean): CborValue => ({ t: "bool", v });
+export const array = (v: readonly CborValue[]): CborValue => ({ t: "array", v });
+export const map = (v: ReadonlyArray<readonly [string, CborValue]>): CborValue => ({ t: "map", v });
+
+class ByteSink {
+  private readonly bytes: number[] = [];
+  push(...b: number[]): void {
+    for (const x of b) this.bytes.push(x & 0xff);
+  }
+  pushBytes(arr: Uint8Array): void {
+    for (const x of arr) this.bytes.push(x);
+  }
+  toUint8Array(): Uint8Array {
+    return Uint8Array.from(this.bytes);
+  }
+}
+
+// Write a CBOR head: major type (high 3 bits) plus an unsigned argument, shortest form.
+function writeHead(sink: ByteSink, major: number, arg: number): void {
+  const mt = major << 5;
+  if (arg < 24) {
+    sink.push(mt | arg);
+  } else if (arg < 0x100) {
+    sink.push(mt | 24, arg);
+  } else if (arg < 0x10000) {
+    sink.push(mt | 25, (arg >> 8) & 0xff, arg & 0xff);
+  } else if (arg <= 0xffffffff) {
+    sink.push(mt | 26, (arg >>> 24) & 0xff, (arg >>> 16) & 0xff, (arg >>> 8) & 0xff, arg & 0xff);
+  } else {
+    // Only reachable for absurd lengths; included for totality.
+    const hi = Math.floor(arg / 0x100000000);
+    const lo = arg >>> 0;
+    sink.push(
+      mt | 27,
+      (hi >>> 24) & 0xff,
+      (hi >>> 16) & 0xff,
+      (hi >>> 8) & 0xff,
+      hi & 0xff,
+      (lo >>> 24) & 0xff,
+      (lo >>> 16) & 0xff,
+      (lo >>> 8) & 0xff,
+      lo & 0xff,
+    );
+  }
+}
+
+const fbuf = new DataView(new ArrayBuffer(8));
+
+// Returns the IEEE-754 binary16 bit pattern for n if (and only if) f16 represents n exactly,
+// else null. n must be finite and exactly representable as f32 (caller guarantees both).
+function tryF16Bits(n: number): number | null {
+  fbuf.setFloat32(0, n);
+  const bits = fbuf.getUint32(0);
+  const sign = ((bits >>> 31) & 1) << 15;
+  const exp = (bits >>> 23) & 0xff;
+  const mant = bits & 0x7fffff;
+  if (exp === 0 && mant === 0) return sign; // zero (-0 already normalized away by caller)
+  const e = exp - 127; // unbiased exponent (f32 subnormals land at -127 and fall through)
+  if (e >= -14 && e <= 15) {
+    // f16 normal range: the 23-bit mantissa must fit in 10 bits.
+    if ((mant & 0x1fff) !== 0) return null;
+    return sign | ((e + 15) << 10) | (mant >>> 13);
+  }
+  if (e >= -24 && e <= -15) {
+    // f16 subnormal range: value must be an exact multiple of 2^-24.
+    const shift = -(e + 1); // 14..23
+    const sig = 0x800000 | mant; // full 24-bit significand
+    if ((sig & ((1 << shift) - 1)) !== 0) return null;
+    return sign | (sig >>> shift);
+  }
+  return null;
+}
+
+// ERRATA D1: numbers encode as float only, in the shortest of f16/f32/f64 that represents the
+// value exactly (RFC 8949 §4.2.1). -0.0 is normalized to +0.0.
+function writeFloat(sink: ByteSink, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new Error(`non-finite number is not representable: ${value}`);
+  }
+  const n = value + 0; // normalize -0 to +0
+  if (Math.fround(n) === n) {
+    const h = tryF16Bits(n);
+    if (h !== null) {
+      sink.push(0xf9, (h >>> 8) & 0xff, h & 0xff);
+      return;
+    }
+    fbuf.setFloat32(0, n);
+    sink.push(0xfa, fbuf.getUint8(0), fbuf.getUint8(1), fbuf.getUint8(2), fbuf.getUint8(3));
+  } else {
+    fbuf.setFloat64(0, n);
+    sink.push(
+      0xfb,
+      fbuf.getUint8(0),
+      fbuf.getUint8(1),
+      fbuf.getUint8(2),
+      fbuf.getUint8(3),
+      fbuf.getUint8(4),
+      fbuf.getUint8(5),
+      fbuf.getUint8(6),
+      fbuf.getUint8(7),
+    );
+  }
+}
+
+function cmpBytes(a: Uint8Array, b: Uint8Array): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const d = a[i]! - b[i]!;
+    if (d !== 0) return d;
+  }
+  return a.length - b.length;
+}
+
+const utf8 = new TextEncoder();
+
+function encodeInto(sink: ByteSink, val: CborValue): void {
+  switch (val.t) {
+    case "tstr": {
+      const bytes = utf8.encode(val.v.normalize("NFC"));
+      writeHead(sink, 3, bytes.length);
+      sink.pushBytes(bytes);
+      return;
+    }
+    case "bool":
+      sink.push(val.v ? 0xf5 : 0xf4);
+      return;
+    case "float":
+      writeFloat(sink, val.v);
+      return;
+    case "array":
+      writeHead(sink, 4, val.v.length);
+      for (const item of val.v) encodeInto(sink, item);
+      return;
+    case "map": {
+      // ERRATA D4: sort entries by bytewise lex order of the encoded key.
+      const entries = val.v.map(([k, v]) => {
+        const ks = new ByteSink();
+        encodeInto(ks, tstr(k));
+        return { key: ks.toUint8Array(), value: v };
+      });
+      entries.sort((a, b) => cmpBytes(a.key, b.key));
+      for (let i = 1; i < entries.length; i++) {
+        if (cmpBytes(entries[i - 1]!.key, entries[i]!.key) === 0) {
+          throw new Error("duplicate map key in canonical CBOR");
+        }
+      }
+      writeHead(sink, 5, entries.length);
+      for (const e of entries) {
+        sink.pushBytes(e.key);
+        encodeInto(sink, e.value);
+      }
+      return;
+    }
+  }
+}
+
+export function encode(val: CborValue): Uint8Array {
+  const sink = new ByteSink();
+  encodeInto(sink, val);
+  return sink.toUint8Array();
+}
+
+// --- strict decoder for the Rhizomatic profile ----------------------------------------------------
+// Accepts exactly the items the profile emits: definite text strings, f16/f32/f64 floats, bools,
+// definite arrays, definite maps with text keys. Everything else (ints, byte strings, tags,
+// indefinite lengths, null/undefined) is rejected. Canonicality is checked by re-encoding where a
+// caller needs it; this decoder checks structure only.
+
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+class ByteReader {
+  private pos = 0;
+  constructor(private readonly bytes: Uint8Array) {}
+  u8(): number {
+    if (this.pos >= this.bytes.length) throw new Error("cbor: unexpected end of input");
+    return this.bytes[this.pos++]!;
+  }
+  take(n: number): Uint8Array {
+    if (this.pos + n > this.bytes.length) throw new Error("cbor: unexpected end of input");
+    const out = this.bytes.subarray(this.pos, this.pos + n);
+    this.pos += n;
+    return out;
+  }
+  done(): boolean {
+    return this.pos === this.bytes.length;
+  }
+}
+
+function readLength(r: ByteReader, info: number): number {
+  if (info < 24) return info;
+  if (info === 24) return r.u8();
+  if (info === 25) return (r.u8() << 8) | r.u8();
+  if (info === 26) return ((r.u8() << 24) | (r.u8() << 16) | (r.u8() << 8) | r.u8()) >>> 0;
+  throw new Error(`cbor: unsupported length encoding (info ${info})`);
+}
+
+function f16BitsToNumber(bits: number): number {
+  const sign = bits & 0x8000 ? -1 : 1;
+  const exp = (bits >> 10) & 0x1f;
+  const mant = bits & 0x3ff;
+  if (exp === 0) return sign * mant * 2 ** -24;
+  if (exp === 31) throw new Error("cbor: non-finite f16 is not representable");
+  return sign * (1 + mant / 1024) * 2 ** (exp - 15);
+}
+
+function decodeItem(r: ByteReader): CborValue {
+  const head = r.u8();
+  const major = head >> 5;
+  const info = head & 0x1f;
+  switch (major) {
+    case 3: {
+      const len = readLength(r, info);
+      return tstr(utf8Decoder.decode(r.take(len)));
+    }
+    case 4: {
+      const len = readLength(r, info);
+      const items: CborValue[] = [];
+      for (let i = 0; i < len; i++) items.push(decodeItem(r));
+      return array(items);
+    }
+    case 5: {
+      const len = readLength(r, info);
+      const entries: Array<[string, CborValue]> = [];
+      for (let i = 0; i < len; i++) {
+        const key = decodeItem(r);
+        if (key.t !== "tstr") throw new Error("cbor: map keys must be text strings");
+        entries.push([key.v, decodeItem(r)]);
+      }
+      return map(entries);
+    }
+    case 7: {
+      if (info === 20) return bool(false);
+      if (info === 21) return bool(true);
+      if (info === 25) {
+        const b = r.take(2);
+        return float(f16BitsToNumber((b[0]! << 8) | b[1]!));
+      }
+      if (info === 26) {
+        const b = r.take(4);
+        const dv = new DataView(b.buffer, b.byteOffset, 4);
+        const n = dv.getFloat32(0);
+        if (!Number.isFinite(n)) throw new Error("cbor: non-finite float is not representable");
+        return float(n);
+      }
+      if (info === 27) {
+        const b = r.take(8);
+        const dv = new DataView(b.buffer, b.byteOffset, 8);
+        const n = dv.getFloat64(0);
+        if (!Number.isFinite(n)) throw new Error("cbor: non-finite float is not representable");
+        return float(n);
+      }
+      throw new Error(`cbor: unsupported simple/float (info ${info})`);
+    }
+    default:
+      throw new Error(`cbor: major type ${major} is outside the Rhizomatic profile`);
+  }
+}
+
+export function decode(bytes: Uint8Array): CborValue {
+  const r = new ByteReader(bytes);
+  const v = decodeItem(r);
+  if (!r.done()) throw new Error("cbor: trailing bytes after item");
+  return v;
+}

package/src/delta.ts

@@ -0,0 +1,89 @@
+import { type CborValue, array, bool, encode, float, map, tstr } from "./cbor.js";
+import { bytesToHex, contentAddress } from "./hash.js";
+import type { Claims, Pointer, Target } from "./types.js";
+
+function targetToCbor(t: Target): CborValue {
+  switch (t.kind) {
+    case "primitive": {
+      const v = t.value;
+      if (typeof v === "string") return tstr(v);
+      if (typeof v === "boolean") return bool(v);
+      return float(v);
+    }
+    case "entity": {
+      const entries: Array<[string, CborValue]> = [["id", tstr(t.entity.id)]];
+      if (t.entity.context !== undefined) entries.push(["context", tstr(t.entity.context)]);
+      return map(entries);
+    }
+    case "delta": {
+      const entries: Array<[string, CborValue]> = [["delta", tstr(t.deltaRef.delta)]];
+      if (t.deltaRef.context !== undefined) entries.push(["context", tstr(t.deltaRef.context)]);
+      return map(entries);
+    }
+  }
+}
+
+function pointerToCbor(p: Pointer): CborValue {
+  return map([
+    ["role", tstr(p.role)],
+    ["target", targetToCbor(p.target)],
+  ]);
+}
+
+export function claimsToCbor(claims: Claims): CborValue {
+  return map([
+    ["author", tstr(claims.author)],
+    ["pointers", array(claims.pointers.map(pointerToCbor))],
+    ["timestamp", float(claims.timestamp)],
+  ]);
+}
+
+function assertNfc(s: string, what: string): void {
+  if (s.normalize("NFC") !== s) {
+    throw new Error(`${what} must be NFC-normalized (ERRATA D11): ${JSON.stringify(s)}`);
+  }
+}
+
+// Reject malformed claims at the boundary; never repair (SPEC-4 §2).
+export function assertValidClaims(claims: Claims): void {
+  if (claims.author.length === 0) throw new Error("author must be non-empty");
+  assertNfc(claims.author, "author");
+  if (!Number.isFinite(claims.timestamp)) throw new Error("timestamp must be finite");
+  if (claims.pointers.length < 1) throw new Error("a delta MUST contain at least one pointer");
+  for (const p of claims.pointers) {
+    if (p.role.length === 0) throw new Error("role must be non-empty");
+    assertNfc(p.role, "role");
+    if (p.target.kind === "primitive") {
+      const v = p.target.value;
+      if (typeof v === "number" && !Number.isFinite(v)) {
+        throw new Error("numeric primitive must be finite");
+      }
+      if (typeof v === "string") assertNfc(v, "string primitive");
+    }
+    if (p.target.kind === "entity") assertNfc(p.target.entity.id, "entity id");
+    if (p.target.kind === "delta") assertNfc(p.target.deltaRef.delta, "delta ref");
+    const ctx =
+      p.target.kind === "entity"
+        ? p.target.entity.context
+        : p.target.kind === "delta"
+          ? p.target.deltaRef.context
+          : undefined;
+    if (ctx !== undefined) {
+      if (ctx.length === 0) throw new Error("context, when present, must be non-empty");
+      assertNfc(ctx, "context");
+    }
+  }
+}
+
+export function canonicalBytes(claims: Claims): Uint8Array {
+  assertValidClaims(claims);
+  return encode(claimsToCbor(claims));
+}
+
+export function canonicalHex(claims: Claims): string {
+  return bytesToHex(canonicalBytes(claims));
+}
+
+export function computeId(claims: Claims): string {
+  return contentAddress(canonicalBytes(claims));
+}

package/src/derivation.ts

@@ -0,0 +1,229 @@
+// The derivation layer (SPEC-7, ERRATA-7): everything that computes is an author. Derived
+// authors read materializations and write signed claims back through the ordinary ingest path.
+
+import { computeId } from "./delta.js";
+import type { HView } from "./hview.js";
+import { Reactor, type IngestResult, type MaterializationChange } from "./reactor.js";
+import { VOCAB_PREFIX } from "./schema-deltas.js";
+import { makeNegationClaims } from "./set.js";
+import { authorForSeed, signClaims, verifyDelta } from "./sign.js";
+import type { Claims, Delta, Pointer } from "./types.js";
+
+// A v0 derived function: substantive pointer lists, one per claim to emit (G1).
+export type DerivedFn = (view: HView, root: string) => Pointer[][];
+
+export interface BindingSpec {
+  readonly name: string; // binding entity id
+  readonly fnId: string; // fn entity id (declared identity; WASM hash later, G1)
+  readonly materialization: string;
+  readonly pure: boolean;
+  readonly budget: number; // lifetime emission-trigger cap (G2)
+  readonly emit: "append" | "supersede" | { readonly keyed: readonly string[] };
+}
+
+interface Installed {
+  readonly spec: BindingSpec;
+  readonly fn: DerivedFn;
+  readonly seedHex: string;
+  readonly author: string;
+  // Live (un-superseded) emission ids, bucketed by subject key (G4). append/supersede use the
+  // single bucket ""; keyed buckets by emissionKey.
+  liveEmissions: Map<string, string[]>;
+  triggerCount: number;
+  suspended: boolean;
+}
+
+// The subject key of an emission under keyed(contextSet): sorted (entity id, context) pairs of
+// the substantive entity pointers whose context is in the set; "" when none match (G4).
+function emissionKey(substantive: readonly Pointer[], contexts: readonly string[]): string {
+  const pairs: string[] = [];
+  for (const p of substantive) {
+    if (p.target.kind !== "entity") continue;
+    const ctx = p.target.entity.context;
+    if (ctx !== undefined && contexts.includes(ctx)) {
+      pairs.push(`${p.target.entity.id}
${ctx}`);
+    }
+  }
+  return pairs.sort().join("");
+}
+
+function provenancePointers(spec: BindingSpec, inputHex: string): Pointer[] {
+  return [
+    {
+      role: `${VOCAB_PREFIX}.derived.by`,
+      target: { kind: "entity", entity: { id: spec.fnId } },
+    },
+    { role: `${VOCAB_PREFIX}.derived.from`, target: { kind: "primitive", value: inputHex } },
+    {
+      role: `${VOCAB_PREFIX}.derived.under`,
+      target: { kind: "entity", entity: { id: spec.name } },
+    },
+  ];
+}
+
+// Build the full claims for one emission — the exact recipe replay verification re-runs (G5).
+export function derivedClaims(
+  spec: BindingSpec,
+  author: string,
+  substantive: readonly Pointer[],
+  inputHex: string,
+): Claims {
+  // timestamp 0: pure output must be a function of (fn, input hash) only (G3).
+  return {
+    timestamp: 0,
+    author,
+    pointers: [...substantive, ...provenancePointers(spec, inputHex)],
+  };
+}
+
+export class DerivationHost {
+  private readonly bindings = new Map<string, Installed>();
+
+  constructor(readonly reactor: Reactor) {}
+
+  // Installation is an assertion: a signed rdb.derived.binds delta (SPEC-7 §3).
+  install(spec: BindingSpec, fn: DerivedFn, seedHex: string): string {
+    if (this.bindings.has(spec.name)) throw new Error(`duplicate binding: ${spec.name}`);
+    const author = authorForSeed(seedHex);
+    const binds = signClaims(
+      {
+        timestamp: 0,
+        author,
+        pointers: [
+          {
+            role: `${VOCAB_PREFIX}.derived.binds`,
+            target: { kind: "entity", entity: { id: spec.fnId, context: "bindings" } },
+          },
+          { role: `${VOCAB_PREFIX}.derived.author`, target: { kind: "primitive", value: author } },
+        ],
+      },
+      seedHex,
+    );
+    this.reactor.ingest(binds);
+    this.bindings.set(spec.name, {
+      spec,
+      fn,
+      seedHex,
+      author,
+      liveEmissions: new Map(),
+      triggerCount: 0,
+      suspended: false,
+    });
+    return author;
+  }
+
+  isSuspended(name: string): boolean {
+    return this.bindings.get(name)?.suspended ?? false;
+  }
+
+  authorOf(name: string): string | undefined {
+    return this.bindings.get(name)?.author;
+  }
+
+  // The write-back loop (G2): ingest, then drain triggers until quiescent.
+  ingest(delta: Delta): IngestResult {
+    const result = this.reactor.ingest(delta);
+    if (result.status !== "accepted") return result;
+    this.drain([...this.reactor.changesFromLastIngest()]);
+    return result;
+  }
+
+  private drain(pending: MaterializationChange[]): void {
+    let depth = 0;
+    while (pending.length > 0 && depth < 32) {
+      depth += 1;
+      const next: MaterializationChange[] = [];
+      for (const change of pending) {
+        for (const b of this.bindings.values()) {
+          if (b.spec.materialization !== change.materialization) continue;
+          next.push(...this.trigger(b, change));
+        }
+      }
+      pending = next;
+    }
+  }
+
+  private emitSigned(b: Installed, claims: Claims): MaterializationChange[] {
+    const signed = signClaims(claims, b.seedHex);
+    const result = this.reactor.ingest(signed);
+    if (result.status === "rejected") throw new Error("derived emission rejected");
+    return result.status === "accepted" ? [...this.reactor.changesFromLastIngest()] : [];
+  }
+
+  private trigger(b: Installed, change: MaterializationChange): MaterializationChange[] {
+    if (b.suspended) return [];
+    // The default non-reentrancy guard (SPEC-7 §6): skip when the trigger is entirely our own.
+    const own = change.responsibleDeltaIds.every(
+      (id) => this.reactor.get(id)?.claims.author === b.author,
+    );
+    if (own) return [];
+    if (b.triggerCount >= b.spec.budget) {
+      b.suspended = true;
+      // Divergence becomes an observable event, not a melted reactor (G2).
+      return this.emitSigned(b, {
+        timestamp: 0,
+        author: b.author,
+        pointers: [
+          {
+            role: `${VOCAB_PREFIX}.derived.suspended`,
+            target: { kind: "entity", entity: { id: b.spec.name, context: "suspensions" } },
+          },
+        ],
+      });
+    }
+    b.triggerCount += 1;
+    const view = this.reactor.materializedView(change.materialization, change.root);
+    if (view === undefined) return [];
+    const out: MaterializationChange[] = [];
+    if (b.spec.emit === "supersede") {
+      // Wholesale supersession: negate every live emission before emitting anew (G4).
+      for (const prior of [...b.liveEmissions.values()].flat()) {
+        out.push(...this.emitSigned(b, makeNegationClaims(b.author, 0, prior)));
+      }
+      b.liveEmissions.clear();
+    }
+    const keyed = typeof b.spec.emit === "object" ? b.spec.emit.keyed : undefined;
+    for (const substantive of b.fn(view, change.root)) {
+      const claims = derivedClaims(b.spec, b.author, substantive, change.newHex);
+      const signed = signClaims(claims, b.seedHex);
+      const key = keyed === undefined ? "" : emissionKey(substantive, keyed);
+      // Per-subject supersession: negate only the same-key priors; an empty key appends (G4).
+      if (keyed !== undefined && key !== "") {
+        for (const prior of b.liveEmissions.get(key) ?? []) {
+          out.push(...this.emitSigned(b, makeNegationClaims(b.author, 0, prior)));
+        }
+        b.liveEmissions.set(key, []);
+      }
+      const result = this.reactor.ingest(signed);
+      if (result.status === "accepted") {
+        const bucket = b.liveEmissions.get(key);
+        if (bucket === undefined) b.liveEmissions.set(key, [signed.id]);
+        else bucket.push(signed.id);
+        out.push(...this.reactor.changesFromLastIngest());
+      }
+    }
+    return out;
+  }
+}
+
+// Pure-replay verification (SPEC-7 §4, G5): recompute the emission from (fn, input view) and
+// compare content addresses; the signature must also verify.
+export function verifyPureDerivation(
+  emitted: Delta,
+  spec: BindingSpec,
+  fn: DerivedFn,
+  view: HView,
+  root: string,
+  viewHex: string,
+): boolean {
+  if (verifyDelta(emitted) !== "verified") return false;
+  const fromPtr = emitted.claims.pointers.find(
+    (p) => p.role === `${VOCAB_PREFIX}.derived.from` && p.target.kind === "primitive",
+  );
+  if (fromPtr?.target.kind !== "primitive" || fromPtr.target.value !== viewHex) return false;
+  // Re-derive ids: the replayed claims must content-address to the emitted delta's id.
+  const ids = fn(view, root).map((substantive) =>
+    computeId(derivedClaims(spec, emitted.claims.author, substantive, viewHex)),
+  );
+  return ids.includes(emitted.id);
+}