@rhizomes/rhizomatic 0.1.0

package/src/index.ts

@@ -0,0 +1,83 @@
+export type { Primitive, EntityRef, DeltaRef, Target, Pointer, Claims, Delta } from "./types.js";
+export { encode, type CborValue, tstr, float, bool, array, map } from "./cbor.js";
+export { contentAddress } from "./hash.js";
+export {
+  claimsToCbor,
+  canonicalBytes,
+  canonicalHex,
+  computeId,
+  assertValidClaims,
+} from "./delta.js";
+export { claimsToJson, parseClaims } from "./json-profile.js";
+export {
+  AUTHOR_PREFIX,
+  authorForSeed,
+  publicKeyFromSeed,
+  signClaims,
+  verifyDelta,
+  type Verification,
+} from "./sign.js";
+export { DeltaSet, federate, fork, makeDelta, makeNegationClaims, merge } from "./set.js";
+export {
+  comparePrimitives,
+  evalPred,
+  strMatch,
+  type Cmp,
+  type PPred,
+  type Pred,
+  type StrMatch,
+  type ValMatch,
+} from "./pred.js";
+export {
+  aliasClosure,
+  evalTerm,
+  expandAliased,
+  resultCanonicalHex,
+  type AliasedSpec,
+  type EvalResult,
+  type GroupKey,
+  type MaskPolicy,
+  type Term,
+} from "./eval.js";
+export { relationSignature, relationSignatureCanonicalHex } from "./alias.js";
+export { hviewCanonicalHex, type HVEntry, type HView } from "./hview.js";
+export { SchemaRegistry, collectRefs, type HyperSchema } from "./schema.js";
+export {
+  resolveView,
+  viewCanonicalHex,
+  type MergeFn,
+  type Order,
+  type Policy,
+  type PropPolicy,
+  type View,
+} from "./policy.js";
+export { parsePolicy, parsePred, parseTerm } from "./term-json.js";
+export {
+  cborToJson,
+  jsonToCbor,
+  policyToJson,
+  predToJson,
+  termCanonicalHex,
+  termHash,
+  termToJson,
+} from "./term-io.js";
+export { SCHEMA_SCHEMA, VOCAB_PREFIX, loadSchema, publishSchemaClaims } from "./schema-deltas.js";
+export { decode } from "./cbor.js";
+export { packId, packSet, unpackSet } from "./pack.js";
+export { Peer, syncBoth, type SyncReport } from "./peer.js";
+export { offerFor, pullFromUrl, servePeer } from "./http.js";
+export {
+  DerivationHost,
+  derivedClaims,
+  verifyPureDerivation,
+  type BindingSpec,
+  type DerivedFn,
+} from "./derivation.js";
+export {
+  Reactor,
+  isRootAnchored,
+  makeManifestClaims,
+  manifestMemberIds,
+  type IngestResult,
+  type MaterializationChange,
+} from "./reactor.js";

package/src/json-profile.ts

