Review comments on the docs in docs/. Grouped by file, with line numbers.
docs/design.md
- L20 — Give an example of what "language's own native representation" means.
- L20 — The "L1 - query language" section title is ambiguous: unclear whether "query language" describes the input of L1, the output of L1, or what L1 does. Same ambiguity applies to the other layer section titles.
- L51 — Unclear what "column references vs schema positions" means.
- L80 — "Deployment here refers to ..." — move term definitions like this out to a separate glossary section instead of inline.
- L85 — What does "row identity" mean, and how does it relate to cross-query sharing?
- L99 — This could be written much more readably, e.g.: "This layer decides whether to use summaries for an intent. If yes, what summaries to use and how. This includes picking a summary family to use (link to sketch kind in asap_sketchlib) and its configuration parameters. ..."
- L120 — Claims it is assigning each
piece node of a summary-bound L4 plan to physical execution. This is contradicted a few lines later, which says there is no planner, just an interface.
- L150 — "summary-bound plan" or "summary-bound physical plan"? Terms must be consistent — assuming this refers to L5, not L4?
- L152 — Unclear what purpose this sentence serves: "Reality can diverge from the plan in ways planning time never sees."
docs/l1-query-language.md
- L19 — What does this subsection title mean?
- L24 — Unclear what this sentence means.
- L28 — Why are we discussing L2 and L3 here?
- L46 — Same issue as L28.
- L54 — Very confusing — what is "the contract" referring to?
- L89 — Why are we discussing L3 here?
docs/l2-logical-plan.md
- General: it's unclear whether "L2" refers to an object or a process — is L2 the description of some IR, or the process of converting one IR into another? (Same ambiguity applies to the other layers.)
- L15 — Before this point, it's unclear what the output of this layer is.
- L22 — The open-vs-closed schema problem should be introduced explicitly with an example first, then explain how it's handled. Currently the problem statement and the handling are mixed together.
- L32 — What does "purely structural and total" mean?
docs/l3-intent-algebra.md
- L11 — What is the output of this layer?
- L44 — Unclear what the difference is between the "intent vocabulary" and "intent catalog" sections.
docs/l4-summary-bound-ir.md
- L12 — Why are we talking about execution here?
- L18 — Unclear what this means.
- L216 — Tree or DAG? Be precise.
Review comments on the docs in
docs/. Grouped by file, with line numbers.docs/design.md
piecenode of a summary-bound L4 plan to physical execution. This is contradicted a few lines later, which says there is no planner, just an interface.docs/l1-query-language.md
docs/l2-logical-plan.md
docs/l3-intent-algebra.md
docs/l4-summary-bound-ir.md