quilt-jev-toolkit

Small toolkit for using JEV (TypeSafe) as a Quilt canon oracle — and, since wave 63, home of the Cell-Organ Snapshot & Boot protocol: use a receipt-chain ledger to rewind, snapshot, and boot saved states of cells, groups of cells (organs), or entire quilts, as drop-ins that nest inside another program or quilt. v0 = custody (snapshot/boot/nest); v1 = the rewind family + write-side transactions (below); v2 = checkpoint signatures + partial-custody replay seeds (--from-checkpoint, bottom); v3 = Ed25519 attribution — the checkpoint signer has a name (signCheckpointEd25519, key rotation, bottom); §9 = the chrono-op adapter — a sealed quilt-chrono sheet boots as an organ (bootChrono, bottom).

JEV is a hosted oracle that answers yes/no, multiple choice, and scored questions about content. It's deterministic (variance < 0.01 across runs), fast (~66ms/call), and robust to adversarial inputs.

This toolkit wraps JEV with a small noul / choice / score builder API and adds utilities for canon-gating Quilt content.

An organ is a group of cells plus its full receipt-chain history, packaged as a bundle { manifest, state, receipts }. A snapshot is a custody claim: content-addressed (sha256 of canonical state + every receipt hash). Boot is the courtroom: the claim is either proven by replay or refused. Full doctrine: docs/REVERSE-ACTUALIZED-SPEC.md.

# 0. run the proof suite (23 tests) and the end-to-end demo
npm test                      # node --test test/organ.test.mjs
npm run demo                  # snapshot → corrupt → fail-closed → boot → nest → re-snapshot

# 1. SNAPSHOT — quilt cells + ledger → verified bundle (content-addressed)
node -e '
import("./src/organ/snapshot.mjs").then(async ({ snapshot }) => {
  const { buildGreeterQuilt } = await import("./examples/greeter-organ.mjs");
  const q = buildGreeterQuilt();                      // 4 cells, 12 receipts
  const bundle = snapshot(q.cells, q.ledger, { name: "greeter-organ" });
  console.log(bundle.manifest.organId, bundle.manifest.manifestHash.slice(0, 16));
});'

# 2. BOOT (standalone) — verify chain-of-custody + replay == state, or fail closed
node -e '
import("./src/organ/boot.mjs").then(async ({ boot }) => {
  const { buildGreeterQuilt } = await import("./examples/greeter-organ.mjs");
  const { snapshot } = await import("./src/organ/snapshot.mjs");
  const q = buildGreeterQuilt();
  const organ = boot(snapshot(q.cells, q.ledger, { name: "greeter-organ" }));
  console.log(organ.cells.out.value);                 // "Ahoy, SuperInstance!"
});'

# 3. BOOT INTO A HOST QUILT — nesting envelope, cross-quilt receipts
#    boot(bundle, { host }) → organ.nest receipt in host ledger
#    organ.append(op)       → organ DEBIT + host CREDIT (double entry)

# 4. CONTINUE — append ops to a nested organ; every debit is credited host-side
#    organ.append({ type: "set", cellId: "subject", value: "organ" })
#    verifyDoubleEntry(host, organ) → { ok, creditsChecked }

# 5. RE-SNAPSHOT — the organ is portable again, identity intact
#    snapshotOrgan(organ) → bundle (same organId, full chain, supersedes pinned)
#    boot(that, { host: freshQuilt }) → wakes in a third quilt, hash-equal state

(1–2 are runnable one-liners; 3–5 are three lines each, shown as the demo runs them in examples/boot-demo.mjs.)

• I1 content addressing — manifest + state + receipts are canonical-JSON, sha256-addressed; identical bytes = identical manifestHash; cell order is sorted so the hash is a pure function of content.
• I2 chain of custody — every receipt hash re-verifies on boot, from GENESIS or from a pinned trustedCheckpoint {seq, hash}. A range starting at seq > 0 with no checkpoint is unowned history → refuse.
• I3 deterministic replay — boot == replay: state is rebuilt by replaying the receipt range on empty cells and asserted hash-equal to the carried state. Receipts carry no wall-clock time; seq is time.
• I4 the manifest is the custody claim — quilt.organ.manifest/v1: cells(+hashes), edges, receiptRange, genesis anchor, state address, supersedes, self-hash.
• I5 nesting without host breakage — the organ keeps ITS OWN ledger across quilt boundaries; the host only receives pointer receipts (organ.nest, organ.credit), so host invariants are structurally safe and the host ledger still replays deterministically.

