Data

The signed, append-only log records conversation events. Data decodes those events into tables you can query with SQL. Queries cannot write to the log or create a separate durable copy.

SELECT partition, position
FROM events
WHERE kind LIKE 'output_msg:%'
ORDER BY partition, position;

Shared event interpretation

Decoding reads an event's payload. A fold interprets events to derive a fact, such as a settled payment. Separate implementations can disagree about which events count.

A decoded payment receipt does not establish that its signature is valid. If a dashboard skips verification, it can display a forged receipt as settled. A spending check that verifies signatures would reject the same receipt.

polyc-facts provides shared folds for readers. Spending checks call a fold directly, and the query layer uses the same fold to build tables. Both therefore apply the same payment rules.

The tables

The query layer adds three identifying columns. Event records contain kind, trust, and payload; they do not contain these row identifiers:

• partition — the conversation the row belongs to, written conv-{id}.
• position — the row's position in append-only order.
• turn_id — the turn the row belongs to. The log records it three different ways. The query layer normalizes them into one column.

These columns identify rows derived from individual log events. Reference tables and aggregate views, such as dashboard, use their own schemas. Start with events, which is available in every scope:

-- Inspect event rows
SELECT * FROM events LIMIT 5;

-- Count input and output tokens per turn
SELECT turn_id,
       SUM(input_tokens)  AS input_tokens,
       SUM(output_tokens) AS output_tokens
FROM usage
GROUP BY turn_id
ORDER BY turn_id;

-- Find tool calls without a recorded result
SELECT c.name, c.turn_id, c.position
FROM tool_calls c
LEFT JOIN (SELECT tool_call_id FROM tool_calls WHERE block_type = 'result') r
       ON r.tool_call_id = c.tool_call_id
WHERE c.block_type = 'call'
  AND r.tool_call_id IS NULL
ORDER BY c.position DESC;

A tool call, result, approval, and receipt share a call id. tool_calls and payments name it tool_call_id. approvals names it request_id. Join these columns to inspect the transaction.

-- List settled payments with their approvals
SELECT p.reference, p.amount, p.currency, a.tool_name, a.approved
FROM payments p
JOIN approvals a ON a.request_id = p.tool_call_id
WHERE a.phase = 'response'
ORDER BY p.position DESC;

The catalog lists queryable tables. Your scope determines which tables register in your session. Names outside that scope fail to resolve.

Only committed turns

The control plane records dispatch intent through the state plane before calling the harness. It records the commit marker after the harness returns. A crash between these writes can leave records for an unfinished turn, including one that caused an external effect.

The events table includes a row only when its conversation and turn have turn_start and turn_complete markers. Most event-derived tables apply the same filter, excluding payments and messages from unfinished turns. refusals remains queryable even when a turn never commits. wallet_link_lifecycle records occur outside turns, and summary uses synthetic turn tags. Neither uses the committed-turn filter.

The filter matches both conversation and turn because clients supply turn ids. A committed turn in one conversation cannot make another conversation's turn eligible. A real-journal test checks that an unfinished turn has three raw rows and zero rows in the view.

Admin sessions can inspect unfinished-turn records through events_raw. Other session catalogs do not register that table.

Scope applies before query planning

Session creation registers only the tables and columns your scope permits. Queries that reference other names fail before execution.

The verified session determines scope. Admin sessions can query every conversation the control plane discovers. Persona sessions can query conversations associated with that person's participation records.

Tools running within a conversation use its trusted dispatch attribution to determine scope. Their arguments cannot select another conversation.

Non-admin queries expose the content already available to participants through transcripts and approval interfaces. These five categories require admin scope:

• Raw signer keys.
• Every other participant's identity on the edge.
• Messages the wire format marks as never sent to a client.
• Undecoded payload bytes.
• Deployment-wide persona tables.

Queries include full tool arguments and results already available to participants, without display truncation.

How an agent reads its own conversation

Two conversation-history tools use fixed SQL statements and do not require approval. conversation_recent_turns lists committed turns, newest first: 20 by default, at most 50. conversation_list_tool_calls lists recorded calls and argument previews: 20 by default, at most 100. Full-detail mode adds turn-failure information or human-approval status, respectively.

Agents cannot submit raw SQL from within a conversation. Model-authored SQL can combine rows with different trust levels, preventing the result from retaining each row's provenance verdict.

Outside conversations, POST /api/query and an MCP tool expose the query engine. Each request requires a verified session. Both apply the same scope rules and return the same response format.

curl -sS https://<control-plane>/api/query \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $POLYCHROME_SESSION" \
  -d '{"sql":"SELECT model, COUNT(*) AS turns FROM model_call GROUP BY model"}'
# → {"columns":["model","turns"],"rows":[["…",42]],"truncated":false,"skipped_partitions":0}

Check truncated before interpreting a result. A true value means the response reached its row limit. Narrow the query or use COUNT(*) to obtain a total.

Query limits

The engine parses each statement and checks its type, not its prefix. It accepts exactly one statement, and that statement has to be a query. Data definition, data modification, SHOW, COPY, SET, transaction control, and multi-statement batches are refused before planning. EXPLAIN ANALYZE runs the query, so it is refused everywhere. Plain EXPLAIN is admin-only. Ad hoc external-table references are off for every scope.

Each query records an intent before execution and an outcome afterward in a dedicated audit partition. If recording the intent fails, the query does not run. An intent without an outcome indicates that no result was recorded. Fixed-statement conversation tools follow the same audit requirement.

Where the rows come from

A query reads its authorized log partitions and decodes their events through shared folds into in-memory tables. Most tables therefore require no separate ingestion process.

Replay decodes events rather than scanning columnar files, so file statistics cannot skip unread blocks. The planner pushes projections and filters into the scan. A LIMIT can bound a simple plan. Sorting, grouping, and joins build intermediate results before applying the output limit. Narrow the conversation scope to reduce replay work; reducing returned rows alone may not avoid the replay limit.

A decode cache reuses replayed partitions across queries and extends them when the log grows. Rewriting a partition invalidates its cache entry.

The dashboard table uses a maintained projection from the durable commit feed. At-least-once delivery can leave it temporarily behind during redelivery or resubscription. Other catalog tables use query-time replay, with cached decoding where available.

The query fact model defines the responsibilities of decoding, shared folds, and consumer projections. It also documents table classes, scope, and redaction rules.