> ## Documentation Index
> Fetch the complete documentation index at: https://os.inttegro.dev/simile/llms.txt
> Use this file to discover all available pages before exploring further.

# Operation execution

# Operation execution

Simile executes a compiled service through a protocol-neutral runtime. The runtime does
not open a port, route a URL, or depend on an HTTP framework. It accepts the stable operation key
selected by a caller and coordinates the runtime primitives that already understand the compiled
artifact.

## Execution boundary

`Runtime::execute` accepts an `OperationCall` containing:

* a stable operation key such as `POST /orders`;
* the incoming request Content-Type; and
* the incoming body bytes.

Transport adapters that have already decoded a body call `Runtime::execute_value` with an
`OperationValueCall`. This is the boundary used by the one-shot CLI: JSON, form, and future wire
formats remain adapter concerns while schema validation and response projection operate on one
normalized value model.

The normal execution path selects its response from the compiled OpenAPI contract and optional HCL
behavior. Public request predicates may select a named outcome automatically. Test scenarios that
need a particular result can use `Runtime::execute_with_options` with a named outcome or opaque
scenario; those controls are not presented as part of the incoming operation call. An adapter can
also supply an opaque `ReplayIdentity`:
`IdempotencyKey` for mutations or `Resource` for GET requests.

It performs one ordered run:

1. resolve the operation from the loaded artifact;
2. decode and validate the request body;
3. synthesize the immediate response, using the validated request as context; and
4. collect the asynchronous operations attached by HCL, including their abstract resources; and
5. cache the completed outcome when the adapter supplied a replay identity.

The result owns the validated request body, synthesized response, and asynchronous operation plan.
No plan is returned when validation or response synthesis fails. This gives future state and effect
execution a single success boundary instead of spreading partial work across transport handlers.

## One-shot CLI execution

The `simile run` command compiles a local OpenAPI path or an in-memory `--spec-url` response and
invokes this runtime boundary once. Callers select the operation using either its stable
`METHOD /path` key or its exact OpenAPI `operationId`. The selectors are mutually exclusive.

If the caller supplies `--request`, Simile reads an inline JSON request object, a bare file path
(`@file` remains supported), or standard input when passed `-`. The object contains a `headers`
object and an optional `body`. Header names are matched case-insensitively. `Content-Type` selects
the OpenAPI media type used to validate a provided body; the remaining headers are retained in the
execution report but are not interpreted as runtime policy. Supplying two case variants of
`Content-Type` is an error. A present JSON `null` body is distinct from an omitted body.

If any request body is declared and `--request` is absent, Simile synthesizes and validates a fresh
value from the compiled schema. This also applies to optional request bodies; only an
operation with no request-body declaration runs without one by default. `--content-type` selects a
media type for synthesis and cannot be combined with `--request`. By default, stdout is only the
pretty-printed JSON response payload; a bodyless response is `null`. Passing `--verbose` prints the
selected operation, normalized request, provided headers, response metadata, and asynchronous
plan. Each invocation is a fresh process and therefore produces fresh schema-valid values; it is
not an HTTP server or a persistent replay store.

`--outcome NAME` selects one named result directly. `--scenario NAME` activates an opaque scenario
selection. They are mutually exclusive. Both controls are outside the emulated request and never
require magic provider headers.

## Replay identity

A `Runtime` owns an in-memory replay index for its lifetime. A repeated idempotency key returns the
first completed outcome, including its generated response and asynchronous plan. Reusing that key
with a different validated request is an error. A repeated `Resource` identity is accepted only for
a GET operation and returns the first outcome for that operation and resource. Different identities,
or calls without an identity, generate fresh outcomes.

The runtime deliberately does not inspect headers, route templates, or parameter names. The HTTP
adapter normalizes the idempotency header or addressed resource into `ReplayIdentity`.
This keeps HTTP policy out of the schema and operation layers, and prevents route names from being
mistaken for storage semantics.

## Asynchronous work

The runtime plans declared work; it does not claim that the work has executed. Each planned entry
contains the HCL async-operation name and its abstract resource references, such as `db.orders` or
`mail.receipts`. A subsequent runtime layer can dispatch those entries to deterministic local
resource implementations and record their progress without reparsing HCL or performing string
lookups through the compiled service graph.

OpenAPI-only operations produce an empty asynchronous plan. Simile does not infer storage or
effects from route names.

## HTTP adapter

`simile-server` remains a wire adapter:

1. listen on the configured local port;
2. match the incoming method and path to a compiled operation key;
3. apply transport limits and gather the request values;
4. pass the wire body and any process-selected scenario to `Runtime::execute`; and
5. translate the result or runtime error into an HTTP response.

It currently matches literal and parameterized OpenAPI paths, applies an 8 MiB body limit, extracts
`Content-Type` and `Idempotency-Key`, and preserves GET replay by full URI. Path, query, and header
schema validation, authentication behavior, form and multipart codecs, durable state, and execution
of asynchronous plans remain later runtime slices. They are not silently treated as implemented by
the current body-oriented runtime.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.