diff --git a/.agents/skills/asap-pr-authoring/SKILL.md b/.agents/skills/asap-pr-authoring/SKILL.md index 0b7f1e34e..58133ada8 100644 --- a/.agents/skills/asap-pr-authoring/SKILL.md +++ b/.agents/skills/asap-pr-authoring/SKILL.md @@ -8,29 +8,47 @@ description: Prepare concise ProjectASAP commits and pull-request descriptions. Organize commits at incremental logical boundaries. Do not include unrelated working-tree changes or rewrite existing history without explicit authorization. -Write the pull-request description top-down: +Write the pull-request description top-down, so a reviewer learns what changed +and where to look before reading details: -1. **Why**: the user, design, correctness, or MVP need. -2. **What**: the observable behavior and scope changed. -3. **How**: the core implementation or algorithm, without narrating every file. -4. **Key code interfaces added / modified**: the public interfaces the PR adds, - changes, or removes: types, functions, methods, traits, fields, enum - variants, module paths, CLI flags, and wire, file, or document formats. - Write "None" when no interface changes (for example, documentation or tests - only). Use this layout: +1. **Summary**: three lines: the problem, the change, and its effect, with one + concrete example and its numbers (the input, and the output, cost, or + latency before and after). +2. **Review guide**: the base branch and, for a stacked PR, its place in the + stack; the files or functions to read first; which parts are mechanical + (renames, moves, regenerated snapshots) and which need careful review. +3. **Behavior: before → after**: one end-to-end example, from what the user + writes (the workload entry or query with its requirements and data facts, or + the CLI or devtool invocation) to what they get back, before and after this + PR side by side. Say which user, design, correctness, or MVP need it serves. + This replaces separate Why / What / Before / After sections; do not repeat + it elsewhere. +4. **Interfaces**: the public interfaces the PR adds, changes, or removes: + types, functions, methods, traits, fields, enum variants, module paths, CLI + flags, and wire, file, or document formats. Removed interfaces appear as `-` + lines, so no separate deleted list is needed; under the block, give a + one-line reason for any removal whose reason is not obvious. Write "None" + when no interface changes (for example, documentation or tests only). Use + this layout: - Group by source file. Head each group with links to the files at a fixed commit, i.e. a permalink to the PR head or the merge commit, not a branch. - - Under each group, put one fenced code block in the source language. It - holds the real declarations copied from the diff: type definitions with - their fields or variants, and function, method and trait signatures with - bodies elided (`;` or `/* ... */`). Mark each change with a trailing - comment (`// new`, `// was X`, `// removed`). + - Under each group, put one fenced ```` ```diff ```` block. It holds the + real declarations copied from the PR's diff (not from memory): type + definitions with their fields or variants, and function, method and trait + signatures with bodies elided (`;` or `/* ... */`). Mark each line by its + first character: `+` for an added line, `-` for a removed line, and a + space for an unchanged context line (the enclosing `struct`, `enum`, + `impl` or `trait` header and closing brace, and unchanged members). A + changed item is its old line(s) with `-` followed directly by its new + line(s) with `+`; a rename is shown the same way. Do not add trailing + `// new`, `// was X` or `// removed` comments: the `+`/`-` marks say it. + A `///` line takes the mark of the declaration it explains (a space + above an unchanged member, `+` above an added or changed one). - Never collapse members into a comment such as `// ...` or `/* A, B, C unchanged */`; readers take a collapsed list for a removed - one. When a type is shown, list each of its variants or fields with a - one-line `///` and a marker (`// unchanged`, `// new`, `// was X`, - `// removed`), and put a `///` on the type itself saying whether the type - stays or is removed. + one. When a type is shown, list each of its variants or fields, unchanged + ones as context lines, and put a `///` on the type itself saying whether + the type stays or is removed. - Explain every interface. Above each declaration, write a short `///` (or the language's doc-comment form) saying what it is, what it is for, and when a caller uses it. For an enum variant or an error, say when it is @@ -50,7 +68,7 @@ Write the pull-request description top-down: Use real syntax and numbers, and check them by compiling and running the example (a test, an example binary or a devtool run) at the linked commit. See [references/key-code-interfaces-example.md](references/key-code-interfaces-example.md). -5. **Major algorithm changes**: for each algorithm the PR adds, replaces, or +5. **Algorithm changes**: for each algorithm the PR adds, replaces, or changes in a way that alters its results or cost (search, selection, pruning, sizing, accuracy composition, cost model, scheduling, execution kernels), write a short subsection: @@ -68,23 +86,28 @@ Write the pull-request description top-down: - **Assumptions and limits**: when the algorithm does not apply or falls back, and what it deliberately leaves out. Write "None" when the PR changes no algorithm (for example, a rename, - documentation, tests, or plumbing only). Keep **How** as the overview and put - the algorithmic detail here. -6. **Before this PR**: the previous end-to-end behavior, limitation, failure - mode, architecture, or workflow. -7. **After this PR**: the new end-to-end behavior and what users, developers, or - operators can do differently. -8. **Verification**: focused tests and applicable end-to-end evidence. - -Include a compact before/after example, screenshot, or diagram when it provides -real evidence or makes behavior easier to understand. For significant design -changes, summarize architectural decisions and alternatives. + documentation, tests, or plumbing only). Keep **Summary** as the overview and + put the algorithmic detail here. +6. **Decisions and open questions**: + - **Needs reviewer decision**: each open question and each new public + interface awaiting approval, with its full definition and a concrete + example. Keep an item here until the reviewer answers it. + - **Decided**: each consequential decision with its date, the choice, and + the rejected alternatives; move an item here when it is answered. + Write "None" when there are neither. +7. **Verification**: a table with one row per test scope (crate, suite, or + command): passed / failed / ignored, newly failing compared with the base, + and notes. Give each new test a one- or two-line behavioral purpose, and add + the end-to-end evidence (CLI output, snapshot changes with old → new numbers, + measurements). +8. **Follow-ups**: linked issues, known limitations, and what the PR + deliberately leaves out. Use the evidence form appropriate to the change: screenshots for visual output, execution examples for behavior, measurements for performance, or diagrams for architecture. Explicitly mark an evidence type as not applicable instead of fabricating it. -State limitations and follow-up work explicitly. Never fabricate screenshots, +Never fabricate screenshots, test results, measurements, or human approval. Creating or publishing a commit or PR still requires user authorization. diff --git a/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md b/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md index fdb14c7a8..e00ac3fc0 100644 --- a/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md +++ b/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md @@ -1,121 +1,125 @@ -# Example: Key code interfaces section +# Example: Interfaces section An excerpt from ASAPPlanner #715 (HLL sized from (ε, δ)) in the expected layout: -links per file group at a fixed commit, real declarations with every member -listed and marked, a `///` on every interface, and an end-to-end usage example +links per file group at a fixed commit, real declarations in a `diff` block with +every member listed (`+` added, `-` removed, a space for unchanged context, a +changed item as its `-` old line then its `+` new line), a `///` on every interface, and an end-to-end usage example whose every variable is commented and whose numbers come from running it. -## Key code interfaces added / modified +## Interfaces [`crates/types/src/post_asap/sketch.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/types/src/post_asap/sketch.rs) -```rust -/// Concrete parameters of one sketch instance; equality compares the built shape. -/// The type stays; this PR adds a field to `Hll` and `Kmv`. -pub enum SketchParams { - /// A UnivMon universal sketch (frequency moments, entropy, distinct count). - UnivMon { // unchanged - /// Top-k heap entries per layer. - heap_size: u32, // unchanged - /// Rows of each layer's Count Sketch. - sketch_rows: u32, // unchanged - /// Columns of each layer's Count Sketch. - sketch_cols: u32, // unchanged - /// Number of sampling layers. - layers: u8, // unchanged - /// The δ the heap was sized for when it answers a distinct count; None = no distinct guarantee. - distinct_failure_probability: Option, // unchanged - }, - /// A KLL quantile sketch. - Kll { // unchanged - /// Compactor capacity. - k: u32, // unchanged - /// The δ `k` was sized for when below 0.01; None = the empirical 99% calibration. - failure_probability: Option, // unchanged - }, - /// A Count-Min sketch. - Cms { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - }, - /// A HyperLogLog distinct-count sketch. - Hll { // unchanged variant; gains relative_error - /// `m = 2^precision` registers. - precision: u8, // unchanged - /// The relative error `precision` was sized for: its guarantee's error bound, - /// at which its failure probability is evaluated. - #[serde(default, skip_serializing_if = "Option::is_none")] - relative_error: Option, // new: the ε precision was sized for; None = RSE 1.04/√m; ignored by equality - }, - /// A DDSketch relative-error quantile sketch. - DDSketch { // unchanged - /// Relative accuracy of each bucket. - alpha: f64, // unchanged - }, - /// A Count-Min sketch with a top-k heap. - CmsWithHeap { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - /// Heap entries. - heap_size: u32, // unchanged - }, - /// A KMV (k minimum values) distinct-count sketch. - Kmv { // unchanged variant; gains relative_error - /// The number of smallest hashes kept. - k: u32, // unchanged - /// The relative error `k` was sized for: its guarantee's error bound, at which - /// its failure probability is evaluated. - #[serde(default, skip_serializing_if = "Option::is_none")] - relative_error: Option, // new: the ε k was sized for; None = RSE 1/√(k-2); ignored by equality - }, - /// A Theta distinct-count sketch. - Theta { // unchanged - /// Nominal entries. - k: u32, // unchanged - }, - /// A Count Sketch. - CountSketch { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - }, - /// A Count Sketch with a top-k heap. - CountSketchWithHeap { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - /// Heap entries. - heap_size: u32, // unchanged - }, -} +```diff + /// Concrete parameters of one sketch instance; equality compares the built shape. + /// The type stays; this PR adds a field to `Hll` and `Kmv`. + pub enum SketchParams { + /// A UnivMon universal sketch (frequency moments, entropy, distinct count). + UnivMon { + /// Top-k heap entries per layer. + heap_size: u32, + /// Rows of each layer's Count Sketch. + sketch_rows: u32, + /// Columns of each layer's Count Sketch. + sketch_cols: u32, + /// Number of sampling layers. + layers: u8, + /// The δ the heap was sized for when it answers a distinct count; None = no distinct guarantee. + distinct_failure_probability: Option, + }, + /// A KLL quantile sketch. + Kll { + /// Compactor capacity. + k: u32, + /// The δ `k` was sized for when below 0.01; None = the empirical 99% calibration. + failure_probability: Option, + }, + /// A Count-Min sketch. + Cms { + /// Counters per row. + width: u32, + /// Rows. + depth: u32, + }, + /// A HyperLogLog distinct-count sketch. + Hll { + /// `m = 2^precision` registers. + precision: u8, ++ /// The relative error `precision` was sized for: its guarantee's error bound, at which ++ /// its failure probability is evaluated. None = RSE 1.04/√m; ignored by equality. ++ #[serde(default, skip_serializing_if = "Option::is_none")] ++ relative_error: Option, + }, + /// A DDSketch relative-error quantile sketch. + DDSketch { + /// Relative accuracy of each bucket. + alpha: f64, + }, + /// A Count-Min sketch with a top-k heap. + CmsWithHeap { + /// Counters per row. + width: u32, + /// Rows. + depth: u32, + /// Heap entries. + heap_size: u32, + }, + /// A KMV (k minimum values) distinct-count sketch. + Kmv { + /// The number of smallest hashes kept. + k: u32, ++ /// The relative error `k` was sized for: its guarantee's error bound, at which ++ /// its failure probability is evaluated. None = RSE 1/√(k-2); ignored by equality. ++ #[serde(default, skip_serializing_if = "Option::is_none")] ++ relative_error: Option, + }, + /// A Theta distinct-count sketch. + Theta { + /// Nominal entries. + k: u32, + }, + /// A Count Sketch. + CountSketch { + /// Counters per row. + width: u32, + /// Rows. + depth: u32, + }, + /// A Count Sketch with a top-k heap. + CountSketchWithHeap { + /// Counters per row. + width: u32, + /// Rows. + depth: u32, + /// Heap entries. + heap_size: u32, + }, + } ``` [`crates/asap-aware-mapping/src/accuracy/estimators/hll.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/asap-aware-mapping/src/accuracy/estimators/hll.rs) -```rust -/// Pass 1's classic HLL precision for relative error `eps` at failure probability -/// `delta`, without data; plan selection later enlarges it for the source's bound. -pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8; // was hll_precision(eps) -/// Classic HLL's distinct-count guarantee over `source`'s own rows, with δ left -/// symbolic in the source's distinct bound; `None` for a precision outside the contract. -pub(crate) fn classic_guarantee( - precision: u8, - relative_error: Option, // new parameter - source: &str, -) -> Option; -/// The failure probability given the source's distinct bound; 1 (no certificate) -/// outside the contract's range. Plan selection calls it to bind the symbol. -pub(crate) fn classic_failure_probability( - precision: u8, - relative_error: f64, // new parameter - max_distinct: u64, -) -> f64; +```diff + /// Pass 1's classic HLL precision for relative error `eps` at failure probability + /// `delta`, without data; plan selection later enlarges it for the source's bound. +-pub(crate) fn hll_precision(eps: f64) -> u8; ++pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8; + /// Classic HLL's distinct-count guarantee over `source`'s own rows, with δ left + /// symbolic in the source's distinct bound; `None` for a precision outside the contract. +-pub(crate) fn classic_guarantee(precision: u8, source: &str) -> Option; ++pub(crate) fn classic_guarantee( ++ precision: u8, ++ relative_error: Option, ++ source: &str, ++) -> Option; + /// The failure probability given the source's distinct bound; 1 (no certificate) + /// outside the contract's range. Plan selection calls it to bind the symbol. +-pub(crate) fn classic_failure_probability(precision: u8, max_distinct: u64) -> f64; ++pub(crate) fn classic_failure_probability( ++ precision: u8, ++ relative_error: f64, ++ max_distinct: u64, ++) -> f64; ``` Usage, end to end: one SQL distinct count with ε = 0.05 and δ = 0.01, planned diff --git a/.github/PULL_REQUEST_TEMPLATE/projectasap.md b/.github/PULL_REQUEST_TEMPLATE/projectasap.md index 71c28d6ea..4c268119e 100644 --- a/.github/PULL_REQUEST_TEMPLATE/projectasap.md +++ b/.github/PULL_REQUEST_TEMPLATE/projectasap.md @@ -1,29 +1,39 @@ -## Why +## Summary -Why is this needed from the user, design, correctness, or MVP perspective? +Three lines: the problem, the change, and its effect, with one concrete example +and its numbers (for example, the workload or input and the cost, latency, or +output before and after). -## What +## Review guide -What observable behavior and scope does this PR change? +- Position: the base branch, and for a stacked PR its place in the stack. +- Reading order: the files or functions to read first. +- Mechanical parts (renames, moves, regenerated files) versus the parts that + need careful review, named by file or function. -## How +## Behavior: before → after -What is the core algorithm, interface, or design decision? Keep this top-down. +One end-to-end example from what the user writes (query, requirements, data +facts, or CLI call) to what they get back, before and after this PR side by +side. Include the user, design, correctness, or MVP need it serves. -## Key code interfaces added / modified +## Interfaces Group by source file, with links to the files at a fixed commit. Under each group, -put one fenced code block holding the real declarations: types with every field -or variant listed (never collapsed into `// ...`), and function/method/trait -signatures with bodies elided. Mark every member (`// unchanged`, `// new`, -`// was X`, `// removed`), say on each type whether it stays or is removed, and -explain each interface in a short doc comment: what it is, what it is for, and when +put one fenced `diff` block holding the real declarations from the diff: types +with every field or variant listed (never collapsed into `// ...`), and +function/method/trait signatures with bodies elided. Start each line with `+` +(added), `-` (removed) or a space (unchanged context); show a changed item as +its `-` old line followed by its `+` new line. Say on each type whether it stays +or is removed, and explain each interface in a short doc comment: what it is, what it is for, and when it is used or produced. End with an end-to-end usage example: from what the user writes (query, requirements, data facts, or CLI call), through where this PR's interfaces are called, to what the user gets back, with every variable commented and the numbers checked by running it. Write "None" if no interface changes. +Removed interfaces appear as `-` lines; give a one-line reason under the block +for any removal whose reason is not obvious. -## Major algorithm changes +## Algorithm changes For each algorithm this PR adds, replaces, or changes (search, selection, pruning, sizing, accuracy composition, cost model, scheduling, execution @@ -33,45 +43,30 @@ or guarantee and the tests that check it; time and memory complexity before and after, with a measured number when available; and assumptions, limits, and fallbacks. Write "None" if no algorithm changes. -## Before this PR +## Decisions and open questions -Describe the previous end-to-end behavior, limitation, failure mode, -architecture, or workflow. +- **Needs reviewer decision**: each open question and each new public interface + awaiting approval, with its full definition and a concrete example. +- **Decided**: each consequential decision with its date, the choice, and the + rejected alternatives. -## After this PR - -Describe the new end-to-end behavior and what users, developers, or operators -can do differently. - -## Evidence - -Provide the appropriate evidence: execution example, screenshot for visual -output, before/after measurement for performance, or diagram for architecture. -Mark non-applicable forms explicitly; do not fabricate evidence. +Write "None" when there are neither. ## Verification -- Unit tests: -- End-to-end tests: -- Other checks: - -Give each new test a one- or two-line behavioral purpose. - -## Snapshot changes - -For each changed file under `crates/devtools/tests/corpus_snapshots/` or -`crates/devtools/tests/sketch_plan_snapshots/`: the query or workload and why -its plan changed. Write "None" if no snapshot changed. See -[planner snapshots](../../docs/develop_docs/planner-snapshots.md). - -## Architectural decisions +| Scope | Passed / failed / ignored | Newly failing vs base | Notes | +| --- | --- | --- | --- | +| | | | | -List consequential decisions and rejected alternatives, or state why this is not -applicable. +Give each new test a one- or two-line behavioral purpose. Add the evidence the +change calls for: an execution example, a screenshot for visual output, a +before/after measurement for performance, or a diagram for architecture. Mark +non-applicable forms explicitly; do not fabricate evidence. -## Limitations and follow-up +## Follow-ups -State known limitations, rollout concerns, and deliberately deferred work. +Linked issues, known limitations, rollout concerns, and what this PR +deliberately does not do. ## Human review — do not complete with an agent diff --git a/AGENTS.md b/AGENTS.md index abf1b2f7f..9d9a0a8f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,14 @@ # ProjectASAP agent policy - Work in a dedicated Git worktree unless the user explicitly says otherwise. +- Create the dedicated Git worktree inside the repository root at + `.worktrees/`. Do not create worktrees as sibling directories + outside the repository root. - Create new worktrees from `origin/main` unless another base is specified. - Fetch the base first, and never disturb an existing dirty working DAG. + Fetch the base first, and never disturb an existing dirty working tree. +- Do not use `git add -A` or other broad staging commands; stage only the files + relevant to the requested change. +- Do not amend commits unless the user explicitly asks you to. - Keep communication and generated prose concise. - Prefer the minimally complex implementation that satisfies the requirement. - Do not introduce a conceptual layer, abstraction, or public interface without @@ -22,14 +28,13 @@ - For correctness fixes, first establish a regression test that fails for the original behavior, then confirm it passes after the fix. - Commit at incremental logical boundaries when commits are requested. -- Keep pull-request descriptions top-down and concise. Explain why, what, and - how, and list the **Key code interfaces added / modified** (or "None") and the - **Major algorithm changes** (or "None"). - Explicitly describe **Before this PR** and **After this PR**, using an - end-to-end example, screenshot, measurement, or diagram appropriate to the - change. +- Keep pull-request descriptions top-down and concise, in the sections of the + `asap-pr-authoring` skill: **Summary**, **Review guide**, **Behavior: before + → after** (one end-to-end example), **Interfaces** (diff blocks, or "None"), + **Algorithm changes** (or "None"), **Decisions and open questions**, + **Verification**, and **Follow-ups**. - A PR that changes planner snapshots - (`crates/devtools/tests/corpus_snapshots/`) says under **Snapshot changes** + (`crates/devtools/tests/corpus_snapshots/`) says under **Verification** which queries changed and why; a person confirms the why. - Agents must not complete fields reserved for human judgment, approval, or attestation.