Data

The signed, append-only log records conversation events. The projector folds those events into tables you can query with SQL — a query reads the tables, never the log, and cannot write to either.

SELECT partition, position, role, text
FROM messages
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 projector uses the same fold to build the tables a query reads. Both therefore apply the same payment rules.

The tables

The projection adds identifying columns no log event carries:

• partition — the conversation the row belongs to, written conv-{id}.
• source_incarnation — which incarnation of the source partition produced the row.
• 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 fold normalizes them into one column.

These columns identify rows folded from individual log events. Deployment-wide tables — persona records, credential history, query audit — carry their own keys instead. Start with turns, which every participant grant can name:

-- Inspect committed turns
SELECT * FROM turns 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_base_units, p.asset, a.tool_name, a.outcome
FROM payments p
JOIN approvals a ON a.request_id = p.tool_call_id
ORDER BY p.position DESC;

The catalog lists the tables your credential's realm may name. A participant grant names the conversation tables; a fleet grant names all of them. Your scope then bounds which partitions' rows appear. Names outside the realm fail to resolve before execution.

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.

A turn-derived table gains a row only when its conversation and turn have turn_start and turn_complete markers. An unfinished turn's events are folded into nothing, so no realm can read them — there is no raw-events escape hatch. Tables that are not turn-scoped apply no such gate: refusals keeps the record a blocked attempt must leave, and wallet_link_lifecycle ceremonies run outside any turn.

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.

Realm and scope apply before query planning

The credential you present fixes the realm: a participant grant names only the conversation tables, a fleet grant names every table. A name outside the realm fails to resolve before execution. The scope inside the grant then admits only the partitions your persona participates in.

The verified caller determines the credential. An admin session mints a short-lived fleet-wide grant. A persona session mints a grant over the conversations that person's participation records name.

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

Participant grants expose the content already available to participants through transcripts and approval interfaces. These categories live in fleet-only tables:

• Raw signer keys.
• Identity provenance — who asserted each participant identity on the edge.
• Rows a turn marks as never sent to a client.
• Settlement verdicts and routine internals.
• Deployment-wide persona, credential, and query-audit records.

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, ad-hoc SQL runs against the standalone Query plane. Your session mints a caller-held grant — POST /api/query/grant for your own conversations, POST /api/query/admin-grant for an admin — and the caller presents it as the bearer on a direct Execute call to the Query edge socket. No Control endpoint accepts SQL; Control only mints the credential.

curl -sS -X POST https://<control-plane>/api/query/grant \
  -H "authorization: Bearer $POLYCHROME_SESSION"
# → {"token":"…","expires_at_ms":…}

# The grant rides as the bearer on a Connect Execute call to the Query
# edge socket, which streams result frames back:
# POST https://<query-edge>/polychrome.query.v1.QueryService/Execute
#   authorization: Bearer <token>
#   {"sql":"SELECT model, COUNT(*) AS turns FROM model_call GROUP BY model"}

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 Query plane 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 the fleet-only query_audit_* tables. 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

The projector replays each journal partition once per generation and writes exact, signed artifacts. A query registers only the artifacts its realm and scope admit, then reads them as ordinary columnar tables — statistics and projection pushdown apply. There is no query-time replay and no decode cache; a new generation republishes an artifact rather than mutating one.

A LIMIT can bound a simple plan. Sorting, grouping, and joins build intermediate results before applying the output limit. Narrowing the conversations your scope admits reduces the artifact set a query opens.

The dashboard and the fixed-statement conversation tools run per-request statements against the fleet realm. No maintained dashboard table exists — the totals come out of the same published artifacts.

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