# gizdb:source One typed data-source contract. An adapter reports its actual abilities and returns owned column pages. It never manufactures global snapshot/CDC semantics. ```gizlang import * as Source from "gizdb:source"; ``` ## Types ### `Capabilities` ```gizlang 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`: `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` ### `Semantics` ```gizlang 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`: `string` - `collation`: `string` - `timezone`: `string` - `nulls`: `string` ### `Version` ```gizlang type Version = { source: string; revision: string; snapshot: bool; } ``` Revisions remain per source; "snapshot=false" is never upgraded by a federation. - `source`: `string` - `revision`: `string` - `snapshot`: `bool` ### `Request` ```gizlang type Request = { tree: Select; parameters: Vec; values: Vec; outputs: Vec; 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`: `_gizlang_lib_db__sql__ast.Select` - `parameters`: `Vec` - `values`: `Vec` - `outputs`: `Vec` - `rows`: `i64` - `bytes`: `i64` - `sql`: `string` ### `Cursor` ```gizlang type Cursor = { slots: Vec; versions: Vec; poll: (rows: i64, bytes: i64) => Result; close: () => Result; } ``` 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` - `versions`: `Vec` - `poll`: `(rows: i64, bytes: i64) => _gizlang_sdk_core.Result<_gizlang_lib_db__sql__exec__vm.FinitePoll, M56.DbError>` - `close`: `() => _gizlang_sdk_core.Result` ### `Source` ```gizlang type Source = { identity: string; semantics: Semantics; capabilities: Capabilities; prepare: (request: Request) => Result; change: (commands: Vec) => Result; read: Option; } ``` A data source that a query reads: its identity, semantics and capabilities, and how to prepare queries and run changes. - `identity`: `string` - `semantics`: `M61.Semantics` - `capabilities`: `M61.Capabilities` - `prepare`: `(request: M61.Request) => _gizlang_sdk_core.Result` - `change`: `(commands: Vec<_gizlang_lib_db__sql__ast.Statement>) => _gizlang_sdk_core.Result` - `read`: `_gizlang_sdk_core.Option<(sql: string, rows: i64, bytes: i64) => _gizlang_sdk_core.Result>` ### `Requirement` ```gizlang type Requirement = { snapshot: bool; changeLog: bool; write: bool; transaction: bool; } ``` What a caller needs of a source. - `snapshot`: `bool` - `changeLog`: `bool` - `write`: `bool` - `transaction`: `bool` ### `Descriptor` ```gizlang 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`: `string` - `identity`: `string` - `revision`: `bytes` - `semantics`: `M61.Semantics` - `capabilities`: `M61.Capabilities` - `maxRows`: `i64` - `maxBytes`: `i64` ### `TextRows` ```gizlang type TextRows = { columns: Vec; rows: Vec>>; } ``` A text client's answer: the column names the database gives and the text cells (none for NULL). - `columns`: `Vec` - `rows`: `Vec>>` ### `TextClient` ```gizlang type TextClient = { query: (sql: string, parameters: Vec>) => Result; atomic: (statements: Vec) => Result; numbered: bool; } ``` A database client that runs SQL text with text parameters and gives text cells (gizlang:sqlite, gizlang:postgres). `atomic` runs statements in one transaction. - `query`: `(sql: string, parameters: Vec<_gizlang_sdk_core.Option>) => _gizlang_sdk_core.Result` - `atomic`: `(statements: Vec) => _gizlang_sdk_core.Result` - `numbered`: `bool` ## Functions ### `pinSchema` ```gizlang function pinSchema(expected: bytes, slots: Vec): Result ``` Database-first callers pin observed result schemas rather than guessing a row type. Effects: fail. ### `odbc` ```gizlang function odbc(connection: Odbc.Connection, identity: string, semantics: Semantics): Result ``` One driver contract covers PostgreSQL/MySQL/SQL Server/Oracle/SQLite and other ODBC sources. A particular driver is usable only after its type/semantic checks. Effects: fail, read, io. ### `federated` ```gizlang function federated(sources: Vec, atomic: bool, live: bool): Result, DbError> ``` A federation requires identical semantics for a moved calculation and keeps source frontiers distinct. Atomic distributed writes are never implied. Effects: fail. ### `document` ```gizlang function document(identity: string, slots: Vec, text: string): Result ``` Arrays 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. ### `files` ```gizlang function files(directory: Dir, identity: string, pattern: string, format: i64, text: Files.TextOptions, planning: Files.FilePlanningLimits, limits: Files.FileCursorLimits, context: ResourceContext): Source ``` CSV, NDJSON and Parquet all use the existing bounded physical file reader. The supplied context is the caller's original resource issuer. Mutable files are not advertised as transaction snapshots. ### `httpJson` ```gizlang function httpJson(sys: System, host: string, port: i64, request: Http.Request, identity: string, slots: Vec, bodyBytes: i64): Result ``` Caller supplies the HTTP endpoint and request; this adapter does no redirects. Body admission occurs during Incoming consumption, before JSON record decoding. Effects: fail, read, write, console, io. ### `semantics` ```gizlang function semantics(dialect: string): Result ``` The 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. ### `text` ```gizlang function text(client: TextClient, identity: string, semantics: Semantics): Source ``` A 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. ### `postgres` ```gizlang function postgres(connection: Pg.Connection, identity: string): Source ``` A source on a PostgreSQL connection (gizlang:postgres). Effects: fail. ## Methods ### `Source.describe` ```gizlang function Source.describe(self: Source): Descriptor ``` The descriptor of the source: its contract version, identity, semantics, capabilities and limits. Effects: fail. ### `Source.admit` ```gizlang function Source.admit(self: Source, request: Request, need: Requirement, revision: bytes): Result ``` Admit 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. ### `Source.require` ```gizlang function Source.require(self: Source, need: Requirement): Result ``` Fails with an error that names the first capability of NEED that the source does not have. Effects: fail. ### `Source.transaction` ```gizlang function Source.transaction(self: Source, commands: Vec, result: T): Result ``` Runs COMMANDS as one transaction of the source; RESULT when they all succeed. ### `Source.discover` ```gizlang function Source.discover(self: Source, tree: Select, parameters: Vec, values: Vec, rows: i64, bytes: i64): Result ``` A 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.