CodeRifts Decision Spec

Decision Object (Public Layer)

Every CodeRifts analysis returns a Decision Object. The public fields are stable, versioned, and free to consume without authentication.

{
  "coderifts_version": "1.0",
  "decision": "BLOCK",
  "risk_score": 87,
  "safe_for_agent": false,
  "breaking_changes": 3,
  "patterns": [
    "AUTH_SCOPE_REDUCTION",
    "FIELD_REMOVED",
    "ENDPOINT_REMOVED"
  ],
  "requires_migration": true,
  "timestamp": "2026-03-18T10:00:00Z"
}

Field Definitions

Decision Values

safe_for_agent Flag

safe_for_agent: false is set when any of the following agent-breaking patterns are detected:

• • Tool schema drift (TOOL_CALLING_SCHEMA_DRIFT)
• • Tool result shape change (TOOL_RESULT_SHAPE_DRIFT)
• • Agent protocol change (AGENT_PROTOCOL_DRIFT)
• • Workflow chain break (WORKFLOW_CHAIN_BREAK)
• • Auth delegation change (AUTH_DELEGATION_DRIFT)
• • Shared state schema change (SHARED_STATE_SCHEMA_DRIFT)

Pattern Registry (v1.0)

Patterns are named identifiers for categories of breaking changes. They are stable across spec versions.

Contract Patterns

Agent Patterns

Behavioral Patterns (roadmap — requires traffic capture)

Extended Decision Object (Authenticated)

With an API key, the full decision object is returned including blast radius, migration plan, compliance index, and workflow simulation:

{
  "coderifts_version": "1.0",
  "decision": "BLOCK",
  "risk_score": 87,
  "safe_for_agent": false,
  "breaking_changes": 3,
  "patterns": ["AUTH_SCOPE_REDUCTION", "FIELD_REMOVED"],
  "requires_migration": true,
  "timestamp": "2026-03-18T10:00:00Z",

  "extended": {
    "omega_api": 87.3,
    "reflex_triggers": [
      { "rule": "endpoint_removed ∧ public_api", "decision": "BLOCK" }
    ],
    "blast_radius": {
      "affected_consumers": 4,
      "estimated_cost": "$12,000–$45,000",
      "migration_effort_days": 8
    },
    "migration_plan": "Restore removed field as deprecated with x-sunset date. Notify consumers via POST /api/v1/scar/create.",
    "compliance_index": "F",
    "workflow_simulation": {
      "simulation_result": "WORKFLOW_BROKEN",
      "first_failure_step": 2
    }
  }
}

Configurable heuristic estimate (engineer rate × migration hours) — see methodology

What the fingerprint covers

The verdict_fingerprint is a SHA-256 hash computed over the canonical verdict core: the decision, per-module risk scores, gate results, and the aggregation values — nothing else.

Transport metadata is deliberately outside the hash: timestamps, correlation IDs and the receipt signature are not fingerprint inputs. The Ed25519 receipt signs over the fingerprint — a downstream step, never an input to it.

The same analysis therefore yields a byte-identical fingerprint across runs, regardless of when it ran or which receipt attests it. Determinism lives in the verdict core; freshness lives in the receipt.

How Agents Should Use This Spec

Step 1: Preflight Check Before Tool Call

POST https://app.coderifts.com/api/v1/agent/preflight
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "tools_before": [ /* previous tool schemas */ ],
  "tools_after": [ /* current tool schemas */ ]
}

Step 2: Parse the Decision

const { decision, safe_for_agent, patterns } = response;

if (!safe_for_agent || decision === "BLOCK") {
  throw new Error(`API change blocks agent execution. Patterns: ${patterns.join(", ")}`);
}

if (decision === "REQUIRE_APPROVAL") {
  await requestHumanApproval(response);
  return;
}

// ALLOW or WARN — proceed
await callAPI();

Step 3: Handle BLOCK Gracefully

if (decision === "BLOCK") {
  // 1. Log the block with full decision object
  // 2. Notify the team
  // 3. Do not retry — human review required
  // 4. Check extended.migration_plan for remediation steps
}

Integration Examples

LangChain

from langchain.tools import tool
from coderifts import CodeRifts

coderifts = CodeRifts(api_key="cr_live_...")

@tool
def safe_api_call(endpoint: str, payload: dict):
    """Call an API endpoint with CodeRifts governance check."""
    result = coderifts.preflight_change_set(
        artifacts=[{
            "id": endpoint,
            "type": "openapi",
            "before": get_cached_schema(endpoint),
            "after": get_current_schema(endpoint),
        }],
    )
    # Branch on execution_action (proceed); decision explains why.
    action, decision = result.execution_action, result.decision
    # CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
    # (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
    if action != "CONTINUE":
        return {"error": f"CodeRifts aborted: execution_action={action!r} (decision={decision})"}
    if not result.safe_for_agent:
        return {"error": f"Blocked by CodeRifts. Decision: {decision}"}

    return call_endpoint(endpoint, payload)

AutoGen

import autogen
from coderifts import CodeRifts

coderifts = CodeRifts(api_key="cr_live_...")

def coderifts_preflight_hook(agent, message):
    result = coderifts.preflight_change_set(
        artifacts=message["artifacts"],  # [{id, type, before, after}, ...]
    )
    # Branch on execution_action (proceed); decision explains why.
    action = result.execution_action
    # CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
    # (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
    if action != "CONTINUE":
        raise ValueError(f"CodeRifts aborted: execution_action={action!r} (decision={result.decision})")
    return message

agent = autogen.AssistantAgent(
    name="SafeAgent",
    pre_message_hooks=[coderifts_preflight_hook]
)

Claude / MCP

{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Add the instruction below to your agent's system prompt to have it run preflight_change_set before tool invocations.

Auto-Discovery

Agents can discover CodeRifts governance endpoints automatically:

GET https://coderifts.com/.well-known/coderifts.json

Returns the full manifest including available tools, endpoints, and this spec URL.

Versioning Policy

• • This is v1.0. The public layer fields (decision, risk_score, safe_for_agent, breaking_changes, patterns, requires_migration) are stable and will not change in v1.x.
• • New fields may be added in minor versions (v1.1, v1.2) without breaking existing consumers.
• • Breaking changes to the spec format will only occur in major versions (v2.0) with 6 months notice.

Changelog

Links

• API Reference
• MCP Manifest
• Well-Known Discovery
• Agent Frameworks Integration
• GitHub