Guides & internals
Topic deep-dives and compiler internals. New to Sky? Take the tour first. Looking up a module? See the API reference.
Guides
How to build things — the runtime, data, UI, auth, tooling, deployment.
- A medium production web:app, before and after
- ADT provenance and old saved snapshots
- Attribution run — where the interaction cost and the session memory go
- Audit-grade diagrams — `sky doc --diagram`
- Build speed at the final commit: v0.27.8 against v0.27.9
- Build speed, final: v0.27.8 against v0.27.9
- Build speed: levers deferred from v0.27.9
- Build speed: measurements behind the deferred levers
- Build speed: v0.27.8 against the perf/build-speed branch
- CLI reference
- Configuration architecture — build manifest, typed config, environment
- Correctness-first incremental execution for Sky
- Coverage ledger
- Cycle 4 field persistence diagnostics
- Cycle 8 collections
- Design deep-dive: `Std.App` config syntax + DX (the sole-front-door model)
- Design: `Std.App` — one builder, one `--target`, unifying Sky.Live / Sky.Spa / Sky.Tui / Sky.Cli / Sky.Webview
- Design: how a `Std.App` app configures itself — `withX` + `SKY_*` env
- Does Sky.Live's throughput scale with cores?
- Durable execution — `Std.Durable`
- Embedded PostgreSQL
- Embedded PostgreSQL — local end-to-end delivery proof (2026-08-16)
- Embedded Sky.Live — a Live app inside a Task program
- Evaluating a model: `Std.Ai.Eval`
- Fine-tuning adapters: `Std.Ai.Train`
- Forum re-baseline — the interaction cost on an application, at HEAD
- Generated typed Codec.auto codecs vs the reflective walker (2026-11-10)
- Getting started
- HOF dispatch — A/B for the `coerce_if_needed` eta-expansion
- Incremental execution final validation continuation
- Incremental execution: implementation and validation
- Incremental persistence: protocol obligations
- Is `GOGC` a shippable default, or a trap?
- Keys on the device: `withClientCrypto`
- Known limitations (v0.30.x)
- LLM agents — `Std.Ai`
- Language Server
- Language syntax
- Local and remote models: `Std.Ai.Endpoint` and `Std.Ai.Local`
- Method — verifying the shipped GC default
- Migrating to the `Secret` type
- Mobile shells: a rebuild runs no shell tool
- Modules
- Native shells: permissions, entitlements, secure storage, release
- Observability — tracing & spans (user guide)
- On-device models: `Std.Ai.Device`
- Oversized primitive Dict changes
- Pattern matching
- Persistent B+-tree prototype for `Dict` (design 1b, stage D2) — 2026-10-28
- Persistent `Dict` (stage D2): design chosen by measurement — 2026-10-28
- Raw data — Sky.Live under load on x86 GCE, 2026-08-15
- Raw data — embedded PostgreSQL under load on x86 GCE, 2026-08-15
- Relay soak: a slow RSS rise is bounded telemetry rings under GOGC=400 (2026-09-29)
- Render-pipeline optimization — Html→VNode reflect de-boxing
- Render-pipeline optimization — Std.Ui `renderNodeAs` append-on-empty
- Roadmap: consolidate on `Std.App`, deprecate the per-shape front doors
- Sizing a Sky deployment: memory, CPU and sessions
- Sky CI/CD + Test Architecture — v2 (reconciled)
- Sky auto-testing — Phase 3: the deterministic effect-mock harness
- Sky auto-testing — design (draft)
- Sky in two programs
- Sky.Live architecture
- Sky.Live capacity on x86 GCE — the mandate's number, measured
- Sky.Live input authority protocol
- Sky.Live overview
- Sky.Live production-resilience — hidden silent-failure class (2026-08-01)
- Sky.Live pub/sub
- Sky.Live topic-based pub/sub — design doc
- Sky.Spa de-reflection (prod web) — progress tracker
- Sky.Spa emit-path prototype — results (VERIFIED)
- Sky.Spa v1 — client routing + the explicit typed server boundary (P4)
- Sky.Spa v1 — progress tracker (autonomous build)
- Sky.Spa — client-side TEA (overview)
- Sky.Spa — client-side TEA, statically partitioned (design)
- Sky.Spa — production web (exploration + measured evidence)
- Sky.Spa — the auto-split: `Task`-type tracing + the effects-via-`Cmd` dialect
- Sky.Tui overview
- Sky.Webview
- Stage 1 — runtime constant factors on the interaction hot path
- Stage 2 — the erased list-helper round trip, removed where it is provable
- Stage 3 — a provable `List.foldl` / `List.any` call stops widening its list
- Stage 4 — a provable `++`, and a provable length read, stop widening their lists
- Standard library reference
- Std.Ai on Google Cloud: training on Vertex AI, serving on Cloud Run
- Std.Ai.Serve: the GPU tier
- Std.Ai.Trace: what model calls did and cost
- Std.App — one builder, one `--target`
- Std.Auth overview
- Std.Db overview
- Std.Ui overview
- Std.Ui.Canvas — SVG against a batched `<canvas>`
- Std.Ui.Terminal — DOM byte stream vs. server screen + canvas
- Step-cost measurement
- Stream G: run the front end once per Sky.Spa build
- Streaming HTTP responses (`Sky.Core.Http.Stream`)
- Testing Sky projects
- Testing the Std.Ai lifecycle: a guide
- The AI application lifecycle in Sky: build, data, train, eval, registry, serve
- The four contended locks: contention removed, throughput unchanged — a null
- The gate harness (`xtask harness`)
- The model registry: `Std.Ai.Registry`
- The project's AI pipeline: `Std.Ai.Pipeline` and `sky ai`
- The shipped GC default: does the bound actually hold?
- Tiered session cache — bounded RAM working set + disk backing
- Training and evaluation data: `Std.Ai.Dataset`, `Scrub` and `Synthetic`
- Transparent Msg-replay for `Std.Durable` — an epic, not a patch
- Typed list destructuring — `rt.SkyLenT` / `SkyElemT` / `SkyTailSliceT`
- Types
- Upgrading from v0.26 to v0.27.0
- Upgrading from v0.27 to v0.28.0
- Upgrading from v0.28 to v0.29.0
- Upgrading from v0.29 to v0.30.0
- Validating the Sky.Live numbers on real x86 hardware
- What a Sky.Live interaction actually costs
- What a headless Sky.Http.Server + Std.Db read costs
- What an interaction costs on an application
- `examples/13-skyshop`: empty Go cache, after the `-p` fix
- `sky.toml` — project manifest reference
Compiler & contributing
For contributors: the Rust compiler architecture, the FFI boundary, stdlib correctness, and how to work in the repo.
- 00 — Goals & Principles
- 01 — Architecture Overview
- 02 — Workspace & Crates
- 03 — Language Reference (the compat contract)
- 04 — Syntax: Lexer, Lossless CST, Layout & Recovery
- 05 — Name Resolution (the `hir` crate)
- 06 — Type System (the `ty` crate)
- 07 — Lowering & the Typed Go-IR
- 08 — Go Codegen
- 09 — Runtime & FFI
- 10 — LSP & Tooling
- 11 — Testing & Verification
- 13 — Change verification & the edge-case matrix
- 14 — Runtime-Narrowing Taxonomy (origins, floor, levers)
- Development
- Error system
- FFI boundary philosophy
- FFI design
- Go interop
- Known divergences — the Rust-vs-oracle ledger
- Sky Compiler — Rust Rewrite (architecture-first)
- Sky stdlib — Canonical correctness reference
- [E1011] NOT EXPOSED
- [E1015] UNKNOWN EXPORT
- [E1016] RECURSIVE TYPE ALIAS
- [E1017] CONSTRUCTOR CLASH
- [E1018] BAD RECURSION
- [E2014] INVALID REGEX