Decide

decide.fyi Decision API

Deterministic Decision API engine powering workflow applications, stable MCP notary remotes, decision memo packets, and execution gates

Positioning: Decide is the API engine and compatibility surface. Krafthaus workflow apps, Policy MCP Notaries, decision memo packets, and execution gates are application surfaces that reuse the same verdict, request ID, and evidence contract.

Production Determinism Boundary

Binding production verdicts should use a versioned declarative rulebook:

Runtime architecture: see docs/RULEBOOK_RUNTIME_ARCHITECTURE.md. Machine-readable schema: https://api.decide.fyi/schemas/rulebook-v1.schema.json. Active runtime manifest: https://api.decide.fyi/manifests/rulebook-runtime-v1.json. Downstream application binding: decide_application_binding_v1.

The production core is hybrid_declarative_rulebook_with_trusted_adapters: direct declarative rulebooks are supported, registered first-party trusted adapters may supply bounded facts, and customer executable rulebooks are rejected. In both supported binding modes, Rulebook v1 remains the only binding verdict selector.

{
  "mode": "rulebook",
  "rulebook": {
    "schema_version": "rulebook_v1",
    "rulebook_id": "pricing_exception",
    "version": "2026-06-11",
    "input_schema": {
      "required": ["discount_percent"],
      "properties": {
        "discount_percent": { "type": "number" }
      }
    },
    "rules": [
      {
        "rule_id": "approve_standard_discount",
        "priority": 50,
        "condition": {
          "field": "discount_percent",
          "operator": "lte",
          "value": 15
        },
        "outcome": {
          "decision": "yes",
          "verdict": "APPROVE",
          "action": "approve_discount",
          "reason_code": "WITHIN_STANDARD_LIMIT"
        }
      }
    ],
    "default_outcome": {
      "decision": "review",
      "verdict": "REVIEW",
      "action": "route_to_owner",
      "reason_code": "NO_RULE_MATCHED"
    }
  },
  "context": {
    "inputs": {
      "discount_percent": 10
    }
  }
}

mode: "rulebook" does not call an LLM. It validates the request rulebook against the published JSON Schema, hashes the rulebook, evaluates bounded conditions, and returns yes, no, or review alongside the application verdict, action, reason code, matched rule, and evaluator_version. Responses also include rulebook_contract with the enforced schema URL/hash, runtime_binding with the direct or trusted-adapter binding mode, input_hash, a SHA-256 hash of the canonical inputs or adapter facts consumed by the declarative evaluator, plus a rulebook_attestation_v1 bundle hash over the deterministic execution tuple. Production deployments can sign that bundle hash with a rulebook_attestation_signature_v1 Ed25519 envelope; verification keys are published at /.well-known/rulebook-attestation-keys.json. Set DECIDE_RULEBOOK_ATTESTATION_SIGNATURE_REQUIRED=true in production to fail closed instead of returning unsigned Rulebook decisions. Publish retired public verification keys with DECIDE_RULEBOOK_ATTESTATION_KEY_HISTORY_JSON so older Decision Records remain verifiable after rotation.

Rulebook requests cannot preload Decide-generated Decision Record material. Fields such as runtime_binding, trusted_adapter, adapter_facts, rulebook_attestation, application_verdict, and action are response-only at the request body, context.inputs, and adapter-facts boundaries; attempts return RULEBOOK_OUTPUT_MATERIAL_FORBIDDEN.

Legacy single, multi, and runtime requests remain available for AI-assisted exploration, but they are not binding production verdicts. Those responses include decision_contract with authority: "advisory_only" and production_verdict: false, plus production_binding_required: true and the supported production binding modes; callers that need deterministic execution must use mode: "rulebook" and capture rulebook_contract, runtime_binding, and the Rulebook attestation material.

At the public Decision Record boundary, successful evaluations are registered as immutable tenant-scoped snapshots. Historical replay restores the original canonical input and stored rulebook snapshot rather than trusting a caller override or the current application deployment.

Rulebook v1 also supports registered first-party trusted adapters for bounded fact normalization. Adapter requests pin an exact semantic version and manifest hash; responses attest the bundled implementation source hash plus canonical input/output hashes and the enforced execution contract. Each invocation runs once in an empty-environment worker with hard time/resource limits and denied common ambient capabilities. The declarative rulebook remains the only binding verdict selector. See docs/TRUSTED_ADAPTERS_V1.md.

