Skip to content
ContractSpec
Start here

Core guide · Operations · 3 min read

Observe a call without confusing it with approval

Use traces and outcomes to diagnose execution, and keep durable evidence requirements explicit.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Carry context through the call

A useful operation trace lets you connect a request, its selected contract version, the handler outcome and the interface that invoked it. The registry's canonical result can carry trace and source context supplied by the host.

Use those identifiers to follow a failure across layers. Keep diagnostic details bounded and avoid collecting raw inputs merely because they are available to the handler.

1 / 4

0 points in your packet

Carry context through the call

A useful operation trace lets you connect a request, its selected contract version, the handler outcome and the interface that invoked it. The registry's canonical result can carry trace and source context supplied by the host.

Use those identifiers to follow a failure across layers. Keep diagnostic details bounded and avoid collecting raw inputs merely because they are available to the handler.

Understand the telemetry path

The inspected invocation path can emit configured success and failure telemetry through a host-supplied telemetry context. It checks the operation's data-handling configuration and can redact declared transient fields before computing telemetry properties.

Telemetry errors are handled as best effort so they do not automatically fail the business handler. That is useful for operations monitoring, but it means a telemetry event is not automatically a durable record of every effect.

At this snapshot, success telemetry is emitted after the handler returns but before output validation. Use the final canonical operation result when counting completed successes; a handler event alone does not establish that the returned value passed the contract boundary.

EvidenceUseful forDo not treat it as
Trace/source identifierFollowing one invocationAn authorization grant
Telemetry eventBehavior and failure monitoringGuaranteed durable audit persistence
Approval receiptEvidence checked at an execution boundaryA general-purpose reusable permission
Durable host recordAccountability and recovery according to host designSomething created merely by declaring an audit intent

Make denials visible

Record the meaningful failure category and operation identity for denied requests. For an approval demo, show the missing-receipt reason alongside the handler invocation count. That makes the boundary understandable without inventing a successful effect.

When a request is denied before handler entry, distinguish it from a business failure after execution began. The recovery action is different: fix context or satisfy an authorized approval path in the first case, investigate the implementation or provider in the second.

Review the operational path you depend on

If the product requires durable audit or cost evidence, choose and test the host persistence path explicitly. Include a failure or retry case and verify how the record relates to the business mutation.

Use the smallest evidence needed to support the claim. A source declaration, a fixture trace and a live environment qualification each answer different questions; label them accordingly in examples and runbooks.

Read the signal at the stage it describes.

A trace can help explain a request, but timing and durability determine what it establishes.

Which signal are you looking at?

A CONCRETE SITUATION

The boundary stopped the operation before the effect.

The result reports a meaningful failure before handler entry.

01 / Identify

Carry operation key, version and trace context.

What changes

The operation identity and failure category show where to investigate.

What stays explicit

A precondition denial is different from a business failure after execution began.

Follow the consequence

Fix the applicable input or trusted context, or follow the authorized approval path. Preserve that distinction in the explanation.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.