Skip to main content

Outcome fidelity

OpenAPI defines which responses are legal. Simile compiles those responses into named outcomes so tests can select a public cause instead of asking for an arbitrary HTTP status. The resulting catalog is carried in .similec; the runtime does not reopen OpenAPI or HCL.

Provenance

Every compiled outcome reports one fidelity source:
  • open_api_derived: an exact OpenAPI example or fully described bodyless response;
  • provider_authored: an HCL outcome whose body is checked against the OpenAPI response;
  • recorded_reviewed: reserved for provider-reviewed examples produced by authoring tools;
  • schema_synthesized: a schema-valid approximation where no exact example was published.
Scenarios are selectors, not a body-provenance source. simile inspect reports scenario selections separately while the selected outcome retains the provenance of its response body. simile inspect service.similec lists each operation’s outcomes and calls out operations for which every outcome is schema-synthesized. This is an authoring worklist, not a claim that those operations are production-faithful.

OpenAPI first

Simile derives named outcomes from response statuses, media types, and named OpenAPI examples. A provider only needs HCL for public behavior that OpenAPI cannot express precisely. Named examples are the lowest-maintenance way to publish exact successes and errors. Descriptions are not executable decision trees. Simile may display them to an author, but does not turn prose about internal checks into runtime rules.

Reusable provider outcomes

An error family can be authored once and attached to many operations:
The status must already be declared by that OpenAPI operation. The body must validate against the selected response schema or compilation fails. apply_error_set attaches the family to every operation carrying any listed OpenAPI tag, so providers can cover a product area without repeating operation identifiers.

Public request predicates

Simple, externally observable request values can select an outcome:
path is a JSON Pointer into the validated request body. Every when clause must match. These predicates are for public contract inputs only; they must not encode private risk thresholds, vendor decisions, database state, or production algorithms.

Opaque scenarios

Sensitive production decisions are represented by an opaque public scenario that selects an already declared outcome:
Use simile run ... --scenario payment_declined for one operation or simile start SERVICE --scenario payment_declined for a running emulator. The distributed artifact contains the public scenario name and observable result, never the provider’s hidden decision tree.

Protocol errors

Simile has a small provider-neutral taxonomy for failures discovered before an operation can run: malformed_request, invalid_body, unsupported_media_type, authentication_required, permission_denied, idempotency_conflict, and rate_limited. Built-in mappings choose only a response status already declared by the operation. A provider can override a mapping once for the whole service:
If no compatible service response exists, the HTTP adapter retains Simile’s diagnostic fallback.

Public export audit

HCL has no construct for private implementation checks. Compilation also rejects explicit private markers such as _internal*, private_*, implementation_detail, fraud_threshold, and database_table in distributed outcome metadata. simile inspect reports whether the artifact passed this audit. This is a guardrail, not a substitute for provider review of all published examples and scenario names.