Skip to content

RQ1 — recipe-health ⇄ TestGrid Evidence deep-link #1283

Description

@njhensley

Parent: #1265 · Labels: enhancement; area/docs auto-assigns from the docs/** change. No net-new pkg/recipe helper is introduced by RQ1 — the shared mapping function is shipped and owned by the TestGrid epic (§3), so RQ1 carries no labeler.yml/CODEOWNERS add of its own; it imports the TestGrid epic's package. · Size: M · Depends on: #1224 children #1225#1230 (specifically #1229 tools/health generator and the pkg/health.Compute + docs/user/recipe-health.md they introduce — none exist at HEAD), the TestGrid epic's shipped mapping function + coordinate/URL scheme (TG2/TG4a/TG6), and the TestGrid epic's coordinate-presence query surface (TG4a) that RQ2 keys off. RQ1 must land after #1224 V1 ships its pending column.

Goal. Turn the literal pending Evidence column (docs/design/009-recipe-health-tracking.md:263) into a stable, deterministic deep-link to each recipe's TestGrid (group, dashboard, tab) coordinate — without duplicating any TestGrid data into the matrix — as the #1224 v1.1 Evidence rendering.

Scope.

  • Consume the TestGrid epic's shipped recipe → coordinate function (§2): service → group, accelerator-os → dashboard, intent[-platform] → tab, applying the TestGrid epic's path-sanitize rules (lowercase; collapse /\:;[]{}, +whitespace to -; dedupe; trim; empty→unknown for required segments; bare-intent tab when platform absent). This is one function, owned by the TestGrid epic (TG2/TG6), imported here and by Epic: Recipe health tracking (ADR-009 V1) — enumeration, structural soundness, public matrix #1224's join key — not re-implemented. Confirming the import path against the TestGrid epic is a hard dependency, not a note: there must be a single source of truth.
  • Contribute the link-rendering change to the tools/health generator + make targets + public recipe-health matrix #1229 tools/health generator so the Evidence column emits a markdown link to the AICR-native UI's stable URL for the coordinate. The "has a presence" signal must be obtainable without the generator making a network call on the hermetic path. Chosen approach (a): emit the deterministic link unconditionally for resolvable recipes, keep the generator fully hermetic (link construction is pure, offline, byte-deterministic), and let RQ2 own resolution against the TestGrid epic's coordinate-presence surface. Document this choice in the matrix header note. (Approach (b) — read an offline presence manifest published by the TestGrid epic — is the fallback if unconditional emission proves too noisy.)
  • Update the hand-written header note in docs/user/recipe-health.md (the prose block ADR-009 reserves for explaining the column) to explain that Evidence now links to live TestGrid posture, that absence of data is shown by the link landing on an empty coordinate, and that community-source columns are author-asserted provenance, not independently-verified correctness (the tab placement is author-declared; see §2 trust caveat).
  • Reconcile with ADR-009's deferred in-cell freshness state, in prose. Note that the deep-link is the V1.1 Evidence rendering and that ADR-009's verify-gated/AttestedAt in-cell freshness/unattested-vs-aged trust state (009-recipe-health-tracking.md:245-251) is a distinct, later refinement Epic: Recipe health tracking (ADR-009 V1) — enumeration, structural soundness, public matrix #1224 owns — the two coexist (the link points at the live board; an optional freshness token can later annotate the same cell). Do not silently drop the trust distinction.
  • Docs same PR: the column-semantics change is itself the doc; also cross-link docs/user/recipe-health.md ⇄ the TestGrid public UI and ⇄ docs/user/coverage-matrix.md (RQ3).

Out of scope. Resolution verification (RQ2). The coverage matrix (RQ3). The verify-gated in-cell freshness state and letter-grade grading fusion (#1224 v1.1). Any change to ADR-009's structural signals or status rollup. Embedding pass/fail counts (forbidden). Authoring or re-implementing the mapping function (the TestGrid epic owns it).

Key files. pkg/recipe/criteria.go (type Criteria struct :345, doc-comment :343; CriteriaAnyValue :42) as the mapping input type; the TestGrid epic's shipped mapping package (import, do not duplicate); the #1229-introduced tools/health/ generator and docs/user/recipe-health.md (both to be created by #1224 — coordinate, do not pre-create here); docs/index.yml; docs/design/009-recipe-health-tracking.md (the Evidence-column contract, :263/:456, and the deferred-axis spec :245-251). Determinism precedent: pkg/serializer.MarshalYAMLDeterministic, tools/bom -deterministic.

Tests. Table-driven mapping tests over the criteria enum values, drive from the runtime union so --data-extended values cannot silently produce an unmapped coordinate. The enumerators are methods on *CriteriaRegistry (AllServiceTypes criteria.go:104, AllAcceleratorTypes :161, AllIntentTypes :203, AllOSTypes :256, AllPlatformTypes :307), obtained via GetCriteriaRegistryFor(dp) (criteria_registry.go:254) / NewCriteriaRegistry (:96) / (*CriteriaRegistry).Values(field) (:179); the static package funcs GetCriteriaServiceTypes() (criteria.go:98) / GetCriteriaAcceleratorTypes() (:155) / GetCriteriaIntentTypes() (:197) / GetCriteriaOSTypes() (:250) / GetCriteriaPlatformTypes() (:301) cover the OSS-static set. Assert: every value maps to the expected sanitized coordinate; wildcard/any and empty-string dimensions handled; the intent/platform-only-in-tab invariant; the per-cloud OS divergence (h100-eks-ubuntu-training-kubeflow → eks / h100-ubuntu / training-kubeflow and h100-gke-cos-training-kubeflow → gke / h100-cos / training-kubeflow); byte-deterministic link rendering across two generator runs; a recipe with no platform renders intent alone (training, not training-). A golden-file test on a small fixture matrix asserting link text and that no status/count token appears. Since RQ1 imports the TestGrid epic's function, the canonical mapping golden test lives in the TestGrid epic's owning package (AC #6); RQ1's tests assert rendering (link text, hermeticity, no-status-token), not re-derive the mapping.

Acceptance. The Evidence column links deterministically to TestGrid coordinates via the TestGrid epic's shared function; the link is stable under k8s-version change because of the k8s-out-of-path decision (§2) — the link target is the (group, dashboard, tab) coordinate whose dashboard is accelerator-os with no k8s component, so a recipe's k8s range (K8s.server.version, e.g. recipes/overlays/gb200-eks-training.yaml:32) and the per-run observed major.minor never enter the path; the generator stays hermetic; no TestGrid data is duplicated into markdown; the reconciliation prose distinguishes the link from #1224's deferred in-cell freshness state; the community-source provenance caveat is stated. Any new Go (rendering helpers) clears the 75% floor standalone and the baseline-delta gate (no > 0.5% per-package regression; no new exported func at 0%).


Child of #1265 · staged from docs/design/012-recipe-quality-surfaces.md (RQ1).

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions