Upgrading from v0.26 to v0.27.0

This page lists every change in v0.27.0 that can affect code or a deploy that worked on v0.26.1. Each entry is one bullet: what changed, the old code, and the new code.

• Loud changes stop the build. The error names the change and ends with a link to its entry here, for example see docs/migration/v0.27.md#value-restriction.
• Silent changes compile, but the program behaves differently. The first run of a new sky prints these once ("Sky upgraded X -> Y"). Read them before you deploy.

Run sky install once after the upgrade: it regenerates sky-ffi/ in the new surface format. Then run sky check and fix what it reports. The full story of each change is in CHANGELOG.md under v0.27.0.

Loud (fails to compile, the error shows the fix)

Value restriction

• A top-level value with no parameters whose body is an application can no longer be used at two types inside a mutable or invariant type ([E2012]): shared = Task.run (Sync.newRef []) used as a Ref (List Int) and a Ref (List String) -> give it one type, shared : Result Error (Sync.Ref (List Int)).
• A point-free function that is not generic enough is the same error: render = makePrinter True -> render x = makePrinter True x.

any in annotations

• any in your own signature is no longer an unchecked cast. It is a hole the body fills, and callers see the filled type: coerce : a -> any then String.length (coerce 5) -> write the real type, coerce : a -> a, and fix the caller. Stdlib signatures are not affected.

Comparable bound

• <, >, compare, min, max, List.sort, the key of List.sortBy and Set elements need a comparable type ([E2001]): List.sortBy .price items with price : Decimal -> List.sortWith (\a b -> Decimal.compare a.price b.price) items.
• A signature that sorts must say so: largest : List a -> Maybe a -> largest : List comparable -> Maybe comparable.

Encodable bound

• Codec.auto, App.withDurable, Table.table, Jobs.define and Auth.signToken refuse a type that holds a function, a Secret, a key or a runtime handle ([E2001]): Codec.auto { model | proc = Nothing } with proc : Maybe Process -> keep the handle out of the saved record.

AEAD encrypt is a Task

• Crypto.aesGcmEncrypt and Crypto.chacha20Encrypt return Task Error String: case Crypto.aesGcmEncrypt key plain of Ok c -> ... -> case Task.run (Crypto.aesGcmEncrypt key plain) of Ok c -> ..., or chain it with Task.andThen. Decrypt stays a Result.

FFI Result enforced

• A sky add binding returns Result Error a, and the checker now enforces it: probe : Int and probe = Hex.encodedLen 3 -> probe = Hex.encodedLen 3 |> Result.withDefault 0, or handle the Err in a case.

Sky Ffi is stdlib-only

• Ffi.kernel, Ffi.call, Ffi.callPure and Ffi.callTask in application code are [E1011]: Ffi.kernel "Crypto_sha256" -> Crypto.sha256 (the hint names the stdlib function), or sky add the Go package and call its binding.

Registry packages are checked

• A fetched .skydeps package is type-checked with your code and has no Sky.Ffi: a package that no longer type-checks fails the build -> update the package, or ask its author for a v0.27.0 release.

FFI opaque Go types

• A Go value that has no Sky form is its own type (Pkg.Thing), no longer usable at any type: n = case Pkg.mk () of Ok t -> t used as an Int -> annotate t : Pkg.Thing and pass it only to bindings of that package.
• A Go value is not a kernel Value either: startServer : Value -> Result Error () for a router -> startServer : Mux.Router -> Result Error ().

FFI pointer is Maybe

• A Go pointer to a non-opaque type is a Maybe (nil is Nothing) in results, parameters, lists, fields and callbacks: Pkg.setName title p -> Pkg.setName (Just title) p, and Ok s -> s -> Ok (Just s) -> s.

FFI map keys

• A Go map with an int, float or bool key is a Dict with that key type: Dict String V for a Go map[int]V -> Dict Int V.

FFI callback result

• A callback passed to Go is typed from the Go signature, result included: Pkg.apply (\n -> n * 2) for a func(int) string -> Pkg.apply (\n -> String.fromInt n). A zero-parameter Go callback is () -> r.

FFI Go interface params

• A Sky value where Go wants an interface is [E2013]: Pkg.writeTo "x" s -> pass a Go value that implements the interface (from another binding). This holds through a binding bound to a name (w = Pkg.writeTo) or passed to a function (apply Pkg.writeTo "x" s) too.

