Docs / Specification

contract read · 20-read.md · 21-memory.md · guide · card

The read face

Implementers use this page for SQL queries, ranked retrieval and read responses. Each connection registers relations with the caller’s access restrictions. Reads write no rows and hold no leases. Queries use existing index sidecars and build no indexes.

Query components and their connections to storage, access controls and memory:

register

Registered relations, query tools, templates, the embedded SQL engine and HTTP transport.

• connection-viewstestEach session connection creates or replaces one view per manifest table, scanning explicit-file-liststore.reconcile.explicit-file-listEvery read passes read_parquet an explicit sorted file list of the parts the pointer's manifests name, with no glob, so stray files and indexes/ stay out.. Statements reuse these views under session-poolread.cache.session-poolFace reuses sessions and connections while the key matches: admitted authority, token id, revocation epoch, request zone, bounds, pin map and table set. Each granted table contributes schema digest, pointer, run set and ledger files.. No view directory exists on disk.
• declaration-settestThe face registers the tables of declaration-setstore.declare.declaration-setThe project's tables combine its declaration with adjacent pipelines/.toml and pipelines/.json, [pipeline] tables as named and specification tables under table-name; queries and every sync verb use this set., so a primary_key a pipeline file declares reaches dedup-viewstore.declare.dedup-viewA keyed table reads through ROW_NUMBER() OVER (PARTITION BY <pk> ORDER BY <order_by> DESC, _ingested_at DESC, _run_id DESC, _row_seq DESC) = 1 over the current snapshot, if any, unioned with the committed runs it omits. on the operator verb and the tool server alike.
• enginetestEvery profile serving reads links an embedded columnar SQL engine that reads Parquet with standard SQL. External processes read the same files without that embedded engine.
  Why

  A-topology#build-profiles
• quiet-tabletestA quiet table registers as empty-runstore.declare.empty-runA zero-row run commits a manifest with no parts, replacing nothing without empty-replacement; a table with no rows registers as a zero-row relation over its declared and injected columns.. Reading that table returns an empty result rather than a missing-relation fault.
  Why

  P4
• bare-nametestIn caller statements, templates, ranking queries and file previews, a bare table name resolves to the caller’s registered relation. That relation carries the caller’s restriction.
  Why

  P5
• tool-settestThe face exposes context.describe, context.query, context.reference, context.lineage, context.execute_query for templates, context.files, context.file, context.subscribe, corpus.retrieve, memory.recall, memory.traverse and memory.explain as its closed tool set.
  Why

  A-read#pooled-engine-reuses
• bound-argumentstestExcept memory.recall, memory.traverse, memory.explain, context.subscribe and context.lineage, read tools, including templates, accept as_of and valid_as_of and echo echostore.bound-time.echoA bounded read returns contextful.bounds as {as_of?, valid_as_of?, inclusive}, each instant RFC 3339 UTC with nine fractional digits and a Z; an unbounded read omits it.. valid-as-ofstore.bound-time.valid-as-ofvalid_as_of filters the same inner source with from <= valid_as_of AND (to IS NULL OR to > valid_as_of) over the declared pair. applies only to tables the read touches.
  Why

  because a session registers every granted table, and wrapping one declaring no pair refuses reads that never name it
• bound-listingtestcontext.files and a context.describe naming no table select under as_of alone; each ignores valid_as_of and echoes only its as_of part.
  Why

  because valid time narrows rows, and a listing returns files and table names, never rows
• available-bound-argumenttestTools under bound-argumentsread.register.bound-argumentsExcept memory.recall, memory.traverse, memory.explain, context.subscribe and context.lineage, read tools, including templates, accept as_of and valid_as_of and echo echo. valid-as-of applies only to tables the read touches. also accept available_as_of and echo bound-echostore.available-time.bound-echoA read carrying available_as_of adds it, in the same instant form, to the object echo returns.. available-as-ofstore.available-time.available-as-ofavailable_as_of filters the inner source with <column> <= available_as_of under beneath-enforcement, combining with as-of and valid-as-of when the read supplies them. applies only to tables the read touches.
  Why

  because a session registers every granted table, and wrapping one declaring no availability time refuses reads that never name it
• available-bound-listingtestA listing bound-listingread.register.bound-listingcontext.files and a context.describe naming no table select under as_of alone; each ignores valid_as_of and echoes only its as_of part. names ignores available_as_of and echoes no available_as_of part.
  Why

  because availability time narrows rows, and a listing returns files and table names, never rows
• describe-payloadtestcontext.describe returns row count, size-estimateread.register.size-estimatecontext.describe reports bytes, the serialized JSON length of the caller's restricted rows, and estimated_tokens, one per 4 B of that length, rounded up., schema fingerprint, description, column-hintsread.register.column-hintsA table's column_hints map supplies optional per-column hints; context.describe includes each hint only with a column the session registers., declared indexes, partition scheme, limits.max_rows, zone label, lexicon and example queries.
• size-estimatetestcontext.describe reports bytes, the serialized JSON length of the caller’s restricted rows, and estimated_tokens, one per 4 B of that length, rounded up.
  Why

  because a client choosing between a full-context read and a ranked one compares the corpus against its context window before reading it
• join-routetestCross-table joins use one context.query statement over registered relations or a published model listed by describe. No tool constructs joins for callers.
  Why

  because a statement already composes each relation’s restriction, and a join tool restates that composition outside the guard
• column-hintstestA table’s column_hints map supplies optional per-column hints; context.describe includes each hint only with a column the session registers.
  Why

  because a hint for an absent column describes a relation the registered schema cannot query
• describe-zonetestcontext.describe reports the session zone as session_zone, and per table, listed or described, zone_admitted: whether the table’s effective allow-set admits that zone.
  Why

  A-read#read-surface-admits
• advertised-is-enforcedtestA table’s published limits block lists a bound exactly when the engine applies it.
  Why

  because a published number and a delivered guarantee cannot disagree when one derives from the other
• budget-argumentstestEvery read tool but context.subscribe, which overrunread.subscribe.overrunA subscription holding more than 1000 notifications undelivered sends 1000, then a terminal overrun message naming each table's last delivered position, and ends. bounds, accepts optional max_duration_ms and max_response_bytes request fields, each with no default.
• duration-no-statementtestA read tool running no SQL statement accepts max_duration_ms without triggering duration-ceilingread.respond.duration-ceilingUnder duration-ceiling, the engine interrupts the statement's connection at its deadline. ReadDurationExceeded names the ceiling, source and elapsed milliseconds. The response contains no rows; other statements continue running..
  Why

  because no connection executes a statement for its deadline to interrupt
• budget-advertisementtestcontext.describe lists a table’s limits.max_duration_ms and limits.max_response_bytes under advertised-is-enforcedread.register.advertised-is-enforcedA table's published limits block lists a bound exactly when the engine applies it. and omits each undeclared limit.
• template-projectiontestEach manifest template registers a tool named by the template’s identifier. The tool’s typed schema requires every declared positional parameter.
• file-listingtestcontext.files returns store-root-relative paths for the tables the caller reads, and a table outside that set contributes no path.
  Why

  P5
• file-preview-targettestcontext.file resolves a path to its (table, run_id) and reads it through that table’s registered relation. A snapshot part, a traversal, an absolute path or a ledger file raises FilePreviewNotATable.
  Why

  A-read#read-surface-admits
• ledger-relationtestEach table’s per-run request ledger registers as the child relation <table>__requests, holding identifiers, connector, method, host, status and timing of mediated outbound calls.
• scoped-ledgertestThe child relation registers on the owner read alone: a credential carrying no tenant scope, over a table carrying no row policy. Naming a closed ledger raises LedgerNotTenantScoped, stating what closed the relation.
  Why

  A-read#read-surface-admits
• no-tenant-ledgertestNo tenant-scoped projection of a request ledger registers; scoped-ledgerread.register.scoped-ledgerThe child relation registers on the owner read alone: a credential carrying no tenant scope, over a table carrying no row policy. Naming a closed ledger raises LedgerNotTenantScoped, stating what closed the relation. is the ledger’s one read path.
  Why

  because ledger rows carry no tenant column, and a projection filtering on a dimension its rows lack discloses every tenant’s calls
• lexicon-surfacetestThe describe payload carries the store’s numeric-identifier and badge vocabulary. Aliases, time-window phrases and distillation examples stay on the serving side.
• reserved-relationtestThe engine’s reserved table namespaces register like any other relation, with no privileged path underneath.
  Why

  P5

HTTP transport

contextful serve --http admits each request, bounds its connections and drains on stop.