Boot throws OrganBootError (never partially boots) on: SCHEMA_DRIFT, MANIFEST_INVALID, STATE_HASH_MISMATCH, RECEIPT_HASH_MISMATCH, CHAIN_GAP, CUSTODY_GAP, CUSTODY_CHECKPOINT_MISMATCH, REPLAY_DIVERGENCE, REPLAY_INVALID_OP. Nesting throws NestError on DUPLICATE_NEST; the double-entry audit reports DOUBLE_ENTRY_UNBALANCED / _HASH_MISMATCH / _STATE_MISMATCH and never auto-repairs.

Proofs: test/organ.test.mjs (23/23 v0; 34/34 with the v1 section; 44/44 with the v2 section; 54/54 with the v3 section, further below) — including a self-consistent forged chain (re-hashed by an attacker) that only replay can catch, and a forged host credit caught by double-entry. Evidence receipt: examples/receipts/boot-demo-receipt.json.

v0 substrate note: the toolkit had no cells/ledger concept before this lane, so src/organ/toyQuilt.mjs is the receipted stand-in quilt (4 op types, pure, clock-free). When a real cells/ledger layer lands (quilt-upstream or here), organ code moves onto it by adapting quiltApply / applyOp / stateOf.

v1 adds three verbs on top of v0's snapshot/boot/nest. v0's law is carried over untouched: nothing is trusted, everything is re-proven — the subject (bundle or booted organ) is fully re-verified (chain + replay == carried state) before any query, rewind, or write runs, so a rewind is never a forgery laundromat for the tail it ignores.

• stateAt(subject, seq) — time-travel query, pure: the state as of receipt seq, hash-asserted against an independent prefix replay. Never mutates, never writes host receipts.
• rewind(subject, toSeq) — bundle form: a pure view { state, stateHash, provenance } (input untouched). Organ form: destructive — the organ's ledger truncates to toSeq, cells are rebuilt by pure replay (byte-equal to a fresh boot of the truncated bundle), and if the organ is nested the host receives exactly ONE compensating receipt { type: "organ.rewind", organId, fromSeq, toSeq, stateHashAfter, rewound: [{creditSeq, creditHash, organSeq, debitHash}, ...] } — the double-entry discipline applied backwards, append-only: the superseded credits stay in the host ledger, marked dead by the evidence list.
• transact(bundle, ops) — all ops or nothing. PREPARE stages every op on detached copies, each validated against the post-op state (first failure names failedOp + code; the input bundle is byte-untouched). COMMIT materializes the successor bundle exactly once (supersedes pinned, same organId) and self-verifies it through the boot courtroom — a committed bundle is one that would boot.

# 0. the proof suite (34 tests) and the v1 end-to-end demo
npm test                                    # 23 v0 + 11 v1
npm run demo:rewind                         # transact → atomicity → stateAt → rewind → compensating credit → fail-closed audit

# 1. STATE AT — time-travel query (pure; bundles and booted organs)
node -e '
import("./src/organ/rewind.mjs").then(async ({ stateAt }) => {
  const { buildGreeterQuilt } = await import("./examples/greeter-organ.mjs");
  const { snapshot } = await import("./src/organ/snapshot.mjs");
  const q = buildGreeterQuilt();
  const v = stateAt(snapshot(q.cells, q.ledger, { name: "greeter-organ" }), 5);
  console.log(v.seq, v.stateHash.slice(0, 16), v.provenance.count, v.state.cells.subject.value);
});'

# 2. REWIND — bundle form is a pure view; organ form is the real rewind
#    rewind(bundle, toSeq) → { state, stateHash, provenance }
#    rewind(organ,  toSeq) → + rewoundFrom, compensating (host receipt if credits are revoked)

# 3. TRANSACT — atomic multi-op write (input bundle byte-untouched on any failure)
#    transact(bundle, ops) → ok: { bundle, newReceipts, fromStateHash, toStateHash }
#                            fail: { ok:false, phase:"prepare", failedOp, code, detail }

# 4. REWIND PAST A NEST BOUNDARY — compensating entry, double-entry applied backwards
#    host ledger gains organ.rewind; verifyDoubleEntry(host, organ)
#      → { ok, creditsChecked, creditsRevoked, rewinds }   // nets to zero

# 5. CONTINUE + RE-SNAPSHOT — the organ appends from the rewound tip, custody unbroken
#    organ.append(op) → fresh debit + fresh host credit; snapshotOrgan(organ)
#    boot(snapshotOrgan(organ)) → hash-equal state in a fresh quilt

(1 is a runnable one-liner; 2–5 are the lines examples/rewind-demo.mjs runs, each asserted by a demo stage with a committed evidence receipt at examples/receipts/rewind-v1-demo-receipt.json.)

