Seven-Language Documentation Coverage
This matrix measures whether a reader can learn and use TeaQL in their chosen language. Runtime PASS counts and page counts do not measure that outcome. The review on 2026-10-28 found an editorial gap: every language had runnable Order sources and extensive School excerpts, but no dedicated ordered Order tutorial; debugging pages mostly explained observability setup. The language overview also still described Order execution as unrecorded.
This documentation pass turns the retained examples into a first-edit tutorial, a task-oriented API reference, native troubleshooting tables and advanced line-removal/state/version-conflict recipes, plus export/retained-ID/summary walkthroughs, plus v1.1 buyer/tenant isolation and trusted-session boundaries. It reuses the existing model, Assist, application code and dated receipts. It adds no model submission, generation, runtime change or stress campaign.
Coverage definitions
| Label | Reader-facing acceptance |
|---|---|
| Documented | An entry link leads to the steps, prerequisites, native call/result shape, expected behavior and a recovery path for the named task. This is a documentation status, not a new execution PASS. |
| Partial | Relevant explanation or executable evidence exists, but the reader still has to assemble a complete recipe or supply retained local artifacts. |
| Planned | A proposed ecosystem integration has no corresponding completed tutorial/execution claim in this path. |
A documented core path does not mean a language's whole API surface or production integration is complete. The following rows intentionally keep remaining gaps visible.
Current seven-language matrix
| Language | First Order read/edit tutorial | API usage and native result handling | Symptom → diagnosis → action | Existing deeper material | Release boundary retained |
|---|---|---|---|---|---|
| Java | Documented | Documented, shared decision guide | Documented | School excerpts, Java query/mutation/runtime deep dives | Core/isolation/stock published; lifecycle/soak JDBC workspace RELEASE PENDING. |
| Rust | Documented | Documented, shared decision guide | Documented | School excerpts, transactions, E expressions and native provider guides | Workspace pagination/advanced Order RELEASE PENDING; generator/Assist deployment marks retained. |
| TypeScript | Documented | Documented, shared decision guide | Documented | School excerpts, Node/browser separation and customization | Workspace delete/pagination/advanced Order RELEASE PENDING; nullable generator repair pending deployment. |
| Python | Documented | Documented, shared decision guide | Documented | School excerpts, async context/provider customization | Workspace pagination/advanced Order RELEASE PENDING. |
| Go | Documented | Documented, shared decision guide | Documented | School excerpts, expression packages, runtime infrastructure | Generator/runtime contract and pagination workspace RELEASE PENDING. |
| C# / .NET | Documented | Documented, shared decision guide | Documented | School excerpts, provider/connection and customization guides | Workspace condition-key/pagination/advanced Order RELEASE PENDING. |
| Swift | Documented | Documented, shared decision guide | Documented | School excerpts, value semantics, actor/provider customization | Recorded published 0.3.1 SQLite; application retained-ID adapter and generator qualifications remain scoped. |
The shared API guide explains Q versus E, loaded/null/NotLoaded state, complete relations versus previews, audit/transaction ownership, paging choices and analytic result carriers. Each language tutorial supplies the actual read, write and page excerpts. Each troubleshooting page explains native failure modes rather than requiring a reader to run all tests to understand an error.
Advanced Order mutation coverage
All seven now explain the three named operations, including their prerequisites, native write/error path, expected persisted result and recovery decision. The quoted code is from the retained 17-case core application; the earlier P1 and completion receipts keep their own sources and qualification. This closes the writing gap for these recipes without creating a new execution claim.
| Language | Explicit line removal | State transitions | Version conflict | Scope |
|---|---|---|---|---|
| Java | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| Rust | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| TypeScript | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| Python | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| Go | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| C# / .NET | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
| Swift | Documented | Documented | Documented | Retained native SQLite/v1.0; original release markers preserved. |
Each removal recipe separates omission from deletion and preserves the competing
child in the rollback control. Each state recipe distinguishes pre-save
observedVersion from committed readback. Each conflict recipe explains native
classification and reload/reconcile/reject decisions, rather than retrying all
errors. Service-level automatic merge/retry policies remain application work.
Order query recipe coverage
All seven now explain continuous ID-ordered export, retained-ID page jumps and provider summaries. Each walkthrough identifies the nine- versus ten-order fixture, context/store lifetime, native plan/result carrier, expected empty and fallback behavior, and recovery from common setup/interpretation errors.
| Language | Continuous export | Retained-ID pages | Order summaries |
|---|---|---|---|
| Java | Documented | Documented | Documented |
| Rust | Documented | Documented | Documented |
| TypeScript | Documented | Documented | Documented |
| Python | Documented | Documented | Documented |
| Go | Documented | Documented | Documented |
| C# / .NET | Documented | Documented | Documented |
| Swift | Documented | Documented | Documented |
The recipes distinguish an overflow lower bound of 5 from exact total 8,
OFFSET_FALLBACK:CACHE_MISS from an unsuccessful export, and an empty grouped
list from an overall count-0/sum-null row. TypeScript's retained store and Swift's
invalidation adapter remain application-owned. The .NET condition-key repair
and every existing runtime/generator release marker remain qualified. Fixed-data
recipes do not establish snapshot isolation under concurrent writes, distributed
retention or an unbounded export implementation.
Order isolation tutorial coverage
All seven now explain the v1.0 → v1.1 model/library change, fresh database, server-owned native context and session resolver, pre-provider request gate, root/buyer-scoped lists/detail/items/aggregates/retained sets, narrow audited writes and native denial handling. These are application-facade tutorials built from the existing isolation model, scoped Assist and source-bound receipt.
| Language | Model and trusted context | Scoped reads / cache | Authorized writes and recovery |
|---|---|---|---|
| Java | Documented | Documented | Documented |
| Rust | Documented | Documented | Documented |
| TypeScript | Documented | Documented | Documented |
| Python | Documented | Documented | Documented |
| Go | Documented | Documented | Documented |
| C# / .NET | Documented | Documented | Documented |
| Swift | Documented | Documented | Documented |
A native context/store is kept alongside the trusted application session; the example does not rebind native tenant/actor for every session. Fixture keys and returned actor metadata do not establish authentication or audit-principal mapping. The eight-order fixture reuses buyer and Order numbers across scopes to make the need for both predicates visible. Detail/edit child-overflow guards and exact-one root guards are explained without inventing new migration/overflow executions.
Java and Swift retain their published isolation passes; the other five remain WORKSPACE PASS — RELEASE PENDING. Generator graph-save/relationship Assist repairs remain pending deployment. Real authentication, principal mapping, HTTP/TFP integration, live data backfill and revocation/concurrent-authorization contracts remain separate integration gaps; arbitrary Q/database access has no automatic authorization guarantee from these facade tutorials.
Gaps and writing order
| Priority / task | Current coverage across languages | Existing basis | Next document deliverable / need for verification |
|---|---|---|---|
| P0: first Order read/edit, null states, bounded pages, diagnostics and navigation | Documented for all seven in this pass. | Core 17-case receipt and immutable native application sources. | Maintain readable steps and exact excerpts. No additional native run is needed for wording or navigation edits. |
| P1: clean-machine, downloadable example packaging | Partial for all seven. Tutorials state the retained-workspace prerequisite; Quick Starts cover generation, but the offline reviewed package/cache is not a portable bundle in a fresh site checkout. | Generated app guides, recorded dependency manifests/toolchains and runner installation hooks. | Explain or package a selected example distribution and its dependency setup. Validate only that selected bootstrap path when the distribution is concrete; do not label it runnable before then. |
| P1: advanced Order mutation recipes | Documented for all seven: explicit deletion, state transitions and native stale-version recovery, linked in the task matrix above. | Existing P1/completion receipts and current source-bound core functions. | Maintain the transaction/error distinctions and seed-based expectations; broader service retry/merge policy remains outside the console recipe. |
| P1: export, retained IDs and summaries | Documented for all seven, with separate fixture setup, native plans, retained-store lifecycle, aggregate carriers and troubleshooting. | Existing pagination/insights receipts and source-bound native applications. | Maintain the native API/result differences and source excerpts. Production streaming, concurrent-write snapshot guarantees and distributed stores remain separate integration work. |
| P1: buyer/tenant isolation teaching | Documented for all seven: v1.1 ownership model, application-owned trusted sessions/context, scoped reads/aggregates/cache, narrow edits and recovery. | Existing isolation model, scoped Assist, native facades and dated receipt. | Maintain native predicate/save differences and boundaries. A v1.0 buyer filter alone does not authorize a tenant. |
| P1: production authentication and live upgrade integration | Partial for all seven: the console supplies a synthetic session resolver and fresh database only. | Explicit server-owned seam and exact-one root guard in the isolation facade. | Choose a service boundary and document real membership/principal wiring, migration/backfill and authorization-change behavior. Validate only concrete new integration claims. |
| P1: stock workflow teaching | Partial for all seven: shared contract and verified programs exist; reservation, rollback and replay recovery still need complete per-language tutorials. | Separate v1.2 stock model and receipt. | Walk through tenant sequence, inventory mutation and receipt ownership using the retained examples. |
| P1: runtime lifecycle recipes | Partial for all seven: diagnostic tables and existing fault/soak evidence are available; full service-integration lifecycle chapters remain separate. | Existing cancellation, provider/COMMIT and finite-soak receipts. | Document ownership, cancellation propagation and shutdown for one actual service boundary; keep console and HTTP/UI claims separate. |
| P2: framework/Apple UI/browser integrations | Planned in the Order path; Java/Rust have more ecosystem material elsewhere than the other five. | Advertised generator targets and existing stack guides, not an executed Order framework integration. | Choose a concrete integration task before implementation/verification. An advertised target or native console PASS cannot supply missing integration evidence. |
| P2: broad API reference depth | Partial: Java/Rust retain more detailed reference coverage. All seven now have the common Order task/return-shape reference, not a complete catalog of every generated method. | Retained scoped Assist and the public runtime/query contracts. | Fill lookup pages based on reader tasks and actual scopes; do not clone Java chapters by translating method casing. |
Most remaining P1 work is writing and organization with available evidence. Release publication gaps remain separate product/release work. Making page counts uniform or adding more case counts does not close those documentation gaps.
Evidence reuse rules
- Write the reader's intended task and identify the existing source/receipt that establishes its behavior.
- If that basis exists, explain the steps, arguments, result and failure path; preserve the exact language spelling and qualification.
- If the source and claim conflict or a concrete step lacks any basis, isolate the smallest operation needed to answer that question. Record only what it proves.
- Run documentation checks, source-excerpt checks and the site build. Rerun native programs only when the behavioral content or an unsupported concrete claim needs it.
The source-excerpt check reads the retained application files and verifies their hashes against the existing receipt. It does not inspect generated domain-library source, change receipt inputs, generate a model, compile a new application or relabel a workspace runtime as published.
npm run check:docs-contracts
npm run check:language-docs
npm run build
The release-scope guide and Order evidence table remain the authority for runtime qualification. School and every historical Order receipt stay immutable. This matrix is an editorial inventory with a review date, not a new compatibility certificate.