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

Reading and memory — card

Generated by contextful-spec state from the contract’s files and spec/terms/read.toml; not authored.

Operations

Operation	Covers	Clauses
`register`	Registered relations, query tools, templates, the embedded SQL engine and HTTP transport.	43
`guard`	SQL validation, allowed relations, operator statements and template arguments.	15
`respond`	Response fields, cell encoding, row and byte limits, truncation and diagnostic metadata.	24
`query`	The operator’s raw statement verb on the command line: its arguments, the relations it registers, its row bound and its output.	11
`reference`	Resolution of one stored citation through the caller’s registered relation, including the authenticated distinction between an erased source and an absent version.	5
`lineage`	The applied dataflow graph narrowed to the relations one caller’s session registers, whole or walked from one table.	6
`retrieve`	Candidate rows for ranked retrieval: query tokens, relevance thresholds, per-table queries, deduplication and snippets.	38
`rank`	Candidate ordering by vector and lexical scores, timeframe and reported confidence.	17
`cache`	Locality of the bytes a read touches, reuse of a resolved session and its connections, and reuse of a result across requests.	15
`resolve-pin`	Resolution of a named published-model build at read time, and the state each response echoes.	9
`embed`	Embedding implementations, stored model identifiers, query-model checks, build identity and missing-backend errors.	6
`as-of-join`	Point-in-time `ASOF JOIN` statements and templates that match rows by their availability timestamps.	3
`horizon`	Reads under `horizon`: default time bounds, rejected arguments, hidden metadata, network restrictions and selection of indexes, embedding models and builds.	10
`subscribe`	Committed-run notifications, durable replay, resume positions, queue limits and the subscription CLI.	13
`declare`	Memory table schemas, required columns, trust tiers, scopes and relation types.	6
`synthesize`	Claim extraction, entity resolution, consolidation, evidence, deduplication, audit records and coverage gaps.	10
`revise`	Claim replacement within a validity interval, confidence decay, direct writes, timestamps, expiry, retention and promotion.	15
`recall`	Ranked and keyed claim retrieval, read timestamps, tier ordering, scope and tombstone filters, and evidence checks.	23
`resolve-entity`	Entity matching, aliases, identity cards, location relationships, edges and ownership queries.	17
`settle`	Prediction registration, observations, required verdict citations and outcome label views.	17
`traverse`	Graph traversal from a seed entity, bounded by time, hop count and readable edges in the caller’s session.	14

Error cases

