gizmodel/source
One typed data-source contract. An adapter reports its actual abilities and returns owned column pages. It never manufactures global snapshot/CDC semantics.
import * as Source from "gizmodel/source";Types
Capabilities
type Capabilities = { schema: bool; projection: bool; filter: bool; group: bool; join: bool; snapshot: bool; changeLog: bool; write: bool; transaction: bool; cancel: bool; compute: bool; order: bool; limit: bool; window: bool; set: bool; }What a source can do itself: the parts of a query that it runs, and whether it gives snapshots, a change log, writes and transactions.
schema:boolprojection:boolfilter:boolgroup:booljoin:boolsnapshot:boolchangeLog:boolwrite:booltransaction:boolcancel:boolcompute:boolorder:boollimit:boolwindow:boolset:bool
Semantics
type Semantics = { dialect: string; collation: string; timezone: string; nulls: string; }How a source compares and shows values: its SQL dialect, collation, time zone and null order.
dialect:stringcollation:stringtimezone:stringnulls:string
Version
type Version = { source: string; revision: string; snapshot: bool; }Revisions remain per source; "snapshot=false" is never upgraded by a federation.
source:stringrevision:stringsnapshot:bool
Request
type Request = { tree: Select; parameters: Vec<Typed.Slot>; values: Vec<Value>; outputs: Vec<Typed.Slot>; rows: i64; bytes: i64; sql: string; }A query for a source: its tree, parameters and their values, outputs, and the most rows and bytes to read.
tree:M151.Selectparameters:Vec<M142.Slot>values:Vec<M143.Value>outputs:Vec<M142.Slot>rows:i64bytes:i64sql:string
Cursor
type Cursor = { slots: Vec<Typed.Slot>; versions: Vec<Version>; poll: (rows: i64, bytes: i64) => FinitePoll throws DbError; dispose: () => bool throws DbError; }The open result of a query: its columns, the versions of the sources that it reads, and how to poll and close it.
slots:Vec<M142.Slot>versions:Vec<M140.Version>poll:(rows: i64, bytes: i64) => M152.FinitePoll throws M129.DbErrordispose:() => bool throws M129.DbError
Source
type Source = { identity: string; semantics: Semantics; capabilities: Capabilities; prepare: (request: Request) => Cursor throws DbError; change: (commands: Vec<Statement>) => i64 throws DbError; read: Option<NativeRead>; version: () => string throws DbError; }A data source that a query reads: its identity, semantics and capabilities, and how to prepare queries and run changes.
identity:stringsemantics:M140.Semanticscapabilities:M140.Capabilitiesprepare:(request: M140.Request) => M140.Cursor throws M129.DbErrorchange:(commands: Vec<M151.Statement>) => i64 throws M129.DbErrorread:_gizlang_sdk_core.Option<(sql: string, rows: i64, bytes: i64) => M140.Cursor throws M129.DbError>version:() => string throws M129.DbError— The version of the data the source reads now, "" when it has none: two reads in one version see the same data (model/policy.giz Kept).
Requirement
type Requirement = { snapshot: bool; changeLog: bool; write: bool; transaction: bool; }What a caller needs of a source.
snapshot:boolchangeLog:boolwrite:booltransaction:bool
Descriptor
type Descriptor = { version: string; identity: string; revision: bytes; semantics: Semantics; capabilities: Capabilities; maxRows: i64; maxBytes: i64; }This is the adapter contract revision, not a fabricated data revision. Actual data cuts remain Cursor.versions and are scoped to each source.
version:stringidentity:stringrevision:bytessemantics:M140.Semanticscapabilities:M140.CapabilitiesmaxRows:i64maxBytes:i64
TextRows
type TextRows = { columns: Vec<string>; rows: Vec<Vec<Option<string>>>; }A text client's answer: the column names the database gives and the text cells (none for NULL).
columns:Vec<string>rows:Vec<Vec<_gizlang_sdk_core.Option<string>>>
TextClient
type TextClient = { query: (sql: string, parameters: Vec<Option<string>>, kept: bool) => TextRows throws DbError; atomic: (statements: Vec<string>) => i64 throws DbError; numbered: bool; version: () => string throws DbError; reader?: (sql: string, parameters: Vec<Option<string>>) => Sql.Reader throws DbError; }A database client that runs SQL text with text parameters and gives text cells
(gizlang/sql/sqlite, gizlang/sql/postgres). atomic runs statements in one transaction. A query that is KEPT has an
answer that depends only on the data it reads (ast.giz keepable): the client may keep it until the data changes.
With reader the client steps a row at a time (SQLite): a page then reads rows as they come, and nothing holds a
whole answer.
query:(sql: string, parameters: Vec<_gizlang_sdk_core.Option<string>>, kept: bool) => M140.TextRows throws M129.DbErroratomic:(statements: Vec<string>) => i64 throws M129.DbErrornumbered:boolversion:() => string throws M129.DbError— The version of the data (Source.version).reader:_gizlang_sdk_core.Option<(sql: string, parameters: Vec<_gizlang_sdk_core.Option<string>>) => gizlang_sql.Reader throws M129.DbError>
Functions
pinSchema
function pinSchema(expected: bytes, slots: Vec<Typed.Slot>): bool throws DbErrorDatabase-first callers pin observed result schemas rather than guessing a row type.
Effects: fail, alloc.
federated
function federated(sources: Vec<Source>, atomic: bool, live: bool): Vec<Version> throws DbErrorA federation requires identical semantics for a moved calculation and keeps source frontiers distinct. Atomic distributed writes are never implied.
Effects: fail, alloc.
document
function document(identity: string, slots: Vec<Typed.Slot>, text: string): Source throws DbErrorArrays of records are the shared JSON/API/SaaS/spreadsheet export boundary. Nested fields are explicit text/extension codecs; no DOM f64 round-trip occurs.
Effects: fail, alloc.
semantics
function semantics(dialect: string): Semantics throws DbErrorThe semantics of a SQL engine that an external source runs: its dialect, the collation of its text, its time zone and how it types NULL. A federation requires equal semantics.
Effects: fail, alloc.
text
function text(client: TextClient, identity: string, semantics: Semantics): SourceA source on a text client. A query's declared output slots type the text cells; a query that declares none (discover) gets the columns the database names, each cell kept as nullable text. It has no snapshot or change log, so a watch is refused as a missing capability.
Effects: fail, alloc.
mutations
function mutations(commands: Vec<Statement>, dialect: string): Vec<string> throws DbErrorThe SQL of an external source's batch of COMMANDS in DIALECT, each with its literals written in: at most 1024.
Effects: fail, alloc.
projection
function projection(request: Request, identity: string): boolWhether REQUEST only projects table IDENTITY: no filter, grouping, order, bound, join or parameter, which a source that pushes nothing down would answer wrong.
Effects: fail.
sqlFault
function sqlFault(e: Sql.SqlError): DbErrorA database's failure as a DbError: its SQLSTATE (HY000 when it has none) and its native code.
Effects: fail, alloc.
database
function database(store: Sql.Database, identity: string): SourceA source on a database of gizlang/sql (SQLite, PostgreSQL or a GizDB server, MySQL, an ODBC data source): its SQL text runs as written, and the declared output slots type the text cells. The one adapter of every SQL database. A database the SQLite driver serves steps its rows, so a page reads them as they come; the others answer a whole read here, and their reader is refused as a missing cursor.
Effects: fail, alloc.
Methods
Source.describe
function Source.describe(self: Source): DescriptorThe descriptor of the source: its contract version, identity, semantics, capabilities and limits.
Effects: fail, alloc.
Source.admit
function Source.admit(self: Source, request: Request, need: Requirement, revision: bytes): bool throws DbErrorAdmit an exact typed request under a pinned adapter contract. The provider's prepare/binder remains the final authority for its actual operator support.
Effects: fail, alloc.
Source.request
function Source.request(self: Source, request: Request, need: Requirement): bool throws DbErrorSource.admit of a request to this source itself, whose contract is the one in hand: no revision to compare. Each A typed read hashed the descriptor twice to compare it with itself (a sixth of a one-row read, 2026-10-31).
Effects: fail, alloc.
Source.require
function Source.require(self: Source, need: Requirement): bool throws DbErrorFails with an error that names the first capability of NEED that the source does not have.
Effects: fail, alloc.
Source.transaction
function Source.transaction<T>(self: Source, commands: Vec<Statement>, result: T): T throws DbErrorRuns COMMANDS as one transaction of the source; RESULT when they all succeed.
Source.discover
function Source.discover(self: Source, tree: Select, parameters: Vec<Typed.Slot>, values: Vec<Value>, rows: i64, bytes: i64): Cursor throws DbErrorA cursor of TREE with PARAMETERS and VALUES, after the source admits each part of it, reading at most ROWS rows and BYTES bytes.
Effects: fail, read, write, console, io, alloc.