Issue #114: meta::column and the statement’s row type

Open and answer this issue on GitHub.

language, libraries, ready · opened 2026-09-30 · updated 2026-10-06 · 2 comments

Step 1 of ADR-143 §5. A grammar declares a result column with meta::column(name, type), the third and last intrinsic of the hybrid binding; the compiler derives the statement’s row type from the declared columns, as it derives the parameter type from the holes. Today a dsl block’s holes come from a scan of the body text (crates/nikaia/src/dsl.rs, which its own note calls an approximation); meta::parameter waits on the same machinery.

The harness it waited on is built (ADR-177: the grammar’s generated parser is compiled and run during the build). What comes back must be a flat list of declared columns and parameters, one of the five shapes that cross.

Steps 1 and 3 are one piece of work with ADR-254: the row type cannot be run without an execute, and the connection is the statement’s subject.

Comments

keywan-ghadami, 2026-10-06

Brought up to date: decided in the 2026-10-06 round (0.0.519, 9d47c62)

State before

• The records this issue cites, ADR-143 and ADR-254, are merged into ADR-299.
• Nothing of meta::column / meta::parameter / meta::capture exists in the compiler. dsl.rs still finds holes by scanning the text.
• Two questions were open and blocked building:
  1. How a grammar writes a type as an argument. Types are not values in Nikaia, and there are no type arguments at a call.
  2. Column names that cannot be fields. For example duplicates from a join, or "created-at".

How it was decided

• The owner first asked how build time handles types today. In every existing mechanism the type is written in the source and build time only produces values of it: comptime (ADR-287/311), reflection (ADR-304: field.name, field.of(v), no field.type), and grammar runs (ADR-177). meta::column is the first channel that goes from data to a type.
• The owner then asked whether ADR-304’s reasons forbid this. They do not: ADR-304 answers how to read a type’s shape, and rejects macros, string mixins and anytype. Nothing in it is about creating a type from data. The relevant principle is that a message must point at something someone wrote, and D4 of the new record keeps it.
• SQL needs no exception. The compiler already builds a DSL’s parameter struct from data (ADR-296 D5).
• Scalars only would be too narrow for JSON, Protobuf and GraphQL. So the owner chose a general description, built first for what SQL needs.

Decision in short

ADR-323:

• std::meta::Type is an enum: I64, I32, U8, U64, U32, F64, Bool, Text, Bytes, Maybe(Type), List(Type), Record(Vec[Field]), Named(ref String).
• meta::column(name, ty) and meta::parameter(name, ty) take one.
• The compiler writes the row and parameter types. Named is resolved where the block stands, and an unknown name gives NK1135.
• Messages name the block that declared a field, and --comptime prints each block’s type.

ADR-299 D12–D14:

• A row has one field per table (by alias or table name), plus a flat field per unique column name: u.a.id, u.name.
• When a name is shared (two columns, or a column and a table/alias), there is no flat field. Reading it gives NK1107, and the help names the qualified paths and AS.
• A name that cannot be a field is refused at the query, asking for AS. The compiler never renames.

Specification: Part II 10.5, Part III NK1107.

Not decided: whether two blocks with the same columns share one type, or each block gets its own (ADR-323 §6). Asked of the owner now; build each block its own type until answered (the safe direction).

To build (with #116; the row type cannot run without execute)

1. std::meta. Type and Field as above, in std’s Nikaia half. The recursive variant needs #97’s boxing; until then, build the scalars and Maybe, and mark the rest.
2. meta::column / meta::parameter in a grammar run. Callable from a grammar’s actions at build time. The calls are recorded and handed back beside the rule’s result, through ADR-177 D4’s crossing; Type values cross as enum variants (ADR-311).
3. Row type. For a dsl block whose grammar declared columns, write a struct: one field per table group holding that table’s columns, plus the flat fields from D12–D13. Map Text→String, Maybe(t)→t?, the numeric types and Bytes.
4. Parameter type. Replace dsl.rs’s text scan with the declared parameters, and feed ADR-296 D5’s struct with them.
5. Messages.
   • u.emial gives NK1107, naming the block (line) and the declared fields.
   • u.id when two tables have id gives NK1107, and the help names u.a.id, u.b.id and AS.
   • Named("Nope") gives NK1135 at the block, naming the grammar.
6. --comptime prints the row and parameter types of each block.
7. Tests, with a minimal test grammar (no real SQL needed): a grammar that declares two columns and one parameter. Check field access, T? for Maybe, a duplicate name across two groups, and a refusal from the grammar for a bad column name.

---

Generated by Claude Code

keywan-ghadami, 2026-10-06

Decided: a block may name the struct its rows are

dsl … -> T { … } eod. The rules, all decided by the owner:

• columns match fields by name, and a struct field matches a table’s group;
• strict by default, with extra_columns / missing_fields, which belong to the compiler;
• a NULL goes only into T?, and a NULL at run time is a named error;
• Shared[T] fields are refused until #475.

Records: ADR-299 D15-D19, Part II 10.5, NK1218-NK1223. Build: #477.

Still open: a column of one number type into a field of another.

---

Generated by Claude Code

Back to Open Issues