@@ -0,0 +1,96 @@
+// Parse the JSON debug profile used by the vectors (SPEC-1 §4.1, ERRATA "JSON debug profile")
+// into the logical delta model. The CBOR form is normative; this is for authoring/inspection.
+
+import type { Claims, Pointer, Primitive, Target } from "./types.js";
+
+function asObject(x: unknown, what: string): Record<string, unknown> {
+  if (typeof x !== "object" || x === null || Array.isArray(x)) {
+    throw new Error(`expected object for ${what}`);
+  }
+  return x as Record<string, unknown>;
+}
+
+function parsePrimitive(v: unknown): Primitive {
+  if (typeof v === "string" || typeof v === "boolean") return v;
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new Error("numeric primitive must be finite");
+    return v;
+  }
+  throw new Error("primitive must be string | number | boolean");
+}
+
+// The profile mirrors the canonical CBOR exactly: a primitive target is the bare value; an
+// entity ref is {id, context?}; a delta ref is {delta, context?}. Discrimination is structural
+// (SPEC-1 §2.1) — primitives are never objects, and the id/delta key names the ref kind.
+function parseTarget(raw: unknown): Target {
+  if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+    return { kind: "primitive", value: parsePrimitive(raw) };
+  }
+  const o = asObject(raw, "target");
+  if ("id" in o) {
+    const id = o["id"];
+    if (typeof id !== "string") throw new Error("entity ref id must be a string");
+    const context = o["context"];
+    return context === undefined
+      ? { kind: "entity", entity: { id } }
+      : { kind: "entity", entity: { id, context: String(context) } };
+  }
+  if ("delta" in o) {
+    const delta = o["delta"];
+    if (typeof delta !== "string") throw new Error("delta ref delta must be a string");
+    const context = o["context"];
+    return context === undefined
+      ? { kind: "delta", deltaRef: { delta } }
+      : { kind: "delta", deltaRef: { delta, context: String(context) } };
+  }
+  throw new Error("target must be a primitive, {id, context?}, or {delta, context?}");
+}
+
+function parsePointer(raw: unknown): Pointer {
+  const o = asObject(raw, "pointer");
+  if (typeof o["role"] !== "string") throw new Error("pointer.role must be a string");
+  return { role: o["role"], target: parseTarget(o["target"]) };
+}
+
+// Serialize claims back to the JSON debug profile (the inverse of parseClaims).
+export function claimsToJson(claims: Claims): unknown {
+  return {
+    timestamp: claims.timestamp,
+    author: claims.author,
+    pointers: claims.pointers.map((p) => {
+      let target: unknown;
+      switch (p.target.kind) {
+        case "primitive":
+          target = p.target.value;
+          break;
+        case "entity":
+          target = {
+            id: p.target.entity.id,
+            ...(p.target.entity.context === undefined ? {} : { context: p.target.entity.context }),
+          };
+          break;
+        case "delta":
+          target = {
+            delta: p.target.deltaRef.delta,
+            ...(p.target.deltaRef.context === undefined
+              ? {}
+              : { context: p.target.deltaRef.context }),
+          };
+          break;
+      }
+      return { role: p.role, target };
+    }),
+  };
+}
+
+export function parseClaims(raw: unknown): Claims {
+  const o = asObject(raw, "claims");
+  if (typeof o["timestamp"] !== "number") throw new Error("claims.timestamp must be a number");
+  if (typeof o["author"] !== "string") throw new Error("claims.author must be a string");
+  if (!Array.isArray(o["pointers"])) throw new Error("claims.pointers must be an array");
+  return {
+    timestamp: o["timestamp"],
+    author: o["author"],
+    pointers: o["pointers"].map(parsePointer),
+  };
+}

package/src/pack.ts

