@thehonestmachine/oath-sdk 0.1.0

package/dist/verify.d.ts

@@ -0,0 +1,43 @@
+import { type OathDoc, type SignedTreeHead } from '@thehonestmachine/oath-core';
+export interface CheckResult {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface VerificationReport {
+    ok: boolean;
+    source: string;
+    agents: string[];
+    treeSize: number;
+    checks: CheckResult[];
+}
+/** Everything a monitor needs, however it was obtained. All of it public. */
+export interface LedgerData {
+    source: string;
+    /** Exact leaf bytes, position = leaf index. */
+    leafLines: string[];
+    /** Every signed tree head, in emission order. */
+    heads: SignedTreeHead[];
+    /** Keys allowed to sign tree heads (agent key locally, ledger key remotely). */
+    sthPubkeys: string[];
+    /** Oath version chains per agent handle. */
+    oathsByAgent: Map<string, OathDoc[]>;
+}
+/**
+ * Verify ledger contents from nothing but public data (SPEC.md §6, §11):
+ * recompute the tree, re-check every signature, every tree head, every oath
+ * chain, and the consistency of the whole history. Needs no keys and no
+ * trust in the operator — this is what a monitor runs.
+ */
+export declare function verifyLedgerData(data: LedgerData): VerificationReport;
+/** Verify a local ledger directory (SPEC.md Appendix A). */
+export declare function verifyLocalLedger(dir: string): VerificationReport;
+/**
+ * Verify a remote public ledger over its read API (SPEC.md §11.2), starting
+ * from its discovery document. Entries beyond the latest tree head are
+ * within the merge delay and are not judged yet.
+ */
+export declare function verifyRemoteLedger(url: string, options?: {
+    fetch?: typeof fetch;
+}): Promise<VerificationReport>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAkBL,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAKrC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iDAAiD;IACjD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4CAA4C;IAC5C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,kBAAkB,CAiLrE;AAUD,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAuBjE;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACrC,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}

package/dist/verify.js

