<!-- ephemeral -->

# TypeScript Assist — Query `Customer Order`

Use the exact generated `Q.customerOrdersWithMinimalFields()`
entry point. Trusted runtime and policy state comes only from `UserContext`.

```typescript
import { Q } from './Q';
import { CustomerOrder } from './models/CustomerOrder';
import { SmartList, UserContext } from '../teaql-ts';

export async function queryCustomerOrderById(
    context: UserContext,
    entityId: string,
): Promise<SmartList<CustomerOrder>> {
    return Q.customerOrdersWithMinimalFields()
        .withIdIs(entityId)
        .orderByIdAscending()
        .limit(20)
        .comment('what: load the requested Customer Order row')
        .purpose('why: serve the authorized Customer Order view')
        .executeForList(context);
}
```

Compile and execute this source unchanged. Use only generated projection,
predicate, ordering, and relation-selection APIs. Missing or blank intent,
unknown fields, unbounded reads, and trusted-context inputs must fail. Use generated
relation loading rather than handwritten child-query loops; never guess a plural.


## Field-specific Query Assist

Use the canonical KSML field name from this list. Do not substitute a language member name, JSON name, or database column.

| KSML field | Type | Field help |
| --- | --- | --- |
| `id` | `id` | `typescript-assist-query/customer_order.id` |
| `customer` | `relation<customer>` | `typescript-assist-query/customer_order.customer` |
| `status` | `relation<order_status>` | `typescript-assist-query/customer_order.status` |
| `order_number` | `string` | `typescript-assist-query/customer_order.order_number` |
| `order_date` | `date` | `typescript-assist-query/customer_order.order_date` |
| `total_amount` | `number` | `typescript-assist-query/customer_order.total_amount` |
| `version` | `version` | `typescript-assist-query/customer_order.version` |

Generated reverse relations are derived from referencing KSML fields. Use their exact generated location for relation selection and access:

| Generated reverse relation | Child entity | Field help |
| --- | --- | --- |
| `order_item_list` | `order_item` | `typescript-assist-query/customer_order.order_item_list` |


---

## TeaQL seven-language assist contract

Apply the verified Rust semantic ceiling while using only the exact TYPESCRIPT generated and
runtime APIs. Discover APIs through the generated application AGENTS.md and progressive
model-aware Assist. Do not inspect generated domain-library source.

- Do not create plurals by appending `s` or `es`; use the centralized generated plural.
- Human and non-human entities use different generated predicate vocabularies. Preserve
  forms such as “who are active” and “whose email is”; never infer them from English.
- Configure filters, projection, paging, and other query options before `purpose(...)`.
  Comment may appear anywhere in the chain. Purpose enters the executable stage; execution
  requires both values, but comment does not have to immediately precede purpose.
- Every execute/list/stream and every save accepts exactly one context argument:
  `UserContext`. Name that argument `context`, never `runtime`; data services and global
  policy are injected when the context is built. Reserve `runtime` for process-level
  runtime ownership, provider/pool setup, and module assembly.
- Tenant, merchant, identity, permissions, request policy, purpose policy, hard limit,
  and continuous-page cursor policy come only from trusted context, never dynamic JSON or TFP.
- If the required operation is absent after current entity/action and required field
  Assist, stop that path and report MISSING_ASSIST. Do not guess an API or search the
  generated library as a fallback.
- Create each application-owned source file once. After its first compile attempt,
  repair only the smallest block identified by the exact compiler or test diagnostic.
  Preserve unrelated code; do not rewrite the complete file as an error-recovery loop.
- Before a repair that would replace more than 25% of an existing application file,
  stop and report LARGE_REWRITE_REQUEST with the file, exact diagnostic, reason, and
  estimated scope. Initial creation and model-driven regeneration are not repairs.

Capability: `query`.

- Use generated projection, relation, predicate, sort, and aggregate APIs; never
  concatenate application SQL or silently ignore an unsupported filter.
- Rows, record count, facets, and aggregates must share the same active filter.
- Add negative tests for missing purpose/comment and forbidden dynamic fields.

### Optional per-parent Top-N optimization

- Configure `topNProbeParentThreshold(threshold)` on the nested child request before its intent/execution
  stage. Use the field-specific relation Assist for the exact generated selector.
- Give the child a per-parent limit and deterministic ordering with an ID tie-breaker;
  bound the parent query separately. A single-parent detail query is not batch Top-N.
- Server providers default to a window query (`threshold = 0`). A positive threshold
  permits bounded probes only when the already-loaded parent count is at or below it;
  above it, use the window plan. SQLite uses its internal AlwaysProbe policy by default.
- Measure before opting in. Do not infer a threshold from table size or execute COUNT
  or statistics queries to choose a plan. Keep an index on foreign key + sort + ID.
- Inspect selected-plan, parent-count, per-parent-limit and probe-count telemetry.
  Runtime-managed probes are not application-owned N+1 loops; neither strategy changes
  authorization, loaded-state semantics or the required comment/purpose.