Every Way Apple's On-Device Model Can Fail, and How to Handle Each One

kill  + child process    blocked 8/8   0.16 s
stop  + child process    blocked 8/8   0.11 s
kill  + worker process   blocked 8/8   0.12 s
kill  + subprocess        passed 8/8   1.64 s
spawn + child process     passed 8/8   1.57 s

let model = SystemLanguageModel(guardrails: .permissiveContentTransformations)
let session = LanguageModelSession(model: model, instructions: "...")

let attachment = session.logFeedbackAttachment(
    sentiment: .negative,
    issues: [.init(category: .triggeredGuardrailUnexpectedly,
                   explanation: "Ordinary process-management documentation.")]
)

you can see these coming
  exceededContextWindowSize
  unsupportedLanguageOrLocale
  concurrentRequests
  unsupportedGuide
  decodingFailure
  assetsUnavailable

you cannot
  guardrailViolation
  refusal
  rateLimited

//  SummariseFailure.swift

import Foundation
import FoundationModels

/// Every way a request to the on-device model can fail, turned into something worth showing a
/// person.
///
/// `GenerationError` has nine cases. Parts one and two of this app handled three and five of them
/// respectively, which is what most sample code does. The four nobody covers are
/// `assetsUnavailable`, `unsupportedLanguageOrLocale`, `rateLimited` and `concurrentRequests`,
/// and they are ordinary app-level failures rather than exotica.
///
/// Eight of the nine carry only a `Context`, whose entire payload is a `debugDescription` string.
/// That is a debug aid, not user-facing copy, which is why this type exists.
enum SummariseFailure: Equatable {
    /// The text is longer than the window, or the answer grew past the end of it.
    case tooLong
    /// Apple's safety filter blocked the input or the model's answer.
    case blocked
    /// The model itself declined. The only case that can explain itself.
    case declined
    /// The model's answer could not be made into our type.
    case couldNotDecode
    /// A constraint we asked for is not supported.
    case unsupportedConstraint
    /// The model does not support this language.
    case unsupportedLanguage
    /// The model's files are not on the device.
    case notDownloaded
    /// Too many requests, too quickly.
    case rateLimited
    /// A request was already in flight on this session.
    case alreadyRunning
    /// Something this build does not recognise.
    case unknown(String)

    init(_ error: any Error) {
        guard let generation = error as? LanguageModelSession.GenerationError else {
            self = .unknown(error.localizedDescription)
            return
        }
        switch generation {
        case .exceededContextWindowSize:   self = .tooLong
        case .guardrailViolation:          self = .blocked
        case .refusal:                     self = .declined
        case .decodingFailure:             self = .couldNotDecode
        case .unsupportedGuide:            self = .unsupportedConstraint
        case .unsupportedLanguageOrLocale: self = .unsupportedLanguage
        case .assetsUnavailable:           self = .notDownloaded
        case .rateLimited:                 self = .rateLimited
        case .concurrentRequests:          self = .alreadyRunning
        @unknown default:                  self = .unknown(generation.localizedDescription)
        }
    }

    var title: String {
        switch self {
        case .tooLong:               return "That text is too long"
        case .blocked:               return "The safety filter blocked this"
        case .declined:              return "The model declined"
        case .couldNotDecode:        return "The answer came back malformed"
        case .unsupportedConstraint: return "Unsupported constraint"
        case .unsupportedLanguage:   return "Unsupported language"
        case .notDownloaded:         return "The model isn't on this device yet"
        case .rateLimited:           return "Too many requests"
        case .alreadyRunning:        return "Already summarising"
        case .unknown:               return "Something went wrong"
        }
    }

