@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/docs/examples/native-pytorch/index.md

@@ -0,0 +1,38 @@
+---
+title: "CPU tensors with PyTorch"
+generated: true
+source: "examples/native-pytorch"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# CPU tensors with PyTorch
+
+Import real LibTorch from its public August package, add CPU tensors, and verify the elements and sum. Owned tensors are released when their scope ends.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+This project requires the August `0.21.0` LLVM preview on macOS 14+ with Apple Silicon, or Debian/Ubuntu GNU/Linux x64 or ARM64 with glibc 2.36+. The library archives are public; the matching compiler release is still being qualified.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`tensors.aug`](tensors.md)
+
+
+## Try this project
+
+[Download this project](/downloads/native-pytorch.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd native-pytorch
+aug install .
+aug check .
+aug spec .
+aug test .
+aug run .
+```
+
+[Browse all examples](../index.md)

package/docs/examples/native-pytorch/main.md

@@ -0,0 +1,73 @@
+---
+title: "main.aug · CPU tensors with PyTorch"
+generated: true
+source: "examples/native-pytorch/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[CPU tensors with PyTorch](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`tensors.aug`](tensors.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import calculate from tensors
+import TensorError from "https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4"
+try:
+    print(value=calculate())
+catch TensorError error:
+    print(value=error.message)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import calculate from tensors
+import TensorError from "https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4"
+try {
+    print(value=calculate())
+}
+catch TensorError error {
+    print(value=error.message)
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It prints [`calculate`](tensors.md#symbol-calculate). If this work raises [`TensorError`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/contracts.md#symbol-TensorError) as `error`, it prints `error.message`.
+
+### Dependencies
+
+It uses [`TensorError`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/contracts.md#symbol-TensorError) (`message`) from `https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4`. It uses [`calculate`](tensors.md#symbol-calculate) from `tensors`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/native-pytorch/tensors.md

@@ -0,0 +1,123 @@
+---
+title: "tensors.aug · CPU tensors with PyTorch"
+generated: true
+source: "examples/native-pytorch/tensors.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `tensors.aug`
+
+[CPU tensors with PyTorch](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`tensors.aug`](tensors.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "tensors.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Tensor and TensorError and tensor and add and sum and values from "https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4"
+/** Add two CPU tensors using LibTorch and return the sum of their elements. */
+calculate() returns float unless TensorError:
+    own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+    own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+    own Tensor result = add(left, right)
+    return sum(tensor=result)
+test calculate:
+    when "cpu":
+        it "adds_and_reads_real_tensors":
+            own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+            own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+            own Tensor result = add(left, right)
+            List<float> output = values(tensor=result)
+            assert(output.length() == 3)
+            assert(output.get(index=0) == 5.0)
+            assert(output.get(index=1) == 7.0)
+            assert(output.get(index=2) == 9.0)
+            assert(sum(tensor=result) == 21.0)
+            assert(calculate() == 21.0)
+```
+
+```aug [Braces]
+// aug-spec: "tensors.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Tensor and TensorError and tensor and add and sum and values from "https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4"
+/** Add two CPU tensors using LibTorch and return the sum of their elements. */
+calculate() returns float unless TensorError {
+    own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+    own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+    own Tensor result = add(left, right)
+    return sum(tensor=result)
+}
+test calculate {
+    when "cpu" {
+        it "adds_and_reads_real_tensors" {
+            own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+            own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+            own Tensor result = add(left, right)
+            List<float> output = values(tensor=result)
+            assert(output.length() == 3)
+            assert(output.get(index=0) == 5.0)
+            assert(output.get(index=1) == 7.0)
+            assert(output.get(index=2) == 9.0)
+            assert(sum(tensor=result) == 21.0)
+            assert(calculate() == 21.0)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `calculate` · [source](tensors.md#code) {#symbol-calculate}
+
+Add two CPU tensors using LibTorch and return the sum of their elements. Failures can raise [`TensorError`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/contracts.md#symbol-TensorError).
+
+It sets `left` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-tensor) with `values` from a list containing `1.0`, `2.0`, `3.0`. `left` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value. It sets `right` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-tensor) with `values` from a list containing `4.0`, `5.0`, `6.0`. `right` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value.
+
+It sets `result` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`add`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-add) with `left` and `right`. `result` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value. It returns [`sum`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-sum) with `tensor` from `result`.
+
+### `test calculate` · [source](tensors.md#code) {#symbol-test-20-calculate}
+
+Tests [`calculate`](tensors.md#symbol-calculate). Each case gets fresh setup and dependencies.
+
+#### `cpu`
+
+##### `adds_and_reads_real_tensors` · [source](tensors.md#code)
+
+It sets `left` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-tensor) with `values` from a list containing `1.0`, `2.0`, `3.0`. `left` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value. It sets `right` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-tensor) with `values` from a list containing `4.0`, `5.0`, `6.0`. `right` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value.
+
+It sets `result` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) to [`add`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-add) with `left` and `right`. `result` of type [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor) owns this value. It sets `output` of type `List<float>` to [`values`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-values) with `tensor` from `result`. The test requires the number of elements in `output` equals `3`.
+
+The test requires the item at index `0` in `output` equals `5.0`. The test requires the item at index `1` in `output` equals `7.0`. The test requires the item at index `2` in `output` equals `9.0`. The test requires [`sum`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-sum) with `tensor` from `result` equals `21.0`.
+
+The test requires [`calculate`](tensors.md#symbol-calculate) equals `21.0`.
+
+### Dependencies
+
+It uses [`add`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-add), [`sum`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-sum), [`tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-tensor), [`values`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/api.md#symbol-values), [`Tensor`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/bindings.md#symbol-Tensor), and [`TensorError`](dependencies/packages/%40greenpandastudios/aug-pytorch/0.1.4/contracts.md#symbol-TensorError) from `https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/native-sqlite/database.md

@@ -0,0 +1,116 @@
+---
+title: "database.aug · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/database.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `database.aug`
+
+[A database with SQLite](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`database.aug`](database.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "database.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database and SqliteError and openMemory and execute and queryScalar from "https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3"
+/** Store a bound value in an in-memory SQLite database and read it back. */
+storedName() returns string unless SqliteError:
+    own Database database = openMemory()
+    borrow database:
+        execute(
+            database,
+            sql="CREATE TABLE users (name TEXT NOT NULL)",
+            parameters=[]
+        )
+        execute(
+            database,
+            sql="INSERT INTO users (name) VALUES (?)",
+            parameters=["August"]
+        )
+    return queryScalar(database, sql="SELECT name FROM users", parameters=[])
+test storedName:
+    when "database":
+        it "inserts_and_queries_bound_data":
+            assert(storedName() == "August")
+```
+
+```aug [Braces]
+// aug-spec: "database.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database and SqliteError and openMemory and execute and queryScalar from "https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3"
+/** Store a bound value in an in-memory SQLite database and read it back. */
+storedName() returns string unless SqliteError {
+    own Database database = openMemory()
+    borrow database {
+        execute(
+            database,
+            sql="CREATE TABLE users (name TEXT NOT NULL)",
+            parameters=[]
+        )
+        execute(
+            database,
+            sql="INSERT INTO users (name) VALUES (?)",
+            parameters=["August"]
+        )
+    }
+    return queryScalar(database, sql="SELECT name FROM users", parameters=[])
+}
+test storedName {
+    when "database" {
+        it "inserts_and_queries_bound_data" {
+            assert(storedName() == "August")
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `storedName` · [source](database.md#code) {#symbol-storedName}
+
+Store a bound value in an in-memory SQLite database and read it back. Failures can raise [`SqliteError`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/contracts.md#symbol-SqliteError).
+
+It gets `database` of type [`Database`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/bindings.md#symbol-Database) from [`openMemory`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-openMemory). `database` of type [`Database`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/bindings.md#symbol-Database) owns this value. With temporary permission to change `database`, it calls [`execute`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-execute) with `database`, `sql` `"CREATE TABLE users (name TEXT NOT NULL)"`, and `parameters` from a list with no items; then it calls [`execute`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-execute) with `database`, `sql` `"INSERT INTO users (name) VALUES (?)"`, and `parameters` from a list containing `"August"`. It returns [`queryScalar`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-queryScalar) with `database`, `sql` `"SELECT name FROM users"`, and `parameters` from a list with no items.
+
+### `test storedName` · [source](database.md#code) {#symbol-test-20-storedName}
+
+Tests [`storedName`](database.md#symbol-storedName). Each case gets fresh setup and dependencies.
+
+#### `database`
+
+##### `inserts_and_queries_bound_data` · [source](database.md#code)
+
+The test requires [`storedName`](database.md#symbol-storedName) equals `"August"`.
+
+### Dependencies
+
+It uses [`execute`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-execute), [`openMemory`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-openMemory), [`queryScalar`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/api.md#symbol-queryScalar), [`Database`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/bindings.md#symbol-Database), and [`SqliteError`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/contracts.md#symbol-SqliteError) from `https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/native-sqlite/dependencies/packages/@greenpandastudios/aug-sqlite/0.1.3/api.md

@@ -0,0 +1,284 @@
+---
+title: "packages/@greenpandastudios/aug-sqlite/0.1.3/api.aug · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/.aug-spec/packages/@greenpandastudios/aug-sqlite/0.1.3/api.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-sqlite/0.1.3/api.aug`
+
+[A database with SQLite](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database from bindings
+import SqliteError and DatabaseStorage from contracts
+extern C _open(string path) returns own Database unless SqliteError
+extern C _execute(borrow Database database, string sql, List<string> parameters) returns int changes database unless SqliteError
+extern C _queryScalar(Database database, string sql, List<string> parameters) returns string unless SqliteError
+/** Open a serialized connection. Use :memory: for an in-memory database. */
+NativeDatabaseStorage() implements DatabaseStorage:
+    open(string path) returns own Database:
+        unsafe:
+            return _open(path)
+open(resolve DatabaseStorage storage, string path) returns own Database:
+    return storage.open(path)
+/** Open an in-memory database without filesystem permission. */
+openMemory() returns own Database:
+    unsafe:
+        return _open(path=":memory:")
+/** Execute one parameterized statement. Return the number of changed rows. */
+execute(borrow Database database, string sql, List<string> parameters) returns int:
+    unsafe:
+        return _execute(database, sql, parameters)
+/** Query one non-null text value with SELECT. Reject PRAGMAs, transactions, savepoints and writes before execution. Copy the result before finalization. */
+queryScalar(Database database, string sql, List<string> parameters) returns string:
+    unsafe:
+        return _queryScalar(database, sql, parameters)
+test openMemory:
+    when "databases":
+        it "binds_and_queries":
+            own Database database = openMemory()
+            borrow database:
+                execute(
+                    database,
+                    sql="CREATE TABLE users (name TEXT NOT NULL)",
+                    parameters=[]
+                )
+                execute(
+                    database,
+                    sql="INSERT INTO users (name) VALUES (?)",
+                    parameters=["O'Reilly"]
+                )
+            assert(
+                queryScalar(database, sql="SELECT name FROM users", parameters=[]) == "O'Reilly"
+            )
+        it "rejects_connection_and_transaction_control":
+            own Database database = openMemory()
+            for statement in [
+                "PRAGMA query_only=ON",
+                "BEGIN",
+                "COMMIT",
+                "ROLLBACK",
+                "SAVEPOINT hidden"
+            ]:
+                rejected = false
+                try:
+                    queryScalar(database, sql=statement, parameters=[])
+                catch SqliteError error:
+                    rejected = error.code == 23
+                assert(rejected)
+            borrow database:
+                execute(
+                    database,
+                    sql="CREATE TABLE rows (value TEXT)",
+                    parameters=[]
+                )
+                execute(
+                    database,
+                    sql="INSERT INTO rows VALUES (?)",
+                    parameters=["unchanged"]
+                )
+            assert(
+                queryScalar(database, sql="SELECT value FROM rows", parameters=[]) == "unchanged"
+            )
+```
+
+```aug [Braces]
+// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database from bindings
+import SqliteError and DatabaseStorage from contracts
+extern C _open(string path) returns own Database unless SqliteError
+extern C _execute(borrow Database database, string sql, List<string> parameters) returns int changes database unless SqliteError
+extern C _queryScalar(Database database, string sql, List<string> parameters) returns string unless SqliteError
+/** Open a serialized connection. Use :memory: for an in-memory database. */
+NativeDatabaseStorage() implements DatabaseStorage {
+    open(string path) returns own Database {
+        unsafe {
+            return _open(path)
+        }
+    }
+}
+open(resolve DatabaseStorage storage, string path) returns own Database {
+    return storage.open(path)
+}
+/** Open an in-memory database without filesystem permission. */
+openMemory() returns own Database {
+    unsafe {
+        return _open(path=":memory:")
+    }
+}
+/** Execute one parameterized statement. Return the number of changed rows. */
+execute(borrow Database database, string sql, List<string> parameters) returns int {
+    unsafe {
+        return _execute(database, sql, parameters)
+    }
+}
+/** Query one non-null text value with SELECT. Reject PRAGMAs, transactions, savepoints and writes before execution. Copy the result before finalization. */
+queryScalar(Database database, string sql, List<string> parameters) returns string {
+    unsafe {
+        return _queryScalar(database, sql, parameters)
+    }
+}
+test openMemory {
+    when "databases" {
+        it "binds_and_queries" {
+            own Database database = openMemory()
+            borrow database {
+                execute(
+                    database,
+                    sql="CREATE TABLE users (name TEXT NOT NULL)",
+                    parameters=[]
+                )
+                execute(
+                    database,
+                    sql="INSERT INTO users (name) VALUES (?)",
+                    parameters=["O'Reilly"]
+                )
+            }
+            assert(
+                queryScalar(database, sql="SELECT name FROM users", parameters=[]) == "O'Reilly"
+            )
+        }
+        it "rejects_connection_and_transaction_control" {
+            own Database database = openMemory()
+            for statement in [
+                "PRAGMA query_only=ON",
+                "BEGIN",
+                "COMMIT",
+                "ROLLBACK",
+                "SAVEPOINT hidden"
+            ] {
+                rejected = false
+                try {
+                    queryScalar(database, sql=statement, parameters=[])
+                }
+                catch SqliteError error {
+                    rejected = error.code == 23
+                }
+                assert(rejected)
+            }
+            borrow database {
+                execute(
+                    database,
+                    sql="CREATE TABLE rows (value TEXT)",
+                    parameters=[]
+                )
+                execute(
+                    database,
+                    sql="INSERT INTO rows VALUES (?)",
+                    parameters=["unchanged"]
+                )
+            }
+            assert(
+                queryScalar(database, sql="SELECT value FROM rows", parameters=[]) == "unchanged"
+            )
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `NativeDatabaseStorage` · class · [source](api.md#code) {#symbol-NativeDatabaseStorage}
+
+Open a serialized connection. Use :memory: for an in-memory database. It implements [`DatabaseStorage`](contracts.md#symbol-DatabaseStorage).
+
+#### `NativeDatabaseStorage.open` · [source](api.md#code) {#symbol-NativeDatabaseStorage.open}
+
+It takes `path` as a string. It returns ownership of [`Database`](bindings.md#symbol-Database). Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+Within an unsafe block, it returns [`_open`](api.md#symbol-_open) with `path`. Native operations must satisfy their declared C contracts.
+
+### `open` · [source](api.md#code) {#symbol-open}
+
+It takes `path` as a string. It gets `storage` ([`DatabaseStorage`](contracts.md#symbol-DatabaseStorage)) from dependency injection. It returns ownership of [`Database`](bindings.md#symbol-Database). Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+It returns [`storage.open`](contracts.md#symbol-DatabaseStorage.open) with `path`.
+
+### `openMemory` · [source](api.md#code) {#symbol-openMemory}
+
+Open an in-memory database without filesystem permission. It returns ownership of [`Database`](bindings.md#symbol-Database). Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+Within an unsafe block, it returns [`_open`](api.md#symbol-_open) with `path` `":memory:"`. Native operations must satisfy their declared C contracts.
+
+### `execute` · [source](api.md#code) {#symbol-execute}
+
+Execute one parameterized statement. Return the number of changed rows. It takes `database` as [`Database`](bindings.md#symbol-Database) with permission to mutate it during the call, `sql` as a string, and `parameters` as `List<string>`.
+
+It may change `database`. Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError). Within an unsafe block, it returns [`_execute`](api.md#symbol-_execute) with `database`, `sql`, and `parameters`. Native operations must satisfy their declared C contracts.
+
+### `queryScalar` · [source](api.md#code) {#symbol-queryScalar}
+
+Query one non-null text value with SELECT. Reject PRAGMAs, transactions, savepoints and writes before execution. Copy the result before finalization. It takes `database` as [`Database`](bindings.md#symbol-Database), `sql` as a string, and `parameters` as `List<string>`.
+
+Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError). Within an unsafe block, it returns [`_queryScalar`](api.md#symbol-_queryScalar) with `database`, `sql`, and `parameters`. Native operations must satisfy their declared C contracts.
+
+### `_open` · [source](api.md#code) {#symbol-_open}
+
+It is private to its defining scope. It takes `path` as a string. It returns ownership of [`Database`](bindings.md#symbol-Database). Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+Native implementation: `@greenpandastudios/aug-sqlite@0.1.3`, `3.53.4`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi-json.md) (SHA-256 `3c75c2925c85f1b83db06ee00fa04f1d2d37c9fd6edca0d074ce89b4647ffffb`). It calls `aug_sqlite_open_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. The caller owns the returned handle. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+### `_execute` · [source](api.md#code) {#symbol-_execute}
+
+It is private to its defining scope. It takes `database` as [`Database`](bindings.md#symbol-Database) with permission to mutate it during the call, `sql` as a string, and `parameters` as `List<string>`.
+
+It returns `int`. It may change `database`. Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+Native implementation: `@greenpandastudios/aug-sqlite@0.1.3`, `3.53.4`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi-json.md) (SHA-256 `3c75c2925c85f1b83db06ee00fa04f1d2d37c9fd6edca0d074ce89b4647ffffb`). It calls `aug_sqlite_execute_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. `database` lends mutable access for this call. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+### `_queryScalar` · [source](api.md#code) {#symbol-_queryScalar}
+
+It is private to its defining scope. It takes `database` as [`Database`](bindings.md#symbol-Database), `sql` as a string, and `parameters` as `List<string>`. It returns `string`. Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+Native implementation: `@greenpandastudios/aug-sqlite@0.1.3`, `3.53.4`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi-json.md) (SHA-256 `3c75c2925c85f1b83db06ee00fa04f1d2d37c9fd6edca0d074ce89b4647ffffb`). It calls `aug_sqlite_scalar_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. `database` lends read access for this call. August copies the returned buffer, then calls `aug_sqlite_text_release_v1` to release it. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+### `test openMemory` · [source](api.md#code) {#symbol-test-20-openMemory}
+
+Tests [`openMemory`](api.md#symbol-openMemory). Each case gets fresh setup and dependencies.
+
+#### `databases`
+
+##### `binds_and_queries` · [source](api.md#code)
+
+It gets `database` of type [`Database`](bindings.md#symbol-Database) from [`openMemory`](api.md#symbol-openMemory). `database` of type [`Database`](bindings.md#symbol-Database) owns this value. With temporary permission to change `database`, it calls [`execute`](api.md#symbol-execute) with `database`, `sql` `"CREATE TABLE users (name TEXT NOT NULL)"`, and `parameters` from a list with no items; then it calls [`execute`](api.md#symbol-execute) with `database`, `sql` `"INSERT INTO users (name) VALUES (?)"`, and `parameters` from a list containing `"O'Reilly"`. The test requires [`queryScalar`](api.md#symbol-queryScalar) with `database`, `sql` `"SELECT name FROM users"`, and `parameters` from a list with no items equals `"O'Reilly"`.
+
+##### `rejects_connection_and_transaction_control` · [source](api.md#code)
+
+It gets `database` of type [`Database`](bindings.md#symbol-Database) from [`openMemory`](api.md#symbol-openMemory). `database` of type [`Database`](bindings.md#symbol-Database) owns this value. For each `statement` in a snapshot of a list containing `"PRAGMA query_only=ON"`, `"BEGIN"`, `"COMMIT"`, `"ROLLBACK"`, `"SAVEPOINT hidden"`, it sets `rejected` to `false`.
+
+It tries to call [`queryScalar`](api.md#symbol-queryScalar) with `database`, `sql` from `statement`, and `parameters` from a list with no items. If this work raises [`SqliteError`](contracts.md#symbol-SqliteError) as `error`, it sets `rejected` to `error.code` equals `23`. The test requires `rejected` is true. After the loop, with temporary permission to change `database`, it calls [`execute`](api.md#symbol-execute) with `database`, `sql` `"CREATE TABLE rows (value TEXT)"`, and `parameters` from a list with no items; then it calls [`execute`](api.md#symbol-execute) with `database`, `sql` `"INSERT INTO rows VALUES (?)"`, and `parameters` from a list containing `"unchanged"`.
+
+The test requires [`queryScalar`](api.md#symbol-queryScalar) with `database`, `sql` `"SELECT value FROM rows"`, and `parameters` from a list with no items equals `"unchanged"`.
+
+### Dependencies
+
+It uses [`Database`](bindings.md#symbol-Database) from `bindings`. It uses [`DatabaseStorage`](contracts.md#symbol-DatabaseStorage) ([`open`](contracts.md#symbol-DatabaseStorage.open)) and [`SqliteError`](contracts.md#symbol-SqliteError) from `contracts`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::