FFI surface format 3

• A call through a binding of an older sky-ffi/ surface whose wrapper converted a value unsoundly is refused: old sky-ffi/ -> run sky install to regenerate it. All-native bindings still build, with a warning.

Auth verifyToken JSON

• Auth.verifyToken : Secret -> String -> Result Error Json.Value (it returned any type you asked for): verify s t = Auth.verifyToken s t typed Result Error (Dict String String) -> Auth.verifyToken s t |> Result.andThen (Decode.decodeValue (Decode.field "sub" Decode.string)).

Server withCookie typed

• Server.withCookie is String -> String -> String -> Response -> Response (it was any): Server.withCookie someCookie resp -> Server.addCookie someCookie resp, and Server.withCookie name value resp -> Server.addCookie (Server.cookie name value) resp. The four-argument form is unchanged.

Opaque handle constructors

• The constructors of WebSocket, WebSocketServer, StreamId, StreamWriter and Cache are hidden: Cache.Cache n, case c of Cache.Cache n -> ... or import Std.Cache exposing (Cache(..)) -> keep and pass the value itself, never build or match it.

New stdlib names

• A bare name that two exposing (..) imports now both export is [E1012] ambiguous: value "x" with Std.Html.Attributes and Json.Decode both exposed -> Attributes.value "x", or import Std.Html.Attributes exposing (value). The names that collide with an older export: Done, Event, Running, Step, address, close, island, onIslandEvent, raw, rpc, serve, spawn, stop, toMaybe, value, withClientCrypto, withEmbedded, withName, withSessionTransport. The error names both modules.

Stdlib combinators are checked

• Result.map, Result.withDefault, Result.andThen, Result.mapError, Maybe.isJust, Maybe.isNothing, identity, always and not had no signature, so any argument passed. A wrong one is now [E2001]: Ok "s" |> Result.map k with k : Int -> Int -> Ok 1 |> Result.map k, or a k that takes a String.

Recursive type alias

• A recursive type alias is [E1016] at its declaration (it passed sky check, then go build failed): type alias Node = { next : Maybe Node } -> type Node = Node { next : Maybe Node }. See docs/errors/E1016-recursive-type-alias.md.

init takes unit

• App.app, App.web, App.cli and App.tui fix init's seed to (): init : Page -> ( Model, Cmd Msg ) -> init : () -> ( Model, Cmd Msg ), and read the route with App.withRoutes / App.withOnNavigate, the request with App.withRequest.

WebOpts record literals

• WebOpts has two new fields: a literal App.WebOpts { port = 8000, ... } -> add embedded = False and sessionTransport = CookieSession, or write { App.webDefaults | port = 8000 }.
• WebSocketServerCfg has onFrame and frameMode: a literal cfg -> add onFrame = \_ _ -> Task.succeed () and frameMode = False, or build it with Ws.defaultCfg |> Ws.with....
• App.DurableWiring has discard: a hand-built record -> add discard = Durable.deleteSnapshot db, or use App.withDurable.

Native permissions

• Std.Bundle.Permission has six new constructors: a case over Permission -> add LocationAlways, PhotoLibrary, Contacts, FaceId, LocalNetwork and Bluetooth.
• A mobile build refuses a capability without its permission: Native.authenticate with no Bundle.FaceId -> add |> Bundle.withUsage Bundle.FaceId "<why>" (the same for Camera, Location, and Notifications on Android).

Spa rpc body value

• Spa.rpc and Spa.rpcWith take the request body as a value: Spa.rpc bodyCodec respCodec url (\model -> body) toMsg -> Spa.rpc bodyCodec respCodec url body toMsg. Generated split code needs only a rebuild.

Spa split refusals

• sky build of a Sky.Spa split refuses two wire records with one name, one module imported under several aliases, and a server arm it cannot read: the build names the site -> rename the record, use one alias, or split the arm into a named function.

Stdlib module names are reserved

• A package or app module named like a stdlib or kernel module is refused: src/Std/Log.sky or a dependency's module Auth -> rename it (App.Log).

sky check runs the Spa split

• sky check on a web:app or Spa.app project fails where sky build failed: a bare data-carrying union in the model -> give the field a Codec, or wrap the union in a record.

