dexterm-cli 0.1.6 → 0.1.7

package/dist/packages/data/src/trade/ledger/file.js

@@ -0,0 +1,135 @@
+// task-1530 — the unified trade ledger FILE: $DEXTERM_HOME/ledger/trades.jsonl (0600, the directory 0700).
+//
+// Appends only. An append re-reads the file, verifies the whole chain, skips any draft whose `ref` is already
+// there, and writes the new lines in one append, all under a lock file, so two syncs never interleave. A file whose
+// chain is broken is never appended to (the user sees where it broke with `dexterm ledger verify`); a file written
+// by a newer dexterm is refused rather than half-read.
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { GENESIS, LEDGER_SCHEMA, LEDGER_VERSION, ledgerHash, verifyLedger } from "./schema.js";
+export function dextermHomeDir(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export const tradeLedgerPath = (env = process.env) => join(dextermHomeDir(env), 'ledger', 'trades.jsonl');
+/** Read and verify. A missing file is an empty, valid ledger. A line that is not JSON fails the check at that line. */
+export function readTradeLedger(path) {
+    if (!existsSync(path))
+        return { events: [], check: { ok: true, events: 0, head: GENESIS }, exists: false };
+    const events = [];
+    const lines = readFileSync(path, 'utf8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        if (!l.trim())
+            continue;
+        try {
+            events.push(JSON.parse(l));
+        }
+        catch {
+            return { events, check: { ok: false, events: events.length, at: events.length + 1, error: 'a line is not JSON (the file was edited or cut off)' }, exists: true };
+        }
+    }
+    const head = events[0];
+    if (head && head.kind === 'header' && head.schema !== LEDGER_SCHEMA) {
+        return { events, check: { ok: false, events: events.length, at: 1, error: `unknown ledger schema ${JSON.stringify(head.schema)} (this build reads ${LEDGER_SCHEMA})` }, exists: true };
+    }
+    return { events, check: verifyLedger(events), exists: true };
+}
+export class LedgerBusyError extends Error {
+    constructor(m) { super(m); this.name = 'LedgerBusyError'; }
+}
+export class LedgerBrokenError extends Error {
+    constructor(m) { super(m); this.name = 'LedgerBrokenError'; }
+}
+const LOCK_STALE_MS = 60_000;
+function withLock(path, fn) {
+    const lock = `${path}.lock`;
+    let fd = null;
+    for (let attempt = 0; attempt < 2 && fd === null; attempt++) {
+        try {
+            fd = openSync(lock, 'wx', 0o600);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let age = 0;
+            try {
+                age = Date.now() - statSync(lock).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (age > LOCK_STALE_MS) {
+                try {
+                    unlinkSync(lock);
+                }
+                catch { /* raced */ }
+                continue;
+            }
+            throw new LedgerBusyError('another ledger sync is running (try again in a few seconds)');
+        }
+    }
+    if (fd === null)
+        throw new LedgerBusyError('could not take the ledger lock');
+    try {
+        writeSync(fd, String(process.pid));
+        return fn();
+    }
+    finally {
+        closeSync(fd);
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* gone */ }
+    }
+}
+/**
+ * Append drafts to the ledger (creating it with its header when missing). Drafts whose `ref` is already in the
+ * file are skipped, so an import can be re-run any number of times. `now` stamps the header only.
+ */
+export function appendTradeLedger(path, drafts, now = Date.now()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    return withLock(path, () => {
+        const cur = readTradeLedger(path);
+        if (!cur.check.ok)
+            throw new LedgerBrokenError(`the ledger at ${path} fails its check at line ${cur.check.at}: ${cur.check.error}. Nothing was appended.`);
+        const seen = new Set();
+        for (const e of cur.events)
+            if ('ref' in e && typeof e.ref === 'string')
+                seen.add(e.ref);
+        let prev = cur.events.length ? cur.events[cur.events.length - 1].hash : GENESIS;
+        let seq = cur.events.length;
+        const out = [];
+        const push = (d) => {
+            const e = { ...d, seq: ++seq, v: LEDGER_VERSION };
+            delete e.prev;
+            delete e.hash;
+            const h = ledgerHash(prev, e);
+            e.prev = prev;
+            e.hash = h;
+            prev = h;
+            out.push(JSON.stringify(e));
+        };
+        if (!cur.events.length)
+            push({ kind: 'header', t: now, schema: LEDGER_SCHEMA, createdAt: now });
+        let skipped = 0;
+        for (const d of drafts) {
+            const ref = d.ref;
+            if (typeof ref !== 'string' || !ref)
+                throw new Error('a ledger event needs a ref');
+            if (seen.has(ref)) {
+                skipped++;
+                continue;
+            }
+            seen.add(ref);
+            push(d);
+        }
+        const added = out.length - (cur.events.length ? 0 : 1);
+        if (out.length) {
+            if (!cur.exists)
+                closeSync(openSync(path, 'a', 0o600));
+            appendFileSync(path, `${out.join('\n')}\n`);
+        }
+        return { added, skipped, head: prev, events: seq };
+    });
+}

package/dist/packages/data/src/trade/ledger/fold.js

@@ -0,0 +1,191 @@
+// task-1530 — fold ledger events into TRADES (one row per round trip). Pure: the same events give the same rows.
+//
+// A trade is every fill that shares a `tradeKey`, from the first buy until the source says it is flat (or a
+// `close` event). What the row carries, and where each field comes from:
+//   strategy        id + version + hash from the fills (autotrade runs, live runner orders)
+//   profile         the entry fill's tag, else a late PROFILE tag, then every REPROFILE in order (the last wins)
+//   entry / exit    the entry fill's reason; the closing sell's exit reason code and the agent's words
+//   size            SOL (and USD) in, % of the book the source had just before the first buy
+//   prices          average entry, blended exit, as SOL price, USD price and market cap (price × recorded supply)
+//   costs           fees, the SOL-weighted price impact of entries and exits, the slippage limit used
+//   hold            first buy to the closing fill (an open trade: to `now`)
+//   MFE / MAE       best and worst move from the entry price that the source SAW: the close event's extremes
+//                   plus every fill's own price ('observed' vs 'fills only' says which)
+//   rug             an annotate event, else a bag that could not be sold (stuck), else a liquidity exit that
+//                   lost 80 %+ ('why' names the rule)
+//   model           every session id on the trade's fills / close, and the sum of their recorded costs
+/** Exit codes that mean the pool went away under the position. */
+const LIQUIDITY_EXITS = new Set(['thesis-liquidity', 'illiquid', 'rug', 'liquidity-pull', 'lp-pull', 'stuck']);
+const RUG_LOSS_PCT = -80;
+const sum = (xs) => { let s = 0, n = 0; for (const x of xs)
+    if (x !== null) {
+        s += x;
+        n++;
+    } return n ? s : null; };
+const r = (x, p = 6) => (x === null || !Number.isFinite(x) ? null : Number(x.toPrecision(p)));
+const rank = { structured: 6, rule: 5, 'tag-line': 4, late: 3, default: 2, missing: 1 };
+/** Weighted mean of `v` by `w` over the fills where both are known. */
+function wmean(fs, v, w) {
+    let s = 0, ws = 0;
+    for (const f of fs) {
+        const a = v(f), b = w(f);
+        if (a !== null && b !== null && b > 0) {
+            s += a * b;
+            ws += b;
+        }
+    }
+    return ws > 0 ? s / ws : null;
+}
+export function foldTrades(events, o = {}) {
+    const now = o.now ?? Date.now();
+    const fills = new Map();
+    const tags = [];
+    const closes = new Map();
+    const looseCloses = [];
+    const costs = new Map();
+    const notes = new Map();
+    for (const e of events) {
+        if (e.kind === 'fill') {
+            const a = fills.get(e.tradeKey) ?? [];
+            a.push(e);
+            fills.set(e.tradeKey, a);
+        }
+        else if (e.kind === 'tag')
+            tags.push(e);
+        else if (e.kind === 'close') {
+            if (e.tradeKey)
+                closes.set(e.tradeKey, e);
+            else
+                looseCloses.push(e);
+        }
+        else if (e.kind === 'cost') {
+            const c = costs.get(e.sessionId);
+            costs.set(e.sessionId, { usd: (c?.usd ?? 0) + e.costUsd, model: e.model ?? c?.model ?? null });
+        }
+        else if (e.kind === 'annotate')
+            notes.set(e.tradeKey, e);
+    }
+    const rows = [];
+    for (const [key, fsRaw] of fills) {
+        const fs = [...fsRaw].sort((a, b) => a.t - b.t || a.seq - b.seq);
+        const buys = fs.filter((f) => f.side === 'buy');
+        const sells = fs.filter((f) => f.side === 'sell');
+        if (!buys.length)
+            continue; // a sell with no buy on record has no basis; it is not a trade
+        const first = buys[0];
+        const closing = [...fs].reverse().find((f) => f.closes === true) ?? null;
+        // a loose close (the run that traded this coin on the desk): the first one after the entry, near the last fill
+        const lastT = fs[fs.length - 1].t;
+        const close = closes.get(key) ?? looseCloses.find((c) => c.mint === first.mint && c.source === first.source && c.t >= first.t - 5_000 && (closing ? c.t <= closing.t + 120_000 : c.t <= lastT + 120_000) && c.t >= lastT - 120_000) ?? null;
+        const status = close || closing ? 'closed' : 'open';
+        const closedAt = status === 'closed' ? Math.max(close?.t ?? -Infinity, closing?.t ?? -Infinity, fs[fs.length - 1].t) : null;
+        // ── tags ──
+        const myTags = tags.filter((g) => g.tradeKey === key || (g.tradeKey === null && g.mint === first.mint && g.source === first.source && g.t >= first.t && (closedAt === null || g.t <= closedAt + 120_000)));
+        let profile = { id: null, source: 'missing' };
+        const pick = (id, source) => { if (id && rank[source] > rank[profile.source])
+            profile = { id, source }; };
+        pick(first.tag?.profile, first.tag?.source ?? 'missing');
+        for (const g of myTags)
+            if (g.tagKind === 'profile')
+                pick(g.profile, g.tagSource);
+        const reprofiles = myTags.filter((g) => g.tagKind === 'reprofile').sort((a, b) => a.t - b.t).map((g) => ({ t: g.t, from: g.from ?? null, to: g.to ?? null, reason: g.reason ?? null }));
+        if (reprofiles.length && reprofiles[reprofiles.length - 1].to)
+            profile = { id: reprofiles[reprofiles.length - 1].to, source: profile.source === 'missing' ? 'late' : profile.source };
+        const entryTagged = first.tag && first.tag.reason ? first.tag : (myTags.find((g) => g.tagKind === 'profile' && g.reason) ?? null);
+        const entryReason = entryTagged
+            ? { code: null, text: entryTagged.reason ?? null, line: entryTagged.line ?? null, source: 'tagSource' in entryTagged ? entryTagged.tagSource : entryTagged.reasonSource ?? entryTagged.source }
+            : { code: null, text: null, line: null, source: first.tag?.source === 'default' ? 'default' : 'missing' };
+        const lastSell = closing ?? sells[sells.length - 1] ?? null;
+        const exitTag = lastSell?.tag ?? null;
+        const lateExit = [...myTags].reverse().find((g) => g.tagKind === 'exit') ?? null;
+        let exitReason = { code: null, text: null, line: null, source: 'missing' };
+        if (exitTag && (exitTag.exitReason || exitTag.reason))
+            exitReason = { code: exitTag.exitReason ?? null, text: exitTag.reason ?? null, line: exitTag.line ?? null, source: exitTag.source };
+        if (lateExit && rank[lateExit.tagSource] > rank[exitReason.source])
+            exitReason = { code: lateExit.exitReason ?? exitReason.code, text: lateExit.reason ?? exitReason.text, line: lateExit.line ?? null, source: lateExit.tagSource };
+        if (!exitReason.code && close?.reason)
+            exitReason = { ...exitReason, code: close.reason, source: exitReason.source === 'missing' ? 'rule' : exitReason.source };
+        if (status === 'open')
+            exitReason = { code: null, text: null, line: null, source: 'missing' };
+        // ── money ──
+        const sizeSol = sum(buys.map((f) => f.sol));
+        const sizeUsd = sum(buys.map((f) => f.usd));
+        const proceedsSol = sells.length ? sum(sells.map((f) => f.sol)) : null;
+        const proceedsUsd = sells.length ? sum(sells.map((f) => f.usd)) : null;
+        const boughtTok = sum(buys.map((f) => f.tokens));
+        const soldTok = sum(sells.map((f) => f.tokens));
+        const entryPriceSol = sizeSol !== null && boughtTok ? sizeSol / boughtTok : wmean(buys, (f) => f.priceSol, (f) => f.tokens);
+        const entryPriceUsd = sizeUsd !== null && boughtTok ? sizeUsd / boughtTok : wmean(buys, (f) => f.priceUsd, (f) => f.tokens);
+        const exitPriceSol = proceedsSol !== null && soldTok ? proceedsSol / soldTok : wmean(sells, (f) => f.priceSol, (f) => f.tokens);
+        const exitPriceUsd = proceedsUsd !== null && soldTok ? proceedsUsd / soldTok : wmean(sells, (f) => f.priceUsd, (f) => f.tokens);
+        const supply = [...fs].reverse().find((f) => f.supply && f.supply.tokens > 0)?.supply ?? null;
+        const mcap = (p) => (p !== null && supply ? p * supply.tokens : null);
+        const closedOut = status === 'closed';
+        const pnlSol = closedOut && sizeSol !== null ? (proceedsSol ?? 0) - sizeSol : null;
+        const pnlUsd = closedOut && sizeUsd !== null ? (proceedsUsd ?? 0) - sizeUsd : null;
+        const pnlPct = pnlSol !== null && sizeSol ? (pnlSol / sizeSol) * 100 : pnlUsd !== null && sizeUsd ? (pnlUsd / sizeUsd) * 100 : null;
+        const bookSol = first.bookSol;
+        const bookUsd = first.bookUsd;
+        const pctOfBook = sizeSol !== null && bookSol ? (first.sol ?? sizeSol) / bookSol * 100 : first.usd !== null && bookUsd ? first.usd / bookUsd * 100 : null;
+        // ── excursions: the source's extremes + every fill's own price, in the unit the entry is known in ──
+        const unit = close?.priceUnit ?? (entryPriceSol !== null ? 'sol' : entryPriceUsd !== null ? 'usd' : null);
+        const entryRef = close?.entryPrice ?? (unit === 'sol' ? entryPriceSol : unit === 'usd' ? entryPriceUsd : null);
+        const obs = [];
+        for (const f of fs) {
+            const p = unit === 'sol' ? f.priceSol : f.priceUsd;
+            if (p !== null && p > 0)
+                obs.push(p);
+        }
+        if (close?.peakPrice)
+            obs.push(close.peakPrice);
+        if (close?.troughPrice)
+            obs.push(close.troughPrice);
+        const mfePct = entryRef && obs.length ? (Math.max(...obs) / entryRef - 1) * 100 : null;
+        const maePct = entryRef && obs.length ? (Math.min(...obs) / entryRef - 1) * 100 : null;
+        const excursionBasis = mfePct === null ? null : close && (close.peakPrice || close.troughPrice) ? 'observed' : 'fills only';
+        // ── rug ──
+        const stuck = close?.stuck ?? false;
+        const note = notes.get(key) ?? null;
+        let rug = false, rugWhy = null;
+        if (note && note.rug !== null) {
+            rug = note.rug;
+            rugWhy = note.why;
+        }
+        else if (stuck) {
+            rug = true;
+            rugWhy = 'stuck: the bag could not be sold (no exit liquidity)';
+        }
+        else if (closedOut && exitReason.code && LIQUIDITY_EXITS.has(exitReason.code) && pnlPct !== null && pnlPct <= RUG_LOSS_PCT) {
+            rug = true;
+            rugWhy = `${exitReason.code} exit at ${pnlPct.toFixed(0)}%`;
+        }
+        // ── model ──
+        const sessionIds = [...new Set([...fs.map((f) => f.sessionId), close?.sessionId ?? null].filter((x) => !!x))];
+        const known = sessionIds.filter((id) => costs.has(id));
+        const costUsd = known.length ? known.reduce((s, id) => s + costs.get(id).usd, 0) : null;
+        const models = [...new Set([...fs.map((f) => f.model), ...known.map((id) => costs.get(id).model)].filter((x) => !!x))];
+        const weightSol = (f) => f.sol ?? f.usd;
+        rows.push({
+            tradeId: key, source: first.source, walletMode: first.walletMode, status, mint: first.mint, symbol: first.symbol, decimals: fs.find((f) => f.decimals !== null)?.decimals ?? null,
+            runId: first.runId, agent: first.agent, strategy: [...fs].reverse().find((f) => f.strategy)?.strategy ?? null,
+            account: fs.find((f) => f.account)?.account ?? null,
+            profile, reprofiles, entryReason, exitReason,
+            openedAt: first.t, closedAt, holdSec: Math.max(0, Math.round(((closedAt ?? now) - first.t) / 1000)),
+            buys: buys.length, sells: sells.length,
+            sizeSol: r(sizeSol), sizeUsd: r(sizeUsd), pctOfBook: r(pctOfBook, 4), bookSol: r(bookSol), bookUsd: r(bookUsd),
+            entryPriceSol: r(entryPriceSol), entryPriceUsd: r(entryPriceUsd), entryMcapUsd: r(mcap(entryPriceUsd)),
+            exitPriceSol: r(exitPriceSol), exitPriceUsd: r(exitPriceUsd), exitMcapUsd: r(mcap(exitPriceUsd)),
+            supply, proceedsSol: r(proceedsSol), proceedsUsd: r(proceedsUsd),
+            pnlSol: r(pnlSol), pnlUsd: r(pnlUsd), pnlPct: r(pnlPct, 4),
+            feesSol: r(sum(fs.map((f) => f.feeSol))),
+            impactPctEntry: r(wmean(buys, (f) => f.impactPct, weightSol), 4), impactPctExit: r(wmean(sells, (f) => f.impactPct, weightSol), 4),
+            slippageBps: fs.reduce((m, f) => (f.slippageBps === null ? m : Math.max(m ?? 0, f.slippageBps)), null),
+            mfePct: r(mfePct, 4), maePct: r(maePct, 4), excursionBasis,
+            rug, rugWhy, stuck,
+            txSigs: fs.map((f) => f.txSig).filter((x) => !!x),
+            model: { sessionIds, costUsd: r(costUsd), models },
+            fills: fs.map((f) => ({ ref: f.ref, t: f.t, side: f.side, sol: f.sol, usd: f.usd, tokens: f.tokens, priceSol: f.priceSol, priceUsd: f.priceUsd, mcapUsd: r(mcap(f.priceUsd)), feeSol: f.feeSol, impactPct: f.impactPct, exitReason: f.tag?.exitReason ?? null, txSig: f.txSig })),
+        });
+    }
+    return rows.sort((a, b) => a.openedAt - b.openedAt || a.tradeId.localeCompare(b.tradeId));
+}

package/dist/packages/data/src/trade/ledger/index.js

@@ -0,0 +1,9 @@
+// task-1530 — @dexterm/data/ledger: the unified trade ledger (schema, file, importers, fold, stats, exports).
+export * from "./schema.js";
+export * from "./file.js";
+export * from "./tags.js";
+export * from "./sources.js";
+export * from "./fold.js";
+export * from "./stats.js";
+export * from "./export.js";
+export * from "./view.js";

package/dist/packages/data/src/trade/ledger/schema.js

@@ -0,0 +1,83 @@
+// task-1530 — the UNIFIED TRADE LEDGER (`dexterm-ledger/1`): one schema for every trade dexterm books, whatever
+// booked it (the paper wallet, the agent paper desk, an autotrade run, the live signer).
+//
+// The ledger is an append-only, hash-chained JSONL file of EVENTS. A trade is never stored as a mutable row: it is
+// folded from its events (`fold.ts`), so a late PROFILE line, a rug found after the exit or a session's cost can
+// be added later without rewriting anything.
+//
+//   header   line 1: the schema, when the file was made
+//   import   provenance: which source journal was read, how many events, its own chain head and check
+//   fill     one buy or sell (SOL, USD, tokens, price, supply, fees, impact, slippage, the book before it, tag, tx sig)
+//   tag      a PROFILE / REPROFILE / EXIT declared apart from its fill (a late line, a reprofile)
+//   close    the source closed the position (stuck or not), with the price extremes it saw (MFE / MAE)
+//   cost     a model session's cost (joined to the trades that name the session)
+//   annotate a fact found later about a trade (a rug)
+//
+// Every event carries `ref`, unique per source event, so importing the same journal twice adds nothing. Its hash
+// covers the previous hash plus the canonical event, so an edited, dropped or reordered line breaks the chain from
+// that line on (`verifyLedger`). Nothing in a ledger event can hold a key: there is no field for one, and every
+// string is passed through `redactKeyShaped` on the way in.
+import { createHash } from 'node:crypto';
+export const LEDGER_SCHEMA = 'dexterm-ledger/1';
+/** The event format this build writes and reads. A file from a newer build is refused (never half-read). */
+export const LEDGER_VERSION = 1;
+export const GENESIS = 'genesis';
+export const LEDGER_SOURCES = ['paper', 'desk', 'autotrade', 'live'];
+export const WALLET_MODES = ['paper', 'devnet', 'live'];
+// ───────────────────────────── hygiene ─────────────────────────────
+/** A base58 secret key (64 bytes ≈ 87-88 chars) or a 64-number byte array: never stored, whatever field it is in. */
+const KEY_SHAPED = /(?:[1-9A-HJ-NP-Za-km-z]{85,90})|(?:\[(?:\s*\d{1,3}\s*,){63}\s*\d{1,3}\s*\])/g;
+export const redactKeyShaped = (s) => s.replace(KEY_SHAPED, '[REDACTED]');
+/** Text from a journal or an agent: one line, control characters out, capped, key-shaped runs redacted. */
+export function cleanLedgerText(s, max = 200) {
+    if (typeof s !== 'string')
+        return null;
+    // eslint-disable-next-line no-control-regex
+    const t = redactKeyShaped(s.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim());
+    return t ? t.slice(0, max) : null;
+}
+/** Ids, codes and refs: a strict alphabet, so nothing odd ever lands in an id column. */
+export function cleanCode(s, max = 64) {
+    if (typeof s !== 'string')
+        return null;
+    const t = s.trim().toLowerCase().replace(/[^a-z0-9:_.@-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, max);
+    return t || null;
+}
+export const finite = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+// ───────────────────────────── the chain ─────────────────────────────
+/** Sorted keys, undefined dropped, so a stored line re-hashes to the same value. (No key is special.) */
+export function canonicalJson(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v) ?? 'null';
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).filter((k) => o[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(',')}}`;
+}
+/** sha256(prev + canonical(event without prev/hash)), full hex. */
+export function ledgerHash(prev, e) {
+    const { prev: _p, hash: _h, ...body } = e;
+    return createHash('sha256').update(prev + canonicalJson(body)).digest('hex');
+}
+/** Recompute the chain: seq 1..n, every prev is the previous hash, every hash matches its content, line 1 is the header. */
+export function verifyLedger(events) {
+    let prev = GENESIS;
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.seq !== i + 1)
+            return { ok: false, events: events.length, at: i + 1, error: `seq ${String(e.seq)} where ${i + 1} was expected` };
+        if (i === 0 && e.kind !== 'header')
+            return { ok: false, events: events.length, at: 1, error: 'line 1 is not the ledger header' };
+        if (i > 0 && e.kind === 'header')
+            return { ok: false, events: events.length, at: i + 1, error: 'a second header' };
+        if (typeof e.v !== 'number' || e.v > LEDGER_VERSION)
+            return { ok: false, events: events.length, at: i + 1, error: `event version ${String(e.v)} is newer than this build reads (${LEDGER_VERSION}); update dexterm` };
+        if (e.prev !== prev)
+            return { ok: false, events: events.length, at: i + 1, error: 'prev does not match the previous hash (a line was removed, added or reordered)' };
+        const want = ledgerHash(prev, e);
+        if (e.hash !== want)
+            return { ok: false, events: events.length, at: i + 1, error: 'hash does not match the content (the line was edited)' };
+        prev = want;
+    }
+    return { ok: true, events: events.length, head: prev };
+}