writeonce/docs/stories/language-runtime-database/09b-table-relations-query.md

Iteration 9b — @table, relations, and language-integrated query

Format: fiberloom product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Inserted 2026-08-11, hence 9b rather than a renumber. It follows iteration 9 because a query surface needs tables that actually execute, and precedes iteration 10 because service blocks will want to return query results.

Spec exists (2026-08-15): 2026-08-15-table-relations-query-design.md settles the three forks recorded in Info below (kept as the decision record): the SQL/Cypher layer is superseded as the program surface, the syntax is a compiler-desugared comprehension, and the references contribute vocabulary + semantics (System.Linq) and execution + integrity vocabulary (PostgreSQL, surveyed with the spec). Plan: 2026-08-15-employee-relations-query.md.

Goals

• @table graduates from a parsed-but-inert annotation into the declaration that makes a class persistent: named storage, declared indexes, and a primary identity.
• Relations become first-class and typed — ref T foreign keys, backlink inverses, and multi collections — so a developer navigates their data by following fields rather than by hand-writing joins.
• Queries are written in the language, checked by the compiler: a LINQ-shaped operator vocabulary (filter, project, join, group, order, aggregate) over tables and relations, with the result's type inferred and every column reference resolved at compile time. A typo in a field name is a compile error, not a runtime one.

Acceptance Criteria

• What to achieve?
  • Given a class annotated @table with a declared index,
  • when the program is compiled and run,
  • then its instances persist through the engine, the index is built, and a query that could use the index does use it — demonstrated, not assumed.
• What to achieve?
  • Given two classes related by ref with a backlink inverse,
  • when a query navigates the relation in either direction,
  • then it typechecks with the related class's field set in scope, and navigating a field that does not exist is a compile error naming it.
• What to achieve?
  • Given a query whose result shape is a projection rather than a whole row,
  • when it is assigned or returned,
  • then its type is the projected shape — so a later use of a column the projection dropped is a compile error.
• What to achieve?
  • Given a query written against tables,
  • when the compiler lowers it,
  • then it becomes engine operations, not a string handed to a parser at runtime — provable by disassembly, and by the absence of any SQL-text construction in the emitted image.
• What to achieve?
  • Given the ecommerce sample's existing relational shapes (Order.user: ref User, User.orders: backlink Order.user, line-item collections),
  • when they are expressed as queries in this surface,
  • then each produces the same results as the equivalent hand-written query, and the sample's README records anything that could not be expressed.

Out Of Scope

• Cross-shard queries and distributed joins — iteration 8 owns ownership movement, and a query spanning shards is a 2PC concern recorded with the database track.
• LIVE subscriptions over queries. The subscription registry is the HTTP/UI track's; a query that pushes updates is a later composition of the two.
• Migrations. Changing a @table class's shape is the blue-green spec's additive-only differ (iteration 12), not this iteration's problem.
• Query optimisation beyond index selection. A cost-based planner is a separate, much later concern; this iteration must only prove that declared indexes are used.

Info

Three open forks the spec has to settle. Each is a real decision, and I have a leaning on all three but no mandate.

1. Where does this leave the existing SQL + Cypher query layer? docs/runtime/database/02-wo-language.md specifies a two-layer design — a schema layer plus a query layer of literal SQL and Cypher with five "fixed-glue" rules. A language-integrated surface either replaces that layer, sits beside it, or becomes the only surface with SQL retained purely as an export format. Replacing it is the coherent choice and also the most disruptive, because that document is normative and the wo-db C++ prototype implements the SQL/Cypher grammar it describes.

2. There are no function values, so what is the syntax? LINQ-to-Objects is built on delegates: .Where(x => x.Age > 18) passes a lambda. writeonce has no function-value type, and the systems-track spec deliberately rejected closure builtins (map/filter/reduce) for exactly this reason. So the surface cannot be method-chaining-with-lambdas as written in C#. The realistic options are a comprehension syntax the compiler desugars (from o in orders where o.total > 100 select o.id), or method chaining whose "lambda" argument is a compiler-recognised expression form rather than a value. Either way the predicate is compile-time syntax, never a runtime closure — which is also what lets the whole query lower to engine ops.

3. What does the reference actually contribute? .dev/reference/dotnet-runtime/src/libraries/System.Linq/src/System/Linq/ (sparse checkout, added with this iteration) is the operator catalogue: read Where.cs, Select.cs, Join.cs, GroupBy.cs, OrderBy.cs for what each operator means and which edge cases it has to answer, and the *.SpeedOpt.cs files for how LINQ specialises when the source's shape is known statically — directly relevant, since writeonce knows every shape statically. What does not transfer is the machinery: IEnumerable iterator composition, delegates, and IQueryable's runtime expression trees, the last of which depends on reflection that principle 13 forbids outright. Take the vocabulary and the semantics; leave the plumbing.

Also relevant: @table(name:, index:) already parses today with known-key validation (WO-E102), the Rust runtime already ships secondary indexes and find_by behind that annotation, and ref T already classifies as a scalar id rather than a pointer — so the relational vocabulary partly exists and this iteration makes it mean something in the C stack.

Proposed Solution

• Brainstorm a spec first — done 2026-08-15; the spec settles all three forks and the plan exists (pointers in the header note). The fork-1 outcome for the record: language-integrated query is the only program surface; docs/runtime/database/02-wo-language.md's SQL/Cypher layer stays as design history and as the wo-db prototype's engine-semantics reference, never as syntax.
• The acceptance workload is a new sample: docs/examples/employee — Department/Employee with @unique, a composite index, a ref/ backlink pair, and a report mode that is one GROUP BY after another (headcount, avg/min/max salary by department). It is 9b's acceptance the way log-watcher was iterations 1–7's; the ecommerce query rewrite (the fifth criterion below) follows as its own step once employee is green.
• Study .dev/reference/dotnet-runtime's System.Linq operator set for the vocabulary, and docs/runtime/database/02-wo-language.md plus prototypes/wo-db/ for the semantics already committed to.
• Expect the work to span the front end (query syntax, relation typing, projection types), the emitter (lowering to engine operations rather than text), and the engine (index selection, relation traversal) — which is why it follows iteration 9 rather than preceding it.