{"owner":"milvus-io","repo":"milvus","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":6338,"categories":["claude-rule","root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"milvus":{"command":"npx","args":["-y","@modelcontextprotocol/server-milvus"]}}},"found":["CLAUDE.md","AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"CLAUDE.md":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n","AGENTS.md":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/plugin.json)"},"files":{"CLAUDE.md":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n","AGENTS.md":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/milvus-io/milvus/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n","isInternal":false,"tokens":2719,"sizeBytes":11321},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/milvus-io/milvus/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n","isInternal":false,"tokens":2719,"sizeBytes":11321},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":195},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":181},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":174}],"systemPromptSnippet":"<yakaai_skills repo=\"milvus-io/milvus\">\n<!-- File: AGENTS.md (Tokens: ~2719 | Category: root-instruction) -->\n# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n\n<!-- File: CLAUDE.md (Tokens: ~2719 | Category: claude-rule) -->\n# Milvus\n\nVector database. Go + C++ (internal/core/) + Rust (tantivy).\npkg has its own go.mod (module: `github.com/milvus-io/milvus/pkg/v3`). Run `go get` from `pkg/` when adding dependencies there, not from root.\n\n## Architecture\n\nCoordinators manage metadata and scheduling; nodes execute work.\n- Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)\n- Nodes: proxy (user-facing), querynodev2, datanode, streamingnode\n- All component interfaces defined in `internal/types/types.go`\n\n## Subsystems & Code Map\n\nEach subsystem has a **top-level doc** (overview with links to sub-documents) and multiple **sub-documents** (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.\n\n### Mandatory reading procedure\n\nWhen your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:\n\n**Step 1 — Read the top-level doc.** Identify all sub-documents it links to.\n\n**Step 2 — Read sub-documents.** The scope depends on task type:\n- **Design tasks** (new feature, architecture change, cross-component change): Read **every** sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.\n- **Targeted tasks** (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.\n\n**Step 3 — Read source code** listed in each doc's \"Key Packages\" section. At minimum read the files directly related to your task.\n\n**Step 4 — Cross-check** documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.\n\nNEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.\n\n### Subsystems Reference\n\n- [**Observability**](docs/agent_guides/observability/README.md): Logging, metrics, tracing, and observability debug workflows.\n- [**Streaming System**](docs/agent_guides/streaming-system/streaming-system.md): Write path, WAL, DDL/DCL execution, replication && CDC.\n  - Also read [replicate.md](docs/agent_guides/streaming-system/replication/replicate.md) when you add a feature, or add a side effect to an existing feature. This applies when the feature creates, changes or deletes something that a user expects to still exist after a switchover to another cluster. Examples: rows from any write path, a collection property, a new partition that joins a loaded collection, a granted privilege, a row-level policy, an analyzer that refers to an uploaded dictionary file. Background jobs and internal triggers count too, not only client requests. Decide how the feature works on a CDC deployment. There are three choices:\n    - Replicate it. CDC replicates a state change only through its WAL messages. A secondary applies a message with the same consumer or ack callback as the primary. It derives its physical state (segments, index files, replica placement) by itself.\n    - Keep it local to each cluster, when the state describes that cluster's own deployment: resource group configuration, the message queue in use. Mark its messages unreplicable (`_ur`).\n    - Reject it on a cluster with a replicate topology, until replication is supported. Return an error that says the operation is not supported on a replicating cluster.\n  - Two patterns break replication:\n    - The code applies a state change outside the message path. For example, a coordinator writes its meta directly, or the proxy sends a second RPC after `Broadcast` returns.\n    - A state change depends on a value that is local to one cluster. For example: a segment ID, a node ID, an ID from the local TSO, or a local file path. Allocate such a value on the primary before the broadcast and carry it in the message. Otherwise, do not use it in the state change.\n- [**Storage Paths**](docs/agent_guides/storage/path_contract.md): Read before changing storage paths, manifests, local migration, or GC.\n\n## Testing\n\nGo tests MUST use `-tags dynamic,test` and `-gcflags=\"all=-N -l\"` (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:\n\n```bash\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/querycoordv2/...\ngo test -tags dynamic,test -gcflags=\"all=-N -l\" -count=1 ./internal/proxy/... -run TestXxx\n```\n\nPer-module shortcuts: `make test-querycoord`, `make test-proxy`, etc.\n\n## Verification gate (MANDATORY before claiming \"done\" or pushing for review)\n\nThe reading procedure above tells you how to *enter* the code. This tells you how to *prove a change works*. A change is NOT verified by \"it compiles + unit tests pass + success-path e2e is green.\" When the goal of a change is a **behavior** (retry / classification / routing / error-code propagation / fallback / cache invalidation / concurrency), execute these IN ORDER. Skipping them is the most expensive failure mode — it ships changes that are self-consistent but miss their purpose.\n\n**G1 — Verify the data, not just your transform.** If your change adds a function/layer that maps or preserves a value X (an error code, a Status, a category, a flag), you only verified *your function*. Now verify its INPUT. Audit **every** place that constructs, throws, or rewrites X across the **whole repo** — not only the lines you edited. grep the escape hatches: `throw`, `.ToString()`/stringify, blanket fallbacks (catch-all → `Invalid` / `IOError` / `UnexpectedError`). A value destroyed or mis-set upstream makes your boundary logic dead code. Audit at the SOURCE of X, never only at the boundary that consumes it.\n\n**G2 — Trace each real failure mode end-to-end.** Success-path e2e — even thousands of cases — does NOT exercise the failure modes a behavioral change exists for (S3 throttle, corrupt file, OOM, cancel, timeout, not-ready). For EACH one: either trace it by hand from origin → consumer, or fault-inject it, and confirm it lands in the intended bucket. \"All green\" on the happy path is not evidence the change works; it is only evidence you did not break the happy path.\n\n**G3 — Do not over-claim.** Commit messages and PR body may assert ONLY benefits verified end-to-end via G1+G2. A benefit that depends on un-audited upstream or an un-triggered failure mode must be written as \"follow-up\" or \"preserves codes for observability; retry wiring unverified\" — never as achieved. A reviewer will verify your claim against the running system; over-claiming wastes their round.\n\n**G4 — Adversarial self-review before human review.** Before pushing, do one pass asking: which failure mode have I NOT traced to its bucket? which upstream construction site of X have I NOT read? what would an adversarial reviewer grep for? Fix the gaps, or list them explicitly in the PR.\n\n## Run Milvus Locally\n\n```bash\nscripts/start_standalone.sh    # start standalone mode\nscripts/start_cluster.sh       # start cluster mode\nscripts/stop_graceful.sh       # stop\nscripts/standalone_embed.sh    # embedded standalone (no external deps)\n```\n\n## Code Conventions\n\n- Error handling: use `merr` package, not fmt.Errorf — see mandatory procedure below\n- Logging: use `github.com/milvus-io/milvus/pkg/v3/mlog` only; do not use `pkg/log`, standard `\"log\"`, direct `zap`, or `fmt.Println`. Every log call must pass a real `ctx` by priority: function parameter ctx > struct ctx > `context.TODO()`. Refer to [logging.md](docs/agent_guides/observability/logging.md).\n- Import order: standard → third-party → github.com/milvus-io (enforced by gci)\n- Config params: paramtable (`pkg/v2/util/paramtable`), config in `configs/milvus.yaml`\n\n### Error handling (mandatory when originating, wrapping, or classifying errors)\n\nRead [error_handling_guide.md](docs/dev/error_handling_guide.md) (decision tree,\nInput-vs-System) and [error_handling_casebook.md](docs/dev/error_handling_casebook.md)\n(the 7 mistake patterns) BEFORE writing the change. Non-negotiable rules:\n\n1. Blame test: is the **request content itself** what forces this branch? → Input factory. A Milvus bug, or an internal/transient failure (not-ready, TOCTOU race), → System factory — even when a correct Milvus does reach it on a valid request (transient errors are System, and must stay retriable). \"Looks like validation\" is not the test.\n2. Add context to an existing error with `merr.Wrap/Wrapf` ONLY — `WrapErrXxxErr(err, …)` masks the inner code; cause never goes into a format string.\n3. Before marking anything InputError: grep `retry.Do` consumers. Before converting an `errors.New` sentinel to merr: grep `errors.Is` guards.\n4. Pick codes from the existing family ranges in `pkg/util/merr/errors.go` (scan first; see the partition table in [error_sentinel_convention.md](docs/dev/error_sentinel_convention.md)); never hand-pick 20xx segcore codes.\n5. Touched a wire projection, oldCode mapping, or metric label? Run the merr guard tests AND a full `make test-go` — contract changes break packages you didn't touch.\n6. **C++ side (segcore / milvus-storage / cgo boundary) — the rules above are Go/merr; the same discipline applies in C++, and the verification gate (G1) is non-negotiable here.** The final class is decided at the `ThrowInfo` / `AssertInfo` / `SegcoreError` / arrow-`Status` / `LOON_*` **construction sites**, NOT at the cgo boundary translator. A boundary helper (`KnowhereStatusToErrorCode` / `ArrowStatusToErrorCode` / `LoonResultToErrorCode`) is correct ONLY if its inputs carry the right category — so audit upstream, not the helper. When a code must survive to the cgo boundary, grep every construction/throw/rewrite site and confirm none collapse it: `FailureCStatus` needs a real `SegcoreError` (an `ExecOperatorException` or `throw std::runtime_error(status.ToString())` destroys the code), and an upstream `IOError`-rewritten-as-`Invalid` (or catch-all → `IOError`) silently inverts transient vs permanent. Apply the blame test (rule 1) at EVERY such site, not only the ones you edit.\n\n## PR and Commit Conventions\n\nPR title format: `{type}: {description}`. Valid types: `feat:`, `fix:`, `enhance:`, `test:`, `doc:`, `auto:`, `build(deps):`.\nPR body must be non-empty. Issue/doc linking rules:\n- `fix:` — must link issue (e.g. `issue: #123`)\n- `feat:` — must link issue + design doc under `docs/design-docs`\n- Every Milvus feature should have a related design doc under `docs/design-docs`; submit the doc in this repository and link it from the Milvus feature PR.\n- `enhance:` — must link issue if size L/XL/XXL\n- `doc:`, `test:` — no issue required\n- 2.x branch PRs must link the corresponding master PR (e.g. `pr: #123`)\n\nDCO check is required. Always use `-s` so the developer's Signed-off-by is appended last:\n\n```\ngit commit -s -m \"commit message\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\"\n```\n\n`-s` auto-appends `Signed-off-by: <developer>` at the end. The developer MUST be the final sign-off, not the AI.\n\n## Generated Files — Do Not Hand-Edit\n\n- Mock files (`internal/mocks/*`, `mock_*.go`): regenerate with `make generate-mockery-{module}`\n- Proto files (`pkg/proto/*.pb.go`): regenerate with `make generated-proto-without-cpp`\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/milvus-io/milvus/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}