@@ -0,0 +1,278 @@
+import { assertEntryUnderOath, assertValidAmendment, assertValidEntry, assertValidOathDoc, assertValidSth, bytesToHex, canonicalize, consistencyPath, hexToBytes, leafHash, oathHash, rootFromLeafHashes, utf8Bytes, verifyConsistency, verifyOathSignature, verifySthSignature, } from '@thehonestmachine/oath-core';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { LEDGER_FILES, readLeafLines, readOathVersions } from './localLedger.js';
+/**
+ * Verify ledger contents from nothing but public data (SPEC.md §6, §11):
+ * recompute the tree, re-check every signature, every tree head, every oath
+ * chain, and the consistency of the whole history. Needs no keys and no
+ * trust in the operator — this is what a monitor runs.
+ */
+export function verifyLedgerData(data) {
+    const { leafLines, heads, sthPubkeys, oathsByAgent } = data;
+    const checks = [];
+    const agents = [...oathsByAgent.keys()];
+    checks.push({
+        name: 'files',
+        ok: true,
+        detail: `${agents.length} agent(s), ${leafLines.length} entries, ${heads.length} tree heads`,
+    });
+    // 1. Oath chains: v1 self-signed, every later version a valid amendment (§2, §9).
+    const chainProblems = [];
+    for (const [handle, versions] of oathsByAgent) {
+        try {
+            if (versions.length === 0)
+                throw new Error('no oath versions');
+            versions.forEach((doc) => assertValidOathDoc(doc));
+            if (versions[0].version !== 1)
+                throw new Error('chain does not start at version 1');
+            if (!verifyOathSignature(versions[0])) {
+                throw new Error('v1 signature does not verify against its own pubkey');
+            }
+            for (let i = 1; i < versions.length; i++) {
+                assertValidAmendment(versions[i - 1], versions[i]);
+            }
+        }
+        catch (error) {
+            chainProblems.push(`${handle}: ${error.message}`);
+        }
+    }
+    checks.push({
+        name: 'oath-chain',
+        ok: chainProblems.length === 0,
+        detail: chainProblems.length === 0
+            ? `${agents.length} chain(s), forward-only, signatures verify`
+            : chainProblems.join('; '),
+    });
+    // 2. Every entry: canonical bytes, valid shape, signed under its oath version (§3).
+    const entries = [];
+    const entryProblems = [];
+    leafLines.forEach((line, i) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (canonicalize(parsed) !== line)
+                throw new Error('line is not in canonical (JCS) form');
+            assertValidEntry(parsed);
+            const versions = oathsByAgent.get(parsed.agent);
+            const oath = versions?.find((o) => o.version === parsed.oath_version);
+            if (oath === undefined) {
+                throw new Error(`cites unknown oath ${parsed.agent} v${parsed.oath_version}`);
+            }
+            assertEntryUnderOath(parsed, oath);
+            entries.push(parsed);
+        }
+        catch (error) {
+            entries.push(null);
+            entryProblems.push(`entry ${i}: ${error.message}`);
+        }
+    });
+    checks.push({
+        name: 'entries',
+        ok: entryProblems.length === 0,
+        detail: entryProblems.length === 0
+            ? `${leafLines.length} entries valid, canonical, and signed`
+            : entryProblems.join('; '),
+    });
+    // 3. Sworn records: each agent's first entry is its oath.swear; every
+    //    amendment is committed to by an oath.amend entry (§2.4, §9).
+    const recordProblems = [];
+    for (const [handle, versions] of oathsByAgent) {
+        const own = entries.filter((e) => e !== null && e.agent === handle);
+        const first = own[0];
+        const v1Hash = versions.length > 0 ? safeOathHash(versions[0]) : null;
+        if (first === undefined || first.action.type !== 'oath.swear' || first.action.content_hash !== v1Hash) {
+            recordProblems.push(`${handle}: first entry is not oath.swear committing to oath v1`);
+        }
+        // Every declared amendment must be committed to by exactly its own leaf...
+        const validAmendHashes = new Set();
+        for (let v = 2; v <= versions.length; v++) {
+            const hash = safeOathHash(versions[v - 1]);
+            if (hash !== null)
+                validAmendHashes.add(hash);
+            if (!own.some((e) => e.action.type === 'oath.amend' && e.action.content_hash === hash)) {
+                recordProblems.push(`${handle}: no oath.amend entry commits to oath v${v}`);
+            }
+        }
+        // ...and no reserved oath-lifecycle leaf may be forged. A stranger's
+        // monitor is the trust anchor: an extra oath.swear, or an oath.amend
+        // committing to an oath that was never served, must fail verification.
+        own.forEach((e, i) => {
+            if (e.action.type === 'oath.swear' && (i !== 0 || e.action.content_hash !== v1Hash)) {
+                recordProblems.push(`${handle}: leaf with a forged/misplaced oath.swear (only leaf 0 may swear v1)`);
+            }
+            if (e.action.type === 'oath.amend' && !validAmendHashes.has(e.action.content_hash ?? '')) {
+                recordProblems.push(`${handle}: oath.amend commits to an oath version the ledger never served`);
+            }
+        });
+    }
+    checks.push({
+        name: 'sworn-record',
+        ok: recordProblems.length === 0,
+        detail: recordProblems.length === 0
+            ? 'every agent swore at its first leaf; every amendment logged'
+            : recordProblems.join('; '),
+    });
+    // 4. Tree heads: recompute every root, verify every signature (§5).
+    const leafHashes = leafLines.map((line) => leafHash(utf8Bytes(line)));
+    const headProblems = [];
+    let previousSize = 0;
+    heads.forEach((head, i) => {
+        try {
+            assertValidSth(head);
+            if (head.tree_size < previousSize)
+                throw new Error('tree size decreased');
+            previousSize = head.tree_size;
+            if (head.tree_size > leafHashes.length) {
+                throw new Error(`covers ${head.tree_size} leaves but only ${leafHashes.length} are known`);
+            }
+            const recomputed = bytesToHex(rootFromLeafHashes(leafHashes.slice(0, head.tree_size)));
+            if (recomputed !== head.root_hash) {
+                throw new Error(`root hash does not match the recomputed tree at size ${head.tree_size}`);
+            }
+            if (!sthPubkeys.some((pubkey) => verifySthSignature(head, pubkey))) {
+                throw new Error('signature does not verify against any accepted key');
+            }
+        }
+        catch (error) {
+            headProblems.push(`tree head ${i}: ${error.message}`);
+        }
+    });
+    if (leafLines.length > 0 && (heads.length === 0 || heads[heads.length - 1].tree_size !== leafLines.length)) {
+        headProblems.push('the latest tree head does not cover every entry (SPEC.md §5)');
+    }
+    checks.push({
+        name: 'tree-heads',
+        ok: headProblems.length === 0,
+        detail: headProblems.length === 0
+            ? `${heads.length} tree heads recomputed and signature-verified`
+            : headProblems.join('; '),
+    });
+    // 5. Consistency between every consecutive pair of tree heads (§6.2).
+    const consistencyProblems = [];
+    let pairs = 0;
+    for (let i = 1; i < heads.length; i++) {
+        const prev = heads[i - 1];
+        const next = heads[i];
+        if (next.tree_size > leafHashes.length || prev.tree_size > next.tree_size)
+            continue; // reported above
+        const ok = verifyConsistency({
+            oldSize: prev.tree_size,
+            newSize: next.tree_size,
+            oldRoot: hexToBytes(prev.root_hash),
+            newRoot: hexToBytes(next.root_hash),
+            path: consistencyPath(prev.tree_size, leafHashes.slice(0, next.tree_size)),
+        });
+        pairs++;
+        if (!ok) {
+            consistencyProblems.push(`tree heads ${i - 1} -> ${i} (sizes ${prev.tree_size} -> ${next.tree_size}) are not consistent: history was rewritten`);
+        }
+    }
+    checks.push({
+        name: 'consistency',
+        ok: consistencyProblems.length === 0,
+        detail: consistencyProblems.length === 0
+            ? `${pairs} consecutive pair(s) prove append-only history`
+            : consistencyProblems.join('; '),
+    });
+    return {
+        ok: checks.every((c) => c.ok),
+        source: data.source,
+        agents,
+        treeSize: leafLines.length,
+        checks,
+    };
+}
+function safeOathHash(doc) {
+    try {
+        return oathHash(doc);
+    }
+    catch {
+        return null;
+    }
+}
+/** Verify a local ledger directory (SPEC.md Appendix A). */
+export function verifyLocalLedger(dir) {
+    let data;
+    try {
+        const oathVersions = readOathVersions(dir);
+        const agent = oathVersions[0].agent;
+        data = {
+            source: dir,
+            leafLines: readLeafLines(dir),
+            heads: JSON.parse(readFileSync(join(dir, LEDGER_FILES.heads), 'utf8')),
+            // A local ledger's agent key doubles as its ledger key (§5).
+            sthPubkeys: oathVersions.map((doc) => doc.pubkey),
+            oathsByAgent: new Map([[agent, oathVersions]]),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            source: dir,
+            agents: [],
+            treeSize: 0,
+            checks: [{ name: 'files', ok: false, detail: `unreadable ledger: ${error.message}` }],
+        };
+    }
+    return verifyLedgerData(data);
+}
+/**
+ * Verify a remote public ledger over its read API (SPEC.md §11.2), starting
+ * from its discovery document. Entries beyond the latest tree head are
+ * within the merge delay and are not judged yet.
+ */
+export async function verifyRemoteLedger(url, options = {}) {
+    const f = options.fetch ?? fetch;
+    const base = url.replace(/\/+$/, '');
+    const get = async (path) => {
+        const response = await f(`${base}${path}`);
+        if (!response.ok)
+            throw new Error(`GET ${path} -> ${response.status}`);
+        return response.json();
+    };
+    try {
+        const discovery = (await get('/v0/ledger.json'));
+        const heads = (await get('/v0/sth/history'));
+        const covered = heads.length > 0 ? heads[heads.length - 1].tree_size : 0;
+        const leafLines = [];
+        for (let start = 0; start < covered; start += 1000) {
+            const page = (await get(`/v0/entries?start=${start}&end=${Math.min(start + 999, covered - 1)}`));
+            for (const row of page.entries) {
+                leafLines[row.leaf_index] = row.leaf_bytes;
+            }
+        }
+        const handles = new Set();
+        for (const line of leafLines) {
+            try {
+                const agent = JSON.parse(line).agent;
+                if (typeof agent === 'string')
+                    handles.add(agent);
+            }
+            catch {
+                /* reported by verifyLedgerData */
+            }
+        }
+        const oathsByAgent = new Map();
+        for (const handle of handles) {
+            const record = (await get(`/v0/agents/${handle}`));
+            oathsByAgent.set(handle, record.oath_versions);
+        }
+        return verifyLedgerData({
+            source: `${discovery.ledger} (${base})`,
+            leafLines,
+            heads,
+            sthPubkeys: [discovery.pubkey],
+            oathsByAgent,
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            source: base,
+            agents: [],
+            treeSize: 0,
+            checks: [{ name: 'files', ok: false, detail: `unreachable ledger: ${error.message}` }],
+        };
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@thehonestmachine/oath-sdk",
+  "version": "0.1.0",
+  "description": "The OATH developer surface: swear an oath, log entries, and maintain a verifiable local ledger on disk.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "homepage": "https://oath.sh",
+  "dependencies": {
+    "@thehonestmachine/oath-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aamir222686/oath.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "oath",
+    "ai-agents",
+    "accountability",
+    "transparency",
+    "merkle",
+    "certificate-transparency"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  LocalLedger,
+  LEDGER_FILES,
+  readOathVersions,
+  readLeafLines,
+  type EntryFields,
+  type AppendResult,
+} from './localLedger.js';
+export { RemoteLedger, type LedgerDiscovery, type SubmitResult } from './remote.js';
+export {
+  verifyLedgerData,
+  verifyLocalLedger,
+  verifyRemoteLedger,
+  type LedgerData,
+  type VerificationReport,
+  type CheckResult,
+} from './verify.js';

package/src/localLedger.ts

@@ -0,0 +1,255 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  assertValidAmendment,
+  assertValidOathDoc,
+  assertValidUnsignedOathDoc,
+  bytesToHex,
+  canonicalize,
+  edPublicKey,
+  leafBytesOf,
+  leafHash,
+  oathHash,
+  ProtocolError,
+  rootFromLeafHashes,
+  signEntry,
+  signOathDoc,
+  signSth,
+  SPEC_VERSION,
+  utf8Bytes,
+  type Action,
+  type Adjudication,
+  type Confession,
+  type Entry,
+  type OathDoc,
+  type SignedTreeHead,
+  type UnsignedEntry,
+  type UnsignedOathDoc,
+  type Verdict,
+} from '@thehonestmachine/oath-core';
+
+/** File layout per SPEC.md Appendix A. */
+export const LEDGER_FILES = {
+  oath: 'oath.json',
+  history: 'oath.history',
+  entries: 'entries.jsonl',
+  heads: 'heads.json',
+} as const;
+
+export interface EntryFields {
+  action: Action;
+  verdict: Verdict;
+  law_cited: number | null;
+  adjudication: Adjudication;
+  confession?: Confession;
+}
+
+export interface AppendResult {
+  entry: Entry;
+  head: SignedTreeHead;
+}
+
+/** RFC 3339 UTC now — Date#toISOString emits exactly the spec's format. */
+function defaultNow(): string {
+  return new Date().toISOString();
+}
+
+function historyPath(dir: string, version: number): string {
+  return join(dir, LEDGER_FILES.history, `v${version}.json`);
+}
+
+/**
+ * A local ledger (SPEC.md §4 storage note, Appendix A): the agent-operated,
+ * on-disk, offline-verifiable form of the OATH log. The agent's key doubles
+ * as the ledger key (§5).
+ */
+export class LocalLedger {
+  private constructor(
+    readonly dir: string,
+    private seed: string,
+    private readonly oathVersions: OathDoc[],
+    private readonly leafHashes: Uint8Array[],
+    private readonly heads: SignedTreeHead[],
+    private readonly ledgerName: string,
+    private readonly now: () => string,
+  ) {}
+
+  /**
+   * Take the oath: sign version 1, create the ledger directory, and log the
+   * `oath.swear` entry as leaf 0 (SPEC.md §2.4).
+   */
+  static swear(options: {
+    dir: string;
+    oath: UnsignedOathDoc;
+    seed: string;
+    ledgerName?: string;
+    now?: () => string;
+  }): LocalLedger {
+    const { dir, oath, seed } = options;
+    const now = options.now ?? defaultNow;
+    assertValidUnsignedOathDoc(oath);
+    if (oath.version !== 1) {
+      throw new ProtocolError('an agent swears at version 1; later versions are amendments (SPEC.md §9)');
+    }
+    if (oath.pubkey !== edPublicKey(seed)) {
+      throw new ProtocolError('oath pubkey does not match the signing seed');
+    }
+    if (existsSync(join(dir, LEDGER_FILES.oath))) {
+      throw new ProtocolError(`a ledger already exists at ${dir}`);
+    }
+    const doc = signOathDoc(oath, seed);
+    // Write oath.json LAST: it is the sentinel the swear/open guards key on
+    // (existsSync above, and open() reads it first). Everything else is
+    // written and the swear leaf appended before it, so a crash mid-write
+    // leaves a directory that a retried swear() cleanly overwrites rather
+    // than a half-built ledger that can be neither sworn nor opened.
+    mkdirSync(join(dir, LEDGER_FILES.history), { recursive: true });
+    writeFileSync(historyPath(dir, 1), canonicalize(doc) + '\n');
+    writeFileSync(join(dir, LEDGER_FILES.entries), '');
+    writeFileSync(join(dir, LEDGER_FILES.heads), '[]\n');
+    const ledger = new LocalLedger(
+      dir,
+      seed,
+      [doc],
+      [],
+      [],
+      options.ledgerName ?? `${doc.agent}.local`,
+      now,
+    );
+    const occurredAt = now();
+    ledger.append({
+      action: {
+        type: 'oath.swear',
+        summary: `Swore the oath of ${doc.agent}, version 1.`,
+        content_hash: oathHash(doc),
+        occurred_at: occurredAt,
+      },
+      verdict: 'compliant',
+      law_cited: null,
+      adjudication: { mode: 'machine', check: 'oath.swear' },
+    });
+    writeFileSync(join(dir, LEDGER_FILES.oath), canonicalize(doc) + '\n');
+    return ledger;
+  }
+
+  /** Open an existing ledger for appending. Verification is the monitor's job. */
+  static open(options: { dir: string; seed: string; now?: () => string }): LocalLedger {
+    const { dir, seed } = options;
+    const oathVersions = readOathVersions(dir);
+    const current = oathVersions[oathVersions.length - 1]!;
+    if (current.pubkey !== edPublicKey(seed)) {
+      throw new ProtocolError('seed does not match the current oath pubkey');
+    }
+    const leafHashes = readLeafLines(dir).map((line) => leafHash(utf8Bytes(line)));
+    const heads = JSON.parse(readFileSync(join(dir, LEDGER_FILES.heads), 'utf8')) as SignedTreeHead[];
+    const ledgerName = heads.length > 0 ? heads[heads.length - 1]!.ledger : `${current.agent}.local`;
+    return new LocalLedger(dir, seed, oathVersions, leafHashes, heads, ledgerName, options.now ?? defaultNow);
+  }
+
+  get currentOath(): OathDoc {
+    return this.oathVersions[this.oathVersions.length - 1]!;
+  }
+
+  get treeSize(): number {
+    return this.leafHashes.length;
+  }
+
+  latestHead(): SignedTreeHead | null {
+    return this.heads.length > 0 ? this.heads[this.heads.length - 1]! : null;
+  }
+
+  /**
+   * Sign and append an entry, then emit a fresh STH — the local ledger emits
+   * one per append so its contents are always presentable (SPEC.md §5).
+   */
+  append(fields: EntryFields): AppendResult {
+    const current = this.currentOath;
+    const unsigned: UnsignedEntry = {
+      spec_version: SPEC_VERSION,
+      agent: current.agent,
+      oath_version: current.version,
+      ...fields,
+      timestamp: this.now(),
+    };
+    if (fields.confession === undefined) delete (unsigned as Partial<UnsignedEntry>).confession;
+    const entry = signEntry(unsigned, this.seed);
+    const line = canonicalize(entry);
+    appendFileSync(join(this.dir, LEDGER_FILES.entries), line + '\n');
+    this.leafHashes.push(leafHash(utf8Bytes(line)));
+    const head = signSth(
+      {
+        ledger: this.ledgerName,
+        tree_size: this.leafHashes.length,
+        root_hash: bytesToHex(rootFromLeafHashes(this.leafHashes)),
+        timestamp: this.now(),
+      },
+      this.seed,
+    );
+    this.heads.push(head);
+    writeFileSync(join(this.dir, LEDGER_FILES.heads), JSON.stringify(this.heads, null, 2) + '\n');
+    return { entry, head };
+  }
+
+  /**
+   * Amend the oath (SPEC.md §9): sign the next version with the current key,
+   * write it, and log the `oath.amend` entry. For key rotation pass the new
+   * key's seed; future entries and tree heads are signed with it.
+   */
+  amend(next: UnsignedOathDoc, options: { summary: string; newSeed?: string }): AppendResult {
+    const signed = signOathDoc(next, this.seed);
+    assertValidAmendment(this.currentOath, signed);
+    const activeSeed = options.newSeed ?? this.seed;
+    if (signed.pubkey !== edPublicKey(activeSeed)) {
+      throw new ProtocolError('amended oath pubkey does not match the active seed (pass newSeed when rotating keys)');
+    }
+    // Write order matters for crash recovery. oath.json is the sentinel that
+    // readOathVersions keys its version loop on, so it goes LAST. First log
+    // the amend entry (still adjudicated under the PRIOR version — the last
+    // act of the old oath, §9), then the new history file, then oath.json.
+    // A crash before oath.json leaves an OPENABLE ledger at the prior version
+    // (with an orphan amend leaf a monitor will flag), never an un-openable
+    // one pointing at a version whose history file does not yet exist.
+    const result = this.append({
+      action: {
+        type: 'oath.amend',
+        summary: options.summary,
+        content_hash: oathHash(signed),
+        occurred_at: this.now(),
+      },
+      verdict: 'compliant',
+      law_cited: null,
+      adjudication: { mode: 'machine', check: 'oath.amend' },
+    });
+    writeFileSync(historyPath(this.dir, signed.version), canonicalize(signed) + '\n');
+    writeFileSync(join(this.dir, LEDGER_FILES.oath), canonicalize(signed) + '\n');
+    this.oathVersions.push(signed);
+    this.seed = activeSeed;
+    return result;
+  }
+}
+
+/** Read and structurally validate the oath version chain from disk. */
+export function readOathVersions(dir: string): OathDoc[] {
+  const currentRaw = readFileSync(join(dir, LEDGER_FILES.oath), 'utf8');
+  const current = JSON.parse(currentRaw) as unknown;
+  assertValidOathDoc(current);
+  const versions: OathDoc[] = [];
+  for (let v = 1; v <= current.version; v++) {
+    const doc = JSON.parse(readFileSync(historyPath(dir, v), 'utf8')) as unknown;
+    assertValidOathDoc(doc);
+    if (doc.version !== v) {
+      throw new ProtocolError(`${LEDGER_FILES.history}/v${v}.json contains version ${doc.version}`);
+    }
+    versions.push(doc);
+  }
+  if (canonicalize(versions[versions.length - 1]!) !== canonicalize(current)) {
+    throw new ProtocolError('oath.json does not match the latest history version');
+  }
+  return versions;
+}
+
+/** Read raw entry lines (the exact leaf bytes, newline-separated). */
+export function readLeafLines(dir: string): string[] {
+  const raw = readFileSync(join(dir, LEDGER_FILES.entries), 'utf8');
+  return raw === '' ? [] : raw.replace(/\n$/, '').split('\n');
+}