Error	When	Clause
`FilePreviewNotATable`	A previewed path resolved to no table.	`read.register.file-preview-target`
`LedgerNotTenantScoped`	A tenant-scoped token named the request-ledger child relation.	`read.register.scoped-ledger`
`ServeDeclarationMissing`	The network transport was started with no audience or no positive in-flight ceiling.	`read.register.serve-declaration`
`HttpCredentialMissing`	A network transport request carried no credential.	`read.register.credential-missing`
`StatementNotReadOnly`	Admitted text did not parse to exactly one read-only SELECT.	`read.guard.single-read-only-statement`
`TableFunctionRefused`	A table function or a schema-qualified catalog reach appeared in caller text.	`read.guard.table-function`
`TemplateNamesForeignRelation`	A template named a non-store relation or collided with a built-in tool prefix.	`read.guard.template-relation-shape`
`TemplateArgumentRejected`	A template argument was missing, unknown or mistyped.	`read.guard.template-binding`
`QueryParameterRejected`	A query parameter was missing, unused, untyped or mistyped.	`read.guard.query-binding`
`ReadDurationExceeded`	A statement reached its selected duration ceiling.	`read.respond.duration-ceiling`
`ReadResponseTooLarge`	A response envelope or first row exceeds its selected byte ceiling.	`read.respond.byte-ceiling`
`QueryNotOneStatement`	Operator text held other than exactly one statement.	`read.query.one-statement`
`QueryProjectAbsent`	A `--project` named no store on disk.	`read.query.project-store`
`RetrieveTableUnavailable`	A ranked read listed a table name outside the session’s relations.	`read.retrieve.table-list`
`FilterBudgetExceeded`	A ranked read’s filter exceeded its value, condition or byte budget.	`read.retrieve.filter-budget-refusal`
`ReadPartUnavailable`	A part a statement touches did not download within its wait.	`read.cache.miss-wait`
`PinnedBuildUnavailable`	A pinned build identifier is unknown or collected.	`read.resolve-pin.unknown-build`
`RequiredFaceAbsent`	A client required a face this binary did not link.	`read.embed.required-face`
`ReadBackendAbsent`	A read tool was called on a binary without the embedded SQL engine.	`read.embed.absent-read-backend`
`ReadBoundExceedsHorizon`	A call’s `available_as_of` or `since` falls later than its credential’s horizon.	`read.horizon.exceeds-horizon`
`ReadNoBuildWithinHorizon`	A model table holds no build whose recorded horizon is at or before the credential’s.	`read.horizon.build-resolution`
`SubscriptionPositionUnavailable`	A subscription’s `after` position names no committed run of its table.	`read.subscribe.position-unavailable`
`SubscriptionUnderHorizon`	A tool-protocol subscription arrived under a credential carrying a horizon.	`read.subscribe.horizon-refusal`
`MemoryShapeColumnMissing`	A table naming a memory shape omits a canonical column.	`read.declare.canonical-column`
`MemoryUndeclaredRelation`	A candidate edge carries an undeclared relation type.	`read.declare.undeclared-relation`
`MemoryExtractExhausted`	An extract batch exhausted its attempts and was dead-lettered.	`read.synthesize.dead-letter`
`MemoryDirectWriteShapeRefused`	A direct write targeted a memory shape other than claims.	`read.revise.direct-write`
`MemoryObservationOutOfOrder`	A claim was observed before a live contradicting claim of its line.	`read.revise.observed-order`
`MemoryCitationNotLive`	A direct write cites a keyed row that is not its key’s live version.	`read.revise.citation-live`
`MemoryClaimScopeRefused`	A served claim write names another actor or reading session.	`read.revise.served-scope`
`MemoryClaimBrowserRefused`	A browser-origin request reached the served claim-write route.	`read.revise.browser-request`
`MemoryClaimMalformed`	A served claim write holds a malformed or client-scoped body.	`read.revise.malformed-request`
`MemoryClaimWriteRefused`	A served claim write’s store effect refused.	`read.revise.served-fault`
`MemoryEvidenceUnresolved`	A claim’s evidence does not resolve through the caller’s session.	`read.recall.evidence-unresolved`
`MemoryEvidenceOverflow`	A claim names more evidence entries than the gate bound.	`read.recall.evidence-gate-bound`
`MemoryRecallNotClaims`	A keyed recall named a table declaring no `memory_facts` shape.	`read.recall.keyed-not-claims`
`MemoryEntityAmbiguous`	A mention resolves onto two identities with no separating key.	`read.resolve-entity.ambiguous-mention`
`MemoryEdgeEndpointUnresolved`	A candidate edge endpoint resolves to no identity.	`read.resolve-entity.edge-endpoint`
`MemoryExplainNotEntities`	A knowledge card named a table declaring no `memory_entities` shape.	`read.resolve-entity.card-not-entities`
`MemoryEntityFieldEmpty`	An entity upsert carried an id, kind, name or alias empty after trimming.	`read.resolve-entity.upsert-fields`
`MemoryEntityAliasConflict`	An entity upsert names a name or alias another entity already carries.	`read.resolve-entity.alias-conflict`
`MemoryEntityTableTruncated`	An entity upsert’s session read of its table returned truncated.	`read.resolve-entity.upsert-whole-table`
`MemoryEntityAvailabilityDeclared`	An entity upsert targeted a table declaring `available_time`.	`read.resolve-entity.upsert-availability`
`OutcomeRegistrationInvalid`	A prediction registration breaks the one-form, one-source, comparator-iff-metric rule.	`read.settle.registration`
`OutcomeSourceMismatch`	An observation’s verdict carries no source or a source other than the registration’s.	`read.settle.source-mismatch`
`OutcomeCitationMissing`	A judgment verdict carries no http or https settling citation.	`read.settle.settling-citation`
`OutcomeStatementTooLong`	A registration’s statement exceeds its byte bound.	`read.settle.statement-bound`
`OutcomeMetricReferenceInvalid`	A registration’s metric reference is malformed or names a series under a non-metric source.	`read.settle.metric-reference`
`OutcomePredictionUnregistered`	An observation names a prediction no stored registration the writer reads carries.	`read.settle.prediction-unregistered`
`OutcomeRegistrationConflict`	A registration reuses a stored prediction id with different fields.	`read.settle.registration-conflict`
`OutcomeAlreadySettled`	An observation differs from a stored outcome that already carries a verdict.	`read.settle.outcome-settled`
`MemoryTraverseNotEdges`	A traversal named a table that holds no memory edges.	`read.traverse.not-edges`
`MemoryTraverseRelationUnwalkable`	A traversal named a relation its declaration does not mark walkable.	`read.traverse.walkable`
`MemoryTraverseHopsExceeded`	A traversal asked for more hops than the bound.	`read.traverse.hop-bound`

