@surea11y/core 1.6.0 → 1.7.0

package/docs/RULE_TAXONOMY.md

@@ -11,13 +11,34 @@ It reflects **what already exists in the rules and tests**, not theory.
 Encoded by: `meta.type`
 
 - `automatic`
-    - Rule makes a **normative decision**
-    - Allowed outcomes: `pass`, `fail`, `notApplicable`, and `cantTell` as a defensive fallback only (e.g. an internal-failure safety net, or a computability gate a rule can't resolve — see `contrast-minimum.js`/`contrast-enhanced.js`/`contrast-computable.js`/`target-size-minimum.js`), never as its primary intended path
+    - Rule **decides deterministically**, with no heuristics and no guessing
+    - Allowed outcomes: `pass`, `fail`, `notApplicable`, `cantTell`
+    - `cantTell` is the primary path in two distinct cases, and a defensive
+      fallback in a third:
+        - the rule decides that a real violation exists, but the violation does
+          not on its own establish that the mapped criterion fails — an ARIA
+          author requirement the exposed name, role and value survive
+          (`aria-valid-attr`, `aria-braille-equivalent`,
+          `aria-conditional-attr`), or the graded tier of a rule that fails
+          elsewhere (`aria-required-attr`, `aria-roles-valid`)
+        - the rule decides deterministically but claims no Success Criterion at
+          all (`aria-allowed-role`, tagged `best-practice`)
+        - the rule asks whether something is PRESENT, and its absence conveys
+          nothing false, while the question of whether what IS present is valid
+          belongs to a sibling rule that still fails
+          (`aria-required-children`, paired with `aria-prohibited-children`)
+        - a computability gate the rule cannot resolve, or an internal-failure
+          safety net (`contrast-minimum.js`/`contrast-enhanced.js`/
+          `contrast-computable.js`/`target-size-minimum.js`)
 - `manual`
-    - Rule signals **human review required**
+    - Rule signals **human review required**: it cannot decide at all
     - Allowed outcomes: `cantTell`, `notApplicable`
 
-Manual rules MUST NOT make normative failure decisions.
+Manual rules MUST NOT make normative failure decisions. The dividing line
+between the two types is whether the rule can decide, not which outcome it
+reports: an automatic rule that reports `cantTell` has decided, and is saying
+what it found; a manual rule reports `cantTell` because the question is not
+decidable from markup.
 
 ---
 

package/docs/SARIF.md

@@ -14,11 +14,30 @@ See [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md) for a ready-to-paste GitHub Act
 
 ## What becomes a SARIF result
 
-Only `fail`/`cantTell` occurrences produce SARIF results — a `pass`/`notApplicable` check has no occurrences to report at all (same "violations only" framing as [`REPORT.md`](./REPORT.md)'s HTML report).
+Only `fail`/`cantTell` occurrences produce SARIF results (same "violations only" framing as [`REPORT.md`](./REPORT.md)'s HTML report).
+
+A `notApplicable` check is not always empty: a rule may attach one occurrence explaining why it had nothing to judge, which the contrast rules do when no text had a computable background. Those never become results — a consumer treats every result as an alert, and "this was not evaluated" is not one — but they are not dropped either. They are carried as `note`-level entries in `runs[0].invocations[0].toolExecutionNotices`, each naming the rule it came from via `associatedRule.id`:
+
+```json
+"invocations": [
+  {
+    "executionSuccessful": true,
+    "toolExecutionNotices": [
+      {
+        "level": "note",
+        "message": { "text": "No eligible text had computable contrast (eligible text nodes: 13). See the contrast computability rule for details." },
+        "associatedRule": { "id": "contrast-minimum" }
+      }
+    ]
+  }
+]
+```
+
+That keeps a SARIF-only pipeline from reading silence as a clean bill of health: no contrast alerts can mean the page is fine, or that contrast was never computable, and only the notice separates the two. The block is emitted only when there is something to say, so a run with nothing to report has no `invocations` key at all.
 
 | Engine outcome | SARIF `level` | Meaning |
 |---|---|---|
-| `fail` | `error` | Deterministic, high-confidence violation — the CI-gating case. |
+| `fail` | `error` | Deterministic violation — the CI-gating case. |
 | `cantTell` | `warning` | Needs human review — surfaced, but shouldn't block a build on its own. |
 
 Every rule that ran (regardless of whether it produced a result) is listed once in `runs[0].tool.driver.rules`, with `defaultConfiguration.level` set from the rule's `type`: `automatic` (fail-capable) → `error`, `manual` (capped at `cantTell`) → `warning`.

package/docs/WCAG_CONFORMANCE.md

@@ -44,6 +44,14 @@ only its own origin tag — so a full conformance target is a union of tag sets.
 ready-made sets per version, including the one criterion WCAG 2.2 removed rather than
 added.
 
+**The removed criterion is handled for you.** Every run resolves a target WCAG version
+(`engineOptions.wcagVersion`, else whatever your version tags imply, else `2.2`) and
+reports it back as `engine.wcagVersion`. Under a 2.2 target, a rule mapped only to SC
+4.1.1 Parsing cannot report `fail` — it runs, reports its occurrences, and comes back
+`cantTell` with a `wcagVersionScope` field explaining the coercion. So a default scan
+never gates on a criterion WCAG 2.2 does not contain, and a 2.0/2.1 scan still gets a
+real 4.1.1 verdict.
+
 Composites, unlike atomic rules, *are* filtered cumulatively. The runner reads the
 highest level named in `tags` and drops every composite above it, so requesting
 `['wcag2a', 'wcag2aa']` returns no `rulesResults` entry for an AAA-only SC. That is
@@ -58,7 +66,7 @@ suppression.
 No automated tool — this one included — can certify full WCAG conformance. That's not a limitation specific to surea11y; it's inherent to WCAG itself; a meaningful fraction of Success Criteria require human judgment (is this alt text *accurate*, not just *present*; is this error message *understandable*) or dynamic testing this engine's static-DOM-scan architecture cannot do at all (keyboard-trap detection, real layout/reflow at zoom). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the full, explicit list of what's out of scope and why.
 
 What surea11y *can* give you, honestly:
-- Every `fail` is a real, deterministic, normative violation — never a guess.
+- Every `fail` is a real, deterministic, normative violation under the version you targeted — never a guess.
 - Every `cantTell` is an explicit flag for human review, not a swallowed uncertainty.
 - The facet coverage table tells you exactly which parts of which SCs have zero automated coverage, so you know where a `pass` is silent rather than exhaustive.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -30,7 +30,9 @@
     "./baseline": "./src/baseline.js",
     "./report": "./src/report.js",
     "./sarif": "./src/sarif.js",
+    "./earl": "./src/earl.js",
     "./browser": "./surea11y.browser.js",
+    "./i18n/*": "./surea11y.i18n.*.js",
     "./package.json": "./package.json"
   },
   "author": "Jorge Rumoroso",
@@ -55,6 +57,7 @@
     "src/baseline.js",
     "src/report.js",
     "src/sarif.js",
+    "src/earl.js",
     "src/checks/**/*.js",
     "surea11y.browser.js",
     "surea11y.i18n.*.js",
@@ -74,7 +77,7 @@
     "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
     "build": "node scripts/build-core.js && node scripts/build-browser.js",
     "pretest": "playwright install chromium",
-    "test": "npm run format:check && npm run build && node scripts/run-tests.js",
+    "test": "npm run lint && npm run format:check && npm run build && npm run validate:rules && node scripts/run-tests.js",
     "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",
@@ -85,11 +88,13 @@
     "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
     "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
     "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
+    "finding-ids": "npm run build && node scripts/generate-finding-ids.js",
     "fixtures:index": "node scripts/generate-fixture-index.js",
+    "fixtures:check": "node scripts/generate-fixture-index.js --check",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
     "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
-    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
+    "validate:rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic src/checks/manual",
     "i18n:new": "node scripts/i18n-scaffold.js",
     "i18n:sync": "node scripts/i18n-sync.js",
     "i18n:check": "node scripts/i18n-sync.js --check",
@@ -98,6 +103,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "aria-query": "^5.3.2",
+    "esbuild": "^0.28.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",

package/src/checks/automatic/aria-allowed-attr.js

@@ -934,6 +934,12 @@ function runInPage(ctx) {
               hintKey: 'ariaAllowedAttr_hint_cantTell',
               params: { attr: name, role }
             },
+            uncertainty: {
+              code: 'spec-only',
+              needed:
+                'Whether the deprecated attribute is still honoured by the assistive technology in use.',
+              evidence: { attribute: name, role, status: 'deprecated-for-role' }
+            },
             data: {
               details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
             }

package/src/checks/automatic/aria-allowed-role.js

@@ -6,8 +6,7 @@
  * @check aria-allowed-role
  * @atomic true
  * @summary Explicit role must be permitted by the ARIA-in-HTML spec for its host element
- * @standard WCAG 2.2
- * @sc 4.1.2
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role, where
  *   the host element/attribute combination has an asserted permitted-roles
@@ -16,7 +15,18 @@
  * @expectation
  *   The explicit role is one of the roles the ARIA-in-HTML specification
  *   permits for that host element.
+ *   Reported at CANTTELL rather than FAIL: ARIA-in-HTML's permitted-roles
+ *   table is an author conformance requirement with no ACT rule and no WCAG
+ *   mapping in any source. The role the author asked for is still the role
+ *   assistive technology exposes, so whether the combination harms anyone
+ *   depends on the widget, not on the table.
  * @implementation-notes
+ * - Not WCAG-normative. ARIA-in-HTML's permitted-roles table is an author
+ *   conformance requirement of that specification; no ACT rule covers it and
+ *   no source maps it to a Success Criterion, so the rule reports the
+ *   violation without claiming a criterion is failed. Deterministic all the
+ *   same, so it stays `type: 'automatic'` and keeps deciding rather than
+ *   deferring to a reviewer -- see docs/RULE_TAXONOMY.md 1.1.
  * - Scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
  *   elements without an asserted constraint are treated as "no constraint"
  *   (not flagged) rather than guessed at, see that table's header comment.
@@ -36,22 +46,14 @@ const meta = {
     descriptionKey: 'ariaAllowedRole_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
-  normativeMappings: [
-    {
-      standard: 'WCAG',
-      version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
-      conformanceLevel: 'A'
-    }
-  ],
+  tags: ['best-practice', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: [],
+  normativeMappings: [],
   defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-allowed-for-element'] } }
+  coverage: {}
 };
 
 function runInPage(ctx) {
@@ -93,6 +95,16 @@ function runInPage(ctx) {
           hintKey: 'ariaAllowedRole_hint_fail',
           params: { role, element: tag }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the role misstates this element to assistive technology in practice.',
+          evidence: {
+            role,
+            element: tag,
+            source: 'ARIA in HTML permitted-roles table',
+            wcagSc: []
+          }
+        },
         data: {
           details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
         }
@@ -103,15 +115,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-braille-equivalent.js

@@ -23,6 +23,11 @@
  *   Using either braille-specific attribute as the ONLY naming mechanism
  *   leaves non-braille assistive technology (most screen readers, voice
  *   control, etc.) with no accessible name/role description at all.
+ *   Reported at CANTTELL rather than FAIL: aria-brailleroledescription
+ *   without aria-roledescription reaches no user at all, and a missing
+ *   accessible name is the naming rules' decision for the roles that require
+ *   one. The braille attribute being unpaired is worth surfacing, but it is
+ *   not itself a criterion failing.
  * @implementation-notes
  * - `aria-braillelabel`/`aria-brailleroledescription` do not participate
  *   in the standard accessible-name computation, so
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -131,6 +136,12 @@ function runInPage(ctx) {
             hintKey: 'ariaBrailleEquivalent_hint_fail',
             params: { element: tag, attr: m.attr, requires: m.requires }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether any user reaches this attribute, given no braille equivalent is exposed.',
+            evidence: { element: tag, attribute: m.attr, requires: m.requires }
+          },
           data: {
             details: {
               reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
@@ -146,15 +157,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-conditional-attr.js

@@ -17,6 +17,11 @@
  *   An element with `aria-errormessage` but `aria-invalid` absent or
  *   `"false"` silently drops the error message from the accessibility
  *   tree, authors almost always intend it to be exposed.
+ *   Reported at CANTTELL rather than FAIL: aria-errormessage is only
+ *   exposed once aria-invalid is set, so the reference is currently inert.
+ *   Whether that costs the user anything depends on whether the message is
+ *   conveyed some other way (visible text next to the field, aria-describedby),
+ *   which static markup does not settle.
  * @implementation-notes
  * - This is narrow: the broader space is a table of many
  *   attribute/condition pairs. This rule implements only the one pairing
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -98,6 +103,11 @@ function runInPage(ctx) {
           hintKey: 'ariaConditionalAttr_hint_fail',
           params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the field is ever in an invalid state that should expose this message.',
+          evidence: { element: tag, ariaInvalid: invalidValue || null }
+        },
         data: {
           details: {
             reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
@@ -111,15 +121,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-deprecated-role.js

@@ -161,6 +161,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether this user-agent-reserved role misleads the assistive technology in use.',
+            evidence: { role, ariaStatus: 'discouraged-for-authors' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
           }
@@ -178,6 +184,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether the deprecated role is still honoured, and what it should be replaced with.',
+            evidence: { role, ariaStatus: 'deprecated' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
           }

package/src/checks/automatic/aria-hidden-body.js

@@ -33,7 +33,7 @@ const meta = {
     descriptionKey: 'ariaHiddenBody_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag131', 'wcag412', 'structure', 'atomic', 'automatic'],
+  tags: ['wcag2a', 'wcag131', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
   wcagSc: ['1.3.1', '4.1.2'],
   normativeMappings: [
     {

package/src/checks/automatic/aria-prohibited-attr.js

@@ -370,6 +370,11 @@ function runInPage(ctx) {
               hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
               params: { attr, element: tag }
             },
+            uncertainty: {
+              code: 'judgement-required',
+              needed: 'Whether the element’s own content already serves as its label.',
+              evidence: { attribute: attr, element: tag, role: null, hasOwnContent: true }
+            },
             data: {
               details: {
                 reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',

package/src/checks/automatic/aria-prohibited-children.js

@@ -7,7 +7,7 @@
  * @atomic true
  * @summary Container roles must not own an accessible-tree child with a disallowed role
  * @standard WCAG 2.2
- * @sc 4.1.2
+ * @sc 1.3.1
  * @applicability
  *   Applies to elements with an explicit, valid role that is one of the
  *   container roles with a documented "required owned elements" entry
@@ -126,14 +126,14 @@ const meta = {
     descriptionKey: 'ariaProhibitedChildren_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
+  tags: ['wcag2a', 'wcag131', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1'],
   normativeMappings: [
     {
       standard: 'WCAG',
       version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
       conformanceLevel: 'A'
     }
   ],
@@ -141,7 +141,7 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'medium',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-owned-children-allowed'] } }
+  coverage: { facetsBySc: { '1.3.1': ['aria-role-owned-children-allowed'] } }
 };
 
 function runInPage(ctx) {

package/src/checks/automatic/aria-required-attr.js

@@ -19,8 +19,22 @@
  *   native control's own state exposure already covers it; no aria-checked
  *   is required. helpers.aria.getNativeRoleForElement resolves this).
  * @expectation
- *   Every required aria-* attribute for that role is present (and non-empty).
+ *   Every required state/property for that role is present and non-empty.
+ *   Graded by whether ARIA supplies a stand-in for the missing attribute:
+ *   - FAIL where it does not, so the state is simply not exposed
+ *     (aria-checked on checkbox/radio/switch/menuitemcheckbox/menuitemradio,
+ *     aria-valuenow on slider/scrollbar/meter and on a focusable separator).
+ *   - CANTTELL where ARIA defines an implicit value the role falls back to
+ *     (aria-expanded on combobox, aria-level on heading), so the role still
+ *     exposes a value and only the author knows whether it is the right one.
  * @implementation-notes
+ * - The implicit-value table is generated from aria-query's requiredProps by
+ *   scripts/generate-aria-tables.js (REQUIRED_PROP_IMPLICIT_VALUES in
+ *   src/core/aria-helpers.js), so the two tiers cannot drift apart from the
+ *   spec by hand. ACT 4e8ab6 maps this rule's requirement to WAI-ARIA rather
+ *   than to WCAG, and names 1.3.1/4.1.2 as "less strict" precisely because
+ *   they "allow for fallback default values"; the cantTell tier is that
+ *   carve-out, not a softening of the fail tier.
  * - Scoped to REQUIRED_PROPS_BY_ROLE in src/core/aria-helpers.js,
  *   which only lists a required property when the spec is unambiguous and
  *   context-independent, see that file's header for the rationale.
@@ -131,7 +145,8 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
@@ -178,8 +193,43 @@ function runInPage(ctx) {
     if (!missing.length) continue;
 
     for (const attr of missing) {
-      occurrences.push(
+      const implicit =
+        typeof ariaHelpers.getRequiredAttrImplicitValue === 'function'
+          ? ariaHelpers.getRequiredAttrImplicitValue(role, attr)
+          : null;
+
+      if (implicit) {
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(el, {
+            occurrenceOutcome: 'cantTell',
+            summary: `This attribute is required for this element’s role and is missing, but ARIA falls back to "${implicit}".`,
+            hint: 'Set the attribute explicitly if the implicit value is not the state you mean.',
+            i18n: {
+              summaryKey: 'ariaRequiredAttr_summary_cantTell',
+              hintKey: 'ariaRequiredAttr_hint_cantTell',
+              params: { attr, role, implicit }
+            },
+            uncertainty: {
+              code: 'spec-only',
+              needed: 'Whether the implicit fallback is the state the author meant.',
+              evidence: { attribute: attr, role, implicitValue: implicit }
+            },
+            data: {
+              details: {
+                reasonCode: 'ARIA_ATTR_REQUIRED_MISSING_IMPLICIT',
+                attr,
+                role,
+                implicitValue: implicit
+              }
+            }
+          })
+        );
+        continue;
+      }
+
+      failOccurrences.push(
         helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'fail',
           summary: 'This attribute is required for this element’s role, but is missing.',
           hint: 'Add this attribute with a valid value for this role.',
           i18n: {
@@ -198,15 +248,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-required-children.js

@@ -7,7 +7,7 @@
  * @atomic true
  * @summary Container roles that require specific owned elements must contain at least one
  * @standard WCAG 2.2
- * @sc 4.1.2
+ * @sc 1.3.1
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role that is
  *   also one of the container roles with a documented "required owned
@@ -15,7 +15,17 @@
  *   table, grid, treegrid, tablist, tree, row).
  * @expectation
  *   At least one descendant, or one aria-owns-referenced element, has one
- *   of the acceptable owned roles for that container role.
+ *   of the acceptable owned roles for that container role. Reported at
+ *   CANTTELL, never FAIL: this rule asks only whether the required content
+ *   is PRESENT, and a container that owns nothing conveys nothing false --
+ *   an empty role="list" is announced as a list with no items, which is what
+ *   it is. Whether the content a container does own is VALID is
+ *   aria-prohibited-children's decision, and that rule still fails, so a
+ *   genuinely misdescribed structure (a role="button" among list items, a
+ *   tablist of plain buttons) is caught with the same strength as before.
+ *   The native-HTML equivalents already work this way: nothing in this
+ *   ruleset fails an empty <ul>, and list-children-valid judges only the
+ *   children that exist.
  * @implementation-notes
  * - Scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
  *   (see that file's header for the conservative-scope rationale).
@@ -75,14 +85,14 @@ const meta = {
     descriptionKey: 'ariaRequiredChildren_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
+  tags: ['wcag2a', 'wcag131', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1'],
   normativeMappings: [
     {
       standard: 'WCAG',
       version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
       conformanceLevel: 'A'
     }
   ],
@@ -90,7 +100,7 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'medium',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-required-owned-children'] } }
+  coverage: { facetsBySc: { '1.3.1': ['aria-role-required-owned-children'] } }
 };
 
 function runInPage(ctx) {
@@ -269,6 +279,16 @@ function runInPage(ctx) {
           hintKey: 'ariaRequiredChildren_hint_fail',
           params: { role, requiredRoles: requiredOwned.join(', ') }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed:
+            'Whether this container is legitimately empty, or holds items that never got their role.',
+          evidence: {
+            role,
+            requiredOwnedRoles: requiredOwned,
+            childElementCount: el.children ? el.children.length : null
+          }
+        },
         data: {
           details: {
             reasonCode: 'ARIA_REQUIRED_CHILD_MISSING',
@@ -283,15 +303,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };