# CodeRifts

> AI Agent Infrastructure Safety — PR-native API governance that scores and signs contract-change decisions so agents and humans can act on them.

CodeRifts is a GitHub App that analyzes contract changes in pull requests, scores blast radius, and posts a signed BLOCK / WARN / ALLOW / REQUIRE_APPROVAL report on every PR. An install delivers that report path (comment + check run) by default — it does not, by itself, block merges. Blocking a merge is a separate, optional configuration: a required status check bound to the App, an analysable schema, and admin enforcement. See https://coderifts.com/docs/enforcement-status/#make-the-check-block and https://coderifts.com/docs/what-each-path-does/ — do not treat a red PR comment as a merge gate.

## What an install delivers vs what blocking requires

- **Install delivers:** a signed governance report on each PR that changes analysable contracts (PR comment + check run). No CI YAML required for the report path. Visibility for reviewers and agents.
- **Install does not deliver:** automatic merge blocking. GitHub still allows merge until branch protection is set up correctly.
- **Merge blocking** needs the conditions documented at https://coderifts.com/docs/enforcement-status/#make-the-check-block (required check, App binding, analysable schema, enforce_admins). This file does not restate the four steps — that page is the source.
- **Runtime prevention of a tool call** is a different path: `@coderifts/agent-guard`. PR reports alone do not stop an agent from calling a broken API.

## What CodeRifts does (and does not claim)

- Detects breaking OpenAPI (and related contract) changes in PRs and on preflight APIs
- Scores risk using the Ω_API engine (risk 0–100) under the supplied evidence
- Emits Decision Spec v2 preflight responses (mode-discriminated: analyze is risk-only; authorize carries decision + execution_action and may mint a receipt)
- Posts signed verdicts / receipts so a third party can verify the decision was issued, not invent a new one
- Does **not** block merges by install alone — see above
- Does **not** prove that every possible API break is found — coverage depends on schema presence, configuration, and path

## Capabilities beyond a local diff engine

Each item states what it does and what it does **not** prove. A bare capability list without limits is marketing.

### Signed verdicts and Change IR
- **Does:** Records a canonical change intermediate representation (Change IR); chain receipts can bind an IR hash under Ed25519 so the analyzed change set is tamper-evident after the fact.
- **Does not prove:** That the change was safe, that production matches the specs, or that a human acted correctly. Signature authenticity ≠ currently authorized for a new operation (verify with intended context).

### Semver-violation forensics
- **Does:** When a breaking change ships under a non-major version bump, records a forensic finding (e.g. BREAKING_IN_NONMAJOR) that can be cited later; can be covered by the signed receipt.
- **Does not prove:** Merge policy. The finding is forensic — it does not by itself change the merge verdict or risk score. The breaking change drives the decision; the semver record only notes that the version number failed to signal it. Details: https://coderifts.com/blog/what-is-a-semver-violation/

### MCP poison gate
- **Does:** On MCP manifest diffs, escalates unambiguous poison (hidden instructions / exfiltration-class signals in tool text) to BLOCK and sets safe_for_agent false so a careful agent can halt before running the tool. Heuristic anomalies can escalate to REQUIRE_APPROVAL.
- **Does not prove:** Runtime safety if the agent ignores the verdict. Does not catch attacks that never appear as a description/schema change. Merge blocking still requires the check to be a configured gate (same install vs block distinction as above). See https://coderifts.com/what-is-mcp-tool-poisoning/

### Declared consumer graph
- **Does:** When a consumer dependency manifest is declared (e.g. cross-service config), surfaces affected consumers and blast-radius style context on the **PR comment and check summary**.
- **Does not prove:** Completeness of your real service mesh. Only declared consumers are known. **Not returned on the anonymous preflight response** — deliberately: exposing who depends on a repository to unauthenticated callers would be a reconnaissance surface.

### Traffic capture (conditional)
- **Does:** Where enabled, can support traffic-informed analysis paths (inferring observed API shape against the declared spec). Gated by product flags (e.g. BETA_MODE) and requires an API key — not part of bare GitHub App install alone.
- **Does not prove:** Full OpenAPI generation from traffic as a drop-in for every host (that remains a separate / roadmap-class workflow on the public site). Without capture configured, static-spec analysis still runs; behavioral patterns that need traffic stay unavailable.

### Session taint (runtime package)
- **Does:** In `@coderifts/agent-guard`, session-taint tracking can flag multi-step contract mutation patterns that single-call detection alone would miss (process-local session state).
- **Does not prove:** Cross-process or cross-host session continuity. Does not replace cloud preflight. Does not see tools outside the guarded table.

## Measured real-world accuracy

**Number (bucket `real_vendor` only):** TP=31 FP=0 TN=19 FN=0 · precision 100.0% · recall 100.0% · F1 100.0%.

**Sample size:** n=50. That is the publishable slice of a 64-case offline corpus. The other 14 cases are `spec_conformance` (`ground_truth.type` = `spec_rule`) and are **not** included in the number above. Do not blend the buckets.

**Method:**
- **External ground truth.** Each `real_vendor` case is typed `provider_changelog` and carries a citation to the provider's own breaking-change / changelog declaration (sources in this corpus: GitHub REST API, Stripe API, Kubernetes API). Labels are not CodeRifts labels of CodeRifts outputs.
- **No precision target in the measurement suite.** The suite prints the confusion matrix; it does not assert "precision above X". The number is what was measured.
- **Corpus self-checks.** Batches must not overlap by id; ground-truth fields must be present. Those checks defend against quiet relabelling and double-counting.
- **Regression ratchet (separate from measurement).** Pinned baseline counts: a drop fails; an improvement also fails until the baseline is updated deliberately; adding or removing cases fails as a composition change. The pin cannot drift unnoticed.
- **Offline path.** Same in-process contract-diff path the product uses for these specs; no network and no API keys for the corpus run.

**Scope (does not prove):** Generalisation to every API, every change type, or change shapes not present in these fifty provider-changelog cases. Fifty vendor cases is fifty vendor cases.

## Decision Spec v2 (preflight)

`preflight_mode` is **required** on every preflight (`analyze` | `authorize`). Mode-less → **400**. Default is Decision Spec 2.0: analyze omits `decision` / `execution_action` / `safe_for_agent` and cannot be read as permission. A request that pins `decision_spec_version: "1.0"` still gets the pre-v2 analyze shape (`decision` / `execution_action` / `safe_for_agent` in the body and in `x-coderifts-decision` / `x-coderifts-safe-for-agent`). Deprecation headers fire (`Deprecation: true`, `Sunset: 2026-09-07T00:00:00Z`, `successor-version` link). The announced sunset was **2026-09-07T00:00:00Z**; the pin is still answering as of 2026-09-14. Do not pin 1.0. If you read a response you did not request, branch on `preflight_mode` first.

Responses are a **discriminated union** on `preflight_mode` (JSON Schema oneOf). **Analyze is not permission.**

### ANALYZE (informational)

```json
{
  "preflight_mode": "analyze",
  "decision_spec_version": "2.0",
  "analysis_outcome": "NO_BREAK_DETECTED | BREAKS_DETECTED | ANALYSIS_FAILED",
  "authorization_effect": "NONE",
  "may_execute": false,
  "receipt_kind": "NONE",
  "risk_score": 0,
  "breaking_changes": 0,
  "patterns": []
}
```

- Omits `decision`, `execution_action`, and `safe_for_agent` (structural — schema-invalid if present).
- Branch on `may_execute` / `analysis_outcome` for risk handling only. Never treat analyze as permission to merge, deploy, or call tools.
- Risk classification is `analysis_outcome` (+ risk payload), not an authorize `decision`.

### AUTHORIZE (operation-bound)

```json
{
  "preflight_mode": "authorize",
  "decision_spec_version": "2.0",
  "receipt_kind": "operation_authorization",
  "decision": "ALLOW | WARN | REQUIRE_APPROVAL | BLOCK",
  "execution_action": "CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP",
  "safe_for_agent": true,
  "risk_score": 0,
  "chain_receipt": "",
  "breaking_changes": 0,
  "patterns": []
}
```

- Requires `context.operation`. Branch on `execution_action`; use `decision` as explanation.
- Permission requires the authorize path and a **verified** receipt: receipt present AND `currently_authorized` AND operation match AND fingerprint match AND allow-class `execution_action`. No single field alone permits proceed.
- **BLOCK / STOP do not automatically stop a GitHub merge** unless the check is configured as a merge gate.

Schema: https://coderifts.com/schemas/preflight-response.v2.consumer.json

## How AI agents can use CodeRifts

- Auto-discovery: GET https://coderifts.com/.well-known/coderifts.json
- Public preflight (no auth): GET https://app.coderifts.com/api/v1/public/preflight
- JSON Schema: GET https://coderifts.com/decision-spec/v2.0.json
- How agents use this: https://coderifts.com/decision-spec/how-agents-use-this/
- MCP manifest: https://coderifts.com/mcp.json
- Path honesty map: https://coderifts.com/docs/what-each-path-does/

## SDKs

