compiler

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 21, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package rql implements RQL — a Starlark-hosted, governed SQL renderer — and the engine behind the `requel` CLI.

The design brief is blueprint 13: keep the trust boundary, guard system, and fan-out analysis, but host them in Starlark (deterministic, hermetic, recursion-free by construction) instead of a bespoke ML-family language.

The central adaptation is that Starlark has no tagged literals, so the trust boundary is carried by *types* instead of syntax: caller-supplied strings/dates/timestamps arrive as opaque *Val values that can only be interpolated (never used as SQL templates), while plain Starlark strings are authored-by-construction. A static check additionally pins every sql() call's template to a string literal.

Package compiler implements Requel's pure semantic compiler. Hosts import the curated root requel package, while the standalone product composes the same compiler through explicit application-facing contracts.

Index

Constants

View Source 
const (
	ActionEffectEmit          = "emit"
	ActionEffectCreateObject  = "create_object"
	ActionEffectSetProperties = "set_properties"
	ActionEffectSchedule      = "schedule"
	ActionEffectInvoke        = "invoke"
)
View Source 
const (
	BridgeEquality            = "equality"
	BridgeIntervalContainment = "interval_containment"
)

Cardinalities a bridge may declare. The two-sided spelling is deliberate: `join_one`/`join_many` describe what an edge does to the row count *in one direction*, which is what fan-out needs, while a correspondence between two value spaces is a property of the mapping itself and is read in both directions by whoever traverses it. Operators a bridge may declare. Equality is the default and the only one that needs no extra columns.

interval_containment exists because a structural domain lies INSIDE the region a chain maps to, and that correspondence is not an equality. Written as one it is false; written as a key join on the bound columns it is worse, because segment bounds are small integers that co-occur across unrelated proteins and the join reports a large overlap between ranges that share nothing but a number. Measured on SIFTS 2026-07-26: 55,857 of 55,956 SCOP2B domains are contained, and the equality spelling finds a different set entirely.

View Source 
const (
	// CoverageUnmeasured is the trivial bound. It is the DEFAULT, and it is
	// deliberately [0, 1] rather than zero: an absent measurement that read as
	// 0.0 would look like "nothing matches", which is a stronger claim than any
	// evidence supports and the exact direction a fail-open takes.
	CoverageUnmeasured = "unmeasured"
	// CoverageExact came from traversing every source key.
	CoverageExact = "exact"
	// CoverageSampled came from traversing a sample; lower and upper are the
	// interval's ends, not the point estimate.
	CoverageSampled = "sampled"
)

Coverage bases, closed so a basis nobody defined cannot silently mean "measured".

View Source 
const (
	// CardinalityExpected is a reviewer's declaration. It is the DEFAULT.
	CardinalityExpected = "expected"
	// CardinalityMeasured means both directions were counted over the certified
	// release pair.
	CardinalityMeasured = "measured"
)

Cardinality bases, closed for the reason the coverage bases are: a basis nobody defined must not be readable as "measured".

View Source 
const (
	GateOverGated  = gateOverGated
	GateUnderGated = gateUnderGated
)
View Source 
const (
	VUndecided = vUndecided
	VNeutral   = vNeutral
	VSound     = vSound
	VUnsafe    = vUnsafe
)
View Source 
const CatalogVersion = "rql.catalog.v2"
View Source 
const ChromaDialect = "chroma"

ChromaDialect is RetrievalDialect's Chroma twin: the driver name a Chroma entrypoint reports, for the same reason — the artifact is a Chroma query body, not turbopuffer's, and the inspect/audit surfaces must name the target they actually rendered.

View Source 
const DefaultMaxMemoryMB = 512

DefaultMaxMemoryMB is the per-evaluation heap budget when requel.toml declares none. Real ontologies assemble fragments measured in kilobytes; 512 MiB leaves three orders of headroom while keeping a runaway accumulation loop well inside what a developer laptop or CI runner absorbs without dying.

View Source 
const GraphMaxDepth = 5

GraphMaxDepth is the default hop cap. Cycles are reachable whenever two objects declare edges toward each other — which rung A's thunk form exists to make authorable — so enumeration is bounded on two axes: simple paths (no object repeats) and this depth.

View Source 
const GuardDenialCode = guardDenialCode

GuardDenialCode is the stable refusal emitted by fail_closed.

View Source 
const LangVersion = "0.2"

LangVersion is the RQL *language* version: the kernel surface, the value model, and the semantics a module can rely on. StdVersion is the *stdlib* version: the modules under std/ that `requel vendor` copies into a repo. They are pinned separately (requel.toml pins only `std`) and move independently — a stdlib release that adds a filter leaves the language untouched, and a kernel change lands without reshuffling every vendored tree. Report them separately too (`requel version`); conflating them makes the first divergence a lie.

View Source 
const MaxQueryResidues = maxQueryResidues

MaxQueryResidues is the bounded homology sequence length.

View Source 
const MaxSteps = 50_000_000

MaxSteps bounds evaluation of one render. Starlark bans recursion but NOT unbounded loops, so `for i in range(10**9)` would otherwise hang the CLI — and `requel` runs in CI over proposed changes, where a hang is an availability bug, not just a slow file. A no-loops/no-recursion rule would make termination structural; Starlark buys expressiveness and pays with a budget. Real ontologies use a few thousand steps; this leaves four orders of headroom while capping a runaway file at a few seconds.

View Source 
const MaxStructureQueryBytes = maxStructureQueryBytes

MaxStructureQueryBytes is the bounded Foldseek query size.

View Source 
const PublicAnnotation = "# rql:public"

PublicAnnotation is the source-level opt-out for a deliberately public relation. A reason is required by the guard-suggestion policy.

View Source 
const RetrievalDialect = "turbopuffer"

RetrievalDialect is what a retrieval entrypoint reports where a SQL one reports the project dialect. It is the driver name for the same reason the audit line carries it: the artifact is a turbopuffer query body, and naming the warehouse the repo happens to also use would describe a render that never happens.

View Source 
const StdVersion = "0.2"

StdVersion is the shipped stdlib version.

Variables

View Source 
var BlastHSPColumns = append([]string(nil), blastHSPColumns...)

BlastHSPColumns is the canonical BLAST tabular result contract.

View Source 
var Exceptions []Exception

Exceptions is the in-tree record shipped with the toolchain. It is empty: 0.1 and 0.2 broke no promise. The file still ships (written by `requel vendor`) so the process exists before it is needed — an exception mechanism invented during an incident is one that gets skipped.

View Source 
var Unrestricted = unrestrictedType{}

Unrestricted is the singleton guard sentinel (kernel-provided so the check in checkNamespaceGuard is an identity test, not a protocol).

View Source 
var ValidExceptionClasses = map[ExceptionClass]bool{
	ExceptSecurity:          true,
	ExceptUnspecified:       true,
	ExceptSpecContradiction: true,
}

ValidExceptionClasses is the closed set. Adding a class is a blueprint amendment, not a code change.

Functions

func AuditBridgeNames 

func AuditBridgeNames(bridges []RenderBridge) []string

AuditBridgeNames renders a render's correspondences for the audit line: name order, with `!` marking the lossy ones.

One field rather than two because a reader brings one question — an absent row in this result may be a gap in a mapping rather than an absence in the data, and knowing which mapping is what makes it checkable. The marker is a suffix rather than a nested object because the trail is one line per execution and every other evidence field on it is a scalar or a flat list.

func AuditContext 

func AuditContext(ctx *Context) audit.Context

AuditContext projects semantic context onto the stable audit attribution contract shared by the compiler and standalone runtime.

func BackingAlias 

func BackingAlias(left, right string) bool

BackingAlias reports whether two names are accepted aliases of one backing.

func BridgeCovers 

func BridgeCovers(bridge *Bridge, left *Relation, leftColumn string, right *Relation, rightColumn string) bool

BridgeCovers reports whether a certified equality bridge covers a column pair.

func BridgeExports 

func BridgeExports(files map[string]string) map[string]map[string]bool

BridgeExports maps a module path to the names it binds from a `bridge()` call, so the repo-wide lint can tell a load-bearing bridge import from an unused one.

Syntactic and repo-wide, mirroring RelationDeclSites, because that is the posture the whole lint layer has: nothing here evaluates a module. A binding assigned from anything other than a literal top-level `bridge(…)` call is not claimed, so the fallback is the old over-report rather than a miss.

The map is keyed by the module's own label. A `load("/bridges/mesh.rql", …)` names the module it imports from, so the answer is exact rather than a repo-wide pool of names that happen to be bridges somewhere.

func BridgeLine 

func BridgeLine(bridge BridgeDecl) string

BridgeLine renders one traversed bridge for explain output.

func BuildCatalogRepository 

func BuildCatalogRepository(repository *Repository, manifest *Manifest) (*Catalog, *Diagnostic)

BuildCatalogRepository builds the strict catalog from an immutable source snapshot.

func BuildCatalogRepositoryWithRuntime 

func BuildCatalogRepositoryWithRuntime(repository *Repository, manifest *Manifest, runtime *CatalogRuntime) (*Catalog, *Diagnostic)

BuildCatalogRepositoryWithRuntime overlays standalone readiness on a catalog compiled exclusively from an immutable repository snapshot.

func BuildCatalogRepositoryWithVocabulary added in v0.3.0 

func BuildCatalogRepositoryWithVocabulary(repository *Repository, manifest *Manifest, vocabulary *ActionVocabulary) (*Catalog, *Diagnostic)

BuildCatalogRepositoryWithVocabulary builds the catalog with the host's capability vocabulary in hand, so the emits/invokes halves of action effect envelopes validate at load beside everything else. A nil vocabulary leaves those members to the host's own registries.

func BuildMonoOrigins 

func BuildMonoOrigins(plan *function.Plan, nodes map[string]function.Node) map[string]map[string]string

BuildMonoOrigins traces monotone group measures through a function plan.

func CanonicalExampleValue 

func CanonicalExampleValue(value any) string

CanonicalExampleValue renders stable JSON for fixture and diff output.

func CanonicalJSON 

func CanonicalJSON(s string) (string, bool)

CanonicalJSON re-encodes a JSON document with sorted object keys and no insignificant whitespace — the retrieval analog of Normalize: two spellings of the same body compare equal, and anything else does not. Returns ok = false when s is not JSON at all, so callers can fall back to a string comparison that will fail with both texts visible.

func CanonicalOpList 

func CanonicalOpList() []string

CanonicalOpList returns the closed filter-operator vocabulary.

func CheckGuardResult 

func CheckGuardResult(file string, inst Instance, pred starlark.Value) (*Fragment, *Diagnostic)

CheckGuardResult validates what a guard lambda handed back, returning the predicate fragment to inject or the diagnostic that refuses the render.

It is separate from the injection loop above because `requel explain --personas` evaluates the same guards to build its matrix, and a matrix that printed a predicate `requel render` refuses would be worse than no matrix: the two disagreeing is exactly the confusion a security review cannot resolve. One definition of "a valid guard predicate", used by both.

func ClaimsEveryNull 

func ClaimsEveryNull(predicate function.Predicate, column string) bool

ClaimsEveryNull proves that a predicate accepts every null for one column.

func CoNullGroups 

func CoNullGroups(plan *function.Plan) map[string][][]string

CoNullGroups returns column groups whose nullability is correlated.

func CompileDatasetList 

func CompileDatasetList(request DatasetListCompileRequest) (*DatasetRenderResult, *Diagnostic)

CompileDatasetList compiles a bounded read over a closed, host-declared dataset contract. It deliberately reuses the object filter, sort, property, and lowering machinery: Requel has one semantic query compiler even when a host offers both ontology objects and raw-source inspection.

func CompileDerivedRelation 

func CompileDerivedRelation(request DerivedRelationCompileRequest) (*DerivedRelationRenderResult, *Diagnostic)

CompileDerivedRelation validates one immutable read-only query, closes its relation namespace, discovers logical dependencies, and places only table references through the compiler's SQL scanner.

func CompileObjectAggregate 

func CompileObjectAggregate(request ObjectAggregateCompileRequest) (*ObjectAggregateRenderResult, *Diagnostic)

CompileObjectAggregate compiles the bounded generic aggregate surface over the same authorized and decorated source used by list/get/traversal.

func CompileObjectGet 

func CompileObjectGet(request ObjectGetCompileRequest) (*ObjectRenderResult, *Diagnostic)

func CompileObjectKeyProbe 

func CompileObjectKeyProbe(request ObjectKeyProbeCompileRequest) (*ObjectKeyProbeRenderResult, *Diagnostic)

CompileObjectKeyProbe returns at most one duplicated declared key. It is a release/startup integrity probe, not part of ordinary object reads.

func CompileObjectList 

func CompileObjectList(request ObjectListCompileRequest) (*ObjectRenderResult, *Diagnostic)

func CompileObjectTraversal 

func CompileObjectTraversal(request ObjectTraversalCompileRequest) (*ObjectRenderResult, *Diagnostic)

CompileObjectTraversal renders one declared direct or composed edge as one governed SQL statement. It never fetches the source row first and never invents a path from an object pair.

func CompileStudioFunction 

func CompileStudioFunction(repository *Repository, manifest *Manifest, file string, params map[string]any) (*StudioFunction, *Diagnostic)

CompileStudioFunction compiles one function entrypoint with caller params. When params is nil, the first authored example supplies deterministic defaults.

func ConnectorShapeViolation 

func ConnectorShapeViolation(name string, connector manifest.Connector) string

ConnectorShapeViolation reports the first invalid connector shape field.

func ContainmentShape 

func ContainmentShape(bridge *Bridge) string

ContainmentShape renders the certified interval-containment predicate.

func ContractNameList 

func ContractNameList(columns []function.ResultColumn) string

ContractNameList formats a result contract for diagnostics.

func EmbeddedStandardLibrary 

func EmbeddedStandardLibrary() embed.FS

EmbeddedStandardLibrary returns the exact standard-library filesystem used by the compiler. The standalone application projection consumes this value instead of embedding a second copy of the semantic sources.

func ExactAtLines 

func ExactAtLines(infos []SelectableInfo) []string

ExactAtLines renders deduplicated exact-grain disclosures.

func ExampleFailureText 

func ExampleFailureText(diagnostic *Diagnostic) string

ExampleFailureText renders a diagnostic with its help and cause chain.

func ExampleRunsUnder 

func ExampleRunsUnder(ex *Example, dialect string) bool

ExampleRunsUnder reports whether an example applies to a dialect.

func ExitCode 

func ExitCode(code string) int

ExitCode maps a diagnostic code to the CLI exit-code table (blueprint 13 §7): 

0 ok · 1 findings · 2 usage/config · 3 input validation · 4 load/eval
5 analysis · 6 connector

func Explain 

func Explain(repository *Repository, man *Manifest, path string) (*ExplainDoc, *Diagnostic)

Explain summarizes an entrypoint's security-relevant structure.

func FilterValue 

func FilterValue(raw any) starlark.Value

FilterValue converts a runtime filter operand into its compiler value.

func FoldseekResultUnit 

func FoldseekResultUnit(method string) string

FoldseekResultUnit returns the governed result unit for a method.

func FormatExceptions 

func FormatExceptions(entries []Exception) string

FormatExceptions renders api-except.txt. The header explains the file to whoever opens it during an incident, which is when it will be read.

func FormatFloat 

func FormatFloat(value float64) string

FormatFloat renders a numeric literal using the compiler's canonical form.

func FunctionColumnNames 

func FunctionColumnNames(columns []function.ResultColumn) []string

FunctionColumnNames projects a result schema to its ordered column names.

func FunctionEvidenceText 

func FunctionEvidenceText(node function.Node) string

FunctionEvidenceText describes the evidence carried by one function node.

func FunctionGoldenCanonical 

func FunctionGoldenCanonical(s string) (string, bool)

FunctionGoldenCanonical normalizes function plan JSON for golden comparison.

func FunctionInspectDocument 

func FunctionInspectDocument(plan *function.Plan) map[string]any

FunctionInspectDocument projects a function plan into its inspect document.

func FunctionParamJSON 

func FunctionParamJSON(v starlark.Value) (any, error)

FunctionParamJSON projects one compiler value into function plan data.

func FunctionPredicateText 

func FunctionPredicateText(predicate *function.Predicate) string

FunctionPredicateText renders a function predicate for inspect and explain.

func GuardMatrix 

func GuardMatrix(repository *Repository, man *Manifest, path string, ps []personas.Persona) (*GuardMatrixDoc, *Diagnostic)

func GuardsWithoutSlot 

func GuardsWithoutSlot(frag *Fragment) []string

GuardsWithoutSlot reports the backings of guarded relation instances sitting in a scope that has no where-slot, so their guards have nowhere to go. It is the structural half of the check injectScope performs, factored out so `requel explain` can report the condition without evaluating any guard lambda — explain is context-free and must stay that way.

func HomologyColumnDomain 

func HomologyColumnDomain(spec *HomologySpec, name string) []function.ColumnLabel

HomologyColumnDomain returns the closed label domain declared for one homology result column.

func HomologyContains 

func HomologyContains(values []string, value string) bool

HomologyContains reports membership in a homology vocabulary list.

func HomologyCoordinateSpace 

func HomologyCoordinateSpace(kind string) string

HomologyCoordinateSpace returns the query coordinate system for a kind.

func HomologyDatabaseCoordinateSpace 

func HomologyDatabaseCoordinateSpace(kind string) string

HomologyDatabaseCoordinateSpace returns the database coordinate system for a kind.

func HomologyFiltersUnsupportedReason 

func HomologyFiltersUnsupportedReason(engine string) string

HomologyFiltersUnsupportedReason explains why an engine cannot apply filters.

func HomologyFunctionSchema 

func HomologyFunctionSchema(spec *HomologySpec) function.Schema

HomologyFunctionSchema returns the function schema for a homology request.

func HomologyMethods 

func HomologyMethods() map[string]HomologyMethodSpec

HomologyMethods returns a shallow copy of the compiler capability table.

func Human 

func Human(d *Diagnostic, src string) string

Human renders a diagnostic with an optional source snippet.

func IdentNeedsQuote 

func IdentNeedsQuote(name string) bool

IdentNeedsQuote reports whether a dialect-neutral identifier needs quoting.

func IsEntrypoint 

func IsEntrypoint(src string) bool

IsEntrypoint reports whether a source file declares params()/query().

func LeadingDoc 

func LeadingDoc(src string) string

LeadingDoc returns the first line of an entrypoint's leading documentation.

func LeadingDocBlock 

func LeadingDocBlock(src string) string

LeadingDocBlock returns an entrypoint's complete leading documentation.

func LoadManifestRepository 

func LoadManifestRepository(repository *Repository) (*Manifest, *Diagnostic)

LoadManifestRepository reads and validates the manifest from an immutable repository snapshot.

func LossyBridgeNames 

func LossyBridgeNames(bridges []RenderBridge) []string

LossyBridgeNames filters a render's correspondences to the ones whose absences carry no information. A complete correspondence carries every row, so an absent match over one is an absence in the data — precisely the claim a function is allowed to make.

func MMseqsTaxonomyRQLColumns 

func MMseqsTaxonomyRQLColumns() []string

MMseqsTaxonomyRQLColumns returns the fixed MMseqs taxonomy result columns.

func MarkFunctionArmCoverage 

func MarkFunctionArmCoverage(plan *function.Plan, tables map[string]*function.Table, covered map[string]bool)

MarkFunctionArmCoverage records decision arms reached by fixture tables.

func MarkFunctionThresholdCoverage 

func MarkFunctionThresholdCoverage(plan *function.Plan, tables map[string]*function.Table, covered map[string]bool)

MarkFunctionThresholdCoverage records the boundary families covered by the observed function tables.

func MatchGlob 

func MatchGlob(glob, s string) bool

MatchGlob matches a backing string against a glob supporting `*`.

Matching is **case-insensitive**, because unquoted SQL identifiers are: `FROM WAREHOUSE.ACCT` and `FROM warehouse.acct` name the same table on every supported engine. A case-sensitive glob therefore did not merely miss a spelling — it let a hand-written reference in different letter case walk past a `[guards].require` entry entirely, so the required guard was silently skipped. A fail-open defeated by holding shift (blueprint 14 §12 S13, cross-ported with internal/analysis).

func MatchesAnyBacking 

func MatchesAnyBacking(backings []string, name string) bool

MatchesAnyBacking reports whether a name matches any declared backing.

func MaxEmittedLimit 

func MaxEmittedLimit(limits []int) int

MaxEmittedLimit returns the conservative bound from emitted SQL limits.

func MemoryBudgetBytes 

func MemoryBudgetBytes(man *Manifest) int64

MemoryBudgetBytes resolves the configured compiler evaluation budget for runtime adapters that enforce the same process boundary.

func MissingFixtureHelp 

func MissingFixtureHelp(plan *function.Plan, node function.Node) string

MissingFixtureHelp explains the least ambiguous fixture key for a call node.

func MissingFunctionArmLabels 

func MissingFunctionArmLabels(arms map[string]FunctionArm, covered map[string]bool) []string

MissingFunctionArmLabels returns stable labels for uncovered decision arms.

func MissingFunctionThresholdMessages 

func MissingFunctionThresholdMessages(thresholds map[string]FunctionThreshold, covered map[string]bool) []string

MissingFunctionThresholdMessages reports uncovered non-residual families.

func NamespaceProtections 

func NamespaceProtections(repository *Repository) (guarded, pinned []string, err error)

NamespaceProtections returns guarded and identity-pinned namespaces.

func Normalize 

func Normalize(s string) string

Normalize collapses whitespace runs *between tokens* to a single space, for golden comparison (layout-insensitive, semantically strict).

Whitespace inside a string literal, a quoted identifier, or a dollar-quoted body is **data**, and is copied through verbatim. Collapsing it made `SELECT 'a b'` and `SELECT 'a b'` compare equal, which matters twice over here: `Normalize` decides golden pass/fail in `run.go`, and it is also what `requel diff` uses to decide whether two renders differ at all (diff.go). A literal-blind comparison therefore told a *reviewer* "no change" for a change that altered a rendered literal's contents. [12 §1.9 L2] leaves whitespace between tokens unspecified — it says nothing about whitespace inside a token, because there it is not formatting.

