Skip to content

Commit e4cf777

Browse files
PingoLeeclaude
andcommitted
docs(agents): the querybuilder skill named a parameter type that never existed
`pormg-querybuilder-internals` called the bucketed collector `PormGPositionalParam` in its *Parameter routing* section and again in the maintenance checklist. That identifier appears nowhere in `src/` — the abstract type is `PormGSQLiteParam`, with `SQLiteParameterizedQuery` as its concrete subtype. Anyone reading the skill to understand #432 was handed a name they could not grep, in the exact section #432 rewrites. `test_alignment_sqlite.jl` carried the same ghost name in a comment. The checklist's "update `get_final_parameters` flatten order" entry now points at `_BUCKET_ORDER`, which is the single list both `get_final_parameters` and `detach_nested_run!` read — #432 made that genuinely single-sourced rather than two hand-written copies that must agree. Adds the rule the four nested-render sites now follow, so the next person editing this area does not have to rediscover it: a nested render does not pick a bucket. Its values are marked, lifted and re-emitted as one clause-ordered run at the parent's marker position, because binding order is not text order — a build binds joins last and renders them first, which is the difference the buckets exist to reconcile. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 6f247c3 commit e4cf777

1 file changed

Lines changed: 6 additions & 3 deletions

File tree

  • .github/skills/pormg-querybuilder-internals

.github/skills/pormg-querybuilder-internals/SKILL.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,13 @@ For positional backends, preserve bucket semantics and flatten order. The bucket
4141

4242
`:cte → :select → :update → :join → :where → :having`
4343

44+
**A nested render does not pick a bucket (#432).** An `Exists(...)`, a projected `Subquery(...)` or an `__@in` subquery renders inside the PARENT's clause, so its values are marked, lifted and re-emitted as one clause-ordered run at the parent's marker position (`nested_parameter_mark` / `detach_nested_run!`), with `own_contexts=true` so the inner build files its values under its own clauses first. Binding order is not text order: a build binds joins last and renders them first, which is what the buckets exist to reconcile.
45+
4446
Parameter collector model:
4547

4648
- `AbstractPormGParam`: base abstraction for all collectors
4749
- `PormGPostgresParam`: linear collector for `$1`, `$2`, ... placeholders
48-
- `PormGPositionalParam`: bucketed collector for positional `?` placeholders
50+
- `PormGSQLiteParam`: bucketed collector for positional `?` placeholders (concrete type `SQLiteParameterizedQuery`)
4951

5052
When changing parameter behavior, verify:
5153

@@ -54,7 +56,7 @@ When changing parameter behavior, verify:
5456
- parent and subquery inheritance behavior
5557
- HAVING alias promotion placement
5658
- custom join parameter routing into the join bucket
57-
- flattening through `get_final_parameters(::PormGPositionalParam)` in SQL-clause order
59+
- flattening through `get_final_parameters(::PormGSQLiteParam)` in SQL-clause order
5860

5961
Query-building context rules:
6062

@@ -235,7 +237,8 @@ When introducing a new parameterized SQL clause or changing clause order, update
235237

236238
- bucket struct fields in `parameters.jl`
237239
- `set_context!` call sites in builder modules
238-
- `get_final_parameters` flatten order
240+
- `_BUCKET_ORDER` in `parameters.jl` — the single list both `get_final_parameters` and
241+
`detach_nested_run!` (#432) read; there is no second copy to keep in sync
239242
- unit coverage in the canonical alignment tests
240243
- integration coverage if the behavior is user-visible
241244

0 commit comments

Comments
 (0)