docs(metrics): deployment layout for local/dev/prod + schema decision

[DanielVisca]

Problem

The metrics query surface is about to grow (filters, group-by, counter functions, formulas). Locking the request/response contract down as frozen dataclasses before the behavior lands means every later PR extends one shape instead of inventing its own.

Changes

Adds facade/contracts.py + facade/enums.py (previously empty stubs): MetricFilter, MetricGroupBy, MetricQueryClause, MetricQueryRequest, MetricPoint, MetricSeries, and the AttributeScope / FilterOp / MetricAggregation enums. Framework-free, frozen, validated in __post_init__ (quantile bounds, unique clause names, window ordering). Design choices worth knowing:

• interval lives on the request, not per clause — every series in a response shares one bucket grid, which is what makes formulas like a / b line up.
• The response is always [MetricSeries]; a single ungrouped query returns one series with empty labels, so consumers never branch on single-vs-multi.
• AttributeScope.AUTO is the default everywhere — explicit resource/attribute scope stays available but the planned schema-v2 merged-label layout makes auto the forward-compatible choice.

Pure types + unit tests; no behavior change.

How did you test this code?

I'm an agent. Automated: hogli test products/metrics/backend/tests/test_contracts.py (12 tests: validation rules, immutability).

🤖 Agent context

Autonomy: Human-driven (agent-assisted) — directed by @DanielVisca

Contracts were drafted by Daniel; this revision validates them against the implemented stack above it (no shape changes were needed — only the docstring promise that the formula result uses clause="formula", which PR #63129 honors).

[DanielVisca]

• feat(metrics): investigating-metric-anomalies skill #63132
• feat(metrics): characterize-metric-anomaly endpoint and MCP tool #63131
• feat(metrics): expose query-metrics and metric-names-list MCP tools #63130
• feat(metrics): multi-clause queries and server-side formulas (P7) #63129
• feat(metrics): histogram_quantile from OTel explicit-bounds buckets (P6) #63128
• feat(metrics): counter-aware rate and increase aggregations (P5) #63127
• feat(metrics): group_by on a shared, zero-filled interval grid (P4) #63126
• feat(metrics): label filters with explicit resource/attribute/auto scope (P3) #63125
• feat(metrics): return one MetricSeries per clause from the query endpoint (P2) #63124
• feat(metrics): pipe our logs services into metrics1 locally + verify script #63123
• docs(metrics): deployment layout for local/dev/prod + schema decision #63122 👈 (View in Graphite)
• feat(metrics): add attribute_field helper and seed_metric fixture (P0) #61953
• docs(metrics): dashboard MVP design #61952
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
products/metrics/backend/facade/contracts.py:112
**Mutable `dict` breaks the "Immutable" contract guarantee**

The module docstring advertises these types as `Immutable (frozen=True)`, but `frozen=True` on a dataclass only prevents reassigning the attribute reference — it does not prevent mutating the dict's contents. Any caller can write `series.labels["injected"] = "x"` and silently corrupt a shared series object. `points` is fine because `tuple` is immutable; `labels` is not.

Use `types.MappingProxyType` at construction time, or change the type annotation to `Mapping[str, str]` and enforce immutability by convention with a note that producers must pass a `MappingProxyType`. The latter is lighter-weight and consistent with the rest of the module.

### Issue 2 of 2
products/metrics/backend/tests/test_contracts.py:28-38
**Non-parameterised tests violate project conventions**

Both `test_quantile_aggregation_requires_quantile` (two aggregations inline) and `test_quantile_must_be_in_open_unit_interval` (a `for` loop over bad values) should use `@pytest.mark.parametrize`. A for-loop swallows the failure message after the first bad value, so the test output won't tell you which specific boundary was hit. The project rule is "We always prefer parameterised tests."

_{Reviews (1): Last reviewed commit: "feat(metrics): query contracts and enums..." | Re-trigger Greptile}

[greptile-apps]

Mutable dict breaks the "Immutable" contract guarantee

The module docstring advertises these types as Immutable (frozen=True), but frozen=True on a dataclass only prevents reassigning the attribute reference — it does not prevent mutating the dict's contents. Any caller can write series.labels["injected"] = "x" and silently corrupt a shared series object. points is fine because tuple is immutable; labels is not.

Use types.MappingProxyType at construction time, or change the type annotation to Mapping[str, str] and enforce immutability by convention with a note that producers must pass a MappingProxyType. The latter is lighter-weight and consistent with the rest of the module.

Prompt To Fix With AI

This is a comment left during a code review.
Path: products/metrics/backend/facade/contracts.py
Line: 112

Comment:
**Mutable `dict` breaks the "Immutable" contract guarantee**

The module docstring advertises these types as `Immutable (frozen=True)`, but `frozen=True` on a dataclass only prevents reassigning the attribute reference — it does not prevent mutating the dict's contents. Any caller can write `series.labels["injected"] = "x"` and silently corrupt a shared series object. `points` is fine because `tuple` is immutable; `labels` is not.

Use `types.MappingProxyType` at construction time, or change the type annotation to `Mapping[str, str]` and enforce immutability by convention with a note that producers must pass a `MappingProxyType`. The latter is lighter-weight and consistent with the rest of the module.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Non-parameterised tests violate project conventions

Both test_quantile_aggregation_requires_quantile (two aggregations inline) and test_quantile_must_be_in_open_unit_interval (a for loop over bad values) should use @pytest.mark.parametrize. A for-loop swallows the failure message after the first bad value, so the test output won't tell you which specific boundary was hit. The project rule is "We always prefer parameterised tests."

Prompt To Fix With AI

This is a comment left during a code review.
Path: products/metrics/backend/tests/test_contracts.py
Line: 28-38

Comment:
**Non-parameterised tests violate project conventions**

Both `test_quantile_aggregation_requires_quantile` (two aggregations inline) and `test_quantile_must_be_in_open_unit_interval` (a `for` loop over bad values) should use `@pytest.mark.parametrize`. A for-loop swallows the failure message after the first bad value, so the test output won't tell you which specific boundary was hit. The project rule is "We always prefer parameterised tests."

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[github-actions]

Purely additive changes: new internal docs, frozen dataclass contracts, expanded StrEnum definitions, and matching unit tests for a metrics product in active development. No existing code is modified, no API contracts or data models are altered, and the author is on the owning team. The two bot comments are P2 quality concerns (mutable dict inside a frozen dataclass; non-parameterized tests) — valid but not showstoppers for an additive contract-definition file with no production call sites yet.

New commits pushed (delta classified non_linear_history) — stamphog approval dismissed; re-review running automatically.

[github-actions]

Purely additive changes by the owning team: internal docs, frozen dataclass contracts with no production call sites, expanded enums, and unit tests. No existing code modified, no API contracts or data models altered, no security surface touched.

[github-actions]

Docs from this PR will be published at posthog.com

Project	Deployment	Preview	Updated (UTC)
posthog.com	🤷 Unknown	Preview	Jun 11, 2026, 10:36 PM

Preview will be ready in ~10 minutes. Click Preview link above to access docs at /handbook/engineering/

New commits pushed (delta classified non_linear_history) — stamphog approval dismissed; re-review running automatically.

[stamphog]

Gates denied due to size (917 lines across 9 files). The changes are purely additive — new internal docs, frozen dataclass contracts, expanded enums, and unit tests — with no modifications to existing production code. The two bot inline comments raise valid quality concerns (mutable dict in a frozen dataclass, non-parameterized tests) but are not showstoppers. Needs a human to confirm approval given the size gate failure.