# TypeScript Order: first read and write

This source-only package reuses the evaluated Order v1.0 model, unchanged generated
library and original eight-case Node console. It contains no runtime checkout,
node_modules, npm cache, native addon binary or database. No generator account,
model upload or online Assist request is needed for this fixed example.

## Requirements

- Node **22.23.4** and its bundled npm. With nvm already installed, run `nvm install`
  and `nvm use` inside this directory. Alternatively install that version from
  https://nodejs.org/dist/v22.23.4/ and put its `bin` directory on PATH.
- Bash (macOS/Linux, or WSL on Windows), and access to registry.npmjs.org.
- `better-sqlite3` is a native addon. Its installer may download a matching public
  prebuilt binary from GitHub. If no compatible prebuild is available, compilation
  needs Python 3 and a C/C++ toolchain (Xcode Command Line Tools on macOS, or the
  platform compiler, make and headers on Linux). Node headers may be downloaded
  from nodejs.org. No database server or Docker is needed.
- Python 3 is optional for the independent SQLite check below when installation
  uses a prebuilt addon binary.

## Run

From the extracted `order-typescript` directory:

```bash
node --version
npm --version
bash order.sh build
bash order.sh init
bash order.sh read
bash order.sh edit
bash order.sh verify
```

`build` runs `npm ci` with the unchanged lockfile and package-local `.npm-cache`,
then `npm run build` (`tsc --noEmit`). Explicit user/global npm settings select the
public registry. Runtime phases use the installed local ts-node; no global
TypeScript or ts-node is needed. Do not use `--ignore-scripts`: the native addon
needs its install step. Match `.nvmrc` before installation and execution.

The unchanged manifest uses the exact npm alias
`"teaql-ts": "npm:@teaql/teaql@0.3.1"`. The lockfile fixes better-sqlite3 12.11.1,
TypeScript 5.9.3, ts-node 10.9.2 and transitive dependencies. Do not replace the
alias, update the lockfile or copy node_modules from a runtime workspace. This
recipe qualifies historical published 0.3.1, not the latest release.

`init` explicitly ensures schema and seeds three Orders/six items through 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` reads the persisted
graph in a new Node process: the changed Order/item have version 2; untouched
items retain version 1. Successful phases end 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. For another first run:

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

Use the same absolute database path for all four commands. Run the edit once
when comparing first-run versions. The script supplies the included fixture;
the seed command is not an import/upsert service.

Optional independent check after the edit:

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

The oracle opens SQLite read-only and checks quantities, totals, versions,
relationships and integrity. `bash order.sh notes` runs the previously recorded
nullable/projection/invalid-quantity handlers, including handled NotLoaded errors.
These are distinct from unhandled startup or addon-load failures.

## Source and qualification boundaries

- `src/main.ts`: unchanged original first-flow application, including explicit
  SQLite provider/context wiring and schema initialization.
- Other `src/` files: retained generated library, adapters and runtime module;
  unchanged. Do not inspect generated source for API discovery or hand-edit it.
  New model/API work requires evaluation, generation and scoped Assist.
- `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 0.3.1. Later TypeScript deletion
readback/pagination/advanced Order receipts remain **WORKSPACE PASS — RELEASE PENDING**;
the nullable generator repair remains **pending generator deployment**. This
is the original eight-case console, not the later seventeen-case program. First
read/edit success does not clear those markers or certify browser/TFP, long-lived
service cleanup, cancellation or stress behavior.

## Troubleshooting

- Wrong Node: activate 22.23.4 before both install and run. Do not reuse node_modules
  produced for another Node ABI, OS or architecture.
- Addon load/ABI error: restore the pinned Node, rerun `build`, and check the
  prebuild download or fallback compilation. This is not a query/version conflict.
- Registry/install failure: check public registry and prebuild/header hosts;
  retry the same locked build. Do not inject an unpublished runtime to hide it.
- Existing DB or partial seed: choose a new disposable `ORDER_DATABASE`.
- Empty read: confirm the same absolute DB path was initialized successfully.
- Wrong total/version: use a fresh run; preserve complete child loading, safe
  integer checks and the audited Order graph save.

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