Cross-ported from internal/render (blueprint 13 §9.2 round thirteen, second open finding). The two implementations must agree: differential_test.go normalizes each engine's SQL with its own Normalize and then compares the results, so a divergence between the normalizers is a divergence in the oracle itself. TestNormalizersAgree pins that.

Known limit: quote state is tracked with the SQL-standard doubled-quote escape only. On dialects that also honour backslash escapes a `\'` inside a literal is read as its end. That keeps Normalize deterministic (both sides of every comparison see the same function) but slightly less faithful there; making it exact would require the dialect, which callers do not have here.

func NormalizeIdents 

func NormalizeIdents(sql string) string

NormalizeIdents removes inert SQL text while preserving reference spellings.

func NotAdditiveLines 

func NotAdditiveLines(infos []SelectableInfo) []string

NotAdditiveLines renders deduplicated non-additivity disclosures.

func NoteScopedFunctionSkips 

func NoteScopedFunctionSkips(w io.Writer, labels []string)

NoteScopedFunctionSkips writes the CLI disclosure for function declarations that cannot be plan-linted in a path-scoped run.

func NoteUnevaluatedModules 

func NoteUnevaluatedModules(w io.Writer, modules []string)

NoteUnevaluatedModules writes the CLI disclosure for a static-only lint run.

func NullableColumns 

func NullableColumns(schema function.Schema) map[string]bool

NullableColumns indexes nullable result columns by name.

func Placeholder 

func Placeholder(dialect string, ord int) string

Placeholder renders the dialect-specific placeholder for a 1-based bind ordinal. It is exposed for the standalone CLI's direct-SQL execution path; model compilation uses the same implementation through Lower.

func Predeclared 

func Predeclared(ctx *Context) starlark.StringDict

Predeclared builds the kernel scope shared by every RQL module.

func QuoteAlias 

func QuoteAlias(dialect, name string) string

QuoteAlias renders a result alias using the selected dialect.

func QuoteString 

func QuoteString(dialect, value string) string

QuoteString renders one dialect-safe SQL string literal.

func RelationIndex 

func RelationIndex(files map[string]string) map[string]RelDecl

RelationIndex folds every repo `relation(backing=…, guard?=…)` call into the backing→declaration map that powers the RQL3003 bypass lint and the schema probe. It is pure syntax (no evaluation), so it works across files that never import one another. A guarded declaration wins over an unguarded one for the same backing.

The scan itself is RelationDeclSites, which keeps its per-call-site detail: this map answers "what is known about this table", while the RQL3025 guard lint has to ask "what did the author write at *this* declaration", and one scanner serving both is one place that learns about a new `relation` keyword.

func Render 

func Render(req *Request) (*Result, *Diagnostic)

Render runs the full pipeline: load → validate → call query(p) → analyze → inject guards → lower (blueprint 13 §5.4).

func RepoGuardedBackings 

func RepoGuardedBackings(repository *Repository) ([]string, error)

RepoGuardedBackings returns backings protected anywhere in a repository.

func RepoGuardedNamespaces 

func RepoGuardedNamespaces(repository *Repository) ([]string, error)

RepoGuardedNamespaces returns namespaces guarded anywhere in a repository.

func RepoPinnedNamespaces 

func RepoPinnedNamespaces(repository *Repository) ([]string, error)

RepoPinnedNamespaces returns namespaces pinned by caller identity.

func RetrievalPosture 

func RetrievalPosture(r *ExplainRetrieval) string

RetrievalPosture describes declared retrieval isolation without implying that a guard was evaluated.

func SchemaFor 

func SchemaFor(decls []*ParamDecl) (map[string]any, map[string]string)

SchemaFor emits the params surface as JSON Schema 2020-12 plus the x-rql-required-messages extension.

func SnapshotTable 

func SnapshotTable(table *function.Table) *function.Table

SnapshotTable copies a function table retained for an intermediate assertion.

func SortFiles 

func SortFiles(files []string)

SortFiles orders discovered files deterministically.

func SourceUsesFunction 

func SourceUsesFunction(label, source string) bool

SourceUsesFunction reports whether source constructs a function entrypoint.

func StdModules 

func StdModules() []string

StdModules lists the standard library modules.

func StdSource 

func StdSource(mod string) (string, bool)

StdSource returns an embedded stdlib module's source.

func StdTests 

func StdTests() map[string]string

StdTests lists the stdlib self-test files (name → source). Vendored into _rql/std/tests/ so `requel test` runs them in every consuming repo — a vendor upgrade is verified where it landed (blueprint 13 R6, and the std/tests contract in [12 §8]).

func SuggestUndefined 

func SuggestUndefined(message string) string

SuggestUndefined enriches a Starlark undefined-name diagnostic.

func UnevaluatedModules 

func UnevaluatedModules(files []string, sources map[string]string) []string

UnevaluatedModules identifies loadable modules when the selected lint scope contains no entrypoint.

func UnhandledNullableCompares 

func UnhandledNullableCompares(predicate function.Predicate, nullable map[string]bool, groups [][]string) []string

UnhandledNullableCompares returns nullable columns whose null cases are not explicitly handled by a function predicate.

func UnmappedTargetHelp 

func UnmappedTargetHelp(man *Manifest, target string) string

UnmappedTargetHelp explains how to map a function target in the manifest.

func UsableMeasure 

func UsableMeasure(origin map[string]string, nullable map[string]bool) func(string) MonoDir

UsableMeasure returns the proven direction of non-null monotone measures.

Types

type Ack 

type Ack struct {
	Reason string
	Line   int
	// Edges are the join aliases inside the fragment this acknowledgement wrapped,
	// for allow_unbridged only. It is what makes *where* the ack was written
	// mean something: wrapping one join acknowledges that join, and wrapping the
	// whole view acknowledges the whole view.
	//
	// allow_fanout needs no equivalent and does not set it. Its reason defends one
	// claim — that a total is still correct across a multiplied row set — and a
	// query has one such situation. A correspondence reason is inherently about a
	// specific pair of columns, so a single sentence covering every crossing in a
	// query licenses claims the author never read. Measured: one reason reading
	// "the FIRST join is fine, I checked it" silenced an unrelated
	// genome-position-to-cDNA-position join in the same query.
	Edges []string
}

Ack records an allow_fanout or allow_unbridged acknowledgement.

type ActionContractValue added in v0.3.0 

type ActionContractValue struct {
	// contains filtered or unexported fields
}

ActionContractValue is the immutable nominal value returned by action.make. It is a compiled declaration and nothing more: what an action is named, the object it acts on or creates, its typed input, what it reads, and the closed effect envelope it may produce. Requel performs no host operation — its pure renderer can only return inert intents. The host that runs plans (authorization, reviews, transactions, the ledger, delivery) consumes this contract and remains the only place an action ever happens. The distinct Starlark type prevents an unrelated struct with similar attributes from posing as a declared action.

func (*ActionContractValue) Attr added in v0.3.0 

func (v *ActionContractValue) Attr(name string) (starlark.Value, error)

func (*ActionContractValue) AttrNames added in v0.3.0 

func (v *ActionContractValue) AttrNames() []string

func (*ActionContractValue) Freeze added in v0.3.0 

func (v *ActionContractValue) Freeze()

func (*ActionContractValue) Hash added in v0.3.0 

func (v *ActionContractValue) Hash() (uint32, error)

func (*ActionContractValue) String added in v0.3.0 

func (v *ActionContractValue) String() string

func (*ActionContractValue) Truth added in v0.3.0 

func (v *ActionContractValue) Truth() starlark.Bool

func (*ActionContractValue) Type added in v0.3.0 

func (v *ActionContractValue) Type() string

type ActionDecl added in v0.3.0 

type ActionDecl struct {
	Name  string
	Local string
	File  string
	Line  int
}

ActionDecl is one statically discovered `action.make(...)` assignment.

type ActionEffect added in v0.3.0 

type ActionEffect struct {
	Type       string           `json:"type"`
	Line       string           `json:"line"`
	Kind       string           `json:"kind,omitempty"`
	Subject    *ActionObjectRef `json:"subject,omitempty"`
	CausedBy   string           `json:"caused_by,omitempty"`
	Payload    map[string]any   `json:"payload,omitempty"`
	Target     *ActionObjectRef `json:"target,omitempty"`
	Properties map[string]any   `json:"properties,omitempty"`
	Action     string           `json:"action,omitempty"`
	After      string           `json:"after,omitempty"`
	Connection string           `json:"connection,omitempty"`
	Path       string           `json:"path,omitempty"`
}

ActionEffect is Requel's closed, execution-neutral write intent. It can name an authored event, object edit, scheduled action, or host operation, but it cannot contain a handler, credential, absolute endpoint, SQL, or transaction. Hosts independently validate this value before performing it.

type ActionInputValue added in v0.3.0 

type ActionInputValue struct {
	Kind       string
	Nullable   bool
	ObjectType string
	Reads      []string
	Doc        string
	Label      string
	Labels     []string
	Format     string
	Default    starlark.Value
	HasDefault bool
	Minimum    *float64
	Maximum    *float64
}

ActionInputValue is the nominal declaration accepted by action.make's input dictionary. Operational inputs are intentionally distinct from object properties: files, object references, and bounded object sets are not source-relation columns.

func (*ActionInputValue) Attr added in v0.3.0 

func (value *ActionInputValue) Attr(name string) (starlark.Value, error)

func (*ActionInputValue) AttrNames added in v0.3.0 

func (value *ActionInputValue) AttrNames() []string

func (*ActionInputValue) Freeze added in v0.3.0 

func (value *ActionInputValue) Freeze()

func (*ActionInputValue) Hash added in v0.3.0 

func (value *ActionInputValue) Hash() (uint32, error)

func (*ActionInputValue) String added in v0.3.0 

func (value *ActionInputValue) String() string

func (*ActionInputValue) Truth added in v0.3.0 

func (value *ActionInputValue) Truth() starlark.Bool

func (*ActionInputValue) Type added in v0.3.0 

func (value *ActionInputValue) Type() string

type ActionObjectRef added in v0.3.0 

type ActionObjectRef struct {
	ObjectType string `json:"object_type"`
	Key        string `json:"key"`
}

ActionObjectRef is the only object identity an action plan may carry. It is data, not a lookup capability: the host resolves and authorizes it before rendering and again before applying the returned effects.

type ActionRuntime added in v0.3.0 

type ActionRuntime struct {
	// contains filtered or unexported fields
}

ActionRuntime is one frozen action declaration paired with the pure functions it declared. Calls use a fresh Starlark thread and receive only the host-supplied target slice and input; the runtime has no I/O capability.

func (*ActionRuntime) Allowed added in v0.3.0 

func (runtime *ActionRuntime) Allowed(ref ActionObjectRef, target, input map[string]any) (bool, error)

func (*ActionRuntime) AllowedFor added in v0.3.0 

func (runtime *ActionRuntime) AllowedFor(subject string, roles []string, attrs map[string]any) (bool, error)

AllowedFor evaluates the model's semantic actor eligibility. It can only narrow: the embedding host remains responsible for checking its capability grant independently before consulting this predicate.

func (*ActionRuntime) Render added in v0.3.0 

func (runtime *ActionRuntime) Render(ref ActionObjectRef, target, input map[string]any) ([]ActionEffect, error)

Render evaluates only the authored effect function and then enforces the declaration's default-deny envelope. It performs no host operation.

func (*ActionRuntime) ReviewRequired added in v0.3.0 

func (runtime *ActionRuntime) ReviewRequired(ref ActionObjectRef, target, input map[string]any) (bool, error)

type ActionVocabulary added in v0.3.0 

type ActionVocabulary struct {
	Events      []string
	Connections []string
}

ActionVocabulary is the host capability catalog: the event kinds and outbound connection names a host's registries declare, injected at load so the emits and invokes halves of the effect envelope validate beside the rest. Names only — URLs, credentials, SQL, and handler implementations never enter the model. nil means the host validates those members itself.

type AggSpec 

type AggSpec struct {
	Name string
	Spec []any
}

AggSpec is one authored aggregate: a result column name and its wire spec (["Count"] or ["Sum", attribute]). Ordered by name at parse so the body and every document derived from it are deterministic.

type Aggregate 

type Aggregate struct {
	At   *Relation
	Line int
	// File is where Line was captured. See Edge.File.
	File string
	// Key is the registry key of the metric this aggregate computes, where one
	// named it. It exists for review rather than for rendering.
	//
	// `explain` printed one line per aggregate reading `at main.record`, so an
	// entrypoint selecting eight metrics reviewed as eight identical lines — five
	// of them carrying the same `allow_fanout` reason. That mechanism's whole
	// design is that "the reason is mandatory and survives into review", and a
	// reviewer who cannot tell which of five identical reasons defends which
	// measure cannot check any of them. `Line` does not help: every metric is
	// tagged at the single `aggregate(...)` call inside `rql:object`, so all
	// eight share one line number in the vendored stdlib.
	//
	// Empty for an aggregate tagged outside a metric registry — a hand-assembled
	// terminal fragment, which has no key to name.
	Key    string
	Acked  bool
	Reason string
}

Aggregate is an aggregation tagged with its grain relation.

type AliasIndex 

type AliasIndex struct {
	// contains filtered or unexported fields
}

AliasIndex resolves authored aliases without exposing its collision map.

func BuildAliasIndex 

func BuildAliasIndex(fragment *Fragment) AliasIndex

BuildAliasIndex builds exact and folded alias lookups for a fragment.

func (AliasIndex) Lookup 

func (index AliasIndex) Lookup(alias string) *Relation

Lookup resolves an alias exactly, or by folding when unambiguous.

type Atom 

type Atom struct {
	Kind   AtomKind
	Text   string
	Bind   Bind
	Preds  []*Fragment
	Guards []GuardPred
	Group  *Fragment
}

Atom is one piece of a fragment.

type AtomKind 

type AtomKind int

AtomKind classifies a fragment atom. 

const (
	AtomText  AtomKind = iota // literal SQL text
	AtomBind                  // a lowered value
	AtomWhere                 // a WHERE slot (guard-injection target)
	AtomGroup                 // a nested scope (subquery); guards inject per scope
)

type Bind 

type Bind struct {
	Kind     BindKind
	Raw      any
	Display  string
	Authored bool
}

Bind is a value lowered into SQL. Authored marks provenance from authored literals only: those inline as escaped literals in every render mode, so an authored constant can never become a runtime placeholder in a structural position (blueprint 13 §3.3).

type BindKind 

type BindKind string

BindKind classifies a lowered value's SQL type. 

const (
	BindString    BindKind = "string"
	BindInt       BindKind = "int"
	BindFloat     BindKind = "float"
	BindBool      BindKind = "bool"
	BindDate      BindKind = "date"
	BindTimestamp BindKind = "timestamp"
)

type BindOut 

type BindOut struct {
	Ordinal int    `json:"ordinal"`
	Type    string `json:"type"`
	Value   any    `json:"value"`
}

BindOut is one entry in the render bind list.

type Bridge 

type Bridge struct {
	ID       int
	Name     string
	Left     *Relation
	LeftKey  []string
	Right    *Relation
	RightKey []string
	// Operator is HOW the two ends are compared. Empty means equality, so every
	// bridge written before this field existed keeps its meaning.
	Operator string
	// LeftInterval and RightInterval are the [begin, end] columns an interval
	// operator compares. They are separate from the keys on purpose: the keys
	// stay the IDENTITY that partitions the axis, so a checker that only knows
	// equality still sees a correct, if incomplete, picture rather than a wrong
	// one built from bound columns.
	LeftInterval  []string
	RightInterval []string
	// Closed says which endpoints of the containing interval are inside.
	Closed string
	// Cardinality is declared, never inferred. `requel lint
	// --probe-cardinality` checks a join edge's promise against the warehouse;
	// nothing checks this one, because a bridge is reviewed against the two
	// *releases* it was certified over rather than against whatever the
	// connector happens to hold now — which is the job of the pin, not of a
	// live probe.
	Cardinality string
	// CardinalityBasis says whether Cardinality was COUNTED over those releases
	// or is the reviewer's expectation.
	//
	// The distinction earns a field because `cardinality` is the argument that
	// switches the fan-out guard off, and it sat unmarked beside coverage bounds
	// that carry an explicit basis — so a declaration could not tell a count from
	// a sentence, and the checker believed both equally. The generated
	// `astral-scope-40-in-95` is the case: it is emitted `one_to_one` while its
	// certification carries no right-to-left measurement at all, which told
	// Requel that each of 35,494 domains has at most one preimage on nobody's
	// evidence.
	//
	// The default is CardinalityExpected, not CardinalityMeasured: an absent
	// basis is the absence of a measurement, and defaulting the other way is the
	// fail-open this exists to close.
	CardinalityBasis string
	// Lossy marks a correspondence that does not cover every row on the left.
	// It is the property an absence claim turns on: "no match was found" over a
	// lossy bridge is indistinguishable from "the match exists and this mapping
	// does not carry it", so a function that concludes absence across one is
	// refused (RQL3051) for the reason a truncated search cannot support one.
	Lossy bool
	// LTRCoverage and RTLCoverage are what is KNOWN about each direction's
	// coverage, as an interval rather than a scalar.
	//
	// `Lossy` alone is one bit, and one bit cannot separate a correspondence
	// that carries 99.4% of its rows from one that carries 34%: both are
	// "lossy", and a reader given only the flag has no way to tell an
	// almost-complete mapping from a mostly-absent one. Direction was missing
	// entirely, so "nobody measured the reverse" and "the reverse is total"
	// looked identical.
	//
	// An interval rather than a number because the measurement ladder has rungs:
	// an exact traversal pins lower == upper, a sampled traversal reports a
	// confidence interval, and an unmeasured direction is the trivial bound
	// [0, 1]. The same field carries all three, so refining a bound later is new
	// numbers rather than a new format.
	LTRCoverage CoverageBound
	RTLCoverage CoverageBound
	// LeftRelease, RightRelease, CertifiedAt and Evidence are what the
	// correspondence was measured AGAINST, when the declaration knows.
	//
	// They exist because a generated declaration knows them and had no way to
	// say so: `requel bridges` wrote a skeleton per bridge and asked a human to
	// type in release identities the ontology had already certified and carried
	// into the generated file as a comment. Everything here is opaque to Requel
	// and compared, never parsed — the shape the lock already had.
	//
	// They are NOT in DeclarationDigest. Re-measuring the same declaration
	// against a newer release must not read as the declaration having moved,
	// which is RQL3050's whole distinction.
	LeftRelease  string
	RightRelease string
	CertifiedAt  string
	Evidence     string
	Doc          string
	File         string
	Line         int
}

Bridge is a declared correspondence between two relations' key columns.

Name is the ontology-facing identity and is what a lockfile pins, what `explain` prints and what RQL3048's help tells the author to write. It is taken from the declaration's own `name` rather than derived from the two backings, because a pair of relations may correspond in more than one way (an exact identifier mapping and a lossy positional one) and a derived name would collide precisely where the distinction matters.

func (*Bridge) Attr 

func (b *Bridge) Attr(name string) (starlark.Value, error)

Attr exposes read-only bridge fields. Read-only for the reason a relation's `require_filter` is: an ontology must not be able to edit the declaration the checker is about to hold it to.

func (*Bridge) AttrNames 

func (b *Bridge) AttrNames() []string

AttrNames lists bridge fields.

func (*Bridge) CardinalityBasisOrDefault 

func (b *Bridge) CardinalityBasisOrDefault() string

CardinalityBasisOrDefault reads an unstated basis as an expectation, so a bridge written before the field existed keeps meaning exactly what it meant.

func (*Bridge) Decl 

func (b *Bridge) Decl() BridgeDecl

Decl projects a bridge into its published form.

func (*Bridge) Freeze 

func (b *Bridge) Freeze()

func (*Bridge) Hash 

func (b *Bridge) Hash() (uint32, error)

func (*Bridge) OperatorOrDefault 

func (b *Bridge) OperatorOrDefault() string

OperatorOrDefault reads the comparison, defaulting to equality so a bridge written before the field existed keeps its meaning.

func (*Bridge) String 

func (b *Bridge) String() string

func (*Bridge) Truth 

func (b *Bridge) Truth() starlark.Bool

func (*Bridge) Type 

func (b *Bridge) Type() string

type BridgeDecl 

type BridgeDecl struct {
	Name        string   `json:"name"`
	Left        string   `json:"left"`
	LeftKey     []string `json:"left_key"`
	Right       string   `json:"right"`
	RightKey    []string `json:"right_key"`
	Cardinality string   `json:"cardinality"`
	// CardinalityBasis travels with the decl for the reason the coverage basis
	// does: `cardinality` is what turns the fan-out guard off, so a reviewer and
	// a lockfile both need to see whether it was counted or expected.
	CardinalityBasis string `json:"cardinality_basis"`
	Lossy            bool   `json:"lossy"`
	// Operator, the interval columns and the closure travel with the decl so a
	// lockfile pins WHAT was compared, not only which columns. A containment
	// published as a bare key pair would read as an equality downstream.
	Operator      string   `json:"operator"`
	LeftInterval  []string `json:"left_interval,omitempty"`
	RightInterval []string `json:"right_interval,omitempty"`
	Closed        string   `json:"closed,omitempty"`
	// LTRCoverage and RTLCoverage travel with the decl so a lockfile and a
	// review both see what was measured, not only that something was lossy.
	LTRCoverage CoverageBound `json:"ltr_coverage"`
	RTLCoverage CoverageBound `json:"rtl_coverage"`
	Doc         string        `json:"doc,omitempty"`
	// Namespaces is the label pair each key position corresponds across, in key
	// order, formatted `left_label -> right_label`. It is derived from the two
	// relations rather than declared on the bridge, because declaring it would
	// create a second place for the same fact to be written and a way for the
	// two to disagree.
	Namespaces []string `json:"namespaces,omitempty"`
}

BridgeDecl is one declared bridge, for `explain`, `inspect` and the lockfile.

func BridgeDecls 

func BridgeDecls(bridges []*Bridge) []BridgeDecl