Bounds

Bound	Value	Basis	Clause
`read-bytes-per-token`	4 B	chosen	`read.register.size-estimate`
`read-http-retry-after`	1 s	chosen	`read.register.past-ceiling`
`read-http-request-body`	1 MiB	chosen	`read.register.request-body`
`read-http-stop-drain`	20 s	chosen	`read.register.stop-drain`
`read-row-ceiling-overfetch`	1 rows	chosen	`read.respond.row-ceiling`
`read-face-row-ceiling`	10000 rows	chosen	`read.respond.face-ceiling`
`read-lineage-depth`	16 edges	chosen	`read.lineage.depth-bound`
`read-lineage-nodes`	1000 nodes	chosen	`read.lineage.node-page`
`read-relevance-floor-narrow`	1 tokens	chosen	`read.retrieve.relevance-floor`
`read-relevance-floor-split`	3 tokens	chosen	`read.retrieve.relevance-floor`
`read-relevance-floor-wide`	2 tokens	chosen	`read.retrieve.relevance-floor`
`read-token-length-floor`	2 chars	chosen	`read.retrieve.token-length-floor`
`read-content-token-cap`	12 tokens	chosen	`read.retrieve.token-cap`
`read-plural-suffix-floor`	4 chars	chosen	`read.retrieve.plural-suffix-floor`
`read-candidate-window-factor`	8 times	chosen	`read.retrieve.candidate-window`
`read-candidate-window-floor`	200 rows	chosen	`read.retrieve.candidate-window`
`read-filter-bytes`	16 KiB	chosen	`read.retrieve.filter-budget`
`read-filter-conditions`	32 conditions	chosen	`read.retrieve.filter-budget`
`read-filter-values`	256 entries	chosen	`read.retrieve.filter-budget`
`read-sidecar-probe-factor`	4 times	chosen	`read.retrieve.sidecar-oversampling`
`read-sidecar-probe-floor`	64 rows	chosen	`read.retrieve.sidecar-oversampling`
`read-sidecar-restricted-factor`	4 times	chosen	`read.retrieve.sidecar-oversampling`
`read-filtered-exact-rows`	4096 rows	chosen	`read.retrieve.filtered-exact-threshold`
`read-over-fetch-rounds`	4 rounds	chosen	`read.retrieve.adaptive-over-fetch`
`read-sidecar-node-mark`	4 B	chosen	`read.retrieve.sidecar-size-cap`
`read-sidecar-size-cap`	64 MiB	chosen	`read.retrieve.sidecar-size-cap`
`read-fulltext-sealed-cap`	256 MiB	chosen	`read.retrieve.fulltext-sealed-cap`
`read-fusion-lexical-weight`	40 percent	chosen	`read.rank.fusion`
`read-fusion-vector-weight`	60 percent	chosen	`read.rank.fusion`
`read-window-anchor-tolerance`	24 h	chosen	`read.rank.window-anchor-tolerance`
`read-lexical-index-cache`	64 entries	chosen	`read.rank.lexical-index-cache`
`read-part-wait`	30 s	chosen	`read.cache.miss-wait`
`read-session-pool-entries`	16 entries	chosen	`read.cache.pool-entries`
`read-session-pool-connections`	4 connections	chosen	`read.cache.pool-connections`
`read-subscribe-queue`	1000 notifications	chosen	`read.subscribe.overrun`
`memory-extract-attempts`	3 attempts	chosen	`read.synthesize.extract-attempts`
`memory-prompt-bytes`	32 KiB	chosen	`read.synthesize.prompt-bound`
`memory-row-chars`	16384 chars	chosen	`read.synthesize.row-cap`
`memory-evidence-references`	256 entries	chosen	`read.recall.evidence-references`
`memory-evidence-gate`	4096 entries	chosen	`read.recall.evidence-gate-bound`
`outcome-grace-window`	86400 s	chosen	`read.settle.grace-window`
`outcome-statement-bytes`	4096 B	chosen	`read.settle.statement-bound`
`memory-traverse-hops`	3 hops	chosen	`read.traverse.hop-bound`
`memory-traverse-fan-out`	64 memory-edges	chosen	`read.traverse.fan-out`
`memory-traverse-frontier`	512 memory-edges	chosen	`read.traverse.frontier-cap`

Types

Each struct or enum a {{type:<path>}} pointer names, with the keys serde reads and their doc comments.

`contextful_core::memory::revise::Tier`