• rewind round-trip: rewind(bundle, 0) reproduces the genesis state byte-identically; rewind to the pre-advance tip == the v0 snapshot's state hash; rewind to tip == carried state; a rewound organ's re-snapshot boots hash-equal in a fresh quilt.
• transaction atomicity: fail op 2 of 3 → OP_APPLY_FAILED at failedOp: 1, staged effects never leak, the bundle is byte-identical to before the transaction.
• compensating credit: rewinding a nested organ past its nest boundary emits one organ.rewind host receipt revoking exactly the post-nest credits; the host ledger still verifies; double-entry nets to zero; a partial rewind leaves the surviving credits pairing 1:1.
• stateAt determinism: same seq → same hash across independent builds and runs; pure on bundles and organs.
• fail-closed: forged rewind receipts are caught three ways (padded evidence → DOUBLE_ENTRY_REWIND_INVALID + DOUBLE_ENTRY_HASH_MISMATCH; bogus stateHashAfter → DOUBLE_ENTRY_STATE_MISMATCH; dangling evidence → DOUBLE_ENTRY_HASH_MISMATCH); bounds refuse REWIND_TARGET_INVALID / REWIND_PAST_CUSTODY; self-consistent forged chains refuse stateAt, rewind, AND transact with v0's REPLAY_DIVERGENCE.

Cross-feed: both v1 states (tip + rewound) are on the live fleet organ store — examples/receipts/rewind-v1-upload-receipt.json (uploaded through the receipted quilt.organ.v1 dialect adapter; native-dialect refusal receipted as the DIALECT_DRIFT finding, unification parked to lane 64-c).

v2 adds the scale path: mint a SIGNED checkpoint once (pay the genesis replay once), then boot bundles that carry only the post-checkpoint receipts plus a replay seed. The custody gap becomes conditional — legal exactly when an HMAC-SHA256 signature under the verifier's key covers the boundary; unsigned gaps still fail closed (CUSTODY_GAP, unchanged). Doctrine: docs/REVERSE-ACTUALIZED-SPEC.md §8.

# 0. the proof suite (44 tests: 34 v0/v1 + 10 v2)
npm test                                    # node --test test/organ.test.mjs

# 1. MINT — verify the snapshot, replay the prefix ONCE, sign (manifestHash, chainTip, seq)
node -e '
Promise.all([import("./src/organ/checkpoint.mjs"), import("./src/organ/snapshot.mjs"), import("./examples/greeter-organ.mjs")])
  .then(async ([{ signCheckpoint }, { snapshot }, { buildGreeterQuilt }]) => {
    const q = buildGreeterQuilt();
    const cp = signCheckpoint(snapshot(q.cells, q.ledger, { name: "greeter-organ" }), 7, "fleet-key");
    console.log(cp.seq, cp.alg, cp.manifestHash.slice(0, 16)); // 7 HMAC-SHA256 <prefix manifestHash>
  });'

# 2. CARVE — the partial-custody bundle: receipts [checkpointSeq+1..tip] + seed + signed checkpoint
#    carvePartialCustody(bundle, cp) → { manifest, state, receipts, seed, checkpoint }

# 3. BOOT --from-checkpoint — verify signature → replay from the anchored seed → assert == state
#    boot(partial, { checkpointKey: "fleet-key" })
#    → organ.custody = { signedAt: {seq, hash, manifestHash, alg}, verifiedRange, seed }
#    Fail-closed: CHECKPOINT_SIGNATURE_INVALID (forged/wrong key), CHECKPOINT_SEED_MISMATCH
#    (seed tamper), CHECKPOINT_ANCHOR_MISMATCH (swapped prefix manifest),
#    CHECKPOINT_SEQ_BEYOND_RECEIPTS, CHECKPOINT_SIGNATURE_REQUIRED (no key),
#    CUSTODY_GAP (unsigned gap — unchanged v0 law)

# 4. REWIND --from-checkpoint — down to the custody boundary only, hash-equal to
#    the full bundle's answers; below the boundary is unowned history:
#    rewind(organ, seq < boundary) → REWIND_PAST_CUSTODY (names the checkpoint)

# 5. CONTINUE + RE-SNAPSHOT — append/transact extend the same chain and carry the
#    anchor forward; snapshotOrgan(organ) boots again under the same key

Scale property: booting a 10-million-receipt organ costs O(tail), not O(history) — genesis is replayed once at checkpoint time, never at boot. The signature anchors the seed through two content-address hops (sig → manifestHash → prefix manifest → seed state); the only trust input is the key. Honest scope (§8.3): the anchor vouches for the prefix; post-checkpoint custody is the v0 law (hash chain + replay == state). Ed25519 attribution ("who vouches") is v3, below.

