# 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<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`: `_gizlang_lib_db__sql__ast.Select`
- `parameters`: `Vec<M54.Slot>`
- `values`: `Vec<M55.Value>`
- `outputs`: `Vec<M54.Slot>`
- `rows`: `i64`
- `bytes`: `i64`
- `sql`: `string`

### `Cursor`

```gizlang
type Cursor = { slots: Vec<Typed.Slot>; versions: Vec<Version>; poll: (rows: i64, bytes: i64) => Result<FinitePoll, DbError>; close: () => Result<bool, 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<M54.Slot>`
- `versions`: `Vec<M61.Version>`
- `poll`: `(rows: i64, bytes: i64) => _gizlang_sdk_core.Result<_gizlang_lib_db__sql__exec__vm.FinitePoll, M56.DbError>`
- `close`: `() => _gizlang_sdk_core.Result<bool, M56.DbError>`

### `Source`

```gizlang
type Source = { identity: string; semantics: Semantics; capabilities: Capabilities; prepare: (request: Request) => Result<Cursor, DbError>; change: (commands: Vec<Statement>) => Result<i64, DbError>; read: Option<NativeRead>; }
```

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<M61.Cursor, M56.DbError>`
- `change`: `(commands: Vec<_gizlang_lib_db__sql__ast.Statement>) => _gizlang_sdk_core.Result<i64, M56.DbError>`
- `read`: `_gizlang_sdk_core.Option<(sql: string, rows: i64, bytes: i64) => _gizlang_sdk_core.Result<M61.Cursor, M56.DbError>>`

### `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<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`

```gizlang
type TextClient = { query: (sql: string, parameters: Vec<Option<string>>) => Result<TextRows, DbError>; atomic: (statements: Vec<string>) => Result<i64, DbError>; 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<string>>) => _gizlang_sdk_core.Result<M61.TextRows, M56.DbError>`
- `atomic`: `(statements: Vec<string>) => _gizlang_sdk_core.Result<i64, M56.DbError>`
- `numbered`: `bool`

## Functions

### `pinSchema`

```gizlang
function pinSchema(expected: bytes, slots: Vec<Typed.Slot>): Result<bool, DbError>
```

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<Source, DbError>
```

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<Source>, atomic: bool, live: bool): Result<Vec<Version>, 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<Typed.Slot>, text: string): Result<Source, DbError>
```

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<Typed.Slot>, bodyBytes: i64): Result<Source, DbError>
```

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<Semantics, DbError>
```

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<bool, DbError>
```

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<bool, DbError>
```

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<T>(self: Source, commands: Vec<Statement>, result: T): Result<T, DbError>
```

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<Typed.Slot>, values: Vec<Value>, rows: i64, bytes: i64): Result<Cursor, DbError>
```

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.

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<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: _gizlang_lib_db__sql__ast.Select
parameters: Vec<M54.Slot>
values: Vec<M55.Value>
outputs: Vec<M54.Slot>
rows: i64
bytes: i64
sql: string

`Cursor`

gizlang

type Cursor = { slots: Vec<Typed.Slot>; versions: Vec<Version>; poll: (rows: i64, bytes: i64) => Result<FinitePoll, DbError>; close: () => Result<bool, 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<M54.Slot>
versions: Vec<M61.Version>
poll: (rows: i64, bytes: i64) => _gizlang_sdk_core.Result<_gizlang_lib_db__sql__exec__vm.FinitePoll, M56.DbError>
close: () => _gizlang_sdk_core.Result<bool, M56.DbError>

`Source`

gizlang

type Source = { identity: string; semantics: Semantics; capabilities: Capabilities; prepare: (request: Request) => Result<Cursor, DbError>; change: (commands: Vec<Statement>) => Result<i64, DbError>; read: Option<NativeRead>; }

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<M61.Cursor, M56.DbError>
change: (commands: Vec<_gizlang_lib_db__sql__ast.Statement>) => _gizlang_sdk_core.Result<i64, M56.DbError>
read: _gizlang_sdk_core.Option<(sql: string, rows: i64, bytes: i64) => _gizlang_sdk_core.Result<M61.Cursor, M56.DbError>>

`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<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`

gizlang

type TextClient = { query: (sql: string, parameters: Vec<Option<string>>) => Result<TextRows, DbError>; atomic: (statements: Vec<string>) => Result<i64, DbError>; 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<string>>) => _gizlang_sdk_core.Result<M61.TextRows, M56.DbError>
atomic: (statements: Vec<string>) => _gizlang_sdk_core.Result<i64, M56.DbError>
numbered: bool

Functions

`pinSchema`

gizlang

function pinSchema(expected: bytes, slots: Vec<Typed.Slot>): Result<bool, DbError>

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<Source, DbError>

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<Source>, atomic: bool, live: bool): Result<Vec<Version>, 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<Typed.Slot>, text: string): Result<Source, DbError>

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<Typed.Slot>, bodyBytes: i64): Result<Source, DbError>

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<Semantics, DbError>

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<bool, DbError>

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<bool, DbError>

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<T>(self: Source, commands: Vec<Statement>, result: T): Result<T, DbError>

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<Typed.Slot>, values: Vec<Value>, rows: i64, bytes: i64): Result<Cursor, DbError>

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.