fmt refuses a file that does not parse

• sky fmt --check on a file with a syntax error exited 0: it now exits 1 with [E0001] -> fix the syntax.

sky add finds the project root

• sky add ../lib run in src/ wrote src/sky.toml: it now edits the project's sky.toml, and refuses outside a project -> run it inside the project.

Release refuses local addresses

• sky package --release refuses a local or private-network backend address: SKY_APP_URL=https://192.168.1.10/ -> a public host name in App.withAppUrl or SKY_APP_URL.

Dependency native code

• A dependency's Android fragment may add only <uses-permission>, <uses-feature> and <queries>, and a dangerous permission only when the app declares it too: a dependency adding READ_SMS -> declare it with Bundle.withPermission in the app.

Client crypto keys inside unions

• With App.withClientCrypto, a key inside a user union is refused in the model and on the wire: boxed : Maybe KeyBox with type KeyBox = KeyBox Noise.Handshake -> handshake : Maybe Noise.Handshake.

TestFlight ipa must match the project

• --upload testflight --ipa Other.ipa of another app or build is refused -> upload the project's own archive, or fix Bundle.withId / Bundle.withBuild.

Upgrades and installs verify checksums

• sky upgrade, install.sh and the Docker image refuse a download with no or a wrong checksums.txt entry: a mirror without checksums.txt -> publish the release's checksums.txt beside the archives.

Dependency names and paths

• sky add refuses a path or package name with ", \ or a control character: sky add '../q"uote' -> rename the directory.

Silent (compiles, behaves differently)

Each bullet below is printed once by the first run of the new sky.

Handles belong to their session

• SILENT A process, watcher, WebSocket or stream opened outside a Sky.Live session (in main) is Err PermissionDenied inside one: Process.write shared ... from update -> spawn it inside the session that uses it.

Handle ids are random

• SILENT A handle kept in a stored session across a restart or from another replica is Err "not live in this server": model.proc reused after a restart -> spawn or open it again on Err.

CAF handles are process-owned

• SILENT A top-level value that opens a process or watcher (shell = Task.run (Process.spawn ...)) belonged to the first session that used it: it is now owned by the process, not closed when that session ends.

Set-Cookie header holds every cookie

• SILENT A response that sets several cookies sends all of them now (before, only the first reached the browser), and resp.headers "Set-Cookie" holds every line joined by a newline, not only the first: Dict.get "Set-Cookie" resp.headers == Just line -> split it on "\n" and check the line you need.

readFileLimit positive limit

• SILENT File.readFileLimit path 0 read the whole file and is now Err InvalidInput: File.readFileLimit path 0 -> File.readFileLimit path 1048576.

File permissions no clamp

• SILENT File.permissions with a digit outside 0 to 7 gives -1, which File.chmod refuses: File.permissions 9 4 4 -> File.permissions 7 4 4.

resolveWithin empty root

• SILENT File.resolveWithin "" path meant the working directory and is now Err InvalidInput: File.resolveWithin "" path -> File.resolveWithin "." path.

PTY size bound

• SILENT Process.resize and Process.withPty above 500 columns by 200 rows are Err InvalidInput: { cols = 1000, rows = 400 } -> at most { cols = 500, rows = 200 }.

Compare derived order

• SILENT compare, List.sort and Set order a custom type by constructor declaration order, then the arguments, and a record by field name: compare Red (Green 1) was EQ -> it is LT when Red is declared first; Just _ sorts before Nothing, Ok _ before Err _, and Set.toList is ascending.

Compare NaN

• SILENT compare orders Floats totally with NaN greatest: compare nan 1 was EQ -> GT; compare nan nan is EQ, and nan < 1 and nan == nan stay False.

Task parallel panic

• SILENT A panic in a Task.parallel or Task.parallelN branch ended the process: the task that waits for the branches now raises it, so a server answers 500 for that request.

Process tree close

• SILENT Process.close left a shell's background jobs running: it ends the whole process tree -> start a job that must outlive its parent outside Sky.Core.Process.

Process release after exit

• SILENT Outside a session a process was kept until Process.close: it is released after it exits (30 s after, unless its output and status were read) -> read the output within 30 s of the exit.

Field read strict

