Skip to main content
Version: 1.3.1

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:

touba.manifest.json
{
"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:

release-reservation.handler.mjs
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:

FieldExpected value
compensation_request_idstable request identifier, such as request:refund-17
compensates_effect_idexact effect identifier from the journal
requester_refidentity verified by the application
journal_scope_refscope verified by the application

AIR and manifest files must match the original effect. Use separate databases for the existing journal, compensation store and traces.

create-compensation.mjs
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:

create-compensation.py
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.