@@ -0,0 +1,239 @@
+// The pack format (SPEC-8, ERRATA-8): a content-addressed physical container whose logical form
+// is invariant. Never hash the dehydrated form; rehydration is byte-exact by construction because
+// unpacking rebuilds claims through the standard makeDelta path.
+
+import { array, bool, decode, encode, float, map, tstr, type CborValue } from "./cbor.js";
+import { contentAddress } from "./hash.js";
+import { manifestMemberIds } from "./reactor.js";
+import { DeltaSet, makeDelta } from "./set.js";
+import type { Claims, Delta, Pointer, Target } from "./types.js";
+
+const PACK_VERSION = 1;
+
+// --- string interning -------------------------------------------------------------------------------
+
+function stringsOf(delta: Delta, out: Set<string>): void {
+  out.add(delta.id); // stored ids make rehydration self-verifying (SPEC-8 §4)
+  out.add(delta.claims.author);
+  if (delta.sig !== undefined) out.add(delta.sig);
+  for (const p of delta.claims.pointers) {
+    out.add(p.role);
+    switch (p.target.kind) {
+      case "entity":
+        out.add(p.target.entity.id);
+        if (p.target.entity.context !== undefined) out.add(p.target.entity.context);
+        break;
+      case "delta":
+        out.add(p.target.deltaRef.delta);
+        if (p.target.deltaRef.context !== undefined) out.add(p.target.deltaRef.context);
+        break;
+      case "primitive":
+        if (typeof p.target.value === "string") out.add(p.target.value);
+        break;
+    }
+  }
+}
+
+// --- packing ----------------------------------------------------------------------------------------
+
+function ptrToCbor(p: Pointer, idx: (s: string) => number): CborValue {
+  const entries: Array<[string, CborValue]> = [["r", float(idx(p.role))]];
+  let context: string | undefined;
+  switch (p.target.kind) {
+    case "entity":
+      entries.push(["e", float(idx(p.target.entity.id))]);
+      context = p.target.entity.context;
+      break;
+    case "delta":
+      entries.push(["d", float(idx(p.target.deltaRef.delta))]);
+      context = p.target.deltaRef.context;
+      break;
+    case "primitive": {
+      const v = p.target.value;
+      if (typeof v === "string") entries.push(["s", float(idx(v))]);
+      else if (typeof v === "number") entries.push(["n", float(v)]);
+      else entries.push(["b", bool(v)]);
+      break;
+    }
+  }
+  if (context !== undefined) entries.push(["c", float(idx(context))]);
+  return map(entries);
+}
+
+function hydratedRecord(d: Delta, idx: (s: string) => number): CborValue {
+  const entries: Array<[string, CborValue]> = [
+    ["i", float(idx(d.id))],
+    ["a", float(idx(d.claims.author))],
+    ["t", float(d.claims.timestamp)],
+    ["p", array(d.claims.pointers.map((p) => ptrToCbor(p, idx)))],
+  ];
+  if (d.sig !== undefined) entries.push(["s", float(idx(d.sig))]);
+  return map(entries);
+}
+
+function memberRecord(
+  d: Delta,
+  manifest: Delta,
+  envelopeIdx: number,
+  idx: (s: string) => number,
+): CborValue {
+  const entries: Array<[string, CborValue]> = [
+    ["i", float(idx(d.id))],
+    ["m", float(envelopeIdx)],
+    ["p", array(d.claims.pointers.map((p) => ptrToCbor(p, idx)))],
+  ];
+  // Dehydrate against the envelope (SPEC-8 §3.1); divergent fields stored explicitly (P2).
+  if (d.claims.author !== manifest.claims.author) entries.push(["a", float(idx(d.claims.author))]);
+  const dt = d.claims.timestamp - manifest.claims.timestamp;
+  if (dt !== 0) entries.push(["dt", float(dt)]);
+  if (d.sig !== undefined) entries.push(["s", float(idx(d.sig))]);
+  return map(entries);
+}
+
+export function packSet(set: DeltaSet): Uint8Array {
+  const deltas = [...set].sort((a, b) => (a.id < b.id ? -1 : 1));
+  // Manifests: deltas carrying rdb.txn.member pointers, sorted by id.
+  const manifests = deltas.filter((d) => manifestMemberIds(d).length > 0);
+  // Each member is dehydrated against the lexicographically FIRST claiming manifest (P1).
+  const memberToManifest = new Map<string, number>();
+  manifests.forEach((m, i) => {
+    for (const id of manifestMemberIds(m)) {
+      if (set.has(id) && !memberToManifest.has(id)) memberToManifest.set(id, i);
+    }
+  });
+  const manifestIds = new Set(manifests.map((m) => m.id));
+  const members = deltas.filter((d) => memberToManifest.has(d.id) && !manifestIds.has(d.id));
+  const loose = deltas.filter((d) => !memberToManifest.has(d.id) && !manifestIds.has(d.id));
+
+  const stringSet = new Set<string>();
+  for (const d of deltas) stringsOf(d, stringSet);
+  const strings = [...stringSet].sort();
+  const indexOf = new Map(strings.map((s, i) => [s, i]));
+  const idx = (s: string): number => indexOf.get(s)!;
+
+  const packed = map([
+    ["version", float(PACK_VERSION)],
+    ["strings", array(strings.map(tstr))],
+    ["envelopes", array(manifests.map((m) => hydratedRecord(m, idx)))],
+    [
+      "members",
+      array(
+        members.map((d) =>
+          memberRecord(
+            d,
+            manifests[memberToManifest.get(d.id)!]!,
+            memberToManifest.get(d.id)!,
+            idx,
+          ),
+        ),
+      ),
+    ],
+    ["loose", array(loose.map((d) => hydratedRecord(d, idx)))],
+  ]);
+  return encode(packed);
+}
+
+export function packId(bytes: Uint8Array): string {
+  return contentAddress(bytes);
+}
+
+// --- unpacking --------------------------------------------------------------------------------------
+
+type Obj = Map<string, CborValue>;
+
+function asMap(v: CborValue, what: string): Obj {
+  if (v.t !== "map") throw new Error(`pack: expected map for ${what}`);
+  return new Map(v.v);
+}
+
+function asArray(v: CborValue | undefined, what: string): readonly CborValue[] {
+  if (v === undefined || v.t !== "array") throw new Error(`pack: expected array for ${what}`);
+  return v.v;
+}
+
+function asNum(v: CborValue | undefined, what: string): number {
+  if (v === undefined || v.t !== "float") throw new Error(`pack: expected number for ${what}`);
+  return v.v;
+}
+
+function ptrFromCbor(v: CborValue, strings: readonly string[]): Pointer {
+  const o = asMap(v, "pointer");
+  const str = (key: string): string => strings[asNum(o.get(key), key)]!;
+  const role = str("r");
+  const context = o.has("c") ? str("c") : undefined;
+  let target: Target;
+  if (o.has("e")) {
+    target = {
+      kind: "entity",
+      entity: context === undefined ? { id: str("e") } : { id: str("e"), context },
+    };
+  } else if (o.has("d")) {
+    target = {
+      kind: "delta",
+      deltaRef: context === undefined ? { delta: str("d") } : { delta: str("d"), context },
+    };
+  } else if (o.has("s")) {
+    target = { kind: "primitive", value: str("s") };
+  } else if (o.has("n")) {
+    target = { kind: "primitive", value: asNum(o.get("n"), "n") };
+  } else if (o.has("b")) {
+    const b = o.get("b")!;
+    if (b.t !== "bool") throw new Error("pack: expected bool for b");
+    target = { kind: "primitive", value: b.v };
+  } else {
+    throw new Error("pack: pointer record has no target");
+  }
+  return { role, target };
+}
+
+function hydrateRecord(v: CborValue, strings: readonly string[]): Delta {
+  const o = asMap(v, "record");
+  const claims: Claims = {
+    author: strings[asNum(o.get("a"), "a")]!,
+    timestamp: asNum(o.get("t"), "t"),
+    pointers: asArray(o.get("p"), "p").map((p) => ptrFromCbor(p, strings)),
+  };
+  const sig = o.has("s") ? strings[asNum(o.get("s"), "s")]! : undefined;
+  return verifiedDelta(claims, sig, strings[asNum(o.get("i"), "i")]!);
+}
+
+// SPEC-8 §4: hydrate -> canonical CBOR -> multihash MUST equal the stored id. Free fsck.
+function verifiedDelta(claims: Claims, sig: string | undefined, storedId: string): Delta {
+  const d = makeDelta(claims, sig);
+  if (d.id !== storedId) {
+    throw new Error(`pack: rehydrated delta ${d.id} does not match stored id ${storedId}`);
+  }
+  return d;
+}
+
+export function unpackSet(bytes: Uint8Array): DeltaSet {
+  const top = asMap(decode(bytes), "pack");
+  if (asNum(top.get("version"), "version") !== PACK_VERSION) {
+    throw new Error("pack: unsupported version");
+  }
+  const strings = asArray(top.get("strings"), "strings").map((s) => {
+    if (s.t !== "tstr") throw new Error("pack: string table entries must be text");
+    return s.v;
+  });
+  const out = new DeltaSet();
+  const envelopes = asArray(top.get("envelopes"), "envelopes").map((e) =>
+    hydrateRecord(e, strings),
+  );
+  for (const m of envelopes) out.add(m);
+  for (const rec of asArray(top.get("members"), "members")) {
+    const o = asMap(rec, "member");
+    const manifest = envelopes[asNum(o.get("m"), "m")];
+    if (manifest === undefined) throw new Error("pack: member references missing envelope");
+    const author = o.has("a") ? strings[asNum(o.get("a"), "a")]! : manifest.claims.author;
+    const timestamp = manifest.claims.timestamp + (o.has("dt") ? asNum(o.get("dt"), "dt") : 0);
+    const claims: Claims = {
+      author,
+      timestamp,
+      pointers: asArray(o.get("p"), "p").map((p) => ptrFromCbor(p, strings)),
+    };
+    const sig = o.has("s") ? strings[asNum(o.get("s"), "s")]! : undefined;
+    out.add(verifiedDelta(claims, sig, strings[asNum(o.get("i"), "i")]!));
+  }
+  for (const rec of asArray(top.get("loose"), "loose")) out.add(hydrateRecord(rec, strings));
+  return out;
+}

