decide.fyi Decision API

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

Positioning: Decide Runtime is the general deterministic decision engine. Decide Services are standalone specialized checks built on it; Policy Notaries is the existing family. Krafthaus owns workflow applications built on Decide, including intake, review, and execution handoff. MCP, REST, and SDK interfaces belong to the product they expose, not automatically to Krafthaus.

See the ecosystem ownership contract. Direct service and runtime integrations do not require a Krafthaus app. Policy checks are one service family, not the definition of the general Decision API.

Gate agent tool calls before execution

Use Decide to evaluate an agent-proposed action against a deterministic rulebook before the tool receives authority to change state. The caller gets a replayable Decision Record and routes yes, no, or review while retaining control of credentials and execution.

See the AI agent action gate guide

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 always verifies the published hybrid_declarative_rulebook_with_trusted_adapters manifest, closed Rulebook v1 schema, attestation key endpoint, and protected Decision API edge. Supply DECIDE_RULEBOOK_RUNTIME_SMOKE_API_KEY to also exercise live declarative evaluation, rejection behavior, and advisory-only legacy metadata. GitHub Actions runs the public boundary checks as the scheduled/manual Rulebook Runtime Production Smoke workflow and runs the authenticated checks when its optional smoke credential is configured.

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

JavaScript SDK and CLI

The public @decide-fyi/sdk client covers Decision API calls, Decision Record and Decision Packet verification, Rulebook conformance, replay, execution receipts, and outcome reporting.

npm install @decide-fyi/sdk

The canonical package source is sdk/, licensed under Apache-2.0. Package release requirements and source mapping are documented in sdk/SOURCE_PROVENANCE.md.

One-Click Install

Buttons install the canonical four-tool Decide Policy Notaries server. Existing specialist endpoints remain supported for compatibility.

Stable MCP Remotes

Server	Domain	Tool	Verdicts
Policy Notaries	policy.decide.fyi	All 4 tools below	Policy-specific verdicts
Refund Notary	refund.decide.fyi	refund_eligibility	ALLOWED / DENIED / UNKNOWN
Cancel Notary	cancel.decide.fyi	cancellation_penalty	FREE_CANCEL / CANCEL_AT_PERIOD_END / PENALTY / LOCKED / UNKNOWN
Return Notary	return.decide.fyi	return_eligibility	RETURNABLE / EXPIRED / NON_RETURNABLE / UNKNOWN
Trial Notary	trial.decide.fyi	trial_terms	TRIAL_AVAILABLE / NO_TRIAL / UNKNOWN

Stateless, no auth, 100 req/min. Coverage is policy-specific: 100 existing US individual-plan vendors, plus scoped Typeform Basic cancellation only. Results fail closed to UNKNOWN when scope or current reviewed evidence is missing. See Typeform integration.

Quick Start

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

{
  "mcpServers": {
    "decide-policy-notaries": { "url": "https://policy.decide.fyi/api/mcp" }
  }
}

Specialist compatibility configuration

Existing installations can keep using the specialist remotes. They expose the same tool names and response contracts as the canonical suite:

{
  "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","qualifying_conditions_met":true}'

# 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","billing_cadence":"annual"}'

# 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","qualifying_conditions_met":true}'

# 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","offer_confirmed":true,"observed_trial_days":7,"observed_card_required":true,"observed_auto_converts":true}'

Only set evidence fields from facts you have actually verified. A time window alone is not proof that source-specific conditions are satisfied. Approval-dependent policies stay UNKNOWN even when a caller sets qualifying_conditions_met; trial results require a live offer observation.

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

---

Protected Zendesk Reference Workflow

The Zendesk routes are protected reference adapters. They return an advisory classification, a policy result, and a recommended Zendesk action shape, but they do not write to Zendesk, authorize execution, or create a binding production Decision Record. Every response sets workflow_contract.execution_allowed: false.