• network-transporttestcontextful serve --http <addr> --audience <aud> --max-in-flight <n> serves MCP Streamable HTTP at POST /mcp. The stdio tool server answers each request’s single JSON-RPC message as application/json.
  Why

  A-read#networked-read-transport
• concurrent-statementstestRequests on any number of connections run concurrently. Each statement uses its own engine connection under pool-connectionsread.cache.pool-connectionsOne pool entry keeps at most 4 connections idle; a concurrent statement past them opens its own and closes it afterwards. and delays no other request.
  Why

  A-read#pooled-engine-reuses
• serve-declarationtestA serve with no --audience, or no positive --max-in-flight, raises ServeDeclarationMissing naming the flag and binds no listener; neither ships a default.
  Why

  P3
• past-ceilingtestA request arriving while the ceiling’s count of requests is in flight answers 503 with a Retry-After of 1 s and admits nothing.
  Why

  A-read#networked-read-transport
• connection-ceilingtestAn accepted connection holds a slot until the server writes its response. With all slots held, the server answers past-ceilingread.register.past-ceilingA request arriving while the ceiling's count of requests is in flight answers 503 with a Retry-After of 1 s and admits nothing. before parsing the request and starts no thread.
  Why

  because a request head arrives before admission, and a slot taken only after reading it lets an unadmitted caller hold one thread per connection
• per-request-admissiontestEach request carries Authorization: Bearer <credential>, or DPoP <credential> with a DPoP proof header. The listener admits each credential under possession-bindingauthority.verify.possession-bindingA confirmation claim holds a client public-key thumbprint. Each request under a credential carrying one bears a proof signed by the matching private key over method, target, body digest, issue instant and nonce; a credential carrying none requires no proof. and network-bearerauthority.verify.network-bearerA network checkpoint admits a credential with no confirmation claim as a bearer when it names the checkpoint's declared audience and meets bearer-lifetime; the peer fallback never applies over a network. and restricts reads to that credential’s grants.
  Why

  A-read#networked-read-transport
• credential-missingtestA request carrying no Authorization credential raises HttpCredentialMissing with 401 and reads no row.
  Why

  A-read#networked-read-transport
• admission-refusedtestA request its admission refuses answers 401 carrying the refusal’s identifier, except a full nonce cache, which answers 503 under nonce-cacheauthority.verify.nonce-cacheA checkpoint's nonce cache holds at most 100000 entries; a proof arriving while it is full answers 503 and admits nothing..
  Why

  A-read#networked-read-transport
• per-request-revocationtestThe server re-reads --denylist for each request and rejects a revoked credential on the next request without restarting. An unreadable denylist returns 503 and admits nothing.
  Why

  A-read#networked-read-transport
• stateless-sessiontestA notification answers 202 with no body. The face holds no protocol session and opens no server stream: a GET or DELETE on /mcp answers 405, any other path 404.
  Why

  A-read#networked-read-transport
• request-bodytestFor a request body over 1 MiB, the server returns 413 and stops reading the body.
  Why

  because the listener reads the body before admission, and an unbounded body lets an unadmitted caller hold memory
• healthtestGET /health answers 200 with the build identity of build-identityread.embed.build-identityThe handshake reports linked retrieval backends (duckdb, fts, hnsw), connector families (m365, s3, wasm) and interfaces (http, eval, otlp). These names derive from the same feature declarations as version output; otlp names span-encoding's protobuf exporter., admitting no credential and reading no row.
  Why

  because a container runtime probes readiness before any caller holds a credential
• health-hydratedtestGET /health?ready=hydrated answers as past-ceilingread.register.past-ceilingA request arriving while the ceiling's count of requests is in flight answers 503 with a Retry-After of 1 s and admits nothing. until snapshot-set hydration completes, then as healthread.register.healthGET /health answers 200 with the build identity of build-identity, admitting no credential and reading no row..
  Why

  because a load balancer probing plain /health routes reads to a container still hydrating, which answers each one 503
• stop-draintestOn SIGTERM or SIGINT, contextful serve --http admits no new request, answers every connection it accepted before the signal, and exits 0 once none remains, at most 20 s after the signal.
  Why

  because a container platform kills a stopping process after its grace period, and a process exiting at the signal resets every request it holds
• drain-unfinishedtestA connection still unanswered at the bound of stop-drainread.register.stop-drainOn SIGTERM or SIGINT, contextful serve --http admits no new request, answers every connection it accepted before the signal, and exits 0 once none remains, at most 20 s after the signal. closes unanswered; the server names their count on stderr and exits non-zero.
  Why

  because an operator reading a clean exit as a complete drain misses the requests the bound cut off
• draining-healthtestFrom the stop signal on, every new connection, GET /health included, answers as past-ceilingread.register.past-ceilingA request arriving while the ceiling's count of requests is in flight answers 503 with a Retry-After of 1 s and admits nothing. before its request is parsed.
  Why

  because a load balancer reading 503 from /health stops routing to a target whose admitted requests are still finishing

guard

SQL validation, allowed relations, operator statements and template arguments.

• single-read-only-statementtestAdmitted text parses to exactly one read-only SELECT. Attach, copy, install, load, pragma, set, any schema change, any data modification and a piggybacked second statement raise StatementNotReadOnly.
  Why

  A-read#read-surface-admits
• engine-own-parsetestThe guard checks the syntax tree serialized by the SQL engine. The tree determines whether the statement is read-only; no keyword blocklist determines admission.
  Why

  because guard and executor cannot disagree about what a text means when they share one parse
• relation-allowlisttestEvery base relation names a view registered for this caller or a common table expression the statement declares. A bare file path is a base relation and falls under this rule.
  Why

  A-read#read-surface-admits
• whole-tree-walktestThe guard checks the entire tree, including select-list subqueries, union arms and pivot sources. Common-table-expression names resolve only within their declaring scope and nested scopes.
• unregistered-relationtestThe guard rejects an unregistered base relation under ungranted-tableauthority.refuse.ungranted-tableA relation the caller holds no grant on, whether or not a table of that name exists, raises EnforceUnknownRelation and is absent from listings and descriptions.. The error echoes the requested name and no relation belonging to another caller.
  Why

  A-read#read-surface-admits
• table-functiontestA table function anywhere in the tree, and a schema-qualified reach into a system catalog, raise TableFunctionRefused.
  Why

  A-read#read-surface-admits
• statement-provenancetestLocal operator statements, template bodies and engine-composed reads execute without caller-SQL validation. The guard validates capability-token callers’ SQL. No network interface exposes raw operator execution.
  Why

  A-read#read-surface-admits
• quoted-identifierstestEvery schema- or manifest-derived identifier is double-quoted where rendered, admitting any UTF-8 vendor field name as an identifier and never as an expression.
• template-declarationtestA template declares an identifier, one SQL statement, positional parameters written name:type over integer, float, string, timestamp and boolean, and an optional row ceiling.
• template-reserved-parametertestManifest validation rejects template parameters named as_of, valid_as_of, zone or pin. Every template tool reserves those names for read bounds, zone and build pins.
  Why

  because a parameter sharing a read argument’s name hides that bound from the template tool
• available-reserved-parametertestManifest validation rejects available_as_of template parameters under template-reserved-parameterread.guard.template-reserved-parameterManifest validation rejects template parameters named as_of, valid_as_of, zone or pin. Every template tool reserves those names for read bounds, zone and build pins.. Every template tool reserves that name for the availability bound.
  Why

  because a parameter sharing a read argument’s name hides that bound from the template tool
• template-relation-shapetestManifest validation and server startup raise TemplateNamesForeignRelation for template SQL naming anything except store tables as plain identifiers. Template identifiers starting with context., corpus. or memory. also raise that error.
  Why

  A-read#read-surface-admits
• template-bindingtestA missing, unknown or type-mismatched argument raises TemplateArgumentRejected ahead of execution, with no coercion. Placeholders are $1…$n or ? in declaration order, or exactly the declared names.
  Why

  A-read#read-surface-admits
• query-bindingtestcontext.query binds $name or contiguous $1…$n from parameters typed under template-declarationread.guard.template-declarationA template declares an identifier, one SQL statement, positional parameters written name:type over integer, float, string, timestamp and boolean, and an optional row ceiling., without coercion. Positional ?, missing, unused, untyped or mismatched parameters raise QueryParameterRejected before execution. Bound values pass scope-guardauthority.refuse.scope-guardThe scope guard walks the engine's parse once, deciding literal equalities and membership lists over the tenant column and bound template parameters destined for it..
  Why

  because a value bound to a placeholder reaches no parser, and the tenant guard decides a bound value as it decides a literal
• startup-time-checktestTemplate checks are caller-independent and run once at startup; a request pays nothing for them.

respond

Response fields, cell encoding, row and byte limits, truncation and diagnostic metadata.

