# Context Module

The context module provides a blackboard-style communication mechanism for tools in the Wasot event processing pipeline. It allows tools to share information with each other without tight coupling.

## Overview

When processing Wasot documents, different tools may need to share information. For example, a document title processor might set a document name that an idea exporter later needs to reference. The context system enables this communication through a simple key-value store.

## ContextItem

The core data structure is `ContextItem`, which represents a single piece of context information:

```rust
pub struct ContextItem {
    pub key: String,
    pub value: Value,  // serde_json::Value
}
```

Values are stored as JSON to ensure they are:
- **Serializable**: Can be written to the event log
- **Human-readable**: Developers can inspect context values
- **Type-flexible**: Supports all JSON types (Object, Array, String, Number, Boolean, Null)

## Usage Examples

```rust
use crate::context::ContextItem;
use serde_json::json;

// Create simple context items
let doc_name = ContextItem::new("document-name".to_string(), json!("User Manual"));
let page_num = ContextItem::new("current-page".to_string(), json!(10));

// Create from any serializable type
let metadata = ContextItem::from_serializable("metadata".to_string(), MyStruct { 
    version: "1.0", 
    author: "Alice" 
})?;

// Retrieve typed values
let page: i32 = page_num.get_value()?;
let title: String = doc_name.get_value()?;
```

## Architecture Integration

The context system integrates with Wasot's event-driven architecture:

1. **Tools process blocks** and emit context put-events
2. **Context items flow** through the event stream
3. **Downstream tools access** the accumulated context
4. **Upsert semantics** allow overwriting keys (latest wins)

## Design Philosophy

See the comprehensive design document at [`docs/the_context.md`](../../docs/the_context.md) for:

- **Event-driven approach**: Why context uses events rather than direct state
- **Immutable data structures**: How the append-only log works
- **Tool communication patterns**: How tools coordinate through context
- **JSON serialization rationale**: Why values are stored as JSON

## Key Benefits

- **Decoupled communication**: Tools don't need direct references to each other
- **Event log integration**: Context changes are part of the document's event history
- **Memory efficient**: Uses Wasot's streaming architecture
- **Human readable**: Context values can be inspected and debugged easily