BridgeDecls projects them for publication, sorted by name so the document is order-independent — a repository that reorders its `load()` calls must not produce a different `api.txt`.

func BridgesTraversed 

func BridgesTraversed(frag *Fragment, bridges []*Bridge) []BridgeDecl

BridgesTraversed lists the bridges a rendered fragment's edges actually use, sorted by name.

It is the reviewer-facing half of the mechanism: `explain` already names which relations an entrypoint reaches and which are unguarded, and this answers the question one layer down — which certified correspondences the answer depends on, and which of them are lossy.

type Catalog 

type Catalog struct {
	Object                string              `json:"object"`
	Version               string              `json:"version"`
	DefinitionFingerprint string              `json:"definition_fingerprint"`
	Project               CatalogProject      `json:"project"`
	Entrypoints           []CatalogEntrypoint `json:"entrypoints"`
	Relations             []CatalogRelation   `json:"relations"`
	Namespaces            []CatalogNamespace  `json:"namespaces"`
	Connectors            []CatalogConnector  `json:"connectors"`
	Targets               []CatalogTarget     `json:"targets"`
	AllowedFlows          []string            `json:"allowed_flows"`
	CapabilityEdges       []CatalogEdge       `json:"capability_edges"`
	Objects               []CatalogObject     `json:"objects"`
	Actions               []CatalogAction     `json:"actions,omitempty"`
	ObjectGraph           *GraphReport        `json:"object_graph"`
	Runtime               *CatalogRuntime     `json:"runtime,omitempty"`
}

type CatalogAction added in v0.3.0 

type CatalogAction struct {
	Name         string `json:"name"`
	Label        string `json:"label,omitempty"`
	Description  string `json:"description,omitempty"`
	DeniedReason string `json:"denied_reason,omitempty"`
	// Target and Creates are the two mutually exclusive subjects: exactly
	// one is set. Target names the declared object type an action acts on;
	// Creates names the type whose record it births.
	Target  string `json:"target,omitempty"`
	Creates string `json:"creates,omitempty"`
	// Inputs is the typed surface a caller may supply, sorted by name.
	Inputs []CatalogActionInput `json:"inputs"`
	// Reads names target properties the effects and predicates may see.
	Reads []string `json:"reads"`
	// The effect envelope, default-deny: what the effects may produce.
	// Writes members are "Object.property" and must name declared writable
	// properties; Schedules members must name declared actions. Emits and
	// Invokes name host vocabularies (event kinds, connections) the host
	// validates against its own registries.
	Emits     []string `json:"emits"`
	Writes    []string `json:"writes"`
	Schedules []string `json:"schedules"`
	Invokes   []string `json:"invokes"`
	// AllowedFor is semantic narrowing over a host-supplied principal. The
	// host's capability grant remains an independent ceiling.
	AllowedForShape string `json:"allowed_for_shape"`
	// AllowedIfShape and RequiresReviewShape record how each row predicate
	// was declared — always, never, or conditional — never its verdict,
	// which is a question about data.
	AllowedIfShape      string `json:"allowed_if_shape"`
	RequiresReviewShape string `json:"requires_review_shape"`
	// AllowedIf and RequiresReview carry the structured predicate tree when
	// the declaration used the closed vocabulary (shape "structured"), with
	// the catalog's deterministic text rendering beside each. A host can
	// evaluate the tree directly — no Starlark in the loop — and a reviewer
	// reads the text. Opaque function predicates leave these empty.
	AllowedIf          *CatalogActionPredicate `json:"allowed_if,omitempty"`
	AllowedIfText      string                  `json:"allowed_if_text,omitempty"`
	RequiresReview     *CatalogActionPredicate `json:"requires_review,omitempty"`
	RequiresReviewText string                  `json:"requires_review_text,omitempty"`
	CorrelationFrom    string                  `json:"correlation_from,omitempty"`
	// Dependencies names every object type this contract touches — its
	// subject, the objects its writes members address, and the objects its
	// reference inputs name — deduplicated and sorted. This is what lets
	// "who depends on this object?" include the constructs that mutate it,
	// not only the ones that read it.
	Dependencies []string `json:"dependencies"`
	File         string   `json:"file"`
	Line         int      `json:"line"`
}

CatalogAction is one compiled action contract: the reviewable description of a governed write, produced by `action.make` and validated against the object catalog it references. It is a declaration, not an operation — requel executes nothing, so the catalog can state what an action is without ever being able to perform it, which is exactly what makes it trustworthy as a review artifact.

type CatalogActionInput added in v0.3.0 

type CatalogActionInput struct {
	Name         string   `json:"name"`
	Type         string   `json:"type"`
	IsNullable   bool     `json:"is_nullable,omitempty"`
	ObjectType   string   `json:"object_type,omitempty"`
	Reads        []string `json:"reads,omitempty"`
	Doc          string   `json:"doc,omitempty"`
	Label        string   `json:"label,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	Format       string   `json:"format,omitempty"`
	DefaultValue any      `json:"default,omitempty"`
	HasDefault   bool     `json:"has_default,omitempty"`
	Minimum      *float64 `json:"min,omitempty"`
	Maximum      *float64 `json:"max,omitempty"`
}

CatalogActionInput is the complete caller-input contract. ObjectType and Reads are populated for typed references and bounded object sets.

type CatalogActionPredicate added in v0.3.0 

type CatalogActionPredicate struct {
	Kind     string                   `json:"kind"`
	Column   string                   `json:"column,omitempty"`
	Op       string                   `json:"op,omitempty"`
	Value    any                      `json:"value,omitempty"`
	Input    string                   `json:"input,omitempty"`
	Children []CatalogActionPredicate `json:"children,omitempty"`
}

CatalogActionPredicate is one node of the closed predicate vocabulary — compare | all | any | not — the same algebra function conditions use, instantiated for actions: Column names a subject property, and the operand is a literal Value or the name of a declared caller Input.

type CatalogConnector 

type CatalogConnector struct {
	Name    string `json:"name"`
	Driver  string `json:"driver"`
	Kind    string `json:"kind"`
	Dialect string `json:"dialect,omitempty"`
}

CatalogConnector is configuration, never connection state. In particular it deliberately carries no DSN environment-variable name: even a secret's location is operator configuration, not an agent capability.

type CatalogDimension 

type CatalogDimension struct {
	Key   string `json:"key"`
	Type  string `json:"type"`
	Label string `json:"label,omitempty"`
	Doc   string `json:"doc,omitempty"`
}

type CatalogEdge 

type CatalogEdge struct {
	From     string `json:"from"`
	FromKind string `json:"from_kind"`
	To       string `json:"to"`
	ToKind   string `json:"to_kind"`
	Kind     string `json:"kind"`
	Step     string `json:"step,omitempty"`
	Target   string `json:"target,omitempty"`
}

CatalogEdge connects independently addressable catalog resources. Function internals remain in the authoritative x-rql-function contract; these edges are the cross-resource paths an agent needs for discovery.

type CatalogEntrypoint 

type CatalogEntrypoint struct {
	File                string         `json:"file"`
	Kind                string         `json:"kind"`
	Doc                 string         `json:"doc,omitempty"`
	ContractFingerprint string         `json:"contract_fingerprint"`
	Contract            map[string]any `json:"contract"`
}

CatalogEntrypoint embeds the exact Inspect document rather than translating it into a second schema. ContractFingerprint lets a client cheaply decide whether the callable contract it cached moved.

type CatalogFilterable 

type CatalogFilterable struct {
	Key       string   `json:"key"`
	Type      string   `json:"type"`
	Operators []string `json:"operators"`
	Values    []string `json:"values,omitempty"`
	Doc       string   `json:"doc,omitempty"`
}

type CatalogMetric 

type CatalogMetric struct {
	Key            string   `json:"key"`
	ResultType     string   `json:"result_type"`
	Doc            string   `json:"doc,omitempty"`
	ExactGrain     []string `json:"exact_grain"`
	Additivity     string   `json:"additivity"`
	AdditivityNote string   `json:"additivity_note,omitempty"`
}

type CatalogNamespace 

type CatalogNamespace struct {
	Name        string   `json:"name"`
	Guarded     bool     `json:"guarded"`
	Pinned      bool     `json:"pinned"`
	Doc         string   `json:"doc,omitempty"`
	Entrypoints []string `json:"entrypoints"`
}

type CatalogObject 

type CatalogObject struct {
	Name               string               `json:"name"`
	Label              string               `json:"label,omitempty"`
	Description        string               `json:"description,omitempty"`
	Group              string               `json:"group,omitempty"`
	Backing            string               `json:"backing"`
	IsDerived          bool                 `json:"is_derived"`
	Dependencies       []string             `json:"dependencies"`
	DependencyCoverage string               `json:"dependency_coverage"`
	SchemaHash         string               `json:"schema_hash"`
	Key                []string             `json:"key"`
	Display            CatalogObjectDisplay `json:"display"`
	Properties         []CatalogProperty    `json:"properties"`
	Links              []CatalogObjectLink  `json:"links"`
	Dimensions         []CatalogDimension   `json:"dimensions"`
	Metrics            []CatalogMetric      `json:"metrics"`
	Filterables        []CatalogFilterable  `json:"filterables"`
	File               string               `json:"file"`
	Line               int                  `json:"line"`
}

CatalogObject is one nominal object type and its closed instance contract.

type CatalogObjectDisplay 

type CatalogObjectDisplay struct {
	Primary   string `json:"primary,omitempty"`
	Secondary string `json:"secondary,omitempty"`
}
type CatalogObjectLink struct {
	Name        string   `json:"name"`
	From        string   `json:"from"`
	To          string   `json:"to"`
	Cardinality string   `json:"cardinality"`
	IsOptional  bool     `json:"is_optional"`
	IsComposed  bool     `json:"is_composed"`
	IsGuarded   bool     `json:"is_guarded"`
	Hops        []ViaHop `json:"hops,omitempty"`
}

type CatalogProject 

type CatalogProject struct {
	Name     string `json:"name"`
	Dialect  string `json:"dialect"`
	Language string `json:"language"`
	Std      string `json:"stdlib"`
}

type CatalogProperty 

type CatalogProperty struct {
	Name       string   `json:"name"`
	Type       string   `json:"type"`
	IsKey      bool     `json:"is_key"`
	IsNullable bool     `json:"is_nullable"`
	IsWritable bool     `json:"is_writable"`
	IsComputed bool     `json:"is_computed"`
	MaskRole   string   `json:"mask_role,omitempty"`
	Doc        string   `json:"doc,omitempty"`
	Label      string   `json:"label,omitempty"`
	Labels     []string `json:"labels,omitempty"`
	Format     string   `json:"format,omitempty"`
	// contains filtered or unexported fields
}

type CatalogRelation 

type CatalogRelation struct {
	Backing string   `json:"backing"`
	Key     []string `json:"key"`
	Guarded bool     `json:"guarded"`
	File    string   `json:"file"`
	Line    int      `json:"line"`
}

type CatalogRuntime 

type CatalogRuntime struct {
	ExecutionEnabled bool                      `json:"execution_enabled"`
	DefaultConnector string                    `json:"default_connector,omitempty"`
	Connectors       []CatalogRuntimeConnector `json:"connectors"`
	FunctionTargets  []string                  `json:"function_targets"`
	FunctionFlows    []string                  `json:"function_flows"`
}

CatalogRuntime is the served-process overlay. It is excluded from the definition fingerprint: readiness can change without the repository's callable definition changing.

type CatalogRuntimeConnector 

type CatalogRuntimeConnector struct {
	Name         string `json:"name"`
	Driver       string `json:"driver"`
	Kind         string `json:"kind"`
	IsReady      bool   `json:"is_ready"`
	Capabilities any    `json:"capabilities,omitempty"`
}

CatalogRuntimeConnector is the transport-neutral readiness projection added by the standalone application. It keeps the compiler catalog independent of connector handles and runtime implementation types.

type CatalogTarget 

type CatalogTarget struct {
	Name      string `json:"name"`
	Connector string `json:"connector"`
	Driver    string `json:"driver"`
	Kind      string `json:"kind"`
}

type CompletenessGateFinding 

type CompletenessGateFinding = completenessGateFinding

CompletenessGateFinding is one provably incorrect completeness gate.

func FunctionCompletenessGates 

func FunctionCompletenessGates(plan *function.Plan) []CompletenessGateFinding

FunctionCompletenessGates returns provably incorrect completeness gates.

type CompletenessGateKind 

type CompletenessGateKind = completenessGateKind

CompletenessGateKind classifies over- and under-gated function predicates.

type ComposedEdge 

type ComposedEdge struct {
	From        string   `json:"from"`
	Name        string   `json:"name"`
	To          string   `json:"to,omitempty"`
	Hops        []ViaHop `json:"hops"`
	Cardinality string   `json:"cardinality,omitempty"`
	Optional    bool     `json:"optional"`
	GuardChain  []string `json:"guard_chain"`
	File        string   `json:"file"`
	Line        int      `json:"line"`
	// Unresolved explains why the path could not be walked, when it could not.
	Unresolved string `json:"unresolved,omitempty"`
}

ComposedEdge is a `via` edge: a caller-visible name for a hop sequence, with the cardinality and optionality the stdlib derives from those hops.

type Context 

type Context struct {
	// Sub is the stable authenticated owner of durable resources. It is never
	// exposed to RQL as ctx.sub; guards continue to see only roles/attrs/now.
	Sub   string         `json:"sub,omitempty"`
	Roles []string       `json:"roles"`
	Attrs map[string]any `json:"attrs"`
	Now   string         `json:"now"`
	// contains filtered or unexported fields
}

Context is the runtime context exposed to Starlark as `ctx`.

func ContextFromMap 

func ContextFromMap(m map[string]any) *Context

ContextFromMap converts an authored example context to compiler context.

func (*Context) Attr 

func (c *Context) Attr(name string) (starlark.Value, error)

Attr exposes roles/attrs/now, failing closed in pure mode and on missing attributes (blueprint 13 §2 T6).

func (*Context) AttrNames 

func (c *Context) AttrNames() []string

AttrNames lists context fields.

func (*Context) Freeze 

func (c *Context) Freeze()

func (*Context) HasRunState 

func (c *Context) HasRunState() bool

HasRunState reports whether a loader session has stamped this context. Runtime adapters use it to verify that reusable request context remains immutable without exposing the compiler's session state.

func (*Context) Hash 

func (c *Context) Hash() (uint32, error)

func (*Context) IsPureEvaluation 

func (c *Context) IsPureEvaluation() bool

IsPureEvaluation reports whether this context is restricted to the pure declaration phase.

func (*Context) String 

func (c *Context) String() string

func (*Context) Truth 

func (c *Context) Truth() starlark.Bool

func (*Context) Type 

func (c *Context) Type() string

type CoverageBound 

type CoverageBound struct {
	Lower float64 `json:"lower"`
	Upper float64 `json:"upper"`
	Basis string  `json:"basis"`
}

CoverageBound is what is known about one direction of a correspondence.

func UnmeasuredCoverage 

func UnmeasuredCoverage() CoverageBound

UnmeasuredCoverage is what a direction carries when nothing measured it.

func (CoverageBound) Describe 

func (c CoverageBound) Describe() string

Describe renders the bound for a diagnostic, naming the absence of a measurement rather than printing a number that looks like one.

func (CoverageBound) IsExact 

func (c CoverageBound) IsExact() bool

IsExact reports whether the bound is a point measurement.

func (CoverageBound) IsMeasured 

func (c CoverageBound) IsMeasured() bool

IsMeasured reports whether anything narrowed this bound.

type DatasetColumn 

type DatasetColumn struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	IsNullable bool   `json:"is_nullable"`
}

DatasetColumn is one closed column in a host-declared source dataset. Dataset contracts are trusted model structure; filter values remain caller-controlled data and are always lowered as binds.

type DatasetListCompileRequest 

type DatasetListCompileRequest struct {
	Dataset          string
	Relation         string
	Key              []string
	Columns          []DatasetColumn
	Select           []string
	Filter           *ObjectFilter
	Sort             []ObjectSort
	Limit            int
	Offset           int
	IncludeTotal     bool
	Dialect          string
	RelationBindings map[string]string
}

type DatasetRenderResult 

type DatasetRenderResult struct {
	Dataset      string         `json:"dataset"`
	Dependencies []string       `json:"dependencies"`
	Columns      []ObjectColumn `json:"columns"`
	Rows         *RenderResult  `json:"rows"`
	Count        *RenderResult  `json:"count,omitempty"`
	Limit        int            `json:"limit"`
	Offset       int            `json:"offset"`
}

type DeferredValue 

type DeferredValue struct{ Value function.DeferredParam }

func (*DeferredValue) Freeze 

func (v *DeferredValue) Freeze()

func (*DeferredValue) Hash 

func (v *DeferredValue) Hash() (uint32, error)

func (*DeferredValue) String 

func (v *DeferredValue) String() string

func (*DeferredValue) Truth 

func (v *DeferredValue) Truth() starlark.Bool

func (*DeferredValue) Type 

func (v *DeferredValue) Type() string

type Deprecation 

type Deprecation struct {
	Key  string `json:"key"`
	Note string `json:"note"`
}

Deprecation is a structured deprecation record surfaced by inspect.

type DerivedRelationCompileRequest 

type DerivedRelationCompileRequest struct {
	Relation           string
	Query              string
	AvailableRelations []string
	File               string
	RelationBindings   map[string]string
}

DerivedRelationCompileRequest is a host-authored derived relation over a closed logical namespace. Requel owns validation, dependency discovery, and compile-local placement; the host owns execution.

type DerivedRelationRenderResult 

type DerivedRelationRenderResult struct {
	Relation     string   `json:"relation"`
	Dependencies []string `json:"dependencies"`
	Query        string   `json:"query"`
}

type Diagnostic 

type Diagnostic struct {
	Code     string   `json:"code"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
	// Kind sub-classifies a code that covers several distinct situations, for
	// consumers that branch on it. A code is the stable API; prose is not, and a
	// nightly job matching on message text breaks the first time the wording
	// improves. Empty for codes that mean exactly one thing.
	Kind         string      `json:"kind,omitempty"`
	File         string      `json:"file,omitempty"`
	Span         Span        `json:"span"`
	Related      []Related   `json:"related,omitempty"`
	Help         string      `json:"help,omitempty"`
	Cause        *Diagnostic `json:"cause,omitempty"`
	Retryable    bool        `json:"is_retryable,omitempty"`
	RetryAfterMS int64       `json:"retry_after_ms,omitempty"`
}

Diagnostic is one RQL finding. Codes are stable API (see codeExit).

func AsDiagnostic 

func AsDiagnostic(err error, file string) *Diagnostic

AsDiagnostic converts a Starlark or compiler error into a source-anchored diagnostic for standalone authoring tools.

func AtCallSite 

func AtCallSite(d *Diagnostic, node *function.Node) *Diagnostic

AtCallSite preserves an inner diagnostic location and relates its function call site, or locates an otherwise unlocated diagnostic there.

func BindFunctionFixtures 

func BindFunctionFixtures(plan *function.Plan, example *Example) (map[string]FixtureBinding, *Diagnostic)

BindFunctionFixtures resolves authored fixtures to function call nodes.

func BindProducesAt 

func BindProducesAt(plan *function.Plan, ex *Example) (map[string]producesAtBinding, *Diagnostic)

BindProducesAt resolves one example's intermediate-node assertions.

func CheckAlias 

func CheckAlias(fn, alias string) *Diagnostic

CheckAlias validates a relation alias at the compiler boundary.

func CheckAliasRenderable 

func CheckAliasRenderable(dialect, name string) *Diagnostic

CheckAliasRenderable validates a result alias for a dialect.

func CheckExampleBlockShapes 

func CheckExampleBlockShapes(example *Example) *Diagnostic

CheckExampleBlockShapes validates all static function fixture blocks together.

func CheckFunctionRootContract 

func CheckFunctionRootContract(label string, declared *function.Schema, plan *function.Plan) *Diagnostic

CheckFunctionRootContract verifies that a declared function return schema is no stronger than the plan's actual output contract.

func CheckGuardCoverage 

func CheckGuardCoverage(file string, frag *Fragment, globs, implied []string) *Diagnostic

CheckGuardCoverage enforces that every relation instance whose backing is required to be guarded declares a guard. A backing is required either because it matches a `[guards].require` glob, or because it is *implied* — some relation() declaration in the repository guards it, so an unguarded twin over the same backing is the RQL3029 bypass (repoGuardedBackings). The two are kept distinct only so the message can name the reason; both fail closed with RQL3002 at render time. `implied` is empty on the pure `render`/`test` paths and non-empty only where the caller computed it once (execute/serve/explain), so this never walks the repository itself.

func CheckJoinGraph 

func CheckJoinGraph(file string, frag *Fragment) *Diagnostic

CheckJoinGraph verifies well-formedness of the final fragment's join graph and applies the conservative fan-out rule (blueprint 13 §5).

Scope honesty: analysis sees only *declared* metadata (relation/source/ join_one/join_many/aggregate). It never parses authored SQL text, so a join hand-written inside a raw fragment is invisible — which is why RQL3003 nudges table access through the kernel constructors.

func CheckRequireFilter 

func CheckRequireFilter(file string, frag *Fragment) *Diagnostic

CheckRequireFilter enforces relation-declared `require_filter` (blueprint 13 §5): every instance of a relation that names required columns must have at least one of them constrained in the scope where the instance occurs.

Guards protect rows; nothing protected scan cost. A governed, guarded, reviewable query can still ask for "total revenue ever" and scan a petabyte fact table — LIMIT applies after the scan and the warehouse bills it. This is the analog of BigQuery's `require_partition_filter` and Looker's `always_filter`, declared once next to the relation instead of repeated in every query.

What counts

A predicate in the instance's scope whose *authored text* references `<alias>.<column>`. By the time analysis runs, the two routes named in the design are the same object — a predicate fragment in the scope's where-slot:

  • a compiled filterable (the caller passed `{"key": "ordered_at", …}` and `filter_where` lowered the registered `{}.ordered_at` expression), and
  • an authored predicate the query wrote itself.

Bound values never count: a caller string containing "o.ordered_at" is data, not a reference — the same rule the guard alias check applies.

