Domain: Thought — Function Reference

Decision trail domain (ζ concept). Provides immutable, hash-chained reasoning records linked to sessions and actions. Thoughts form a tree structure (via parentId). Hash chain integrity can be verified. Thoughts are write-once — linkThoughtToAction throws to enforce immutability.

MCP Tools Exposed

Exposed through unified controller. Key tool names: thought_record, thought_plan, thought_analysis, thought_decision, thought_reflection, thought_tree, thought_for_action, thought_verify_chain, thought_reasoning_trail.

Tool Name	Description	Key Inputs	Returns
thought_record	Record a generic thought	sessionId, thoughtType, content, contextId?, actionId?, parentId?	{ success, thought: { thoughtId, thoughtType, stepIndex, contentHash, chainHash } }
thought_plan	Record a plan thought	sessionId, planDescription, contextId?, actionId?, parentId?	Same as thought_record
thought_analysis	Record an analysis thought	sessionId, analysis, ...	Same
thought_decision	Record a decision	sessionId, decision, ...	Same
thought_reflection	Record a reflection	sessionId, reflection, ...	Same
thought_tree	Get thought tree for session	sessionId, includeContent?, includeChildren?	{ success, count, tree[] }
thought_for_action	Get thoughts linked to action	actionId: string	{ success, actionId, count, thoughts[] }
thought_verify_chain	Verify hash chain integrity	sessionId: string	{ success, valid, message, thoughtCount, brokenAt }
thought_reasoning_trail	Get full reasoning trail for action	actionId: string	{ success, actionId, hasReasoning, trailCount, trails[][] }

Core Functions

recordThought(sessionId, thoughtType, content, options)

Purpose: Write an immutable thought record to the database with hash chaining. Parameters: sessionId: string, thoughtType: string, content: string, options: { contextId?, actionId?, parentId? } Returns: Promise<{ success, thought: { thoughtId, thoughtType, stepIndex, contentHash (truncated), chainHash (truncated) } }> Side effects: INSERT to thoughts table via dbLogThought. Hash is computed by DB layer over content. Notes for rewrite: Thoughts are immutable once written. contentHash and chainHash are truncated to 16 chars + “…” in response for security.

recordPlan(sessionId, planDescription, options)

Purpose: Convenience wrapper calling recordThought with thoughtType = "plan". Returns: Same as recordThought.

recordAnalysis(sessionId, analysis, options)

Purpose: Convenience wrapper with thoughtType = "analysis".

recordDecision(sessionId, decision, options)

Purpose: Convenience wrapper with thoughtType = "decision".

recordReflection(sessionId, reflection, options)

Purpose: Convenience wrapper with thoughtType = "reflection".

linkThoughtToAction(thoughtId, actionId)

Purpose: Intentionally throws — thoughts are immutable and must be created with actionId upfront. Returns: Never. Always throws Error("Thoughts are immutable. Create with actionId from start."). Notes for rewrite: This enforces the append-only design. Do not implement mutable linking.

getThoughtTree(sessionId, options)

Purpose: Retrieve all thoughts for a session, build a parent-child tree, and return as nested structure. Parameters: sessionId: string, options: { includeContent?: boolean, includeChildren?: boolean } Returns: Promise<{ success, count, tree[] }> Notes for rewrite: Tree is built in-memory from flat list. Root thoughts (no parentId or parentId not in session) become top-level. Content is truncated to 100 chars unless includeContent = true. Children not nested unless includeChildren = true.

getThoughtsForAction(actionId)

Purpose: Get all thoughts linked to a specific action ID. Parameters: actionId: string Returns: Promise<{ success, actionId, count, thoughts[] }> Notes for rewrite: Content truncated to 200 chars.

verifyThoughtChain(sessionId)

Purpose: Verify the hash chain integrity across all thoughts in a session. Parameters: sessionId: string Returns: Promise<{ success, valid, message, thoughtCount, brokenAt: number|null }> Notes for rewrite: Delegates entirely to dbVerifyThoughtChain in db-gateway. The chain link logic is: each thought’s chainHash covers the previous thought’s hash. Any break indicates tampering.

getReasoningTrail(actionId)

Purpose: Build root-to-leaf paths from session thoughts leading to a specific action. Parameters: actionId: string Returns: Promise<{ success, actionId, hasReasoning, trailCount?, trails[][]? }> Notes for rewrite: Loads all session thoughts, then for each action-linked thought walks parentId links back to root. Each trail is an ordered path [root, ..., leaf]. Content truncated to 150 chars.

Database Operations

Operation	Query Pattern	Tables Used
Record thought	INSERT with hash chain	thoughts
Get thoughts by session	SELECT all for session, ORDER BY stepIndex	thoughts
Get thoughts by action	SELECT WHERE actionId	thoughts
Verify chain	Walk chain hashes	thoughts

Key Algorithms

In-Memory Tree Construction (getThoughtTree)

nodeMap = Map(thoughtId → { ...thought, children: [] })
for each thought:
  if thought.parentId in nodeMap:
    nodeMap[parentId].children.push(node)
  else:
    roots.push(node)
return roots.map(shapeNode)

Reasoning Trail (getReasoningTrail)

for each thought linked to actionId:
  path = []
  current = thought
  while current:
    path.unshift({ thoughtId, thoughtType, content[0..150], stepIndex })
    current = current.parentId
               ? allThoughts.find(t => t.thoughtId == current.parentId)
               : null
  trails.push(path)

thoughtType Values (from usage)

• plan — planning thoughts
• analysis — analytical reasoning
• decision — decision records
• reflection — retrospective thoughts
• Any string is accepted by recordThought directly

Content Truncation Rules

• getThoughtTree with includeContent=false: 100 chars + “…”
• getThoughtsForAction: 200 chars + “…”
• getReasoningTrail: 150 chars + “…”
• recordThought response contentHash/chainHash: 16 chars + “…”