@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-language/references/swift-patterns-extended.md

@@ -1,518 +1,475 @@
-# Swift Patterns Extended Reference
+# Extended Swift patterns
 
-Additional patterns and examples that extend the core SKILL.md. Refer to this file for deeper Codable patterns, advanced result builder techniques, and supplementary collection/formatting recipes.
+Longer examples behind the main skill. Deep Codable work still belongs to
+`swift-codable`, and format styles beyond a custom style to `swift-formatstyle`.
 
 ## Contents
 
-- [Codable: Enums with Associated Values](#codable-enums-with-associated-values)
-- [Codable: Date Decoding Strategies](#codable-date-decoding-strategies)
-- [Codable: Unkeyed Containers (Arrays)](#codable-unkeyed-containers-arrays)
-- [Codable: Wrapper for Lossy Array Decoding](#codable-wrapper-for-lossy-array-decoding)
-- [Codable: `@dynamicMemberLookup` Wrapper](#codable-dynamicmemberlookup-wrapper)
-- [Result Builder: HTML Builder](#result-builder-html-builder)
-- [Result Builder: buildFinalResult](#result-builder-buildfinalresult)
-- [Property Wrapper: UserDefaults-Backed](#property-wrapper-userdefaults-backed)
-- [Property Wrapper: Validated](#property-wrapper-validated)
-- [Advanced Regex Builder Patterns](#advanced-regex-builder-patterns)
-- [FormatStyle: Custom FormatStyle](#formatstyle-custom-formatstyle)
-- [Collection Patterns: Chunking and Windows](#collection-patterns-chunking-and-windows)
-- [Guard: Complex Pattern Matching](#guard-complex-pattern-matching)
-- [Typed Throws: Protocol with Typed Errors](#typed-throws-protocol-with-typed-errors)
-- [String Interpolation: Custom appendInterpolation](#string-interpolation-custom-appendinterpolation)
-- [Never: Advanced Usage](#never-advanced-usage)
-
-## Codable: Enums with Associated Values
+- [Codable](#codable)
+- [Result builders](#result-builders)
+- [Property wrappers](#property-wrappers)
+- [Advanced Regex](#advanced-regex)
+- [Custom FormatStyle](#custom-formatstyle)
+- [Collection patterns](#collection-patterns)
+- [guard: complex pattern matching](#guard-complex-pattern-matching)
+- [Typed throws in protocols](#typed-throws-in-protocols)
+- [String interpolation](#string-interpolation)
+- [Never: advanced usage](#never-advanced-usage)
+
+## Codable
+
+### Enums with associated values
+
+Encode a discriminator key next to the payload keys, and throw a data
+corruption error for a discriminator you do not recognise.
 
 ```swift
-enum Shape: Codable {
-    case circle(radius: Double)
-    case rectangle(width: Double, height: Double)
+enum Reward: Codable {
+    case points(Int)
+    case voucher(code: String, percent: Int)
 
-    enum CodingKeys: String, CodingKey {
-        case type, radius, width, height
-    }
+    private enum CodingKeys: String, CodingKey { case kind, amount, code, percent }
 
     func encode(to encoder: Encoder) throws {
-        var container = encoder.container(keyedBy: CodingKeys.self)
+        var c = encoder.container(keyedBy: CodingKeys.self)
         switch self {
-        case .circle(let radius):
-            try container.encode("circle", forKey: .type)
-            try container.encode(radius, forKey: .radius)
-        case .rectangle(let width, let height):
-            try container.encode("rectangle", forKey: .type)
-            try container.encode(width, forKey: .width)
-            try container.encode(height, forKey: .height)
+        case .points(let n):
+            try c.encode("points", forKey: .kind)
+            try c.encode(n, forKey: .amount)
+        case .voucher(let code, let percent):
+            try c.encode("voucher", forKey: .kind)
+            try c.encode(code, forKey: .code)
+            try c.encode(percent, forKey: .percent)
         }
     }
 
     init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        let type = try container.decode(String.self, forKey: .type)
-        switch type {
-        case "circle":
-            let radius = try container.decode(Double.self, forKey: .radius)
-            self = .circle(radius: radius)
-        case "rectangle":
-            let width = try container.decode(Double.self, forKey: .width)
-            let height = try container.decode(Double.self, forKey: .height)
-            self = .rectangle(width: width, height: height)
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        let kind = try c.decode(String.self, forKey: .kind)
+        switch kind {
+        case "points":
+            self = .points(try c.decode(Int.self, forKey: .amount))
+        case "voucher":
+            self = .voucher(code: try c.decode(String.self, forKey: .code),
+                            percent: try c.decode(Int.self, forKey: .percent))
         default:
-            throw DecodingError.dataCorruptedError(
-                forKey: .type, in: container,
-                debugDescription: "Unknown shape type: \(type)")
+            throw DecodingError.dataCorruptedError(forKey: .kind, in: c,
+                debugDescription: "Unrecognised reward kind \(kind)")
         }
     }
 }
 ```
 
-## Codable: Date Decoding Strategies
-
-```swift
-// Configure decoder for specific date formats
-let decoder = JSONDecoder()
+### Date strategies
 
-// ISO 8601 (most common for APIs)
-decoder.dateDecodingStrategy = .iso8601
+Set `dateDecodingStrategy` on the `JSONDecoder`:
 
-// Unix timestamp (seconds since epoch)
-decoder.dateDecodingStrategy = .secondsSince1970
+- `.iso8601` for standard ISO 8601 strings.
+- `.secondsSince1970` for Unix timestamps.
+- `.formatted(formatter)` with a `DateFormatter` whose locale is
+  `en_US_POSIX`, so user settings cannot change parsing.
+- `.custom` when the feed mixes formats:
 
-// Custom format
-let formatter = DateFormatter()
-formatter.dateFormat = "yyyy-MM-dd"
-formatter.locale = Locale(identifier: "en_US_POSIX")
-decoder.dateDecodingStrategy = .formatted(formatter)
-
-// Multiple formats in one payload
-decoder.dateDecodingStrategy = .custom { decoder in
-    let container = try decoder.singleValueContainer()
-    let string = try container.decode(String.self)
-
-    let iso = ISO8601DateFormatter()
-    if let date = iso.date(from: string) { return date }
-
-    let fallback = DateFormatter()
-    fallback.dateFormat = "yyyy-MM-dd"
-    fallback.locale = Locale(identifier: "en_US_POSIX")
-    if let date = fallback.date(from: string) { return date }
-
-    throw DecodingError.dataCorruptedError(
-        in: container, debugDescription: "Cannot decode date: \(string)")
+```swift
+import Foundation
+
+let reader = JSONDecoder()
+reader.dateDecodingStrategy = .custom { decoder in
+    let box = try decoder.singleValueContainer()
+    let raw = try box.decode(String.self)
+    if let stamp = ISO8601DateFormatter().date(from: raw) { return stamp }
+    let dayOnly = DateFormatter()
+    dayOnly.locale = Locale(identifier: "en_US_POSIX")
+    dayOnly.dateFormat = "yyyy-MM-dd"
+    if let stamp = dayOnly.date(from: raw) { return stamp }
+    throw DecodingError.dataCorruptedError(in: box,
+        debugDescription: "Unreadable date \(raw)")
 }
 ```
 
-## Codable: Unkeyed Containers (Arrays)
+### Unkeyed containers
 
-```swift
-// JSON: { "coordinates": [37.7749, -122.4194] }
-struct Location: Decodable {
-    let latitude: Double
-    let longitude: Double
+A JSON array whose positions carry meaning, such as `[51.5, -0.12, 35]`, maps
+onto named fields by reading it in order:
 
-    enum CodingKeys: String, CodingKey {
-        case coordinates
-    }
+```swift
+struct Fix: Decodable {
+    var lat: Double, lon: Double, altitude: Double
+    private enum CodingKeys: String, CodingKey { case point }
 
     init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        var coords = try container.nestedUnkeyedContainer(forKey: .coordinates)
-        latitude = try coords.decode(Double.self)
-        longitude = try coords.decode(Double.self)
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        var point = try c.nestedUnkeyedContainer(forKey: .point)
+        lat = try point.decode(Double.self)
+        lon = try point.decode(Double.self)
+        altitude = try point.decode(Double.self)
     }
 }
 ```
 
-## Codable: Wrapper for Lossy Array Decoding
+### Skipping bad elements
 
-Skip invalid elements instead of failing the entire array:
+One malformed element should not fail the whole array. Decode each element
+with `try?`; when it fails, decode a throwaway value so the container moves
+past it.
 
 ```swift
-struct LossyArray<Element: Decodable>: Decodable {
-    let elements: [Element]
+struct Tolerant<Element: Decodable>: Decodable {
+    var values: [Element] = []
+    private struct Skip: Decodable {}
 
     init(from decoder: Decoder) throws {
-        var container = try decoder.unkeyedContainer()
-        var result: [Element] = []
-        while !container.isAtEnd {
-            if let element = try? container.decode(Element.self) {
-                result.append(element)
+        var list = try decoder.unkeyedContainer()
+        while !list.isAtEnd {
+            if let item = try? list.decode(Element.self) {
+                values.append(item)
             } else {
-                _ = try? container.decode(AnyCodable.self) // skip invalid
+                _ = try? list.decode(Skip.self)
             }
         }
-        elements = result
     }
 }
-
-private struct AnyCodable: Decodable {}
 ```
 
-## Codable: `@dynamicMemberLookup` Wrapper
+### Dynamic member lookup over loose JSON
 
-Type-safe access to arbitrary JSON:
+For payloads with no fixed shape, a `@dynamicMemberLookup` wrapper gives
+dot-syntax access over a dictionary, with typed helpers:
 
 ```swift
 @dynamicMemberLookup
-struct JSONValue: Decodable {
-    private let storage: [String: Any]
-
-    subscript(dynamicMember key: String) -> JSONValue? {
-        guard let value = storage[key] as? [String: Any] else { return nil }
-        return JSONValue(storage: value)
-    }
-
-    func string(for key: String) -> String? {
-        storage[key] as? String
-    }
+struct LooseJSON {
+    private let fields: [String: Any]
+    init(_ fields: [String: Any]) { self.fields = fields }
 
-    func int(for key: String) -> Int? {
-        storage[key] as? Int
-    }
-
-    init(from decoder: Decoder) throws {
-        let container = try decoder.singleValueContainer()
-        guard let dict = try container.decode([String: AnyCodableValue].self)
-            .mapValues({ $0.value }) as? [String: Any] else {
-            throw DecodingError.typeMismatch(
-                [String: Any].self,
-                .init(codingPath: decoder.codingPath,
-                      debugDescription: "Expected dictionary"))
-        }
-        storage = dict
+    subscript(dynamicMember key: String) -> LooseJSON? {
+        (fields[key] as? [String: Any]).map(LooseJSON.init)
     }
+    func text(_ key: String) -> String? { fields[key] as? String }
+    func number(_ key: String) -> Double? { fields[key] as? Double }
 }
+
+let doc = LooseJSON(["owner": ["name": "Lena", "karma": 12.0]])
+let ownerName = doc.owner?.text("name")
 ```
 
-## Result Builder: HTML Builder
+## Result builders
 
-A practical example of a custom result builder:
+A builder that joins markup fragments, with optional, either and loop support:
 
 ```swift
 @resultBuilder
-struct HTMLBuilder {
-    static func buildBlock(_ components: String...) -> String {
-        components.joined(separator: "\n")
-    }
-
-    static func buildOptional(_ component: String?) -> String {
-        component ?? ""
-    }
-
-    static func buildEither(first component: String) -> String {
-        component
-    }
-
-    static func buildEither(second component: String) -> String {
-        component
-    }
-
-    static func buildArray(_ components: [String]) -> String {
-        components.joined(separator: "\n")
-    }
+enum MarkupBuilder {
+    static func buildBlock(_ parts: String...) -> String { parts.joined(separator: "\n") }
+    static func buildOptional(_ part: String?) -> String { part ?? "" }
+    static func buildEither(first part: String) -> String { part }
+    static func buildEither(second part: String) -> String { part }
+    static func buildArray(_ parts: [String]) -> String { parts.joined(separator: "\n") }
 }
 
-func div(@HTMLBuilder content: () -> String) -> String {
-    "<div>\n\(content())\n</div>"
-}
+func section(@MarkupBuilder _ body: () -> String) -> String { "<section>\n\(body())\n</section>" }
+func heading(_ t: String) -> String { "<h2>\(t)</h2>" }
+func para(_ t: String) -> String { "<p>\(t)</p>" }
 
-func p(_ text: String) -> String { "<p>\(text)</p>" }
-func h1(_ text: String) -> String { "<h1>\(text)</h1>" }
-
-let html = div {
-    h1("Welcome")
-    p("Hello, world!")
-    if showDetails {
-        p("Details here")
-    }
+let isBeta = true
+let page = section {
+    heading("Release notes")
+    para("Faster sync.")
+    if isBeta { para("Beta build.") }
 }
 ```
 
-## Result Builder: buildFinalResult
-
-Transform the accumulated result at the end:
+`buildFinalResult` converts the accumulated component into a different output
+type at the very end. A builder can collect `AttributedString` pieces and hand
+back a SwiftUI `Text`:
 
 ```swift
-@resultBuilder
-struct AttributedStringBuilder {
-    static func buildBlock(_ components: AttributedString...) -> AttributedString {
-        components.reduce(into: AttributedString()) { $0.append($1) }
-    }
+import SwiftUI
 
-    static func buildFinalResult(_ component: AttributedString) -> Text {
-        Text(component)
+@resultBuilder
+enum StyledTextBuilder {
+    static func buildExpression(_ s: AttributedString) -> AttributedString { s }
+    static func buildBlock(_ parts: AttributedString...) -> AttributedString {
+        parts.reduce(into: AttributedString()) { $0.append($1) }
     }
+    static func buildFinalResult(_ joined: AttributedString) -> Text { Text(joined) }
 }
 ```
 
-## Property Wrapper: UserDefaults-Backed
+## Property wrappers
+
+### Backed by UserDefaults
 
 ```swift
+import Foundation
+
 @propertyWrapper
-struct AppStorage<Value> {
+struct Preference<Value> {
     let key: String
-    let defaultValue: Value
-    let store: UserDefaults
+    let fallback: Value
+    let defaults: UserDefaults
 
-    var wrappedValue: Value {
-        get { store.object(forKey: key) as? Value ?? defaultValue }
-        set { store.set(newValue, forKey: key) }
+    init(wrappedValue: Value, _ key: String, defaults: UserDefaults = .standard) {
+        self.key = key
+        self.fallback = wrappedValue
+        self.defaults = defaults
     }
 
-    init(wrappedValue: Value, _ key: String, store: UserDefaults = .standard) {
-        self.key = key
-        self.defaultValue = wrappedValue
-        self.store = store
+    var wrappedValue: Value {
+        get { defaults.object(forKey: key) as? Value ?? fallback }
+        set { defaults.set(newValue, forKey: key) }
     }
 }
 
-// Usage
-struct Settings {
-    @AppStorage("onboarding_complete") var onboardingComplete = false
-    @AppStorage("preferred_theme") var theme = "system"
+struct ReaderSettings {
+    @Preference("fontScale") var fontScale = 1.0
+    @Preference("nightMode") var nightMode = false
 }
 ```
 
-## Property Wrapper: Validated
+Passing a suite-specific `UserDefaults` in tests keeps them isolated.
+
+### Validation with a projected flag
 
 ```swift
 @propertyWrapper
-struct Validated<Value> {
-    private var value: Value
-    private let validator: (Value) -> Bool
-    private(set) var isValid: Bool
+struct Checked {
+    private var text = ""
+    private let rule: (String) -> Bool
+    private(set) var passes = false
 
-    var wrappedValue: Value {
-        get { value }
-        set {
-            value = newValue
-            isValid = validator(newValue)
-        }
+    init(wrappedValue: String, _ rule: @escaping (String) -> Bool) {
+        self.rule = rule
+        self.wrappedValue = wrappedValue
     }
 
-    var projectedValue: Bool { isValid }
-
-    init(wrappedValue: Value, _ validator: @escaping (Value) -> Bool) {
-        self.value = wrappedValue
-        self.validator = validator
-        self.isValid = validator(wrappedValue)
+    var wrappedValue: String {
+        get { text }
+        set { text = newValue; passes = rule(newValue) }
     }
+    var projectedValue: Bool { passes }
 }
 
-// Usage
-struct SignUpForm {
-    @Validated({ $0.count >= 3 }) var username = ""
-    @Validated({ $0.contains("@") && $0.contains(".") }) var email = ""
-
-    var canSubmit: Bool { $username && $email }
+struct SignupForm {
+    @Checked({ $0.count >= 3 }) var handle = ""
+    @Checked({ $0.contains("@") }) var mail = ""
+    var canSubmit: Bool { $handle && $mail }
 }
 ```
 
-## Advanced Regex Builder Patterns
+## Advanced Regex
 
-### Reference captures with strong typing
+A `Reference` names a capture so it can be read by key instead of by tuple
+position. `ChoiceOf` lists alternatives.
 
 ```swift
 import RegexBuilder
 
-struct LogEntry {
-    let timestamp: String
-    let level: String
-    let message: String
+let level = Reference(Substring.self)
+let message = Reference(Substring.self)
+let logLine = Regex {
+    "["
+    Capture(as: level) { ChoiceOf { "DEBUG"; "NOTICE"; "FAULT" } }
+    "] "
+    Capture(as: message) { OneOrMore(.any) }
 }
-
-let timestampRef = Reference(Substring.self)
-let levelRef = Reference(Substring.self)
-let messageRef = Reference(Substring.self)
-
-let logRegex = Regex {
-    Capture(as: timestampRef) { /\[.+?\]/ }
-    " "
-    Capture(as: levelRef) {
-        ChoiceOf { "INFO"; "WARN"; "ERROR"; "DEBUG" }
-    }
-    ": "
-    Capture(as: messageRef) { OneOrMore(.any) }
-}
-
-if let match = "[2026-05-28] INFO: Started".firstMatch(of: logRegex) {
-    let entry = LogEntry(
-        timestamp: String(match[timestampRef]),
-        level: String(match[levelRef]),
-        message: String(match[messageRef])
-    )
-    _ = entry
+if let m = "[FAULT] disk full".firstMatch(of: logLine) {
+    print(m[level], m[message])
 }
 ```
 
-### Reusing regex components
+Small pieces compose into larger patterns. An IPv4 octet built once and reused:
 
 ```swift
-let ipOctet = Regex {
+let octet = Regex {
     ChoiceOf {
         Regex { "25"; ("0"..."5") }
-        Regex { "2"; ("0"..."4"); .digit }
-        Regex { Optionally { ("0"..."1") }; .digit; Optionally { .digit } }
+        Regex { "2"; ("0"..."4"); One(.digit) }
+        Regex { Optionally { ("0"..."1") }; One(.digit); Optionally { One(.digit) } }
     }
 }
-
-let ipAddress = Regex {
-    ipOctet; "."; ipOctet; "."; ipOctet; "."; ipOctet
+let ipv4 = Regex {
+    octet; "."; octet; "."; octet; "."; octet
 }
+let isAddress = "10.0.254.1".wholeMatch(of: ipv4) != nil
 ```
 
-## FormatStyle: Custom FormatStyle
+## Custom FormatStyle
 
-Create reusable format styles for domain types:
+Conform to `FormatStyle`, name the input and output types, implement
+`format(_:)`, then add a static member so call sites read naturally.
 
 ```swift
-struct FileSize {
-    let bytes: Int64
-}
+import Foundation
 
-struct FileSizeFormatStyle: FormatStyle {
-    typealias FormatInput = FileSize
+struct PaceStyle: FormatStyle {
+    typealias FormatInput = Double
     typealias FormatOutput = String
 
-    func format(_ value: FileSize) -> String {
-        ByteCountFormatter.string(fromByteCount: value.bytes, countStyle: .file)
+    func format(_ secondsPerKm: Double) -> String {
+        let total = Int(secondsPerKm.rounded())
+        return "\(total / 60)'\(String(format: "%02d", total % 60))\" /km"
     }
 }
 
-extension FormatStyle where Self == FileSizeFormatStyle {
-    static var fileSize: FileSizeFormatStyle { .init() }
+extension FormatStyle where Self == PaceStyle {
+    static var pace: PaceStyle { PaceStyle() }
 }
 
-// Usage
-let size = FileSize(bytes: 1_500_000)
-size.formatted(.fileSize) // "1.5 MB"
+let label = 312.0.formatted(.pace)
 ```
 
-## Collection Patterns: Chunking and Windows
+Anything more (locale-aware parsing, attributed output) goes to
+`swift-formatstyle`.
+
+## Collection patterns
+
+The Swift Algorithms package (`import Algorithms`) adds sequence helpers:
 
 ```swift
-// chunks(ofCount:) -- Swift Algorithms package
 import Algorithms
 
-let batches = items.chunks(ofCount: 10)
-for batch in batches {
-    try await upload(batch)
-}
+let uploads = Array(1...23)
+for batch in uploads.chunks(ofCount: 10) { print(batch.count) }
 
-// windows(ofCount:) -- sliding window
-let movingAverages = values.windows(ofCount: 3).map { window in
-    window.reduce(0, +) / Double(window.count)
-}
+let readings = [3.0, 5.0, 4.0, 8.0, 6.0]
+let smoothed = readings.windows(ofCount: 3).map { $0.reduce(0, +) / 3 }
 
-// adjacentPairs() -- process consecutive elements
-for (previous, current) in values.adjacentPairs() {
-    if current > previous * 2 {
-        print("Spike detected")
-    }
-}
+let stops = ["Depot", "Mill Rd", "Harbour"]
+let legs = stops.adjacentPairs().map { "\($0) to \($1)" }
 ```
 
-## Guard: Complex Pattern Matching
+`chunks(ofCount:)` batches, `windows(ofCount:)` slides a fixed window (a
+moving average here), `adjacentPairs()` pairs each element with the next.
+
+## guard: complex pattern matching
+
+Several clauses in one `guard` can walk untyped JSON. Prefer Codable when the
+shape is known; this is for genuinely dynamic input.
 
 ```swift
-func processResponse(_ data: Data) throws -> User {
-    guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-          let userData = json["user"] as? [String: Any],
-          let name = userData["name"] as? String,
-          let id = userData["id"] as? Int
-    else {
-        throw ParseError.invalidFormat
-    }
+import Foundation
 
-    // Use Codable instead when practical -- this is for mixed/dynamic JSON
-    return User(id: id, name: name)
+func firstTrackTitle(_ data: Data) -> String? {
+    guard let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          let album = root["album"] as? [String: Any],
+          let tracks = album["tracks"] as? [[String: Any]],
+          let title = tracks.first?["title"] as? String
+    else { return nil }
+    return title
 }
+```
 
-// Guard with where clause
-func processItems(_ items: [Item]) {
-    for item in items {
-        guard case .active(let config) = item.status,
-              config.isEnabled,
-              !config.isExpired
-        else { continue }
+Enum payloads plus extra conditions work inside loops:
 
-        activate(item, with: config)
+```swift
+struct Plan { var isEnabled: Bool; var isExpired: Bool }
+enum Status { case active(Plan), paused }
+struct Account { var name: String; var status: Status }
+
+func billable(_ accounts: [Account]) -> [String] {
+    var names: [String] = []
+    for account in accounts {
+        guard case .active(let plan) = account.status, plan.isEnabled, !plan.isExpired else {
+            continue
+        }
+        names.append(account.name)
     }
+    return names
 }
 ```
 
-## Typed Throws: Protocol with Typed Errors
+## Typed throws in protocols
+
+An associated error type lets each conformer throw its own concrete error
+while callers keep exhaustive handling.
 
 ```swift
-protocol DataStore {
-    associatedtype StoreError: Error
-    func save(_ data: Data) throws(StoreError)
-    func load(id: String) throws(StoreError) -> Data
+protocol Vault {
+    associatedtype VaultError: Error
+    func read(_ key: String) throws(VaultError) -> Data
+    func write(_ data: Data, for key: String) throws(VaultError)
 }
 
-struct FileStore: DataStore {
-    enum StoreError: Error {
-        case notFound, permissionDenied, diskFull
-    }
+final class MemoryVault: Vault {
+    enum VaultError: Error { case missing(String), full }
+    var slots: [String: Data] = [:]
+    let capacity = 8
 
-    func save(_ data: Data) throws(StoreError) {
-        // ...
+    func read(_ key: String) throws(VaultError) -> Data {
+        guard let data = slots[key] else { throw .missing(key) }
+        return data
     }
-
-    func load(id: String) throws(StoreError) -> Data {
-        guard fileExists(id) else { throw .notFound }
-        // ...
+    func write(_ data: Data, for key: String) throws(VaultError) {
+        guard slots.count < capacity || slots[key] != nil else { throw .full }
+        slots[key] = data
     }
 }
 ```
 
-## String Interpolation: Custom appendInterpolation
+## String interpolation
 
-Apple documents `DefaultStringInterpolation` as the type used while building interpolated strings, and supports extending it with custom `appendInterpolation(...)` overloads.
+Add `appendInterpolation` overloads to `DefaultStringInterpolation`:
 
 ```swift
+import Foundation
+
 extension DefaultStringInterpolation {
     mutating func appendInterpolation(json value: some Encodable) {
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        if let data = try? encoder.encode(value),
-           let string = String(data: data, encoding: .utf8) {
-            appendLiteral(string)
+        let writer = JSONEncoder()
+        writer.outputFormatting = [.prettyPrinted, .sortedKeys]
+        if let data = try? writer.encode(value), let text = String(data: data, encoding: .utf8) {
+            appendLiteral(text)
+        } else {
+            appendLiteral("<unencodable>")
         }
     }
 
-    mutating func appendInterpolation(ordinal value: Int) {
-        let formatter = NumberFormatter()
-        formatter.numberStyle = .ordinal
-        if let result = formatter.string(from: value as NSNumber) {
-            appendLiteral(result)
-        }
+    mutating func appendInterpolation(ordinal n: Int) {
+        let f = NumberFormatter()
+        f.numberStyle = .ordinal
+        appendLiteral(f.string(from: NSNumber(value: n)) ?? String(n))
     }
 }
 
-print("Config: \(json: settings)")
-print("You placed \(ordinal: 3)")
+struct Seat: Encodable { var row: Int; var letter: String }
+let dump = "\(json: Seat(row: 12, letter: "C"))"
+let place = "You finished \(ordinal: 2)"
 ```
 
-## Never: Advanced Usage
+## Never: advanced usage
 
-```swift
-// Publisher that never fails
-let publisher: AnyPublisher<String, Never> = Just("hello").eraseToAnyPublisher()
+- Combine uses `Never` as a failure type: `AnyPublisher<Int, Never>` is a
+  stream that cannot fail, which is what `assign(to:)` and SwiftUI bindings
+  expect.
+- Empty enums are uninhabited too, which makes them good phantom types. A
+  generic parameter can carry state in the type, and constrained extensions
+  expose methods only in the right state:
 
-// Phantom type preventing construction
-enum Locked {}
-enum Unlocked {}
+```swift
+enum Draft {}
+enum Published {}
 
-struct Door<State> {
-    private init() {}
+struct Article<Stage> {
+    var body: String
 }
 
-extension Door where State == Unlocked {
-    func open() { /* ... */ }
+extension Article where Stage == Draft {
+    func publish() -> Article<Published> { Article<Published>(body: body) }
 }
 
-// Generic constraint meaning "this case cannot happen"
-func absurd<T>(_ never: Never) -> T {
-    // No body needed -- Never has no values, so this is never called
+extension Article where Stage == Published {
+    var shareURL: String { "https://example.com/a/\(body.count)" }
 }
+
+let draft = Article<Draft>(body: "Hello")
+let live = draft.publish()
+```
+
+- Because `Never` has no values, a function taking one can never be called,
+  so its body may stay empty with no `return`. An empty `switch impossible {}`
+  also type-checks, but the compiler then warns "will never be executed":
+
+```swift
+func unreachable<T>(_ impossible: Never) -> T {}
 ```