    var detail: String {
        switch self {
        case .tooLong:
            return "This app should have split it up before asking. That's a bug, not your text."
        case .blocked:
            return "Apple's filter rejected this before the model saw it. Ordinary technical "
                 + "writing can trigger it: phrases like \"kill the child process\" read as "
                 + "something else out of context."
        case .declined:
            return "The model chose not to answer this one."
        case .couldNotDecode:
            return "The model's answer didn't fit the shape this app asked for."
        case .unsupportedConstraint:
            return "This app asked for a constraint the model doesn't support. That's a bug here."
        case .unsupportedLanguage:
            return "The on-device model doesn't support this language yet."
        case .notDownloaded:
            return "Apple Intelligence is on, but the model files aren't downloaded. "
                 + "Stay on Wi-Fi and try again later."
        case .rateLimited:
            return "The system is throttling requests. Wait a moment and try again."
        case .alreadyRunning:
            return "A summary is already in progress. One request at a time."
        case .unknown(let description):
            return description
        }
    }

    /// Whether asking again, unchanged, could plausibly succeed.
    ///
    /// Worth being honest about. A retry on `unsupportedLanguage` will fail identically forever,
    /// and offering the button teaches people the app is broken.
    var retryMightHelp: Bool {
        switch self {
        case .blocked, .declined, .couldNotDecode, .rateLimited, .alreadyRunning:
            return true
        case .tooLong, .unsupportedConstraint, .unsupportedLanguage, .notDownloaded, .unknown:
            return false
        }
    }

    /// Whether relaxing the guardrail is worth offering for this failure.
    ///
    /// `SystemLanguageModel(guardrails: .permissiveContentTransformations)` cleared every blocked
    /// case in testing, including the process-management text that the default setting refuses
    /// eight times out of eight.
    ///
    /// Deliberately an *offer* rather than an automatic retry. Downgrading a safety setting on
    /// someone's behalf without telling them is not a decision an app should make quietly.
    var relaxedFilterMightHelp: Bool {
        self == .blocked
    }
}

request A: ok         in 3.99 s
request B: concurrent in 0.00 s

guard !isWorking else { return }
isWorking = true
defer { isWorking = false }

public struct Refusal: Sendable {
    public var explanation: LanguageModelSession.Response<String> { get async throws }
    public var explanationStream: LanguageModelSession.ResponseStream<String> { get }
}

error: non-Sendable type
'LanguageModelSession.Response<String>' of
nonisolated property 'explanation' cannot be
sent to main actor-isolated context

let text = try await Task.detached {
    try await refusal.explanation.content
}.value

prompt already too long   threw in 1.31 s
answer runs off the end   threw in 9.09 s
both fit                 worked in 8.36 s

GenerationOptions(maximumResponseTokens: 220)

tokenCount(for prompt: some PromptRepresentable) async throws -> Int
tokenCount(for instructions: Instructions)       async throws -> Int
tokenCount(for tools: [any Tool])                async throws -> Int
tokenCount(for schema: GenerationSchema)         async throws -> Int
tokenCount(for transcriptEntries: some Collection<Transcript.Entry>) async throws -> Int

//  WindowBudget.swift

import Foundation
import FoundationModels

/// Works out how much of the model's context window is actually left for the user's text.
///
/// The context window is the total number of tokens the model can hold at once, and the thing
/// that catches people out is that **your text and the model's answer come out of the same
/// budget**. It is not 4,096 for you plus room for a reply.
///
/// Four things are spoken for before a single word of the user's input arrives:
///
///   - the session's own fixed cost, 22 tokens
///   - the instructions, which are sent with every request
///   - the schema, the description of the struct we want back, which the framework writes into
///     the prompt for us
///   - whatever the answer is allowed to grow to
///
/// Measuring this up front is the difference between a failure that costs nothing and one that
/// costs the user ten seconds of waiting and returns nothing at all.
struct WindowBudget {

    /// The session's fixed cost, over and above what `tokenCount(for:)` reports for the text.
    ///
    /// `tokenCount(for: "")` returns 8, but a session actually charges 22. Those are two
    /// different overheads and the one you can measure is not the one you are billed for.
    static let sessionCost = 22