• one-projectiontestCLI JSON output, HTTP and the tool protocol serialize the same response: columns, rows, truncated, and optional restriction, resolved-build, provenance, retrieval and time-bound blocks.
  Why

  because a guarantee landing on one transport and missing on another is worse than a guarantee on none
• row-ceilingtestThe executor applies each table’s limits.max_rows to delivered rows. Truncation detection uses an extra-row probe (1 rows). This ceiling limits no work performed.
• face-ceilingtestEvery read interface, including corpus.retrieve, delivers at most 10000 rows. This ceiling contributes to row-ceilingauthority.grant.row-ceilingA read's row ceiling is the least of the grant's, the request's, the template's, each touched table's published ceiling and face-ceiling; an undeclared component imposes none, and the face ceiling is always declared. without requiring a declaration and bounds the candidate window.
  Why

  because an undeclared ceiling otherwise streams a whole table into one response, and a caller learns of the cut from truncated rather than from memory exhaustion
• engine-composed-ceilingtestEngine-composed table reads, derive sources and memory reads apply the least declared grant or table row ceiling, excluding the interface ceiling. Without declared ceilings, these reads deliver every row.
  Why

  because a derive or memory pass over a silently cut table records partial input as complete
• truncation-is-exacttestFor a row ceiling, the serializer sets truncated exactly when the extra probe row exists. Comparing returned counts with requested limits does not determine truncation.
  Why

  P4
• cell-encodingtestSQL NULL is JSON null and nothing else is. Non-finite floats are "NaN", "inf", "-inf"; temporal values are ISO-8601 strings, intervals ISO-8601 durations; an enum is its label; a union is its text form.
• bytes-and-vectorstestThe serializer encodes binary as padded base64. Fixed-size float arrays, including vector columns, become JSON arrays whose elements use float-cell encoding.
  Why

  A-store#binary-fixed-size
• nested-valuestestLists encode as JSON arrays. Structs and maps encode as JSON objects keyed by field name or key text. Each item, field or value uses cell encoding.
  Why

  A-store#struct-list-map
• wide-number-shapetestSQL type alone determines JSON encoding. Integers up to 32 bits, finite floats and decimals up to 15 digits encode as numbers. Wider integers and decimals encode as exact decimal strings.
  Why

  because a wire type that varies with the values on one page breaks a typed client on the next
• type-is-the-celltestThe response carries no separate type list. Each cell’s JSON type declares its type.
• one-response-shapetestEvery read answers with one complete result set in one response; no read tool streams partial rows.
  Why

  P4
• zero-rows-is-successtestFewer rows than the requested limit, zero included, is a success.
  Why

  P2
• match-counttestMatch counts report the number of matching rows scored by the ranker in that call. These counts require no diagnostic metadata.
• coverage-is-a-counttestA claim of missing corpus coverage requires a table count after the full-scan fallback, without recency truncation. The highest ranked score supplies no coverage conclusion.
  Why

  because the calibrated lexical leg scores the best row 1.0 and IDF lifts one incidental rare-term mention
• internals-opt-intestWith internals: true, every read tool and HTTP response includes a separate object containing executed SQL, engine name, applied limit, row count and elapsed milliseconds. Otherwise, the response omits that object.
• query-internals-parameterstestUnder internals: true, query-bindingread.guard.query-bindingcontext.query binds $name or contiguous $1…$n from parameters typed under template-declaration, without coercion. Positional ?, missing, unused, untyped or mismatched parameters raise QueryParameterRejected before execution. Bound values pass scope-guard. includes the validated typed parameter map beside executed SQL in the internals object.
• duration-ceilingtestUnder duration-ceilingauthority.grant.duration-ceilingA statement's max_duration_ms is the least of its grant, touched-table and request limits; an undeclared component imposes none, and no component declares a default., the engine interrupts the statement’s connection at its deadline. ReadDurationExceeded names the ceiling, source and elapsed milliseconds. The response contains no rows; other statements continue running.
  Why

  A-read#statement-owns-deadline
• byte-ceilingtestUnder byte-ceilingauthority.grant.byte-ceilingA response's max_response_bytes is the least of its grant, touched-table and request limits; an undeclared component imposes none, and no component declares a default., the serialized response includes only whole rows within the selected ceiling. An envelope or first row exceeding that ceiling raises ReadResponseTooLarge and returns no rows.
  Why

  A-read#statement-owns-deadline
• truncation-causetestA truncated response carries contextful.truncation with by, ceiling and source: rows admits grant, table, request, template or face; bytes admits grant, table or request.
• truncation-tietestIf both ceilings cut the same next row, bytes takes precedence. Equal ceilings within one dimension choose the first eligible source: grant, table, request, template, face.
  Why

  because one cut needs one deterministic cause for a client to branch on
• operator-metadatatestOperator table metadata includes column count and backing files. A row count comes from a count query rather than a stored field.
  Why

  P3
• restriction-blocktestThe restriction block includes session zone, incognito flag and an entry per touched relation excluded or column-masked by zone: table, excluded, rows_dropped, columns_masked. Reads withholding no touched relation omit the block.
  Why

  A-read#zone-withheld-relation
• in-band-errortestOn the tool protocol a refusal arrives in-band, as a protocol error object or a result flagged as an error under transport success.
  Why

  P2
• paths-stay-insidetestAn ordinary read’s result carries no store path. Provenance arrives as columns naming table, run, connector version, ingestion instant and authoring subject.
  Why

  A-read#read-surface-admits

query

The operator’s raw statement verb on the command line: its arguments, the relations it registers, its row bound and its output.

• operator-verbtestcontextful query --json [--project <name>] [--declaration <path>] [--limit <n>] [--incognito] <sql> runs one raw operator statement under statement-provenanceread.guard.statement-provenanceLocal operator statements, template bodies and engine-composed reads execute without caller-SQL validation. The guard validates capability-token callers' SQL. No network interface exposes raw operator execution.. The command prints one-projectionread.respond.one-projectionCLI JSON output, HTTP and the tool protocol serialize the same response: columns, rows, truncated, and optional restriction, resolved-build, provenance, retrieval and time-bound blocks. as one JSON line on standard output.
• one-statementtestText the engine’s parser splits into other than exactly one statement raises QueryNotOneStatement before any statement runs.
  Why

  because preparing multi-statement text executes every statement but the last and answers only the last, dropping the earlier results and side effects unseen
• project-relationstestWithin a project, outside incognitoread.query.incognitoWith --incognito or [project.zone] setting incognito_default = true, each relation passes the zone step at local:device. Excluded tables return no rows; excluded columns return null. restriction-block reports both., all stored or manifest-declared tables register under bare names as unrestricted base relations at latest committed state. Quiet tables follow quiet-tableread.register.quiet-tableA quiet table registers as empty-run. Reading that table returns an empty result rather than a missing-relation fault..
  Why

  because operator text is the store owner’s own, and a restriction bounds a capability-token caller
• incognitotestWith --incognito or [project.zone] setting incognito_default = true, each relation passes the zone step at local:device. Excluded tables return no rows; excluded columns return null. restriction-blockread.respond.restriction-blockThe restriction block includes session zone, incognito flag and an entry per touched relation excluded or column-masked by zone: table, excluded, rows_dropped, columns_masked. Reads withholding no touched relation omit the block. reports both.
  Why

  because incognito pins the uncredentialed local owner’s reads to the fail-closed pair, and this verb is that owner’s read
• discovered-projecttestWithout --project, the project discoverystore.init.discoveryWithout --project, a command takes the [project] name of the nearest contextful.toml at or above the working directory, basing the store root, .contextful/run/<project>/ and .contextful/memory/<project>/ on its directory. finds is the verb’s project. When discovery finds none, or the found project’s store is absent, no relation registers and the statement runs over no store.
  Why

  because every other verb reads the nearest contextful.toml, and a statement over files or literals needs no store
• project-storetestA --project whose .contextful/context/<project>/ store is absent raises QueryProjectAbsent.
  Why

  because every declared table of an absent store registers as quiet, and an operator reads its zero rows as an answer
