Answer shapes

A structural question returns one of four documents. The first three come from the engines; the fourth is the host envelope around the first.

The full answer

queryResult carries the manifest with the query hash and the package list with their hashes, the columns, the rows with values and provenance, the warnings, and the funnel that explains empty answers. Its schema is published once and shared: query-result.

The refusal

queryError carries a diagnostic code with the message, the position and the hints. Every code of the query family has its own page under diagnostics: the message wording is part of the contract, the code is the stable handle.

The live dictionary

querySchema lists every relation with its fields and every function with its arity, with row counts on the current snapshot. queryCatalog lists the named questions with their descriptions and parameters. Both are printed by the command itself instead of an answer: law query --schema and law query --list. The relations and functions pages of this topic render the same dictionary with one paragraph of meaning per entry.

The page envelope

The host answers with a window onto the full document rather than the document: the manifest of a wide scope alone would overflow the answer budget. The envelope carries the identity of the full document and of the scope, so the page checks against the command-line document.

field	use
kind	always queryPage: a window onto a full queryResult, never the document itself
schemaVersion	page schema, 0.1, matching the queryResult it windows
language	the LawQL line the host runs
queryHash	sha256 of the query text
resultHash	sha256 of the canonical bytes of the full queryResult: the page checks against the CLI —json document
snapshot	sha256 of the canonical bytes of manifest.corpus: the identity of the scope with package hashes
packages	how many scope packages the manifest lists
materializationEngine	who ran eval() materializations, if any
materializations	how many eval() materializations ran
columns	the select aliases of this window
rowCount	rows of the whole result, not just this window
rowOffset	where this window starts
rowLimit	window size: 20 by default, at most 5000
rows	the window rows, each values with provenance
next	cursor for the continuation, with snapshot, or null on the last window
explain	the funnel: row counts after each clause, and the clause that emptied the answer
warnings	page warnings, including ROWS_TRUNCATED while the result does not fit one window

A continuation is taken from the next cursor together with the snapshot; a continuation on another snapshot is refused. The full document instead of a page is served only for a single-package scope that fits the budget.