AGENTS.md@src/operator git:20260921.66d38e8A

Immutable. This exact content never changes and is served at /api/v1/blob/90593a318465c2c5.

# operator — Agent & Contributor Guide

Navigation map for `src/operator`. Repo-wide invariants:
[`.agents/architecture-invariants.md`](../../.agents/architecture-invariants.md).

`operator` connects frontend statements and writes to query, catalog, metasrv,
and datanodes. It owns statement dispatch, DDL task conversion, and region-level
insert/delete routing.

## Module map

| Area | Path | Entry point |
| --- | --- | --- |
| Statements | `src/operator/src/statement.rs`, `src/operator/src/statement/` | `StatementExecutor` and per-statement handlers |
| Inserts | `src/operator/src/insert.rs`, `src/operator/src/bulk_insert.rs` | Insert, auto-create/alter, routing, dispatch |
| Deletes | `src/operator/src/delete.rs` | Delete conversion and dispatch |
| Request conversion | `src/operator/src/req_convert.rs`, `src/operator/src/req_convert/` | Table/row/column requests to region requests |
| Region requests | `src/operator/src/region_req_factory.rs` | Region-level DDL/DML request construction |
| Procedures | `src/operator/src/procedure.rs` | Metasrv procedure administration |
| Flow | `src/operator/src/flow.rs`, `src/operator/src/statement/ddl.rs` | Flow requests and internal mode selection |

## Change coupling

- New statement kinds usually touch parser/AST handling, frontend permission
  and interception, executor dispatch, and sqlness cases.
- DDL task changes require matching `common-meta`, metasrv, recovery, and
  compatibility updates.
- Insert/delete conversion changes must cover both request formats, partition
  routing, and schema-on-write behavior.
- Flow creation changes must stay aligned with `src/flow/AGENTS.md` and
  `common-meta` flow metadata.

## Testing

```bash
cargo nextest run -p operator
cargo sqlness bare -t <case>
```

Check standalone and distributed routing when changing region dispatch.

Write admission uses fallible `write_meter!` calls in `Inserter::do_request`
and `handle_bulk_insert`, before flow side effects and datanode dispatch. Bulk
records carry row counts and the request channel with zero WCU. Validate both
the default `meter-macros/noop` build and active metering when changing this path.
Finite requests split internally use `admit_write` / `admit_row_insert_batches`
before dispatch. Their database-scoped `QueryContext` admission prevents a second
row debit while `do_request` still records WCU for the actual writes.