docs(tcg): clarify TCG schema forward-compat model (closed enums + version-matched validation)

[ANcpLua]

Summary

Fast-follow on #12 (CodeRabbit-flagged, the one survivor of adversarial triage).

The TCG exchange schema's top-level description promised "consumers MUST tolerate unknown enum members for forward compatibility", but signal / lane / status / payloadAccess / provenance are closed enums. Strict JSON-Schema validation would therefore reject a future document carrying a new enum value — contradicting the schema's own promise.

Fix (description text only — no structural change)

Reword the description to the model the spec already documents (docs/TELEMETRY_CAPABILITY_GRAPH.md → Versioning & compatibility): the enums are intentionally closed so a document is validated strictly against the schema whose version equals its own schemaVersion; forward compatibility comes from version-matched validation + tolerant consumer code (map unknown enum members to the catch-all, ignore unknown properties — additionalProperties stays true). Strict typo-catching is kept; the contradiction is removed.

The emitted TCG validates identically (enums and structure unchanged).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: af3b8572-6998-4a6d-9895-3a0cc80a9d61

📥 Commits

Reviewing files that changed from the base of the PR and between 004c58d and ad2be49.

📒 Files selected for processing (1)

• docs/schema/telemetry-capability-graph.schema.json

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: webapi-aot-demo (qyl-macos)
• GitHub Check: webapi-aot-demo (qyl-linux)

🧰 Additional context used

📓 Path-based instructions (2)

docs/schema/telemetry-capability-graph.schema.json

📄 CodeRabbit inference engine (AGENTS.md)

Keep the vendor-neutral Telemetry Capability Graph exchange schema in docs/schema/telemetry-capability-graph.schema.json aligned with the current contract.

Files:

• docs/schema/telemetry-capability-graph.schema.json

**

⚙️ CodeRabbit configuration file

AGENTS.md

**: # Qyl.OpenTelemetry.AutoInstrumentation agent rules

Mission

This repository is the runtime AOT auto-instrumentation lane for qyl, evolving into a
self-describing observability substrate. The foundation is unchanged: .NET 10
NativeAOT-compatible zero-code instrumentation through managed build assets, source generation,
DiagnosticListener consumption, and module-initializer boot. The direction is the North Star
below.

Keep this repository separate from:

• semantic-convention package generation (Qyl.OpenTelemetry.SemanticConventions is a referenced
  vocabulary package, not generated here),
• the old CLR-profiler/OpenTelemetry auto-instrumentation substrate,
• unrelated compile-time tracing experiments (the experiment/ and spike/ trees stay outside
  the .slnx / production build graph — see docs/experiments/).

North Star — declare and prove the whole stack

Every observability tool today is pull-by-observation: a backend learns what a service emits
by receiving samples over time, and never knows whether it has seen the whole surface. qyl has a
capability none of them have — because instrumentation is source-generated interceptors + a static
contract + a referenced semconv registry + (incrementally) DTO inference, the complete set of
telemetry a binary can ever produce is a compile-time-derivable fact, with provenance.

The substrate goal: every qyl binary ships a complete, machine-readable Telemetry Capability
Graph (TCG) — the full possible OpenTelemetry surface for that exact binary, each capability
tagged compile-time-owned vs runtime-valued — and proves it by self-hosting (instrumenting its
own pipeline with its own mechanism, zero extra code). Any external entity consumes the TCG to know
the entire stack before a span is sampled. The contract becomes the shared semantic graph; an OTLP
backend is just one consumer.

Three pillars:

1. Self-host (the proof). qyl instruments qyl with qyl — `QylSelfTelemetr...

Files:

• docs/schema/telemetry-capability-graph.schema.json

---

⚙️ CodeRabbit configuration file

**: Operating principles (solo-dev, agentic SDLC — reviews are advisory, agents act on them):

1. LAZY: one self-contained, correct review beats ten partial ones. Every finding is
   definitive — concrete evidence with file:line, a concrete fix, no "consider maybe",
   no open or ambiguous questions back to the author. If you cannot decide a point
   from the diff plus repo context, stay silent on it. Never cite a source, API, or
   version you have not verified; an unverifiable claim is a dropped claim.
2. IMPATIENT: never stall a PR. There are no compatibility obligations here — internal
   and dogfooding code has NO public-API contract; removing shims, breaking signatures,
   and deleting dead paths are normal, desirable changes. Do not flag backward
   compatibility, deprecation ceremony, or migration paths. (SemVer applies only to
   commercially sold libraries — this repo has none.)
3. EGO: hold the bar of the best reviewer on the market — flag real correctness,
   security, data-loss, and structural problems precisely; produce zero noise.

Files:

• docs/schema/telemetry-capability-graph.schema.json

🔇 Additional comments (1)

docs/schema/telemetry-capability-graph.schema.json (1)

5-5: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated the telemetry capability graph schema description to clarify how consumers should validate and interpret it.
  • The schema guidance now emphasizes version-matched validation and tolerant handling of objects and enums.

Walkthrough

The top-level description string in docs/schema/telemetry-capability-graph.schema.json is replaced with a more explicit statement directing consumers to use version-matched validation and tolerant enum/object handling, noting enums are intentionally closed and additionalProperties is true.

Changes

Schema Description Update

Layer / File(s)	Summary
Schema top-level description rewrite docs/schema/telemetry-capability-graph.schema.json	Single-line description replaced with explicit forward-compatibility and versioning guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly reflects the schema description update and its closed-enum/version-matched validation focus.
Description check	✅ Passed	The description matches the documentation-only schema clarification and its forward-compatibility rationale.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/tcg-schema-enum-forward-compat

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch fix/tcg-schema-enum-forward-compat

---

_{Comment @coderabbitai help to get the list of available commands.}