Stop bad data before an automated write.
Protect a data handoff between an external API and your database, store or business system. Zorqelio checks the exact submitted payload; your application performs the destination write only after claiming a short-lived permission.
Try the no-account inventory demonstration → · Download the runnable local example
1. Define what a good update looks like
Create an inventory contract with this schema, then create a quality policy for that contract in your workspace:
{"type":"object","required":["sku","quantity"],"properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}
Quality rules:
{"requiredFields":["sku"],"numericRanges":{"quantity":{"min":0}}}
Pin the contract and policy versions. Optional source-readiness rules add monitor freshness and health checks; they do not replace checking this payload. Publishing new schema or quality versions invalidates unclaimed permissions for the previous version.
2. Install the client
npm install https://zorqelio.xyz/downloads/zorqelio-sdk-js-0.3.0.tgz # Or Python: python -m pip install https://zorqelio.xyz/downloads/zorqelio-sdk-python-0.3.0.tar.gz
SHA-256 package checksums. These packages contain the client code only; the main application repository remains private. Existing workspace subscription and usage limits apply. A successful guarded write normally uses three API operations and one saved quality evaluation. Retries and history also consume operations.
3. Guard the actual write
import { ZorqelioClient } from "@zorqelio/sdk";
const client = new ZorqelioClient(process.env.ZORQELIO_WORKSPACE_TOKEN);
const result = await client.guardedWrite({
workflow: "supplier-sync", action: "inventory-upsert",
policyId: process.env.ZORQELIO_POLICY_ID,
policyVersion: 1, contractVersion: 1,
data: { sku: "DEMO-A", quantity: -1 }
}, "supplier-batch-2026-11-13-001", async (payload, { idempotencyKey }) => {
// This callback does not run for negative quantity.
// Your destination must enforce idempotencyKey durably with the write.
return destination.upsert(payload, { idempotencyKey });
});
// Handle blocked, already_succeeded, reconciliation_required and outcome_unconfirmed separately.
Replace the negative quantity with corrected source data and use a new operation ID to test an allowed update. Never commit tokens or expose them in browser code. Keep destination credentials in your server. The Python client offers the equivalent client.guarded_write(input, operation_id, write); its callback must be synchronous.
What happens when something fails?
- BLOCK or WARN: no protected callback. Inspect field/rule reasons, correct the source and evaluate fresh input.
- Expired, changed or rejected permission: no callback. Permissions last at most 60 seconds, can be claimed once and are bound to the input, action and version pins.
- CLAIM_NOT_CONFIRMED: no callback was attempted by the wrapper. Inspect the handoff; do not retry the claim blindly.
- WRITE_OUTCOME_UNKNOWN: a callback failed and may have already caused a side effect. Inspect the destination using the handoff ID before doing anything else.
- outcome_unconfirmed: the callback completed, but reporting its outcome failed. Reconcile the outcome without repeating the write.
Review and evidence
The dashboard shows recent runs, pinned versions and sanitized reasons. A signed-in account can reject an unclaimed run; no control overrides failed checks. Stored outcomes are customer reports, not independent verification of destination execution. Payloads, callback results and destination credentials are not stored. Evidence is retained for seven days and keyed input digests are removed after one day.
MCP and REST
MCP tools handoff_evaluate, handoff_get and handoff_history let connected agents evaluate and inspect runs. They do not execute destination writes. Use a workspace credential and the SDK guard for enforcement in the calling application.
POST /api/v1/quality/handoffs # Stable Idempotency-Key; JSON input
POST /api/v1/quality/handoffs/:id/claim # Exact same JSON input; do not retry
POST /api/v1/quality/handoffs/:id/outcome # {"status":"succeeded|failed|unknown"}
GET /api/v1/quality/handoffs?limit=25
GET /api/v1/quality/handoffs/:id
This guard enforces configured checks through its integrated callback. It cannot prevent bypassing application code, establish factual truth, or guarantee exactly-once execution in another service. Use destination idempotency and your normal application authorization.
Safe retries in SDK 0.3.0
A previously reported successful handoff returns already_succeeded. Claimed, failed or unknown attempts return reconciliation_required. Neither response runs the callback, claims permission again or reconstructs an original destination result. Use the handoff ID and your stable business event ID to inspect the destination before deciding what to do. These outcomes are customer-reported, not independent proof of a write. Do not repeat uncertain operations with a new operation ID.
Try a guarded inventory example
Explore a free, browser-only interactive inventory validation example that blocks a negative quantity before a simulated write. The example explains where production authorization and durable idempotency are still required.