# Data specs

`ol.smolvm.spec` registers `clojure.spec.alpha` specs for local and cloud
configuration, options and results. Loading it does not initialize a native
runtime or contact a service.

```clojure
(require '[clojure.spec.alpha :as s]
         '[ol.smolvm.spec :as spec])

(s/valid? ::spec/local-config {:name "worker" :memory-mib 256})
;; => true

(s/valid? ::spec/exec-options {:timeout-ms 0})
;; => false
```

## Selected shapes

|     |     |     |
| --- | --- | --- |
| Data | Local specs | Cloud specs |
| Configuration | `::spec/local-config` | `::spec/cloud-client-options`, `::spec/cloud-config` |
| Commands | `::spec/exec-options`, `::spec/process-options` | `::spec/cloud-exec-options`, `::spec/cloud-job-options` |
| Execution results | `::spec/exec-result`, `::spec/process-result` | `::spec/cloud-exec-result`, `::spec/cloud-job-output` |
| Machine records | `::spec/machine-summary` | `::spec/cloud-machine-info` |
| Saved state | `::spec/checkpoint-options`, `::spec/restore-options`, `::spec/checkpoint-result` | `::spec/cloud-restore-options`, `::spec/cloud-checkpoint`, `::spec/cloud-upload-plan` |
| Resources and ports | `::spec/resize-options`, `::spec/resize-result`, `::spec/published-ports` | `::spec/cloud-ports` |
| Individual port changes | `::spec/publish-options`, `::spec/unpublish-options` | — |
| Readiness waits | `::spec/wait-ready-options` | — |
| HTTP helper options | `::spec/local-http-request-options`, `::spec/local-fetch-options` | — |
| Endpoints | `::spec/local-endpoint` | `::spec/cloud-endpoint` |
| Branch requests | — | `::spec/cloud-branch-options`, `::spec/cloud-branch-batch-options` |
| Checkpoint parts | — | `::spec/cloud-part-options` |
| Leases | — | `::spec/cloud-assign-options`, `::spec/cloud-assignment`, `::spec/cloud-lease-complete-options` |
| Caches | — | `::spec/cloud-cache-options`, `::spec/cloud-cache` |
| SSE | — | `::spec/cloud-stream-options`, `::spec/cloud-stream-event` |

Maps accept unrelated keys, including registered qualified keys, and preserve
them when conformed. SDK input validation uses the shared field specs without
changing its error maps. It does not validate every returned result.

These specs do not check opaque handles, machine existence, filesystem access
or native feature support. Cloud record specs allow additional server fields
and do not describe every nested resource or usage field.

For example, check helper options without connecting to a machine:

```clojure
(s/valid? ::spec/publish-options {:guest 8080})
;; => true

(s/valid? ::spec/unpublish-options {})
;; => false

(s/valid? ::spec/wait-ready-options {:timeout-ms 10000 :interval-ms 250})
;; => true

(s/valid? ::spec/local-http-request-options
          {:method :post :headers {"Content-Type" "application/json"}
           :body "{\"command\":\"refresh\"}"})
;; => true
```

`branch-exec` uses `::spec/exec-options` and returns `::spec/exec-result`.
The endpoint spec describes URL data, not proof that a service is listening.
For practical examples, see
[Check a service and read its HTTP response](local-workloads.adoc#check-service-readiness).

## Cloud request values

Part ranges require a nonnegative offset and positive length. Cache size is
1 through 500 GB. Lease task/result maps use string keys and JSON values:

```clojure
(s/valid? ::spec/cloud-part-options {:offset 0 :length 1048576})
;; => true

(s/valid? ::spec/cloud-part-options {:offset 0 :length 0})
;; => false

(s/valid? ::spec/cloud-cache-options {:size-gb 1 :mount-path "/cache"})
;; => true

(s/valid? ::spec/cloud-assign-options
          {:lease-id "example-lease" :task {"command" "inspect"}})
;; => true
```

Valid part options do not prove that a file exists or that a signed URL permits
upload. Cache specs do not prove plan entitlement or deletion safety.
Workflow futures resolve to data, not machine handles. Result specs describe
that data, not the future’s state or completion of remote cleanup.
See [cloud workflows](cloud-workflows.adoc) for resource handling.

Spec explanations can contain the supplied values. Do not log explanations
that contain API keys or interceptor credentials.