How examples are verified

This site is generated by running the tool it documents. While the site builds, every example is parsed, compiled, and where possible applied to a database — and an example that breaks its promises stops the build.

The pipeline

During a build, docgen — a small builder that links Surform as a library — runs every example through the toolchain:

1. Parse the SDL with Surform's own parser (the same one surform check runs). Valid examples must parse clean; error examples must produce exactly the diagnostic codes the page promises.
2. Emit the DDL — that is what the What surform build emits panels show, byte for byte.
3. Apply the DDL to a fresh, in-process SurrealDB 3.3.0 engine (the official surrealdb crate, embedded). The few shapes the embedded engine gates (Surrealism modules; buckets needing server-side configuration) stop here and carry the compiles clean badge instead — their DDL is still validated against the SurrealDB 3.3 parser with the experimental capabilities enabled.
4. Read back the schema via INFO FOR DB (plus each table's INFO FOR TABLE), parse it with Surform's reverse reader, and normalize — that is what the canonical form panels show (the fences that opt in with the info attribute).
5. For workflow pages, go further: apply a hand-made drift mutation and capture surform migrate generate's report and convergence script, or run the surform binary and capture its terminal transcript.

Any step failing — a parse error where the page promised success, a define-time rejection, a comparison that should have been empty — aborts the build with the file, line, and reason.

The badges

• applied to SurrealDB 3.3.0 — parsed, emitted, and executed against the engine; every output panel is that run's output.
• compiles clean (engine-gated shape) — parsed and emitted, but the shape needs a server capability the embedded engine runs without (Surrealism modules), or server-side configuration (a bucket with no backend). The DDL was still validated against the SurrealDB 3.3 parser.
• compiles clean inside a table block — the Language spec pages' clause-level fragments (sdl-body fences): parsed, emitted, and the wrapped DDL validated against the SurrealDB 3.3 parser after wrapping in a minimal table statement — not applied to the engine, since a fragment's DDL depends on the host its prose names. Rendered as a static panel. The spec's complete sdl fences behave like the docs pages' own — live editors, verified outputs.
• real Surform diagnostics / lint findings — the error and lint examples were run through the tool, and the codes asserted.
• canonical form verified — the formatted output re-parses and formats to itself.
• captured from the real binary — terminal panels produced by running surform.
• adoption verified through the normalize pipeline — the adopt walkthroughs: the fence's INFO text was read by the reverse reader, merged, and written back by the same functions surform normalize runs.
• live drift — the migration walkthroughs: applied, mutated by hand, compared, all in-process.

What "the database" means here

The examples run against SurrealDB 3.3.0 embedded in the builder — the official engine library, no sockets, no servers. It is the same engine surreal start runs, minus the network layer — which is why every example can run against a fresh database of its own.

Reproducing it

The site builds locally in one command (from the repository root):

cargo build --bin surform
cargo run -p surform-docs --release -- --out docs/_site --cli target/release/surform

Then open docs/_site/index.html, or deploy it — the deployment recipe lives in docs/README.md in the repository.

The editors run the same pipeline

The Playground — and every editable example on these pages — runs the same compiler in your browser, compiled to WebAssembly: the same parser and codegen as the CLI. Every keystroke (debounced ~300 ms) runs through the pipeline: parse the SDL and, on a clean parse, re-parse the emission through the official parser. If the diagnostics card shows SDL-E1060, the compiler emitted DDL that the parser rejects — a Surform bug. The highlighting keywords and the example loader come from the same sources this build verifies, stamped in while the site builds.

The browser build does not carry the database: executing the DDL and reading INFO back stay build-time checks, run when the site is built against the embedded engine. That is why the canonical panels keep the text this build verified, and why Reset restores the example exactly as it was — the engine-checked original, not a browser re-derivation.

Where next

Back to the docs, or on to Getting started.