• declaration-defaulttest--declaration <path> names the manifest whose declared tables register; without it, the default-declarationstore.init.default-declarationUnder --project, a command runs no discovery and bases every path discovery names on the working directory. Without --declaration, it reads the discovered contextful.toml, or the working directory's under --project. file does when present, and no manifest otherwise. With no project, --declaration refuses by undiscoveredstore.init.undiscoveredWithout --project, a command raises StoreProjectUndiscovered, naming the starting directory, when no contextful.toml sits at or above it or the nearest lacks [project] name..
• limit-truncatestest--limit <n> bounds delivered rows using the over-fetch of row-ceilingread.respond.row-ceilingThe executor applies each table's limits.max_rows to delivered rows. Truncation detection uses an extra-row probe (1 rows). This ceiling limits no work performed. and sets truncated under truncation-is-exactread.respond.truncation-is-exactFor a row ceiling, the serializer sets truncated exactly when the extra probe row exists. Comparing returned counts with requested limits does not determine truncation.. Without this flag, the query returns every row raw-row-ceilingread.query.raw-row-ceilingAn operator's raw read delivers at most the least limits.max_rows among the relations its parsed statement names, and at most --limit beside it. admits.
• raw-row-ceilingtestAn operator’s raw read delivers at most the least limits.max_rows among the relations its parsed statement names, and at most --limit beside it.
  Why

  because a published bound the owner’s own verb ignores advertises a guarantee one face breaks
• json-onlytestThe verb prints the JSON projection alone; it carries no text rendering, and a call omitting --json is a usage error.
  Why

  because a second rendering is a second projection a script must reconcile with the first
• engine-faulttestA statement the engine rejects exits non-zero with the engine’s message on standard error and nothing on standard output.
  Why

  because a caller parsing standard output never mistakes a partial or empty envelope for an answer

reference

Resolution of one stored citation through the caller’s registered relation, including the authenticated distinction between an erased source and an absent version.

• calltestcontext.reference accepts one table, run identifier and row sequence. contextful context reference uses the same resolver under Read admission, returning one-projectionread.respond.one-projectionCLI JSON output, HTTP and the tool protocol serialize the same response: columns, rows, truncated, and optional restriction, resolved-build, provenance, retrieval and time-bound blocks. without selecting a filesystem path.
  Why

  A-read#result-reused-under
• admissiontestResolution applies unregistered-relationread.guard.unregistered-relationThe guard rejects an unregistered base relation under ungranted-table. The error echoes the requested name and no relation belonging to another caller., the caller’s registered row and column restrictions, and duration-ceilingread.respond.duration-ceilingUnder duration-ceiling, the engine interrupts the statement's connection at its deadline. ReadDurationExceeded names the ceiling, source and elapsed milliseconds. The response contains no rows; other statements continue running., byte-ceilingread.respond.byte-ceilingUnder byte-ceiling, the serialized response includes only whole rows within the selected ceiling. An envelope or first row exceeding that ceiling raises ReadResponseTooLarge and returns no rows. and read-entrydisclosure.record.read-entryEach read tool call the face answers with a result, over stdio or HTTP, appends one entry, and the result leaves only after that entry's append group syncs; initialize, ping and tools/list append none. before publishing its verdict.
  Why

  A-read#read-surface-admits
• erased-verdicttestAn admitted reference in the independently verified cumulative erasure index returns available: false and reason: erased. An absent reference outside that index returns reason: missing without source payload.
  Why

  A-read#result-reused-under
• index-visibilitytestA tenant-scoped, row-policy-restricted, zone-excluded or column-masked caller receives an unreadable verdict before erasure-index access; only the owner metadata eligibility of scoped-ledgerread.register.scoped-ledgerThe child relation registers on the owner read alone: a credential carrying no tenant scope, over a table carrying no row policy. Naming a closed ledger raises LedgerNotTenantScoped, stating what closed the relation. admits an erased verdict.
  Why

  A-read#read-surface-admits
• frontiertestBefore resolution and response publication, the resolver validates the same signed store frontier. The frontier’s erasure index binds store identity and cumulative reference versions through store-bindingdisclosure.erase.store-bindingThe signed erasure entry binds store-identity; readers reject a frontier whose signed store identity differs from the receiving store, following recovery..
  Why

  A-read#result-reused-under

lineage

The applied dataflow graph narrowed to the relations one caller’s session registers, whole or walked from one table.

• calltestcontext.lineage accepts an optional table, direction and depth, and returns nodes, edges, truncated and withheld from the latest applied graph of dataflow-edgessurface.visualize.dataflow-edgesThe published workflow lists edges {from, to, via} between typed node ids: pipeline and build-job after, pipeline to produced table, table or model to its reading model or job, build job to model, job to written table and publication..
  Why

  because lineage states which relations feed one another, and the caller’s session decides which of them it names
• withheld-counttestA table or model the session does not register leaves the graph, one joined to a returned node counts in withheld, and a step joined to no registered relation leaves uncounted.
  Why

  because a lineage with its withheld tables removed uncounted reads as a complete one, and naming one discloses it
• seed-refusaltestA table the session does not register refuses as unregistered-relationread.guard.unregistered-relationThe guard rejects an unregistered base relation under ungranted-table. The error echoes the requested name and no relation belonging to another caller. does.
  Why

  because a graph answering for an ungranted seed discloses that the table exists
• depth-boundtestOne walk follows at most 16 edges each way and sets truncated where an edge remains.
• node-pagetestOne response carries at most 1000 nodes and sets truncated past them.
• operator-verbtestcontextful context lineage serves callread.lineage.callcontext.lineage accepts an optional table, direction and depth, and returns nodes, edges, truncated and withheld from the latest applied graph of dataflow-edges. under Read admission and prints the same answer.

Scenarios

• read.lineage.withheld-countread.lineage.withheld-countA table or model the session does not register leaves the graph, one joined to a returned node counts in withheld, and a step joined to no registered relation leaves uncounted.: WHEN a session reads one table of two a job joins, THEN the graph names that table and its step and reports withheld as 1.
• read.lineage.depth-boundread.lineage.depth-boundOne walk follows at most 16 edges each way and sets truncated where an edge remains.: WHEN a walk stops at depth with an edge remaining, THEN truncated is true.

retrieve

Candidate rows for ranked retrieval: query tokens, relevance thresholds, per-table queries, deduplication and snippets.

• ranked-calltestcorpus.retrieve({prefix, tables?, query, query_embedding?, filter?, kinds?, limit?, since?, min_score?, as_of?, valid_as_of?}) returns ranked rows across item and artifact genres under prefix and tables, each with a snippet and provenance, composing the query surface and memory recall, storing nothing.
• table-listtestRetrieval queries session relations matching both tables and prefix. Names outside the session raise RetrieveTableUnavailable, listing every unavailable name in input order. Absent and ungranted tables receive identical errors under default-denyauthority.filter-rows.default-denyA table reached with no matching grant yields no rows..
  Why

  because one identical refusal for an absent and an ungranted table confirms neither exists, and a silently skipped typo answers a different question
• relevance-floortestA row reaches a caller when its lexical score is null, at least the floor, or its vector score is positive. The floor is 2 tokens for queries of 3 tokens or more, else 1 tokens; a caller minimum overrides.
• content-tokenstestThe tokenizer lowercases query text and splits at non-alphanumeric characters. The tokenizer removes stop tokens, keeps non-ASCII runs of two or more characters, and deduplicates tokens in order.
• token-length-floortestAn ASCII run shorter than 2 chars leaves the content-token set.
• token-captestThe content-token set holds at most 12 tokens. An empty set omits the relevance predicate.
• script-split-matchingtestAn all-lowercase-alphanumeric token matches on an ASCII word boundary with an optional plural suffix; a token with any non-ASCII character matches by containment.
  Why

  because no ASCII word boundary occurs beside an ideograph
• plural-suffix-floortestA token under 4 chars takes no optional plural suffix.
• scored-texttestUnder table-blockstore.declare.table-blockA table block takes TableDecl, canonical serialization omitting unset keys. A key applies from the next read, rewriting no committed part; columns types every landing under typed-landing., retrieve.text optionally lists columns for lexical scoring and relevance-floorread.retrieve.relevance-floorA row reaches a caller when its lexical score is null, at least the floor, or its vector score is positive. The floor is 2 tokens for queries of 3 tokens or more, else 1 tokens; a caller minimum overrides., excluding session-classed or masked columns. Without retrieve.text, scoring uses the table’s snippet columns.
  Why

  because a snippet is chosen for display, so a match in a long body misses the floor and a categorical label in the snippet matches every row
• empty-scored-texttestIf declared retrieve.text leaves no column, retrieval skips that table’s full-text probe. For queries containing a content token, only positive vector scores admit its rows.
  Why

  because a null lexical score passes the floor, so a text-only query otherwise returns such a table’s newest rows whatever it asks
• text-free-table-scores-nulltestA table without scored text columns has a null lexical score rather than zero. Only vector scores admit that table’s rows.
  Why

  P4
• candidate-windowtestThe candidate window is 8 times the requested limit or 200 rows, whichever is larger. A filled window reports a recency-ordered slice. Where a vector sidecar answers, the window bounds no semantic recall: sidecar-generates-candidatesread.retrieve.sidecar-generates-candidatesVector probes use query embeddings; full-text probes use content tokens. Each probe adds its top results to the recency window and rejoins through vector-arm. Per-row scores equal exact-scan scores. adds candidates beyond it.
  Why

  P4
