AGENTS.md@src/common/meta · diff

git:20260817.09c0b23 to git:20261012.f50f421

9 added, 0 removed. Audit A to A.

# common-meta — Agent & Contributor Guide

Navigation map for `src/common/meta`. Repo-wide invariants:

[`.agents/architecture-invariants.md`](../../../.agents/architecture-invariants.md).

`common-meta` contains shared metadata keys and values, KV backends, caches,

and durable DDL procedures. Metasrv process and service wiring live in

`src/meta-srv`.

## Module map

| Area | Path | Entry point |

| --- | --- | --- |

| Metadata model | `src/common/meta/src/key.rs`, `src/common/meta/src/key/` | Typed keys, values, and `TableMetadataManager` |

| KV storage | `src/common/meta/src/kv_backend.rs`, `src/common/meta/src/kv_backend/` | `KvBackend`, transactions, memory/etcd/RDS backends |

| DDL procedures | `src/common/meta/src/ddl.rs`, `src/common/meta/src/ddl/`, `src/common/meta/src/ddl_manager.rs` | Durable DDL state machines and task dispatch |

| Caches | `src/common/meta/src/cache.rs`, `src/common/meta/src/cache/`, `src/common/meta/src/cache_invalidator.rs` | Metadata caches and invalidation |

| RPC types | `src/common/meta/src/rpc.rs`, `src/common/meta/src/rpc/` | Shared metasrv request/response types |

| Recovery | `src/common/meta/src/reconciliation.rs`, `src/common/meta/src/reconciliation/` | Catalog/table/region reconciliation |

## Change coupling

- Key/value encoding changes require backward-compatible decoding and a case in

`tests/compatibility/`.

- Multi-key metadata changes must preserve transaction boundaries and cache

invalidation.

- Procedure changes must preserve persisted state and `TYPE_NAME`; new

procedures need loader registration in `src/common/meta/src/ddl_manager.rs`.

- Marker-style table options that no region consumes (`greptime.semantic.*`,

`repartition.column.hint`) go through `AnnotationFamily` in

`src/table/src/requests.rs` — classification, validation, logical-table

eligibility, and the metadata-only alter flow come with it. Do not add

per-option special cases to the alter conversion or DDL routing.

- `KvBackend` behavior changes should extend the shared tests in

`src/common/meta/src/kv_backend/test.rs`.

## Testing

```bash

cargo nextest run -p common-meta

```

Backend-specific coverage may also need `pg_kvbackend` or `mysql_kvbackend`.

+ `test_util::etcd_certs_dir` and `test_util::test_certs_dir` resolve fixture

+ certificates using `CARGO_MANIFEST_DIR` at **run time** (`std::env::var`, not `env!`).

+ `cargo nextest run` sets it; direct test-binary execution requires setting the

+ variable to the crate directory. Run this example from the repository root:

+ ```bash

+ CARGO_MANIFEST_DIR="$PWD/src/common/meta" ./target/debug/deps/<test_binary>

+ ```