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

```gizlang
import * as Source from "gizmodel/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`: `M151.Select`
- `parameters`: `Vec<M142.Slot>`
- `values`: `Vec<M143.Value>`
- `outputs`: `Vec<M142.Slot>`
- `rows`: `i64`
- `bytes`: `i64`
- `sql`: `string`

### `Cursor`

```gizlang
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.DbError`
- `dispose`: `() => bool throws M129.DbError`

### `Source`

```gizlang
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`: `string`
- `semantics`: `M140.Semantics`
- `capabilities`: `M140.Capabilities`
- `prepare`: `(request: M140.Request) => M140.Cursor throws M129.DbError`
- `change`: `(commands: Vec<M151.Statement>) => i64 throws M129.DbError`
- `read`: `_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`

```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`: `M140.Semantics`
- `capabilities`: `M140.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>>, 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.DbError`
- `atomic`: `(statements: Vec<string>) => i64 throws M129.DbError`
- `numbered`: `bool`
- `version`: `() => 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`

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

Database-first callers pin observed result schemas rather than guessing a row type.

Effects: fail, alloc.

### `federated`

```gizlang
function federated(sources: Vec<Source>, atomic: bool, live: bool): Vec<Version> throws DbError
```

A federation requires identical semantics for a moved calculation and keeps
source frontiers distinct. Atomic distributed writes are never implied.

Effects: fail, alloc.

### `document`

```gizlang
function document(identity: string, slots: Vec<Typed.Slot>, text: string): Source throws 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, alloc.

### `semantics`

```gizlang
function semantics(dialect: string): Semantics throws 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, alloc.

### `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, alloc.

### `mutations`

```gizlang
function mutations(commands: Vec<Statement>, dialect: string): Vec<string> throws DbError
```

The SQL of an external source's batch of COMMANDS in DIALECT, each with its literals written in: at most 1024.

Effects: fail, alloc.

### `projection`

```gizlang
function projection(request: Request, identity: string): bool
```

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

```gizlang
function sqlFault(e: Sql.SqlError): DbError
```

A database's failure as a DbError: its SQLSTATE (HY000 when it has none) and its native code.

Effects: fail, alloc.

### `database`

```gizlang
function database(store: Sql.Database, identity: string): Source
```

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

```gizlang
function Source.describe(self: Source): Descriptor
```

The descriptor of the source: its contract version, identity, semantics, capabilities and limits.

Effects: fail, alloc.

### `Source.admit`

```gizlang
function Source.admit(self: Source, request: Request, need: Requirement, revision: bytes): bool throws 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, alloc.

### `Source.request`

```gizlang
function Source.request(self: Source, request: Request, need: Requirement): bool throws DbError
```

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

```gizlang
function Source.require(self: Source, need: Requirement): bool throws DbError
```

Fails with an error that names the first capability of NEED that the source does not have.

Effects: fail, alloc.

### `Source.transaction`

```gizlang
function Source.transaction<T>(self: Source, commands: Vec<Statement>, result: T): T throws 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): Cursor throws 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, alloc.