• reserved-columns-project-nulltestReserved projected columns — modality, language, prompt hash, kind — render null for a table lacking them, and its rows stay in the union.
• unsatisfiable-arm-dropstestIn filter, a scalar tests column equality; a value list tests membership. Rows match every condition. A table lacking a named column contributes no rows, including unfiltered rows.
  Why

  P4
• filter-valuestestFilter values are strings, numbers or booleans; membership lists contain at least one value. Nulls, nested objects, nested lists and empty lists are malformed conditions.
• kindstestkinds lists artifact kind strings as one membership condition on kind. A table without that column contributes no rows under unsatisfiable-arm-dropsread.retrieve.unsatisfiable-arm-dropsIn filter, a scalar tests column equality; a value list tests membership. Rows match every condition. A table lacking a named column contributes no rows, including unfiltered rows..
• engine-resolved-datetestThe engine resolves each table’s publication column itself, outside the caller’s filter.
• sincetestsince is the inclusive lower bound of the question’s timeframe over the publication instant engine-resolved-dateread.retrieve.engine-resolved-dateThe engine resolves each table's publication column itself, outside the caller's filter. resolves; the anchor is as_of, else the read’s clock. A date-only value means midnight UTC, and omitting since leaves every row in window.
• filter-budgettestA filter holds at most 32 conditions, each membership list at most 256 entries, and its serialized JSON, kinds included, at most 16 KiB.
• filter-budget-refusaltestBefore building per-table queries, retrieval checks the entire filter’s budget. An oversized or malformed condition raises FilterBudgetExceeded for the whole read.
  Why

  A-read#restricted-sidecar-probe
• row-key-deduptestRanked reads keep only the newest ingestion per (table, row key). If that version misses the relevance floor, no older copy substitutes. The key uses the declared content-hash column, otherwise null; projected values supply no digest.
• row-key-under-masktestFor content-hash columns masked by drop, truncate, bucket, range or any combine, every row key is null. Masking by hash or tokenize alone uses the digest as key.
  Why

  because a mask merging distinct hashes lets a reader’s grants decide which rows a table holds
• row-key-stays-internaltestThe row key is absent from the outer projection.
• dedup-is-gatedtestThe deduplicating window function runs under the same condition as the relevance floor, and a browse-shaped read skips it.
• excluded-armtestAn arm whose table the session’s zone excludes contributes no candidate, and the ranked response names that table in restriction-blockread.respond.restriction-blockThe restriction block includes session zone, incognito flag and an entry per touched relation excluded or column-masked by zone: table, excluded, rows_dropped, columns_masked. Reads withholding no touched relation omit the block..
  Why

  A-read#restricted-sidecar-probe
• snippettestA snippet concatenates up to three text columns, using retrieve.text when declared. Label-priority columns, such as title, summary, description and thesis, come first; prose-worthy columns follow in schema order.
• identifiers-never-snippettestSnippets exclude content hashes, URLs, identifiers and instant-valued columns.

index sidecars

Vector and full-text sidecars add candidates that rejoin through the caller’s relation.

• sidecar-generates-candidatestestVector probes use query embeddings; full-text probes use content tokens. Each probe adds its top results to the recency window and rejoins through vector-armauthority.compose.vector-armA sidecar vector index returns candidate identifiers, which re-join through the registered relation before contributing to a result.. Per-row scores equal exact-scan scores.
  Why

  P5
• fulltext-probetestFull-text probes rank the entire snapshot by BM25 with one should-clause per content token. Tokens split by the sidecar tokenizer match resulting terms at consecutive positions. ASCII word tokens match plurals under script-split-matchingread.retrieve.script-split-matchingAn all-lowercase-alphanumeric token matches on an ASCII word boundary with an optional plural suffix; a token with any non-ASCII character matches by containment..
  Why

  because a term outside the recency window is found only by a probe that reads every row’s postings
• sidecar-oversamplingtestOne probe requests 4 times the limit or 64 rows, whichever is larger, and a full-text probe 4 times that where the request carries restriction context.
• filtered-traversaltesttesttestUnder a caller filter or restriction context, a vector probe admits only identifiers the reader’s relation yields under the filter; traversal expands refused nodes’ neighbours and returns the probe size in admitted rows where that many exist.
  Why

  A-read#filtered-vector-traversal
• filtered-exact-thresholdtestA pre-scan of the arm’s relation under the filter counts the matching identifiers; under 4096 rows, the filtered probe ranks them by exact distance instead of traversal.
  Why

  A-read#filtered-vector-traversal
• filter-matches-nothingtestA filtered probe whose pre-scan matches no identifier adds no candidate and raises no error.
• adaptive-over-fetchtestA full-text probe, and a vector probe carrying neither filter nor restriction context, runs at most 4 rounds in total, doubling its size while readable rows fall below the requested limit. The retrieval block reports any remaining shortfall.
  Why

  A-read#restricted-sidecar-probe
• sidecar-size-captestA vector sidecar exceeding 64 MiB resident memory stays unloaded; retrieval uses an exact scan. Resident memory includes each graph node’s 4 B probe mark and, for sealed sidecars, the graph file.
  Why

  A-store#sidecar-memory-mapped
• fulltext-sealed-captestA sealed full-text sidecar file larger than 256 MiB stays unopened, and its arm adds no candidates.
  Why

  A-store#sidecar-memory-mapped
• sidecar-falls-backtestRetrieval uses an exact scan for missing snapshots, missing matching sidecars, masked or zone-withheld identifiers or indexed columns, classed text columns, dimension or manifest mismatches, or unreadable dumps.
  Why

  P4
• gain-never-losstestFor each reader, accelerated retrieval returns a superset of the exact scan’s rows. Different readers querying one snapshot may receive different rows.

Scenarios

• read.retrieve.sinceread.retrieve.sincesince is the inclusive lower bound of the question's timeframe over the publication instant engine-resolved-date resolves; the anchor is as_of, else the read's clock. A date-only value means midnight UTC, and omitting since leaves every row in window.: WHEN corpus.retrieve carries since: "2030-01-01" and a matching row’s publication column holds 2029-12-31, THEN the row still returns, its in-window flag false, ordered below every in-window row.

unsettled: Does the row id identity-columnsrun.normalize.identity-columnsNormalize injects a content-hash row id, byte-identical across re-runs of one input, on every table; a load id on the root; a parent id and list index on each child; and a root id below the first child level. injects serve as the row key of a table declaring no content-hash column? owner: read-path affects: read.retrieve

unsettled: Does restriction get the statistics treatment rank-statisticsread.horizon.rank-statisticsUnder a horizon, sidecar probes return only entries available at or before that horizon. Full-text scoring derives document count, average length and document frequency solely from those entries. gives the horizon, so BM25 document frequency on fulltext-proberead.retrieve.fulltext-probeFull-text probes rank the entire snapshot by BM25 with one should-clause per content token. Tokens split by the sidecar tokenizer match resulting terms at consecutive positions. ASCII word tokens match plurals under script-split-matching. excludes restricted rows? owner: authority affects: read.retrieve

rank

Candidate ordering by vector and lexical scores, timeframe and reported confidence.

• three-legstestRanking runs exact cosine similarity over the candidate set, BM25 over a full-text index, and a weighted fusion of the two.
• fusiontestFusion computes w_vec · clamp(cosine, 0, 1) + w_lex · rrf(bm25). Weights are 60 percent and 40 percent. rrf maps BM25 rank r to 61 / (60 + r). Absent documents score zero per leg; identifiers break ties.
• lexical-leg-matches-onlytestBM25 ranks documents matching at least one should-clause. Documents matching no term are absent. An empty query, candidate set or result produces an empty ranking and uses recency order.
• flat-window-full-credittestA lexical window with no score spread awards every present document full credit.
• question-window-is-a-tiertestA question’s timeframe projects a per-row in-window flag against the resolved publication column, and the flag leads the ordering. An out-of-window row sorts down and stays.
  Why

  P4
• window-anchor-tolerancetestA publication instant more than 24 h past the question’s anchor sets the in-window flag false. A null or uncastable value sets it false too, and a basis field names which case applied.
• ordering-casts-firsttestOrdering compares publication values as TIMESTAMPTZ instants, casting a text value before any comparison.
  Why

  because a text comparison of two date spellings orders strings, not instants
