@kashscript/hudhud 0.1.0

package/src/exception/index.ts

@@ -0,0 +1,244 @@
+// ============================================================================
+// @kashscript/hudhud/exception — signed exception-classification dataset
+// ----------------------------------------------------------------------------
+// The appreciating record of WHERE frontier models fail on real inputs and HOW
+// a human resolved it. Two invariants make it an asset, not a log line:
+//   1. MANDATORY — `failureClass` is required with NO "unclassified" member and
+//      NO default; `assertFailureClass` is the runtime belt (an untyped caller
+//      still cannot resolve without classifying).
+//   2. SIGNED — the operator's Ed25519 key signs the record over its EXACT
+//      bytes (`id` + `timestampIso` minted INTO the signed payload).
+// Ported from the oreoasis-core-host engine (M5); the DST is neutralized, the
+// error reuses hudhud's `ExceptionClassificationError`, id generation inlined.
+// ============================================================================
+
+import { signEvent, verifyEvent } from "@kashscript/identity-core";
+import { ExceptionClassificationError } from "../errors";
+
+/** The failure classes. No "unclassified": classification is mandatory. */
+export const FAILURE_CLASSES = ["judgment", "gap-filling", "ambiguous"] as const;
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+
+/** DST so a classification signature can't replay as a ledger/attestation sig.
+ *  Neutral default; a venture passes its own DST at swap for wire-compat. */
+export const HUDHUD_EXCEPTION_CLASSIFICATION_DST = "kash-exception-classification-v1\n" as const;
+export const EXCEPTION_CLASSIFICATION_SCHEMA_VERSION = "exception-classification/1" as const;
+const SIGN_HEADER = { kind: "exception-classification/1" } as const;
+
+let lastIdMicros = 0;
+function newRecordId(): string {
+  let micros = Date.now() * 1000;
+  if (micros <= lastIdMicros) micros = lastIdMicros + 1;
+  lastIdMicros = micros;
+  const rand = crypto.getRandomValues(new Uint8Array(6));
+  let hex = "";
+  for (const b of rand) hex += b.toString(16).padStart(2, "0");
+  return `exc_${micros.toString(36)}_${hex}`;
+}
+
+/** The mandatory gate — throws `ExceptionClassificationError` if `value` is
+ *  absent/empty or not one of the classes. NOT merely the TS type. */
+export function assertFailureClass(value: unknown): asserts value is FailureClass {
+  if (value === undefined || value === null || value === "") {
+    throw new ExceptionClassificationError(
+      `FAILURE_CLASS_REQUIRED — an exception cannot be resolved without a failureClass (one of ${FAILURE_CLASSES.join(" | ")})`,
+    );
+  }
+  if (!(FAILURE_CLASSES as ReadonlyArray<string>).includes(value as string)) {
+    throw new ExceptionClassificationError(
+      `FAILURE_CLASS_INVALID — failureClass must be one of ${FAILURE_CLASSES.join(" | ")} (got ${String(value)})`,
+    );
+  }
+}
+
+export interface ExceptionClassificationInput {
+  readonly failureClass: FailureClass;
+  readonly failureTag: string;
+  readonly workflowId: string;
+  readonly sopVersion: string;
+  readonly inputRef: string;
+  readonly contentHash: string;
+  readonly model: string;
+  readonly modelVersion: string;
+  readonly resolutionSummary: string;
+  readonly resolutionActionRefs: ReadonlyArray<string>;
+}
+
+export interface ClassificationSignedEnvelope {
+  readonly alg: "ed25519";
+  readonly sig: string;
+  readonly dst: string;
+  readonly kid: string;
+}
+
+export interface ExceptionClassificationRecord {
+  readonly id: string;
+  readonly schemaVersion: string;
+  readonly timestampIso: string;
+  readonly workflowId: string;
+  readonly sopVersion: string;
+  readonly inputRef: string;
+  readonly contentHash: string;
+  readonly model: string;
+  readonly modelVersion: string;
+  readonly failureClass: FailureClass;
+  readonly failureTag: string;
+  readonly operatorDid: string;
+  readonly resolutionSummary: string;
+  readonly resolutionActionRefs: ReadonlyArray<string>;
+  readonly escalationId: string | null;
+  readonly signoffLedgerStepIndex: number | null;
+  readonly signedEnvelope: ClassificationSignedEnvelope;
+}
+
+type UnsignedClassification = Omit<ExceptionClassificationRecord, "signedEnvelope">;
+function unsignedOf(record: ExceptionClassificationRecord): UnsignedClassification {
+  const { signedEnvelope: _drop, ...rest } = record;
+  return rest;
+}
+
+/** Mint + sign a classification record (id/timestamp minted into the signed
+ *  payload). Throws the mandatory gate if `failureClass` is missing/invalid. */
+export async function buildSignedClassification(
+  input: ExceptionClassificationInput,
+  operator: { readonly did: string; readonly privateKey: Uint8Array },
+  link: { readonly escalationId?: string | null; readonly signoffLedgerStepIndex?: number | null } = {},
+): Promise<ExceptionClassificationRecord> {
+  assertFailureClass(input.failureClass);
+  const unsigned: UnsignedClassification = {
+    id: newRecordId(),
+    schemaVersion: EXCEPTION_CLASSIFICATION_SCHEMA_VERSION,
+    timestampIso: new Date().toISOString(),
+    workflowId: input.workflowId,
+    sopVersion: input.sopVersion,
+    inputRef: input.inputRef,
+    contentHash: input.contentHash,
+    model: input.model,
+    modelVersion: input.modelVersion,
+    failureClass: input.failureClass,
+    failureTag: input.failureTag,
+    operatorDid: operator.did,
+    resolutionSummary: input.resolutionSummary,
+    resolutionActionRefs: [...input.resolutionActionRefs],
+    escalationId: link.escalationId ?? null,
+    signoffLedgerStepIndex: link.signoffLedgerStepIndex ?? null,
+  };
+  const signed = await signEvent(SIGN_HEADER, unsigned, operator.privateKey, {
+    dst: HUDHUD_EXCEPTION_CLASSIFICATION_DST,
+    encoding: "hex",
+    kid: operator.did,
+  });
+  return {
+    ...unsigned,
+    signedEnvelope: { alg: "ed25519", sig: signed.sig, dst: HUDHUD_EXCEPTION_CLASSIFICATION_DST, kid: operator.did },
+  };
+}
+
+/** Verify a record's operator signature. Returns false on a well-formed mismatch. */
+export async function verifyClassificationSignature(
+  record: ExceptionClassificationRecord,
+  operatorPublicKey: Uint8Array,
+): Promise<boolean> {
+  return verifyEvent(
+    {
+      header: SIGN_HEADER,
+      body: unsignedOf(record),
+      signature: {
+        alg: "ed25519",
+        sig: record.signedEnvelope.sig,
+        dst: record.signedEnvelope.dst,
+        encoding: "hex",
+        kid: record.signedEnvelope.kid,
+      },
+    },
+    operatorPublicKey,
+  );
+}
+
+// ── Store (append-only) ────────────────────────────────────────────────────
+
+export interface ExceptionClassificationStore {
+  append(record: ExceptionClassificationRecord): Promise<void>;
+  history(): Promise<ReadonlyArray<ExceptionClassificationRecord>>;
+  latest(): Promise<ExceptionClassificationRecord | null>;
+  byWorkflow(workflowId: string): Promise<ReadonlyArray<ExceptionClassificationRecord>>;
+}
+
+export class InMemoryExceptionClassificationStore implements ExceptionClassificationStore {
+  private readonly rows: ExceptionClassificationRecord[] = [];
+  async append(record: ExceptionClassificationRecord): Promise<void> {
+    this.rows.push(record);
+  }
+  async history(): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+    return [...this.rows];
+  }
+  async latest(): Promise<ExceptionClassificationRecord | null> {
+    return this.rows.length === 0 ? null : this.rows[this.rows.length - 1]!;
+  }
+  async byWorkflow(workflowId: string): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+    return this.rows.filter((r) => r.workflowId === workflowId);
+  }
+}
+
+// ── Export + stats ─────────────────────────────────────────────────────────
+
+export const EXCEPTION_DATASET_FORMAT_VERSION = "kash-exception-dataset/1" as const;
+
+export interface ExceptionClassificationDatasetExport {
+  readonly formatVersion: string;
+  readonly exportedAtIso: string;
+  readonly count: number;
+  readonly records: ReadonlyArray<ExceptionClassificationRecord>;
+}
+
+/** Bundle the dataset for hand-off (records carry their own signatures). */
+export function exportExceptionClassificationDataset(
+  records: ReadonlyArray<ExceptionClassificationRecord>,
+  exportedAtIso: string = new Date().toISOString(),
+): ExceptionClassificationDatasetExport {
+  return { formatVersion: EXCEPTION_DATASET_FORMAT_VERSION, exportedAtIso, count: records.length, records: [...records] };
+}
+
+export interface WorkflowMonthCount {
+  readonly workflowId: string;
+  readonly month: string;
+  readonly count: number;
+}
+
+export interface ExceptionClassificationStats {
+  readonly total: number;
+  readonly classMix: Record<FailureClass, number>;
+  readonly perWorkflow: ReadonlyArray<{ readonly workflowId: string; readonly count: number }>;
+  readonly perWorkflowOverTime: ReadonlyArray<WorkflowMonthCount>;
+}
+
+function emptyClassMix(): Record<FailureClass, number> {
+  const mix = {} as Record<FailureClass, number>;
+  for (const c of FAILURE_CLASSES) mix[c] = 0;
+  return mix;
+}
+
+/** Class mix + per-workflow (+ over-time) exception counts (the rate numerator). */
+export function computeExceptionClassificationStats(
+  records: ReadonlyArray<ExceptionClassificationRecord>,
+): ExceptionClassificationStats {
+  const classMix = emptyClassMix();
+  const perWorkflow = new Map<string, number>();
+  const perWfMonth = new Map<string, number>();
+  for (const r of records) {
+    classMix[r.failureClass] += 1;
+    perWorkflow.set(r.workflowId, (perWorkflow.get(r.workflowId) ?? 0) + 1);
+    const key = `${r.workflowId} ${r.timestampIso.slice(0, 7)}`;
+    perWfMonth.set(key, (perWfMonth.get(key) ?? 0) + 1);
+  }
+  const perWorkflowArr = [...perWorkflow.entries()]
+    .map(([workflowId, count]) => ({ workflowId, count }))
+    .sort((a, b) => (a.workflowId < b.workflowId ? -1 : 1));
+  const perWorkflowOverTime = [...perWfMonth.entries()]
+    .map(([key, count]) => {
+      const [workflowId, month] = key.split(" ");
+      return { workflowId: workflowId!, month: month!, count };
+    })
+    .sort((a, b) => (a.workflowId === b.workflowId ? (a.month < b.month ? -1 : 1) : a.workflowId < b.workflowId ? -1 : 1));
+  return { total: records.length, classMix, perWorkflow: perWorkflowArr, perWorkflowOverTime };
+}

