Diff: how-to/read-the-command-ledger
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "How to read the command ledger" | title: "How to read the command ledger" |
| slug: read-the-command-ledger | slug: read-the-command-ledger |
| category: how-to | category: how-to |
| content_type: how-to | content_type: how-to |
| type: how-to | type: how-to |
| status: active | status: active |
| last_edited: 2026-06-14 | last_edited: 2026-06-14 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: read-the-command-ledger.es.md | paired_with: read-the-command-ledger.es.md |
| --- | --- |
| The Command Ledger is the append-only audit record of everything a Totebox operator session has produced — commands executed, records verified, messages sent, and session boundaries. Reading the ledger is how you understand the history of a session, audit what changed during a window, and verify that a record was written in the sequence you expected. | The Command Ledger is the append-only audit record of everything a Totebox operator session has produced — commands executed, records verified, messages sent, and session boundaries. Reading the ledger is how you understand the history of a session, audit what changed during a window, and verify that a record was written in the sequence you expected. |
| For the Command Ledger's place in the session architecture, see [[console-os]]. For how the underlying storage layer works, see [[service-fs-architecture]]. | For the Command Ledger's place in the session architecture, see [[console-os]]. For how the underlying storage layer works, see [[service-fs-architecture]]. |
| ## Prerequisites | ## Prerequisites |
| - An active Totebox session (see [[open-first-totebox-session]]) | - An active Totebox session (see [[open-first-totebox-session]]) |
| - F12 Input Machine available (see [[app-console-input]]) | - F12 Input Machine available (see [[app-console-input]]) |
| ## Read the ledger in the Input Machine (F12) | ## Read the ledger in the Input Machine (F12) |
| The Input Machine at F12 surfaces ledger activity alongside the verification queue. | The Input Machine at F12 surfaces ledger activity alongside the verification queue. |
| 1. Press **F12** to open the Input Machine. | 1. Press **F12** to open the Input Machine. |
| 2. Use the tab or arrow keys to navigate to the **Ledger** view (shown in the navigation strip as `LEDGER`). | 2. Use the tab or arrow keys to navigate to the **Ledger** view (shown in the navigation strip as `LEDGER`). |
| 3. The ledger displays entries in chronological order, newest at the bottom. Each entry shows a timestamp, entry type, and a short summary. | 3. The ledger displays entries in chronological order, newest at the bottom. Each entry shows a timestamp, entry type, and a short summary. |
| 4. Use **Page Up** / **Page Down** to scroll; **/** to search entries by keyword. | 4. Use **Page Up** / **Page Down** to scroll; **/** to search entries by keyword. |
| ## Entry types | ## Entry types |
| | Type | Meaning | | | Type | Meaning | |
| |---|---| | |---|---| |
| | `SESSION_OPEN` | A Totebox session was started with the listed identity | | | `SESSION_OPEN` | A Totebox session was started with the listed identity | |
| | `SESSION_CLOSE` | The session was closed; duration recorded | | | `SESSION_CLOSE` | The session was closed; duration recorded | |
| | `RECORD_VERIFIED` | A human operator confirmed a record through F12 | | | `RECORD_VERIFIED` | A human operator confirmed a record through F12 | |
| | `RECORD_REJECTED` | A record was rejected; routed to quarantine | | | `RECORD_REJECTED` | A record was rejected; routed to quarantine | |
| | `MESSAGE_SENT` | An outbound message was dispatched | | | `MESSAGE_SENT` | An outbound message was dispatched | |
| | `CHECKPOINT` | A signed proof of ledger state was written (periodic) | | | `CHECKPOINT` | A signed proof of ledger state was written (periodic) | |
| ## Verify a specific entry | ## Verify a specific entry |
| To confirm that a record is genuinely in the ledger (and not altered after the fact): | To confirm that a record is genuinely in the ledger (and not altered after the fact): |
| 1. Note the entry's position (row index) and its displayed hash suffix. | 1. Note the entry's position (row index) and its displayed hash suffix. |
| 2. Export the corresponding tile using the `read_since` operation on the CLI or the service-fs API. | 2. Export the corresponding tile using the `read_since` operation on the CLI or the service-fs API. |
| 3. Compute the SHA-256 hash of the tile and compare it to the checkpoint hash for that position. | 3. Compute the SHA-256 hash of the tile and compare it to the checkpoint hash for that position. |
| A mismatch indicates tampering — the WORM guarantee covers the chain from the first write, not just the visible summary. | A mismatch indicates tampering — the WORM guarantee covers the chain from the first write, not just the visible summary. |
| For the verification procedure in detail, see [[verify-worm-ledger]]. | For the verification procedure in detail, see [[verify-worm-ledger]]. |
| ## Export ledger entries | ## Export ledger entries |
| In the Input Machine's Ledger view, press **e** to export a date range as a local text file. The file format is plain-text C2SP tlog-tiles — readable without any PointSav tooling. | In the Input Machine's Ledger view, press **e** to export a date range as a local text file. The file format is plain-text C2SP tlog-tiles — readable without any PointSav tooling. |
| ## Key takeaways | ## Key takeaways |
| - The Command Ledger is append-only; no entry can be modified or deleted | - The Command Ledger is append-only; no entry can be modified or deleted |
| - The Input Machine (F12) surfaces ledger activity alongside the verification queue — they are two views of the same audit trail | - The Input Machine (F12) surfaces ledger activity alongside the verification queue — they are two views of the same audit trail |
| - Checkpoint hashes enable third-party verification without a live service | - Checkpoint hashes enable third-party verification without a live service |
| - Exporting tiles produces standard C2SP tlog-tiles format; any SHA-256 implementation can verify the chain | - Exporting tiles produces standard C2SP tlog-tiles format; any SHA-256 implementation can verify the chain |
| ## See also | ## See also |
| - [[console-os]] — the Command Ledger's role in the session architecture | - [[console-os]] — the Command Ledger's role in the session architecture |
| - [[service-fs-architecture]] — the WORM storage layer that persists ledger entries | - [[service-fs-architecture]] — the WORM storage layer that persists ledger entries |
| - [[worm-ledger-architecture]] — what the WORM guarantee covers and what it does not | - [[worm-ledger-architecture]] — what the WORM guarantee covers and what it does not |
| - [[verify-worm-ledger]] — step-by-step ledger verification procedure | - [[verify-worm-ledger]] — step-by-step ledger verification procedure |
| - [[app-console-input]] — the Input Machine and its ledger view | - [[app-console-input]] — the Input Machine and its ledger view |