• retrieval-blocktestThe contextful.retrieval block reports window, candidates_prefloor, candidates, matched, returned, in_window, deduped, padded, floor and since. Each row carries _score, the count of content tokens its scored-textread.retrieve.scored-textUnder table-block, retrieve.text optionally lists columns for lexical scoring and relevance-floor, excluding session-classed or masked columns. Without retrieve.text, scoring uses the table's snippet columns. matches, the in-window flag and the basis label.
• delivered-countstestThe retrieval block’s returned count equals delivered rows; its in_window count equals delivered rows with a true in-window flag, after byte truncation.
  Why

  because aggregate counts describe the rows the caller receives
• internal-score-stays-internaltestResponses omit the lexical engine’s internal floating-point score.
  Why

  because a corpus-relative number drifts under a consumer’s threshold as the corpus changes
• absent-blocktestNon-ranked statements and builds without a ranker omit the retrieval block. An absent block differs from a block reporting zero matches.
  Why

  P2
• degradation-not-errortestWithout the lexical backend linked, ranking substitutes a token fallback scoring each query token over the scored-textread.retrieve.scored-textUnder table-block, retrieve.text optionally lists columns for lexical scoring and relevance-floor, excluding session-classed or masked columns. Without retrieve.text, scoring uses the table's snippet columns., recency breaking ties. The result differs in order and still answers.
  Why

  A-topology#build-profiles
• fallback-counts-tokenstestUnder the fallback every matching token contributes, ranking hyphenated, spaced and possessive phrasings equivalently.
• caller-embeddingtestA supplied query_embedding adds per-row cosine fused with the lexical leg; omitting one leaves every projected column as the lexical-only path. Without the vector backend it scores only rows the recency window recalled.
  Why

  A-topology#build-profiles
• lexical-index-cachetestThe opened full-text sidecar cache holds at most 64 entries in FIFO order, keyed by table, snapshot, path and key-version fingerprint. Repeated reads reuse sidecars; a different snapshot requires opening another.
• widened-window-statisticstestLexical term statistics use the widened candidate window. Accelerated retrieval may therefore order rows differently from the exact scan.
• calibration-gatetestA lexical-leg calibration replaces the one fusionread.rank.fusionFusion computes w_vec · clamp(cosine, 0, 1) + w_lex · rrf(bm25). Weights are 60 percent and 40 percent. rrf maps BM25 rank r to 61 / (60 + r). Absent documents score zero per leg; identifiers break ties. names only when the native evaluation scores it at or above that one on every tracked measure.
  Why

  A-read#reciprocal-rank-calibrates

unsettled: Does a convex combination over min-max-normalized scores, its weight fitted per domain on settled judgments, replace fusionread.rank.fusionFusion computes w_vec · clamp(cosine, 0, 1) + w_lex · rrf(bm25). Weights are 60 percent and 40 percent. rrf maps BM25 rank r to 61 / (60 + r). Absent documents score zero per leg; identifiers break ties.? owner: read-path affects: read.rank

unsettled: Does the read face admit a pointwise reranker, and does one whose every checkpoint postdates the horizon refuse to score under it? owner: read-path affects: read.rank

cache

Locality of the bytes a read touches, reuse of a resolved session and its connections, and reuse of a result across requests.

• hot-local-parquettestThe retrieval container syncs the current snapshot set to local disk and memory-maps it; object storage stays out of the per-query path except as lazy-hydrationread.cache.lazy-hydrationUnder lazy-parts, hydration completes once the pull returns and the parts on disk are mapped, and a query's first read of an absent part takes the one fetch miss-wait bounds. admits.
• cold-starttestA cold retrieval container meets container-readinesstopology.publish-hostname.container-readinessA retrieval container reaches readiness within 8 s of a cold start, before its snapshot-set hydration completes.; a container holding no snapshot adds a whole-store pull before its first answer.
• warming-readtestA request other than GET /health reaching a retrieval container whose snapshot-set hydration is incomplete answers as past-ceilingread.register.past-ceilingA request arriving while the ceiling's count of requests is in flight answers 503 with a Retry-After of 1 s and admits nothing.; /health names the hydration state.
  Why

  because a container ready before hydration completes otherwise answers a read from a partial snapshot set
• miss-waittestUnder lazy-partsstore.pull.lazy-partsWith [sync] lazy_parts = true, pull skips table Parquet data parts, which the store fetches whole on first read or fold use and verifies under digest-mismatch., each absent part has a 30 s acquisition deadline covering manifest lookup, GET attempts and backoff sleeps. Expiry raises ReadPartUnavailable, naming the part.
  Why

  A-store#cold-store-boots
• lazy-hydrationtestUnder lazy-partsstore.pull.lazy-partsWith [sync] lazy_parts = true, pull skips table Parquet data parts, which the store fetches whole on first read or fold use and verifies under digest-mismatch., hydration completes once the pull returns and the parts on disk are mapped, and a query’s first read of an absent part takes the one fetch miss-waitread.cache.miss-waitUnder lazy-parts, each absent part has a 30 s acquisition deadline covering manifest lookup, GET attempts and backoff sleeps. Expiry raises ReadPartUnavailable, naming the part. bounds.
  Why

  A-store#cold-store-boots
• result-keytestResult keys include token id, revocation epoch, grants, subject, session zone and incognito state. Keys also include touched relations and files, bounds, statement, parameter values and applied row ceiling.
  Why

  A-read#result-reused-under
• cache-is-opt-intestResults enter the cache only if every touched table declares result_cache with a time to live and none declares private = true. Entries expire at the shortest declared time to live.
  Why

  A-read#result-reused-under
• volatile-bypassestestStatements execute uncached if they call functions the engine marks inconsistent across queries, including now(), current_timestamp and random(). Macros calling these functions also bypass caching.
  Why

  because such a call answers differently under an unchanged key, and a hit returns its first answer frozen until the entry expires
• frontier-invalidatestestCommits, folds and request-ledger appends change a touched table’s read frontier: its snapshot and runs. Earlier cache entries stop matching. Statements executing during a fold read under non-blockingstore.fold.non-blockingA statement running during a pass reads the snapshot the pointer named when it started; statements starting after the commit read the new one..
  Why

  P4
• budgettestThe result cache stays within its process’s declared byte budget and evicts the least recently used entry first. Without a declared budget, the server caches nothing.
  Why

  A-read#result-reused-under
• hit-identicaltestCache hits return responses byte-identical to the original miss, including the restriction block. With internals: true, diagnostic metadata reports cache as hit or miss.
  Why

  because a reused answer differing from a computed one is a second projection a caller must reconcile
• session-pooltestFace reuses sessions and connections while the key matches: admitted authority, token id, revocation epoch, request zone, bounds, pin map and table set. Each granted table contributes schema digest, pointer, run set and ledger files.
  Why

  A-read#result-reused-under
• change-missestestCommitted runs, snapshots, schema edits, new tables, request-ledger files and tokens with different ids or epochs cause pool misses. The next statement reads the changed state through a new connection.
  Why

  A-read#result-reused-under
• pool-entriestestThe pool holds at most 16 entries, oldest evicted first; a miss evicts the same principal’s entries under an older store state.
  Why

  because connections hold memory per authority, and an entry under a superseded store state is never hit again
• pool-connectionstestOne pool entry keeps at most 4 connections idle; a concurrent statement past them opens its own and closes it afterwards.
  Why

  because concurrency on one session is bursty, and an idle connection holds its footer cache in memory

resolve-pin

Resolution of a named published-model build at read time, and the state each response echoes.

• pin-parametertestEvery read tool admits pin, mapping a table name to a build identifier, and resolves that table to the files its build’s committed manifest names. An unnamed table resolves to the latest published state.
• pinned-schematestA pinned table registers the columns stored in that build’s parts. Later builds neither add, remove nor retype columns in the pinned read or description.
• null-pintestA pin entry with value null resolves as an unnamed table. Pin maps differing only in null entries are equivalent.
• unknown-buildtesttestAn unknown or collected build identifier, one collected-snapshotstore.fold.collected-snapshotA snapshot counts as collected while the bucket's _collected.json stands beside it or, on a store reading through no part source, a part it names is absent; no as_of read, pin or hold resolves to it. counts included, raises PinnedBuildUnavailable, naming the oldest identifier still pinnable. A pin never widens to the latest state.
  Why

  because a substituted build applied to every remaining query passes the consumer’s cross-query comparison and stitches two states
• unregistered-pintestPins on absent or ungranted tables raise unknown-buildread.resolve-pin.unknown-buildAn unknown or collected build identifier, one collected-snapshot counts included, raises PinnedBuildUnavailable, naming the oldest identifier still pinnable. A pin never widens to the latest state. as for a table publishing no build. Both cases return identical text.
  Why

  because an answer differing between an absent and an ungranted table discloses the ungranted table’s existence
