Skip to main content

Compiled artifact format

.similec is Simile’s runtime distribution format. OpenAPI and HCL remain the provider-authored and reviewable source formats; the runtime never needs to parse either one on startup.

Envelope version 9

Every artifact begins with a fixed 52-byte envelope: Readers must reject an unknown format version or non-zero flags. They must also reject a truncated payload, trailing bytes, a digest mismatch, unknown record tags, and every out-of-range internal index. These checks happen before runtime execution.

Payload model

The payload is an ordered CBOR array rather than a serialized Rust struct map. Version 9 contains:
  1. compiler version string identifier;
  2. a sorted and deduplicated string table;
  3. service metadata;
  4. operations in stable operation-key order;
  5. an indexed value arena used by response definitions, exact outcome bodies, and predicates;
  6. resources in stable resource-reference order;
  7. asynchronous operations in stable name order; and
  8. one shared request/response schema catalog.
Strings, value nodes, resources, and asynchronous operations are referenced with unsigned numeric identifiers. Behavior records therefore point directly to asynchronous-operation records, and those records point directly to abstract resources. The runtime does not repeatedly compare or allocate names to follow those edges. Service metadata also carries the provider-neutral protocol-error table and opaque scenario selections. Each operation carries a named outcome catalog with exact status, optional media type and body, fidelity provenance, and public request predicates. Scenario records map an operation key to one of those names; they never carry the private production decision that selected it. Each operation embeds a compact request-body plan and a body plan for every response that declares content. Plans contain declared media types, schema root identifiers, and optional declared media examples. Those roots point into the shared catalog, where component schemas are compiled once per request/response direction and recursive references remain graph edges. Direction matters: readOnly properties are omitted from request graphs and writeOnly properties are omitted from response graphs. The catalog also contains compact schema example and default hints, plus explicit OpenAPI format annotations used by seeded synthesis. Description prose is deliberately not interpreted as schema metadata. The runtime therefore validates requests and synthesizes requests or responses without parsing OpenAPI, interpreting arbitrary source JSON, or copying common schemas into every operation. Before encoding, provider-authored outcome bodies are checked against their selected OpenAPI response schema. The public-export audit rejects explicit private implementation markers. This audit is a guardrail; the provider remains responsible for reviewing all published values. Recognized x-simile-constraints declarations are compiled into typed relationship records in the same schema graph. Source extension objects are not shipped as arbitrary JSON. Artifact validation rejects relationship selectors, predicates, witnesses, expressions, lifecycle plans, or comparison kinds that do not match the embedded graph. Version 9 carries ordering, relative-bound, implication, equality, equation, aggregate, distinct-selector, scalar-set, template, and lifecycle records; the runtime does not reparse their OpenAPI extension syntax. Version 9 also carries typed provider-neutral generation plans. Every plan records a stable rule identifier, confidence, source-field evidence, and a typed repair. The runtime consumes those plans without re-running name inference. Provider-specific profiles are not part of this version. Response-definition JSON retained from an OpenAPI source is lowered into tagged value nodes: null, boolean, signed integer, unsigned integer, floating point, string identifier, child-node array, or sorted object fields. Schema and media synthesis hints are encoded as CBOR values inside their catalog records. The original JSON text is never stored in the artifact.

Determinism and compatibility

String collection and every map-backed record set are ordered before encoding. CBOR records use arrays and integer tags, so field names are not repeated. Given the same CompiledService, the encoder must produce byte-identical output; this is covered by tests. The envelope version is the compatibility boundary. Adding optional source syntax does not require a format change when it lowers into existing records. A change that alters record meaning or order requires a new format version and an explicit reader policy. Rust type layout, crate versions, and Serde defaults are not compatibility promises. The payload digest protects integrity and enables content-addressed caching. It is not a signature and does not establish who published an artifact. Artifact signing and provider trust policy belong to a later distribution layer.