test(DEN-3828): certify explicit docs alias cardinality peers

.github/workflows/api-docs-cardinality.yml

@@ -0,0 +1,116 @@
+name: api-docs discovery cardinality canary
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/api-docs-cardinality.yml"
+      - ".github/workflows/api-docs-peer-authorities.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: api-docs-cardinality-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  API_DOCS_SHA: f6efa12a3ce5a01713464df6168082c289d85716
+  TJSV_SHA: 93dd73cb246a09b0a1c62d7192cc62ca6ecbe405
+
+jobs:
+  cardinality:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Check out exact canary head
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Check out exact API Docs candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ORESoftware/api-docs
+          ref: ${{ env.API_DOCS_SHA }}
+          path: subject
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Check out canonical TJSV
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ORESoftware/typespec-json-schema-validator
+          ref: ${{ env.TJSV_SHA }}
+          path: tjsv
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Verify immutable source identities
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(git -C subject rev-parse HEAD)" = "$API_DOCS_SHA"
+          test "$(git -C tjsv rev-parse HEAD)" = "$TJSV_SHA"
+          grep -F '@TypeSpec.JsonSchema.extension("minItems", 4)' subject/idl/typespec/docs-discovery.tsp
+          grep -F '@TypeSpec.JsonSchema.extension("maxItems", 4)' subject/idl/typespec/docs-discovery.tsp
+          jq -e '."$defs".DocsDiscoveryManifest.properties.aliases.minItems == 4 and ."$defs".DocsDiscoveryManifest.properties.aliases.maxItems == 4' \
+            subject/json-schema/docs-discovery.schema.json
+
+      - name: Install Node 22.23.1
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22.23.1"
+          package-manager-cache: false
+
+      - name: Install immutable TJSV compiler and emitter
+        working-directory: tjsv
+        shell: bash
+        run: |
+          set -euo pipefail
+          npm ci --ignore-scripts --no-audit --no-fund
+          npm rebuild @oresoftware/f2e --foreground-scripts
+          node bin/typespec-json-schema-validator.mjs doctor --quiet
+
+      - name: Compile TypeSpec and compare against independently authored JSON Schema
+        shell: bash
+        run: |
+          set -euo pipefail
+          out="$RUNNER_TEMP/docs-discovery-cardinality"
+          mkdir -p "$out/generated"
+          node tjsv/bin/typespec-json-schema-validator.mjs check \
+            --typespec=subject/idl/typespec/docs-discovery.tsp \
+            --schema=subject/json-schema/docs-discovery.schema.json \
+            --report="$out/report.json" \
+            --contract-ir="$out/contract-ir.json" \
+            --output-dir="$out/generated" \
+            --bundle-id=docs-discovery.typespec.generated.schema.json \
+            --max-findings=100 \
+            --max-probes=96 \
+            --quiet
+
+          generated="$out/generated/docs-discovery.typespec.generated.schema.json"
+          test -s "$generated"
+          jq -e '."$defs".DocsDiscoveryManifest.properties.aliases.minItems == 4 and ."$defs".DocsDiscoveryManifest.properties.aliases.maxItems == 4' "$generated"
+          jq -e '
+            .status == "passed" and
+            .zeroUnexplainedFindings == true and
+            .authorities.precedence == "none" and
+            .authorities.typespec.authority == "independently-authored" and
+            .authorities.jsonSchema.authority == "independently-authored" and
+            .authorities.typespec.generatedJsonSchemaRole == "comparison-evidence-only" and
+            .coverage.typespecGeneratedJsonSchemaComparison == true and
+            .coverage.differentialInstanceValidation == true and
+            .differential.summary.probesEvaluated > 0 and
+            .differential.summary.divergences == 0
+          ' "$out/report.json"
+          jq -e '.status == "passed" and .admissible == true and .editableAuthority == false' "$out/contract-ir.json"
+
+      - name: Prove candidate sources stayed read-only
+        shell: bash
+        run: |
+          set -euo pipefail
+          git -C subject diff --exit-code -- .
+          git -C tjsv diff --exit-code -- .

.github/workflows/api-docs-peer-authorities.yml

@@ -38,7 +38,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: ORESoftware/api-docs
-          ref: f6bc8771365ee79cf72d53d640ea5c296b0e2dd1
+          ref: f6efa12a3ce5a01713464df6168082c289d85716
           path: subject
           persist-credentials: false
           show-progress: false
@@ -48,7 +48,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          test "$(git -C subject rev-parse HEAD)" = "f6bc8771365ee79cf72d53d640ea5c296b0e2dd1"
+          test "$(git -C subject rev-parse HEAD)" = "f6efa12a3ce5a01713464df6168082c289d85716"
 
       - name: Check out canonical TJSV
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1