quilt-chrono's sealed sheets — ledger + <ledger>.chain.jsonl sidecar + seal() — are now boot()-able organs. src/organ/chronoOps.js adapts the chrono chain into organ receipts (spec §9: reads → no-op witness receipts, writes → cell sets, pushes → the (witness, set) pair; every decision named and tested), and bootChrono runs the full courtroom: seal signature → anchor manifest → sidecar chain verify → boundary pin → mapping → replay == the SIGNED state → the REAL boot().

# 0. the proof suite (70 tests: 54 v0–v3 + 16 chrono/§9)
npm test                                    # node --test test/organ.test.mjs tests/chrono-interop.test.mjs

# 1. BOOT A SEALED CHRONO SHEET (bundle = { links: <chain.jsonl links>, checkpoint: <seal> })
node -e '
import("./src/organ/chronoOps.js").then(async ({ bootChrono }) => {
  const f = JSON.parse((await import("node:fs")).readFileSync("./tests/fixtures/chrono-fixture.json", "utf8"));
  const organ = bootChrono({ links: f.links, checkpoint: f.checkpoint }, { key: f.key });
  console.log(organ.manifest.organId, JSON.stringify(organ.cells));
});'
# → chrono-demo@ef28377edd1b07fc {"sensor.temp":{"kind":"value","value":22.1},"sink.display":{"kind":"value","value":22.4}}

# 2. TIME TRAVEL — the organ verbs work on the chrono-born sheet
#    stateAt(organ, t) / rewind(organ, t) == the chrono write-fold at t

# 3. CUSTODY PROVENANCE — organ.custody = { kind: "chrono-seal", signedAt,
#    sealedRange, verifiedRange, chainTip }
#    Fail-closed: CHECKPOINT_SIGNATURE_INVALID (forged/wrong key),
#    CHECKPOINT_SEQ_BEYOND_RECEIPTS (truncated sidecar),
#    CUSTODY_CHECKPOINT_MISMATCH (wrong chain), CHECKPOINT_ANCHOR_MISMATCH
#    (swapped anchor), REPLAY_DIVERGENCE (stale signed manifest),
#    CHRONO_OP_UNMAPPABLE / CHRONO_FLOW_UNPAIRED (semantic refusals)

# 4. REGENERATE THE FIXTURE (needs ../quilt-chrono present; test-only key)
npm run fixture:chrono                       # scripts/vendor-chrono-fixture.mjs

The live interop test (LIVE interop in tests/chrono-interop.test.mjs) builds a sheet with chrono's own Ledger, seals it with chrono's own seal(), boots it here, and asserts equality with chrono's own verifyCustody — skip-if-absent, so this repo stays standalone. Doctrine: docs/REVERSE-ACTUALIZED-SPEC.md §9.

v2's HMAC is symmetric: every writer holds full signing power, so attribution was fleet-trust, not identity. v3 splits the power with Ed25519 (node:crypto, stdlib, zero deps) — the private key mints, the PUBLIC key verifies, and the checkpoint NAMES its signer by publicKeyFingerprint (sha256 of the signer's SPKI PEM — the same fingerprint law quilt-mcp-receipts' attribution layer uses, which is what makes the cross-repo demo possible). Doctrine: spec §10.

# 0. the proof suite (54 tests incl. 10 v3)
npm test

# 1. MINT — the FULL boot courtroom runs first, then Ed25519 over the same
#    canonical triple (hash, manifestHash, seq) as v2
node -e '
Promise.all([import("./src/organ/checkpoint.mjs"), import("./src/organ/ed25519.mjs"), import("./src/organ/snapshot.mjs"), import("./examples/greeter-organ.mjs")])
  .then(async ([{ signCheckpointEd25519 }, { generateEd25519Keypair }, { snapshot }, { buildGreeterQuilt }]) => {
    const id = generateEd25519Keypair();                 // runtime keys — never committed
    const q = buildGreeterQuilt();
    const cp = signCheckpointEd25519(snapshot(q.cells, q.ledger, { name: "greeter-organ" }), 7, id.privateKeyPem);
    console.log(cp.alg, cp.publicKeyFingerprint.slice(0, 16), cp.sig.slice(0, 16));
  });'

# 2. VERIFY — the key HOLDS the trust (no shared secret exists)
#    verifyCheckpointEd25519(cp, publicKeyPem) → { ok } | { ok:false, code, detail }
#    (verifySignedCheckpoint dispatches on alg — one doorway, v2+v3)
#    Fail-closed: CHECKPOINT_SIGNATURE_INVALID (forged / wrong key /
#    unusable key material), CHECKPOINT_MALFORMED (unknown alg, missing
#    fingerprint), CHECKPOINT_SIGNATURE_REQUIRED (no key)