What does not count, and why

**Guard predicates do not satisfy the requirement.** Guards are evaluated against `ctx`, so letting one satisfy the requirement would make acceptance context-dependent: the identical request would render for one role and be refused for another, and `requel explain` — deliberately context-free — could never tell a reviewer which. So this pass runs *before* guard injection and sees only the query's own predicates. The price is a redundant predicate when a guard already constrains the column; the return is a rule that is deterministic and reviewable, which for a cost control is the entire point.

Select-list, GROUP BY, and join `on` references do not count either — only the scope's where-slot is read, because selecting a column is not filtering on it. A scope with no where-slot cannot be shown to constrain anything and so fails closed, exactly as guard injection does.

Honest scope

Like every pass here this reads structure, not SQL semantics: it verifies the column is *referenced* by a predicate, not that the predicate prunes, so `WHERE o.ordered_at > … OR o.status = 'x'` satisfies a requirement it does not really honour. What it refuses is the failure mode that reaches the bill — no constraint on the column at all.

func CheckRequiredBackings 

func CheckRequiredBackings(file, sql string, frag *Fragment, globs []string, rels []*Relation, implied []string) *Diagnostic

CheckRequiredBackings scans rendered SQL for references to required-guarded tables that are not covered by a guarded instance — the hand-written-FROM bypass. Guarded relations are implicitly required: declaring a guard is the clearest statement of intent, and forgetting the manifest entry must not disable enforcement.

func CheckStructureQuery 

func CheckStructureQuery(document string) *Diagnostic

CheckStructureQuery validates one bounded structure document.

func Coerce 

func Coerce(pt *ParamType, raw any, name, file string, line int) (starlark.Value, *Diagnostic)

Coerce converts one caller parameter according to its declared type.

func CompareFunctionProduces 

func CompareFunctionProduces(ex *Example, plan *function.Plan, run *function.Run) (string, string, *Diagnostic)

CompareFunctionProduces compares an example's output assertion with a run.

func CompareIncompleteReasons 

func CompareIncompleteReasons(example string, plan *function.Plan, declared any, actual []function.IncompleteReason) (any, any, *Diagnostic)

CompareIncompleteReasons validates authored incomplete-reason assertions against an observed function result.

func CompletenessGateDiagnostic 

func CompletenessGateDiagnostic(finding CompletenessGateFinding) *Diagnostic

CompletenessGateDiagnostic renders one completeness-gate finding.

func DecodeObjectKey 

func DecodeObjectKey(object CatalogObject, key string) ([]any, *Diagnostic)

DecodeObjectKey decodes the stable, ordered key representation against one exact nominal object contract and rejects non-canonical alternate spellings.

func DryRun 

func DryRun(loader *Loader, state *State, query starlark.Callable) (starlark.Value, *Diagnostic)

DryRun evaluates an entrypoint without lowering or executing its result.

func Errorf 

func Errorf(code, format string, args ...any) *Diagnostic

Errorf builds an error-severity diagnostic.

func FunctionFixture 

func FunctionFixture(node function.Node, key string, raw any) (*function.Table, *Diagnostic)

FunctionFixture validates and builds one authored function fixture.

func GuardScopeRefusal 

func GuardScopeRefusal(file string, frag *Fragment, atoms []Atom) *Diagnostic

GuardScopeRefusal reports the structural reason InjectGuards would refuse a guarded relation in this fragment WITHOUT evaluating any guard: a set operation whose arms a single where-slot cannot cover per-arm, or a scope with no where-slot to inject into. Both are context-independent — the query is un-renderable for every caller — so it is the half of the injector the reporting surfaces can run: `inspect` marks such an entrypoint incomplete rather than publishing a callable-looking contract for a query render always turns away. It mirrors injectScope's depth-first scope walk exactly (inner scopes first, then this scope) so the two agree by construction.

func InertGateDiagnostic 

func InertGateDiagnostic(finding InertGateFinding) *Diagnostic

InertGateDiagnostic renders one redundant-gate finding.

func Infof 

func Infof(code, format string, args ...any) *Diagnostic

Infof builds an info-severity diagnostic.

func InjectGuards 

func InjectGuards(th *starlark.Thread, file string, frag *Fragment) *Diagnostic

InjectGuards evaluates each guarded relation instance's guard and ANDs the predicate into the WHERE slot of the scope where that instance occurs. Fragments preserve nesting, so a guarded relation used inside a subquery is filtered *inside that subquery* — filtering outside an enclosing aggregation would silently aggregate across tenants first.

func Inspect 

func Inspect(repository *Repository, man *Manifest, path string) (map[string]any, *Diagnostic)

Inspect builds the typed-surface document for an entrypoint: JSON Schema for params plus x-rql-* extensions. It never needs credentials or a runtime session: the params phase is pure, and the structural dry-run runs under a placeholder context whose reads are reported (x-rql-context-dependent) rather than silently passed off as the whole picture.

func InspectForSurfacePersona 

func InspectForSurfacePersona(repository *Repository, manifest *Manifest, path string, persona personas.Persona) (map[string]any, *Diagnostic)

InspectForSurfacePersona projects one entrypoint under a reviewed caller.

func JSONScalar 

func JSONScalar(v starlark.Value) (any, *Diagnostic)

JSONScalar lowers one Starlark scalar to a JSON-encodable value.

func LoadActionRuntimes added in v0.3.0 

func LoadActionRuntimes(repository *Repository, manifest *Manifest, contracts []CatalogAction) (map[string]*ActionRuntime, *Diagnostic)

LoadActionRuntimes evaluates the already cataloged action modules once and retains their frozen pure functions. Catalog construction has already validated every declaration and cross-reference; this pass does not publish a second contract.

func RequireFilterLintRepository 

func RequireFilterLintRepository(repository *Repository, manifest *Manifest, path, label, source string) []*Diagnostic

RequireFilterLintRepository runs required-filter analysis with module loads confined to an immutable repository snapshot.

func RunExamples 

func RunExamples(repository *Repository, man *Manifest, path string, rep *TestReport) *Diagnostic

RunExamples runs every example in a file (inline mode, hermetic). When updates is non-nil, a golden mismatch records the fresh SQL keyed by example name instead of failing, so `requel test --update` can rewrite it in place.

func RunExamplesForUpdate 

func RunExamplesForUpdate(repository *Repository, man *Manifest, path string, rep *TestReport, updates *GoldenUpdates) *Diagnostic

func RunFunctionExample 

func RunFunctionExample(repository *Repository, man *Manifest, plan *function.Plan, ex *Example) (*function.Run, *Diagnostic)

RunFunctionExample executes a function plan only against authored fixtures.

func RunFunctionExampleObserved 

func RunFunctionExampleObserved(repository *Repository, man *Manifest, plan *function.Plan, ex *Example, observer func(function.Node, function.StepRun, *function.Table, error)) (*function.Run, *Diagnostic)

RunFunctionExampleObserved executes an example while reporting each observed function node result to the caller.

func RunStudioFunctionFixture 

func RunStudioFunctionFixture(repository *Repository, manifest *Manifest, file, exampleName string, params map[string]any, observer func(function.Node, function.StepRun, *function.Table, error)) (*function.Run, *Diagnostic)

RunStudioFunctionFixture executes the real function scheduler and transform algebra against an authored example's fixtures. It is the local/offline execution mode used by the studio when no connector-backed Requel runtime is configured. Terminal calls remain hermetic and no connector is opened.

func UnknownStdModule 

func UnknownStdModule(loader *Loader, key, module string) *Diagnostic

UnknownStdModule diagnoses an unavailable standard-library module.

func Validate 

func Validate(decls []*ParamDecl, file string, input map[string]any) (starlark.StringDict, *Diagnostic)

Validate checks caller JSON against the declarations and produces the Starlark params struct passed to query(p). Every violation is an error; nothing is silently narrowed or dropped (blueprint 13 §2 T4).

func Warnf 

func Warnf(code, format string, args ...any) *Diagnostic

Warnf builds a warning-severity diagnostic.

func (*Diagnostic) At 

func (d *Diagnostic) At(file string, span Span) *Diagnostic

At attaches a file and span.

func (*Diagnostic) AtLine 

func (d *Diagnostic) AtLine(file string, line, col int) *Diagnostic

AtLine attaches a file and a line-only position.

func (*Diagnostic) Error 

func (d *Diagnostic) Error() string

func (*Diagnostic) WithHelp 

func (d *Diagnostic) WithHelp(s string) *Diagnostic

WithHelp attaches help text (always the concrete next action).

func (*Diagnostic) WithKind 

func (d *Diagnostic) WithKind(s string) *Diagnostic

WithKind attaches the machine-readable sub-class.

func (*Diagnostic) WithRelated 

func (d *Diagnostic) WithRelated(file string, span Span, note string) *Diagnostic

WithRelated attaches a secondary span.

type Diagnostics 

type Diagnostics []*Diagnostic

Diagnostics is a sortable diagnostic list.

func BypassRefs 

func BypassRefs(label, src string, index map[string]RelDecl, requireGlobs []string) Diagnostics

BypassRefs flags hand-written FROM/JOIN references, in a file's sql() string literals, to a table that has a relation declaration in the repo (blueprint 13 §5 / RQL-5). A table accessed properly through source()/join_* never appears as literal text in a template ("… FROM {} …"), so this catches only the bypass. Severity: a reference to a guarded or [guards].require-listed backing is an error (the guard would be silently skipped); any other declared backing is a warning (analysis and future guards would not see it).

func CheckBridges 

func CheckBridges(file string, frag *Fragment, bridges []*Bridge) Diagnostics

CheckBridges applies the two bridge rules to a rendered fragment's declared edges.

  • RQL3048: an equality whose two columns carry *different* namespace labels and which no bridge declares as corresponding.
  • RQL3049: an edge that uses part of a bridge's key and not the rest.

Both are errors, and both are acknowledged by the same `allow_unbridged`, for the reason `allow_fanout` covers every aggregate in its fragment: the acknowledgement is a sentence about this query's join, and the two codes are two ways of saying the join does not match the certified correspondence.

func CheckNeighbourhoods 

func CheckNeighbourhoods(file string, frag *Fragment, neighbourhoods []*Neighbourhood) Diagnostics

CheckNeighbourhoods applies the four similarity rules to a rendered fragment.

  • RQL3060: a query reaches a similarity edge set without naming it.
  • RQL3061: two traversals on one path, which transfer does not survive.
  • RQL3062: a predicate re-cuts a traversed edge set, silently making it a different set from the one anything was measured against.
  • RQL3063: a scoped edge set joined without the restriction that scoped it.

Only RQL3060 has an acknowledgement, and that asymmetry is deliberate. A traversal is a legitimate thing to do and needs a sentence; the other three are not defensible by explanation, because each makes the query mean something other than what its own declarations say.

func CheckRowDropping 

func CheckRowDropping(file string, m Meta) Diagnostics

CheckRowDropping applies the row-dropping rule (blueprint 03 §3.1), the deflation twin of the fan-out rule: an edge that is not declared `optional` renders INNER JOIN, so every fact row whose key has no match disappears — and with it its contribution to every aggregate in the query. The caller sees a smaller total for asking a *finer* question, which no error message ever explains because nothing failed. Measured against a real engine in blueprint 13 §9.2 (round fourteen): 14 702 -> 13 925 from one unmatched order.

A warning rather than an error, unlike RQL3001: inflation is always wrong, while shrinkage is wrong only when unmatched rows actually exist — a property of the data, not of the query. Analysis cannot know it, so the diagnostic states the exposure and names the two ways to close it: declare the edge `optional = True` (renders LEFT JOIN, unmatched rows survive under NULL), or verify the claim against the warehouse with `requel lint --probe-cardinality` and silence the code in `requel.toml [lint]`.

One warning per distinct edge, anchored at the edge — the fix site — with the aggregate it endangers as a related span.

func CheckSource 

func CheckSource(label, src string) Diagnostics

CheckSource runs the static catalog over one file's syntax tree. The load-bearing rule is RQL3020: every sql() template must be written out in the source — a string literal, or several joined with `+` — which is how RQL recovers the guarantee a tagged literal would give.

func CheckSourceKnowing 

func CheckSourceKnowing(label, src string, bridgeExports map[string]map[string]bool) Diagnostics

CheckSourceKnowing is CheckSource given what the repository's other modules export, which today is exactly one thing: which names come from a `bridge()`.

It exists because RQL3014 asks "is this import used" and a bridge import never is — the declaration is what the analysis pass reads, not the name — so the answer needs a fact from the imported file. Passing nil is the per-file posture and over-reports rather than under-reports.

func DuplicateDeclarationsRepository 

func DuplicateDeclarationsRepository(repository *Repository, only map[string]bool) (Diagnostics, error)

DuplicateDeclarationsRepository runs the repository-wide duplicate relation analysis over an immutable source snapshot.

func DuplicateGuardedDeclarations 

func DuplicateGuardedDeclarations(sites []RelationSite) Diagnostics

DuplicateGuardedDeclarations reports every unguarded `relation()` declaration over a backing that some other declaration guards.

Pure over the syntax scan, so `requel lint` and a test can ask the same question with no repository, no snapshot and no evaluation. `sites` is expected in `RelationDeclSites` order (file, then line); the guarded site a finding points at is the first one in that order, so the message is stable across runs.

func (Diagnostics) HasError 

func (ds Diagnostics) HasError() bool

HasError reports whether any diagnostic is error-severity.

func (Diagnostics) Sort 

func (ds Diagnostics) Sort()

Sort orders diagnostics by file, line, column, then code.

type Edge 

type Edge struct {
	Rel         *Relation
	Alias       string
	Cardinality string
	// Kind is the join keyword the edge renders: "inner" (the default) or
	// "left". It is analysis metadata, not decoration: an inner join *drops*
	// fact rows whose key has no match, so a metric total shrinks the moment
	// the caller selects a dimension from the joined object — the deflation
	// twin of the fan-out hazard (blueprint 03 §3.1, RQL3019).
	Kind string
	// On is the join predicate, kept so the opt-in referential-integrity probe
	// (`requel lint --probe-cardinality`) can rebuild the edge as a standalone
	// LEFT JOIN … IS NULL query. Analysis never reads it.
	On   *Fragment
	Line int
	// File is where Line was captured, for Instance.File's reason and measured
	// on the same defect one struct over: `view.make` calls `join_many` for the
	// author, so Line is a *stdlib* coordinate, and RQL3001 printed it against
	// the entrypoint's name — line 303 of a 42-line file. The Instance fix
	// (round eighteen) was not carried to Edge or Aggregate, so the fan-out
	// refusal, which is the whole point of the mechanism, still pointed past EOF.
	File string
}

Edge is a join edge with declared cardinality ("one" | "many").

func (Edge) Optional 

func (e Edge) Optional() bool

Optional reports whether the edge renders LEFT JOIN, i.e. whether unmatched rows survive it.

type EqualityPair 

type EqualityPair = equalityPair

EqualityPair is one equality comparison between qualified columns.

func EqualityPairs 

func EqualityPairs(text string) []EqualityPair

EqualityPairs extracts equality comparisons from a join predicate.

type Example 

type Example struct {
	Name string
	// Doc says WHY this example exists — the question it answers, the shape it
	// pins, the trap it demonstrates. It is published in `requel inspect`
	// beside the params, which is what makes it worth a field rather than a
	// comment: an example is a few-shot an agent generates from, and the name
	// alone ("the ladder itself") carries the label without the reason.
	//
	// This is the `provides`-doc defect one construct over: the ontology knew
	// and the contract surface an agent reads did not. Found authoring a study
	// whose two examples differ only in which cohort they name, where the
	// difference between them IS the finding and had nowhere to be written.
	//
	// It deliberately does not reach `api.txt`: the surface manifest records
	// what an entrypoint PROMISES — names, types, required-ness — and an
	// example is an illustration of that promise rather than part of it, so
	// `surface --check` stays blind to doc churn exactly as it is for a param's
	// doc and a result column's.
	Doc     string
	Params  map[string]any
	Context map[string]any
	Renders string
	// RendersSet records that renders= was supplied, which an empty Renders
	// cannot express on its own. `requel test --update` authors an empty golden;
	// every other path refuses one (biExample), so the two states must not be
	// the same zero value.
	RendersSet bool
	// RendersFile holds the golden's text in a file beside the entrypoint
	// instead of inside the example. Mutually exclusive with Renders; the
	// assertion and the comparison are otherwise identical (see
	// golden_sidecar.go). A function plan golden is ~2000 lines, which buries
	// the hand-written examples that are the reviewable part of the file.
	RendersFile string
	// Dialects narrows a golden to the dialects its *spelling* is right for.
	// Empty means every dialect, so an example that does not declare one is
	// unchanged in every respect.
	//
	// It exists because a vendored self-test runs under the consuming repo's
	// dialect, not the one its golden was written in, and some of rql:view's
	// output is dialect-spelled while everything it is asserting is not: the
	// nine composed-edge and guard-injection goldens in
	// _rql/std/tests/view_test.rql differ across dialects by exactly one
	// character, the identifier quote around a result alias (`"R.name"` versus
	// “ `R.name` “). The two ways out without this field were both wrong —
	// delete the goldens, which throws away the most load-bearing stdlib
	// coverage there is, or keep one dialect's spelling, which is what made
	// `requel test` fail out of the box in every mysql and bigquery repo.
	//
	// A skip is disclosed, never silent: see TestReport.SkippedExamples.
	Dialects         []string
	FunctionFixtures map[string]any
	Produces         map[string]any
	// ProducesAt asserts named intermediate nodes of the same run, keyed the way
	// FunctionFixtures is. Test-only: nothing about it reaches the function_run
	// envelope a caller receives. See bindProducesAt.
	ProducesAt map[string]any
	Fails      string
	FailsCode  string
	Line       int
}

Example is one colocated example block.

type Exception 

type Exception struct {
	Subject string         // the affected export ("frag.andAll") or behavior
	Class   ExceptionClass // one of ValidExceptionClasses
	Version string         // the std version the break landed in
	Note    string         // free text: what changed and why it was sanctioned
}

Exception is one recorded break of the §1.1 promise.

func ExceptionsFor 

func ExceptionsFor(entries []Exception, version string) []Exception

ExceptionsFor returns the entries recorded for a version — what `requel vendor --update` prints alongside the CHANGELOG so a re-pinning repo sees sanctioned breaks explicitly rather than discovering them in production.

func ParseExceptions 

func ParseExceptions(text string) (entries []Exception, problems []string)

ParseExceptions reads api-except.txt. Malformed or unknown-class entries are returned as problems rather than silently dropped — a broken audit trail is worse than none, because it reads as an empty one.

type ExceptionClass 

type ExceptionClass string

ExceptionClass is one of the three carve-outs adapted from the Go 1 compatibility document. 

const (
	// ExceptSecurity — a guard, escaping, or injection fix MAY change rendered
	// SQL (including existing goldens) within a minor version, immediately.
	// Compatibility never delays a security fix.
	ExceptSecurity ExceptionClass = "security"
	// ExceptUnspecified — behavior never promised (§1.9 L2); recorded only when
	// a change is likely to surprise.
	ExceptUnspecified ExceptionClass = "unspecified"
	// ExceptSpecContradiction — shipped behavior and blueprint 12 disagree; the
	// blueprint wins and the fix is a sanctioned break.
	ExceptSpecContradiction ExceptionClass = "spec-contradiction"
)

type ExplainCtxNote 

type ExplainCtxNote struct {
	Reads []string `json:"reads"`
	Note  string   `json:"note"`
}

ExplainCtxNote says the summary carrying it describes one caller.

Reads names the `ctx` fields the run looked at, which is the reviewer's shortest route to *why*: `ctx.roles` on a query whose relations look unremarkable is the sentence "another role reaches a different query". `requel` prints the same note without this list — its evaluator records that the context was read, not which fields (blueprint 13 §4).

type ExplainDoc 