- Runtime guard (can prevent a tool call through its table): npm install @coderifts/agent-guard
- Node.js/TypeScript: npm install @coderifts/sdk
- Python: pip install coderifts-sdk
- CLI: npm install -g coderifts

## Integrations

- GitHub App: https://github.com/apps/coderifts
- LangGraph / AutoGen / CrewAI: https://coderifts.com/integrations/agent-frameworks/
- VS Code: https://coderifts.com/integrations/vscode/
- Backstage: https://coderifts.com/integrations/backstage/

## Key pages

- https://coderifts.com/decision-spec/ Decision Spec v2.0 full documentation
- https://coderifts.com/portable-verification/ Portable Proof of Authorization — independent Ed25519 chain-receipt verification
- https://github.com/coderifts/receipt-verifier Independent receipt verifier (Node + Python) and frozen RECEIPT_FORMAT.md
- https://coderifts.com/docs/what-each-path-does/ What each path does and does not (report vs prevent)
- https://coderifts.com/docs/enforcement-status/#make-the-check-block Make the Check Block a Merge
- https://coderifts.com/benchmark/ Global OpenAPI Benchmark — public specs via APIs.guru; sample size is live on the page (not a fixed count here). Breaking-rate and risk percentiles shown there are industry reference defaults until measured from the dataset.
- https://coderifts.com/features/archeology/ API Archeology
- https://coderifts.com/counter/ Global Break Monitor

## Capability pages (what ships, and where it stops)

Each page below states its own boundary. Read them before assuming a capability prevents rather than reports. The report-vs-prevent map itself lives at https://coderifts.com/docs/what-each-path-does/ and is not restated here.

- https://coderifts.com/docs/claim-table/ Two blocks, never mixed. Enforced today: fail-closed authorization-execution gate (grant → consume → target-state → offline readback; without the receipt the mutator does not run). Roadmap (planned / on-request, not available): tool-call binding, cross-domain evidence bundle, agent→agent delegation attenuation, TRACE bridge. Roadmap rows carry no proof claims. VERIFY.md: https://github.com/coderifts/conformance/blob/conformance-v0.8.6/VERIFY.md
- https://coderifts.com/docs/proof-boundaries/ What each proof proves and what it does not. Per proof type: the exact claim, the exact non-claim, and the fail-closed behaviour on malformed, unknown-kid, bad-signature, wrong-scope or mismatched-binding evidence. A suppressed gate does not disable the other gates. Public 7/7: `@coderifts/conformance@0.8.11` `END_TO_END COVERED` via `TARGET_STATE_TRANSITION_PROVEN` (`proof_scope TRUSTED_EXECUTOR`, `provider_witness NOT_APPLICABLE`, `externally_witnessed false`). Trusted-executor-integrity, not a provider merge (PATH B), not externally witnessed, not the GitHub provider-loop. CodeRifts did not witness or sign the provider state. Anchor: https://coderifts.com/docs/proof-boundaries/#conformance-end-to-end
- https://coderifts.com/docs/platform-truth-table/ Which layer actually enforces on which platform, and which only reports. The boundary between a posted verdict and a prevented action, stated per path.
- https://coderifts.com/docs/deploy-gate/ The deploy gate evaluates a deploy whose receipt is stale or mismatched. Advisory by default (phase-1); enforcement is opt-in. `coderifts deploy-gate` gates on the current { environment, artifact } using a preflight receipt.
- https://coderifts.com/docs/enforcement-status/ `coderifts status` is a read-only cross-layer enforcement report for Runtime, Merge, Deploy and Content. It prints measured statuses only: no GitHub writes, no branch-protection changes. Dry-run-first path to close setup gaps.
- https://coderifts.com/docs/remediation-transaction/ A BLOCK is not a dead end. The envelope names the required contract fixes; the same input re-submitted is still a BLOCK (deterministic); a modified input triggers a NEW preflight, not permission; disputes escalate to human review.
- https://coderifts.com/docs/execution-attestations/ CAS attestation proves linkage of a frozen execution proof with a conditional-write outcome (authorized_and_committed only on a clean committed branch). Remediation-loop attestation proves typed closure linking a prior BLOCK's remediation transaction to a later ALLOW execution chain.
- https://coderifts.com/docs/synaptic-weight/ Each changed endpoint receives a 0-100 criticality weight and a band; high-weight endpoints are highlighted on the PR as outsized downstream impact. Surfacing, not scoring the verdict.
- https://coderifts.com/docs/mcp-poison-gate/ Assesses an MCP tool manifest for poisoning risk and flags the tools that deserve review, through lockfile drift monitoring. MCP tool-poisoning is malicious instruction content hidden in a tool description or schema that an agent may ingest as trusted.
- https://coderifts.com/agents/contract-lock/ `coderifts lock` fetches an observed agent-contract lockfile (coderifts.lock v1) pinning the agent-contract surface your agents actually touched, and checks MCP drift of a locked manifest against a live one.
- https://coderifts.com/agents/execution-proof/ When a guarded call produces a machine GuardExecutionProof, the guard can attach a human-readable proof block to the agent's final answer: proof spec, preflight and receipt fields, currently_authorized, the bound operation and change_fp. Limits stated structurally.
- https://coderifts.com/agents/onboarding/ Four-step onboarding ladder from keyless discovery to receipt-gated governance: inspect one public spec without an account, move to authenticated preflight, ask for an operation-bound decision, then use the portable verification pointers. Each step states what you can and cannot yet do.

