@binclusive/a11y-contract

The public accessibility finding contract: one zod schema that is both the type and the wire parser. The OSS engine (@binclusive/a11y) emits findings against it; the private platform (auditer + kontrol) parses them against the same schema. Single-sourcing the contract in one published package keeps both sides from forking it.

The shape

A Finding is a zod discriminated union on provenance:

• deterministic — an automated rule engine surfaced it. Lean base metadata plus the corpus tier the rule belongs to.
• agent — the agentic tester judged it. Carries a rationale and an optional natural-language suggestion; no corpus tier.

Both arms share the metadata aligned to the persisted agentic_finding model: criterion (WCAG SC), severity, element (a DOM locator, never source), evidence, and the declared scan scope.

Metadata-only by construction

Every object is .strict(), so the schema is a closed allowlist with no field capable of carrying customer source, and no unknown key can be smuggled in — a payload bearing a source snippet fails the parse. This is the zero-data-retention guarantee made structural, not promised in prose.

Usage

import { parseFindingPayload } from "@binclusive/a11y-contract";

// Parse untrusted input at the trust boundary (throws ZodError on any violation).
const payload = parseFindingPayload(await request.json());
for (const finding of payload.findings) {
  if (finding.provenance === "agent") console.log(finding.rationale);
}