type ExplainDoc struct {
	File string `json:"file"`
	// ContextDependent is set when query(p) read `ctx` while assembling the
	// summary — that is, when everything below describes one caller rather than
	// every caller. Present only when there is something to say; see
	// ctxDependence.
	ContextDependent *ExplainCtxNote `json:"context_dependent,omitempty"`
	Relations        []string        `json:"relations"`
	Guarded          []string        `json:"guarded"`
	// Unguarded is Relations minus Guarded, stated rather than left to be
	// derived. Dogfooding found this summary conveyed "nothing here is
	// protected" only by *omitting* the guarded section — a reviewer had to
	// notice an absent heading, and an agent consuming the JSON had to compute
	// a set difference, to learn the most consequential fact the command
	// reports. Both readings fail the same way: by producing no signal at all,
	// which is indistinguishable from not having looked. The struct comment on
	// Findings already states the rule this now follows — silence is the one
	// failure a reviewer-facing surface must not have.
	Unguarded []string `json:"unguarded"`
	// RequireFilter lists the declared cost requirements — the *declaration*,
	// not whether a request satisfies it. Satisfaction is a property of the
	// caller's filters and this dry run has none, so reporting it as a finding
	// would fire for every correctly declared entrypoint.
	RequireFilter []string `json:"require_filter"`
	Edges         []string `json:"edges"`
	Aggregates    []string `json:"aggregates"`
	FanoutAcks    []string `json:"fanout_acks"`
	// Bridges lists the certified correspondences this query's joins actually
	// traverse, with their cardinality and whether they are lossy.
	//
	// It belongs on the reviewer-facing surface for the reason `unguarded` does.
	// `relations` already says which tables an answer came from; this says which
	// declared claims about how those tables correspond the answer *depends on*
	// — and a lossy one is the difference between "no match exists" and "this
	// mapping does not carry the match", which is exactly the distinction a
	// reviewer approving a negative result has to make and cannot make from a
	// join list.
	Bridges []string `json:"bridges"`
	// UnbridgedAcks are the allow_unbridged reasons, kept separate from
	// FanoutAcks because they defend a different claim: not "the total is still
	// right across multiplied rows" but "these two value spaces do correspond".
	UnbridgedAcks []string `json:"unbridged_acks"`
	// NeighbourhoodAcks are the via_neighbourhood acknowledgements, each prefixed
	// with the edge set it named. Separate from UnbridgedAcks because a reviewer
	// reading this document has to be able to tell a correspondence argument from
	// a similarity one: the first says two spellings mean the same entity, the
	// second says the rows are a guess whose cutoff is in the declaration.
	NeighbourhoodAcks []string `json:"neighbourhood_acks"`
	// ExactAt lists the measures that are exact only at a stated grain — the
	// *declaration*, not whether this query satisfies it.
	//
	// `fanout_safe` answers one way an aggregate can be wrong (a `many` edge
	// duplicates rows) and `FanoutAcks` above publishes the author's
	// acknowledgement of it. `exact_at` answers the second, unrelated way: the
	// values themselves overlap, so pooling rows double-counts shared content
	// with no error anywhere in the join graph. Publishing the first and not the
	// second let a reviewer read "fan-out acks: COUNT(*) over the object's own
	// grain" and conclude a total was trustworthy while a measure in the same
	// query overstated its own — with RQL3045 saying so only at execute time, on
	// stderr, after the number was produced.
	//
	// Satisfaction is deliberately not reported, for RequireFilter's reason: this
	// is a structural dry run over every label, so it has no caller grouping to
	// judge against, and RQL3045 must stay silent under it or it would fire for
	// every correctly declared measure on every document.
	ExactAt     []string `json:"exact_at"`
	NotAdditive []string `json:"not_additive"`
	Filterables []string `json:"filterables"`
	Examples    []string `json:"examples"`
	// Findings are the guard analyses `render` enforces, reported rather than
	// raised. `explain` is the reviewer-facing surface, so staying silent about
	// a bypass `render` would refuse is the one failure it must not have.
	Findings []string `json:"findings"`
	// Retrieval is set for a retrieval entrypoint: the namespace queried, its
	// ranking, and whether it is guarded. The SQL-shaped sections above stay
	// empty there — a retrieval request has no relations, edges or aggregates
	// — and Filterables/Examples/Findings are shared.
	Retrieval *ExplainRetrieval `json:"retrieval,omitempty"`
	Function  *ExplainFunction  `json:"function,omitempty"`
	// GuardMatrix is present only under `--personas`. Everything above it is
	// context-free and stays that way; this is the one field that carries an
	// answer about particular callers.
	GuardMatrix *GuardMatrixDoc `json:"guard_matrix,omitempty"`
}

ExplainDoc is the reviewer/agent security summary of an entrypoint.

type ExplainFunction 

type ExplainFunction struct {
	Version      string                `json:"version"`
	ResultKind   string                `json:"result_kind"`
	OutputNode   string                `json:"output_node"`
	OutputSchema function.Schema       `json:"output_schema"`
	Targets      map[string]string     `json:"targets"`
	DataFlows    []function.DataFlow   `json:"data_flows"`
	Limits       function.Limits       `json:"limits"`
	Nodes        []ExplainFunctionNode `json:"nodes"`
	// GuardedFlows names the cross-target crossings whose value came out of a
	// guarded relation. Derived rather than declared, and additive: a plan with
	// no such crossing carries nothing. See explain_guarded_flow.go.
	GuardedFlows []ExplainGuardedFlow `json:"guarded_flows,omitempty"`
}

type ExplainFunctionNode 

type ExplainFunctionNode struct {
	Name          string            `json:"name"`
	Op            string            `json:"op"`
	DependsOn     []string          `json:"depends_on"`
	MaxRows       int               `json:"max_rows"`
	Target        string            `json:"target,omitempty"`
	Connector     string            `json:"connector,omitempty"`
	Entrypoint    string            `json:"entrypoint,omitempty"`
	Security      string            `json:"security,omitempty"`
	Evidence      string            `json:"evidence,omitempty"`
	Completeness  string            `json:"completeness"`
	InformationIn []string          `json:"information_origins"`
	Retrieval     *ExplainRetrieval `json:"retrieval,omitempty"`
	Relations     []string          `json:"relations,omitempty"`
	// GuardedRelations is the subset of Relations this terminal guards. Recorded
	// per node so a flow's disclosure can name the relation whose data crossed,
	// rather than only counting them in the Security string.
	GuardedRelations []string `json:"guarded_relations,omitempty"`
}

type ExplainGuardedFlow 

type ExplainGuardedFlow struct {
	From     string   `json:"from"`
	To       string   `json:"to"`
	Columns  []string `json:"columns"`
	Guarded  []string `json:"guarded_relations"`
	ViaNodes []string `json:"via_nodes"`
}

ExplainGuardedFlow is a cross-target crossing whose value originated in a guarded relation, with the relations named and the path that carried it.

func GuardedFlows 

func GuardedFlows(function *ExplainFunction) []ExplainGuardedFlow

GuardedFlows derives ordered guard dependencies for explain output.

type ExplainHomology 

type ExplainHomology struct {
	Method               string   `json:"method"`
	Engine               string   `json:"engine"`
	ExecutionShape       string   `json:"execution_shape"`
	Profile              string   `json:"profile"`
	ProfilesAllowed      []string `json:"profiles_allowed"`
	MaxEvalue            string   `json:"max_evalue,omitempty"`
	QueryKind            string   `json:"query_kind"`
	DatabaseKind         string   `json:"database_kind"`
	ResultUnit           string   `json:"result_unit,omitempty"`
	CandidateScopeDigest string   `json:"candidate_scope_digest,omitempty"`
	MaxIterations        int      `json:"max_iterations,omitempty"`
	InclusionEvalue      string   `json:"inclusion_evalue,omitempty"`
	DomainDatabase       string   `json:"domain_database,omitempty"`
	ClaimType            string   `json:"claim_type,omitempty"`
}

ExplainHomology is the recall and representation contract a reviewer needs beside the ordinary retrieval posture. It deliberately carries no caller sequence, only the authored choices that determine what an answer means.

type ExplainRetrieval 

type ExplainRetrieval struct {
	Namespace string `json:"namespace"`
	RankBy    string `json:"rank_by"`
	Guarded   bool   `json:"guarded"`
	// Pinned means the wire namespace is `<name>-<ctx-derived segment>`: the
	// caller's identity chooses the address, which is this target's strongest
	// isolation (blueprint 16 §8). The Namespace above shows the `{pin}`
	// placeholder form; `explain --personas` shows each persona's resolution.
	Pinned   bool             `json:"pinned,omitempty"`
	Homology *ExplainHomology `json:"homology,omitempty"`
}

ExplainRetrieval — see ExplainDoc.Retrieval.

type FanoutAckOut 

type FanoutAckOut struct {
	Reason string `json:"reason"`
	Line   int    `json:"line,omitempty"`
}

FanoutAckOut documents an allow_fanout acknowledgement.

type FileInfo 

type FileInfo struct {
	File     string   `json:"file"`
	Kind     string   `json:"kind"`
	Params   []string `json:"params,omitempty"`
	Examples int      `json:"examples"`
	Doc      string   `json:"doc,omitempty"`
}

FileInfo describes one discovered .rql file.

func Describe 

func Describe(repository *Repository, man *Manifest, path string) FileInfo

Describe classifies a file and (for entrypoints) lists its params.

type FilterIn 

type FilterIn struct {
	Key   string
	Op    string
	Value starlark.Value // *Val, number, bool, or *starlark.List of those
	HasV  bool
}

FilterIn is a validated FilterInput. Key and op are caller-selected names validated against the authored registry; the Go fields stay plain strings for internal use (filter.go's registry lookup), but the Starlark attrs hand back *Ident, not starlark.String, so authored code can branch on them (`.key.eq(…)`) yet can never turn a caller name into SQL text. The value stays wrapped so it can only bind.

func (*FilterIn) Attr 

func (f *FilterIn) Attr(name string) (starlark.Value, error)

Attr exposes key/op so authors can drive join-need detection — as *Ident, the inert caller-name type, so a key can be compared but never becomes SQL text.

func (*FilterIn) AttrNames 

func (f *FilterIn) AttrNames() []string

AttrNames lists filter fields.

func (*FilterIn) Freeze 

func (f *FilterIn) Freeze()

func (*FilterIn) Hash 

func (f *FilterIn) Hash() (uint32, error)

func (*FilterIn) String 

func (f *FilterIn) String() string

func (*FilterIn) Truth 

func (f *FilterIn) Truth() starlark.Bool

func (*FilterIn) Type 

func (f *FilterIn) Type() string

type FilterableInfo 

type FilterableInfo struct {
	Key    string
	Ops    []string
	Values []string
	Type   string
	Doc    string
	// contains filtered or unexported fields
}

FilterableInfo describes a registered filterable (for inspect/explain).

type FixtureBinding 

type FixtureBinding = fixtureBinding

FixtureBinding identifies the authored fixture selected for one call node.

type Fragment 

type Fragment struct {
	Atoms []Atom
	Meta  Meta
}

Fragment is an opaque SQL value: atoms plus analysis metadata. It is the only carrier of SQL structure in the language (blueprint 13 §2 T1).

func ConcatFrag 

func ConcatFrag(a, b *Fragment) *Fragment

ConcatFrag concatenates two fragments with no separator, merging metadata.

func TextFrag 

func TextFrag(s string) *Fragment

TextFrag builds a text-only fragment.

func (*Fragment) Binary 

func (f *Fragment) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error)

Binary implements `+` as fragment concatenation (metadata merges). Starlark operator overloading is what lets the RQL stdlib write its own reductions rather than needing them as kernel builtins (blueprint 13 §5.1).

func (*Fragment) Empty 

func (f *Fragment) Empty() bool

Empty reports whether the fragment renders no SQL text and holds no binds.

A where-slot always counts as non-empty even with no predicates: it is *unfilled*, not absent — guards inject into it after assembly, so a combinator that dropped it (or omitted its separator) would produce `…accountsWHERE …` or, worse, leave the guard nowhere to land.

func (*Fragment) Freeze 

func (f *Fragment) Freeze()

func (*Fragment) Hash 

func (f *Fragment) Hash() (uint32, error)

func (*Fragment) String 

func (f *Fragment) String() string

func (*Fragment) Truth 

func (f *Fragment) Truth() starlark.Bool

func (*Fragment) Type 

func (f *Fragment) Type() string

type FunctionArm 

type FunctionArm = functionArm

FunctionArm identifies one classify or boolean decision arm.

func FunctionArms 

func FunctionArms(plan *function.Plan) []FunctionArm

FunctionArms returns every decision arm in a function plan.

type FunctionColumnRef 

type FunctionColumnRef struct{ Name string }

func (*FunctionColumnRef) Freeze 

func (v *FunctionColumnRef) Freeze()

func (*FunctionColumnRef) Hash 

func (v *FunctionColumnRef) Hash() (uint32, error)

func (*FunctionColumnRef) String 

func (v *FunctionColumnRef) String() string

func (*FunctionColumnRef) Truth 

func (v *FunctionColumnRef) Truth() starlark.Bool

func (*FunctionColumnRef) Type 

func (v *FunctionColumnRef) Type() string

type FunctionLintResult 

type FunctionLintResult struct {
	Findings      Diagnostics
	UsedFlows     []string
	IsEntrypoint  bool
	IsDeclaration bool
}

FunctionLintResult is the complete compiler-owned function analysis for one authored file. The standalone application applies repository severity policy and combines results across files.

func LintFunctionFile 

func LintFunctionFile(repository *Repository, manifest *Manifest, path, label, source string) FunctionLintResult

LintFunctionFile runs every plan-aware function lint over one entrypoint and its authored examples.

type FunctionMeasure 

type FunctionMeasure struct{ Measure function.Measure }

func (*FunctionMeasure) Freeze 

func (v *FunctionMeasure) Freeze()

func (*FunctionMeasure) Hash 

func (v *FunctionMeasure) Hash() (uint32, error)

func (*FunctionMeasure) String 

func (v *FunctionMeasure) String() string

func (*FunctionMeasure) Truth 

func (v *FunctionMeasure) Truth() starlark.Bool

func (*FunctionMeasure) Type 

func (v *FunctionMeasure) Type() string

type FunctionNode 

type FunctionNode struct{ Node function.Node }

func (*FunctionNode) Freeze 

func (v *FunctionNode) Freeze()

func (*FunctionNode) Hash 

func (v *FunctionNode) Hash() (uint32, error)

func (*FunctionNode) String 

func (v *FunctionNode) String() string

func (*FunctionNode) Truth 

func (v *FunctionNode) Truth() starlark.Bool

func (*FunctionNode) Type 

func (v *FunctionNode) Type() string

type FunctionOrder 

type FunctionOrder struct{ Order function.Order }

func (*FunctionOrder) Freeze 

func (v *FunctionOrder) Freeze()

func (*FunctionOrder) Hash 

func (v *FunctionOrder) Hash() (uint32, error)

func (*FunctionOrder) String 

func (v *FunctionOrder) String() string

func (*FunctionOrder) Truth 

func (v *FunctionOrder) Truth() starlark.Bool

func (*FunctionOrder) Type 

func (v *FunctionOrder) Type() string

type FunctionPredicate 

type FunctionPredicate struct{ Predicate function.Predicate }

func (*FunctionPredicate) Freeze 

func (v *FunctionPredicate) Freeze()

func (*FunctionPredicate) Hash 

func (v *FunctionPredicate) Hash() (uint32, error)

func (*FunctionPredicate) String 

func (v *FunctionPredicate) String() string

func (*FunctionPredicate) Truth 

func (v *FunctionPredicate) Truth() starlark.Bool

func (*FunctionPredicate) Type 

func (v *FunctionPredicate) Type() string

type FunctionThreshold 

type FunctionThreshold = functionThreshold

FunctionThreshold is one independently coverable function boundary family.

func FunctionThresholds 

func FunctionThresholds(plan *function.Plan) []FunctionThreshold

FunctionThresholds returns the boundary families authored by a function.

type FunctionValue 

type FunctionValue struct {
	Output      *FunctionNode
	ResultKind  string
	Cardinality string
	Doc         string
}

func (*FunctionValue) Freeze 

func (v *FunctionValue) Freeze()

func (*FunctionValue) Hash 

func (v *FunctionValue) Hash() (uint32, error)

func (*FunctionValue) String 

func (v *FunctionValue) String() string

func (*FunctionValue) Truth 

func (v *FunctionValue) Truth() starlark.Bool

func (*FunctionValue) Type 

func (v *FunctionValue) Type() string

type GoldenUpdates 

type GoldenUpdates struct {
	Inline   map[string]string
	Sidecars []SidecarWrite
	// notes is what the operator should know about *how* a golden was written,
	// as opposed to that it was. Today it carries one line per function plan
	// golden written inline (inlinePlanGoldenNote): `--update` is the moment an
	// entrypoint gains ~1700 lines of generated JSON, and it used to be the one
	// moment nothing said `renders_file` existed.
	Notes []string
}

GoldenUpdates describes authoring work without performing it. The standalone authoring package owns all filesystem mutation.

func NewGoldenUpdates 

func NewGoldenUpdates() *GoldenUpdates

type GraphEdge 

type GraphEdge struct {
	From        string `json:"from"`
	Edge        string `json:"edge"`
	To          string `json:"to"`
	Cardinality string `json:"cardinality"`
	Optional    bool   `json:"optional"`
	// Guarded reports whether the relation this hop traverses — the target
	// object's backing — carries a guard. Guardedness of the *base* object is
	// reported on the node, not the hop.
	Guarded bool   `json:"guarded"`
	Backing string `json:"backing,omitempty"`
	// Source is where the target came from: "declared" when the join entry
	// names its object, "bound" when only a query site supplies it, or both.
	// A declared target is repo-wide metadata; a bound one holds only for the
	// query that wired it, which is a weaker claim and reads as one here.
	Source   string `json:"source"`
	DeclFile string `json:"decl_file"`
	DeclLine int    `json:"decl_line"`
	BindFile string `json:"bind_file,omitempty"`
	BindLine int    `json:"bind_line,omitempty"`
}

GraphEdge is a resolved direct edge between two objects.

type GraphObject 

type GraphObject struct {
	Name    string `json:"name"`
	Backing string `json:"backing,omitempty"`
	Guarded bool   `json:"guarded"`
	File    string `json:"file"`
	Line    int    `json:"line"`
}

GraphObject is an object node as reported.

type GraphPair 

type GraphPair struct {
	From string `json:"from"`
	To   string `json:"to"`
	// Ambiguous marks a pair reachable by more than one *distinct* hop
	// sequence. Nothing selects among them today — this report does not pick
	// paths — so ambiguity is a review signal, not an error.
	Ambiguous bool        `json:"ambiguous"`
	Paths     []GraphPath `json:"paths"`
}

GraphPair is an ordered object pair and every path that connects it.

type GraphPath 

type GraphPath struct {
	Hops []GraphEdge `json:"hops"`
	// Cardinality is "many" if any hop is many — one many-hop anywhere
	// multiplies the fact rows for the whole path (the RQL3001 hazard).
	Cardinality string `json:"cardinality"`
	// Optional is sticky: once a hop is optional the composed join is a LEFT
	// join, because an inner join later in the chain would drop exactly the
	// rows the earlier LEFT join preserved.
	Optional bool `json:"optional"`
	// GuardChain names the hops that traverse a guarded relation, in order.
	GuardChain []string `json:"guard_chain"`
	// Named lists the composed (`via`) edges that denote this exact hop
	// sequence. A caller can reach this pair by naming one of them directly.
	Named []string `json:"named,omitempty"`
}

GraphPath is one hop sequence connecting a pair, with the classifications composed along it.

type GraphReport 

type GraphReport struct {
	Objects       []GraphObject       `json:"objects"`
	Edges         []GraphEdge         `json:"edges"`
	ComposedEdges []ComposedEdge      `json:"composed_edges"`
	Pairs         []GraphPair         `json:"pairs"`
	UnboundEdges  []UnboundEdge       `json:"unbound_edges"`
	Unresolved    []UnresolvedBinding `json:"unresolved_bindings"`
	MaxDepth      int                 `json:"max_depth"`
	// Truncated reports that enumeration hit MaxDepth or the step budget, so
	// the path list is a subset. RQL2009 established the precedent: a bound is
	// only safe if exceeding it is visible.
	Truncated bool `json:"truncated"`
}

GraphReport is the whole document, in a deterministic order so two runs on the same tree diff cleanly.

func BuildGraphReport 

func BuildGraphReport(files map[string]string, index map[string]RelDecl, maxDepth int) *GraphReport

BuildGraphReport builds the reachability report from repo sources.

files maps display label → source (the caller excludes the vendored stdlib). index is the repo-wide RelationIndex, reused verbatim so "is this backing guarded" has one answer shared with the RQL3003 bypass lint.

type GuardMatrixDoc 

type GuardMatrixDoc = personas.Matrix

GuardMatrixDoc is the whole matrix: personas across, guarded relation instances down. Its Note is set when query(p) read `ctx` while assembling the query, in which case the rows are the relations *one* context reaches — a floor, not a ceiling (the caveat `requel inspect` publishes as x-rql-context-dependent).

type GuardOut 

type GuardOut struct {
	Relation  string `json:"relation"`
	Predicate string `json:"predicate"`
}

GuardOut documents an injected guard predicate.

type GuardPred 

type GuardPred struct {
	Backing string
	Short   string
	Frag    *Fragment
}

GuardPred is a relation guard predicate injected into a WHERE slot.

type GuardRow 

type GuardRow = personas.Row

GuardRow is one guarded relation instance and every persona's verdict on it, in the order the persona file declared them.

type GuardVerdict 

type GuardVerdict = personas.Verdict

The matrix document is the shared format (`internal/personas`), not an RQL-side type: a reviewer keeps one personas.json next to the ontology, runs both CLIs against it, and diffs the answers — and the committed golden ([09 §1]) is written from this same document. Two structurally identical structs would be two places for that format to drift.

GuardVerdict is one persona's answer for one guarded relation instance: exactly one of Predicate / Denied / NotReached is set. In RQL, Denied means the guard called `fail_closed`, read a `ctx` attribute the persona does not carry, or returned something render refuses; NotReached means query(p) branched on ctx and never built the relation at all.

type HalfEdge 

type HalfEdge struct {
	Name        string
	Cardinality string // "" for a composed edge — derived from its hops
	Optional    bool
	Target      string // resolved from `object`; "" when the edge is terminal
	TargetExpr  string // what `object` was written as, for reporting
	Via         []ViaHop
	Line        int
}

HalfEdge is a `joins=[…]` entry as authored.

func (HalfEdge) Composed 

func (h HalfEdge) Composed() bool

Composed reports whether this entry is a `via` path rather than a direct edge.

type HomologyMethodSpec 

type HomologyMethodSpec = homologyMethodSpec

HomologyMethodSpec is the compiler's declarative homology capability shape.

type HomologySpec 