---

## Agent-relevant API endpoints

All endpoints are at `https://app.coderifts.com/api`. Auth = API key required via `Authorization: Bearer <key>` header unless noted. This is the agent-relevant surface — not the full product API.

- POST /v1/public/preflight — Auth: no — Keyless quick check (POST body with specs)
- POST /v1/diff — Auth: yes — Contract diff between two OpenAPI specs
- POST /v1/agent/preflight — Auth: yes — Agent tool-schema preflight
- POST /v1/agent-readiness-score — Auth: yes — Readiness scoring for an API spec
- POST /v1/mcp-diff — Auth: yes — MCP manifest comparison
- POST /v1/registry-validate — Auth: yes — Multi-spec validation REST endpoint (live). As an MCP tool, the modern path is `preflight_change_set` (the MCP tool name `registry_validate` maps to this hyphen route and is a deprecated/hidden alias of that); this REST route itself is not deprecated.
- GET /v1/score-mcp?url= — Auth: no — Score a public MCP manifest by URL (keyless; 10 req/min per IP). POST returns 404.
- GET /v1/decision-spec/schema — Auth: no — Permanent redirect (308) to https://coderifts.com/decision-spec/v2.0.json; no schema body on this path. Legacy curated v1.0 remains at https://coderifts.com/decision-spec/v1.0.json (opt-in `decision_spec_version:"1.0"`; announced sunset 2026-09-07T00:00:00Z; still answering as of 2026-09-14; do not pin 1.0).
- GET /v1/system-prompts — Auth: no — Copyable agent system prompts
- GET /v1/ledger — Auth: yes — Decision audit trail

MCP tools (canonical): `preflight_change_set`, `verify_receipt`, `get_decision_details` — advice unless the host treats the verdict as binding. They do not by themselves prevent a merge or a tool call.

## Runtime prevention (`@coderifts/agent-guard`)

The endpoints above are **advice**: they return a governance decision an agent can read. They do not stop a tool call by themselves.

**Prevention** is a different layer. The npm package `@coderifts/agent-guard` wraps the agent's tool table so a contract-affecting call cannot execute without a verdict. `withCodeRifts` is the one-call entry point: it runs the frozen registry over your tools, returns only the protected table, and reports a narrower composition-level assurance separately from the registry's own coverage.

Honesty boundary: edits that already carry both sides (e.g. old_string/new_string) can be evaluated; calls the guard cannot analyse are **stopped**, not allowed. Do not treat a green construction as proof that every tool call is protected.

Receipt carry-forward is shipped (guard@8): withCodeRifts keeps a per-composition receipt_thread cursor (default on) and supplies it as the previous_receipt field on the next preflight. Authorize envelopes name receipt_kind (operation_authorization | NONE). The cursor is a token handle, not product-truth chain authenticity (no package self-attestation; concurrent overlap refuses to advance).

Remaining composition gaps: write-style prior content / freshness stays opt-in unless profile ENFORCING_STRICT plus a host resolvePriorContent (conditional write / CAS is a host assertion — the package never writes). Host-invoked raw tools registered outside the returned table remain invisible. composition_assurance.inescapable_runtime stays false.

Post-commit observation is shipped (guard@8.2): after the host write returns, the guard re-reads the target and compares it to the authorized after — content on filesystem adapters, version token on API/DB/Registry adapters — reporting commit_observation.status as not_observed | observed_match | observed_drift | observed_token_match. On content drift it re-runs preflight against the observed state (commit_observation.blast). enforced is unchanged: it stays a pre-write fact (receipt-verified ALLOW/MONITOR plus the T2 recheck), and commit_observed_drift is report-only, not a permission gate. Default on; opt-out requireCommitObservation:false emits commit_observation_check_disabled. Limit (limits.commit_observation_is_observed_at_t3_not_atomic): commit_observation is observed at T3, not atomic: another writer may act between write and observation; token-only adapters compare version token not content; host attestation is a host claim layered on the measurement.