    /// The model stops a few tokens short of the advertised window.
    ///
    /// Every deliberate overflow reports dying at 4,089 or 4,090 against a stated 4,096, across
    /// a wide range of answer ceilings and prompt sizes. Rounded up to 8 so the budget is
    /// pessimistic rather than optimistic.
    static let ceilingReserve = 8

    /// The whole window, as the model reports it.
    let contextSize: Int
    /// What the instructions cost, in content tokens.
    let instructions: Int
    /// What the schema costs.
    let schema: Int
    /// The ceiling we will put on the answer.
    let answer: Int

    /// Everything that is committed before the user's text is considered.
    var spokenFor: Int {
        Self.sessionCost + Self.ceilingReserve + instructions + schema + answer
    }

    /// How many tokens of the user's text will actually fit in one request.
    var availableForInput: Int {
        max(0, contextSize - spokenFor)
    }

    /// Prices the window for a given configuration.
    ///
    /// Note which `tokenCount` overload does what. There are five of them and they do not agree
    /// with each other: the same instruction string prices at 26 through the `Instructions`
    /// overload and 19 through the prompt overload. We use the prompt overload and subtract the
    /// 8-token scaffolding, because that is the form article 04's arithmetic was derived in.
    ///
    /// The schema figure is deliberately taken from the API rather than from our own measurement.
    /// `tokenCount(for:)` reports 138 where a session is actually charged 119, so the API
    /// overstates it by 19, and an overstatement is exactly what you want in a budget.
    static func measure(
        model: SystemLanguageModel = .default,
        instructions instructionText: String,
        schema: GenerationSchema,
        answerCeiling: Int
    ) async throws -> WindowBudget {
        let scaffolding = try await model.tokenCount(for: "")
        let instructionsTotal = try await model.tokenCount(for: instructionText)
        let schemaCost = try await model.tokenCount(for: schema)

        return WindowBudget(
            contextSize: model.contextSize,
            instructions: max(0, instructionsTotal - scaffolding),
            schema: schemaCost,
            answer: answerCeiling
        )
    }

    /// How many tokens the given text will contribute, with the scaffolding removed.
    static func contentTokens(
        of text: String,
        model: SystemLanguageModel = .default
    ) async throws -> Int {
        let scaffolding = try await model.tokenCount(for: "")
        let total = try await model.tokenCount(for: text)
        return max(0, total - scaffolding)
    }
}

contextSize        4096
session cost         22
ceiling reserve       8
instructions         11
schema              138
answer ceiling      220
-----------------------
spoken for          399
left for your text 3697

tokenCount per sentence  0.019 s per call
300 sentences            5.8 s to plan splits
estimate then verify     0.10 s, 4 calls

private func calibrate(on text: String) async throws -> Double {
    let sample = String(text.prefix(4_000))
    guard !sample.isEmpty else { return Self.fallbackCharactersPerToken }
    let tokens = try await WindowBudget.contentTokens(of: sample, model: model)
    guard tokens > 0 else { return Self.fallbackCharactersPerToken }
    return Double(sample.count) / Double(tokens)
}

                    chunks   recall
fill the budget          3      35%
equal sizes              4      65%
blind slices             5      68%

//  Chunker.swift

import Foundation
import FoundationModels

/// Splits text too long for the context window into pieces that fit, without cutting sentences
/// in half.
///
/// The awkward part is that the only accurate way to count tokens is `tokenCount(for:)`, and that
/// is an `async` call into the model. Calling it once per candidate sentence while packing would
/// mean hundreds of round trips to decide where to put a full stop.
///
/// So this estimates first and verifies afterwards: pack by a cheap character estimate, then
/// measure each finished chunk once and split any that came out over budget. The estimate only
/// has to be roughly right, because the verification pass catches the cases where it is not.
struct Chunker {

    /// Fallback density, used only if the calibration sample comes back empty.
    private static let fallbackCharactersPerToken = 4.0