# 3. ROTATE — a bundle may carry MULTIPLE valid checkpoints under different
#    keys (chain of custody across key rotations; each key checks ITS era):
#    cp1 = signCheckpoint(full, 7, hmacKey); cp2 = signCheckpointEd25519(full, 12, priv2)
#    partial = carveRotatedCustody(full, [cp1, cp2])
#    boot(partial, { checkpointKeys: [hmacKey, publicKey2] })
#    → custody.signers = [{kind:"hmac-sha256",...}, {kind:"ed25519", publicKeyFingerprint}]
#    Later eras are proven by REPLAY from the previous era's anchor — a genuine
#    key signing an unreachable state refuses CUSTODY_CHECKPOINT_MISMATCH.

# 4. CROSS-REPO PROOF — one Ed25519 identity signs an organ checkpoint AND the
#    qmr2 attribution rows; each repo's verifier checks the other's artifact
#    (zero shared secrets — only the public key travels):
#    node examples/v3-attribution-demo.mjs verify

Custody provenance gains a name: organ.custody.signer = { kind: "ed25519", anchoredAt, publicKeyFingerprint } (v2 organs carry { kind: "hmac-sha256", anchoredAt } — a shared secret has no name, the honest residual, receipted in the provenance itself). Honest scope (§10.7): the anchor vouches for the prefix exactly as v2's does; key distribution is trust-on-first-use. Revocation (§11, wave-69): the ENFORCEMENT half is live — boot(bundle, { …, revokedKeys: { fingerprint → revocationSeq } }) refuses eras anchored after a key's closure with E_KEY_REVOKED; the signed-statement layer stays parked by design (spec §11's parking receipt). Minting a keyring (identity + fingerprint + ready-made {fingerprint → publicKeyPem} map) is one helper: node examples/keyring-mint.mjs (or import mintKeyring).

export TYPESAFE_API_KEY=apikey_...   # legacy TYPESAFEAI_KEY also accepted
python3 jev_client.py "the earth is round" '{"x": {"type": "noul", "instructions": "Is this true?"}}'

Or in Python:

from jev_client import ask, noul, choice, score

result = ask(
    "Quilt cells form communities that grow and die like organisms.",
    {
        "is_canon": noul("Is this canon-worthy?"),
        "domain": choice("Which domain?", {"biology": "...", "cs": "..."}),
        "depth": score("Rate depth", ["low", "moderate", "high", "extreme"]),
    }
)
print(result["answers"])

Rounds run so far:

• jev_client.py — minimal JEV client (noul / choice / score builders)
• canon_gate.py — score Quilt content for canon promotion
• discovery_log.md — round-by-round findings

JEV is fast and well-calibrated, but it's still an LLM oracle. It can hallucinate (see Round 2 — "humans have 5 senses" returned 0.49, which is technically right — humans have more than 5 senses — but the conventional answer is 5).

Use JEV as one canary in a multi-signal canon gate:

• JEV score
• Byte-exact polyformality (across 6 substrates)
• Multi-model consensus (JEV + ZAI + DeepSeek agreeing)
• Human review for borderline cases

• criteria is required for score and choice questions (a list of strings for score, a dict of {name: description} for choice)
• noul questions can have criteria (true/false descriptions) but it's optional
• JEV returns usage.input_tokens and usage.output_tokens — use them to budget
• The model name in response is jev-1.13.0 (not the alias jev-latest you sent)
• For choice questions, confidence can be low even when the choice is clearly correct — check the probabilities dict

Wave-69 documentation package (task 69-doc-b). Start here by audience:

• Agent onboarding (zero-shot entry): docs/ONBOARDING.md — identity, verify-commands (incl. the env-key rule), reading order, gotchas, frontier.
• End users: docs/USER-GUIDE.md — install, first success (real captured output), organ + JEV everyday tasks, fail-closed troubleshooting table, FAQ.
• Developers: docs/DEVELOPER-GUIDE.md — code layout, core concepts, how to add ops/checkpoint schemes/adapters, testing, conventions.
• Engineers / operators: docs/ENGINEERING-NOTES.md — architecture, invariants, failure modes & blast radius, cost envelope, the credential model, design decisions.
• Executives: docs/CTO-BRIEF.md — value, maturity, risks, cost profile, strategic options, integration surface.
• Index of all deeper knowledge: docs/KNOWLEDGE-MAP.md — every module, spec section, receipt, and journal Task ID, one line each.