source/teaql-ts/README.md

# TeaQL TypeScript

An AI-native library and runtime for building reviewable business applications in TypeScript.

TeaQL gives coding agents business-shaped APIs, model-aware guidance and
software checks. People review the business operation instead of reconstructing
pages of query-building, relationship-loading and persistence code.

Automatic execution logs make those operations easier to debug and operate,
without adding logging statements to every business method.

[Try with your coding agent](#try-it-with-your-coding-agent) ·
[Run the local example](#run-the-local-example) ·
[See automatic logs](#automatic-logs-without-handwritten-logging-code)

## Why this is an AI native library

AI-native does not mean the library was written by AI, or that every query
calls an LLM. It means the APIs, knowledge delivery and verification workflow
are designed for how coding agents work: limited context, incomplete knowledge
of a project and a tendency to guess unfamiliar operations.

The semantic model describes your business objects, fields, relationships and
states. A generated domain library turns those words into language-native
**Q** queries, **E** expressions and mutation methods. This repository provides
the reusable, domain-independent **runtime** that executes them through
metadata, Context, Checker, Policy and database providers.

The application workspace keeps business code and concise project guidance
together. Progressive **Assist** supplies the exact API guidance needed for
the next operation, instead of asking the agent to explore the entire generated
library. Compilation, runtime checks and tests provide feedback beyond a prompt.

## Less code for a reviewer to reconstruct

The benefit is visible in the application code: the query, data access path
and audited change stay together, while shared mechanics live in the library
and runtime.

| Application code to review | Shared work handled by TeaQL |
| --- | --- |
| A composed Q request | SQL construction and selected relation loading |
| An E access path | Loaded-field checks and explicit NULL handling |
| A mutation with an audit reason | Change tracking, Checker and configured Policy execution |
| Business intent and audit reason | Automatic execution logs and trace context without per-operation logging code |

Reviewers still decide whether the requested data, business rules and
authorization policy are correct. They have less application plumbing to
trace before making that decision; reuse does not make business logic correct
automatically.

**Token savings have not yet been measured in a controlled comparison.**
We make no numerical token-saving claim. Loading guidance only when needed
is a context-management strategy; the smaller application review surface is
visible in the examples, not a measured percentage reduction in review time.

## See a business operation execute

The [Robot Task Board showcase](https://teaql.io/blog/robot-task-board-showcase/)
makes the idea concrete: move a task and follow the state change, generated
SQL, field-level audit and refreshed board.

![TeaQL Robot Task Board](https://teaql.io/img/003-task-board.png)

Explore the [open-source demo](https://github.com/teaql/robot-task-board).
The showcase is a Rust application; the examples below use this repository's
own TypeScript APIs.

## Q API composes business queries

These application-code excerpts assume the example's generated imports, trusted
Context and an existing object identity. `Q` and `E` belong to the generated
domain library, not a generic runtime object with arbitrary field strings.
See the [application source](examples/school-management/app.ts) for complete setup.

```typescript
const schoolTypeDetails = Q.schoolTypesWithMinimalFields().selectName().selectCode();

const school = await Q.schools()
  .withIdIs(schoolId)
  .selectPlatformWith(Q.platformsWithMinimalFields().selectName().selectBaseUrl())
  .selectSchoolTypeWith(schoolTypeDetails)
  .comment("what: load the school and its reference data")
  .purpose("why: review a school before editing")
  .executeForOne(context);
if (!school) throw new Error("School not found");
```

The child request is a query in its own right. Give it a business name,
extract it into a helper and compose it into other requests like a Lego brick.
The reviewer can see which relationships are loaded without following a
separate set of SQL loops. `comment` describes **what**; `purpose` describes
**why**. Both must be non-empty, even when logging is disabled.

## E API protects business reads

```typescript
const schoolTypeId = E.school(school).schoolTypeId().eval();
```

E reads the loaded graph without implicitly querying the database. A loaded
NULL and a field that was **NotLoaded** are different facts. A business rule
must not conclude that a value is absent merely because the query never
requested it.

The access path is explicit, so the reviewer checks whether Q loaded the
required data and whether the code handles a real NULL appropriately.
Unloaded access produces the language-specific diagnostic; a NULL fallback
is not permission to ignore an unloaded property.

## Mutation API keeps changes behind one Save boundary

The application declares the change and its reason instead of writing its own
persistence loop. A graph can stage additions, updates and deletions before Save.

Load the complete scalar fields of every persisted object you actually modify.
A display-only partial projection is not a complete mutation input. Unmodified
reference objects do not have to become fully loaded just to save their parent.

```typescript
school.updateName("Riverside Academy");
await school.auditAs("Rename the reviewed school").save(context);
```

Save traverses the reached mutation graph, runs Checker/Fix and the configured
customer Mutation Policy, then uses the provider transaction boundary.
An explicit policy denial blocks persistence. Missing customer policy or exact
approval emits a warning; it is not automatic rejection. Marking for deletion
stages a change—the audited Save performs it. Atomicity is provider/route scoped,
not a distributed transaction across unrelated databases.

## Automatic logs without handwritten logging code

**Debuggability and operability are core design goals.** The Q and Save
examples above contain no logging calls: you declare the business intent,
and the runtime produces the execution diagnostics and trace context.
Configured audit sinks receive change events without each application
method having to construct its own field-level diff.

The intent declarations already belong to the business operation:

- `comment` describes what the query does.
- `purpose` explains why it runs.
- `auditAs` gives the reason for a saved change.

No-code logging means no handwritten logger calls in each business method,
not an application without code or intent declarations. Runtime startup
still configures any required sink; custom formats and destinations use the
logging extension points rather than edits to every business operation.

- **Debugging:** connect a query's intent to generated SQL, execution outcome
  and the trace path when a screen or business operation behaves unexpectedly.
- **Operations:** follow query and mutation activity and use audit reasons
  and safely exposed changes to investigate incidents.
- **Review:** inspect the business operation without separately checking
  that every TeaQL execution path has a matching application logging statement.

Query and Mutation diagnostic logs are enabled by default and can be switched
off independently. Logging off does not disable intent validation or Policy.

Illustrative, shortened view of the rename operation, not a literal logger
format or a captured test result; the SQL excerpt omits additional selected fields:

```text
query entity=School comment="load the reviewed object" purpose="edit form" outcome=success
SQL: SELECT id, version, name FROM school_data WHERE id = 42;
trace: School -> request -> sqlite -> select
mutation entity=School auditReason="Rename the reviewed school" outcome=committed
change: name "Riverside Primary School" -> "Riverside Academy"
lineage: School#42("Rename the reviewed school")
```

The declarations explain **why**; SQL and audit evidence show **what happened**.
Together they help locate the relevant operation without reconstructing the
entire call path from scattered application code.

SQL execution stays parameterized. Diagnostic SQL has parameters substituted
after field-aware masking; it is not a question-mark template you must manually
reconstruct. Ordinary bindings stay visible, sensitive bindings use the shared
mask algorithm, and credentials/unknown bindings stay hidden. A masked statement
is labeled `MASKED; NOT REPLAYABLE`; SQL that cannot be safely rendered is omitted.
Application mutation audits are delivered after commit and discarded on rollback.
This is not a durable audit outbox. Do not put secrets in comment or purpose.

### Standard Node telemetry

The local source candidate provides optional environment-driven telemetry for
Node applications. It is separate from default-on SQL logging and committed
business audit. No SDK setup or logging calls are needed in each business method.

```bash
export TEAQL_TELEMETRY_ENABLED=true
export TEAQL_TELEMETRY_SERVICE_NAME=payment-service
export TEAQL_TELEMETRY_OTLP_ENDPOINT=http://localhost:4318
```

Without enablement, startup reports support and these three settings without
loading the SDK or creating export resources. Enabled startup reports full
recording and masked SQL. The module owns its providers and HTTP agents; it
does not replace customer globals. Telemetry uses official SDK protobuf
serialization and bounded acknowledgements. Remote error text is never logged;
fixed diagnostics and loss/rejection counters explain export problems without
changing business outcomes. Partial acceptance never resends the entire batch,
following the [OTLP response contract](https://opentelemetry.io/docs/specs/otlp/#partial-success).

Install the optional SDK cohort listed in this checkout's `package.json`,
including its pinned `@opentelemetry/otlp-transformer`, when using the standard
Node entry. Browser SQLite does not enable this Node-only module. Run
`bash scripts/verify-standard-telemetry.sh` for local startup and graph checks;
`bash scripts/verify-examples.sh` also verifies rollback, retry, selective update
and deletion. This is an unreleased source capability, not a published-package
installation claim. Local production-capacity tests qualify queue saturation,
recovery and backlogged shutdown. Span/log admission includes queued and exporting
records; fixed counters distinguish overflow, failed export, queued retirement
and late handoff. Flush waits for the records accepted before that call. Shutdown
has a six-second budget and closes only module-owned resources; closing telemetry
does not disable database operations or committed audit. Advanced graph/stream
and private artifact installation remain separate acceptance gates.

## Discover only the API needed next

A coding agent does not need every generated method in its context. Start with
the generated application's `AGENTS.md` and workspace guidance, request an
entity/action Assist, then ask for field-specific help only for the field
being used.

For a model in `models/`, the TypeScript query path is:

```bash
cargo teaql typescript-assist-query/school --input models/
cargo teaql typescript-assist-query/school.established_date --input models/
```

These commands call the model-aware service; the model must match the generated
library. Assist uses canonical KSML entity and field names, even when the
language-native API uses a different naming style. Cargo TeaQL is a service
client for multiple languages, not just Rust.

Use Assist to discover operations instead of reading generated library source
or guessing names. If the required operation is missing, report
`MISSING_ASSIST` rather than inventing an API. The
[Agent Kit](https://github.com/teaql/teaql-agent-kit) defines this progressive
workflow. Library and runtime maintenance are separate from application coding.

## Software checks complement agent instructions

AI proposes the model and application logic; software checks the parts that
can be verified mechanically. The library is one part of the TeaQL harness,
not a replacement for business review.

| Stage | TeaQL support | Feedback to inspect |
| --- | --- | --- |
| Model and repair | Semantic model evaluation | Errors, warnings and repair guidance |
| Generate | Domain library combined with this runtime | Language tooling checks the generated API contract |
| Customize the workspace | Progressive Assist, Q, E and mutation APIs | Build diagnostics, Checker and configured Policy results |
| Verify and operate | Tests, runtime startup, intent and audit evidence | Actual outcomes, remaining failures and execution paths |

Build checks verify API use, not whether the business decision is right.
Tests must still verify the application's behavior. A prompt, successful
generation or a clean build alone does not prove the finished application correct.

## Try it with your coding agent

You can start with an agent you already use. Paste this prompt:

```text
Follow the current instructions at https://github.com/teaql/teaql-agent-kit.
Build a small school-management application in TypeScript using SQLite.
Evaluate and repair the model, generate the domain library and prepare a runnable
application workspace. Verify Q, E, Checker and audited Save.
Finish with a report of commands, results and
remaining frictions. Include Q/E examples and relevant intent/audit logs.
Do not claim token savings without a measured comparison.
```

The [Agent Kit](https://github.com/teaql/teaql-agent-kit) guides modeling,
evaluation/repair, generation and application customization. It may install
toolchains and download dependencies; review installation permissions and the
final execution report. It is a workflow, not a guarantee of unattended correctness.

## Run the local example

Node.js/npm for the repository examples. Browser SQLite runs in a Web Worker with SQLite/WASM. From a checkout of this repository:

```bash
cd examples/school-management
npm install
npx ts-node app.ts
```

The [School example](examples/school-management/README.md)
exercises SQLite schema/bootstrap and generated application APIs against this
repository's local runtime. No external database server or generator is needed
to run the retained generated example. Use only the example's test database;
reset/repeated-run behavior is documented in its README.

## Use the published runtime

Current documented runtime: **0.3.0**. Keep domain-library and runtime
versions compatible; regenerate older libraries when their provider or graph
adapter SPI has changed.

```bash
npm install @teaql/teaql@0.3.0
```

Use scoped imports such as `@teaql/teaql` or
`@teaql/teaql/sql/sqlite`. The default entry point is driver-free; choose only
the required profile and install its optional driver. Browser SQLite defaults
to memory; OPFS is an explicit persistence choice.

Generation is a separate service; see the [Agent Kit](https://github.com/teaql/teaql-agent-kit)
for producing the application-specific library and workspace. Repository examples
use local source; isolated released-package regression is a separate gate.

## Supported scope

TypeScript supports browser/TFP, Node SQL, Expo SQLite and browser SQLite/WASM profiles. The browser is not a trusted server authorization boundary or a backend key store. Peggy parses a controlled query AST; it does not execute arbitrary JavaScript with eval or new Function.

One semantic model can produce language-native applications across
[Java](https://github.com/teaql/teaql-java),
[Rust](https://github.com/teaql/teaql-rs),
[TypeScript](https://github.com/teaql/teaql-ts),
[Go](https://github.com/teaql/teaql-golang),
[Swift](https://github.com/teaql/teaql-swift),
[.NET](https://github.com/teaql/teaql-dotnet) and
[Python](https://github.com/teaql/teaql-python).
That does not imply identical APIs, providers or complete cross-language feature parity.
The semantic model defines business objects, fields, relationships and states;
it is not the language model used by a coding agent.
The [conformance matrices](https://github.com/teaql/teaql-conformance)
distinguish implemented source, executed examples, artifact verification and release.

## Verification and customization

```bash
npm test -- --runInBand
bash scripts/verify-examples.sh
```

The full example gate is the acceptance entry point for local runtime changes.
External-provider tests need their configured services; skips are not live-provider
evidence. A committed-operation error after audit delivery failure must not be
retried as if the business transaction rolled back.

Install application-owned policies, ID/business-ID services, logging sinks,
transports and other supported SPIs through trusted runtime/Context setup.
Request JSON is not allowed to replace those trusted capabilities.

- [Runtime guide: modules, SPI and advanced verification](RUNTIME_GUIDE.md)
- [Runtime profiles](RUNTIME_GUIDE.md#runtime-profiles)
- [Browser SQLite example](examples/browser-sqlite/README.md)
- [Facet example](examples/facet-trace/README.md)
- [Trace Chain example](examples/trace-chain/README.md)
- [Binary object storage and temporary S3 URLs](examples/object-storage/README.md)

## Safe troubleshooting

Default diagnostics do not authorize plaintext sensitive data. Controlled
debugging requires the exact acknowledgement below and any sensitive sink
required by the runtime:

```bash
export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
```

Debug output is explicitly labeled. Credentials and unknown bindings remain
protected; the flag does not erase old files or govern application/driver
prints outside TeaQL. Restrict access and retention, then unset it and restart.
See the [runtime guide](RUNTIME_GUIDE.md) for log switches and extension details.