• SILENT A field read of a value that is not that record gave nil: it is a classified CoerceFailure. Well-typed code needs no change.

Dict Go map keys

• SILENT A Go map[int]V from FFI became an empty Dict: its keys are converted, and a key that cannot be is a classified CoerceFailure.

Watch limit

• SILENT A watch past the descriptor or inotify limit missed a sub-tree without a word: it is Err at start, or an Overflow batch -> add large directories to ignore.

FFI integer range

• SILENT An out-of-range integer across the Go FFI is an Err: Pkg.big () gave Ok -1 for a uint64 above Int -> Err "... out of range for Int".

FFI Sky value to a Go interface

• SILENT A Sky runtime value (a Secret, a Std.Sync handle, a Maybe, a key) that reaches a Go interface parameter through an annotated generic helper is an Err: it passed when it implemented the interface (Secret is a fmt.Stringer) -> pass a Go value from another binding.

toString prints Sky syntax

• SILENT toString and Debug.toString print Sky syntax: 'a' was 97, Just 5 was 5, True was true, ["a","b"] was [a b], Nothing, (), an Error (IO: disk full) and records (fields sorted) changed too -> for stored or wire text use String.fromInt, String.fromFloat, a Codec or your own formatter.

decodeString rejects trailing text

• SILENT Json.Decode.decodeString and Codec.fromJson refuse text after the JSON value: decodeString int "3 x" was Ok 3 -> Err; cut the JSON out of a larger text (an LLM answer) before you decode it.

Json encode NaN

• SILENT Json.Encode.encode of a NaN or infinite Float returned "" and is a classified JsonEncodeFailure: guard the value with Math.isNaN before you encode it.

Codec auto union

• SILENT Codec.auto with a union blank decoded every object as the blank's variant: it returns the variant the JSON names, or Err.

Codec auto unencodable

• SILENT Codec.auto of a record with a Secret, key or handle field wrote {}: it is a classified JsonEncodeFailure -> move the field out of the saved or sent record, or write its codec by hand.

Ed25519 small-order keys

• SILENT Sign.publicKeyFromBytes refuses the eight small-order points and non-canonical encodings: it returned Ok -> handle the Err and ask the peer for a real key.

Loopback host guard

• SILENT A loopback server answers only localhost-style Host names outside production: a dev proxy name gets 403 -> set SKY_ALLOWED_HOSTS=<host> or SKY_PUBLIC_URL=https://<host>. Production on loopback behind a proxy is not checked.

Desktop console

• SILENT A --target desktop app mounted an open console on its loopback port: it mounts none -> set SKY_CONSOLE_AUTH=token to use it.

Console access follows the app sign-in

• SILENT Under SKY_CONSOLE_AUTH=app the Sky Console cookie kept access for 4 hours after an app sign-out or demotion: the console re-runs App.withConsoleAuth at most every 60 s and refuses with 403 once it answers Nothing (an open console tab stops receiving data and shows the 403 too), and the console sign-out ends the cookie on the server -> no code change; an admin who signs out of the app signs in to it again to reopen the console.

Served app namespace

• SILENT Each App.serve app has its own cookie sky_sid_<name> (else sky_sid_port-<N>), and port 0 with a durable store refuses to start without a name: App.serve app -> App.serve (app |> App.withName "admin").

Session rotation status codes

• SILENT For 60 s after sign-in, a request with the old Sky.Live id gets 409 Retry-After: 1 (event) or 503 Refresh: 1 (page), and /_sky/rotate and /_sky/sse-ticket are reserved paths -> keep 5xx alerts from firing on these.

X-Sky-Sid tag

• SILENT X-Sky-Sid in cookie transport carries a one-way tag t<hex>, never the session id: a tool that read the header as the id -> read the cookie.

Session cookie name

• SILENT Over HTTPS the Sky.Live cookie is __Host-sky_sid, and its value changes at sign-in: Dict.get "sky_sid" req.cookies as a key -> Live.sessionKey ().

Spa cookie sky spa

• SILENT The Sky.Spa session cookie is sky_spa (it shared sky_sid with Sky.Live), moved on the next request: a proxy rule or script that reads sky_sid for a web:app backend -> read sky_spa.

Spa legacy sessions