type HomologySpec struct {
	// Method is the target-native rank method (BLASTP, MMSEQS_SEARCH, …).
	Method string
	// Engine is the driver family the method belongs to, for the dialect a
	// document reports.
	Engine            string
	QueryKind         string
	DatabaseKind      string
	SupportedProfiles []string
	OutputColumns     []string
	ExecutionShape    string
	// Comparison is MMSEQS_SEARCH's authored comparison mode (protein_protein or
	// nucleotide_nucleotide). Unlike BLAST/DIAMOND, which encode the query/database
	// alphabets in the method name, mmseqs2 carries one method and a typed
	// comparison — so the query kind is authored here, never inferred from the
	// query bytes. Empty for every other engine.
	Comparison string
	// Profile is the selected sensitivity, always a member of Allowed.
	Profile string
	// Allowed is the authored domain the profile was selected from. Published
	// by inspect so an agent generates against the real constraint.
	Allowed []string
	// MaxEvalue is an authored admission threshold, or "" when unset. It is
	// never caller-minted: it changes what a result *means*, and the
	// aggregates precedent (blueprint 16 §4) makes authored-only the posture
	// for anything in that class.
	MaxEvalue string
	// ResultUnit is authored scientific representation, never inferred from a
	// row consumer. HSP preserves raw evidence; subject_hit performs a
	// deterministic coordinate-union aggregation; annotation_claim evaluates an
	// authored proposal policy without declaring the proposal reviewed truth.
	ResultUnit string
	Claim      *homologyClaimPolicy
	// FoldseekClaim is the structural claim policy for a Foldseek claim result
	// unit. It is a different shape from the BLAST claim (a TM-score floor rather
	// than an identity floor), so it is a separate authored object that renders
	// into the same `claim` wire position.
	FoldseekClaim   *foldseekClaimPolicy
	HSPReporting    *homologyHSPReporting
	Translation     *homologyTranslation
	MaxIterations   int
	InclusionEvalue string
	DomainDatabase  string
	// SearchStrategy is DIAMOND's sensitivity-cascade selector (single_pass or
	// staged). Empty for every non-DIAMOND method — it is engine-specific, not a
	// shared homology field, so a body carrying it against another engine is a
	// contract error rather than an ignored extra.
	SearchStrategy string
	// CandidateScope is produced only by the evaluated namespace guard. It is
	// sent to the engine as a pre-ranking corpus restriction and therefore may
	// never be populated from caller filters.
	CandidateScope *homologyCandidateScope
	// QueryResidues is the query's length, for explain/inspect. The sequence
	// itself is caller data and is never echoed into a document.
	QueryResidues int
	// QueryBytes is the corresponding measure for a structure document. It is
	// separate rather than relabeling bytes as residues: Foldseek's query is a
	// biological object in a different representation, and inspect must say so.
	QueryBytes int
	// QueryField and QueryObjectSelectors describe a typed Foldseek query object
	// in rank_by[2]. QueryField is "coordinates" or "structure_ref" (the caller
	// data), and QueryObjectSelectors is the authored model/chains/assembly/
	// altloc_policy selection. Both empty for a bare-string query. They are the
	// oracle's contract for a typed query — the caller field is length-checked,
	// the selectors are compared exactly.
	QueryField           string
	QueryObjectSelectors map[string]any
}

HomologySpec is the authored search configuration for a homology entrypoint. It is the part of the request that is *not* ranking and *not* a filter: admission and sensitivity.

func (*HomologySpec) String 

func (s *HomologySpec) String() string

String renders the spec for explain.

type Ident 

type Ident struct {
	S    string // the validated name (an authored registry key / label / op)
	Role string // "key" | "op" | "dir" | "nulls" | "label" | "role" | "attribute" — messages only
}

Ident is a caller-supplied NAME validated against an authored whitelist — a filter/order key, a filter op, an order dir/nulls, or a Set label. Like *Val it is caller data and inert to SQL: no string methods, `+` refused, rejected by text(); interpolated with sql("{}", …) it BINDS (escaped), never inlines as structure. Unlike *Val it answers equality against an authored literal — via the `name_eq(name, "…")` builtin, NOT starlark `==` — because authored code legitimately branches on which name the caller chose (join-need detection, order direction, label selection) without ever turning the name into SQL text.

Its existence is what makes the trust boundary LOCAL rather than derived. The safety claim "a plain starlark.String reaching a kernel builtin is authored" used to be true only because every caller-selected name — .key/.op/.dir/.nulls and Set labels — was handed back as a plain starlark.String that happened to be wire-validated first. With those names wearing this type instead, the claim is a fact about the type at the call site, so text() and computed templates are safe by construction, not because a check ran earlier. This is the type that retires the round-two .key injection's whole class (CONTRIBUTING.md, blueprint 13 §9.2 round two): even a future caller-name channel added without re-doing the wire validation cannot reach SQL text, because the type refuses it.

func (*Ident) Binary 

func (i *Ident) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error)

Binary refuses `+`, exactly as *Val does: a caller name glued to authored text would launder provenance and could reach SQL as structure.

func (*Ident) CompareSameType 

func (i *Ident) CompareSameType(op syntax.Token, y starlark.Value, depth int) (bool, error)

CompareSameType compares two Idents by their name. Cross-type comparison with starlark.String is deliberately unsupported: making it work would require Type()=="string", and then `name in [ident, …]` routes to String.CompareSameType with the String on the left, which type-asserts its argument to String and panics on an *Ident. Authored code compares with `name_eq(name, "…")` instead, which is also what keeps the name from ever becoming a plain, launderable string.

func (*Ident) Freeze 

func (i *Ident) Freeze()

func (*Ident) Hash 

func (i *Ident) Hash() (uint32, error)

func (*Ident) String 

func (i *Ident) String() string

func (*Ident) Truth 

func (i *Ident) Truth() starlark.Bool

func (*Ident) Type 

func (i *Ident) Type() string

type IdentSet 

type IdentSet struct {
	Names []string // the caller's names, in arrival order
	Role  string   // "role" | "label" | "attribute" — for messages only
}

IdentSet is a collection of caller-supplied NAMES — the roles on a context, the labels chosen through a Set param, a list-valued context attribute — and it owns membership. That ownership is the whole point.

A *starlark.List cannot serve here. `x in list` is List.Has, which is Equal per element, and Equal answers false for any cross-type pair *before* a value's own comparison is consulted (starlark CompareDepth gates CompareSameType behind sameType). So a List holding inert elements does not refuse a membership test — it silently answers "no", and a guard takes the wrong branch. Roles escaped that only by holding plain starlark.String, the one element type text() accepts as authored SQL. The container therefore worked exactly when the element was unsafe: for as long as a List was the container, safety and the `in` idiom were opposed, and every caller collection had to give up one of them.

IdentSet ends the opposition by answering membership itself, comparing by text, while handing out *Ident from index and iteration. `"admin" in ctx.roles` reads exactly as it always did, and text(ctx.roles[0]) is refused by the gate *Ident already passes through — so this type adds no new refusal, it only puts the existing ones in reach.

func (*IdentSet) Binary 

func (s *IdentSet) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error)

Binary refuses `+`, exactly as *Val and *Ident do: a caller name glued to authored text would launder provenance and could reach SQL as structure.

func (*IdentSet) CompareSameType 

func (s *IdentSet) CompareSameType(op syntax.Token, y starlark.Value, depth int) (bool, error)

CompareSameType answers == and != by content. Without it, two sets holding the same names fall to identity comparison and report unequal — the same silent lie in a third costume. Ordering is refused: a set of names has no order.

func (*IdentSet) Freeze 

func (s *IdentSet) Freeze()

func (*IdentSet) Has 

func (s *IdentSet) Has(x starlark.Value) (bool, error)

Has answers `x in set` (starlark.Container), comparing by text so the authored idiom is unchanged. A probe with no name reading is REFUSED rather than reported as absent: a membership test that cannot be performed must never come back as a negative result. That silent negative is the defect this type exists to make unrepresentable.

func (*IdentSet) Hash 

func (s *IdentSet) Hash() (uint32, error)

func (*IdentSet) Index 

func (s *IdentSet) Index(i int) starlark.Value

Index is the ONE place an element is made; Iterate and idents both route through it, so what a caller can ever hold is decided in a single line.

func (*IdentSet) Iterate 

func (s *IdentSet) Iterate() starlark.Iterator

func (*IdentSet) Len 

func (s *IdentSet) Len() int

func (*IdentSet) String 

func (s *IdentSet) String() string

func (*IdentSet) Truth 

func (s *IdentSet) Truth() starlark.Bool

func (*IdentSet) Type 

func (s *IdentSet) Type() string

type InertGateFinding 

type InertGateFinding = inertGateFinding

InertGateFinding is one completeness gate made redundant by upstream gates.

func FunctionInertGates 

func FunctionInertGates(plan *function.Plan) []InertGateFinding

FunctionInertGates returns redundant completeness gates.

type InstRef 

type InstRef struct {
	Table string
	Alias string
}

InstRef is one table occurrence found by the authored-SQL scanner.

func TableRefs 

func TableRefs(sql string) []InstRef

TableRefs returns table occurrences without exposing scanner internals.

type Instance 

type Instance struct {
	Rel   *Relation
	Alias string
	Line  int
	// File is where Line was captured. Instances are usually created *inside*
	// the stdlib (view.make calls source/join_one for the author), so Line is a
	// module coordinate; printing it against the entrypoint's name yields a
	// location that is meaningless at best and past EOF at worst — measured at
	// line 145 of a 64-line file (blueprint 13 §9.2, round eighteen). Recording
	// the origin lets a diagnostic tell whether the line belongs to the file it
	// is about to name.
	File string
}

Instance is a relation×alias occurrence recorded by source/join.

type Loader 

type Loader struct {
	Root       string
	Repository *Repository
	Dialect    string
	Ctx        *Context
	Pure       bool
	// contains filtered or unexported fields
}

Loader resolves load() paths, runs modules once per session, and detects cycles. Starlark modules are frozen after load, which gives per-run immutability for free.

func NewRepositoryLoader 

func NewRepositoryLoader(repository *Repository, man *Manifest, ctx *Context) *Loader

NewRepositoryLoader creates a loader session. The module-load phase is ALWAYS pure: params()/example()/relation()/def and any Set-label expression run with `ctx` inert (access is RQL1008), so the typed surface can never depend on the caller's context and `requel inspect` describes exactly what `requel render` serves. Render flips the context live with SetLive() only for the query(p) call and guard evaluation (blueprint 13 §4 — load purity is a property, not a mode).

It takes the whole manifest rather than the dialect alone: repository policy (dialect, row cap) is what configures a session, and a ceiling a caller can forget to install is not a ceiling. NewRepositoryLoader creates a compiler session over an immutable repository snapshot. No module load performed by this loader can reach the host filesystem.

func NewRepositoryLoaderFor 

func NewRepositoryLoaderFor(repository *Repository, man *Manifest, ctx *Context, dialect string) *Loader

NewRepositoryLoaderFor is NewRepositoryLoader with an explicit render dialect. An empty dialect means the repository's [project].dialect, which is what every offline path uses; the execute/serve paths pass the *connector's* dialect, because `dialect()` is read during query(p) — rql:time and rql:filters branch on it while assembling — so a dialect chosen only at lowering would be too late.

func (*Loader) InstallHostModules 

func (l *Loader) InstallHostModules(modules map[string]starlark.StringDict)

InstallHostModules installs one already-validated, trusted module set for this loader session. Model code can reach it only through load("host:name").

func (*Loader) LoadForThread 

func (l *Loader) LoadForThread(thread *starlark.Thread, path string) (starlark.StringDict, error)

LoadForThread resolves one module using an existing bounded thread.

func (*Loader) LoadModule 

func (l *Loader) LoadModule(path string) (starlark.StringDict, string, *Diagnostic)

LoadModule loads a file as a module, returning its globals.

func (*Loader) NewThread 

func (l *Loader) NewThread(label string) *starlark.Thread

NewThread exposes one bounded evaluation thread to compiler-adjacent inspection tools.

func (*Loader) ReadSource 

func (l *Loader) ReadSource(key string, isStd bool) (string, *Diagnostic)

ReadSource returns the source for a resolved key.

func (*Loader) SetLive 

func (l *Loader) SetLive()

SetLive makes `ctx` readable — called by Render after the pure load, before the query(p) call and guard evaluation. Everything that ran during load has already been frozen by Starlark, so nothing observed the flip retroactively.

func (*Loader) SetRelationBindings 

func (l *Loader) SetRelationBindings(bindings map[string]string) *Diagnostic

SetRelationBindings installs the trusted host's physical placement before model evaluation. Declarations retain their logical identity; the placement is visible only while SQL is lowered for this compilation.

func (*Loader) Source 

func (l *Loader) Source(label string) string

Source returns cached source text for a label.

func (*Loader) State 

func (l *Loader) State() *State

State returns the run state (warnings, relations, declarations).

type Manifest 

type Manifest struct {
	Project struct {
		Name    string `toml:"name"`
		Dialect string `toml:"dialect"`
		Std     string `toml:"std"`
	} `toml:"project"`
	Guards struct {
		Require []string `toml:"require"`
		// SuggestColumns are the column names that mark a row's tenancy scope,
		// for the RQL3025 onboarding lint: a relation over a table the committed
		// schema snapshot says carries one of these, and that declares no guard,
		// is a finding. Globs, matched case-insensitively like `require`.
		//
		// Absent falls back to connector.ScopingColumnDefaults, a deliberately
		// short list. Setting it *replaces* the default rather than extending
		// it, so a repo whose tenancy column is spelled locally (`site_id`) gets
		// exactly the check it asked for, and a repo that wants the lint off
		// says so once in `[lint]` instead of fighting a list it did not write.
		SuggestColumns []string `toml:"suggest_columns"`
	} `toml:"guards"`
	Render struct {
		DefaultMode string `toml:"default_mode"`
	} `toml:"render"`
	// Limits is the repository-wide row-cap policy. Without it the authored
	// maximum lives only at the call site (`limit = {"n": p.limit, "max": …}`),
	// so one entrypoint can quietly ship a 50-million-row cap and no reviewer
	// sees it centrally. max_rows is a ceiling, not a default: a per-entrypoint
	// maximum may tighten it, never exceed it (enforced in limit_clause,
	// RQL2010). Absent [limits] means no ceiling.
	Limits struct {
		MaxRows int `toml:"max_rows"`
		// MaxMemoryMB bounds the heap one evaluation may allocate (membudget.go).
		// Unlike max_rows, absence does NOT mean unbounded: it means the
		// DefaultMaxMemoryMB budget, because `requel serve` executes model-authored
		// code in a long-lived process and an opt-in memory bound is no bound at
		// all there. The key exists to *move* the budget, not to create it.
		MaxMemoryMB int `toml:"max_memory_mb"`
	} `toml:"limits"`
	Lint map[string]string `toml:"lint"`
	// Connectors reuses requel's manifest shape so both CLIs share the connector
	// layer (drivers, read-only posture, secrets-via-env; blueprint 07 §6).
	Connectors map[string]manifest.Connector `toml:"connectors"`
	// Context is identity at the MCP serving boundary (blueprint 02 §5.2), and
	// is likewise the same table `requel.toml` declares: one host mints one token
	// and both CLIs must accept or refuse it identically. Absent means the open
	// posture of §5.1.
	Context ctxsign.Policy `toml:"context"`
	// Observability is the serving runtime's telemetry and admission-control
	// policy. The shape lives in the shared manifest package rather than here,
	// which is what let the two engines accept one table while each emitted
	// diagnostics in its own namespace; only this loader remains.
	Observability manifest.Observability `toml:"observability"`
	// Audit is where the accountable execution trail is persisted and how durably
	// the runtime must record a run. Like [observability] the shape lives in the
	// shared manifest package; absent means the historical best-effort JSON line.
	Audit manifest.Audit `toml:"audit"`
	// Function is the closed policy for composing terminal entrypoints. Targets
	// are logical authored names mapped to existing connector names; allowed
	// flows authorize directed data egress between those logical targets.
	Function struct {
		MaxSteps        int               `toml:"max_steps"`
		MaxDepth        int               `toml:"max_depth"`
		MaxFanoutValues int               `toml:"max_fanout_values"`
		MaxCells        int               `toml:"max_cells"`
		MaxParallel     int               `toml:"max_parallel"`
		Timeout         string            `toml:"timeout"`
		AllowedFlows    []string          `toml:"allowed_flows"`
		Targets         map[string]string `toml:"targets"`
	} `toml:"function"`
}

Manifest is requel.toml.

type Meta 

type Meta struct {
	Instances  []Instance
	Edges      []Edge
	Aggregates []Aggregate
	FanoutAcks []Ack
	// UnbridgedAcks records allow_unbridged acknowledgements. Separate from
	// FanoutAcks because the two answer different questions and a reviewer needs
	// to tell them apart: one says a multiplied row set still totals correctly,
	// the other says two value spaces correspond. Collapsing them would let a
	// fan-out reason silence a namespace mismatch.
	UnbridgedAcks []Ack
	// NeighbourhoodAcks records via_neighbourhood acknowledgements. A third list
	// rather than a third use of the first two, because it answers a question
	// neither does: not "this total survives a multiplied row set" and not "these
	// two value spaces correspond", but "the rows this query pairs are a guess,
	// and here is which guess". Folding it into UnbridgedAcks would let a
	// correspondence argument stand in for a similarity one, which is the exact
	// substitution the whole mechanism exists to refuse.
	NeighbourhoodAcks []NeighbourhoodAck
	Filterables       []FilterableInfo
}

Meta is fragment analysis metadata.

func (*Meta) MergeInto 

func (m *Meta) MergeInto(src Meta)

MergeInto merges src metadata into m.

type Mode 

type Mode int

Mode selects bind placeholders or inline literals. 

const (
	Binds Mode = iota
	Inline
)

Render modes.

type MonoDir 

type MonoDir = monoDir

MonoDir is a monotone measure's direction under truncation.

type Namespace 

type Namespace struct {
	Name  string
	Guard starlark.Callable
	Pin   starlark.Callable
	Doc   string
	File  string
	Line  int
}

Namespace is a declared turbopuffer namespace — the retrieval analog of Relation. Guard is a zero-argument callable over ctx returning filter conditions (or the Unrestricted sentinel); there is no alias to hand it because a retrieval request has exactly one namespace and no joins.

Pin is the namespace-per-tenant isolation model turbopuffer itself favors (blueprint 16 §8): a zero-argument callable over ctx whose value becomes a suffix of the wire namespace (`<name>-<pin>`), so each caller's documents live in a namespace the others' requests cannot even address. It is the one place identity data enters a *name* position, and it is sound for the same reason guard predicates reading ctx are: ctx is the operator-controlled channel (pinned/signed modes; `open` is the documented no-invariant dev posture), and biNamespace refuses a pin declared anywhere caller params are in scope.

func (*Namespace) Attr 

func (n *Namespace) Attr(name string) (starlark.Value, error)

Attr exposes read-only namespace fields to Starlark, mirroring Relation.

func (*Namespace) AttrNames 

func (n *Namespace) AttrNames() []string

AttrNames lists namespace fields.

func (*Namespace) DisplayName 

func (n *Namespace) DisplayName() string

DisplayName is the reviewer-facing namespace: the wire name for a plain namespace, `<name>.{pin}` for a pinned one — the placeholder says "resolved per caller" without pretending any one resolution is the namespace.

func (*Namespace) Freeze 

func (n *Namespace) Freeze()

func (*Namespace) Hash 

func (n *Namespace) Hash() (uint32, error)

func (*Namespace) String 

func (n *Namespace) String() string

func (*Namespace) Truth 

func (n *Namespace) Truth() starlark.Bool

func (*Namespace) Type 

func (n *Namespace) Type() string

type NamespaceDecl 

type NamespaceDecl struct {
	Backing string            `json:"backing"`
	Columns map[string]string `json:"columns"`
}

NamespaceDecl is one relation's declared column labels, for `explain` and `inspect`.

func NamespaceDecls 

func NamespaceDecls(frag *Fragment) []NamespaceDecl

NamespaceDecls lists the namespace labels every relation in a fragment declares, deduplicated by relation and sorted by backing.

type Neighbourhood 

type Neighbourhood struct {
	ID   int
	Name string

	// Edges is the relation holding the rows, and FromKey/ToKey the columns
	// carrying each end.
	Edges   *Relation
	FromKey []string
	ToKey   []string

	// From and To are the corpus relations each end refers to, and FromBridge /
	// ToBridge the certified identity bridges that make those two joins legal.
	// Spelled `from_relation` and `to_relation` in the language, because `from`
	// is a Starlark keyword and a declaration using it does not parse at all —
	// the whole module fails with a syntax error that names neither the argument
	// nor the file's real problem.
	// Without them the edge table meets the corpus on an equality nobody
	// certified, which RQL3048 would refuse anywhere else.
	From, To             *Relation
	FromBridge, ToBridge string

	Family, Method string
	PolicyDigest   string
	CorpusRelease  string
	Metric         string
	Threshold      float64
	ScoreColumns   map[string]string

	Source      string
	EdgeRelease string
	Receipt     string
	QueryCount  int

	// ScopeKeys are columns a query joining these rows must stay restricted on.
	// See RQL3063.
	ScopeKeys []string
	// Certifications are the transfer measurements over THIS policy and cutoff.
	// Empty means traversable and licensing no annotation to move.
	Certifications []string

	Doc  string
	File string
	Line int
}

Neighbourhood is a declared similarity edge set.

It is deliberately NOT a *Bridge and shares no code with one. The fields line up well enough that a shared type would be tempting, and that is exactly the hazard: every check in bridge_analysis.go treats a Bridge as a licence, and a similarity edge set inheriting that treatment is the failure this whole file exists to prevent.

func (*Neighbourhood) Certified 

func (n *Neighbourhood) Certified() bool

Certified reports whether anything measured what crossing this set costs.

func (*Neighbourhood) Cutoff 

func (n *Neighbourhood) Cutoff() string

Cutoff renders the threshold the way the declaration wrote it.

func (*Neighbourhood) Freeze 

func (n *Neighbourhood) Freeze()

func (*Neighbourhood) Hash 

func (n *Neighbourhood) Hash() (uint32, error)

func (*Neighbourhood) String 

func (n *Neighbourhood) String() string

func (*Neighbourhood) Truth 

func (n *Neighbourhood) Truth() starlark.Bool

func (*Neighbourhood) Type 

func (n *Neighbourhood) Type() string

type NeighbourhoodAck 

type NeighbourhoodAck struct {
	Name   string
	Reason string
	Edges  []string
	Line   int
}

NeighbourhoodAck records one via_neighbourhood.

It carries the edge set's NAME as well as the reason, which Ack does not need: an unbridged acknowledgement is about the columns it wrapped and there is nothing else to identify, while a traversal has to say which of possibly several guesses was made, or RQL3061 cannot tell one hop from two.

type NullCompareFinding 

type NullCompareFinding = nullCompareFinding

NullCompareFinding is one nullable comparison without explicit null semantics.

func FunctionNullCompares 

func FunctionNullCompares(plan *function.Plan) []NullCompareFinding

FunctionNullCompares returns nullable comparisons that need explicit semantics.

type ObjectAggregateCompileRequest 

type ObjectAggregateCompileRequest struct {
	Root             string
	Repository       *Repository
	Manifest         *Manifest
	ObjectType       string
	Filter           *ObjectFilter
	GroupBy          []string
	Measures         []ObjectAggregateMeasure
	Limit            int
	Context          *Context
	Dialect          string
	Decorator        ObjectSourceDecorator
	RelationBindings map[string]string
}

