Skip to main content

​
RStack Spec v1alpha1

The RStack Spec (rstack.dev/v1alpha1) pins down, normatively, the files a governed run writes and the lifecycle semantics the harness enforces. It is derived from the shipped code, never from intent: every schema, enum, and gate is backed by a runtime producer or validator in the repository, with the source module named next to each section. Nothing aspirational ships in the spec.

​
What ships

​
Two kinds of schema

  • Raw on-disk file schemas describe exactly what RStack writes today: the builder contract (builder.json), validator contract (validation.json), approvals ledger, evidence ledger lines, and attestation envelopes — plus the raw shapes of manifest.json, tasks.json, decisions.json, policy.json, and rstack.config.json under each resource schema’s definitions.
  • Resource envelope schemas are Kubernetes-style projections (apiVersion: rstack.dev/v1alpha1, kind, metadata, spec, status) for tools that exchange RStack resources: Run, Task, Decision, Gate, Profile, Project, AgentRole, Adapter. The attestation is exempt — it defines its own envelope (schema: rstack.dev/attestation/v1alpha1) exactly as the code writes it.
The harness is a tolerant reader by design, so every schema keeps additionalProperties: true; only value sets the code actually closes (status enums, impacts, predicate types) are closed in the schemas.

​
Conformance levels

Claim conformance by level and version: “conforms to RStack Spec rstack.dev/v1alpha1, level business-flex”.

​
Validate anything

The command validates (1) every packaged schema compiles, (2) the packaged conformance example against every matching schema, and (3) the target project’s newest run — tolerantly: missing files are SKIP, invalid files FAIL with the exact field path (e.g. /tasks/1/status: must be equal to one of the allowed values). Exit 0 clean, exit 1 on any FAIL. CI runs it on every push (npm run validate:schemas), so schema/producer drift cannot land silently.