For the production architecture, including the Rulebook v1 action boundary and Decision Record that must precede a downstream side effect, see docs/POLICY_MCP_SUPPORT_WORKFLOW.md.

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_type": "refund",
  "question": "Should this Adobe annual plan refund request proceed under policy?",
  "vendor": "adobe",
  "region": "US",
  "plan": "individual",
  "days_since_purchase": 5,
  "qualifying_conditions_met": true
}

Production workflow requests require a server-to-server Bearer token:

curl -sS -X POST https://refund.decide.fyi/api/v1/workflows/zendesk/refund \
  -H "Authorization: Bearer $WORKFLOW_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @workflow-request.json

For refund and return, include days_since_purchase and source-specific condition evidence when requested. Cancellation may require billing_cadence. Trial automation requires offer_confirmed plus the observed duration, card requirement, and auto-conversion status. The workflow escalates instead of approving when required context is absent.

Test-only fixture mode

decision_override exists only for explicit local and CI tests with both NODE_ENV=test and WORKFLOW_TEST_MODE=1. It is rejected by deployed routes and must never be used as an integration mechanism.

{
  "decision_override": "yes"
}

Response (example)

{
  "ok": true,
  "flow": "zendesk_refund_v1",
  "ticket_id": "ZD-9001",
  "decision": { "c": "yes", "request_id": "req_123" },
  "policy": { "verdict": "ALLOWED", "code": "WITHIN_WINDOW" },
  "workflow_contract": { "production_verdict": false, "execution_allowed": false },
  "action": {
    "type": "approve_refund",
    "execution_allowed": false,
    "zendesk_tags": ["decide", "decide_yes", "refund_allowed"]
  }
}

---

Refund Notary

Endpoint: POST https://refund.decide.fyi/api/v1/refund/eligibility MCP Tool: refund_eligibility

Evaluates a refund only when the versioned rule and supplied source-specific facts support automation.

Input: vendor, days_since_purchase, region, plan, and conditionally qualifying_conditions_met

{"refundable":true,"verdict":"ALLOWED","code":"WITHIN_WINDOW","message":"Refund is allowed. Purchase is 12 day(s) old, within 14 day window.","vendor":"adobe","window_days":14,"qualifying_conditions_met":true,"automation_safe":true}

Codes: WITHIN_WINDOW, OUTSIDE_WINDOW, NO_REFUNDS, MISSING_REQUIRED_CONTEXT, UNSUPPORTED_VENDOR

Cancel Notary

Endpoint: POST https://cancel.decide.fyi/api/v1/cancel/penalty MCP Tool: cancellation_penalty

Checks cancellation penalties — early termination fees, contract locks, or free cancellation.

Adobe cancellation is review-only: billing cadence cannot identify its contract, timing, state-specific or renewal branch. This example is a safe review response, not a fee quote. Retired or non-current policy evidence also requires review.

Input: vendor, region, plan, and conditionally billing_cadence

{"verdict":"UNKNOWN","code":"MISSING_REQUIRED_CONTEXT","vendor":"adobe","billing_cadence":"annual","policy_decision_mode":"review_only","required_context":["manual_policy_review"],"automation_safe":false}

Codes: NO_PENALTY, EARLY_TERMINATION_FEE, CONTRACT_LOCKED, MISSING_REQUIRED_CONTEXT, UNSUPPORTED_VENDOR

Known vendor IDs are not a promise that every scope can be automated. Check automation_safe, policy_decision_mode and policy_evidence on each response. WeightWatchers refund, cancellation and return sources are retired; their history remains available, but they are no longer actively fetched or usable for new automated decisions. See scope reliability and admission.

Return Notary

Endpoint: POST https://return.decide.fyi/api/v1/return/eligibility MCP Tool: return_eligibility

Evaluates whether a subscription purchase can be reversed when the versioned rule and supplied source-specific facts support automation.

Input: vendor, days_since_purchase, region, plan, and conditionally qualifying_conditions_met

