What your service actually writes

This is the real Python client code a service calls to use Qascade. Each step shows the code on the left and what the backend returns on the right — the same suqa.services calls that power every other demo on this site.

STEP 1

Create an executable state

a decision becomes a single-use token
service code
from suqa import services

# Your decision engine produced an approval.
# Wrap it as an *executable state* — one that can be redeemed exactly once.
state = services.create_state(
    state_type="fintech.loan.commit.v1",
    encrypted_payload="enc::{approve_amount:25000,currency:'USD'}",
    created_by="risk-service",
    policy={
        "allowed_transformations": ["underwrite", "price"],
        "delegated_executors": ["underwriting-service", "execution-service"],
        "ttl_days": 7,
    },
    metadata={"loan_id": "L-42"},
)
print(state.state_id, state.status)
backend response
state_7f1c…a9  active

-- db row (suqa_state_envelope) --
state_id        : state_7f1c2e8b49a9
state_type      : fintech.loan.commit.v1
content_hash    : sha256:4e9b…
parent_state_id : null
status          : active
created_by      : risk-service
policy          : 1 transform, 2 executors, ttl=7d

-- audit event --
{"event":"state_created","state_id":"state_7f1c…",
 "actor":"risk-service"}
STEP 2

Authorize a transformation (mint a TAT)

signed, scoped, expiring capability
service code
# Underwriting needs to refine the state. The *controller* issues
# a TAT that scopes exactly what underwriting can do.
req, tat = services.authorize_transform(
    state_id=state.state_id,
    operation="underwrite",
    requested_executor="underwriting-service",
    actor="risk-service",
    purpose="credit-check",
    ttl_seconds=300,
)
# Hand `tat` to the underwriting service out-of-band.
# It can *only* submit one underwrite transform — nothing else.
backend response
-- db row (suqa_transformationrequest) --
transformation_request_id : tr_d3c9…
parent_state              : state_7f1c…
operation                 : underwrite
requested_executor        : underwriting-service
status                    : authorized

-- TAT (JWT-style signed token) --
{
  "jti": "tr_d3c9…",
  "op":  "underwrite",
  "executor": "underwriting-service",
  "exp": 1713654724   (5 min from now)
}

-- audit event --
{"event":"transform_authorized","actor":"risk-service"}
STEP 3

Submit the transformed child state

TAT validated, new immutable child minted
service code
# The underwriting service has the TAT. It submits its refined
# state — the TAT's claims are verified server-side.
child = services.submit_transformed_state(
    tat=tat,
    state_type="fintech.underwrite.v1",
    encrypted_payload="enc::{score:720,model:'uw-v3'}",
    actor="underwriting-service",
    metadata={"model": "uw-v3"},
)
# child.parent_state_id == state.state_id
# child.policy inherited from parent
backend response
-- new db row (child state) --
state_id        : state_9aa2…
state_type      : fintech.underwrite.v1
parent_state_id : state_7f1c…   (original)
content_hash    : sha256:c1a7…  (different hash)
status          : active
policy          : inherited from parent

-- TAT verified: sub/op/executor all match --
-- parent state unchanged, still active --

-- audit event --
{"event":"transformed_state_submitted","child":"state_9aa2…",
 "parent":"state_7f1c…","actor":"underwriting-service"}
STEP 4

Redeem — the irreversible act

exactly one caller wins; the rest are blocked
service code
# Two agents race to redeem the same state.
# Only one can win. The other is blocked cleanly.

result_a = services.redeem_state(
    state_id=child.state_id,
    idempotency_key="exec-L-42-attempt-1",
    redeemer="execution-service",
    reason="loan commit",
)

result_b = services.redeem_state(   # concurrent agent
    state_id=child.state_id,
    idempotency_key="exec-L-42-attempt-2",
    redeemer="execution-service",
    reason="retry",
)

print(result_a.outcome)  # consumed
print(result_b.outcome)  # blocked
backend response
-- result_a (winner) --
redemption_id : red_5b12…
outcome       : consumed  ← execute your side effect
redeemer      : execution-service

-- result_b (loser) --
redemption_id : red_a4ee…
outcome       : blocked  ← do nothing
existing_winner: red_5b12…

-- invariant: exactly one 'consumed' per state_id --
-- enforced by select_for_update + UniqueConstraint --

-- audit events --
{"event":"state_redeemed","outcome":"consumed","actor":"execution-service"}
{"event":"state_redemption_blocked","outcome":"blocked","actor":"execution-service"}
STEP 5

Inspect the ledger

every attempt, provable after the fact
service code
# Retrieve the full redemption history —
# who tried, when, and what happened.

redemptions = services.get_redemptions(child.state_id)
for r in redemptions:
    print(r.outcome, r.redeemer, r.redeemed_at)
backend response
consumed  execution-service  2025-04-20T22:14:31Z
blocked   execution-service  2025-04-20T22:14:31Z

-- This is what makes "tried many times, done once"
-- provable. Compliance, SRE, and ops all read
-- the same truth from the same table. --
Source of truth: suqa/services.py · suqa/models.py · suqa/tokens.py · all steps call the same service layer as the HTTP API at /v1/