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.
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:
- resolve the operation from the loaded artifact;
- decode and validate the request body;
- synthesize the immediate response, using the validated request as context; and
- collect the asynchronous operations attached by HCL, including their abstract resources; and
- cache the completed outcome when the adapter supplied a replay identity.
One-shot CLI execution
Thesimile 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
ARuntime 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 asdb.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:
- listen on the configured local port;
- match the incoming method and path to a compiled operation key;
- apply transport limits and gather the request values;
- pass the wire body and any process-selected scenario to
Runtime::execute; and - translate the result or runtime error into an HTTP response.
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.