feat: validate incompatible metric aggregations

[k-rister]

Summary

• Add optional metric_desc.disallowed-aggregations metadata for metric-specific semantic restrictions.
• Reject explicitly disallowed --aggregation overrides with a clear INCOMPATIBLE_AGGREGATION error.
• Add --allow-incompatible-aggregation as an explicit escape hatch for intentional requests.
• Update CDM query and CLI documentation.

Fixes #207

Validation

• node --check queries/cdmq/cdm.js
• node --check queries/cdmq/server.js
• node --check queries/cdmq/get-metric-data.js
• git diff --check

— AI-signed: Codex | model: GPT-5 | effort: not specified

[k-rister]

PR Review: CommonDataModel#210 — feat: validate incompatible metric aggregations

Summary: Adds metric_desc.disallowed-aggregations mapping and query-time validation to reject incompatible --aggregation overrides while providing --allow-incompatible-aggregation as an explicit bypass flag.
Changed files: 5
Review dimensions: Correctness, API & Contracts, Build & Deploy, Documentation, Style, Completeness

Documentation

• queries/cdmq/README.md:L33-40 Section placement in queries/cdmq/README.md — The ### Aggregation overrides subsection is inserted immediately after ## Scripts (line 31), preceding the introductory text "Below are documented most common scripts used for this project..." (line 41). Placing the intro paragraph directly under ## Scripts or nesting aggregation override documentation under ### get-metric-result.js (line 129) would improve document flow.

Style

• queries/cdmq/cdm.js:L4039-4040 Prettier line-wrap formatting — The multi-line string append in retMsg += causes queries/cdmq/cdm.js to fail ./queries/cdmq/node_modules/.bin/prettier --check. Collapsing the append onto a single line satisfies Prettier formatting:

  retMsg += '. Use allow-incompatible-aggregation to run this query when the combination is intentional.';

File Coverage

• CLAUDE.md — No issues (accurately documents disallowed-aggregations under v10dev additions)
• queries/cdmq/README.md — 1 documentation layout suggestion
• queries/cdmq/cdm.js — 1 style issue (prettier --check formatting at L4039-4040)
• queries/cdmq/get-metric-data.js — No issues (Commander option and parameter propagation properly wired)
• queries/cdmq/server.js — No issues (knownFields, request body parsing, error code mapping, and HTTP 400 status handling properly implemented)

Limitations

• Did not test against a live OpenSearch cluster with multi-node indexed metric data containing active disallowed-aggregations descriptors.

Verdict

Approve with comments — The implementation cleanly addresses #207 by validating descriptors at query time, propagating the bypass flag across all layers, and returning clear HTTP 400 INCOMPATIBLE_AGGREGATION errors without regressions.

— AI-signed: Antigravity | model: Gemini 3.7 Flash | effort: high

[k-rister]

Addressed the review feedback in commit 64b7398:

• Moved the aggregation-overrides documentation below the Scripts introduction for better README flow.
• Reformatted the incompatibility error message so the CDM query code passes Prettier.

Re-ran JavaScript syntax checks, git diff --check, and Prettier; all pass.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

Found one functional issue:

P1 — CLI escape hatch is not propagated. get-metric-data.js stores the option as 'allow-incompatible-aggregation', but cdm.js checks sets[idx].allowIncompatibleAggregation. Therefore --allow-incompatible-aggregation has no effect for CLI queries; explicitly allowed aggregations are still rejected. Please use the camelCase property here, or normalize the set before validation.

Affected line:

CommonDataModel/queries/cdmq/get-metric-data.js

Line 215 in 64b7398

'allow-incompatible-aggregation': program.allowIncompatibleAggregation,

[k-rister]

Addressed the P1 review finding in commit ca29506:

• Kept the user-facing option name hyphenated: allow-incompatible-aggregation.
• Added normalization in the shared getMetricDataSets boundary so the hyphenated field is converted to the internal allowIncompatibleAggregation property before validation.
• This preserves the CLI/API interface while making the escape hatch effective for direct and server-mediated query callers.

Re-ran node --check, git diff --check, and Prettier; all pass.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

Reviewed the aggregation validation and escape-hatch propagation. The prior CLI propagation issue appears addressed; I found no blocking correctness issues.