The enum at crates/contextful-core/src/memory/revise.rs, named by read.revise.tier.

Key	Doc
`researched`
`derived`
`curated`

`contextful_core::read::subscribe::Notification`

The struct at crates/contextful-core/src/read/subscribe.rs, named by read.subscribe.notification.

Key	Doc
`table`
`run_id`
`node_id`
`committed_at`
`frontier`

Decisions

Section	Cited by
`A-read#agent-third-party`	`read.revise.direct-write`
`A-read#citation-keyed-table`	`read.recall.evidence-key`, `read.recall.evidence-no-value`, `read.recall.evidence-stale`
`A-read#claim-standing-derived`	`read.revise.tier`, `read.revise.supersede`, `read.revise.unscoped-collision`, `read.recall.confidence-label`, `read.recall.stale-revision`
`A-read#extraction-cache-keys`	`disclosure.erase.reader-frontier`
`A-read#filtered-vector-traversal`	`read.retrieve.filtered-traversal`, `read.retrieve.filtered-exact-threshold`
`A-read#gleaning-declared-single`	`read.synthesize.cadence`
`A-read#join-matches-availability`	`store.available-time.vintage-rows`, `read.as-of-join.per-row-bound`
`A-read#memory-access-follows`	`read.recall.evidence-unresolved`, `read.recall.evidence-references`, `read.recall.evidence-gate-bound`, `disclosure.erase.privilege`
`A-read#memory-confidence-retention`	`read.synthesize.confidence-calibration`, `read.revise.retention-default`
`A-read#memory-reads-expose`	`read.recall.usage-ledger`, `read.resolve-entity.graph-index`, `read.resolve-entity.ownership-answer`
`A-read#memory-vocabulary-schedules`	`read.declare.undeclared-relation`, `read.declare.reserved-relations`
`A-read#memory-writes-validate`	`read.synthesize.dead-letter`, `read.resolve-entity.ambiguous-mention`, `read.resolve-entity.edge-endpoint`, `read.settle.registration`, `read.settle.source-mismatch`, `read.settle.settling-citation`, `read.settle.calibration-report`
`A-read#nearness-parent-closure`
`A-read#networked-read-transport`	`read.register.network-transport`, `read.register.past-ceiling`, `read.register.per-request-admission`, `read.register.credential-missing`, `read.register.admission-refused`, `read.register.per-request-revocation`, `read.register.stateless-session`, `run.project.unauthenticated-upgrade`
`A-read#pooled-engine-reuses`	`read.register.tool-set`, `read.register.concurrent-statements`
`A-read#read-surface-admits`	`read.register.describe-zone`, `read.register.file-preview-target`, `read.register.scoped-ledger`, `read.guard.single-read-only-statement`, `read.guard.relation-allowlist`, `read.guard.unregistered-relation`, `read.guard.table-function`, `read.guard.statement-provenance`, `read.guard.template-relation-shape`, `read.guard.template-binding`, `read.respond.paths-stay-inside`, `read.reference.admission`, `read.reference.index-visibility`, `surface.package.stdio-credential`
`A-read#reciprocal-rank-calibrates`	`read.rank.calibration-gate`
`A-read#reranker-reorders-masked`
`A-read#restricted-sidecar-probe`	`read.retrieve.filter-budget-refusal`, `read.retrieve.excluded-arm`, `read.retrieve.adaptive-over-fetch`
`A-read#result-reused-under`	`read.reference.call`, `read.reference.erased-verdict`, `read.reference.frontier`, `read.cache.result-key`, `read.cache.cache-is-opt-in`, `read.cache.budget`, `read.cache.session-pool`, `read.cache.change-misses`
`A-read#served-claim-write`	`read.revise.served-write`, `read.revise.served-scope`, `read.revise.browser-request`, `read.revise.malformed-request`, `read.revise.served-dedup`, `read.revise.served-fault`
`A-read#sidecar-serves-past`	`store.index.filter-copies`, `read.horizon.rank-statistics`
`A-read#statement-owns-deadline`	`read.respond.duration-ceiling`, `read.respond.byte-ceiling`, `authority.grant.duration-ceiling`, `authority.grant.byte-ceiling`
`A-read#store-holds-nothing`	`authority.resist.credential-shaped-value`
`A-read#traversal-walks-enforced`	`read.traverse.walkable`, `read.traverse.hop-bound`, `read.traverse.fan-out`, `read.traverse.frontier-cap`
`A-read#zone-withheld-relation`	`read.respond.restriction-block`, `authority.place.excluded-disclosed`