package/src/peer.ts

@@ -0,0 +1,126 @@
+// Federation (SPEC-6, ERRATA-6): a peer is a reactor + keypair + offered lens + admission
+// predicate. Merge is union; this layer is selection and trust. Coordination without conscription.
+
+import { evalTerm, type Term } from "./eval.js";
+import { evalPred, type Pred } from "./pred.js";
+import { Reactor, manifestMemberIds, type IngestResult } from "./reactor.js";
+import { authorForSeed, signClaims, verifyDelta } from "./sign.js";
+import type { Claims, Delta } from "./types.js";
+
+export interface SyncReport {
+  readonly offered: number;
+  readonly bundles: number;
+  readonly loose: number;
+  readonly withheld: number; // unsigned, uncovered: they stay local (F3)
+  readonly accepted: number;
+  readonly rejected: number;
+}
+
+const ALL: Term = { kind: "input" };
+
+export class Peer {
+  readonly reactor = new Reactor();
+  readonly author: string;
+
+  constructor(
+    private readonly seedHex: string,
+    // What this peer offers to others (F4). Default: everything.
+    public offeredLens: Term = ALL,
+    // What this peer accepts (SPEC-6 §5 step 3). Default: everything that verifies.
+    public admission: Pred | undefined = undefined,
+  ) {
+    this.author = authorForSeed(seedHex);
+  }
+
+  // Author a claim as this peer: sign and ingest (read-your-writes).
+  authorClaims(claims: Omit<Claims, "author">): Delta {
+    const signed = signClaims({ ...claims, author: this.author }, this.seedHex);
+    const result = this.reactor.ingest(signed);
+    if (result.status === "rejected") throw new Error(`own claim rejected: ${result.reason}`);
+    return signed;
+  }
+
+  // The admission judgment (SPEC-6 §5 step 3), exposed for transport bindings (F5).
+  admits(d: Delta): boolean {
+    return this.admission === undefined || evalPred(this.admission, d);
+  }
+
+  // The offered set: eval(lens, log) — lens fidelity is a tested invariant (F4).
+  offeredSet(): Delta[] {
+    const result = evalTerm(this.offeredLens, this.reactor.snapshot());
+    if (result.sort !== "dset") throw new Error("a lens must be a DSet-sort term (F4)");
+    return [...result.set];
+  }
+
+  // Pull from another peer: WANT(my ids) -> OFFER/BUNDLE -> verify -> admission -> ingest (§5).
+  pullFrom(other: Peer): SyncReport {
+    const have = new Set<string>();
+    for (const d of this.reactor.arrivalLog()) have.add(d.id);
+
+    const offered = other.offeredSet().filter((d) => !have.has(d.id));
+    const offeredIds = new Set(offered.map((d) => d.id));
+
+    // Partition per the signature boundary (F3): signed manifests carry their present members
+    // as bundles; remaining signed deltas travel loose; unsigned uncovered are withheld.
+    const isSignedManifest = (d: Delta) =>
+      d.sig !== undefined && verifyDelta(d) === "verified" && manifestMemberIds(d).length > 0;
+    const bundles: Array<{ manifest: Delta; members: Delta[] }> = [];
+    const covered = new Set<string>();
+    for (const m of offered.filter(isSignedManifest)) {
+      const members = manifestMemberIds(m)
+        .filter((id) => offeredIds.has(id))
+        .map((id) => offered.find((d) => d.id === id)!)
+        .filter((d) => !isSignedManifest(d));
+      bundles.push({ manifest: m, members });
+      for (const mem of members) covered.add(mem.id);
+      covered.add(m.id);
+    }
+    const loose = offered.filter(
+      (d) => !covered.has(d.id) && d.sig !== undefined && verifyDelta(d) === "verified",
+    );
+    const withheld = offered.length - covered.size - loose.length;
+
+    let accepted = 0;
+    let rejected = 0;
+    const admit = (d: Delta): boolean => this.admits(d);
+    const count = (r: IngestResult) => {
+      if (r.status === "accepted") accepted += 1;
+      else if (r.status === "rejected") rejected += 1;
+    };
+
+    for (const { manifest, members } of bundles) {
+      // Admission applies to the act: if the manifest or any member fails, decline the bundle.
+      if (![manifest, ...members].every(admit)) {
+        rejected += 1 + members.length;
+        continue;
+      }
+      count(this.reactor.ingestBundle(manifest, members));
+    }
+    for (const d of loose) {
+      if (!admit(d)) {
+        rejected += 1;
+        continue;
+      }
+      count(this.reactor.ingest(d));
+    }
+
+    return {
+      offered: offered.length,
+      bundles: bundles.length,
+      loose: loose.length,
+      withheld,
+      accepted,
+      rejected,
+    };
+  }
+}
+
+// Anti-entropy both ways; repeat until quiescent (bounded — union is monotone).
+export function syncBoth(a: Peer, b: Peer): void {
+  for (let i = 0; i < 4; i++) {
+    const before = a.reactor.digest() + b.reactor.digest();
+    a.pullFrom(b);
+    b.pullFrom(a);
+    if (a.reactor.digest() + b.reactor.digest() === before) return;
+  }
+}