Explicit bounded compensation
A compensation requests the declared business inverse of one confirmed external effect, such as releasing a reservation. It is never implicitly triggered by failure, fallback, cancellation or deployment rollback.
The original effect remains applied. The inverse has its own run, effect,
budgets, secrets and authority. Its outcome is completed, partial,
unavailable, failed or unknown; only an observed inverse outcome can
determine that result.
Declare the inverse
A touba-manifest-v1 external-write binding identifies an existing strategy in
its effect contract:
{
"manifest_version": "touba-manifest-v1",
"bindings": {
"tool:reservations/CreateReservation": {
"handler": {
"kind": "process",
"command": "node",
"args": ["handlers/create-reservation.mjs"]
},
"grants": ["network"],
"secrets": ["RESERVATION_API_TOKEN"],
"timeout_ms": 5000,
"max_payload_bytes": 65536,
"effect_contract": {
"kind": "external_write",
"retry_mode": "idempotency_key",
"compensation": {
"entry_ref": "strategy:reservations/ReleaseReservation"
}
}
}
}
}
The inverse graph
contains pure bind nodes, at most one human approval, exactly one external
tool call and a terminal give or stop. Branches, loops, fallbacks, nested
calls, interactions, a second effect and recursive compensation are refused.
Handler contract
For one declared input, request contains its value directly:
import { createToolResult, defineTool } from "@touba/sdk";
await defineTool({
toolRef: "tool:reservations/ReleaseReservation",
inputSignature: [
{ name: "reservation_id", type_ref: "builtin:Text" },
],
outputType: "builtin:Text",
run: async ({ request: reservation_id, context }) => {
const response = await releaseReservation({
reservationId: reservation_id,
originalReceipt: context.compensation.original_effect_receipt,
idempotencyKey: context.effect.effect_id,
});
return createToolResult(response.message, {
effectReceipt: context.createEffectReceipt({
outcome: "applied",
receipt_ref: response.receiptRef,
}),
compensationReceipt: context.createCompensationReceipt({
result: response.complete ? "completed" : "partial",
}),
});
},
});
releaseReservation is your business adapter. See the
runnable callback test.
The inverse handler receives context.compensation.original_effect_receipt
and context.effect.effect_id. It returns an effect receipt created with
context.createEffectReceipt(...) and a compensation receipt created with
context.createCompensationReceipt(...). Keep the original receipt in control
data; do not copy it into business arguments, logs or public traces.
The host separately requests creation and resume. Each command checks target authority before reading the journal, then revalidates authority before progress and immediately before spawning a handler. Resume supplies the current revision and digest. An exact already-handled replay is read-only: no handler or new trace. A fresh approval can replace an expired approval for the same subject and reference; approval is not inherited from the original run.
Call from the application
The application supplies a trusted host file exporting
checkCompensationAuthority(request) in JavaScript, or
check_compensation_authority(request) in Python. It returns true after
checking the authenticated identity, target journal and any required approval.
The phases are lookup, resume and pre_spawn. The command's
requester_ref and journal_scope_ref are references for this host to verify.
The application selects the module through authorityHost /
authority_host. Loading is explicit. For Python modules,
TOUBA_HOST_PYTHON selects the interpreter with touba-sdk installed.
Prepare compensation-request.json with these fields:
| Field | Expected value |
|---|---|
compensation_request_id | stable request identifier, such as request:refund-17 |
compensates_effect_id | exact effect identifier from the journal |
requester_ref | identity verified by the application |
journal_scope_ref | scope verified by the application |
AIR and manifest files must match the original effect. Use separate databases for the existing journal, compensation store and traces.
import {readFileSync, writeFileSync} from "node:fs";
import {ToubaEngine} from "@touba/sdk";
const engine = new ToubaEngine({projectRoot: "."});
try {
const {record} = await engine.createCompensation({
air: "payment.air.json",
manifest: "manifest.json",
effectJournal: "effects.effect-journal.sqlite",
store: "compensations.sqlite",
authorityHost: "authority.mjs",
request: JSON.parse(readFileSync("compensation-request.json", "utf8")),
});
writeFileSync("compensation-result.json", JSON.stringify(record));
console.log(record.state, record.result);
} finally {
await engine.close();
}
The same operation in Python, with the same journal and host contract:
import json
from pathlib import Path
from touba_sdk import ToubaEngine
engine = ToubaEngine(project_root=".")
result = engine.create_compensation(
air="payment.air.json",
manifest="manifest.json",
effect_journal="effects.effect-journal.sqlite",
store="compensations.sqlite",
authority_host="authority.py",
request=json.loads(Path("compensation-request.json").read_text()),
)
record = result["record"]
Path("compensation-result.json").write_text(json.dumps(record))
print(record["state"], record["result"])
The CLI exposes the same operations:
touba compensation create --air payment.air.json --manifest manifest.json \
--effect-journal effects.effect-journal.sqlite --store compensations.sqlite \
--authority-host authority.mjs --request-json "$COMPENSATION_REQUEST"
COMPENSATION_REQUEST holds the request JSON without secrets.
The command returns record; --trace-store traces.sqlite retains events.
SDKs accept traceStore / trace_store, runLimits / run_limits,
secrets and resourceBindings / resource_bindings.
Resume a pending operation
For an action_required record, supply these fields to resumeCompensation,
resume_compensation or touba compensation resume:
resume_request_id: stable identifier for this resumption;compensation_id,compensates_effect_id: values from the record;expected_revision,expected_record_digest: the revision and digest read;requester_ref,journal_scope_ref: host-verified references;approval_evidence, when required: evidence verified by the application.
Evidence includes schema_version: "touba-compensation-approval-v1",
approval_id, the record's approval_ref, subject_ref equal to
compensation_id, decision: "approved", decided_at and expires_at.
Dates use UTC format YYYY-MM-DDTHH:mm:ss.sssZ.
An approval covers this specific compensation.
The host holds a local journal lock during the operation. After a crash,
inspect durable state and the business service before clearing a residual lock.
An uncertain inverse remains unknown.
Meaning of completion
Completion means the declared inverse was applied, not that the external world was perfectly restored. The supplied SQLite store atomically checks revisions and digests across local processes. The host coordinates executions and backups; this store supplies no multi-host lease or tamper-proof history. Existing JSON state uses the explicit migration in Storage and retention.
See External effects.