• SILENT A pre-v0.27.0 Sky.Spa session is converted once on its first request, so visitors stay signed in: nothing to change, but keep the signing key (SKY_SPA_SESSION_SECRET) the same across the upgrade.

Spa session key

• SILENT A development Sky.Spa key is .skydata/spa-session-secret.dev and production never reads it: set SKY_SPA_SESSION_SECRET (32+ bytes) in production to keep sessions across deploys and replicas.

Spa sign-out store

• SILENT Sky.Spa in production with no session store and an unwritable data dir refuses to start (it kept sign-outs in memory): set SKY_LIVE_STORE, or SKY_DATA_DIR to a writable directory.

Spa reload after deploy

• SILENT An open Sky.Spa tab across a deploy that changed the wire lost its follow-up writes: it reloads once and says the last action was not sent. Nothing to change.

Spa server links

• SILENT A Sky.Spa link or Nav.pushUrl to a path with no client route, or under /_sky/ or /_rpc/, is a full page load (it showed the in-app 404): for a path that is both, add Spa.serverRoute "GET /path" to withRoutes.

Spa one event one view

• SILENT In a Sky.Spa app one click runs only the handlers of the view it was delivered to, and a nested outer onClick carries the Msg of the clicked view.

Spa Msg order

• SILENT A Sky.Spa update runs once per Msg, in arrival order, and Msgs wait while a hold RPC (a server arm whose write needs server data) is in flight: put a long wait in a Cmd.perform.

Analytics per visitor

• SILENT Std.Analytics in a Sky.Spa backend or HTTP handler shared one anonymous id and one consent for all visitors: each visitor has its own -> call setConsent per visitor, and re-apply it after a restart.

PubSub reaches every app

• SILENT Std.PubSub.publish reached only the first Sky.Live app in the process: it reaches every running app.

Default web port

• SILENT A Std.App web app with no port binds sky.toml's port (8000 by default, it was 8080), and port = 0 means a free port: keep 8080 with [live] port = 8080.

Ui text wraps

• SILENT Ui.text outside a paragraph is its own wrapping box: two texts in a column now sit on two lines -> Ui.textNoWrap for one-line labels, Ui.paragraph to flow texts together.

sky test exit codes

• SILENT sky test exits 2 when nothing ran (a build failure), not 1: a CI step that tests for 1 -> test for 2 as well.

sky verify in a project

• SILENT sky verify in a project with an examples/ directory verifies the project (fmt, check, tests); it swept the examples and reported green.

sky test json report

• SILENT sky test --format json also writes the SKY_TEST_JSON=<path> report.

sky doctor auth secret

• SILENT sky doctor warns about SKY_AUTH_TOKEN_SECRET only for a project that imports Std.Auth.

Library check

• SILENT sky check in a library (no entry, no Main) checks every module and exits 0 when they build (it exited 1 "no entry main").

Dependency version tags

• SILENT A dependency version "0.1.3" resolves to the tag v0.1.3, and a version with no tag names the fix.

Codec dict on the Spa wire

• SILENT A Dict k v Sky.Spa wire field uses Codec.dict: a JSON array of [key, value] pairs.

New tables in your database

• SILENT The session store creates sky_session_aliases (and sky_session_bindings in a revocation Db), and sky db migrate --gen skips every sky_* table: the store's database role needs CREATE on first start.

Native shells

• SILENT An iOS or Android shell built by v0.26.1 still gets Native.notify through its old entry point: rebuild and ship the native shells with the backend for the new features.

sky fmt record update layout

• SILENT sky fmt lays out a record update that does not fit on one line in the standard form, so the first run reformats those lines (layout only, no change in meaning): { model | a = 1 with the next field at the outer indent -> { model on its own line, then | a = 1 and , b = 2 one step in.

Rolling back to v0.26.1

• Sign-outs recorded under v0.27.0 (the Sky.Spa sid claim and the alias table) are not enforced by v0.26.1.
• A Sky.Spa visitor holds a sky_spa cookie, which v0.26.1 does not read: they sign in again.
• A Sky.Live session that holds a Json.Value or Decimal does not decode on v0.26.1, so that session is lost.
• A served app's sky_sid_<name> cookie is not read by v0.26.1: those sessions start again.
• The new tables stay in the database. v0.26.1 ignores them; drop them only after the rollback is final.