    /// How much of one chunk to actually use.
    ///
    /// The estimate is approximate, so packing right up to the limit means the verification pass
    /// has to split chunks constantly. Leaving a margin makes the common case a single clean
    /// measurement per chunk.
    private static let safetyFactor = 0.9

    /// The most content tokens a single chunk may contain.
    let budget: Int
    let model: SystemLanguageModel

    init(budget: Int, model: SystemLanguageModel = .default) {
        self.budget = budget
        self.model = model
    }

    /// Splits `text` into chunks that each fit the budget.
    func chunks(of text: String) async throws -> [String] {
        let sentences = Self.sentences(in: text)
        let density = try await calibrate(on: text)
        var packed = pack(sentences, charactersPerToken: density)
        packed = try await verify(packed, charactersPerToken: density)
        return packed
    }

    /// Measures how many characters of *this* text make a token, rather than assuming.
    ///
    /// One `tokenCount` call on a sample. A fixed guess was out by 55% on ordinary English
    /// prose, and being wrong in the pessimistic direction is not free: it makes every chunk
    /// smaller than it needs to be, which means more passes, and more passes means more of the
    /// document's detail is lost on the way through.
    private func calibrate(on text: String) async throws -> Double {
        let sample = String(text.prefix(4_000))
        guard !sample.isEmpty else { return Self.fallbackCharactersPerToken }
        let tokens = try await WindowBudget.contentTokens(of: sample, model: model)
        guard tokens > 0 else { return Self.fallbackCharactersPerToken }
        return Double(sample.count) / Double(tokens)
    }