type ObjectAggregateMeasure 

type ObjectAggregateMeasure struct {
	Name     string
	Op       string
	Property string
}

type ObjectAggregateRenderResult 

type ObjectAggregateRenderResult struct {
	ObjectType         string
	Dependencies       []string
	DependencyCoverage string
	Columns            []ObjectColumn
	Rows               *RenderResult
	SourceAccesses     []SourceAccess
}

type ObjectColumn 

type ObjectColumn struct {
	Name       string   `json:"name"`
	Type       string   `json:"type"`
	IsKey      bool     `json:"is_key"`
	IsNullable bool     `json:"is_nullable"`
	Labels     []string `json:"labels,omitempty"`
	Format     string   `json:"format,omitempty"`
}

type ObjectDecl 

type ObjectDecl struct {
	Name    string // declared name=, the identity used in dimension keys
	Local   string // module-level variable it binds to — what load() exports
	Nominal bool   // object.make, rather than the analytical semantic.make twin
	Backing string // resolved backing table, "" when the identifier is opaque
	// BackingExpr is the identifier `backing =` was written as, kept so a
	// relation declared in *another* module can be resolved in a second pass.
	// Relations living in their own file is the layout `requel init` scaffolds and
	// every example uses, so this is the common case, not an exotic one.
	BackingExpr string
	Guarded     bool
	File        string
	Line        int
	Edges       []HalfEdge
}

ObjectDecl is a statically discovered nominal object or analytical semantic namespace. Nominal records whether it belongs to the operational catalog.

type ObjectExprOp 

type ObjectExprOp string
const (
	ObjectAnd       ObjectExprOp = "and"
	ObjectOr        ObjectExprOp = "or"
	ObjectNot       ObjectExprOp = "not"
	ObjectPredicate ObjectExprOp = "predicate"
)

type ObjectFilter 

type ObjectFilter struct {
	Op       ObjectExprOp   `json:"op"`
	Args     []ObjectFilter `json:"args,omitempty"`
	Arg      *ObjectFilter  `json:"arg,omitempty"`
	Property string         `json:"property,omitempty"`
	Operator string         `json:"operator,omitempty"`
	Value    any            `json:"value,omitempty"`
}

type ObjectGetCompileRequest 

type ObjectGetCompileRequest struct {
	Root             string
	Repository       *Repository
	Manifest         *Manifest
	ObjectType       string
	Key              string
	Select           []string
	Context          *Context
	Dialect          string
	Decorator        ObjectSourceDecorator
	RelationBindings map[string]string
}

type ObjectKeyProbeCompileRequest 

type ObjectKeyProbeCompileRequest struct {
	Root             string
	Repository       *Repository
	Manifest         *Manifest
	ObjectType       string
	Context          *Context
	Dialect          string
	Decorator        ObjectSourceDecorator
	RelationBindings map[string]string
}

type ObjectKeyProbeRenderResult 

type ObjectKeyProbeRenderResult struct {
	ObjectType         string
	Key                []string
	Dependencies       []string
	DependencyCoverage string
	Rows               *RenderResult
}

type ObjectListCompileRequest 

type ObjectListCompileRequest struct {
	Root             string
	Repository       *Repository
	Manifest         *Manifest
	ObjectType       string
	Select           []string
	Filter           *ObjectFilter
	Sort             []ObjectSort
	Limit            int
	Offset           int
	IncludeTotal     bool
	Context          *Context
	Dialect          string
	Decorator        ObjectSourceDecorator
	RelationBindings map[string]string
}

type ObjectProperty 

type ObjectProperty struct {
	ScalarType ScalarType
	Nullable   bool
	Writable   bool
	Read       starlark.Callable
	Doc        string
	Label      string
	Labels     []string
	Format     string
	File       string
	Line       int
}

ObjectProperty is the immutable value returned by prop(). Its name belongs to the insertion-ordered object properties dictionary, so the value carries only the contract shared by declaration, catalog, decoder, and action input.

func (*ObjectProperty) Attr 

func (p *ObjectProperty) Attr(name string) (starlark.Value, error)

func (*ObjectProperty) AttrNames 

func (p *ObjectProperty) AttrNames() []string

func (*ObjectProperty) Freeze 

func (p *ObjectProperty) Freeze()

func (*ObjectProperty) Hash 

func (p *ObjectProperty) Hash() (uint32, error)

func (*ObjectProperty) String 

func (p *ObjectProperty) String() string

func (*ObjectProperty) Truth 

func (p *ObjectProperty) Truth() starlark.Bool

func (*ObjectProperty) Type 

func (p *ObjectProperty) Type() string

type ObjectRenderResult 

type ObjectRenderResult struct {
	ObjectType         string         `json:"object_type"`
	SchemaHash         string         `json:"schema_hash"`
	Dependencies       []string       `json:"dependencies"`
	DependencyCoverage string         `json:"dependency_coverage"`
	Columns            []ObjectColumn `json:"columns"`
	Rows               *RenderResult  `json:"rows"`
	Count              *RenderResult  `json:"count,omitempty"`
	Limit              int            `json:"limit"`
	Offset             int            `json:"offset"`
	Cardinality        string         `json:"cardinality"`
	SourceAccesses     []SourceAccess `json:"source_accesses"`
}

type ObjectSort 

type ObjectSort struct {
	Property string `json:"property"`
	IsDesc   bool   `json:"is_desc"`
}

type ObjectSourceDecorationRequest 

type ObjectSourceDecorationRequest struct {
	Object CatalogObject
	Alias  string
}

type ObjectSourceDecorator 

type ObjectSourceDecorator interface {
	DecorateObjectSource(ObjectSourceDecorationRequest) (ObjectSourceWrapper, *Diagnostic)
}

ObjectSourceDecorator is the provisional trusted-host seam for wrapping an already authorized object source. It is deliberately absent from Starlark.

type ObjectSourceWrapper 

type ObjectSourceWrapper struct {
	Before    string
	After     string
	Binds     []Bind
	Relations []string
}

type ObjectTraversalCompileRequest 

type ObjectTraversalCompileRequest struct {
	Root             string
	Repository       *Repository
	Manifest         *Manifest
	SourceType       string
	SourceKey        string
	Edge             string
	Select           []string
	Filter           *ObjectFilter
	Sort             []ObjectSort
	Limit            int
	Offset           int
	IncludeTotal     bool
	Context          *Context
	Dialect          string
	Decorator        ObjectSourceDecorator
	RelationBindings map[string]string
}

type ObjectTypeValue 

type ObjectTypeValue struct {
	// contains filtered or unexported fields
}

ObjectTypeValue is the immutable nominal value returned by object.make. Its fields implement Requel's object protocol, while its distinct Starlark type prevents an unrelated struct with similar attributes from becoming an operational object reference.

func (*ObjectTypeValue) Attr 

func (v *ObjectTypeValue) Attr(name string) (starlark.Value, error)

func (*ObjectTypeValue) AttrNames 

func (v *ObjectTypeValue) AttrNames() []string

func (*ObjectTypeValue) Freeze 

func (v *ObjectTypeValue) Freeze()

func (*ObjectTypeValue) Hash 

func (v *ObjectTypeValue) Hash() (uint32, error)

func (*ObjectTypeValue) String 

func (v *ObjectTypeValue) String() string

func (*ObjectTypeValue) Truth 

func (v *ObjectTypeValue) Truth() starlark.Bool

func (*ObjectTypeValue) Type 

func (v *ObjectTypeValue) Type() string

type OrderIn 

type OrderIn struct {
	Key   string
	Dir   string
	Nulls string
}

OrderIn is a validated OrderInput.

func (*OrderIn) Attr 

func (o *OrderIn) Attr(name string) (starlark.Value, error)

Attr exposes order fields as *Ident, the inert caller-name type: an author branches on them with `.eq("…")` but can never render one as SQL text.

func (*OrderIn) AttrNames 

func (o *OrderIn) AttrNames() []string

AttrNames lists order fields.

func (*OrderIn) Freeze 

func (o *OrderIn) Freeze()

func (*OrderIn) Hash 

func (o *OrderIn) Hash() (uint32, error)

func (*OrderIn) String 

func (o *OrderIn) String() string

func (*OrderIn) Truth 

func (o *OrderIn) Truth() starlark.Bool

func (*OrderIn) Type 

func (o *OrderIn) Type() string

type OrderingPair 

type OrderingPair = orderingPair

OrderingPair is one ordered comparison between qualified columns.

func OrderingPairs 

func OrderingPairs(text string) []OrderingPair

OrderingPairs extracts ordered comparisons from a join predicate.

type ParamDecl 

type ParamDecl struct {
	Name string
	Type *ParamType
	Line int
}

ParamDecl is one entry in the params() declaration.

type ParamType 

type ParamType struct {
	Kind       string // Str Int Float Bool Date Timestamp Set List FilterInput OrderInput
	Labels     []string
	Elem       *ParamType
	Default    starlark.Value
	HasDefault bool
	Optional   bool
	Require    string
	Doc        string
}

ParamType is a declared parameter type. Rather than being grammar, RQL types are ordinary values built by constructor builtins — which makes docs data (`doc=`) rather than comments (blueprint 13 §4).

Two kinds are bound as bare values rather than constructors, because they take no arguments to attach: `FilterInput` and `OrderInput`. A parameter of either carries the wire shapes a caller sends — `FilterInput` a list of `{"key", "op", "value"}` filter objects, checked against the object's filterable registry, and `OrderInput` a list of `{"key", "dir", "nulls"}` ordering objects. An ontology may also write either shape as a literal, which is what lets a function terminal restrict itself without abandoning `view.make`.

func (*ParamType) Freeze 

func (p *ParamType) Freeze()

func (*ParamType) Hash 

func (p *ParamType) Hash() (uint32, error)

func (*ParamType) String 

func (p *ParamType) String() string

func (*ParamType) Truth 

func (p *ParamType) Truth() starlark.Bool

func (*ParamType) Type 

func (p *ParamType) Type() string

type Pos 

type Pos struct {
	Line int `json:"line"`
	Col  int `json:"col"`
}

Pos is a 1-based source position.

type QualifiedRef 

type QualifiedRef = qualifiedRef

QualifiedRef is one alias-qualified SQL column reference.

type RelDecl 

type RelDecl struct {
	Backing string
	Key     []string
	Guarded bool
	File    string
	Line    int
}

RelDecl is a statically-discovered relation declaration: which backing it covers, which key columns it declares, whether it carries a guard, and where it lives. 

type Related struct {
	File string `json:"file"`
	Span Span   `json:"span"`
	Note string `json:"note"`
}

Related is a secondary span attached to a diagnostic.

type Relation 

type Relation struct {
	ID      int
	Backing string

	// Query is an authored parameterless read-only source. It is mutually
	// exclusive with a physical Backing and renders as a derived table.
	Query string
	Reads []string
	Key   []string
	// Unkeyed is why no column set makes this relation's rows unique, when that
	// is the truth about it. Empty for a keyed relation.
	//
	// It exists because the alternative is a fabricated key, and a fabricated
	// key is worse than none: it is indistinguishable from a real one, so a
	// to-one claim over the relation is believed, the row set multiplies, and
	// the aggregate over it is wrong in a way no check can see. Measured on
	// wwpdb/derived#pdb_resolution, which declared `PDB` while releasing 257,342
	// rows over 257,179 accessions.
	Unkeyed string
	Guard   starlark.Callable
	Doc     string
	// RequireFilter names columns of which at least one must be constrained by
	// every query touching this relation. The guard protects rows; this protects
	// scan cost — the analog of BigQuery's `require_partition_filter`. Plain
	// column names, never rendered: analysis matches them against
	// `<alias>.<column>` in the scope's predicates (blueprint 13 §5, RQL3022).
	RequireFilter []string
	// Namespaces labels columns with the value space they live in — an opaque
	// string this package never interprets. Equating two labeled columns whose
	// labels differ is refused unless a bridge declares the correspondence
	// (RQL3048, bridge.go). Like RequireFilter these are plain column names,
	// never rendered: analysis matches them against `<alias>.<column>` in a
	// declared edge's `on` predicate.
	Namespaces map[string]string
	File       string
	Line       int
	// NeighbourhoodEdges names the similarity edge set this relation holds the
	// rows of, when it holds one.
	//
	// It rides the RELATION rather than only the neighbourhood declaration
	// because the gate was fail-OPEN without it, and measured that way: the
	// declaration lives in its own module, a query that never loads that module
	// declares no neighbourhood, and RQL3060 then has nothing to fire on. The
	// query renders clean and joins through a similarity edge set as though it
	// were an identity, which is the exact outcome the rule exists to prevent.
	//
	// Bridges do not have this problem, and the asymmetry is why this field
	// exists. An unloaded bridge module means a cross-namespace join is REFUSED:
	// missing evidence reads as "not certified", which fails closed. An unloaded
	// neighbourhood module meant missing evidence read as "not a guess", which
	// fails open. A relation cannot be queried without being loaded, so putting
	// the marker here makes the evidence arrive with the rows.
	NeighbourhoodEdges string
	// contains filtered or unexported fields
}

Relation is a declared table with a key and an optional row-level guard.

func (*Relation) Attr 

func (r *Relation) Attr(name string) (starlark.Value, error)

Attr exposes read-only relation fields to Starlark.

func (*Relation) AttrNames 

func (r *Relation) AttrNames() []string

AttrNames lists relation fields.

func (*Relation) Freeze 

func (r *Relation) Freeze()

func (*Relation) Hash 

func (r *Relation) Hash() (uint32, error)

func (*Relation) String 

func (r *Relation) String() string

func (*Relation) Truth 

func (r *Relation) Truth() starlark.Bool

func (*Relation) Type 

func (r *Relation) Type() string

type RelationSite 

type RelationSite struct {
	Backing string
	Key     []string
	Guarded bool
	Public  bool
	Reason  string
	File    string
	Line    int
}

RelationSite is one relation() declaration and its source location.

func RelationDeclSites 

func RelationDeclSites(files map[string]string) []RelationSite

RelationDeclSites scans every source for relation() calls in stable order.

type RelativeCompareHazard 

type RelativeCompareHazard = relativeCompareHazard

RelativeCompareHazard is one comparison that can become vacuous under scaling.

func VacuousRelativeCompares 

func VacuousRelativeCompares(plan *function.Plan) []RelativeCompareHazard

VacuousRelativeCompares returns scale-relative comparisons that can be vacuous.

type RenderBridge 

type RenderBridge struct {
	Name  string `json:"name"`
	Lossy bool   `json:"lossy,omitempty"`
	// LTRCoverage travels with the traversal so a diagnostic can say HOW lossy.
	// `Lossy` alone cannot separate a mapping that carries 99% of its rows from
	// one that carries a third.
	LTRCoverage CoverageBound `json:"ltr_coverage"`
}

RenderBridge is one correspondence a render crossed, as the execute path needs it: the name a lock pins, and the one property that changes what an absent row means.

func LossyBridges 

func LossyBridges(bridges []RenderBridge) []RenderBridge

LossyBridges returns the traversed correspondences declared lossy, with what was measured about each. The names alone told a reader that something was dropped but never how much, so a 99.4% mapping and a 34% one read identically.

type RenderResult 

type RenderResult struct {
	SQL        string         `json:"sql"`
	Mode       string         `json:"mode"`
	Binds      []BindOut      `json:"binds"`
	Guards     []GuardOut     `json:"guards"`
	FanoutAcks []FanoutAckOut `json:"fanout_acks"`
	Warnings   []WarningOut   `json:"warnings"`
	// Relations is every relation address this render placed, sorted. Empty for
	// a render that placed none, which keeps an existing render document
	// byte-identical.
	Relations []string       `json:"relations,omitempty"`
	Retrieval *RetrievalOut  `json:"retrieval,omitempty"`
	Function  *function.Plan `json:"function,omitempty"`
	// EmittedLimits is the literal row bound of every LIMIT this render wrote.
	// An execution compares its row count against these to tell whether the
	// answer stopped at a bound the entrypoint set — which no other signal
	// reports, because the cursor ends naturally and no client cap is reached
	// (see connector.TruncatedByAuthoredLimit). Omitted when the render emitted
	// none, so an existing render document is byte-identical.
	EmittedLimits []int `json:"emitted_limits,omitempty"`
	// SingleRow reports that this render's result is one row by construction: a
	// single grouped SELECT whose validated grouping was empty beside at least one
	// aggregate. It exists so the EmittedLimits inference above is not drawn over
	// a result whose row count could not have been larger — see State.groupings
	// for the whole argument. False for every other render, including a
	// hand-assembled fragment, which is what keeps the exemption evidence-based;
	// omitted from the document so an existing render is byte-identical.
	SingleRow bool `json:"single_row,omitempty"`
	// Bridges names the certified correspondences this render traversed
	// (blueprint 03 §3.3), with the one property that changes what a result
	// means.
	//
	// It rides the render for EmittedLimits' reason — the fact belongs to the
	// load that produced this SQL, and the execute path is where it is needed —
	// and it has two consumers that need different halves, which is why it is
	// one field and not two overlapping lists:
	//
	//   - the LOSSY ones answer the question completeness already exists to
	//     answer. A truncated search cannot support an absence claim because the
	//     missing row might be among the ones dropped; a lossy correspondence
	//     cannot support one because the missing row might be among the ones the
	//     mapping does not carry. Same hazard, different route, so it feeds the
	//     same machinery: a function call node turns each into an
	//     `incomplete_reasons` entry and `require_complete` refuses unchanged.
	//   - ALL of them are what the release check compares against `bridges.lock`
	//     before the answer is used, which is the correspondence twin of the data
	//     pin's question: not "which bytes answered" but "was the correspondence
	//     this answer crossed certified against those bytes".
	//
	// Omitted when the render traversed none, which is every repository that
	// declares no bridge — so an existing render document, and the fingerprint
	// taken over it, is byte-identical.
	Bridges []RenderBridge `json:"bridges,omitempty"`
	// ResultSchema is the entrypoint's declared returns() contract, carried here
	// so the execute path can hold the result to it. Nil for the entrypoints —
	// the great majority — that declare none, and omitted from the document so an
	// existing render is byte-identical.
	//
	// It rides the render rather than being re-read at execute because the
	// declaration belongs to the same load that produced this SQL; fetching it
	// again would let the two describe different versions of the file.
	ResultSchema *function.Schema `json:"result_schema,omitempty"`
}

RenderResult is a rendered query. For a retrieval entrypoint (mode "retrieval") SQL carries the pretty-printed request body — the reviewable text every surface already prints — and Retrieval carries the compact wire form `requel execute` POSTs; Binds is always empty there because a JSON body has no placeholder positions to fill.

func Lower 

func Lower(frag *Fragment, dialect string, mode Mode) *RenderResult

Lower renders a fragment to SQL in the given mode and dialect.

type Repository 

type Repository struct {
	// contains filtered or unexported fields
}

Repository is an immutable snapshot of every regular file visible to a model. It is the compiler's only authored-source input; paths are labels within the snapshot, never capabilities for reading the host filesystem.

func NewEmptyRepository 

func NewEmptyRepository(root string) *Repository

NewEmptyRepository returns an immutable repository with no files. It is useful for evaluating standalone Starlark snippets that only use predeclared compiler values.

func SnapshotRepository 

func SnapshotRepository(ctx context.Context, source fs.FS) (*Repository, error)

SnapshotRepository copies source into immutable compiler-owned memory.

func SnapshotRepositoryAt 

func SnapshotRepositoryAt(ctx context.Context, source fs.FS, root string) (*Repository, error)

SnapshotRepositoryAt copies source into immutable compiler-owned memory and uses root only as the display namespace for diagnostics and path resolution. The compiler never opens root; filesystem-backed callers may therefore keep familiar absolute source labels without granting compilation filesystem access.

func (*Repository) AuthoredSources 

func (r *Repository) AuthoredSources() map[string]string

AuthoredSources returns a defensive copy of authored RQL modules, excluding the vendored standard library.

func (*Repository) DefinitionDigest 

func (r *Repository) DefinitionDigest() string

DefinitionDigest identifies the complete authored semantic input in stable path order. It reads only the snapshot and therefore cannot observe drift.

func (*Repository) Path 

func (r *Repository) Path(label string) (string, bool)

Path resolves a confined repository label to its virtual absolute path.

func (*Repository) Root 

func (r *Repository) Root() string

Root is a stable virtual root used only for source labels and lexical path resolution inside the compiler.

type Request 

