> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Journal Store and Audit System
Relevant source files
The following files were used as context for generating this wiki page:
* crates/palyra-daemon/src/application/mod.rs
* crates/palyra-daemon/src/gateway/runtime.rs
* crates/palyra-daemon/src/journal.rs
* crates/palyra-daemon/src/lib.rs
* crates/palyra-daemon/src/orchestrator.rs
* crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs
* crates/palyra-daemon/src/transport/http/router.rs
* crates/palyra-daemon/tests/golden/current\_state\_inventory.json
* crates/palyra-daemon/tests/golden/run\_tape\_basic.json
The Journal Store is the central persistence layer of the Palyra daemon, providing a durable, tamper-evident record of all system activity. It manages the lifecycle of agent runs, tool executions, memory items, and security approvals using a SQLite backend configured for high concurrency and auditability.
## System Architecture and Storage Model
The `JournalStore` [crates/palyra-daemon/src/journal.rs#7-12](http://crates/palyra-daemon/src/journal.rs#7-12) encapsulates a single SQLite database connection. It operates in **Write-Ahead Logging (WAL)** mode with foreign key constraints enabled to ensure data integrity and performance under concurrent access [crates/palyra-daemon/src/journal.rs#6-9](http://crates/palyra-daemon/src/journal.rs#6-9).
### Data Flow: Natural Language to Code Entities
The following diagram illustrates how high-level system concepts (Natural Language Space) map to specific implementation entities (Code Entity Space) within the Journal subsystem.
**Concept to Code Mapping**
```mermaid theme={null}
graph TD
subgraph "Natural Language Space"
A["Audit Log"]
B["Session Memory"]
C["Agent Tape"]
D["Health Check"]
end
subgraph "Code Entity Space (palyra-daemon)"
A --> E["JournalStore::append_event_blocking"]
B --> F["MemoryItemRecord"]
C --> G["OrchestratorSessionTranscriptRecord"]
D --> H["JournalHealthReport"]
E --> I[("SQLite (WAL Mode)")]
F --> I
G --> I
H --> J["state_health.rs"]
end
I --> K["SHA-256 Hash Chain"]
J --> L["JournalHashChainVerificationReport"]
```
**Sources:** [crates/palyra-daemon/src/journal.rs#1-20](http://crates/palyra-daemon/src/journal.rs#1-20), [crates/palyra-daemon/src/gateway/runtime.rs#49-53](http://crates/palyra-daemon/src/gateway/runtime.rs#49-53)
## Tamper-Evidence and Hash Chaining
Palyra implements a cryptographic hash chain to make the audit log tamper-evident. When `hash_chain_enabled` is active, every event is linked to its predecessor [crates/palyra-daemon/src/journal.rs#11-15](http://crates/palyra-daemon/src/journal.rs#11-15).
1. **Identity Fields**: Includes event sequence, type, and actor metadata.
2. **Payload**: The sanitized JSON data of the event.
3. **Hash Calculation**: `hash = SHA-256(prev_hash | identity_fields | payload)` [crates/palyra-daemon/src/journal.rs#12-14](http://crates/palyra-daemon/src/journal.rs#12-14).
Verification is surfaced via the `JournalHealthReport`, which includes a `JournalHashChainVerificationReport` to detect if any historical records have been modified or deleted [crates/palyra-daemon/src/gateway/runtime.rs#49-53](http://crates/palyra-daemon/src/gateway/runtime.rs#49-53).
## Event Sanitization and Redaction
To prevent sensitive information (secrets, credentials, PII) from being persisted in the clear, the Journal uses a multi-stage redaction pipeline [crates/palyra-daemon/src/journal.rs#11-12](http://crates/palyra-daemon/src/journal.rs#11-12).
### Redaction Logic
* **Key-based**: Scans JSON keys for fragments like `secret`, `api_key`, `token`, and `password` [crates/palyra-daemon/src/journal.rs#81-94](http://crates/palyra-daemon/src/journal.rs#81-94).
* **Value-based**: Searches text for phrases such as "bearer token is" or "social security number" [crates/palyra-daemon/src/journal.rs#96-130](http://crates/palyra-daemon/src/journal.rs#96-130).
* **Binary Redaction**: Removes raw binary data from payloads to keep the database size manageable.
* **Marker**: Redacted content is replaced with the string `` [crates/palyra-daemon/src/journal.rs#75-75](http://crates/palyra-daemon/src/journal.rs#75-75).
**Redaction Flow**
```mermaid theme={null}
sequenceDiagram
participant ORCH as Orchestrator
participant JS as JournalStore
participant RED as RedactionPipeline
participant DB as SQLite
ORCH->>JS: append_event(Payload)
JS->>RED: sanitize_payload(Payload)
Note over RED: Scan SENSITIVE_KEY_FRAGMENTS
Note over RED: Scan SENSITIVE_VALUE_PHRASES
RED-->>JS: SanitizedPayload
JS->>JS: compute_hash(PrevHash, SanitizedPayload)
JS->>DB: INSERT INTO journal_events
```
**Sources:** [crates/palyra-daemon/src/journal.rs#75-130](http://crates/palyra-daemon/src/journal.rs#75-130), [crates/palyra-daemon/src/journal.rs#11-15](http://crates/palyra-daemon/src/journal.rs#11-15)
## Key Subsystems Managed by JournalStore
The Journal serves as the durable backend for several critical daemon components:
| Subsystem | Primary Record Type | Role |
| :--------------- | :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Orchestrator** | `OrchestratorSessionRecord` | Tracks run lifecycle (Pending, InProgress, Done) [crates/palyra-daemon/src/orchestrator.rs#22-29](http://crates/palyra-daemon/src/orchestrator.rs#22-29). |
| **Tape** | `OrchestratorSessionTranscriptRecord` | Append-only log of every interaction in a session [crates/palyra-daemon/src/gateway/runtime.rs#76-76](http://crates/palyra-daemon/src/gateway/runtime.rs#76-76). |
| **Memory** | `MemoryItemRecord` | Stores facts and vectors for RAG [crates/palyra-daemon/src/gateway/runtime.rs#64-65](http://crates/palyra-daemon/src/gateway/runtime.rs#64-65). |
| **Approvals** | `ApprovalDecision` | Persists operator decisions for tool execution [crates/palyra-daemon/src/lib.rs#148-151](http://crates/palyra-daemon/src/lib.rs#148-151). |
| **Tool Jobs** | `ToolJobRecord` | Tracks background tool execution and output tails [crates/palyra-daemon/src/gateway/runtime.rs#83-85](http://crates/palyra-daemon/src/gateway/runtime.rs#83-85). |
**Sources:** [crates/palyra-daemon/src/gateway/runtime.rs#54-99](http://crates/palyra-daemon/src/gateway/runtime.rs#54-99), [crates/palyra-daemon/src/orchestrator.rs#20-29](http://crates/palyra-daemon/src/orchestrator.rs#20-29)
## Maintenance and Health
The system includes automated maintenance routines to ensure the database remains healthy and performant.
### JournalHealthReport
The health report, accessible via the `GatewayRuntimeState`, monitors:
* **WAL Checkpoints**: Status of the write-ahead log [crates/palyra-daemon/src/gateway/runtime.rs#51-52](http://crates/palyra-daemon/src/gateway/runtime.rs#51-52).
* **Hash Integrity**: Verification of the SHA-256 chain [crates/palyra-daemon/src/gateway/runtime.rs#49-50](http://crates/palyra-daemon/src/gateway/runtime.rs#49-50).
* **Migrations**: Ensures the schema is at the latest version from the `MIGRATIONS` list [crates/palyra-daemon/src/journal.rs#8-9](http://crates/palyra-daemon/src/journal.rs#8-9).
### Retention and Cleanup
The Journal implements retention policies for artifacts and memory items. For example, `MEMORY_RETENTION_DAY_MS` defines the base unit for memory aging [crates/palyra-daemon/src/journal.rs#150-150](http://crates/palyra-daemon/src/journal.rs#150-150). The `MemoryPurgeRequest` is used to clear expired or explicitly deleted memory segments [crates/palyra-daemon/src/lib.rs#150-150](http://crates/palyra-daemon/src/lib.rs#150-150).
**Sources:** [crates/palyra-daemon/src/journal.rs#140-160](http://crates/palyra-daemon/src/journal.rs#140-160), [crates/palyra-daemon/src/gateway/runtime.rs#49-53](http://crates/palyra-daemon/src/gateway/runtime.rs#49-53), [crates/palyra-daemon/src/lib.rs#148-153](http://crates/palyra-daemon/src/lib.rs#148-153)