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 SEQUENCEUnderstand how the ideas connect
Choose a point to look closer ↓
01 / Guide section
Separate the decisions
Authentication establishes who is calling. Policy decides whether that subject may perform a particular operation in context. Scoped approval supplies evidence that a specific request or class of effects has been reviewed. A ceremony requirement can require additional, fresh verification at execution time.
Read the supporting context ＋
These mechanisms answer different questions. An authenticated user is not automatically permitted to perform every action, and a visible review button is not an approval receipt.
Explore a section, then continue with the complete article below.
1 / 4
Separate the decisions
Authentication establishes who is calling. Policy decides whether that subject may perform a particular operation in context. Scoped approval supplies evidence that a specific request or class of effects has been reviewed. A ceremony requirement can require additional, fresh verification at execution time.
These mechanisms answer different questions. An authenticated user is not automatically permitted to perform every action, and a visible review button is not an approval receipt.
Question
Mechanism
Host responsibility
Who is calling?
Authentication context
Resolve identity through a trusted source
May this caller do this?
Policy decision
Supply and test the decision implementation
Has this request been approved?
Scoped approval
Verify the receipt against operation, subject, input and effects
Is fresh verification required?
Ceremony
Claim and complete the required host-bound ceremony
Declare the approval boundary explicitly
For an operation with execution.approval, the shared preparation path checks for approval evidence before handler entry. Missing evidence yields APPROVAL_REQUIRED with reason missing_receipt. If evidence exists but the host has no approval port, the reason is approval_runtime_unavailable.
Tags, presentation labels and MCP tool annotations describe an operation; they do not opt it into this enforcement. Configure the actual requirement and the trusted verifier.
↳Find the point where the handler can begin.Trace the mechanism · 3 ways to look closer＋
Take an operation that explicitly requires approval. Change one condition and inspect the expected path from the captured runtime guide.
Which request are you inspecting?
A CONCRETE SITUATION
Input preparation stops the path early.
The request omits an input required by the operation schema.
01 / INPUT
Parse and validate the request against the declared schema.
What changes
The request cannot become a valid prepared input.
What stays explicit
No visible button or descriptive tag makes the missing value valid.
FOLLOW THE CONSEQUENCE
A denial test for approval should use otherwise valid input, so it actually reaches the approval boundary.
The approval port receives the operation key and version, subject context, parsed input, required effects and requested cost. Use those values to decide whether the supplied evidence authorizes this invocation, rather than treating the presence of a token as permission.
Connect has its own request, scope, digest, expiry and durable signature checks. Use the appropriate host integration for the boundary you are implementing; do not assume two differently typed receipt systems are interchangeable.
Prove denial before success
Use a disposable handler with an invocation counter. Send valid input as an authenticated fixture subject without approval through REST and MCP. Assert the actual denial from each adapter and a counter that remains zero.
Then exercise the verifier you intend to ship: wrong subject, wrong scope or expiry should remain denied where those conditions apply. Only add an allowed path when its receipt is actually verified. A stub that always returns allow is useful for UI development, but it does not demonstrate authorization.
See it in an example.
Execution / Intermediate
Stop a write before it runs
Control side effects
Trace a REST request through an approval gate and inspect the zero-handler-call denial assertion.
01
Declare the boundary
02
Inspect the denied request
03
Inspect the approved request
Source demonstratesThe inspected denial test asserts that the handler is not invoked when a required receipt is missing.
Does not demonstrateA fresh successful execution in this review.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A synthetic rest.approval.protected command has write and external-side-effect declarations. The fixture sends a request first without approval evidence, then with a receipt bound to the operation and input.
Declare the boundary
The fixture defines a command with execution.effects set to write and external-side-effect, and execution.approval.required set to true.
Inspect the denied request
The first test binds a handler with a call counter. Without a receipt, it expects HTTP 403, APPROVAL_REQUIRED with reason missing_receipt, and calls equal to zero.
Inspect the approved request
The second test provides a receipt through createFetchHandler's approvalReceipt option and an approval port with a controlled clock. The response is expected to be 200 with value ran.
Apply the pattern to your side effect
Replace the synthetic handler with your operation and trusted receipt source. Add tests for the exact subject, operation, input, expiry, and effect requirements your application uses.
What this example establishes＋
Source demonstrates
The inspected denial test asserts that the handler is not invoked when a required receipt is missing.
The approved case adapts receipt evidence outside the operation input.
The fixture has an inspectable positive and negative request path.
Does not demonstrate
A fresh successful execution in this review.
An end-to-end human approval UI or trusted production receipt issuer.
A real external write: the approved handler only returns a fixture value.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A reference agent drafts a message, waits for approval, and invokes sendMessage. The MCP smoke test uses a real MCP server and client over an in-memory transport. The actual handlers remain deterministic fixture logic.
Separate the two operations
The source defines draftAndSend.draftMessage and draftAndSend.sendMessage. Drafting is automation-safe; sending declares its approval requirement.
Inspect the workflow
The example connects draft, approval wait, send, and receipt stages through the WorkflowDevkit adapter. This is a composed reference flow, not an invitation feature in the minimal starter.
Inspect the MCP boundary
The smoke test registers the operation registry as MCP tools, then calls sendMessage with valid, absent, and tampered receipt evidence. It expects success only for the valid case.
Read what send actually does
The bound handler derives a message ID and returns status sent in memory. To send through a real provider, supply your own port and preserve the same execution boundary.
What this example establishes＋
Source demonstrates
The source smoke fixture drives a real MCP server/client over linked in-memory transports.
The fixture asserts APPROVAL_REQUIRED for missing and tampered receipts.
The same registry gate is used by the MCP adapter rather than a second hand-written approval path.
Does not demonstrate
Delivery of a Slack message, email, invitation, or other network request.
A fresh successful run or production human approval system.
That the minimal example includes MCP; this is a separate source package.
Look inside the guideOpening context · complete reading path＋
Start from one registry
Register the operation and bind its handler once. The REST createFetchHandler and MCP registerMcpTools implementations both call OperationSpecRegistry.executeResult. That shared invocation path is the useful connection between an API request and an agent tool call.
Look inside the guideOpening context · complete reading path＋
Follow the execution boundary
A registered call resolves an operation and its bound handler, prepares the input and execution context, invokes the handler, and validates the returned value. The exact checks depend on the contract and the ports supplied by the host.
Look inside the guideOpening context · complete reading path＋
Give each test one question
An operation has several boundaries, and one green check cannot answer every question about them. Separate declaration validity, business behavior, adapter behavior and external consumption so failures tell you where to look.
