Crate saya_types 

Shared public contracts for SAYA CLI.

Structs

ClaimId

Column

Database

DatabaseObjectRef

ProfileIdentity

Opaque, validated profile identity: the literal prefix p- followed by 64 lowercase hex digits.

QueryRequest

A bounded query passed to a database connector.

QueryResult

Connector-neutral tabular result. Values are JSON-compatible for CLI output.

ReferencedColumn

A referenced column snapshotted at claim time: its name plus the type and nullability the connector reported when the claim was made.

Schema

SchemaFingerprint

A versioned schema digest. The version travels with the digest rather than being read from the current constant: a fingerprint loaded from storage was computed under whatever format was current when it was written, and drift detection is only sound if a v1 digest keeps reporting v1.

SchemaTree

A complete schema snapshot returned by a connector.

Scoped

A value paired with the scope its required_scope says it must be stored under. Construction enforces the rule; the fields are public so the store can read them, but a wrong pairing cannot be constructed.

SlotParseError

Error surfaced only through Deserialize / TryFrom<String> when a string is not a valid slot. Payload-free and message-only: it never echoes the rejected string. Not part of the append/replace enforcement surface — that uses [SlotError].

SlotValues

A KnowledgeSlot paired with the values currently held against it. The slot’s declared Cardinality is the rule this holder enforces: append works only on multi-valued slots and refuses past the bound; replace works only on single-valued slots and always leaves exactly one value. The wrong operation for the slot’s cardinality is a typed error, so a single-valued slot cannot be grown to two values by any method on this type.

Table

Enums

BindingValidity

Verdict of validating a knowledge item’s schema binding against live table metadata.

Cardinality

ClaimOrigin

ClaimPayload

ClaimStatus

ColumnRequirement

Semantic type requirement placed on a depended-upon column.

ColumnRole

ConnectionError

Errors exposed by database connectors without leaking driver details.

ContractError

DatabaseObjectKind

DatabaseProfile

Typed database connection profile loaded from connections.toml. Exhaustive matching is intentional so the compiler forces every backend to handle every profile.

DateGrain

The reporting grain for date-shaped results.

KnowledgeSlot

The position a piece of knowledge occupies on a database object.

KnowledgeState

The three persisted states a knowledge slot’s value can be in. Distinct from ClaimStatus, which is still in use and whose Contradicted variant is load-bearing in saya-store’s transition rules; this adds the new vocabulary beside it.

MySqlSslMode

MySQL TLS policy. Omitted legacy profiles are upgraded by the connector to VerifyIdentity; this type deliberately has no downgrade-capable default.

OutputStyle

How a result is rendered in the terminal.

PostgresSslMode

PostgreSQL TLS verification mode. None preserves PostgreSQL’s prefer default for existing profiles that omit sslmode.

PreferenceScope

What a preference applies to. Presentation choices are global; database-shaped choices are scoped to one connection profile.

PreferenceValue

A bounded user preference. Closed enums and shape-validated strings only; no free-text variant exists by design.

SchemaBinding

Structural dependencies a piece of knowledge requires from the database schema.

ScopeRequirement

Which scope a value must be stored under. Carried by the typed error so a caller can name the scope the value requires without re-deriving it.

SecretRef

A reference to a secret. It is safe to serialize because it holds no value.

SlotCardinality

How many values a KnowledgeSlot admits, reported by the slot itself.

SlotError

A typed error from the SlotValues append/replace operations. Payload-free by the security standard: it names what went wrong, never the value or slot the caller tried to act on.

SnowflakeAuth

Supported Snowflake authentication flows; browser SSO remains interactive-only.

SqlDialect

SQL dialect used for parsing, rendering, and connector behavior.

Constants

CLAIM_PAYLOAD_VERSION

Serialization version for ClaimPayload. Bump when a variant’s stored shape changes.

FINGERPRINT_VERSION

MAX_MESSAGE_BYTES

The whole-message byte budget the agent enforces: system + user + history must fit under this before the request is sent. The prompt-recall path reserves the system prompt and the user’s question out of this first, then gives context what remains.

MAX_MULTI_SLOT_VALUES

Bound on every multi-valued slot. Multi-valued slots render into the recall context block, so an unbounded list is a context-budget problem. Four keeps the worst case modest: four table.description values at MAX_TEXT_CHARS (1024) each is ~4 KB, a small slice of the 32 KB MAX_MESSAGE_BYTES whole-message budget; aliases are short names and negligible at four. Four is large enough that a table is never forced to drop a legitimate second alias or clarification, and small enough that a runaway list cannot crowd out the question the context is meant to help.

MAX_NAME_CHARS

MAX_PROFILE_NAME_CHARS

The maximum length of a profile name. Names come from connections.toml, not the identity; a sensible bound keeps the column cheap.

MAX_REFERENCED_COLUMNS

MAX_TEXT_CHARS

MAX_TIMEZONE_CHARS

The maximum length of a timezone string. IANA names are short; 64 is far above the longest real one and keeps the column cheap.

Functions

is_numeric_type

Classifies whether a connector’s raw data type string represents a numeric value (integers, floating point, decimals, serials, and numbers).

is_temporal_type

Classifies whether a connector’s raw data type string represents a temporal value (date, time, timestamp, or datetime).

validate_table

Validates a schema binding against an optional live table reference.