package/src/identity/index.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// @kashscript/hudhud/identity — the accountable-identity gate (MCP OAuth 2.1)
+// ----------------------------------------------------------------------------
+// Replaces Oreoasis's bespoke HS256 / sovereign-session auth with
+// `@kashscript/identity-server` agent tokens (RFC 9068 + 8707 + 8693): the
+// runtime accepts an audience-bound, agent→owner-delegated access token, and
+// extracts the accountable actor `{ owner, agent }` for the ledger. The bespoke
+// JWT + revocation paths are deleted; revocation, if a venture needs it, is a
+// venture-side store. `AUDIENCE_MISMATCH` covers the closeout-aud-revocation
+// behaviour.
+// ============================================================================
+
+import { verifyAgentToken } from "@kashscript/identity-server";
+import type { Jwks } from "@kashscript/identity-server";
+
+/** The delegation the accountable identity carries: the agent acting for the owner. */
+export interface AccountableActor {
+  /** The resource owner — a did:kash root (the token `sub`). */
+  readonly owner: string;
+  /** The delegated agent — a did:kash (the token `act.sub`). */
+  readonly agent: string;
+}
+
+export type AccountableIdentityReason =
+  | "MALFORMED_TOKEN"
+  | "MALFORMED_CLAIMS"
+  | "UNSUPPORTED_ALG"
+  | "UNSUPPORTED_TOKEN_TYPE"
+  | "KEY_NOT_FOUND"
+  | "SIGNATURE_INVALID"
+  | "EXPIRED"
+  | "NOT_YET_VALID"
+  | "ISSUER_MISMATCH"
+  | "AUDIENCE_MISMATCH"
+  | "MISSING_OWNER_BINDING";
+
+export interface AccountableIdentityResult {
+  readonly ok: boolean;
+  readonly reason: AccountableIdentityReason | null;
+  /** The `{ owner, agent }` binding — present whenever the signature verified. */
+  readonly actor: AccountableActor | null;
+  /** The token's granted scope, if any. */
+  readonly scope: string | null;
+}
+
+export interface VerifyAccountableIdentityOptions {
+  /** RFC 8707: this runtime's canonical resource URI. REQUIRED. */
+  readonly expectedAudience: string;
+  readonly expectedIssuer?: string;
+  /** Resolve the signer key by `kid` from this JWKS (else self-certifying did:kash). */
+  readonly jwks?: Jwks;
+  readonly nowSec?: number;
+  readonly clockSkewSeconds?: number;
+}
+
+/**
+ * Verify an agent access token and extract the accountable actor. The runtime
+ * uses `actor.agent` as the ledger actor DID for autonomous actions and
+ * `actor.owner` as the delegating principal.
+ */
+export async function verifyAccountableIdentity(
+  token: string,
+  opts: VerifyAccountableIdentityOptions,
+): Promise<AccountableIdentityResult> {
+  const res = await verifyAgentToken(token, {
+    expectedAudience: opts.expectedAudience,
+    ...(opts.expectedIssuer !== undefined ? { expectedIssuer: opts.expectedIssuer } : {}),
+    ...(opts.jwks !== undefined ? { jwks: opts.jwks } : {}),
+    ...(opts.nowSec !== undefined ? { nowSec: opts.nowSec } : {}),
+    ...(opts.clockSkewSeconds !== undefined ? { clockSkewSeconds: opts.clockSkewSeconds } : {}),
+  });
+
+  const scope = typeof res.claims?.scope === "string" ? res.claims.scope : null;
+  if (!res.ok) {
+    // audit r1 F6: never hand back a consumable actor from a FAILED verification.
+    // identity-server still surfaces `ownerBinding` on post-signature failures
+    // (expired / wrong-audience) for logging, but the runtime must not attribute
+    // ledger rows to a binding whose token is invalid — make misuse unrepresentable.
+    return { ok: false, reason: res.reason, actor: null, scope };
+  }
+  return { ok: true, reason: null, actor: res.ownerBinding, scope };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// ============================================================================
+// @kashscript/hudhud — the Agent Protocol (accountable agent runtime)
+// ----------------------------------------------------------------------------
+// The generic, venture-neutral engine lifted from the oreoasis-core-host (M5 of
+// the Manifestation): SOP compilation, MCP governance (allowlist + circuit
+// breaker + PII redaction), scope gating, a signed action ledger + chain anchor
+// (on @kashscript/attest), exception classification, work certificates
+// (AIUC-1/DSSE), a DID registry, an identity gate (identity-server agent
+// tokens), and the neuron-backed execution runtime. SOP CONTENT, fixtures,
+// routes, storage schemas, and text UIs stay venture-side (guard b).
+//
+// Subpath entries (`./errors`, `./sop`, `./mcp`, `./privacy`, `./scope`,
+// `./ledger`, `./anchor`, `./exception`, `./certificate`, `./did-registry`,
+// `./identity`, `./runtime`, `./adapters/prisma`) mirror these modules; this
+// root barrel re-exports the whole non-adapter surface. The durable Prisma
+// adapters are import-gated behind `@kashscript/hudhud/adapters/prisma`.
+// ============================================================================
+
+export * from "./errors";
+export * from "./sop";
+export * from "./privacy";
+export * from "./mcp";
+export * from "./scope";
+export * from "./ledger";
+export * from "./anchor";
+export * from "./exception";
+export * from "./certificate";
+export * from "./did-registry";
+export * from "./identity";
+export * from "./runtime";
+
+/** The hudhud protocol/package version (M5 initial cut). */
+export const HUDHUD_VERSION = "0.1.0" as const;

package/src/ledger/event-schema.ts

@@ -0,0 +1,61 @@
+// ============================================================================
+// @kashscript/hudhud/ledger — closed-vocabulary payloadMutation schema
+// ----------------------------------------------------------------------------
+// The ledger's forensic value depends on a CLOSED event vocabulary: an
+// unconstrained payload would chain-hash any JSON. Every accepted
+// payloadMutation validates against this discriminated union before hashing.
+// Extending is APPEND-ONLY — never repurpose an existing `event` discriminator
+// (audit pipelines key on it). Ported from the oreoasis-core-host engine (M5);
+// the venture-specific error-code regex is relaxed to a neutral non-empty string.
+// ============================================================================
+
+import { z } from "zod";
+
+const NonNegBigInt = z.union([z.bigint(), z.string().regex(/^\d+$/)]);
+
+const SessionBootstrap = z.object({ event: z.literal("session.bootstrap"), sopId: z.string().min(1) });
+const ToolInvoked = z.object({ event: z.literal("tool.invoked"), tool: z.string().min(1), durationMs: z.number().int().nonnegative() });
+const ToolFailed = z.object({ event: z.literal("tool.failed"), tool: z.string().min(1), errorCode: z.string().min(1), errorMessage: z.string().min(1).optional() });
+const BudgetExhausted = z.object({ event: z.literal("budget.exhausted"), spentPaise: NonNegBigInt });
+const SessionSettled = z.object({ event: z.literal("session.settled"), totalSpentPaise: NonNegBigInt });
+const SessionFailedAudit = z.object({ event: z.literal("session.failed_audit"), reason: z.string().min(1) });
+const SessionProcessCrashed = z.object({ event: z.literal("session.process_crashed"), signal: z.string().min(1).optional() });
+const CacheCheckpoint = z.object({
+  event: z.literal("cache.checkpoint"),
+  flushedAtIso: z.string().min(1),
+  lifecycleState: z.enum(["NOT_STARTED", "RUNNING", "SETTLED", "FAILED_AUDIT", "BUDGET_EXHAUSTED", "PROCESS_CRASHED"]).optional(),
+  computeBudgetPaise: NonNegBigInt.optional(),
+  slotKeyPrefix: z.string().min(1),
+});
+
+/** Empty mutation — the bare `{}` object is a valid Empty-track value. */
+const EmptyMutation = z.object({}).strict();
+
+/** Every accepted event type. Unknown `event` discriminators are rejected, as
+ *  are well-formed objects missing `event` UNLESS they're the empty `{}`. */
+export const LedgerEventSchema = z.union([
+  EmptyMutation,
+  z.discriminatedUnion("event", [
+    SessionBootstrap,
+    ToolInvoked,
+    ToolFailed,
+    BudgetExhausted,
+    SessionSettled,
+    SessionFailedAudit,
+    SessionProcessCrashed,
+    CacheCheckpoint,
+  ]),
+]);
+
+export type LedgerEvent = z.infer<typeof LedgerEventSchema>;
+
+export const KNOWN_LEDGER_EVENTS = [
+  "session.bootstrap",
+  "tool.invoked",
+  "tool.failed",
+  "budget.exhausted",
+  "session.settled",
+  "session.failed_audit",
+  "session.process_crashed",
+  "cache.checkpoint",
+] as const;

package/src/ledger/index.ts

@@ -0,0 +1,22 @@
+// @kashscript/hudhud/ledger — the signed action ledger (write side).
+// The store + mutex + ForensicLedgerService live here; the row shapes, the
+// Ed25519 sign/verify, the forensic scan, and the DID registry are attest's
+// (M1 seed) and are re-exported so ventures reach the whole ledger surface
+// through hudhud.
+
+export * from "./store";
+export * from "./mutex";
+export * from "./writer";
+export * from "./event-schema";
+
+// Re-export attest's ledger crypto surface (seeded from the same Oreoasis files).
+// The DID registry lives at `@kashscript/hudhud/did-registry` (not re-exported
+// here, to avoid a same-name overlap in the top-level barrel).
+export {
+  OREOASIS_LEDGER_DST,
+  LedgerSignatureError,
+  signLedgerBlock,
+  verifyLedgerSignature,
+  forensicConsistencyScan,
+} from "@kashscript/attest";
+export type { LedgerSignaturePayload, ForensicScanReport } from "@kashscript/attest";

package/src/ledger/mutex.ts

@@ -0,0 +1,37 @@
+// ============================================================================
+// @kashscript/hudhud/ledger — per-key async mutex
+// ----------------------------------------------------------------------------
+// Serializes async sections keyed on a string (the ledger sessionId), closing
+// the resolvePreviousBlockHash → appendBlock race two concurrent appends on the
+// same session would otherwise hit. Ported verbatim from the oreoasis-core-host
+// engine (M5).
+// ============================================================================
+
+export class SessionMutex {
+  private readonly tails = new Map<string, Promise<unknown>>();
+
+  /** Run `fn` while holding the mutex for `key`. Other acquirers for the same
+   *  key queue behind this call. */
+  public async run<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const prior = this.tails.get(key) ?? Promise.resolve();
+    let release: (value: void) => void = () => {};
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    this.tails.set(key, gate);
+    try {
+      await prior;
+      return await fn();
+    } finally {
+      if (this.tails.get(key) === gate) {
+        this.tails.delete(key);
+      }
+      release();
+    }
+  }
+
+  /** Number of distinct keys currently locked. */
+  public activeKeyCount(): number {
+    return this.tails.size;
+  }
+}