## Merge gate (phase 1 honesty)

- **CodeRifts — API Contract Check:** can block merges only when configured as a required, App-bound check with an analysable schema and admin enforcement (see docs link above).
- **CodeRifts / contract-gate:** additional PR check that is **advisory in phase 1** (does not fail closed as a merge gate today). Do not require it expecting a red check to stop the merge.

---

## Decision Spec v2.0 JSON Schema

Canonical curated schema (single source — do not re-embed here; drift risk):

- GET https://coderifts.com/decision-spec/v2.0.json
- Alias: GET https://app.coderifts.com/api/v1/decision-spec/schema → 308 to the same v2.0 document
- Full structural producer (mode oneOf): https://coderifts.com/schemas/preflight-response.v2.producer.json
- Consumer: https://coderifts.com/schemas/preflight-response.v2.consumer.json
- Legacy v1.0 (opt-in via decision_spec_version:"1.0"; announced sunset 2026-09-07T00:00:00Z; still answering as of 2026-09-14; do not pin 1.0): https://coderifts.com/decision-spec/v1.0.json

---

## AIDE instability patterns (13 named patterns)

The AIDE (API Instability Detection Engine) detects 13 named instability patterns across four dimensions: latency, payload size, error rate, and token usage. These paths need live traffic / instability signals — they are not the same as static OpenAPI PR analysis.

### Threshold-based patterns (4)

1. LATENCY_REGRESSION (HIGH) — Latency dimension score exceeds threshold. Indicates sustained response time degradation beyond normal variance.
2. PAYLOAD_FLAKINESS (MEDIUM) — Payload dimension score exceeds threshold. Response body sizes are inconsistent, suggesting schema instability or conditional field inclusion.
3. ERROR_RATE_SPIKE (CRITICAL) — Error rate dimension score exceeds threshold. Error rates have spiked significantly, indicating service degradation or upstream failures.
4. TOKEN_COST_DRIFT (HIGH) — Token dimension score exceeds threshold. Token consumption is drifting, suggesting changes in query complexity or response verbosity.

### Composite pattern (1)

5. SYSTEMIC_INSTABILITY (CRITICAL) — Instability score > 75 AND 3+ dimensions score > 50. Multiple dimensions are unstable simultaneously, indicating a systemic issue rather than an isolated regression.

### AIDE V3 advanced patterns (8)

6. SILENT_DATA_LOSS (CRITICAL) — Payload CV > 0.2 AND trend slope < -0.05. Payload size is trending down, meaning responses may be silently truncating data or dropping fields.
7. ZOMBIE_ENDPOINT (HIGH) — Latency CV < 0.05 AND error rate CV > 0.8. Endpoint responds at consistent speed but error rate is erratic — may be returning cached errors or static error pages.
8. SESSION_INSTABILITY (HIGH) — Error rate trend slope > 0.03 AND error rate z-score max > 2.0. Error rate is trending upward, suggesting session management issues or auth token expiry.
9. CHANGE_INDUCED_FLAKINESS (HIGH) — change_induced = true AND instability score > 60. Instability correlates with a recent deployment — rollback may be needed.
10. BLOATED_RESPONSE (MEDIUM) — Payload CV < 0.1 AND trend slope > 0.08. Response size is growing consistently, indicating schema bloat or unintended data exposure.
11. AUTH_DRIFT (CRITICAL) — Error rate z-score max > 3.0 AND anomaly count >= 2 AND change_induced = false. Spontaneous error spikes without deployment — auth token rotation or certificate expiry likely.
12. INTERMITTENT_SLOWDOWN (MEDIUM) — Latency z-score max > 3.0 AND CV > 0.2 AND trend slope < 0.02. Latency spikes detected without upward trend — likely GC pauses, cold starts, or connection pool exhaustion.
13. TRAFFIC_SHIFT (MEDIUM) — Token trend slope > 0.1 AND CV > 0.3. Token usage is growing with high variance — agent query patterns may have changed.

---

## Pricing tiers

All Pro and Team features are free during beta. No credit card required.

- Free — $0 forever — Breaking change detection, PR comments, 1,000 API requests/month, community support
- Pro — $49/month, unlimited repos, per org — Everything in Free plus: Ω_API scoring, reflex rules, compliance ledger, agent governance, instability detection, priority support
- Team — $79/month, unlimited repos, per org — Everything in Pro plus: cross-repo checks, freeze windows, team dashboards, SSO, dedicated support
- Enterprise — $999–3,000/org/month — Everything in Team plus: on-premise deployment, custom integrations, SLA guarantees, dedicated account manager