{"returnable":true,"verdict":"RETURNABLE","code":"FULL_RETURN","message":"Return is available. Purchase is 5 day(s) old, within 14-day window.","vendor":"adobe","return_type":"full_refund","method":"self_service","qualifying_conditions_met":true,"automation_safe":true}

Codes: FULL_RETURN, PRORATED_RETURN, CREDIT_RETURN, OUTSIDE_WINDOW, NO_RETURNS, MISSING_REQUIRED_CONTEXT, UNSUPPORTED_VENDOR

Trial Notary

Endpoint: POST https://trial.decide.fyi/api/v1/trial/terms MCP Tool: trial_terms

Evaluates availability and terms from a live offer observation. It does not publish static trial availability.

Input: vendor, region, plan, offer_confirmed; when confirmed, also observed_trial_days, observed_card_required, observed_auto_converts

{"verdict":"TRIAL_AVAILABLE","code":"AUTO_CONVERTS","message":"A live 7-day adobe trial offer was confirmed. Credit card required. Auto-converts to paid plan.","vendor":"adobe","trial_days":7,"card_required":true,"auto_converts":true,"offer_confirmed":true,"automation_safe":true}

Codes: AUTO_CONVERTS, NO_AUTO_CONVERT, TRIAL_NOT_AVAILABLE, MISSING_REQUIRED_CONTEXT, UNSUPPORTED_VENDOR

---

Supported Vendor Registry (101 distinct vendors)

The versioned JSON registries are the canonical vendor catalog. A compact Markdown table is intentionally not duplicated here because policy windows, channels, and approval branches can change independently. Contract tests require each policy's rules, sources and discovery to agree. Typeform is admitted for cancellation only, not refund, return or trial.

Family	Rules	Official-source registry	Automation classification
Refund	v1_us_individual.json	policy-sources.json	deterministic, conditional, review_only
Cancellation	v1_us_individual_cancel.json	cancel-policy-sources.json	deterministic, conditional, review_only
Return/reversal	v1_us_individual_return.json	return-policy-sources.json	deterministic, conditional, review_only
Trial	v1_us_individual_trial.json	trial-policy-sources.json	observed live-offer mode

• deterministic: the standard policy is categorical for the supported US individual-plan scope.
• conditional: automation requires an explicit caller assertion that the source-specific conditions were verified.
• review_only: the policy depends on approval, channel, commitment, exceptions, or source language that is not categorical enough to automate.
• observed: the current account or promotion must expose a live offer before trial terms can be returned.

Scope: US individual plans by default. Typeform cancellation has an explicit Basic, direct, self-serve platform-subscription override.

Data Freshness

Each policy family has versioned rules and source metadata. Cancellation has 101 vendor identifiers; the other three families have 100 each. The source tracker monitors official vendor documentation and terms of service; it does not automatically promote page text into a verdict.

• Daily source checks — The Daily Policy Check workflow runs once daily across refund, cancellation, return, and trial sources. Material signals enter a human review queue; fetching does not renew applicability verification.
• Human-verification freshness: npm run audit:policy-freshness reports reviewed-source age independently from tracker uptime. New policy evaluations also require current, request-bound evidence; missing or stale evidence routes to review.
• Policy source URLs tracked — Each policy family has its own sources file in rules/ linking to official policy pages.
• Compliance export — GET /api/compliance-export returns a CSV snapshot of tracked sources, hashes, and pending candidate changes (?format=json for machine-readable output).
• Versioned rules — Each rules file includes a rules_version field for staleness detection.

Architecture

• Stateless verdict runtime — Policy calls do not create sessions or mutate policy rules
• Deterministic — Same input always produces same output
• Versioned Rules — Rules files include version for tracking changes
• Scheduled Monitoring — GitHub Action checks all vendor policy pages every six hours
• Serverless — Runs on Vercel serverless functions
• Zero Dependencies — Core compute logic has no external dependencies
• Hostname Routing — Vercel middleware routes subdomains to correct MCP endpoints

Limitations