• earlier-bound-winstestA pin and the store’s transaction-time bound are upper bounds on one clock; a table named by both resolves to the earlier.
• resolved-echotestResponses touching published models include contextful.resolved, mapping each model table to {build_id, watermark}. This includes unpinned and empty results. Watermarks follow watermarkrun.model.watermarkA build's watermark is {at, inputs}: per input table the snapshot id, through, the greatest commit_seq read, and omitted, the count and digest of runs read outside the snapshot chain; at is the newest commit instant..
• absent-watermarktestThe watermark is null for a materialization carrying none, distinct from a watermark of zero.
  Why

  P4
• consumer-comparisontestA consumer compares resolved build identifiers across every query of one derivation and fails the derivation where two differ.
  Why

  P4

embed

Embedding implementations, stored model identifiers, query-model checks, build identity and missing-backend errors.

• default-embeddertestThe default embedding implementation deterministically hashes token term frequencies into an L2-normalized vector. This implementation performs no I/O and requires no download, key or network call.
• default-embedder-reachtestThe default is a lexical-vector baseline: a paraphrase is orthogonal under it and cross-lingual recall is undefined. Semantic reach comes from the learned in-process model or a caller-supplied query embedding.
• model-identifiertestEvery stored vector uses a binary-and-vectorstore.reconcile.binary-and-vectorThe lattice includes Binary, FixedSizeBinary(n) and dimension-n FixedSizeList of Float32 or Float16, none promoting; a width, item or dimension change meets incompatible. column beside embedding_model, which names the producing model. Rows alone determine index identity and provenance.
• build-identitytestThe handshake reports linked retrieval backends (duckdb, fts, hnsw), connector families (m365, s3, wasm) and interfaces (http, eval, otlp). These names derive from the same feature declarations as version output; otlp names span-encodingdisclosure.record.span-encodingA build linking the otlp feature sends each batch as an OTLP protobuf ExportTraceServiceRequest under Content-Type: application/x-protobuf; a build without it sends the OTLP JSON mapping under application/json.‘s protobuf exporter.
  Why

  P3
• required-facetestBefore the first read, the server rejects a client’s require: [...] with RequiredFaceAbsent for any unreported name. An engine reporting no set satisfies no requirement.
  Why

  A-topology#build-profiles
• absent-read-backendtestWithout the embedded SQL engine linked, every read tool raises ReadBackendAbsent rather than answering from a narrower path.
  Why

  A-topology#build-profiles

as-of-join

Point-in-time ASOF JOIN statements and templates that match rows by their availability timestamps.

• per-row-boundtestPer equality key, ASOF JOIN selects the right row with latest declared availability at or before the driving instant named by the inequality. If given, max_age bounds that row’s valid-time from.
  Why

  A-read#join-matches-availability
• horizon-caps-rowtestUnder available_as_of, each driving row’s instant is the earlier of the instant its inequality names and available_as_of, so no right row past the bound joins.
• join-undeclaredtestAn ASOF JOIN whose right relation declares no available_time refuses as undeclaredstore.available-time.undeclaredAn available_as_of read of a table declaring no available_time raises StoreAvailableTimeUndeclared, naming the table; a landing row resolving to a null instant raises StoreAvailableTimeNull, naming the table and run. does, naming the table, whether or not the read carries available_as_of.
  Why

  because joining on valid time picks a restatement published after the event

Scenarios

• read.as-of-join.per-row-boundread.as-of-join.per-row-boundPer equality key, ASOF JOIN selects the right row with latest declared availability at or before the driving instant named by the inequality. If given, max_age bounds that row's valid-time from.: WHEN a resource directory maps stable id resource-1 to label alpha available 2012-05-18 and to beta available 2022-06-09, THEN an event for resource-1 on 2021-03-01 joins alpha and one on 2022-07-01 joins beta.

unsettled: Does an as-of join’s max_age measure valid time or availability time? owner: read-path affects: read.as-of-join

horizon

Reads under horizonauthority.grant.horizonA grant may carry horizon, an instant bounding the availability time and since of every read its holder makes, under inherited-bound and exceeds-horizon; an absent horizon leaves availability unbounded.: default time bounds, rejected arguments, hidden metadata, network restrictions and selection of indexes, embedding models and builds.

• inherited-boundtestUnder a horizon, read tools default absent available_as_of to that horizon, cap horizon-caps-rowread.as-of-join.horizon-caps-rowUnder available_as_of, each driving row's instant is the earlier of the instant its inequality names and available_as_of, so no right row past the bound joins. and echo bound-echostore.available-time.bound-echoA read carrying available_as_of adds it, in the same instant form, to the object echo returns.. context.subscribe instead raises horizon-refusalread.subscribe.horizon-refusalOn the tool protocol, a subscription under a credential carrying a horizon raises SubscriptionUnderHorizon before any table or after position resolves..
  Why

  because a per-call bound is a bound the agent can omit
• exceeds-horizontestA call supplying available_as_of or since later than its credential’s horizon raises ReadBoundExceedsHorizon, naming the argument; as_of, valid_as_of and observed_at pass unbounded by it.
  Why

  because a cutoff the agent can widen is advisory, while a valid-time question about a known future effective date stays legitimate
• recall-horizontestUnder a horizon, keyedread.recall.keyedmemory.recall accepts table, subject, observed_at, as_of_ingest and limit. Returned claims match subject exactly, with valid_from and valid_to covering observed_at under valid-as-of. defaults absent observed_at to that horizon and reads claims at the same available_as_of. A table without declared availability time raises undeclaredstore.available-time.undeclaredAn available_as_of read of a table declaring no available_time raises StoreAvailableTimeUndeclared, naming the table; a landing row resolving to a null instant raises StoreAvailableTimeNull, naming the table and run..
  Why

  because a claim lands at its commit instant, and one concluded after the horizon otherwise answers inside it
• engine-stampstestUnder a horizon, responses omit _ingested_at and _commit_seq but retain citation fields _run_id and _row_seq. context.describe computes row count, size, lexicon and example values from the horizon-bounded relation.
  Why

  because load stamps date a row’s arrival and reveal the present under a past horizon, while _run_id and _row_seq cite a row without ordering rows in time
• late-columnstestA column’s first merge sets schema.json’s first_landed_at once to the batch’s earliest availability instant, otherwise commit instant. Columns with first_landed_at after the horizon are absent from registered schemas and describe payloads.
  Why

  A-store#column-records-commit
• egress-hooktestUnder a horizon, a pre-send hook rejects requests to every host except the configured model endpoint. Rejection follows hook-refusalconnector.meter.hook-refusalA hook refusing an intent raises ConnectorEgressRefused, naming the host and reason. The host resolves no name, and the retry schedule does not retry the request. with reason horizon.
  Why

  because one attachment point already sees every egress, so a per-tool list restates it
• local-ranktestUnder a horizon, corpus.retrieve ranks stored rows through local indexes; search sources read their pinned capturestore.snapshot.capture[pipeline.tables.snapshot] declares SnapshotDecl, the columns describing each captured document. Each capture commits as one store snapshot, and an evaluation case pins it by snapshot id. corpus. Live search reaches no host through egress-hookread.horizon.egress-hookUnder a horizon, a pre-send hook rejects requests to every host except the configured model endpoint. Rejection follows hook-refusal with reason horizon..
  Why

  because a live result order postdates the snapshot, and filtering it afterwards keeps the order
• rank-statisticstestUnder a horizon, sidecar probes return only entries available at or before that horizon. Full-text scoring derives document count, average length and document frequency solely from those entries.
  Why

  A-read#sidecar-serves-past
• embedder-routetestUnder a horizon, an embedder declaring a checkpoint family selects its newest checkpoint whose cutoffsconnector.infer.cutoffsA model reference carries a pinned snapshot id and pre-training and post-training cutoffs, each tagged documented or estimated. An undeclared cutoff compares as the call's own instant. post-training cutoff precedes that horizon. The response names the selected checkpoint.
  Why

  because an embedder trained after the horizon places documents by later events
• build-resolutiontestUnder a horizon, model tables select the newest build whose build-horizonrun.model.build-horizoncontextful build <model> --available-as-of <t> reads every input at available_as_of equal to t and records t as the watermark's horizon; a build without the flag records a null horizon. is at or before the credential’s horizon. If none qualifies, resolution raises ReadNoBuildWithinHorizon, naming the table.
  Why

  because a build over current inputs carries later rows into every horizon

Scenarios

