Every mutating HTTP call must carry a service identity header. Unknown services receive 401 before the service layer is ever reached.

X-Service-Identity: risk-service

Identities are validated against an allowlist in suqa/identity.py. The same header populates created_by, requested_executor, and redeemer on audit events.

Returns the envelope. If ttl_days has elapsed, the state is durably transitioned active → expired as a pre-flight UPDATE before the response is built.

GET /v1/states/state_7f1c2e8b49a9
X-Service-Identity: underwriting-service

{
  "state_id": "state_7f1c2e8b49a9",
  "state_type": "fintech.loan.commit.v1",
  "status": "active",
  "content_hash": "sha256:4e9b…",
  "parent_state_id": null,
  "policy": {"allowed_transformations":["underwrite","price"],"ttl_days":7}
}

Returns the chain from this state up to the originating root, in order. Useful for audit ("what decision led to this execution?") and for refining policies along the chain.

{
  "lineage": [
    {"state_id":"state_9aa2…","state_type":"fintech.price.v1","parent_state_id":"state_7f1c…"},
    {"state_id":"state_7f1c…","state_type":"fintech.loan.commit.v1","parent_state_id":null}
  ]
}

The TAT's sub/op/executor claims must match the server-side TransformationRequest. On success, a new child StateEnvelope is created with parent_state_id set and the parent's policy inherited.

POST /v1/states/submit
X-Service-Identity: underwriting-service

{
  "tat": "eyJhbGciOi…",
  "state_type": "fintech.underwrite.v1",
  "encrypted_payload": "enc::{score:720}",
  "metadata": {"model":"uw-v3"}
}

{
  "state_id": "state_9aa2…",
  "parent_state_id": "state_7f1c…",
  "status": "active"
}

Creates a sibling state with identical content but a new state_id. The original remains active. Useful when multiple consumers need to reason about the same decision without racing for its one redemption.

Guarded server-side by select_for_update and a UniqueConstraint(state, idempotency_key). Under N concurrent callers, exactly one gets consumed; the others get blocked. Retrying with the same idempotency key is safe.

{
  "redemption_id": "red_5b12…",
  "state_id": "state_7f1c…",
  "outcome": "consumed",
  "redeemer": "execution-service"
}

{
  "error": "state_consumed",
  "redemption_id": "red_a4ee…",
  "outcome": "blocked"
}

{
  "redemptions": [
    {"redemption_id":"red_5b12…","outcome":"consumed","redeemer":"agent-b","at":"…"},
    {"redemption_id":"red_a4ee…","outcome":"blocked","redeemer":"agent-a","at":"…"},
    {"redemption_id":"red_91c0…","outcome":"blocked","redeemer":"agent-c","at":"…"}
  ]
}

This is what makes "attempted many times, realized exactly once" provable after the fact. It's what Act 6 of the story demo renders as the final ledger.

from suqa import services

state = services.create_state(
    state_type="fintech.loan.commit.v1",
    encrypted_payload="enc::{amount:25000}",
    created_by="risk-service",
    policy={
        "allowed_transformations": ["underwrite", "price"],
        "delegated_executors": ["underwriting-service"],
        "ttl_days": 7,
    },
    metadata={"loan_id": "L-42"},
)
# -> StateEnvelope(state_id='state_7f1c…', status='active')

Returns StateEnvelope. Raises ValidationError on malformed policy/payload. Emits audit event state_created.

sibling = services.duplicate_state(state.state_id, actor="risk-service")
# sibling.state_id != state.state_id, but content_hash matches.

Emits state_duplicated. Does not consume the original; both remain active until one is redeemed.

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,
)
# req: TransformationRequest  (persisted, with tr_ id)
# tat: signed capability string — hand this to the executor

Raises PolicyViolation if operation isn't allowed or the executor isn't delegated. Emits transform_authorized.

child = services.submit_transformed_state(
    tat=tat,
    state_type="fintech.underwrite.v1",
    encrypted_payload="enc::{score:720}",
    actor="underwriting-service",
    metadata={"model": "uw-v3"},
)
# child.parent_state_id == state.state_id
# child.policy inherited from parent — immediately usable

Raises TATInvalid if signature/expiry is bad or the TAT's sub/op/executor don't match the persisted TransformationRequest. Emits transformed_state_submitted.

for node in services.get_lineage(child.state_id):
    print(node.state_id, node.state_type)

result = services.redeem_state(
    state_id=child.state_id,
    idempotency_key="exec-L-42-attempt-1",
    redeemer="execution-service",
    reason="loan commit",
)
if result.outcome == "consumed":
    do_the_irreversible_thing()
else:
    # 'blocked' — someone else already won, or this is a retry
    log.info("skipped", original_winner=result.existing_redeemer)

Most code should never touch this module directly — authorize_transform and submit_transformed_state call it for you. It's exposed for testing and for integrations that need to validate a TAT at the edge.

from suqa import tokens

tat = tokens.mint_tat(
    sub=req.transformation_request_id,
    op="underwrite",
    executor="underwriting-service",
    purpose="credit-check",
    ttl_seconds=300,
)
claims = tokens.verify_tat(tat)
# {'jti','sub','op','executor','purpose','iat','exp'}

Signed with django.core.signing. Tampering, expiry, or mismatched sub/op/executor all raise TATInvalid.