Domain: Merkle — Function Reference

Provides Merkle tree proof generation and verification for audit session integrity. Session actions are hashed and organized into a binary Merkle tree; root hash is stored in SQLite. Supports inclusion proof generation, verification, and full session audit. Instrumented with Prometheus-style metrics via a lazily loaded collector.

MCP Tools Exposed

Exposed through unified controller. Key tool names: merkle_finalize, merkle_root, merkle_proof, merkle_verify, merkle_attest, merkle_audit, merkle_diagnostics.

Tool Name	Description	Key Inputs	Returns
merkle_finalize	Build Merkle tree for session	sessionId: string	{ success, sessionId, rootHash, actionCount, treeDepth, durationMs, message }
merkle_root	Get session root info	sessionId: string	{ success, sessionId, rootHash, actionCount, thoughtCount, finalizedAt }
merkle_proof	Generate inclusion proof for action	sessionId, actionId	{ success, actionId, actionHash, stepIndex, proofPath[], rootHash, proofDepth, generationTimeMs }
merkle_verify	Verify action inclusion	sessionId, actionId	{ success, valid, actionId, actionHash, rootHash, verificationTimeMs, message }
merkle_attest	Get compact attestation	sessionId: string	{ success, attestation: { sessionId, merkleRoot, actionCount, timestamp, verificationMethod } }
merkle_audit	Full session audit (all actions)	sessionId: string	{ success, sessionId, rootHash, totalActions, verifiedCount, failedCount, integrity, auditTimeMs }
merkle_diagnostics	Get tree diagnostics	sessionId: string	{ success, diagnostics: { actionCount, treeDepth, estimatedHashComputations, rootHash, finalizedAt } }

Core Functions

finalizeSession(sessionId)

Purpose: Trigger Merkle tree construction for all actions in a session. Parameters: sessionId: string Returns: Promise<{ success, sessionId?, rootHash?, actionCount?, treeDepth?, durationMs?, message }> Side effects: Calls dbBuildMerkleTree(sessionId) which writes tree to DB; emits metrics for tree depth, action count, estimated hash computations.

getSessionRoot(sessionId)

Purpose: Retrieve the stored Merkle root for a finalized session. Parameters: sessionId: string Returns: Promise<{ success, sessionId?, rootHash?, actionCount?, thoughtCount?, finalizedAt? }> Notes for rewrite: Returns { success: false } if session not finalized — caller must merkle_finalize first.

generateProof(sessionId, actionId)

Purpose: Generate a Merkle inclusion proof (sibling hash path) for a specific action. Parameters: sessionId: string, actionId: string Returns: Promise<{ success, sessionId, actionId, actionHash, stepIndex, proofPath[], rootHash, proofDepth, generationTimeMs }> Notes for rewrite: proofPath entries have level, siblingHash (first 16 chars + “…”), isLeftSibling. Full hash not exposed in response — truncated for security.

verifyAction(sessionId, actionId)

Purpose: Retrieve inclusion proof and verify it against the stored root hash. Parameters: sessionId: string, actionId: string Returns: Promise<{ success, valid, actionId, actionHash, rootHash, verificationTimeMs, message }> Notes for rewrite: Calls verifyInclusionProof(actionHash, proof, rootHash) from db-gateway. This is a pure cryptographic re-computation.

getAttestation(sessionId)

Purpose: Return a compact attestation record for external sharing. Parameters: sessionId: string Returns: Promise<{ success, attestation: { sessionId, merkleRoot, actionCount, timestamp, verificationMethod } }> Notes for rewrite: verificationMethod is the literal string "SHA256(LEFT || RIGHT)" — documents the hash algorithm.

auditSession(sessionId)

Purpose: Walk all actions in a session and verify each inclusion proof. Parameters: sessionId: string Returns: Promise<{ success, sessionId, rootHash, totalActions, verifiedCount, failedCount, integrity: 'FULL'|'COMPROMISED', auditTimeMs }> Notes for rewrite: Loads up to 10,000 actions. integrity = 'FULL' only if failedCount === 0.

getMerkleDiagnostics(sessionId)

Purpose: Return tree statistics without running verification. Parameters: sessionId: string Returns: Promise<{ success, diagnostics: { actionCount, treeDepth, estimatedHashComputations, rootHash, finalizedAt } }> Notes for rewrite: treeDepth = ceil(log2(actionCount)) + 1. estimatedHashComputations = actions * 2 - 1.

Database Operations

Operation	Query Pattern	Tables Used
Build Merkle tree	Compute hashes + INSERT tree	audit_actions, merkle_nodes, merkle_roots
Get root	SELECT by sessionId	merkle_roots
Get inclusion proof	SELECT tree path	merkle_nodes, audit_actions
Get actions by session	SELECT all in session	audit_actions

All crypto operations delegated to db-gateway.js: dbBuildMerkleTree, dbGetMerkleRoot, dbGetInclusionProof, verifyInclusionProof.

Key Algorithms

Merkle Tree Construction (in db-gateway, referenced here)

leaves = sorted action hashes for session
while len(leaves) > 1:
  if len(leaves) is odd: duplicate last leaf
  pairs = zip(leaves[0::2], leaves[1::2])
  leaves = [SHA256(left + right) for left, right in pairs]
root = leaves[0]

Hash function: SHA-256. Concatenation: SHA256(LEFT_HASH || RIGHT_HASH).

Tree Depth Calculation

treeDepth = ceil(log2(actionCount)) + 1

Estimated Hash Computations

estimatedHashComputations = actionCount * 2 - 1
(leaf hashes + internal node hashes)

Metrics Instrumentation

Lazily loads metrics collector via dynamic import. Falls back to no-op metrics object if collector unavailable. Metrics emitted:

• ams_merkle_proof_generation_seconds — histogram by tree_depth label
• ams_merkle_verification_seconds — histogram by result label
• ams_merkle_verifications_total — counter by result
• ams_merkle_proofs_generated_total — counter by status
• ams_merkle_tree_depth — gauge by session_id
• ams_merkle_action_count — gauge by session_id
• ams_merkle_hash_computations_total — counter
• ams_merkle_audit_actions_total — counter by integrity