type Request struct {
	Root       string
	Repository *Repository
	Manifest   *Manifest
	Path       string // absolute path to the entrypoint
	Params     map[string]any
	Context    *Context
	Mode       Mode
	// Dialect is the SQL dialect to render for. Empty means [project].dialect,
	// which is every offline path: `render`, `test`, `inspect`, `diff` and the
	// goldens all speak the repository's declared dialect.
	//
	// The execute/serve paths set it from the *connector*, because a render is
	// only correct for the engine it is sent to. `turso` renders sqlite and
	// `supabase` renders postgres, so the driver name is not the answer —
	// manifest.DriverDialect is. Before this existed, `[project].dialect` was
	// used unconditionally, so executing against a connector of another dialect
	// put the wrong SQL on the wire: postgres `ILIKE` reached SQLite as a syntax
	// error, and — the dangerous half — a rendered `||` would have reached MySQL
	// as logical OR and returned a boolean instead of a concatenation, with no
	// error at all.
	//
	// It is threaded into evaluation and not only into Lower because `dialect()`
	// is a kernel builtin the stdlib branches on: rql:time picks its truncation
	// and rql:filters its case-insensitive form while query(p) runs, long before
	// lowering.
	Dialect string
	// RelationBindings is trusted host placement for this compilation. Analysis
	// and provenance continue to expose logical relation identities.
	RelationBindings map[string]string
	// AuthorGoldens is set only by `requel test --update`, which renders an
	// entrypoint in order to write its examples' goldens. It permits the one
	// declaration that path exists to resolve — an explicitly-empty
	// `renders = ""` (see State.authorGoldens) — and changes nothing else.
	AuthorGoldens bool
	// ImpliedGuardedBackings are backings that some `relation()` declaration in
	// the repository guards (repoGuardedBackings). The render SQL leg treats them
	// as implicitly required-guarded, so an unguarded twin declaration over the
	// same table fails closed (RQL3002) instead of rendering unfiltered SQL — the
	// RQL3029 bypass, refused at render time rather than only under lint. Populated
	// only by the execute/serve path (runtime.runExecute), where it is computed
	// once per runtime; empty on the pure `render`/`test` paths, which keep their
	// current behavior. The per-render repository walk that
	// lint_duplicate_declaration.go forbids is avoided because this is computed
	// once by the caller and passed in.
	ImpliedGuardedBackings []string
	// ImpliedGuardedNamespaces is the retrieval-target twin of
	// ImpliedGuardedBackings: turbopuffer wire names some `namespace()`
	// declaration in the repository guards (repoGuardedNamespaces). The retrieval
	// render leg treats them as implicitly required-guarded, so an unguarded twin
	// namespace over a guarded-elsewhere wire name fails closed (RQL3002) instead
	// of rendering a body with no guard filter. Populated only by the
	// execute/serve path; empty on the pure `render`/`test` paths, whose behavior
	// is unchanged unless the manifest's `[guards].require` already covered it.
	ImpliedGuardedNamespaces []string
	// ImpliedPinnedNamespaces are wire names some `namespace()` declaration pins
	// (repoPinnedNamespaces). The retrieval render leg refuses a namespace whose
	// name spells its way into a pinned namespace's per-tenant address space
	// (`P.<…>`), which would read that tenant's address-isolated corpus directly.
	// Populated only by the execute/serve path; empty elsewhere.
	ImpliedPinnedNamespaces []string
}

Request describes one render.

type RequireFilterDecl 

type RequireFilterDecl struct {
	Backing string   `json:"backing"`
	Columns []string `json:"columns"`
}

RequireFilterDecl is one relation's declared cost requirement.

func RequireFilterDecls 

func RequireFilterDecls(frag *Fragment) []RequireFilterDecl

RequireFilterDecls lists the declared require_filter columns per relation in a fragment, for `requel explain` and `requel inspect`. Reporting the *declaration* is all a context-free surface can honestly do: whether a given request satisfies it is a property of that request's filters, and explain's dry run has none.

type Result 

type Result struct {
	Render   *RenderResult
	Warnings Diagnostics
	Label    string
	Decls    []*ParamDecl
	Examples []*Example
}

Result is a rendered query plus its warnings.

type ResultColumnValue 

type ResultColumnValue struct{ Column function.ResultColumn }

func (*ResultColumnValue) Freeze 

func (v *ResultColumnValue) Freeze()

func (*ResultColumnValue) Hash 

func (v *ResultColumnValue) Hash() (uint32, error)

func (*ResultColumnValue) String 

func (v *ResultColumnValue) String() string

func (*ResultColumnValue) Truth 

func (v *ResultColumnValue) Truth() starlark.Bool

func (*ResultColumnValue) Type 

func (v *ResultColumnValue) Type() string

type Retrieval 

type Retrieval struct {
	NS      *Namespace
	RankBy  []any  // lowered rank_by array (JSON-encodable)
	RankDoc string // human form for explain ("bm25(content)", …)
	// VectorDims counts a rank-by-vector's dimensions for explain/inspect —
	// the vector itself is caller data and never echoed into documents.
	VectorDims   int
	Conds        []tpufCond // compiled caller filters
	GuardConds   []tpufCond // filled by renderRetrieval (guard evaluation)
	GuardExempt  bool       // guard returned Unrestricted explicitly
	Limit        int
	IncludeAttrs []string
	// Aggregates makes this an aggregate entrypoint: the body carries
	// aggregate_by and the connector decodes the aggregation table as the
	// result. Rows-and-aggregates-together is deliberately not a mode — an
	// entrypoint answers one shape of question, and the split keeps each
	// reviewable on its own (blueprint 16 §4).
	Aggregates  []AggSpec
	Filterables []FilterableInfo // published registry, for inspect/explain

	// Homology makes this a homology entrypoint: rank_by named a target-native
	// alignment method (BLASTP, MMSEQS_SEARCH, …) and the body is a homology query
	// rather than a turbopuffer one. See homology.go.
	Homology *HomologySpec

	// Target selects the vector-store wire grammar the body is lowered to.
	// Empty means the default turbopuffer v2 body; "chroma" lowers a Chroma
	// query body instead (see buildChromaBody). Both are vector targets that
	// share the caller-facing `{key,op,value}` filter contract, so an agent
	// authored against one reads the other; what differs is only the JSON the
	// engine emits and which connector may receive it. Homology is orthogonal
	// (it is chosen by the rank method, not the target) and is never combined
	// with a non-default target.
	Target string

	// The oracle's inputs (blueprint 16 §9): the raw pre-lowering forms of
	// what the engine consumed, captured before any mapping so
	// internal/retrievalcheck can derive the body a second time. MaxLimit is
	// the authored bound the oracle holds the body's limit under.
	RawFilters  []retrievalcheck.Filter
	RawRegistry []retrievalcheck.RegistryEntry
	RawGuard    []retrievalcheck.Cond
	MaxLimit    int
}

Retrieval is a governed retrieval request — what query(p) returns for a retrieval entrypoint, playing the role *Fragment plays for SQL. It is deliberately opaque to Starlark (no attrs): the stdlib assembles it in one retrieve() call, and nothing downstream of that call is authorable.

func (*Retrieval) Freeze 

func (r *Retrieval) Freeze()

func (*Retrieval) Hash 

func (r *Retrieval) Hash() (uint32, error)

func (*Retrieval) String 

func (r *Retrieval) String() string

func (*Retrieval) Truth 

func (r *Retrieval) Truth() starlark.Bool

func (*Retrieval) Type 

func (r *Retrieval) Type() string

type RetrievalOut 

type RetrievalOut struct {
	Namespace string `json:"namespace"`
	Body      string `json:"body"`
	Limit     int    `json:"limit"`
	// Method and Engine are set on a homology entrypoint. They carry the two
	// facts execute cannot recover from the body alone: which gate the bytes
	// must pass (the two wire grammars are different closed field sets), and
	// which driver family may receive them — pointing a BLASTP entrypoint at
	// an mmseqs connector would answer with a different engine's e-values
	// under the authored method's name.
	Method         string         `json:"method,omitempty"`
	Engine         string         `json:"engine,omitempty"`
	QueryKind      string         `json:"query_kind,omitempty"`
	DatabaseKind   string         `json:"database_kind,omitempty"`
	ResultUnit     string         `json:"result_unit,omitempty"`
	OutputColumns  []string       `json:"output_columns,omitempty"`
	QueryField     string         `json:"query_field,omitempty"`
	QuerySelectors map[string]any `json:"query_selectors,omitempty"`
	// Target names the vector-store wire grammar this body was lowered to, so
	// execute can select the matching gate without re-parsing the body. Empty
	// is the default turbopuffer grammar; "chroma" a Chroma query body. Like
	// Method/Engine, it carries a fact execute cannot recover from the bytes
	// alone (a Chroma body and a turbopuffer body are different closed field
	// sets, so the gate must be chosen by the render's declaration).
	Target string `json:"target,omitempty"`
}

RetrievalOut is the executable form of a rendered retrieval request, carried on RenderResult the way SQL text and binds are: Body is the exact compact JSON the connector POSTs (the gated bytes are the sent bytes), and Namespace names the URL path segment.

type ScalarType 

type ScalarType string

ScalarType is the canonical wire and object-property vocabulary. It is deliberately smaller than any one database's type system. 

const (
	ScalarString    ScalarType = "string"
	ScalarInteger   ScalarType = "integer"
	ScalarDecimal   ScalarType = "decimal"
	ScalarNumber    ScalarType = "number"
	ScalarBoolean   ScalarType = "boolean"
	ScalarDate      ScalarType = "date"
	ScalarTimestamp ScalarType = "timestamp"
	ScalarJSON      ScalarType = "json"
)

type SelectableInfo 

type SelectableInfo struct {
	Kind string // "metric" | "dimension"
	Key  string
	Doc  string
	// Deprecated carries the note from a registry entry's `deprecated` field, so
	// the document says "still selectable, but announced" in the same place it
	// says what the key means. `x-rql-deprecations` reports the ones a *render*
	// actually touched; this reports the ones the surface still offers.
	Deprecated string
	// ExactAt is the grain at which a measure counts each unit of content once,
	// where the ontology declared one (`exact_at`). It is published for the reason
	// a closed label set and a column format are: enforcement without publication
	// is half a feature. The engine warns at render time when a caller pools
	// coarser (RQL3045), and a caller who cannot read the declaration learns about
	// it only by receiving that warning — so an agent generating against this
	// document would keep generating the coarse selection.
	//
	// It stays out of `api.txt` deliberately, on the same rule that keeps a
	// selectable's `doc` out: the surface manifest records which calls are
	// accepted and what shape comes back, and this changes neither. It tells a
	// reader how to interpret a total they were always able to ask for.
	ExactAt []string
	// NotAdditive is the reason a measure's per-group values must not be summed,
	// where the ontology declared one (`not_additive`).
	//
	// It is the third way an aggregate misleads, and the two existing fields
	// reach neither half of it. `fanout_safe` answers whether a JOIN duplicates
	// the rows; `exact_at` answers whether a COARSE grouping pools values that
	// overlap. This one answers whether the ENTITIES being counted can belong to
	// more than one group — a `COUNT(DISTINCT isolate_name)` grouped by host is
	// exact in every row it returns and still sums to more than the ungrouped
	// total, because an isolate may carry deposits under two hosts.
	//
	// Nothing checks it, and that is deliberate rather than unfinished: whether
	// entities span groups is a property of the data, decidable only by asking
	// the warehouse, and the moment a reader adds a column up is outside every
	// surface this engine owns. What it can do is carry the author's reason to
	// the two places a reader meets the number — `requel inspect`, which an agent
	// generates against, and `requel explain`, which a reviewer reads — so the
	// warning arrives with the total rather than living in a doc string nobody
	// treats as one.
	//
	// It stays out of `api.txt` for ExactAt's reason: the surface manifest records
	// which calls are accepted and what shape comes back, and this changes
	// neither.
	NotAdditive string
}

SelectableInfo describes one metric or dimension key a view offers, for inspect and for the surface manifest.

`Doc` is the whole reason it exists. A caller composing a request chooses among these keys, and until they carried their authored documentation the only way to learn what `SequenceRecord.criterion_disagreement_count` means was to open the ontology — which is precisely what the typed surface exists to make unnecessary.

type SemanticTypeValue 

type SemanticTypeValue struct {
	// contains filtered or unexported fields
}

SemanticTypeValue is the immutable analytical namespace returned by semantic.make. It implements the query protocol without being a nominal object, so catalog and operational object compilation cannot mistake it for an instance-bearing object type.

func (*SemanticTypeValue) Attr 

func (v *SemanticTypeValue) Attr(name string) (starlark.Value, error)

func (*SemanticTypeValue) AttrNames 

func (v *SemanticTypeValue) AttrNames() []string

func (*SemanticTypeValue) Freeze 

func (v *SemanticTypeValue) Freeze()

func (*SemanticTypeValue) Hash 

func (v *SemanticTypeValue) Hash() (uint32, error)

func (*SemanticTypeValue) String 

func (v *SemanticTypeValue) String() string

func (*SemanticTypeValue) Truth 

func (v *SemanticTypeValue) Truth() starlark.Bool

func (*SemanticTypeValue) Type 

func (v *SemanticTypeValue) Type() string

type Severity 

type Severity string

Severity classifies a diagnostic. 

const (
	SevError   Severity = "error"
	SevWarning Severity = "warning"
	SevInfo    Severity = "info"
)

type SidecarWrite 

type SidecarWrite struct {
	Example string // the example whose golden this is
	Abs     string // absolute path to write
	Rel     string // repo-relative path, for the operator-facing line
	Text    string // canonical golden text, without its trailing newline
}

type SkippedExample 

type SkippedExample struct {
	File     string   `json:"file"`
	Example  string   `json:"example"`
	Dialect  string   `json:"dialect"`
	Declared []string `json:"declared"`
}

SkippedExample is one example the run did not execute, and why.

type SkippedFile 

type SkippedFile struct {
	File   string `json:"file"`
	Reason string `json:"reason"`
}

SkippedFile is a file a test run did not examine, and why.

It exists because the disclosure had nowhere else to go. A file this pass cannot read contributes no examples, and the run then prints a whole-repo total as though it had been examined and found clean — the class this repository has now met four times. On the terminal the fix was a note on the operator's stderr, which is right for a person and invisible to the MCP `requel_test` caller, whose entire view of the run is this document. So the same fact rides the report.

Reason is the prose the note carries, verbatim rather than a code: nothing below the operating system's own error is available to classify an I/O failure by, and inventing a taxonomy for one would promise a discrimination this has no way to make.

type Soundness 

type Soundness = soundness

Soundness is the compiler's proof result for a predicate under truncation.

func PredicateSoundness 

func PredicateSoundness(predicate function.Predicate, direction func(string) MonoDir) (Soundness, string)

PredicateSoundness proves whether a predicate remains valid as rows are admitted.

type SourceAccess added in v0.3.0 

type SourceAccess struct {
	Relation string        `json:"relation"`
	Filter   *ObjectFilter `json:"filter,omitempty"`
	Sort     []ObjectSort  `json:"sort,omitempty"`
	Limit    int           `json:"limit,omitempty"`
}

SourceAccess is a conservative connector refinement proven while compiling an object query. It is emitted only for a direct backing relation whose filtered and ordered properties are unmodified physical columns. Empty access means the host must read the full declared dependency.

type Span 

type Span struct {
	Start Pos `json:"start"`
	End   Pos `json:"end"`
}

Span is a source range.

type State 

type State struct {
	Dialect string
	Ctx     *Context
	Pure    bool

	// MaxRows is the repository-wide row-cap ceiling from [limits] in requel.toml;
	// 0 means the repo declared none. Enforced in limit_clause (RQL2010).
	MaxRows int
	// contains filtered or unexported fields
}

State is per-run engine state carried on the Starlark thread.

func (*State) AddWarning 

func (s *State) AddWarning(d *Diagnostic)

AddWarning records a non-fatal diagnostic.

func (*State) Bridges 

func (s *State) Bridges() []*Bridge

Bridges returns every bridge declared during this run, in declaration order.

func (*State) CtxTouched 

func (s *State) CtxTouched() []string

CtxTouched returns the `ctx` fields read during this run, sorted. Empty means the run never looked at the context — so everything it produced is a function of the params alone.

func (*State) Deprecations 

func (s *State) Deprecations() []Deprecation

Deprecations returns structured deprecations hit during evaluation.

func (*State) Examples 

func (s *State) Examples() []*Example

Examples returns a snapshot of examples declared during this evaluation.

func (*State) Neighbourhoods 

func (s *State) Neighbourhoods() []*Neighbourhood

Neighbourhoods are the declared similarity edge sets, for the checks.

A separate accessor from Bridges(), and a separate list behind it, because a similarity edge set that reached the bridge list is one every rule in bridge_analysis.go would treat as a licence to join silently.

func (*State) Relations 

func (s *State) Relations() []*Relation

Relations returns every relation created during this run.

func (*State) Warnings 

func (s *State) Warnings() Diagnostics

Warnings returns accumulated warnings.

type StudioFunction 

type StudioFunction struct {
	Plan     *function.Plan          `json:"plan"`
	Examples []StudioFunctionExample `json:"examples"`
}

StudioFunction is a compiled plan together with the authored examples that can supply defaults or hermetic terminal fixtures.

type StudioFunctionExample 

type StudioFunctionExample struct {
	Name        string         `json:"name"`
	Doc         string         `json:"doc,omitempty"`
	Params      map[string]any `json:"params"`
	HasFixtures bool           `json:"has_fixtures"`
}

StudioFunctionExample is the public, non-secret part of an authored example. It exists for the ontology studio: the CLI keeps the full Example type because it also owns golden text and fixtures, while a UI only needs enough data to select a safe, hermetic run.

type TestFailure 

type TestFailure struct {
	File    string `json:"file"`
	Example string `json:"example"`
	Kind    string `json:"kind"`
	Want    string `json:"want,omitempty"`
	Got     string `json:"got,omitempty"`
	// Message and Detail carry failures that are not a want/got pair — the
	// stale persona matrix ([09 §1]), whose report is a sentence and a list of
	// what moved. Same two fields `requel`'s testrunner.Failure carries, so the
	// two CLIs' --json test reports stay one shape.
	Message string `json:"message,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

TestFailure is one failing example.

type TestReport 

type TestReport struct {
	Total    int           `json:"total"`
	Passed   int           `json:"passed"`
	Failed   int           `json:"failed"`
	Failures []TestFailure `json:"failures"`
	Skipped  []SkippedFile `json:"skipped,omitempty"`
	// SkippedExamples records the examples whose `dialects =` excluded this
	// repo's dialect. Same discipline as Skipped and for the same reason: it is
	// not folded into Total or Failed, and it is not silent — a run that asserted
	// less than the file declares has to say so, or "48 passed" reads as
	// coverage it does not have.
	SkippedExamples []SkippedExample `json:"skipped_examples,omitempty"`
}

TestReport summarizes an example run.

Skipped is deliberately *not* folded into Total or Failed. A skip is a statement about coverage, not about correctness: counting it as a failure would make an unreadable file indistinguishable from a broken example, and diagnosing it stays `requel lint`'s job. It is `omitempty`, so a run that examined everything it walked emits the document it always emitted, and a consumer that has never heard of the field is unaffected — the addition is additive in both directions.

type UnboundEdge 

type UnboundEdge struct {
	From        string `json:"from"`
	Edge        string `json:"edge"`
	Cardinality string `json:"cardinality"`
	Optional    bool   `json:"optional"`
	File        string `json:"file"`
	Line        int    `json:"line"`
}

UnboundEdge is a declared half-edge with no target from either source. It reaches nothing today, and would create pairs the moment someone wires it up.

type UnresolvedBinding 

type UnresolvedBinding struct {
	Edge   string `json:"edge"`
	Base   string `json:"base,omitempty"`
	Object string `json:"object,omitempty"`
	Reason string `json:"reason"`
	File   string `json:"file"`
	Line   int    `json:"line"`
}

UnresolvedBinding is a target this scan could not trace to an object. Reported rather than dropped: a silently-skipped binding would make the graph read as complete when it is not.

type Val 

type Val struct {
	Kind    BindKind
	S       string // canonical text (string/date/timestamp RFC form)
	Display string // original caller form
}

Val wraps a caller-supplied string-ish scalar. Its existence *is* the provenance mechanism: a plain starlark.String can only have come from authored source, so it lowers inline, while a *Val always binds. Val is deliberately inert — no string methods, no concatenation — so caller data can never become a SQL template or an identifier (blueprint 13 §2 T2/T7).

func (*Val) Binary 

func (v *Val) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error)

Binary refuses `+` with an explanation instead of leaving it to Starlark's default. A caller value is deliberately not concatenable — that inertness is the trust boundary, since a caller string glued to an authored one would launder provenance and reach SQL as structure — but `"prefix-" + p.name` is the first thing an author reaches for, and Starlark's own message for it, "unknown binary op: string + value", names no cause and no fix. Every other refusal on this boundary (text(), source(alias=…)) says why and what to do instead; this one said nothing, which is how a real rule reads as a bug.

Only `+` is answered. Everything else returns (nil, nil), the "not handled" contract, so no operator the default already rejects becomes reachable here.

func (*Val) CompareSameType 

func (v *Val) CompareSameType(op syntax.Token, y starlark.Value, depth int) (bool, error)

CompareSameType compares two caller values by kind and canonical text. Without it a *Val is not Comparable at all, so Starlark falls back to *identity*: two values report unequal however equal their contents, and since Hash() is the hash of that same text, equal-hashing keys that never compare equal break the dict contract too.

Cross-type comparison against a plain authored string remains unsupported, and not by choice: Starlark settles a differing-Type() pair before either value is consulted (CompareDepth gates CompareSameType behind sameType), so no method here can answer it. That is the same structural limit that makes membership the container's job — see *IdentSet.

func (*Val) Freeze 

func (v *Val) Freeze()

func (*Val) Hash 

func (v *Val) Hash() (uint32, error)

func (*Val) String 

func (v *Val) String() string

func (*Val) Truth 

func (v *Val) Truth() starlark.Bool

func (*Val) Type 

func (v *Val) Type() string

type ValueList 

type ValueList struct {
	Items []starlark.Value
}

ValueList is the runtime container for caller-supplied List(...) parameters. Its elements keep their inert scalar representations, while the container owns membership so an authored literal can be compared with the caller value it denotes. A plain starlark.List cannot do both: it checks same-type equality before consulting an inert *Val and therefore silently reports every string, date, and timestamp member absent.

func NewValueList 

func NewValueList(items []starlark.Value) *ValueList

func (*ValueList) CompareSameType 

func (l *ValueList) CompareSameType(op syntax.Token, y starlark.Value, depth int) (bool, error)

func (*ValueList) Freeze 

func (l *ValueList) Freeze()

func (*ValueList) Has 

func (l *ValueList) Has(probe starlark.Value) (bool, error)

func (*ValueList) Hash 

func (l *ValueList) Hash() (uint32, error)

func (*ValueList) Index 

func (l *ValueList) Index(i int) starlark.Value

func (*ValueList) Iterate 

func (l *ValueList) Iterate() starlark.Iterator

func (*ValueList) Len 

func (l *ValueList) Len() int

func (*ValueList) String 

func (l *ValueList) String() string

func (*ValueList) Truth 

func (l *ValueList) Truth() starlark.Bool

func (*ValueList) Type 

func (l *ValueList) Type() string

type ViaHop 

type ViaHop struct {
	Edge  string `json:"edge"`
	Alias string `json:"alias"`
}

ViaHop is one authored hop of a composed edge.

type WarningOut 

type WarningOut struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

WarningOut is a non-fatal diagnostic surfaced in render output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.