openmed.agent.approvals.side_effect_preview renders an offline, value-free
review view for typed resource writes. A preview lists each resource type and
opaque resource handle, each changed schema field path, whether each side is
absent or redacted, and the workflow state transition. A keyed digest commits
to the complete before and after values, action ID, write order, resource
handles, and workflow states. The module performs no network call or write.
from openmed.agent.approvals.side_effect_preview import (
ResourceWrite, WorkflowState, WriteIntent, WriteKind,
render_side_effect_preview, require_current_preview,
)
secret = b"application-private-key-at-least-32-bytes"
current = {"status": "preliminary"} # In memory only; use a fresh local read.
intent = WriteIntent(
action_id="11111111-1111-4111-8111-111111111111",
writes=(ResourceWrite(
WriteKind.UPDATE, "Observation", "res_" + "a" * 32,
current, {"status": "final"},
),),
workflow_before=WorkflowState.AWAITING_REVIEW,
workflow_after=WorkflowState.APPROVED,
)
preview = render_side_effect_preview(intent, secret=secret)
# Show preview.resources and the workflow transition to a reviewer.
# Keep the approved preview digest with the separate approval token.
require_current_preview(
intent,
observed_before=({"status": "preliminary"},), # Fresh read at dispatch.
observed_workflow_state=WorkflowState.AWAITING_REVIEW,
approved_digest=preview.digest,
secret=secret,
)The application must generate a random UUIDv4 action ID and random res_
handles, then keep the handle mapping to real resources in its trusted local
review UI. Field paths must come from a
trusted schema, never from clinical payload keys. Flat paths such as status
or subject.reference are allowed; nested field values are compared as
atomic values. JSON numbers include finite decimal values; nonfinite numbers,
unpaired Unicode surrogates and values nested beyond 64 levels fail with a
value-free validation error. The preview intentionally shows no identifiers or values.
Its digest is a private keyed commitment, not a substitute for the review UI.
Keep the key private and stable through review and dispatch; rotating it
invalidates pending previews.
At dispatch, the application must supply newly observed resource and workflow
states. require_current_preview rejects any changed state or proposal with
stale_preview, requiring another review. It does not validate a human
approval token, read a target system, or dispatch the mutation. The caller
must validate the separate single-use approval token and use target-side
atomic preconditions such as FHIR If-Match to close the race after the fresh
read. For conditional creates, the caller must also resolve search ambiguity
and enforce the target's idempotency contract. Never log the raw write intent,
resource mapping, key, or clinical values.