AGENTS.md@src/common/meta git:20261015.cbfbad4A

Immutable. This exact content never changes and is served at /api/v1/blob/4c5812a79fd3a471.

# 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 |
| --- | --- | --- |
| Affinity | `src/common/meta/src/affinity.rs` | Requirements, reference resolution, node matching, and allocation-context provider |
| 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.
- Create-table preparation obtains allocation inputs from the optional query
  provider in `DdlContext`. Install providers before registering procedure
  loaders so restored procedures use the same runtime dependencies. Affinity
  requirements and fallback policy are runtime inputs, not persisted fields.
- `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>
```