The current reference applications prove both production patterns: Solana Execution Gate, Decision Memo Readiness Gate, and Krafthaus Workflow Readiness Binding use trusted adapters before Rulebook v1, while the Refund, Trial, Cancel, and Return Policy MCP notaries supply normalized facts directly to Rulebook v1 and expose the signed rulebook result through their stable REST and MCP surfaces.

Before evaluator, adapter, or rulebook changes ship, run the local historical replay gate:

npm run rulebook:migration-dry-run -- --json

Use --candidate-rulebook, --candidate-adapter, and --candidate-evaluator-version to compare proposed migrations against the golden replay corpus before production routing changes.

For release gates, prefer a rulebook_migration_v1 manifest so candidate artifacts, expected drift, and approval status are reviewed together:

npm run rulebook:migration-dry-run -- --migration path/to/migration.json --json

The manifest schema is published at https://api.decide.fyi/schemas/rulebook-migration-v1.schema.json, and the dry run validates manifests against that closed schema before replay.

After production routing or runtime-contract changes ship, run the production runtime smoke:

npm run smoke:rulebook-runtime

This hits https://api.decide.fyi from outside the runtime and verifies the published hybrid_declarative_rulebook_with_trusted_adapters manifest, closed Rulebook v1 schema, attestation key endpoint, direct declarative evaluation, executable-rulebook rejection, and advisory-only contract metadata on legacy AI-assisted responses. GitHub Actions also runs this as the scheduled/manual Rulebook Runtime Production Smoke workflow.

The legacy single, multi, and runtime modes are AI-assisted surfaces. They are not the production determinism boundary for loosely defined business judgment.

Architecture:

• Ecosystem constitution
• Application binding contract
• Rulebook v1 contract
• Rulebook compatibility policy
• Rulebook migration examples
• Rulebook migration manifest

One-Click Install

Buttons install the Refund Notary server. To add all 4 servers, use the JSON config below.

Stable MCP Remotes

All servers: 100 vendors, US region, individual plans, stateless, no auth, 100 req/min. Runtime contracts and reference evidence stay here.

Quick Start

Connect via MCP (Claude Desktop / Windsurf / other clients)

{
  "mcpServers": {
    "refund-decide": { "url": "https://refund.decide.fyi/api/mcp" },
    "cancel-decide": { "url": "https://cancel.decide.fyi/api/mcp" },
    "return-decide": { "url": "https://return.decide.fyi/api/mcp" },
    "trial-decide":  { "url": "https://trial.decide.fyi/api/mcp" }
  }
}

REST API

# Refund eligibility
curl -X POST https://refund.decide.fyi/api/v1/refund/eligibility \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","days_since_purchase":12,"region":"US","plan":"individual"}'

# Cancellation penalty
curl -X POST https://cancel.decide.fyi/api/v1/cancel/penalty \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","region":"US","plan":"individual"}'

# Return eligibility
curl -X POST https://return.decide.fyi/api/v1/return/eligibility \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","days_since_purchase":12,"region":"US","plan":"individual"}'

# Trial terms
curl -X POST https://trial.decide.fyi/api/v1/trial/terms \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","region":"US","plan":"individual"}'

Local Dev Checks

Start local dev server:

npx vercel dev

In a separate terminal:

# Handler-level smoke checks (no running server required)
npm run smoke

# MCP endpoint checks (requires a running server)
npm run mcp:check

# Self-contained local MCP check; starts/stops vercel dev on localhost:3000
npm run mcp:check:local

# End-to-end workflow fixture (example -> result)
npm run workflow:test

# Production customer-key verification after provisioning a key
DECIDE_SMOKE_API_KEY='<customer-key>' npm run smoke:customer-key

Zendesk Workflow Orchestrators

Use workflow endpoints when you want one request to return:

• decision classification (yes | no) from /api/decide
• policy result from the relevant notary endpoint
• recommended Zendesk action + tags + private note with request_id

Endpoints

• POST https://refund.decide.fyi/api/v1/workflows/zendesk/refund
• POST https://cancel.decide.fyi/api/v1/workflows/zendesk/cancel
• POST https://return.decide.fyi/api/v1/workflows/zendesk/return
• POST https://trial.decide.fyi/api/v1/workflows/zendesk/trial

Request

{
  "ticket_id": "ZD-9001",
  "workflow_typ

…