# Rust Order: first read and write

This source-only package reuses the evaluated Order v1.0 model, unchanged generated
library and original eight-case Rust console. It contains no runtime checkout,
compiled executable, Cargo cache or database. No generator account, model upload
or online Assist call is required for this fixed example.

## Requirements

- Rustup and the pinned Rust **1.97.1** toolchain (`rust-toolchain.toml`).
- Bash and a C compiler/linker: Xcode Command Line Tools on macOS, or a native
  build toolchain such as `build-essential` on Debian/Ubuntu. SQLite is bundled
  and compiled by the dependency; no database server or Docker is required.
- Internet access to crates.io and static.crates.io; static.rust-lang.org if
  Rustup needs to install the toolchain.
- Python 3 only for the optional independent SQLite check.

## Run

From the extracted `order-rust` directory:

```bash
rustup toolchain install 1.97.1 --profile minimal
rustc --version
cargo --version
bash order.sh build
bash order.sh init
bash order.sh read
bash order.sh edit
bash order.sh verify
```

`build` uses `cargo build --locked`, this package's `.cargo-home` cache and
`target` directory, with four parallel jobs by default. `Cargo.lock` records
registry sources and checksums. The application pins all six TeaQL runtime crates
to published **5.0.7**; the generated library manifest and source are unchanged.
This is a historical first-flow version, not the newest runtime. Do not run
`cargo update` or silently replace the runtime with a workspace checkout.

`init` explicitly ensures the SQLite schema and seeds three Orders with six
items using the generated audited API. `read` prints `ORDER_CASE` JSON:
`ORD-2026-1001` starts at **3850** USD cents. `edit` changes `SKU-NOTEBOOK` quantity
from 2 to 3, its line total to **3750**, and the Order total to **5100**.
`verify` starts a separate process and reads the stored graph: the changed Order
and item have version 2; untouched items retain version 1. Every successful
phase ends with `ORDER_OK phase=...`.

The default DB is `.local/orders.sqlite`. `init` refuses an existing file and
never deletes data. Read/edit/verify refuse a missing database. To repeat, choose
a new absolute path and run the complete sequence again:

```bash
export ORDER_DATABASE="$(mktemp -d)/orders.sqlite"
bash order.sh init
bash order.sh read
bash order.sh edit
bash order.sh verify
```

The script maps `ORDER_DATABASE` to the generated factory input
`ORDER_WORKFLOW_SERVICE_CORE_DATABASE_URL=sqlite://...` and sets `ORDER_FIXTURE`.
Each phase runs in a separate process against the same absolute file path.
Run `edit` once when comparing the first-run version numbers.

Optional independent read-only assertion after the edit:

```bash
python3 check_database.py "${ORDER_DATABASE:-$PWD/.local/orders.sqlite}" edited fixture.json
```

The oracle validates persisted quantities, totals, versions, relationships and
SQLite integrity; it does not seed or repair data. `bash order.sh notes` runs
the previously recorded null-state and invalid-quantity examples. Intentional
NotLoaded panics are caught by the application; they are distinct from a failed
build or an unhandled process failure.

## Scope and source layout

- `rust-app-console/src/main.rs`: the unchanged original first-flow application,
  including runtime creation, explicit schema initialization and audited edits.
- `rust-lib-core/lib/`: unchanged generated type library; do not edit it or read
  generated source for API discovery. New model/API work requires evaluation,
  generation and scoped Assist for that revision.
- `model.xml`, `fixture.json`, `expectations.json`: exact Order v1.0 inputs.
- `provenance.json`: copied-file hashes and original public receipt.

The original first-flow receipt used published 5.0.7. Later Rust pagination and
advanced Order receipts remain **WORKSPACE PASS — RELEASE PENDING**. Nullable/
pagination Assist repairs remain **pending generator deployment**. This package
does not contain the later seventeen-case application, and its first-run check
does not qualify those later scenarios or clear their release markers.

## Troubleshooting

- Wrong compiler: run the version commands inside this directory; check for a
  `RUSTUP_TOOLCHAIN` override if Rustup ignores `rust-toolchain.toml`.
- Registry/download failure: restore access to the public registry and retry
  `build` with the same lockfile. No runtime source checkout is required.
- Native compiler/linker error: install the platform's C toolchain. SQLite's
  bundled C source still needs a compiler. Lower `ORDER_BUILD_JOBS` if RAM is tight.
- Lockfile-change error: restore the package's manifests and lockfile; avoid
  mixing a freshly generated library with this pinned application.
- Missing executable: complete `build` before running phases.
- Existing DB or a partial seed: choose a new disposable `ORDER_DATABASE`; the
  fixture program is not an import/upsert or recovery service.
- Wrong totals/versions: use a fresh run and preserve complete item loading,
  checked arithmetic and the transaction containing both Order and item saves.

Tutorial: https://teaql.io/docs/languages/rust-order-tutorial/
Original receipt: https://teaql.io/examples/order/evidence/native-sqlite-2026-10-27.json