• read.horizon.exceeds-horizonread.horizon.exceeds-horizonA call supplying available_as_of or since later than its credential's horizon raises ReadBoundExceedsHorizon, naming the argument; as_of, valid_as_of and observed_at pass unbounded by it.: WHEN a credential carries horizon 2014-05-01 and corpus.retrieve supplies since: "2015-01-01", THEN the call raises ReadBoundExceedsHorizonread.horizon.exceeds-horizonA call supplying available_as_of or since later than its credential's horizon raises ReadBoundExceedsHorizon, naming the argument; as_of, valid_as_of and observed_at pass unbounded by it. naming since, and a call supplying valid_as_of: "2015-01-01" answers.
• read.horizon.rank-statisticsread.horizon.rank-statisticsUnder a horizon, sidecar probes return only entries available at or before that horizon. Full-text scoring derives document count, average length and document frequency solely from those entries.: WHEN a full-text sidecar indexes stories published 2014-11-01 and 2015-06-01 and corpus.retrieve runs under horizon 2015-01-01, THEN the 2014 story ranks with the score a sidecar over it alone gives, and the 2015 story is absent.

unsettled: Where does the engine record the instant a column first landed in a table, for a schema that predates the record? owner: read-path affects: read.horizon

unsettled: Does a vintage table’s sidecar count only each key’s newest vintage available by the horizon, so its statistics and candidates match the bounded relation’s one vintage per key? owner: read-path affects: read.horizon

subscribe

Committed-run notifications, durable replay, resume positions, queue limits and the subscription CLI.

• durable-sourcetestSubscriptions read on-disk run manifests and commit logs rather than the emission-never-blocksrun.project.emission-never-blocksProgress emission is no journal step: events reach an in-process observer over a bounded channel that drops when full and never blocks the runner. channel. Subscribers receive runs committed by other processes.
  Why

  because an in-process hub ties every reader to the landing process and loses its state on restart
• after-committestSubscriptions notify only runs committed under uncommitted-runstore.lay-out.uncommitted-runA node directory without _manifest.json holds an uncommitted run, whose parts file lists exclude; a leased pipeline's run also waits for its commit-log entry.. Runs without manifests and logged runs absent from their node’s commit log produce no notification.
  Why

  P4
• notificationtestA notification is Notification; its frontier is the pair {as_of, commit_seq}: the run’s commit instant and the _commit_seq value its rows carry.
• frontier-covers-runtestA read of the table bounded as_of a notification’s frontier covers the notified run’s files.
  Why

  P4
• commit-ordertestNotifications of one table arrive in ascending commit_seq, the order commit-orderstore.reserve.commit-orderA commit publishes its manifest once every lower _commit_seq of the table publishes or ends landing, so readable runs form a prefix of the commit sequence. makes runs readable, and each committed run notifies exactly once per subscription.
  Why

  because a subscriber applying notifications in order rebuilds the table’s commit sequence
• no-contenttestA notification carries no row content and no row count.
  Why

  because a count over a table under row policy or tenant scope discloses rows the reader cannot see
• resumetestafter maps tables to <run-id>/<node-id> positions. Subscriptions replay each table’s later committed runs once, then continue live. An intervening fold leaves the replay unchanged.
  Why

  because a fold leaves run manifests in place until retention collects them
• position-unavailabletestAn after position naming no committed run of its table raises SubscriptionPositionUnavailable, naming the table’s oldest resolvable position.
  Why

  because a replay from a collected position cannot tell which later runs retention also removed
• overruntestA subscription holding more than 1000 notifications undelivered sends 1000, then a terminal overrun message naming each table’s last delivered position, and ends.
  Why

  because a bounded queue never drops a notification silently, and the terminal position resumes the stream
• operator-verbtestcontextful context subscribe <table>... [--after <table>=<run-id>/<node-id>] [--follow] prints one JSON notification per line. Without --follow, the command ends after sending the replay.
• tool-polltestcontext.subscribe accepts tables and optional after. One response page includes messages under resumeread.subscribe.resumeafter maps tables to <run-id>/<node-id> positions. Subscriptions replay each table's later committed runs once, then continue live. An intervening fold leaves the replay unchanged. and overrunread.subscribe.overrunA subscription holding more than 1000 notifications undelivered sends 1000, then a terminal overrun message naming each table's last delivered position, and ends., plus after with each table’s last delivered position for the next call.
  Why

  because the tool protocol’s request and response hold no stream, and a returned position resumes a poll exactly as it resumes a stream
• ungranted-tabletestBefore resolving after, the tool rejects subscriptions naming tables outside the session’s relations under ungranted-tableauthority.refuse.ungranted-tableA relation the caller holds no grant on, whether or not a table of that name exists, raises EnforceUnknownRelation and is absent from listings and descriptions., whether the table exists or not.
  Why

  because a position refusal or a notification on an ungranted table discloses that the table exists and commits
• horizon-refusaltestOn the tool protocol, a subscription under a credential carrying a horizon raises SubscriptionUnderHorizon before any table or after position resolves.
  Why

  because a notification carries the run’s commit instant and sequence, which engine-stampsread.horizon.engine-stampsUnder a horizon, responses omit _ingested_at and _commit_seq but retain citation fields _run_id and _row_seq. context.describe computes row count, size, lexicon and example values from the horizon-bounded relation. withholds, and runs committed after the horizon

Scenarios

• read.subscribe.resumeread.subscribe.resumeafter maps tables to <run-id>/<node-id> positions. Subscriptions replay each table's later committed runs once, then continue live. An intervening fold leaves the replay unchanged.: WHEN runs r1, r2 and r3 commit to events and a subscription names after events=r1/ingest-a, THEN it sends r2 then r3, and a fold before the call changes neither.
• read.subscribe.after-commitread.subscribe.after-commitSubscriptions notify only runs committed under uncommitted-run. Runs without manifests and logged runs absent from their node's commit log produce no notification.: WHEN a leased pipeline’s run writes its manifest and its commit-log entry is absent, THEN no subscription notifies it.
• read.subscribe.commit-orderread.subscribe.commit-orderNotifications of one table arrive in ascending commit_seq, the order commit-order makes runs readable, and each committed run notifies exactly once per subscription.: WHEN a relational run commits events at commit_seq 5 before its group marker lands and a plain run commits at 6, THEN a subscription sends neither until the marker lands, then 5 before 6.

unsettled: Does a subscription under a credential horizon withhold runs committed after it and their stamps rather than refuse? owner: read-path affects: read.subscribe

unsettled: Does the networked transport carry context.subscribe as server notifications over a held stream? owner: read-path affects: read.subscribe

Shapes

The registered relation for one table:

CREATE OR REPLACE VIEW orders AS
SELECT * FROM (
  SELECT *, ROW_NUMBER() OVER (
    PARTITION BY order_id
    ORDER BY updated_at DESC, _ingested_at DESC, _run_id DESC, _row_seq DESC
  ) AS _rn
  FROM read_parquet(
    [ 'tables/orders/data/snapshots/snapshot-01773100800000000000/part-00000.parquet',
      'tables/orders/data/runs/run-0192/node-9f2c/part-00000.parquet' ],
    union_by_name = true
  )
) WHERE _rn = 1;

The response projection, with total_cents a BIGINT column:

{
  "columns": ["order_id", "total_cents", "placed_at"],
  "rows": [["A-8812", "1299", "2026-02-14T09:31:00Z"], ["A-8813", "9007199254740993", "2026-02-14T09:44:12Z"]],
  "truncated": true,
  "contextful.bounds": { "as_of": "2026-03-01T00:00:00Z", "inclusive": false },
  "contextful.resolved": {
    "daily_orders": {
      "build_id": "snapshot-01773100800000000000",
      "watermark": { "at": "2026-02-14T10:00:00Z", "inputs": { "orders": { "snapshot_id": null, "through": 7, "omitted": { "count": 1, "digest": "9f2c…" } } } }
    }
  },
  "contextful.policy.applied": { "rows_dropped": 12, "columns_masked": ["email"], "overfetch_rounds": 1 },
  "contextful.retrieval": {
    "window": 200, "candidates_prefloor": 200, "candidates": 61,
    "matched": 61, "returned": 20, "in_window": 14, "deduped": 3,
    "padded": 0, "floor": 2, "since": "2026-02-07"
  }
}

Per-row ranking fields: { "_score": 2, "_vscore": 0.71, "_in_window": true, "_date_basis": "published_at" }.

A template, and the tool it projects as:

[[query_templates]]
id         = "orders_by_region"
sql        = "SELECT region, sum(total_cents) FROM orders WHERE placed_at >= ? AND region = ? GROUP BY region"
parameters = ["since:timestamp", "region:string"]
max_rows   = 500

{ "name": "orders_by_region",
  "inputSchema": { "type": "object",
    "properties": { "since": { "type": "string", "format": "date-time" }, "region": { "type": "string" } },
    "required": ["since", "region"] },
  "limits": { "max_rows": 500 } }