package/src/ledger/store.ts

@@ -0,0 +1,86 @@
+// ============================================================================
+// @kashscript/hudhud/ledger — append-only ledger store (write side)
+// ----------------------------------------------------------------------------
+// The write-side store the ForensicLedgerService appends to. The row shapes +
+// the sign/verify/forensic-scan primitives live in `@kashscript/attest` (M1
+// seed); this module ships the store interface + an in-memory reference +
+// `resolvePreviousBlockHash`. A Prisma adapter ships at `./adapters/prisma`.
+// Ported from the oreoasis-core-host engine (M5).
+// ============================================================================
+
+import { GENESIS_PREV_HASH } from "@kashscript/attest";
+import type { LedgerBlockInput, LedgerBlockRecord } from "@kashscript/attest";
+
+export type { LedgerBlockInput, LedgerBlockRecord };
+
+export interface LedgerStore {
+  appendBlock(input: LedgerBlockInput): Promise<LedgerBlockRecord>;
+  latestBlockForSession(sessionId: string): Promise<LedgerBlockRecord | null>;
+  countBlocksForSession(sessionId: string): Promise<number>;
+  /** Every row for `sessionId` ordered by stepIndex — MUST NOT skip rows (the
+   *  forensic scan's whole job is to detect missing/forged entries). */
+  listBlocksForSession(sessionId: string): Promise<ReadonlyArray<LedgerBlockRecord>>;
+}
+
+/** In-memory store keyed by sessionId. Concurrent same-session appends are
+ *  serialized by the JS event loop + the (sessionId, stepIndex) uniqueness check. */
+export class InMemoryLedgerStore implements LedgerStore {
+  private readonly bySession = new Map<string, LedgerBlockRecord[]>();
+  private nextLocalId = 1;
+
+  async appendBlock(input: LedgerBlockInput): Promise<LedgerBlockRecord> {
+    const existing = this.bySession.get(input.sessionId) ?? [];
+    if (existing.some((b) => b.stepIndex === input.stepIndex)) {
+      throw new Error(`LEDGER_DUPLICATE_STEP: (sessionId=${input.sessionId}, stepIndex=${input.stepIndex})`);
+    }
+    const record: LedgerBlockRecord = {
+      ...input,
+      payloadMutation: { ...input.payloadMutation },
+      emittedAt: new Date().toISOString(),
+      localId: this.nextLocalId++,
+    };
+    existing.push(record);
+    existing.sort((a, b) => a.stepIndex - b.stepIndex);
+    this.bySession.set(input.sessionId, existing);
+    return record;
+  }
+
+  async latestBlockForSession(sessionId: string): Promise<LedgerBlockRecord | null> {
+    const list = this.bySession.get(sessionId);
+    if (!list || list.length === 0) return null;
+    return list[list.length - 1]!;
+  }
+
+  async countBlocksForSession(sessionId: string): Promise<number> {
+    return (this.bySession.get(sessionId) ?? []).length;
+  }
+
+  async listBlocksForSession(sessionId: string): Promise<ReadonlyArray<LedgerBlockRecord>> {
+    const list = this.bySession.get(sessionId);
+    if (list === undefined) return [];
+    return list.map((row) => ({ ...row, payloadMutation: { ...row.payloadMutation } }));
+  }
+
+  /** TEST-ONLY: splice a forged row bypassing the uniqueness + ordering
+   *  invariants, so the forensic scan can be exercised against a corrupt chain.
+   *  Production callers MUST NOT use this. */
+  unsafeInsertForgedRow(record: LedgerBlockRecord): void {
+    const existing = this.bySession.get(record.sessionId) ?? [];
+    existing.push({ ...record, payloadMutation: { ...record.payloadMutation } });
+    existing.sort((a, b) => a.stepIndex - b.stepIndex);
+    this.bySession.set(record.sessionId, existing);
+  }
+}
+
+/** Resolve the previous block hash for the next insert into `sessionId`.
+ *  Genesis (stepIndex 0) → GENESIS_PREV_HASH; else the prior row's currentHash. */
+export async function resolvePreviousBlockHash(
+  store: LedgerStore,
+  sessionId: string,
+): Promise<{ previousBlockHash: string; nextStepIndex: number }> {
+  const latest = await store.latestBlockForSession(sessionId);
+  if (latest === null) {
+    return { previousBlockHash: GENESIS_PREV_HASH, nextStepIndex: 0 };
+  }
+  return { previousBlockHash: latest.currentTransactionBlockHash, nextStepIndex: latest.stepIndex + 1 };
+}