{"owner":"MaterializeInc","repo":"materialize","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Materialize\n\n## Skills\n\nCanonical agent skills in `.agents/skills/`. `.claude/skills` is compat symlink\nfor Claude Code. Check `mz-*` skill before tasks — encodes project conventions,\nsaves time.\n\nUse the `mz-test` skill before running ANY tests, even mid-task — the canonical\ncommands aren't the obvious ones (e.g. `bin/sqllogictest --optimized`, not\n`cargo build --bin sqllogictest`).\n\nUse the `mz-run` skill before building, running, formatting, or linting. `bin/fmt` and `bin/lint` are the canonical entry points, NOT `cargo fmt`, `rustfmt`, or a bare `cargo clippy`. `bin/environmentd`, not `cargo build --bin environmentd`.\n\nUse the `mz-commit` skill before `git commit`, `git push`, or `gh pr create`.\n\nUse the `mz-debug-ci` skill before the first `bk` or `gh pr checks` command, or when handed a Buildkite URL.\n\n## Code navigation\n\nFor operation flow tracing, read first:\n\n* `doc/developer/generated/flows.md` — maps operations (query lifecycle, source ingestion, MV creation, sink lifecycle, catalog DDL, timestamp selection, persist read/write, controller architecture) to `crate::module` paths in execution order.\n* `doc/developer/generated/<crate>/_crate.md` — per-crate overview: modules, key types, dependencies.\n* `doc/developer/generated/<crate>/<module>.md` — per-file docs.\n\n> **READ-ONLY: `doc/developer/generated/` is generated, not authored.**\n> The entire `doc/developer/generated/` tree is maintained exclusively by the\n> recurring documentation agent, which runs the `update-docs` skill/command.\n> That agent is the *only* session permitted to create, edit, or delete files\n> under this directory.\n>\n> In any other session: **treat `doc/developer/generated/` as read-only.** Use\n> it for navigation and context, but never edit, create, delete, or regenerate\n> files there — not even to \"fix\" something you noticed, and not as part of an\n> unrelated change. These files carry `source`/`revision` front-matter that the\n> recurring agent manages; hand edits desync that bookkeeping. If a generated\n> doc is wrong or stale, report it in your response rather than editing it, and\n> leave the correction to the `update-docs` agent. Do not stage or commit any\n> path under `doc/developer/generated/` unless you are explicitly running the\n> `update-docs` workflow.\n\n## Dependency management\n\n### Workspace dependencies\n\nAll third-party versions declared in `[workspace.dependencies]` in root\n`Cargo.toml`. Members use `dep.workspace = true` or\n`dep = { workspace = true, optional = true }`.\n\n* **Add new dep**: add to `[workspace.dependencies]` in root `Cargo.toml` first, then `dep.workspace = true` in member crate.\n* **Never inline version** in member `Cargo.toml` — `bin/lint-cargo` enforces.\n* **Update version**: change once in root `Cargo.toml`.\n* Cargo unifies features workspace-wide, so workspace declaration is union of all features across crates. Members just use `dep.workspace = true`.\n\n### Cargo.lock\n\nNever regenerate full Cargo.lock. When changing deps:\n\n* **Add dep or change features**: run `cargo check` — updates only what changed.\n* **Update specific crate**: `cargo update -p <crate>` (optional `--precise <version>`).\n* **Never bare `cargo update`** — bumps every semver-compatible dep, causes unrelated breakage from transitive changes.\n* **If lock regenerated**, diff before commit (`git diff Cargo.lock | grep '^[+-]version'`) and pin back unintended bumps with `cargo update -p <crate> --precise <old-version>`.\n\n### Licensing\n\nTwo files control license policy, **keep in sync**: `deny.toml` (`[licenses].allow`) and `about.toml` (`accepted`). New dep with new license not already allowed: add SPDX identifier to both.\n\n## Guidance\n\n* When designing specs or implementing features, preserve the full scope and\n  capability of the solution. Do not substitute dynamic or generative\n  approaches with hardcoded data, skip automation that a reference\n  implementation provides, or simplify away the parts that make a feature\n  robust and maintainable. If a reference codebase generates data from an\n  authoritative source, our implementation should do the same, not ship a\n  static snapshot. When you feel tempted to reduce scope or take a shortcut,\n  flag it to the user and workshop an alternative together rather than silently\n  downgrading the design.\n* When making code changes, run cheap checkers/linters and formatters before\n  reporting success and/or committing changes. For Rust, these would be\n  `bin/fmt` and `cargo check`.\n* When debugging CI or lint failures, start by reproducing the exact failing\n  command locally and reading its output. Do not run generic checks (clippy,\n  fmt, grep) in a shotgun approach.\n* We value simplicity and clear abstractions. We especially care about\n  designing the interfaces or boundaries between components well. This includes\n  components, traits, interfaces, modules, and crates.\n* In code comments or inline documentation, we value clearly described\n  contracts and assumptions.\n* In code comments, we don't like \"fluff\" comments, comments that describe what\n  code does when it is obvious from the code. Good code should be readable. It\n  _is_ okay to call out tricky parts of the code or \"nota benes\".\n* In code comments and code documentation we value concise but complete\n  comments.\n* In code comments and documentation, don't refer to potential previous states\n  of the code, or things like future PRs, try not to use chronology in there,\n  except when it's needed to explain why a certain thing behaves as it does and\n  we need to record that knowledge. In general comments need to stand on their\n  own and make sense from just looking at them and the code around it, not\n  previous changes.\n* Avoid em-dashes for structuring sentences in any prose: code comments, specs,\n  design docs, all of it. Restructure with full stops and commas instead. The\n  same goes for semicolons, though one is fine where splitting would mangle the\n  sentence.\n* Our guidance applies both when writing new code or designs, or when we notice\n  deviations in code or architecture that we are working on. At the same time,\n  we want to keep our changes minimal so it's good to call out deviations and\n  then we can decide together what to do about it.\n* Never put a side effect inside `debug_assert!` (or `debug_assert_eq!`, etc.).\n  The macro body compiles out whenever debug-assertions are off, which includes\n  `[profile.optimized]` (what `bin/environmentd` and mzcompose use) and\n  `[profile.release]`. Only `[profile.ci]` turns them on. A side effect written\n  there, for example `debug_assert!(map.insert(k, v).is_none())`, runs under\n  `cargo test` but silently vanishes in optimized and release builds, leaving\n  the logic it powered inert and profiler-blind. Bind the effect to a `let`\n  outside the assert, then assert on the bound value. Clippy's\n  `debug_assert_with_mut_call` catches `&mut self` receivers but not `&self` or\n  free-function side effects.\n* Never write vendor, customer, or account names into durable or user-facing\n  surfaces: committed code, comments, column comments, docs, specs, commit\n  messages, PR bodies, or test fixtures. Anything persisted to disk gets shared,\n  indexed, and outlives the context, so a name in it is a leak. Anonymize to the\n  technical pattern instead, for example \"a wide unfiltered LEFT JOIN driving a\n  freshness incident\" rather than who hit it. Names are fine in ephemeral chat,\n  not on disk.\n* Never use `std::collections::HashMap`/`HashSet` directly, `clippy.toml`'s\n  `disallowed-types` blocks it. Use `BTreeMap`/`BTreeSet` when iteration order\n  matters, or `mz_ore::collections::HashMap` for keyed-only access with no\n  iteration. Hash-order iteration is a real nondeterminism source, for example\n  an unstable order reaching plan output or persisted state, not a style nit.\n* A new feature flag should default off in production but default ON in the\n  test/CI configuration, so the new code path is exercised by sqllogictest,\n  testdrive, and optimizer goldens before it earns trust. Production safety and\n  test coverage are separate settings. Wire the override through\n  `system_parameter_default`: the `--system-parameter-default=NAME=VALUE` CLI\n  flag (env `SYSTEM_PARAMETER_DEFAULT`) for sqllogictest and environmentd\n  binaries, or `TestHarness::with_system_parameter_default` for Rust\n  integration tests.\n\n## Code comments\n\nSpecifics for code comments and documentation:\n\nSpend comments on the non-obvious: concurrency and async hazards (races,\nlease/handle expiry, values that must not be held across an await point),\nordering constraints (\"X must happen before Y, else Z\"), invariants whose\nviolation panics or corrupts data, restart/recovery semantics, the origin of\nmagic constants, and why the obvious alternative was not taken. Idiomatic code\n(match arms, iterator chains, getters, logging) needs none.\n\nA doc comment is the caller's contract: a one-sentence summary, then only the\ninvariants and semantics a caller must know. A self-evident public item needs\nonly that one line. Don't narrate the body in rustdoc (\"Phase 1 ... Phase\n2 ...\", or enumerating a flag's branches). Reasoning about how or why the code\nworks goes in an inline `//` at the decision point, or in a module-level `//!`\nwhen it is about how the pieces fit together. Document a struct field only when\nits meaning is subtle.\n\nMark counterintuitive gotchas with `NOTE:` and future work with `TODO:`.\n"},"files":{"AGENTS.md":"# Materialize\n\n## Skills\n\nCanonical agent skills in `.agents/skills/`. `.claude/skills` is compat symlink\nfor Claude Code. Check `mz-*` skill before tasks — encodes project conventions,\nsaves time.\n\nUse the `mz-test` skill before running ANY tests, even mid-task — the canonical\ncommands aren't the obvious ones (e.g. `bin/sqllogictest --optimized`, not\n`cargo build --bin sqllogictest`).\n\nUse the `mz-run` skill before building, running, formatting, or linting. `bin/fmt` and `bin/lint` are the canonical entry points, NOT `cargo fmt`, `rustfmt`, or a bare `cargo clippy`. `bin/environmentd`, not `cargo build --bin environmentd`.\n\nUse the `mz-commit` skill before `git commit`, `git push`, or `gh pr create`.\n\nUse the `mz-debug-ci` skill before the first `bk` or `gh pr checks` command, or when handed a Buildkite URL.\n\n## Code navigation\n\nFor operation flow tracing, read first:\n\n* `doc/developer/generated/flows.md` — maps operations (query lifecycle, source ingestion, MV creation, sink lifecycle, catalog DDL, timestamp selection, persist read/write, controller architecture) to `crate::module` paths in execution order.\n* `doc/developer/generated/<crate>/_crate.md` — per-crate overview: modules, key types, dependencies.\n* `doc/developer/generated/<crate>/<module>.md` — per-file docs.\n\n> **READ-ONLY: `doc/developer/generated/` is generated, not authored.**\n> The entire `doc/developer/generated/` tree is maintained exclusively by the\n> recurring documentation agent, which runs the `update-docs` skill/command.\n> That agent is the *only* session permitted to create, edit, or delete files\n> under this directory.\n>\n> In any other session: **treat `doc/developer/generated/` as read-only.** Use\n> it for navigation and context, but never edit, create, delete, or regenerate\n> files there — not even to \"fix\" something you noticed, and not as part of an\n> unrelated change. These files carry `source`/`revision` front-matter that the\n> recurring agent manages; hand edits desync that bookkeeping. If a generated\n> doc is wrong or stale, report it in your response rather than editing it, and\n> leave the correction to the `update-docs` agent. Do not stage or commit any\n> path under `doc/developer/generated/` unless you are explicitly running the\n> `update-docs` workflow.\n\n## Dependency management\n\n### Workspace dependencies\n\nAll third-party versions declared in `[workspace.dependencies]` in root\n`Cargo.toml`. Members use `dep.workspace = true` or\n`dep = { workspace = true, optional = true }`.\n\n* **Add new dep**: add to `[workspace.dependencies]` in root `Cargo.toml` first, then `dep.workspace = true` in member crate.\n* **Never inline version** in member `Cargo.toml` — `bin/lint-cargo` enforces.\n* **Update version**: change once in root `Cargo.toml`.\n* Cargo unifies features workspace-wide, so workspace declaration is union of all features across crates. Members just use `dep.workspace = true`.\n\n### Cargo.lock\n\nNever regenerate full Cargo.lock. When changing deps:\n\n* **Add dep or change features**: run `cargo check` — updates only what changed.\n* **Update specific crate**: `cargo update -p <crate>` (optional `--precise <version>`).\n* **Never bare `cargo update`** — bumps every semver-compatible dep, causes unrelated breakage from transitive changes.\n* **If lock regenerated**, diff before commit (`git diff Cargo.lock | grep '^[+-]version'`) and pin back unintended bumps with `cargo update -p <crate> --precise <old-version>`.\n\n### Licensing\n\nTwo files control license policy, **keep in sync**: `deny.toml` (`[licenses].allow`) and `about.toml` (`accepted`). New dep with new license not already allowed: add SPDX identifier to both.\n\n## Guidance\n\n* When designing specs or implementing features, preserve the full scope and\n  capability of the solution. Do not substitute dynamic or generative\n  approaches with hardcoded data, skip automation that a reference\n  implementation provides, or simplify away the parts that make a feature\n  robust and maintainable. If a reference codebase generates data from an\n  authoritative source, our implementation should do the same, not ship a\n  static snapshot. When you feel tempted to reduce scope or take a shortcut,\n  flag it to the user and workshop an alternative together rather than silently\n  downgrading the design.\n* When making code changes, run cheap checkers/linters and formatters before\n  reporting success and/or committing changes. For Rust, these would be\n  `bin/fmt` and `cargo check`.\n* When debugging CI or lint failures, start by reproducing the exact failing\n  command locally and reading its output. Do not run generic checks (clippy,\n  fmt, grep) in a shotgun approach.\n* We value simplicity and clear abstractions. We especially care about\n  designing the interfaces or boundaries between components well. This includes\n  components, traits, interfaces, modules, and crates.\n* In code comments or inline documentation, we value clearly described\n  contracts and assumptions.\n* In code comments, we don't like \"fluff\" comments, comments that describe what\n  code does when it is obvious from the code. Good code should be readable. It\n  _is_ okay to call out tricky parts of the code or \"nota benes\".\n* In code comments and code documentation we value concise but complete\n  comments.\n* In code comments and documentation, don't refer to potential previous states\n  of the code, or things like future PRs, try not to use chronology in there,\n  except when it's needed to explain why a certain thing behaves as it does and\n  we need to record that knowledge. In general comments need to stand on their\n  own and make sense from just looking at them and the code around it, not\n  previous changes.\n* Avoid em-dashes for structuring sentences in any prose: code comments, specs,\n  design docs, all of it. Restructure with full stops and commas instead. The\n  same goes for semicolons, though one is fine where splitting would mangle the\n  sentence.\n* Our guidance applies both when writing new code or designs, or when we notice\n  deviations in code or architecture that we are working on. At the same time,\n  we want to keep our changes minimal so it's good to call out deviations and\n  then we can decide together what to do about it.\n* Never put a side effect inside `debug_assert!` (or `debug_assert_eq!`, etc.).\n  The macro body compiles out whenever debug-assertions are off, which includes\n  `[profile.optimized]` (what `bin/environmentd` and mzcompose use) and\n  `[profile.release]`. Only `[profile.ci]` turns them on. A side effect written\n  there, for example `debug_assert!(map.insert(k, v).is_none())`, runs under\n  `cargo test` but silently vanishes in optimized and release builds, leaving\n  the logic it powered inert and profiler-blind. Bind the effect to a `let`\n  outside the assert, then assert on the bound value. Clippy's\n  `debug_assert_with_mut_call` catches `&mut self` receivers but not `&self` or\n  free-function side effects.\n* Never write vendor, customer, or account names into durable or user-facing\n  surfaces: committed code, comments, column comments, docs, specs, commit\n  messages, PR bodies, or test fixtures. Anything persisted to disk gets shared,\n  indexed, and outlives the context, so a name in it is a leak. Anonymize to the\n  technical pattern instead, for example \"a wide unfiltered LEFT JOIN driving a\n  freshness incident\" rather than who hit it. Names are fine in ephemeral chat,\n  not on disk.\n* Never use `std::collections::HashMap`/`HashSet` directly, `clippy.toml`'s\n  `disallowed-types` blocks it. Use `BTreeMap`/`BTreeSet` when iteration order\n  matters, or `mz_ore::collections::HashMap` for keyed-only access with no\n  iteration. Hash-order iteration is a real nondeterminism source, for example\n  an unstable order reaching plan output or persisted state, not a style nit.\n* A new feature flag should default off in production but default ON in the\n  test/CI configuration, so the new code path is exercised by sqllogictest,\n  testdrive, and optimizer goldens before it earns trust. Production safety and\n  test coverage are separate settings. Wire the override through\n  `system_parameter_default`: the `--system-parameter-default=NAME=VALUE` CLI\n  flag (env `SYSTEM_PARAMETER_DEFAULT`) for sqllogictest and environmentd\n  binaries, or `TestHarness::with_system_parameter_default` for Rust\n  integration tests.\n\n## Code comments\n\nSpecifics for code comments and documentation:\n\nSpend comments on the non-obvious: concurrency and async hazards (races,\nlease/handle expiry, values that must not be held across an await point),\nordering constraints (\"X must happen before Y, else Z\"), invariants whose\nviolation panics or corrupts data, restart/recovery semantics, the origin of\nmagic constants, and why the obvious alternative was not taken. Idiomatic code\n(match arms, iterator chains, getters, logging) needs none.\n\nA doc comment is the caller's contract: a one-sentence summary, then only the\ninvariants and semantics a caller must know. A self-evident public item needs\nonly that one line. Don't narrate the body in rustdoc (\"Phase 1 ... Phase\n2 ...\", or enumerating a flag's branches). Reasoning about how or why the code\nworks goes in an inline `//` at the decision point, or in a module-level `//!`\nwhen it is about how the pieces fit together. Document a struct field only when\nits meaning is subtle.\n\nMark counterintuitive gotchas with `NOTE:` and future work with `TODO:`.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Materialize\n\n## Skills\n\nCanonical agent skills in `.agents/skills/`. `.claude/skills` is compat symlink\nfor Claude Code. Check `mz-*` skill before tasks — encodes project conventions,\nsaves time.\n\nUse the `mz-test` skill before running ANY tests, even mid-task — the canonical\ncommands aren't the obvious ones (e.g. `bin/sqllogictest --optimized`, not\n`cargo build --bin sqllogictest`).\n\nUse the `mz-run` skill before building, running, formatting, or linting. `bin/fmt` and `bin/lint` are the canonical entry points, NOT `cargo fmt`, `rustfmt`, or a bare `cargo clippy`. `bin/environmentd`, not `cargo build --bin environmentd`.\n\nUse the `mz-commit` skill before `git commit`, `git push`, or `gh pr create`.\n\nUse the `mz-debug-ci` skill before the first `bk` or `gh pr checks` command, or when handed a Buildkite URL.\n\n## Code navigation\n\nFor operation flow tracing, read first:\n\n* `doc/developer/generated/flows.md` — maps operations (query lifecycle, source ingestion, MV creation, sink lifecycle, catalog DDL, timestamp selection, persist read/write, controller architecture) to `crate::module` paths in execution order.\n* `doc/developer/generated/<crate>/_crate.md` — per-crate overview: modules, key types, dependencies.\n* `doc/developer/generated/<crate>/<module>.md` — per-file docs.\n\n> **READ-ONLY: `doc/developer/generated/` is generated, not authored.**\n> The entire `doc/developer/generated/` tree is maintained exclusively by the\n> recurring documentation agent, which runs the `update-docs` skill/command.\n> That agent is the *only* session permitted to create, edit, or delete files\n> under this directory.\n>\n> In any other session: **treat `doc/developer/generated/` as read-only.** Use\n> it for navigation and context, but never edit, create, delete, or regenerate\n> files there — not even to \"fix\" something you noticed, and not as part of an\n> unrelated change. These files carry `source`/`revision` front-matter that the\n> recurring agent manages; hand edits desync that bookkeeping. If a generated\n> doc is wrong or stale, report it in your response rather than editing it, and\n> leave the correction to the `update-docs` agent. Do not stage or commit any\n> path under `doc/developer/generated/` unless you are explicitly running the\n> `update-docs` workflow.\n\n## Dependency management\n\n### Workspace dependencies\n\nAll third-party versions declared in `[workspace.dependencies]` in root\n`Cargo.toml`. Members use `dep.workspace = true` or\n`dep = { workspace = true, optional = true }`.\n\n* **Add new dep**: add to `[workspace.dependencies]` in root `Cargo.toml` first, then `dep.workspace = true` in member crate.\n* **Never inline version** in member `Cargo.toml` — `bin/lint-cargo` enforces.\n* **Update version**: change once in root `Cargo.toml`.\n* Cargo unifies features workspace-wide, so workspace declaration is union of all features across crates. Members just use `dep.workspace = true`.\n\n### Cargo.lock\n\nNever regenerate full Cargo.lock. When changing deps:\n\n* **Add dep or change features**: run `cargo check` — updates only what changed.\n* **Update specific crate**: `cargo update -p <crate>` (optional `--precise <version>`).\n* **Never bare `cargo update`** — bumps every semver-compatible dep, causes unrelated breakage from transitive changes.\n* **If lock regenerated**, diff before commit (`git diff Cargo.lock | grep '^[+-]version'`) and pin back unintended bumps with `cargo update -p <crate> --precise <old-version>`.\n\n### Licensing\n\nTwo files control license policy, **keep in sync**: `deny.toml` (`[licenses].allow`) and `about.toml` (`accepted`). New dep with new license not already allowed: add SPDX identifier to both.\n\n## Guidance\n\n* When designing specs or implementing features, preserve the full scope and\n  capability of the solution. Do not substitute dynamic or generative\n  approaches with hardcoded data, skip automation that a reference\n  implementation provides, or simplify away the parts that make a feature\n  robust and maintainable. If a reference codebase generates data from an\n  authoritative source, our implementation should do the same, not ship a\n  static snapshot. When you feel tempted to reduce scope or take a shortcut,\n  flag it to the user and workshop an alternative together rather than silently\n  downgrading the design.\n* When making code changes, run cheap checkers/linters and formatters before\n  reporting success and/or committing changes. For Rust, these would be\n  `bin/fmt` and `cargo check`.\n* When debugging CI or lint failures, start by reproducing the exact failing\n  command locally and reading its output. Do not run generic checks (clippy,\n  fmt, grep) in a shotgun approach.\n* We value simplicity and clear abstractions. We especially care about\n  designing the interfaces or boundaries between components well. This includes\n  components, traits, interfaces, modules, and crates.\n* In code comments or inline documentation, we value clearly described\n  contracts and assumptions.\n* In code comments, we don't like \"fluff\" comments, comments that describe what\n  code does when it is obvious from the code. Good code should be readable. It\n  _is_ okay to call out tricky parts of the code or \"nota benes\".\n* In code comments and code documentation we value concise but complete\n  comments.\n* In code comments and documentation, don't refer to potential previous states\n  of the code, or things like future PRs, try not to use chronology in there,\n  except when it's needed to explain why a certain thing behaves as it does and\n  we need to record that knowledge. In general comments need to stand on their\n  own and make sense from just looking at them and the code around it, not\n  previous changes.\n* Avoid em-dashes for structuring sentences in any prose: code comments, specs,\n  design docs, all of it. Restructure with full stops and commas instead. The\n  same goes for semicolons, though one is fine where splitting would mangle the\n  sentence.\n* Our guidance applies both when writing new code or designs, or when we notice\n  deviations in code or architecture that we are working on. At the same time,\n  we want to keep our changes minimal so it's good to call out deviations and\n  then we can decide together what to do about it.\n* Never put a side effect inside `debug_assert!` (or `debug_assert_eq!`, etc.).\n  The macro body compiles out whenever debug-assertions are off, which includes\n  `[profile.optimized]` (what `bin/environmentd` and mzcompose use) and\n  `[profile.release]`. Only `[profile.ci]` turns them on. A side effect written\n  there, for example `debug_assert!(map.insert(k, v).is_none())`, runs under\n  `cargo test` but silently vanishes in optimized and release builds, leaving\n  the logic it powered inert and profiler-blind. Bind the effect to a `let`\n  outside the assert, then assert on the bound value. Clippy's\n  `debug_assert_with_mut_call` catches `&mut self` receivers but not `&self` or\n  free-function side effects.\n* Never write vendor, customer, or account names into durable or user-facing\n  surfaces: committed code, comments, column comments, docs, specs, commit\n  messages, PR bodies, or test fixtures. Anything persisted to disk gets shared,\n  indexed, and outlives the context, so a name in it is a leak. Anonymize to the\n  technical pattern instead, for example \"a wide unfiltered LEFT JOIN driving a\n  freshness incident\" rather than who hit it. Names are fine in ephemeral chat,\n  not on disk.\n* Never use `std::collections::HashMap`/`HashSet` directly, `clippy.toml`'s\n  `disallowed-types` blocks it. Use `BTreeMap`/`BTreeSet` when iteration order\n  matters, or `mz_ore::collections::HashMap` for keyed-only access with no\n  iteration. Hash-order iteration is a real nondeterminism source, for example\n  an unstable order reaching plan output or persisted state, not a style nit.\n* A new feature flag should default off in production but default ON in the\n  test/CI configuration, so the new code path is exercised by sqllogictest,\n  testdrive, and optimizer goldens before it earns trust. Production safety and\n  test coverage are separate settings. Wire the override through\n  `system_parameter_default`: the `--system-parameter-default=NAME=VALUE` CLI\n  flag (env `SYSTEM_PARAMETER_DEFAULT`) for sqllogictest and environmentd\n  binaries, or `TestHarness::with_system_parameter_default` for Rust\n  integration tests.\n\n## Code comments\n\nSpecifics for code comments and documentation:\n\nSpend comments on the non-obvious: concurrency and async hazards (races,\nlease/handle expiry, values that must not be held across an await point),\nordering constraints (\"X must happen before Y, else Z\"), invariants whose\nviolation panics or corrupts data, restart/recovery semantics, the origin of\nmagic constants, and why the obvious alternative was not taken. Idiomatic code\n(match arms, iterator chains, getters, logging) needs none.\n\nA doc comment is the caller's contract: a one-sentence summary, then only the\ninvariants and semantics a caller must know. A self-evident public item needs\nonly that one line. Don't narrate the body in rustdoc (\"Phase 1 ... Phase\n2 ...\", or enumerating a flag's branches). Reasoning about how or why the code\nworks goes in an inline `//` at the decision point, or in a module-level `//!`\nwhen it is about how the pieces fit together. Document a struct field only when\nits meaning is subtle.\n\nMark counterintuitive gotchas with `NOTE:` and future work with `TODO:`.\n","category":"root","tokens":2359}]}