Community · E2 · artifact verified

Catch contract drift hidden in OpenAPI prose

OAS Sentinel compares two OpenAPI documents in two layers: deterministic checks find structural breaks, and Jev answers bounded semantic questions about changed prose - retries, ordering, pagination, error meaning - that schema diffs cannot see.

01 · Role in the system

What Jev does here

Structural compatibility is checked deterministically; the semantic layer sends bounded questions to Jev about what changed in descriptions, examples, defaults, retry behavior, ordering, pagination, authorization, and error semantics. Jev never writes a review and never changes a specification - it returns typed decisions with probabilities, and deterministic Python decides whether to pass, request review, or block. The output is a counts table plus per-operation findings, available as markdown or SARIF. A dry-run mode needs no API key: it shows exactly which changed prose would be sent for semantic review. The reproducible benchmark suite exercises ten semantic-only contract changes, and a separate repository verifies the published GitHub Action and SARIF upload from a real consumer workflow. Ships on PyPI and the GitHub Marketplace as an independent, unaffiliated community project.

Schema diffs stop where prose begins

Two OpenAPI documents can be structurally identical and mean different things: a retry note quietly added, pagination semantics changed in a description, an error's meaning rewritten. OAS Sentinel splits the work accordingly — deterministic checks own structural compatibility, and Jev answers bounded semantic questions about what changed in prose: retries, ordering, pagination, authorization, error meaning.

The model never writes a review and never edits a specification; it returns typed decisions with probabilities, and Python turns them into pass, request-review, or block, emitting markdown or SARIF. The dry-run mode is the deployment-safety detail worth copying: with no API key it shows exactly which changed prose would leave your machine for semantic review, before you enable any of it.

Ten hand-built changes is a demo, and it says so

The benchmark suite is ten hand-built semantic changes — a demonstration that each question class fires, not a corpus study of real API evolution, and the record draws that line itself. It ships on PyPI and the GitHub Marketplace as an explicitly unaffiliated community project, with a separate repository verifying the published Action from a real consumer workflow.

As the developer-tools cluster's only contract-diff record, it shows judgment extending a deterministic checker into territory regexes cannot reach — with the data-egress question answered by a dry-run instead of a privacy policy.

02 · Control boundary

Where Jev sits

Deterministic diff first; bounded semantic questions to Jev second; deterministic code turns typed answers into pass, review, or block with SARIF output.

Code owns the loop, permissions, thresholds, validation, and side effects. Jev owns only the bounded judgments described above.

03 · Known limits

What this evidence does not prove

  • Semantic review needs an API key and sends the changed prose of your specification to the provider; the dry-run shows the scope before you enable it.
  • The benchmark suite is ten hand-built semantic changes, not a corpus study.
  • An independent community project, explicitly unaffiliated with TypeSafe AI, in early status.

04 · Attribution

Public sources

This is a Community record: the project was published by a third-party community author.