    /// Breaks text on sentence boundaries, which `enumerateSubstrings` does properly for the
    /// user's locale rather than by looking for full stops.
    private static func sentences(in text: String) -> [String] {
        var result: [String] = []
        text.enumerateSubstrings(in: text.startIndex..., options: .bySentences) { substring, _, _, _ in
            if let substring, !substring.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                result.append(substring)
            }
        }
        // A block of text with no sentence punctuation at all comes back empty, so fall back to
        // treating the whole thing as one sentence and let the verification pass deal with it.
        return result.isEmpty ? [text] : result
    }

    private func estimate(_ text: String, charactersPerToken: Double) -> Int {
        Int(Double(text.count) / charactersPerToken)
    }

    /// Packs sentences into chunks of roughly equal size.
    ///
    /// The obvious approach is to fill each chunk to the budget and start a new one when it is
    /// full, which minimises the number of passes. Measured, that is by some distance the worst
    /// thing you can do: filling the window gave 35% recall of planted facts where equal-sized
    /// chunks gave 65%.
    ///
    /// The reason is that every chunk gets summarised into the same small note. A chunk holding
    /// 3,700 tokens has to lose almost all of itself to fit; one holding 2,200 loses much less.
    /// Filling the window optimises the thing that does not matter (pass count) at the expense of
    /// the thing that does (how much survives).
    ///
    /// So: work out the fewest chunks that fit, then aim for that many chunks of equal size.
    private func pack(_ sentences: [String], charactersPerToken: Double) -> [String] {
        let workingBudget = Int(Double(budget) * Self.safetyFactor)
        let total = sentences.reduce(0) { $0 + estimate($1, charactersPerToken: charactersPerToken) }
        let count = max(1, Int((Double(total) / Double(workingBudget)).rounded(.up)))
        let target = max(1, total / count)

        var chunks: [String] = []
        var current = ""
        var currentEstimate = 0

        for sentence in sentences {
            let sentenceEstimate = estimate(sentence, charactersPerToken: charactersPerToken)
            // Start a new chunk once this one has reached its share, unless this is the last
            // chunk, which absorbs whatever rounding left over.
            if currentEstimate + sentenceEstimate > target,
               !current.isEmpty,
               chunks.count < count - 1 {
                chunks.append(current)
                current = sentence
                currentEstimate = sentenceEstimate
            } else {
                current += sentence
                currentEstimate += sentenceEstimate
            }
        }
        if !current.isEmpty { chunks.append(current) }
        return chunks
    }

    /// Measures each chunk for real and splits any that the estimate got wrong.
    ///
    /// One `tokenCount` call per chunk, not per sentence, which is the whole point of estimating
    /// during packing.
    private func verify(_ chunks: [String], charactersPerToken: Double) async throws -> [String] {
        var verified: [String] = []

        for chunk in chunks {
            let actual = try await WindowBudget.contentTokens(of: chunk, model: model)
            if actual <= budget {
                verified.append(chunk)
            } else {
                verified.append(contentsOf: try await halve(chunk,
                                                            measured: actual,
                                                            charactersPerToken: charactersPerToken))
            }
        }
        return verified
    }

    /// Splits an over-budget chunk in half repeatedly until every piece fits.
    ///
    /// Halving rather than re-estimating because the estimate has already been shown wrong for
    /// this particular text, so trusting it a second time would be optimistic.
    private func halve(_ chunk: String,
                       measured: Int,
                       charactersPerToken: Double) async throws -> [String] {
        guard measured > budget else { return [chunk] }

        let sentences = Self.sentences(in: chunk)
        guard sentences.count > 1 else {
            // A single sentence bigger than the whole budget. Nothing clever to do: cut it by
            // character count and accept the seam.
            return splitByCharacters(chunk, charactersPerToken: charactersPerToken)
        }

        let midpoint = sentences.count / 2
        let first = sentences[..<midpoint].joined()
        let second = sentences[midpoint...].joined()

        var result: [String] = []
        for half in [first, second] where !half.isEmpty {
            let halfTokens = try await WindowBudget.contentTokens(of: half, model: model)
            result.append(contentsOf: try await halve(half,
                                                      measured: halfTokens,
                                                      charactersPerToken: charactersPerToken))
        }
        return result
    }

    private func splitByCharacters(_ text: String, charactersPerToken: Double) -> [String] {
        let maximumCharacters = Int(Double(budget) * charactersPerToken * Self.safetyFactor)
        guard maximumCharacters > 0, text.count > maximumCharacters else { return [text] }

        var pieces: [String] = []
        var index = text.startIndex
        while index < text.endIndex {
            let end = text.index(index, offsetBy: maximumCharacters, limitedBy: text.endIndex)
                ?? text.endIndex
            pieces.append(String(text[index..<end]))
            index = end
        }
        return pieces
    }
}

after the chunk notes      56%
after the combining pass   25%

                   notes   combined
prose                58%        19%
typed ChunkNotes     27%        10%

                       notes   combined
"summarise this"         42%        15%
"take notes on this"     56%        12%

                       notes  combined  lost
greedy, "summarise"      33%       10%   70%
greedy, "take notes"     58%       19%   67%
typed notes              27%       10%   63%
equal, "take notes"      56%       25%   55%

//  Summariser.swift

import Foundation
import FoundationModels
import Observation

/// Notes taken from one chunk of a long document.
struct ChunkNote: Identifiable {
    let id: Int
    /// One-based, for showing "passage 2 of 4".
    var number: Int { id + 1 }
    var text: String?
    var failure: SummariseFailure?
}

@Observable
final class Summariser {

    /// What the pre-flight check worked out, before any generation happened.
    struct Plan {
        let inputTokens: Int
        let availablePerPass: Int
        let passes: Int
        var fitsInOnePass: Bool { passes <= 1 }
    }

    /// Notes from each passage, kept rather than thrown away.
    ///
    /// This is the app's most important design decision and it came out of a measurement.
    /// Collapsing these into one final summary loses roughly three quarters of the specific
    /// names, numbers and places: recall measured about 33-58% at this stage and 10-19% after
    /// the combining pass, whatever the prompt said. So the notes are the primary result and
    /// the combined summary below is a convenience.
    private(set) var notes: [ChunkNote] = []

    /// The optional combined summary. Secondary to `notes`, deliberately.
    private(set) var summary: Summary.PartiallyGenerated?

    private(set) var plan: Plan?
    private(set) var timeToFirstToken: Duration?
    private(set) var isWorking = false
    private(set) var failure: SummariseFailure?

    /// How much room the answer is allowed. This is a ceiling, not a reservation: the model uses
    /// only what it needs, so setting it costs nothing when the answer was going to be short.
    ///
    /// It is also the seatbelt. A prompt that fits can still overflow if the answer runs off the
    /// end of the window, and that failure takes about as long as a successful summary and hands
    /// back nothing at all. Capping the answer makes it impossible.
    private static let answerCeiling = 220

    /// Framing matters more than it should. "Take notes on one passage" retained noticeably more
    /// specifics than "summarise this text" on the same input, so the wording here is deliberate.
    private static let noteInstructions = """
        You take notes on one passage of a longer document. \
        Keep every specific name, number, place and date you are given.
        """

    private static let combineInstructions = """
        You combine notes from several passages into one summary. \
        Keep every specific name, number, place and date you are given.
        """

    private static let singlePassInstructions = """
        You summarise text that someone has just shared with you.
        """

    private static func makeSession(
        instructions: String,
        permissive: Bool = false
    ) -> LanguageModelSession {
        let model = permissive
            ? SystemLanguageModel(guardrails: .permissiveContentTransformations)
            : SystemLanguageModel.default
        return LanguageModelSession(model: model, instructions: instructions)
    }

    /// The session the next request will use, warmed in advance.
    @ObservationIgnored
    private var next: LanguageModelSession?

    /// Call this when the text field gains focus. The model goes cold after a minute or so of
    /// inactivity, and paying that cost while someone is still typing is free.
    func prepare() {
        guard next == nil else { return }
        let session = Self.makeSession(instructions: Self.singlePassInstructions)
        session.prewarm()
        next = session
    }

    /// Whether the last request relaxed the safety filter.
    ///
    /// Surfaced so the UI can say so. Quietly downgrading a safety setting on the user's behalf
    /// and never mentioning it is not a thing to ship.
    private(set) var usedRelaxedFilter = false

    // MARK: - The main entry point

    /// - Parameter relaxFilter: run with `.permissiveContentTransformations` instead of the
    ///   default guardrail. Only ever set from an explicit user action, never automatically.
    func summarise(_ text: String, relaxFilter: Bool = false) async {
        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { return }

        // One request at a time. A session throws `concurrentRequests` immediately if a second
        // request arrives while the first is in flight, so this guard is load-bearing rather
        // than cosmetic - the button being disabled is not enough on its own.
        guard !isWorking else { return }

        isWorking = true
        defer { isWorking = false }

        failure = nil
        summary = nil
        notes = []
        plan = nil
        timeToFirstToken = nil
        usedRelaxedFilter = relaxFilter

        do {
            let budget = try await WindowBudget.measure(
                instructions: Self.noteInstructions,
                schema: Summary.generationSchema,
                answerCeiling: Self.answerCeiling
            )
            let inputTokens = try await WindowBudget.contentTokens(of: trimmed)
            let available = budget.availableForInput

            // Ceiling division: 3,800 tokens into 3,700-token passes is two passes, not one.
            let passes = max(1, Int((Double(inputTokens) / Double(available)).rounded(.up)))
            plan = Plan(inputTokens: inputTokens, availablePerPass: available, passes: passes)

            if passes <= 1 {
                await summariseInOnePass(trimmed, relaxFilter: relaxFilter)
            } else {
                await summariseInChunks(trimmed, budget: available, relaxFilter: relaxFilter)
            }
        } catch {
            failure = SummariseFailure(error)
        }

        prepare()
    }

    // MARK: - Short enough to do directly

    private func summariseInOnePass(_ text: String, relaxFilter: Bool) async {
        let clock = ContinuousClock()
        let start = clock.now
        // The prewarmed session always uses the default guardrail, so it can only be reused on
        // an ordinary run.
        let session = relaxFilter
            ? Self.makeSession(instructions: Self.singlePassInstructions, permissive: true)
            : (next ?? Self.makeSession(instructions: Self.singlePassInstructions))
        if !relaxFilter { next = nil }

        do {
            let stream = session.streamResponse(
                to: text,
                generating: Summary.self,
                options: GenerationOptions(maximumResponseTokens: Self.answerCeiling)
            )
            for try await snapshot in stream {
                if timeToFirstToken == nil,
                   let headline = snapshot.content.headline,
                   !headline.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                    timeToFirstToken = clock.now - start
                }
                summary = snapshot.content
            }
        } catch {
            failure = SummariseFailure(error)
        }
    }

    // MARK: - Too long, so chunk it

    private func summariseInChunks(_ text: String, budget: Int, relaxFilter: Bool) async {
        do {
            let chunker = Chunker(budget: budget)
            let pieces = try await chunker.chunks(of: text)

            plan = Plan(
                inputTokens: plan?.inputTokens ?? 0,
                availablePerPass: budget,
                passes: pieces.count
            )
            notes = pieces.indices.map { ChunkNote(id: $0, text: nil, failure: nil) }

            for (index, piece) in pieces.enumerated() {
                notes[index].text = await note(for: piece, at: index, relaxFilter: relaxFilter)
            }

            // Surface a passage-level refusal even when the others succeeded, so the offer to
            // relax the filter appears rather than the failure being silently swallowed.
            if !relaxFilter, notes.contains(where: { $0.failure == .blocked }) {
                failure = .blocked
            }

            // One chunk being refused should not lose the other three. Given how readily the
            // guardrail fires on ordinary technical writing, this is likely rather than exotic.
            let written = notes.compactMap(\.text)
            guard !written.isEmpty else {
                failure = notes.compactMap(\.failure).first ?? .unknown("No passage could be read.")
                return
            }

            await combine(written)
        } catch {
            failure = SummariseFailure(error)
        }
    }

    /// Notes on one chunk, in prose.
    ///
    /// Prose rather than a typed value, which is the opposite of what part two concluded and is
    /// deliberate. Typing the output stopped the model handing back its input, but a typed notes
    /// field retained *fewer* specifics than free prose. Types constrain shape, and shape is not
    /// memory.
    private func note(for chunk: String, at index: Int, relaxFilter: Bool) async -> String? {
        let session = Self.makeSession(
            instructions: Self.noteInstructions,
            permissive: relaxFilter
        )
        do {
            let response = try await session.respond(
                to: chunk,
                options: GenerationOptions(maximumResponseTokens: Self.answerCeiling)
            )
            notes[index].failure = nil
            return response.content
        } catch {
            notes[index].failure = SummariseFailure(error)
            return nil
        }
    }

    private func combine(_ written: [String]) async {
        let clock = ContinuousClock()
        let start = clock.now
        let session = Self.makeSession(instructions: Self.combineInstructions)
        let joined = written.joined(separator: "\n\n")

        do {
            let stream = session.streamResponse(
                to: joined,
                generating: Summary.self,
                options: GenerationOptions(maximumResponseTokens: Self.answerCeiling)
            )
            for try await snapshot in stream {
                if timeToFirstToken == nil,
                   let headline = snapshot.content.headline,
                   !headline.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                    timeToFirstToken = clock.now - start
                }
                summary = snapshot.content
            }
        } catch {
            // The notes survive. Losing the combined summary is a much smaller loss than losing
            // everything, and it is the more useful half anyway.
            failure = SummariseFailure(error)
        }
    }
}

window available to you   3,697 of 4,096
schema, API vs charged        138 vs 119
overflow after generating   9.1 s, nothing
"kill the child process"    8 of 8, 0.16 s
recall after combining                25%