I wrote a semantic search tool, then piped the results through an agent to explain algorithms.
e.g. explain oauth authentication protocol

×

×

The answer above was generated solely from a Swift codebase.

The tool selects the relevant information using a combination of semantic search, heuristics, and the call hierarchy graph. Generating an explanation is generally twice as fast as asking a coding agent, and half as cheap.

This implementation is Swift/Xcode-centric. Semly indexes Swift and relies on Xcode’s IndexStore to build a call-graph.

The Problem

I’m trying to answer a user’s question about an algorithm buried in a mid-sized codebase (100–500k lines). The code exceeds the model’s context window, so the challenge is finding the relevant pieces.

An agent approach is to grep synonyms of the query words, evaluate results, then grep further for symbols found until the picture is clear. This is effective—once the agent finds a trail it follows guided by its own intelligence.

In comparison, semantic search is faster and uses fewer tokens. The tradeoff is depth. An agent can continue indefinitely; semantic search gives you a first step. The quality ceiling is lower, but the cost floor is much lower too.

The best results come from combining both: semantic search for initial exploration (it’s an external system, so token-cheap), then let the agent judge whether the answer is sufficient or whether it needs to grep additional details or start over.

From the terminal, run semly explain or outline, and you’ll get a terminal version of the answers above.

~ % semly outline "explain oauth authentication protocol" --project OAuth2
 ├─ S1 : Start OAuth Flow LoginViewController.swift:9-145
 ├─ S2 : Build Authorization Request OAuth2Client.swift:6-121
 │  └─ S3 : Exchange Code for Token AccessTokenRequest.swift:2-11
 ├─ S4 : Decode Access Token Response AccessTokenResponse.swift:18-119
 └─ S5 : Load Configuration OAuth2Configuration.swift:50-50

Why Semantic Search Isn’t Enough

Semantic search finds code conceptually similar to the query, but ignores the relevancy of the code structure, and doesn’t follow-up the call hierarchy. Therefore, what’s missing here is to expand the call graph of each result, and pick the most likely graph to answer the question.

Building the Index

A required first step is to index the codebase. This inconvenience is why agents don’t implement semantic search.

Chunking

First, it splits files into chunks—contiguous slices of text with a file path and line range.

It is critical to split at semantic boundaries. For source code you don’t want half of one function glued to half of the next, otherwise the resulting code is confusing, and the embedding won’t be representative. I used a parser (SwiftSyntax for Swift) to identify these boundaries. Each chunk represents a coherent unit of meaning. In practice this involved trial and error and dealing with a lot of cases, Swift is complicated.

Markdown, however, was simple: split by sections, paragraphs, tables, etc.

Embedding

The system calculates the embedding for each chunk. It stores each chunk’s text, line range, file path, and embedding in SQLite.

When the user sends a query, the system embeds the query, then looks up similar embeddings in the database. The operation to calculate similarity is called cosine similarity. The result is a list of chunks hopefully related to the user query.

The indexing process interleaves disk I/O with embedding creation, so the CPU is mostly idle. You can leave it running in the background—it scans for changes on a configurable interval (say, 10 minutes) using file modification times, hashes, and file events. Negligible overhead.

Symbols and the Call Graph

Chunks capture text. The source code symbols in that text capture structure.

A symbol is a declaration: a function, method, initializer, computed property, or closure. The indexer extracts these from the syntax tree and stores them with their name, kind, file path, and line span. Closures get a synthetic name like “closure@42”. Importantly, the indexer also extracts call edges—which symbol calls which other symbol.

This gives us a graph. When semantic search finds a relevant function, the tool can ask: what calls this? What does it call? The answer might be more relevant than the original hit.

For cross-file relationships, the system uses USRs (Unified Symbol Resolution identifiers) from Xcode’s IndexStore when available. A USR is a stable identifier for a declaration that works across files and modules. Without it, cross-file callees often remain unresolved.

In order to use the IndexStore, the user must compile the source and then point to its folder within Derived Data. This is done in the application’s UI from the properties of the project. This step exists because some symbols are dynamically resolved and can’t be figured out just by looking at the source. In Swift the compiler always knows what calls what at compilation time, so looking up the store is the only way to get this information. If skipped, the application tries to compensate by favoring locality and lexical overlap (fancy term for string overlap).

The Query Pipeline

When a question arrives, the ‘explain’ feature runs through five stages:

1. Retrieval: semantic search for chunks related to the query.
2. Symbol mapping: convert chunks to structural units (functions, methods) the system can traverse.
3. Graph traversal: walk callers and callees to find code semantic search missed.
4. Ranking: score by graph depth, locality, and lexical overlap with the question.
5. Context composition: concatenate the top chunks into a prompt the model can use.

Retrieval

The system gathers seeds (initial chunks) from three sources:

1. Cosine similarity on the database using query embedding as input.
2. Full text search on the symbols of the database using query terms.
3. Symbol search in the IndexStore if available.

Step 1 returns embeddings, step 2 and 3 return symbols. The database stores triplets of embeddings, symbols, and chunks, so having one lets you query the others. Then perform an additional step of common sense heuristics: discriminate against test files, CLI boilerplate, and UI scaffolding.

For markdown, the indexer treats section headers as symbols. I didn’t implement PDF because it is not semantically annotated and would require clunky heuristics based on font size, styles throughout the document, and common terms.

Option Enable lexical prefilter. When enabled it discards symbols that lack a string overlap with the query. This is useful if your query mentions a specific symbol you are looking for. Default is off because it lets you type vague queries, which is the most common case.

Graph Traversal

Embeddings, symbols, and chunks are all linked in the database. For instance, a chunk covering lines 50–80 maps to whatever function or method is declared in that range.

Therefore the system can focus on the symbols to build a graph and then traverse it. For source code this means moving in two directions: callers (who uses this?) and callees (what does this use?). In Semly the walk is bounded—depth ≤3, nodes ≤10—to keep results focused rather than sprawling across the entire codebase.

This is where the traversal discovers code that semantic search missed. A utility function might have a generic name and boring documentation, but if it’s called by three of the seed symbols, it’s probably relevant.

Ranking

The expanded set of symbols needs ranking. The ranker combines several signals: graph depth (closer to seeds is better), locality (same file or module), lexical overlap with the question, and embedding similarity.

The system also expands locally: if the graph is thin, it adds neighboring chunks from the same file—the function above and below a hit. This helps when the relevant code is clustered.

The ranking of symbols whose string overlaps with the query is increased. e.g. you asked about a pipeline and there is a class name containing that word.

Option Anchor-only downweight scale. Signatures (or headers) are keyword-dense so they are too boosted by lexical overlap, full text search and cosine similarity. This feature only kicks in when results are signatures only to resurface the bodies. Most times signatures are indexed with their bodies and this is not used.

Context Composition

The top-ranked symbols map back to chunks. The pipeline concatenates these into a single text block with file paths and line hints, trimmed to fit the model’s token budget. This is what the model sees: the question and a curated selection of code. The graph itself is never sent to the model. It’s scaffolding for selection, not part of the prompt.

I’m using a budget of 24k tokens (~1,500 lines of code). How much you should use depends on the quality and number of the chunks retrieved. Since I’m using GPT-5 mini (400k context tokens) you can go to Settings and increase it.

Generating the Answer

With context composed, the system calls the model. The prompt includes the question and the selected chunks. The model generates prose, and because each chunk carries its file path and line range, it can include links that direct the user to the relevant code.

So the full loop is: question → semantic retrieval → structural expansion → ranked selection → grounded answer.

Tuning the Pipeline

I experimented with several options in the form of flags. They are not exposed because they represent the best configuration. I’m showing them here to offer some insight on the inner workings.

Sample query

semly explain "How does the per-file pipeline process a file: chunking → embeddings → transactional DB sync?" 
--project Semly 
--limit 10 
--topK 3 
--indexstore-seeding 
--oversize-anchors 
--include-dependencies 
--outline

• –limit N caps the number of anchors (final chunks sent to the model) and the total context size. Lower values produce tighter, more focused answers. Higher values help for broad architectural questions.
• –topK K controls neighbor expansion—how many same-file chunks to add around each anchor when the graph is sparse.
• –oversize-anchors allows large spans when the important logic sits in a single big function. By default, the system caps chunk size to maintain diversity.
• –include-dependencies includes code from packages and dependencies, which are normally filtered to keep focus on the main project.
• –indexstore-seeding enables USR-based seeding and edge repair using the configured Xcode IndexStore. This improves cross-file precision but requires a built project with an up-to-date index.

Beyond flags, I’ve made the selection step more resilient: when the graph is sparse or noisy, explain can fall back to using whole files and focus only on code that’s connected in the call graph. It also drops obvious noise (tests, UI, CLI scaffolding) so the model sees real logic instead of boilerplate. In practice this yields richer context for complex questions without overwhelming the model with irrelevant text.

Outline runs the same retrieval pipeline but asks the model for strict JSON; it takes ~230% longer. Isn’t it wild that 25 years ago we had hierarchy calls for Java but today we need to stitch one together using the IndexStore?

Is this any good?

Locating code is definitely faster during an initial exploration. Claims of “using product X reduces Claude token consumption by 80%” are a cherry pick of this first step.

Explaining code misses more than an agent would. It does better if IndexStore is connected because that provides a true hierarchy of calls, rather than attempting to infer it. I prompted the agent to evaluate its own confidence on the answer and avoid hallucinations.

But it saves tokens. Your main agent gets a more or less accurate version of the algorithm and can continue from there. This is what Claude does already when it uses Haiku to search code.

Note this explain feature presented here is not like Windsurf codemaps. What they do, it seems, is taking part of the hierarchy call graph and requesting a shallow explanation.

Overall, this experiment is a negligible optimization. “You can just ask things,” and live a life without complications. The difference is for initial exploration roughly ~15 seconds and 2% percent on the token context.

• Why MiniLM?
• Prepare MiniLM
  • Convert to Core ML
  • Bundle Tokenizer Assets
• Predicting with Swift
• Power Chart
• Dependencies
• Example Code

Why MiniLM?

MiniLM is a compact family of Transformer models designed to capture the meaning of text in a lightweight way. The version I use, MiniLM-L6-v2, is a smaller cousin of BERT (a well-known language model). Instead of hundreds of millions of parameters, it runs on only 6 layers and produces a 384-dimensional vector (a list of 384 numbers) for each token.

Because it is tuned for sentence-sized text, MiniLM is especially good at representing short pieces of information (like a function signature or DocC comments). It also does a decent job keeping unusual words, such as function or variable names in code.

I’m using it to implement semantic search for Swift and Markdown on this application. In my tests, I’ve found that it produces more relevant results than OpenAI’s largest model.

Prepare MiniLM

Convert to Core ML

We could run the model directly using MLTensor, but converting it to Core ML makes it more suitable to run on GPU/ANE (ANE = Apple Neural Engine).

To convert it, I lock sequence/batch to static shapes and use FP16 for speed, then drop unused paths via tracing. Here are the highlights from prepare-model.py:

• MAX_SEQ = 512 = Max input size. +

• ct.RangeDim(lower_bound=1, upper_bound=16, default=16) = batch size. +

• compute_units=ct.ComputeUnit.ALL = use CPU, GPU, or ANE –whichever is free.

• compute_precision=ct.precision.FLOAT16 = use 16-bit numbers. +

• minimum_deployment_target=ct.target.macOS14 generate a MLProgram. +

• torch.jit.trace records the exact steps the model takes when you run it once. For MiniLM we only care about turning text into embeddings, so we trace just that path and throw away the rest. The result is a smaller, faster model. +

The following script does the download, tracing, and conversion in one go:

mkdir -p MiniLM && cd MiniLM
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install torch==2.5.0 torchvision torchaudio
pip install scikit-learn==1.5.1
pip install coremltools transformers sentence-transformers
python prepare-model.py

The script downloads all-MiniLM-L6-v2, disables a PyTorch fastpath that confuses the converter, fixes the sequence length to 512 tokens, and creates a MiniLM_L6_v2.mlpackage that can be loaded from the bundle.

Using fixed versions and settings make the resulting MiniLM_L6_v2.mlpackage reproducible. Leaving them to defaults could change tensor shapes or precision and make a mess with your previous data.

Bundle Tokenizer Assets

The training process for the model creates a correspondence between words, tokens, and number IDs. Example:

"settings" -> ["set", "##ting", "##s"] -> [1012, 4567, 302]

The index for each token is particular to this model and means nothing for any other model. Therefore along with the model we have to download the following information from huggingface:

• config.json: model architecture config
• tokenizer_config.json: tokenizer behavior settings
• tokenizer.json: configuration + vocabulary + splitting rules
• vocab.txt: the vocabulary lookup table

Looking at the configuration MiniLM-L6 is

• BERT: a standard Transformer encoder stack with self-attention and feed-forward blocks,
• Uncased: everything gets lowercased, which degrades signal for code
• 6 layers (six Transformer encoder blocks)
• Hidden size 384: each token is represented as a 384-dimensional vector
• Vocabulary size 30,522: the set of known WordPiece (=the BERT tokenization algorithm) tokens; words/subwords outside this set become [UNK].
• max sequence length 512: the longest tokenized input it can handle in one pass; shorter inputs are padded, longer ones truncated.

At runtime HFTokenizerAdapter loads tokenizer and vocabulary through Hugging Face’s Swift AutoTokenizer. Then we call encodeWithPadding(text:) it:

1. Splits text into WordPiece subwords using the same rules as the original model.
2. Inserts [CLS] at the front and [SEP] at the end.
3. Truncates or pads to 512 tokens.
4. Builds an attention mask with 1s for real tokens and 0s for padding.

The resulting arrays are wrapped in MLMultiArray and passed to model.prediction(…) to obtain one vector per token position. Specifically we get a 3D tensor shaped [batch, seq_len, hidden_size] where hidden_size is 384 for MiniLM.

Predicting with Swift

1) Load the Core ML model
We exported to mlpackage, which once compiled becomes a .mlmodelc file.

// Load the Core ML model
func loadMiniLM() throws -> MLModel {
    guard let modelURL = Bundle.main.url(forResource: "MiniLM_L6_v2", withExtension: "mlmodelc") else {
        throw NSError(domain: "MiniLM", code: 1, userInfo: [NSLocalizedDescriptionKey: "MiniLM_L6_v2.mlmodelc not found in bundle"])
    }
    let cfg = MLModelConfiguration()
    cfg.computeUnits = .all
    return try MLModel(contentsOf: modelURL, configuration: cfg)
}

2) Tokenize the input +

// Tokenize the input (BERT WordPiece, uncased)
func tokenize(_ text: String, maxLen: Int = 512) throws -> (ids: [Int], mask: [Int]) {
    // Assumes you’ve configured the tokenizer with MiniLM’s vocab + lowercasing.
    let tokenizer = try BERTWordPieceTokenizer()
    let (ids, mask) = tokenizer.encodeWithPadding(text: text, maxLength: maxLen)
    return (ids, mask) // ids/mask are length == maxLen (e.g., 512)
}

3) Wrap input in MLMultiArray +

// Creates one batch of 512 tokens.
func makeInt32Array(_ ints: [Int]) throws -> MLMultiArray {
    let arr = try MLMultiArray(
        shape: [1, NSNumber(value: ints.count)], 
        dataType: .int32
    )
    let ptr = arr.dataPointer.assumingMemoryBound(to: Int32.self)
    for (i, v) in ints.enumerated() { ptr[i] = Int32(v) }
    return arr
}

4) Run prediction and grab token-level hidden states. +

// Run prediction and grab token-level hidden states
func tokenHiddenStates(model: MLModel, inputIDs: MLMultiArray, attentionMask: MLMultiArray) throws -> MLMultiArray {
    let features = try MLDictionaryFeatureProvider(dictionary: [
        "input_ids": inputIDs,
        "attention_mask": attentionMask
    ])
    let out = try model.prediction(from: features)

    // Prefer "last_hidden_state"
    // otherwise fall back to the first multiArray output.
    if let hs = out.featureValue(for: "last_hidden_state")?.multiArrayValue {
        return hs // [1, seqLen, hidden]
    }

    // Fallback: find any multiArray output
    for name in out.featureNames {
        if let arr = out.featureValue(for: name)?.multiArrayValue, arr.shape.count == 3 {
            return arr
        }
    }

    throw NSError(
        domain: "MiniLM", 
        code: 2, 
        userInfo: [NSLocalizedDescriptionKey: "No 3D hidden-state output found"]
    )
}

5) Masked mean pooling. +

// Masked mean pooling (to sentence/chunk vector)
func maskedMeanPool(hs: MLMultiArray, attentionMask: MLMultiArray) -> MLXArray {
    // hs: [1, seqLen, hidden], mask: [1, seqLen]
    let hsArr   = MLXArray(mlMultiArray: hs).astype(.float32)
    let maskArr = MLXArray(mlMultiArray: attentionMask).astype(.float32)

    let seqLen = maskArr.shape.count > 1 ? maskArr.shape[1] : 1
    let mask3D = mlx.reshape(maskArr, [1, seqLen, 1]) // [1, seqLen, 1]

    let masked = hsArr * mask3D // broadcast
    let sumVec = mlx.sum(masked, axes: [1]) // [1, hidden]
    let counts = mlx.maximum(mlx.sum(mask3D, axes: [1]), MLXArray(1e-6 as Float)) // [1,1]
    return sumVec / counts // [1, hidden]
}

6) L2 normalize +

// L2 normalize (cosine-ready)
func l2normalize(_ vec: MLXArray) -> [Float] {
    let eps  = MLXArray(1e-12 as Float)
    let norm = mlx.sqrt(
        mlx.maximum(
            mlx.sum(vec * vec, axes: [1], keepDims: true), 
            eps
        )
    )
    return (vec / norm).toArray() // [Float], length == hidden (≈384)
}

We can now call every function above to produce an embedding for the input text.

// End-to-end: text -> normalized embedding
func miniLMEmbedding(_ text: String, maxLen: Int = 512) throws -> [Float] {
    let model = try loadMiniLM()
    let (ids, mask) = try tokenize(text, maxLen: maxLen)
    let inputIDs = try makeInt32Array(ids)
    let attention = try makeInt32Array(mask)
    let hs = try tokenHiddenStates(
        model: model, 
        inputIDs: inputIDs, 
        attentionMask: attention
    )
    let pooled = maskedMeanPool(hs: hs, attentionMask: attention)
    return l2normalize(pooled)
}

// Example:
let vec = try miniLMEmbedding("SwiftUI view that handles user input")
print("dim:", vec.count) // ~384

MLX keeps the post-processing on-device and vectorized: multiply by the mask, reduce across the sequence axis, divide by the live-token count, then L2 normalize. Rudrank Riyam has a book on MLX if you are interested.

Power Chart

The first conversion was running entirely on the CPU at around 13 W. Core ML defaulted there because it wasn’t sure the GPU or Neural Engine could handle certain features. For instance:

• Flexible input shapes. If the model accepts variable-length inputs, Core ML can’t pre-plan memory well so it keeps work on the CPU (which can handle any shape). Until recently, any model with dynamic dimensions (like RangeDim or 512×N) was forced to CPU. The converter now accepts them, but the runtime still prefers CPU unless you fix the shapes in advance (e.g. always 512 tokens).
• Mixed precision. If some layers want 32-bit floats and others 16-bit, accelerators struggle to coordinate work.
• Attention layers. Transformers rely on operations such as attention, layer norm, and GELU. On macOS, the ANE doesn’t fully support these yet.

By giving Core ML a fixed input size (512 tokens), using FP16 (16-bit floats), and setting computeUnits = .all, the runtime can safely schedule the work on GPU.

With those tweaks, power use dropped to ≈ 5–6 W on CPU, ≈ 0.3–0.4 W on GPU, and 0 W on ANE. This shows how much more efficient the GPU is for transformer workloads: ≈10x less power than the CPU for the same job.

I think this is as good as it gets. MiniLM won’t run on the Neural Engine as-is. The ANE is more specialized than the GPU and only supports a limited set of operations. Transformers like MiniLM rely on others (attention, layer norm, GELU) that it doesn’t accelerate. To change that, Apple would need to design and train a new Transformer variant built only from ANE-friendly ops. Apple’s own Foundation models may be examples of this.

Dependencies

Swift dependencies I used:

• mlx-swift (MLX, MLXNN, MLXFast, MLXLinalg, MLXRandom): Apple’s Swift bindings for MLX, providing the tensor math, neural-net layers, linear algebra, random number generation, and fast kernels used for pooling and normalization.
• swift-transformers (Transformers): Hugging Face’s Swift port, used here for tokenizer adapters.

In the Python script torch==2.5.0, coremltools, transformers, and sentence-transformers are the pieces that actually export the graph, while scikit-learn satisfies a dependency pulled in by sentence-transformers. You need to pin these versions to generate future compatible versions if you want to experiment with conversions.

Example Code

Index

• Introduction
• Agent Evaluation
• A Primer for Embeddings
• Technical details
• Why

Introduction

When an AI agent explores a codebase, it needs to acquire the right context to be effective. There are three complementary ways to do so:

• Exact text with rg (ripgrep) — fastest for literals and identifiers.
• Structure‑aware with ast-grep — precise for declarations and pattern audits.
• Semantic search with embeddings— intent‑level queries like “user settings,” “retry logic,” or “transactional sync.”

Here is a comparison search for user settings:

# EXACT SEARCH: look for settings and possible synonyms
rg -i "settings|preferences|defaults|configuration" .

# SYNTAX AWARE SEARCH: look for functions with settings in their name
ast-grep -p "func $FUNC(settings)" --lang swift .

# SEMANTIC SEARCH
semly locate "user settings"

^*I published semly last week, I’m not aware of a similar tool.

Mind the rg string of synonyms. Agents know settings may appear under multiple names so they search for alternatives. This is highly effective but not as good as semantic search. Semantic search finds code by what it does, not just what it’s called. If you search for ‘retry logic,’ it will find functions named ‘attemptWithBackoff’ or ‘handleFailureAndRetry’—even though those names don’t contain the word ‘retry.’

A typical result:

• rg finds 47 matches across 12 files (lots of noise)
• ast-grep finds 3 function declarations (precise but misses conceptual matches)
• semly finds 8 relevant results ranked by semantic similarity

Agent Evaluation

I specifically wrote this tool to speed up project exploration afer spawning a new agent. Here is a quick test you can drop on your agent to confirm its utility:

compare the effectiveness of rg, ast-grep, and semly finding content in this swift project

Results on my machine:

• Claude Opus executed 6 different tests. Full evaluation.
• Codex gpt-5 high ran “a few representative searches”. Full evaluation.

Both reached this conclusion: ripgrep for exact matches, ast-grep for structure, Semly for meaning. Finally, I asked GPT-5 to summarize both evaluations in a table comparing all three tools:

Embeddings Primer

When you search for “user preferences,” you want to find code about settings, configuration, and defaults—even if those exact words aren’t present. Traditional search finds only exact text matches. Semantic search finds meaning.

Here’s a quick mental model of semantic search. Imagine plotting words on a map where similar words sit close together. “duck” and “chicken” would be neighbors. “car” would be far away. If your query is “chicken,” nearby words (“duck,” “goose”) are retrieved.

Each word’s position on this map is stored as a pair of numbers— its x and y coordinates. These numbers are called embeddings. In reality, we use 300–1500 numbers instead of just 2, but the principle is the same: similar meanings = similar numbers.

The semantic search workflow is:

1. Encode information into numbers
2. Encode query into numbers
3. Retrieve information similar to your query

The same principle can be applied to words or to chunks of text with 200 lines. The codebase indexing flow would be:

1. Split into chunks.
2. Compute embeddings.
3. Store chunks with metadata (file, line).
4. Encode the query as an embedding.
5. Compare via “cosine similarity”
6. Return ranked, relevant chunks.
7. Optionally, hand results to an LLM to interpret the answer.

Here is additional background

• LLM Primer if you know nothing about LLMs
• Embedding with MiniLM if you want to embed using Swift

Technical Details

Parsing Strategy

To parse Markdown and Swift I use swift-markdown and SwiftSyntax. I only support those two but I think Tree-sitter would make multi-language support straightforward.

These libraries tells me the structure, so I can split the file preserving related elements together. For instance, headings stay with their content, code examples remain intact, etc. In other words I’m splitting following semantic boundaries. The goal is fine-grained chunks that differentiate components while preserving local reasoning.

Embedding Model Choice

I used on-device MiniLM L6 v2. I described how in Embedding with MiniLM.

MiniLM outperforms OpenAI’s larger models for code because:

• It is tuned for sentence-sized text. This plays well with one-liners like user queries, markdown headings, DocC comments, function signatures.
• It tends to preserve the distinctiveness of rare tokens (like type and function names).
• It runs fast on-device, so I can index at finer granularity and re-rank more candidates without significant latency.

Ranking & Relevance

• Symbol pinning: ensure exact camelCase identifiers rank top. e.g. if user queries scanForChanges, that function, if found, ranks top.
• Header-lex boosts: reward overlaps between query terms and signatures/headings.
• Lexical prefilter: discard candidates without token overlap.

In practice, there are a lot more knobs to tune in A/B tests, and it’s impossible to predict success before running experiments. There are formal metrics to rank results but without a labeled dataset I just eyeball the results.

Infraestructure

Storage

• Plain SQLite with GRDB. Not even sqlite-vec.
• CPU/GPU/ANE cost is negligible. No need for a vector DB unless you’re at GitHub scale.

Communication terminal/app

• Automator remains the less hacky option for MAS.
• Other options considered: XPC, app groups, defaults, URL + TCP port, tmp files.
• XPC for the notarized version but it requires a global mach name, which is disallowed in MAS.

Why

While working on Semly I created 100+ markdown documents about the application itself. My workflow was

“Claude read x,y,z then work on files a,b,c“.

Now I tell the agent “use semly” –which is unfortunate, but I find that agents don’t automatically reach for external tools.

I rarely read every line of code. Instead, I browse on Sourcetree (!) track architecture, write tests, log experiments, and step in when the agent goes astray. I’ve noticed agents struggle most with what they can’t see directly. Some examples I suffered, from worse to better: graphics with multiple coordinate systems > generics > inheritance > composition > Entity Component System (ECS). I found ECS very effective, giant state + reducers = no problem for agents.

So far, Semly is a workflow enhancer, not a necessity. Likely it will save some tokens and you won’t even notice. But I see no reason not to use it. I think in the near future agents will run semantic search hidden in the background. It’s also likely we will be able to create complete technical documentation for projects –the technology for it is already here; but that’s another story.

Semly is available as CLI and MCP. MCP is like dropping the whole manual in the context for better or worse. If you use Claude Code:

claude mcp add semly --scope user -- semly mcp
claude mcp remove "semly" -s user

Index

• LLM Primer
  • What is an LLM?
  • Training
  • Fine Tuning
  • Chat Completion
• Context in Big Codebases
  • Files
  • Embeddings
  • Fine-Tuning
  • Cost comparison

LLM Primer

What is an LLM?

A Large Language Model is an artificial intelligence designed to recognize patterns in language and produce contextually appropriate responses to queries.

• They are Large because they are trained with curated data that amounts to billions of words – the equivalent of reading millions of books, articles, and documents.
• They are Language Models because they have been trained to understand human created languages.

Even when LLMs are trained with text, the same principles can be applied to train models on movement recordings, musical notes, images, or any other form of sequential data. The key is whether there are patterns that express relationships the model can learn from

Training

Training a large language model (LLM) involves teaching it to predict the next word in a sequence of text. It involves several key steps:

1. Tokenization
2. Embeddings
3. Training loop on a neural network

Tokenization: the text is broken down into tokens, which are numerical representations of words or subwords. Tokens are the basic unit of text that AI models process - smaller than words but larger than individual characters. For instance, the word “hamburger” might be split into tokens like ham–burg–er. Most LLMs have a maximum number of tokens they can handle in a single conversation (the context window). A context window of 32k tokens corresponds to roughly 20–25k English words.

Embeddings are arrays of numbers (vectors) that can represent any structured data—words, images, code, musical notes, etc. Think of them as arrows pointing at a point in space. These vectors are designed so that “similar” pieces of data have embeddings close to each other, making it easy to retrieve related information by comparing vectors.

The Training loop is the iterative process through which a neural network learns from data by repeatedly processing examples, comparing predictions to correct answers, and adjusting its parameters to improve performance. Here are the key steps:

1. Initialize
   • Weights start with random values.
   • Biases start at zero or small random values.
2. Forward Pass
   • Input data flows through the network.
   • The model makes a prediction using the current weights and biases.
3. Calculate Error (Loss)
   • Compare the model’s prediction to the correct answer.
   • The difference is the “loss.”
4. Backpropagation
   • The loss is propagated backward through the network.
   • Each weight and bias receives a gradient indicating how it should change to reduce the loss.
5. Optimization Step
   • An optimizer uses these gradients to update each parameter.
   • The learning rate decides how big these updates are.
6. Repeat
   • This cycle runs many times over the training data.
   • Over time, parameters converge to values that yield accurate predictions.

It’s like turning lots of small knobs (the weights and biases) a little at a time to achieve the best outcome.

Quick summary: chop text into little pieces, place them on a coordinate space, and create a function that looks up your queries in that space to produce an answer. That’s the (simplified) idea. Vectors are really arrows in space, except they may have 300 or 1500 dimensions instead of two or three.

Fine Tuning

Fine-tuning is the process of further training a pre-trained model on a smaller dataset to adapt it for a particular domain while preserving its general capabilities.

Fine-tuning modifies the model’s weights/parameters themselves through additional training on your specific data. This means the model learns patterns and knowledge from your training data and incorporates them into its base capabilities. The fine-tuning process will likely capture general patterns and repeated structures, but it may not reliably memorize every specific detail of every function, specially rarely seen ones. The agent will have to use its context window as working memory to materialize its knowledge.

Chat Completion

A chat completion is a response generated by an LLM in the context of a conversation. The model keeps track of previous messages to maintain context and generate coherent replies.

The context window is the maximum amount of tokens a model can handle per conversation.

• Each user message and any additional information (e.g., instructions, attached files) consume tokens, all of which must fit into the context window.
• Language models can’t exceed their context window because they’re architecturally designed and trained to handle only a specific maximum length of text.
• The attention mechanism itself (how tokens relate to each other) grows quadratically (n²) with context length. But the overall challenge of training grows exponentially because of compounding factors like data requirements, stability issues, hardware needs, etc.
• Modern models may have up to a 200k token context window—meaning they can handle a large chunk of text, but not beyond it.

A model that performs chat completion only has awareness of what is inside its context window. Creating a project with files in Claude or GPT is the equivalent of copy pasting such files at the beginning of the conversation. Each subsequent message from the user will re-send the whole conversation up to that point, increasing the token consumption. Therefore the initial files are “paid for” multiple times in terms of token usage, since they’re sent with each new message.

Once the conversation grows too large, some earlier context may be “pushed out” or truncated, making it inaccessible to the model. Another issue is that LLM performance degrades on long conversations. It’s like they spent most of their attention reading the whole conversation instead of solving the problem. A solution is to ask them to summarize the problem and copy paste that into a new window.

A workaround is to implement “sparse attention” where one token doesn’t relate to every other token, therefore avoiding the n² problem but degrading performance. Another is to compact the conversation keeping the parts relevant for ongoing work. But it remains true that attention is limited.

Context in Big Codebases

LLMs have practical limits. They can only “see” as much text as fits into their context window, and they’re not automatically aware of everything in a massive code repository. Context windows can be easily exceeded by large application codebases.

With these in mind there are three ways we work with LLMs today: files, embeddings, fine-tuning.

Files

For trivial cases, select only the minimal set of files needed to provide context about the problem. This reduces context window usage and ensures the model focuses on the most relevant code. Local reasoning and modularity are highly desirable, and lets you drop entire libraries on the best performance model for architectural advice.

For instance, the following script concatenates all .swift files in current folder and subfolders, then stores the result in a single file within the parent folder:

find . -name "*.swift" -type f -print0 | xargs -0 cat > ../concatenated.swift

Embeddings

If you have sections of code that rarely change—such as a library—you can store them as embeddings. Then, when you need to query the agent about a specific part of that code, you retrieve the relevant chunks and include them in your query. This approach avoids re-uploading the entire library and helps keep the context window usage low.

Here is the workflow:

1. Break down the codebase
   • Split code into smaller chunks, ideally chunks that make sense independently.
   • Convert each chunk into an embedding vector and store it in a database. These vectors represent the relation between structured information.
   • Store the vectors in a regular database (SQLite) or a vector database (Pinecone, Weaviate, Qdrant, Milvus, Redis).
2. Form the Query
   • Convert your user query into an embedding vector.
3. Retrieve & Provide Context
   • Fetch the most relevant chunks from the database.
   • Supply these chunks, alongside your question, into the model’s context. All products provide an API you can use to get the chunks for a query, then you can locally send them to the chat completion model.

Hopefully, this will result in low token consumption but with enough relevant code to answer the query. This ensures the model only sees the most relevant code sections, even when the overall codebase is too large to fit in the context window. For instance, when prompting about a class it may fetch surrounding code so the agent can make sense of the problem.

Fine-Tuning

If your project is especially domain-specific or you repeatedly need the model to handle the same queries, you might consider fine-tuning the model on your codebase or on specific usage patterns. This can help the model internalize common functions and code structures. However, fine-tuning alone will not memorize every detail of a massive repository. You’ll likely still need embeddings for deeper searches.

Cost comparison

Cost comparison

• Files: no upfront costs, may result in being expensive when providing a large amount of texts.
• Embeddings: one-time cost in time, practically free in money.
• Fine-tuning: high upfront cost in time and money. Lowest token usage per query since the model “knows” your code.

When to use them

• Files: casual queries where you manually select the context.
• Embeddings: ongoing queries for mostly stable files. Requires setting up a database and embedding pipeline.
• Fine-tuning: domains that rarely change where you anticipate usage amortizing the cost over time.

@isolated(any) is a function attribute that preserves the isolation information of a function.

@MainActor 
func updateUI() { 
    print("I’m main actor isolated") 
}

let f: @isolated(any) () -> Void = updateUI
print(f.isolation) // Optional(Swift.MainActor)

When you set a function defined with @isolated(any) the isolation information is no longer type-erased, and can be queried through the property isolation: (any Actor)?. The type reflects the three possible isolations of Swift 6 functions:

• non-isolated (nil)
• isolated to an actor
• or isolated to global actor

You can operate with this type as usual in ifs, switch, etc

if let isolation: any Actor = fn.isolation {
    print(isolation)	
}

switch fn.isolation {
case nil:
    print("Function is non-isolated")
case let actor?:
    print("Function is isolated to: \(actor)")
}

The primary motivation for @isolated(any) is to make smart scheduling decisions. Before @isolated(any), Task creation APIs started on the global executor and then hopped on the appropriate actor:

Task {
    // at this point we are on the global executor
    // and about to hop to myActor
    await myActor.work()
}

But with @isolated(any) work is synchronously enqueued on the appropriate executor. Benefits:

• Better performance: no unnecessary executor hops
• Ordering guarantees: tasks enqueue in creation order on the actor

Always await

Functions that carry @isolated(any) are always called with await.

When you call an @isolated(any) function, the compiler doesn’t know if:

• It’s non-isolated (would run immediately)
• It’s isolated to the current actor (would run immediately)
• It’s isolated to a different actor (needs to hop to that actor)

Since the compiler can’t know which case applies, it must assume the worst case - that the function needs to hop to a different actor. Because of this:

1. The call requires await because switching actors is an async operation
2. It’s treated as crossing an isolation boundary - with all the sendability requirements that entails.

Synchronous functions are no exception, if they carry @isolated(any) they must be awaited:

func executeOperation(_ operation: @isolated(any) () -> String) async {
    await operation()
}

@MainActor
func op() -> String {
    ""
}

await executeOperation(op)

Sendability rules

The rules for sendability are nuanced:

• The function must be Sendable if it’s async and the context isn’t known to be non-isolated
• Arguments and results follow standard sendability rules for cross-isolation calls
• Non-async @isolated(any) functions in non-isolated contexts don’t require sendability

Before @isolated(any), passing functions across isolation boundaries had three drawbacks:

• The function type had to be async to switch isolation internally
• Non-Sendable values couldn’t be passed even when safe
• The isolation was completely erased with no way to recover it

Examples

Each task starts on operation’s preferred executor:

func parallelMap<T, U>(
    _ items: [T],
    operation: @isolated(any) (T) async -> U
) async -> [U] {
    await withTaskGroup(of: (Int, U).self) { group in
        for (index, item) in items.enumerated() {
            group.addTask {
                (index, await operation(item))
            }
        }
        // ... collect results
    }
}

Handlers that complete on the preferred caller’s isolation:

struct NetworkEventHandler: EventHandler {
    func handle(
        event: Event,
        completion: @isolated(any) () -> Void
    ) {
        Task {
            // Process on background
            await processEvent(event)

            // Complete on caller's isolation
            completion()
        }
    }
}

Other examples:

• Library authors writing task-spawning APIs
• Framework developers building concurrency abstractions
• Performance-critical code avoiding unnecessary executor hops
• Debugging tools that need isolation awareness

Can’t schedule

While @isolated(any) exposes isolation information, it doesn’t provide APIs to schedule work on that isolation from synchronous contexts. The Swift runtime has this capability internally but doesn’t expose it publicly.

This means you can inspect isolation and pass it to APIs like Task.init, but you can’t implement your own scheduling on dynamic isolation. For library authors needing this capability, the current workaround is to use @MainActor or require explicit isolation.

Here’s an imaginary example of what we can’t do but would like to:

func withObservationTracking<T>(_ apply: () -> T, onChange: () -> Void) { ... }

 func observeValue<T>(_ operation: @isolated(any) () -> T) -> AsyncStream<T> {
     AsyncStream { continuation in
         withObservationTracking {
             _ = operation()
         } onChange: {
             let isolation = operation.isolation
             
             // I would like to do this, but I can’t dynamically schedule
             // on an isolation that is only known at runtime.
             isolation.schedule { // 'schedule' does not exist
                 let newValue = operation()
                 continuation.yield(newValue)
             }             

             // instead, I can always schedule in main
             // whether my clients like it or not
             Task { @MainActor in
                 let newValue = await operation()
                 continuation.yield(newValue)
             }
         }
     }
 }

// I wanted observations to run on this actor but can’t
actor DataModel {
    var count = 0
    func getCount() -> Int {
        count 
    }
}
let model = DataModel()
let stream = observeValue(model.getCount)

// I can see you are calling with actor X, 
// but I can’t dynamically schedule on it.

Links

• NSHipster @isolated(any) I wrote mine after reading this to understand it better
• Failed backport of v26 Observations I learnt there is no public API to schedule this on arbitrary actors
• SE-0431 @isolated(any) Function Types

• deinit
• Asynchronous Function Call Errors
• Sendability and Data Race Protections
• Actor Isolated Protocols
• @MainActor Isolation Violations
• Sendable-Related Errors
  • Type Conformance
  • Non-sendable crossing boundaries
  • Weak var is mutable
  • Sending value risks causing data races
  • Sending closure risks causing data races
  • 'inout sending' parameter task-isolated
  • Captures in a @Sendable closure
  • Isolated value cannot be sent
• Global state
• Singleton
• Concurrency

deinit

@MainActor
class Bar {
    private var observer: NSObjectProtocol?
    deinit {
        // 💥 Cannot access property 'observer' with a non-sendable 
        // type '(any NSObjectProtocol)?' from nonisolated deinit
        observer = nil
    }
}

Class deinitializers are solved in Swift 6.1 SE-0371 Isolated synchronous deinit. The following is implemented in Swift 6.1, which as of Xcode 16.2 is not available.

@MainActor
class MyViewController: UIViewController {
    private var observer: NSObjectProtocol?

    init() {
        super.init(nibName: nil, bundle: nil)
        observer = NotificationCenter.default.addObserver(forName: ...
    }

    isolated deinit { // <-- add isolated here
        if let observer {
            NotificationCenter.default.removeObserver(observer)
        }
    }
}

In Swift 6.1 the isolated keyword for deinit will inherit the actor isolation of the containing class (in this case @MainActor), ensuring the cleanup happens on the main thread.

But for the time being, here is a workaround:

// non isolated
final class TaskHolder {
    var task: Task<Void, Never>?

    deinit {
        task?.cancel()
    }
}

// isolated
@MainActor
final class Foo {
    // var task: Task<Void, Never>?
    let taskHolder = TaskHolder()
    ...
}

The TaskHolder’s deinit is implicitly isolated to @MainActor since it’s created in a main actor context. When LoadingViewModel is deallocated, deinit will be called on the main thread, safely cancelling the task.

Asynchronous Function Call Errors

Error: Call to asynchronous function 'foo()' in a synchronous function
Error: Missing 'await' in call to asynchronous function
Error: Expression is 'async' but is not marked with 'await'

These errors arise when you try to call an async function without:

• Marking the calling function as asynchronous, or
• Using the await keyword to handle the asynchronous call properly.
• In Swift’s strict concurrency model, every asynchronous operation must be explicitly awaited. This enforces clarity around when and where suspension points occur.

How to Fix It:

• Update your function signature to be async if it needs to call async functions.
• Use await when calling async functions, ensuring that you are handling potential suspension correctly.

Sendability and Data Race Protections

Error: Non-sendable type 'T' used in concurrent actor-isolated context

Swift’s concurrency model enforces that types crossing actor boundaries (or used concurrently) must be safe to transfer between threads. A type that isn’t marked as Sendable might introduce data races. This error indicates that you’re using a type in a concurrent context where the compiler cannot guarantee its thread safety.

How to Fix It:

• If the type is indeed safe for concurrent use, you can conform it to Sendable.
• Otherwise, consider refactoring to an immutable type or introducing internal synchronization and making it @unchecked Sendable.

Actor Isolated Protocols

I wrote about this in a previous article.

@MainActor Isolation Violations

Same as Holy Borla’s Calling an actor-isolated method from a synchronous nonisolated context

class Foo {
    // 💥 Main actor-isolated default value in a nonisolated context
    var window = UIWindow()
}

In Swift 6 view related objects are annotated with @MainActor so you can’t use them outside that isolation context. What follows are variations of this.

Error: call to main actor-isolated initializer 'init()' in a synchronous nonisolated context​
Error: Main actor-isolated property 'foo' cannot be referenced from a nonisolated context
Error: Cannot form key path to main actor-isolated property 'foo'

Again, calling an initializer (or method) marked with @MainActor from code that isn’t on the main actor. The solution is to wrap the call in an await MainActor.run {} or Task { @MainActor in }. A temporary workaround could be to use MainActor.assumeIsolated if you are sure such code will only be called from the main actor.

Error: Main actor-isolated property 'foo' cannot be referenced from a Sendable closure.

This time we are calling a main isolated property from a Sendable closure. Because it is Sendable, you are going to send that property away from its isolation context.

This error often appears in SwiftUI or other contexts where a closure is marked @Sendable (implicitly by the system) and you capture a @MainActor state inside it. For instance, using a SwiftUI .task { ... } modifier (which runs concurrently) and capturing a @State (main actor) property inside can produce this error.

Several solutions:

• Mark the closure as running on the main actor, or ensure any UI state is accessed on the main thread. In SwiftUI, you can call await MainActor.run within the task to update UI state​.

• Or move the state into a model that is made thread-safe or Sendable. In one case, a developer created a separate view model and declared it @unchecked Sendable to hold the image data, then used MainActor.run for UI updates​

• Or Design your concurrency so that UI-bound data is only touched on the main actor (for example, by marking the entire view model @MainActor or updating SwiftUI @State within DispatchQueue.main.async or an actor). In short, avoid capturing main-actor state in detached concurrent closures; perform UI updates on the main actor.

Sendable-Related Errors

Type Conformance

Error: Type 'XYZ' does not conform to the 'Sendable' protocol​

It means that a type (often a class or a reference type) is being used in a concurrent context but hasn’t been marked as safe to share across threads.

Several solutions:

• Conform to Sendable: If you know the type is actually safe to use from multiple threads (e.g. it’s immutable or internally synchronized), you can conform to Sendable.

• Isolate to an actor: If the type isn’t inherently thread-safe, consider isolating it to an actor or marking it @MainActor if it should only be used on the main thread.

• Redesign usage: In some cases, you might avoid needing the type across threads. For example, rather than capturing a non-Sendable class inside an async task, perform the needed work on that class on its own queue or actor, or copy the necessary data out into a Sendable form (like a struct) to send to the task, or capture it in the closure capture list.

Non-sendable crossing boundaries

Error: Passing argument of non-sendable type 'Foo' outside of actor-isolated context may introduce data races

This diagnostic appears when you attempt to use a non Sendable value in a way that exits an actor’s protection. In other words, if a type is private to the isolation context of an actor there can’t be data races. But if you send it outside the actor it needs to be Sendable.

Solutions:

• Mark the type as Sendable: See elsewhere on this guide how.
• Keep usage on the actor
• Isolate Foo to a global actor: Another strategy is marking the non-sendable type with a global actor (like @MainActor if appropriate). This way, even when used in async calls, it’s still confined to a single actor. For instance, if Foo is only ever used on the main thread, mark it @MainActor – then the call is actor-to-actor and no cross-actor send happens.

Weak var is mutable

Error: Stored property 'delegate' of 'Sendable'-conforming class 'x' is mutable

Delegates need to be mutable because they may change at runtime. This makes your type non Sendable. Using an actor is one way to solve it:

actor PipelineDelegateHolder {
    weak var delegate: PipelineDelegate?

    nonisolated init(delegate: PipelineDelegate?) async {
        self.delegate = delegate
    }

    func callDelegate(_ action: (PipelineDelegate) -> Void) {
        if let delegate = delegate {
            action(delegate)
        }
    }
}

final class TransPipeline: Sendable {
    let delegateHolder: PipelineDelegateHolder

    init(delegate: PipelineDelegate) async {
        self.delegateHolder = await PipelineDelegateHolder(delegate: delegate)
    }
}

// Usage
await delegateHolder.callDelegate { delegate in
    delegate.pipeline(self, didUpdateApples: apples)
}

By using this solution we are adding suspension points in both initializers and delegate calls. Also, the PipelineDelegate needs to be Sendable. If you want a structured concurrency ‘safe’ solution this is it.

Sending value risks causing data races

From Holy Borla’s sending-risks-data-race.md.

The following example calls a non-isolated function from the main actor:

class Person {
    var name: String = ""    
    func printNameConcurrently() async {
        print(name)
    }
}

@MainActor
func onMainActor(person: Person) async {
    // calling non-isolated function from the main actor
    await person.printNameConcurrently()
}

Non-sendables (like person) can only be accessed from one isolation domain at a time. Otherwise, who is to say main actor won’t change person while printNameConcurrently() is running?.

Solution:

@execution(caller)
func printNameConcurrently() async {
    print(name)
}

Now printNameConcurrently() runs in the isolation domain of the caller. If called from main, it runs on main.

As of march 2025 this change is not yet implemented. See Run nonisolated async functions on the caller’s actor by default. So for the time being follow the doctor’s advice if it hurts don’t do it. Instead, make person a Sendable, move it to @MainActor, etc.

Sending closure risks causing data races

From Holy Borla’s sending-closure-risks-data-race.md.

class MyModel {
  var count: Int = 0

  func perform() {
    Task {
      // 💥 error: passing closure as a 'sending' parameter risks causing data races
      self.update()
    }
  }

  func update() { count += 1 }
}

This code has two isolation domains:

• MyModel (nonisolated)
• Task {}

Task { self… } contains a reference to self (MyModel) which is now accessible from two domains. Again: non-sendables (like person) can only be accessed from one isolation domain at a time.

Solution

• Make MyModel an actor (or isolate to a global one). Actors are Sendable because any code touching them is required to switch to the actor isolation domain. Therefore the actor is only accessible from one (1) isolation domain: its own.
• Another solution is to really send (sending) the value:

class MyModel {
    static func perform(model: sending MyModel) {
        Task {
            model.update()
        }
    }
    
    func update() { ... }
}

This works because it enforces single-ownership semantics:

• The model parameter is annotated sending, meaning: the callsite can’t touch this instance again after sending it.
• perform is an static so you know it can’t capture self in the Task closure

Captures in a @Sendable closure

From Holy Borla’s sendable-closure-captures.md.

func callConcurrently(
  _ closure: @escaping @Sendable () -> Void
) { ... }

func capture() {
    var result = 0
    result += 1
    
    callConcurrently {
        // 💥 error: reference to captured var 
        // 'result' in concurrently-executing code
        print(result)
    }
}

You annotated a closure as Sendable but that closure captures non-Sendable values. This just in: non-sendables can only be accessed from one isolation domain at a time?, news at 5.

Solutions:

• If it is a value (struct, enum) copy it in the closure capture list to avoid passing a non-Sendable self.
• Or make self sendable (make it an actor, annotate with global actor, or @unchecked Sendable with internal synchronization)

‘inout sending’ parameter cannot be task-isolated at end of function

This happens when using Swift 6’s Mutex type from the Synchronization framework. Example:

agentsMutex.withLock { agents in
    agents.removeValue(forKey: AgentRegistryId(agent))
} 
// 💥 'inout sending' parameter 'agents' 
// cannot be task-isolated at end of function

The problem is that Mutex.withLock method expects a specific signature for its closure:

func withLock((inout sending Value) throws(E) -> sending Result) throws(E) -> sending Result

The correct way to use the withLock method is to explicitly mark the parameter as inout and specify a return type:

agentsMutex.withLock { (agents: inout [AgentRegistryId: Agent]) -> Void in
    agents.removeValue(forKey: AgentRegistryId(agent))
}

The error occurs because:

1. The withLock method expects a closure that takes an inout sending parameter
2. This parameter is temporarily sent from the Mutex to your closure
3. When the closure completes, ownership must be returned to the Mutex
4. Without proper inout annotation, Swift can’t guarantee the thread safety of your mutation

The sending keyword in Swift 6 indicates a value being transferred between isolation domains. When a parameter is marked as inout sending, it means you’re temporarily taking ownership of a value, but must properly return it when done.

By explicitly marking the parameter as inout and specifying the return type (often Void), you’re acknowledging this ownership transfer pattern. I would expect this to be handled by type inference but isn’t, maybe it is intentional (?).

Global state

Same as Holy Borla’s Unsafe mutable global and static variables

Error: Var 'xxx' is not concurrency-safe because it is non-isolated global shared mutable state

This error flags a global variable (or a static) that is mutable and not isolated to any actor. Swift 6 enforces stricter rules for global state​: a global var must either be made immutable or be protected by an actor. If not, it’s considered a potential data race, since any thread could access that global.

The Swift evolution proposal SE-0412 Strict concurrency for global variables details several solutions:

• Use a global actor: Mark the global with an actor, commonly @MainActor if it’s related to UI or main thread, or define a custom @globalActor for it. For example: @MainActor var myGlobal = 0. This ensures all access to myGlobal is on the main actor (or your chosen actor), preventing unsynchronized access. Keep in mind you’ll need await to access it from other contexts

• Make it immutable: If possible, use let instead of var, and ensure the type is Sendable. An immutable constant of a Sendable type is safe by definition (no races since it never changes)​. This might not be feasible if the value truly needs to change, but sometimes a redesign (e.g., use of a singleton actor to hold the state instead of a global var) can eliminate the need for a mutable global.

• Mark as nonisolated(unsafe): This attribute explicitly opts out of concurrency checking for that variable. For example: nonisolated(unsafe) var myGlobal = 0. This will silence the error​, but at your own risk. Only do this if you fully understand the implications and perhaps synchronize access.

An example of this problem is when a SDK protocol requirement conflicts with Structured Concurrency:

struct ButtonFramePreferenceKey: PreferenceKey {
    // 💥 Static property 'defaultValue' is not concurrency-safe because it is nonisolated global shared mutable state
    static var defaultValue: CGRect = .zero
    static func reduce(value: inout CGRect, nextValue: () -> CGRect) {
        value = nextValue()
    }
}

I can’t change the SDK so I add @preconcurrency:

@MainActor
private struct ButtonFramePreferenceKey: @preconcurrency PreferenceKey {
    static var defaultValue: CGRect = .zero
    static func reduce(value: inout CGRect, nextValue: () -> CGRect) {
        value = nextValue()
    }
}

Isolated value cannot be sent

Error: Actor isolated value cannot be sent

You are sending a non Sendable object through isolation contexts. Make it Sendable.

Singleton Pattern

Swift 6’s strict concurrency checking flags singleton patterns as potential data race risks. Here’s a common error:

Error: Static property 'shared' is not concurrency-safe because 
       non-'Sendable' type 'YourType' may have shared mutable state

This error appears when you have a singleton (static shared instance) of a class that isn’t properly isolated or made Sendable –obvious fix: make it Sendable. Example:

final class UserLanguage {
    // 💥 Static property 'shared' is not concurrency-safe because 
    // non-'Sendable' type 'UserLanguage' may have shared mutable state
    static let shared = UserLanguage()
    private init() {}
}

Note the “may have shared mutable state” even when no mutable state exists. The compiler is overzealous with classes, flagging a potential error for mutable state that may be added in the future.

Solutions

Actor-based Singleton

actor UserLanguage {
    static let shared = UserLanguage()

    var current: String {
        didSet {
            UserDefaults.standard.set(current, forKey: "userLanguage")
        }
    }

    private init() {
        if let savedLanguage = UserDefaults.standard.string(forKey: "userLanguage") {
            self.current = savedLanguage
        } else {
            let systemLanguage = Locale.current.language.languageCode?.identifier ?? "en"
            self.current = systemLanguage
        }
    }
}

This approach is best when:

• You need high-performance thread-safety
• You expect frequent concurrent access from multiple threads
• You’re comfortable with async/await in your codebase

MainActor Isolation

@MainActor
final class UserLanguage {
    static let shared = UserLanguage()
    ...
}

This approach is best when:

• The singleton is primarily used for UI-related tasks
• You want to ensure all access happens on the main thread
• You want to avoid extensive rewriting of synchronous code

Internally Synchronized Sendable

final class UserLanguage: @unchecked Sendable {
    static let shared = UserLanguage()
    
    private let lock = NSLock()
    
    private var _current: String
    
    var current: String {
        get {
            lock.lock()
            defer { lock.unlock() }
            return _current
        }
        set {
            lock.lock()
            defer { lock.unlock() }
            _current = newValue
            UserDefaults.standard.set(_current, forKey: "userLanguage")
        }
    }
    ...
}

This approach is best when:

• You need to maintain synchronous access patterns
• You want to avoid actor isolation or main thread constraints
• You’re willing to implement proper internal synchronization

Choosing the Right Approach

• Actor: Best for high-performance concurrency needs
• @MainActor: Simplest solution for UI-related singletons
• @unchecked Sendable with locks: Most compatible with existing synchronous code

Remember that the key principle is ensuring that shared mutable state can only be accessed from one isolation domain at a time.

Concurrency

Error: Instance method 'lock' is unavailable from asynchronous contexts; 
       Use async-safe scoped locking instead

You are attempting to await a lock. Example:

extension NSLock {
    func withLock<T>(_ work: () async throws -> T) async rethrows -> T {
        await lock()
        defer { unlock() }
        return try await work()
    }
}

Probably because you wanted to avoid actor reentrancy and execute the content of the method atomically.

Consider the case of an audio recorder that stores recordings on disk and properties on Core Data. Maybe you created an async file and Core Data APIs but now you want both to run atomically. For instance, delete on Core Data and then on disk without a concurrent call seeing an intermediate state. How do you do that?

If you have a code path that you want to:

• Execute fully (without reentrant calls): put it inside an actor and don’t spawn additional async calls.
• Execute on main: annotate it with @MainActor and avoid spawning extra async calls to code not protected by @MainActor –also valid with any global actor.
• Restrict concurrency using a token bucket like TokenBucket.swift or a AsyncSemaphore.

How does it work?

• An actor prevents parallel execution (two active threads running the same code concurrently), but not concurrent scheduling (the code can suspend and re-enter).
• @MainActor ensures code runs on main, but async calls to unprotected code may suspend your main-actor code, run the unprotected code on another thread, and then re-enter your main-actor code.
• The token bucket limits the number of concurrent executions like a semaphore does, but instead of blocking, we can suspend and store tasks as continuations TokenBucket.swift. An alternative solution is AsyncSemaphore, that uses a lock inside, but safely and without warnings.

I wrote more about the TokenBucket and locks in Swift Synchronization Mechanisms.

A test trait in Swift Testing is a modifier you apply to a test or test suite that customizes its behavior.

Example:

@Test(.disabled("Feature broken"))
@Test(.tags(.network))
@Test(.bug("IOS-1234", "Crashes on launch"))
@Test(.enabled(if: Server.isOnline))
@Test(.timeLimit(.seconds(10)))

Traits are passed to @Test(…) or @Suite(…) and the framework applies them during execution. In the example above the traits are:

• .disabled(...) — disables the test
• .tags(...) — groups or filters tests
• .bug(...) — links the test to a ticket
• .enabled(if:) — conditionally runs the test
• .timeLimit(...) — sets a time cap

Trait protocols

Formally, a trait is any type that conforms to the TestTrait protocol. It can:

• Add metadata (name, bug ID, tags)
• Modify execution (disable, enable, retry, set timeouts)
• Provide setup/teardown logic (via TestScoping)
• Interact with runtime conditions (ConditionTrait)

There are three traits protocols

• TestTrait: the base protocol
• TestScoping: extends TestTrait and allows running code before and after a test.
• ConditionTrait: extends TestTrait and is used to conditionally include or skip tests.

protocol TestTrait {}

protocol ConditionTrait: TestTrait {
  func evaluate() async throws -> Bool
}

protocol TestScoping: TestTrait {
  func provideScope(
    for test: Test,
    testCase: Test.Case?,
    performing function: @Sendable () async throws -> Void
  ) async throws
}

ConditionTrait

0010 valuate ConditionTrait

A test trait in Swift Testing is a modifier you apply to a test or test suite that customizes its behavior.

A ConditionTrait is a kind of test trait in Swift Testing that evaluates to a boolean and is used to decide whether to run a test or not. The following modifiers .enabled(if:) and .disabled(...) are condition traits:

@Test(.enabled(if: Server.isOnline))
@Test(.disabled("Currently broken"))

Swift 6.2 added an evaluate() method to ConditionTrait to evaluate the condition outside Test instances:

let skipOnCI = #condition(Skip(if: { isRunningOnCI() }))
if try await skipOnCI.evaluate() {
  print("Skipping test setup because we're on CI")
} else {
  startExpensiveSetup()
}

You can call evaluate on any ConditionTrait:

• Skip(if:)
• Run(if:)
• Any custom type conforming to ConditionTrait

TestScoping

TestScoping specifies code that runs before and after the annotated test or suite. It can:

• Set up resources before the test runs
• Use @TaskLocal to inject scoped values
• Clean up after the test

It’s the Structured Concurrency replacement for XCTest setUp/tearDown but better:

• A trait can be reused across test suites.
• A trait can be applied to only specific tests.
• There is no global mutable state that may interfere with test parallelization.
• It uses Structured Concurrency features for increased performance and compatibility.

Example

I want my tests to access an instance that determines what database to connect to:

struct DatabaseContext {
    let connectionString: String
    let isTestEnvironment: Bool
}

Here is how I do it:

1. Add a TaskLocal variable –this is the Structured Concurrency version of a thread-local value.

   struct DatabaseContext {
       ...
       @TaskLocal static var current: DatabaseContext?
   }

2. Create a TestTrait conforming to TestScoping. This protocol has only one function, intended to set task local values when the test runs. The parameter function is in charge of running the test. You can ignore the other parameters.

   struct DatabaseContextTrait: TestTrait, TestScoping {
       func provideScope(
           for test: Test,
           testCase: Test.Case?,
           performing function: @Sendable () async throws -> Void
       ) async throws {
   
           // this is the instance we are about to set as task local value
           let testContext = DatabaseContext(
               connectionString: "memory:test-db",
               isTestEnvironment: true
           )
   
           // next line sets the value as task local
           try await DatabaseContext.$current.withValue(testContext) {
               // ... this line runs before the test
               try await function() // this function runs the test itself
               // ... this line runs after the test
           }
   
           // Warning: the task value is released after the function()
           // runs so it’s not available for code running after the test
       }
   }
   
   // Make the trait available as a static property
   extension Trait where Self == DatabaseContextTrait {
       static var databaseContext: Self { Self() }
   }

3. Add the trait to a test and read the thread local value.

   @Test(.databaseContext)
   func testDatabaseOperations() async throws {
       // Access the thread local value
       guard let context = DatabaseContext.current else {
           Issue.record("No database context available")
           return
       }
   
       // ... perform operations with it.
       // for instance, let’s check its properties
   
       #expect(context.isTestEnvironment)
       #expect(context.connectionString == "memory:test-db")
   }

Suite Behavior and Test Case Behavior

The proposal intelligently handles how traits are applied at different levels:

// Apply to an entire suite
@Suite(.myTrait)
struct DatabaseTests {
  @Test func test1() { ... }
  @Test func test2() { ... }
}

// Apply only to a specific test
@Test(.myOtherTrait)
func specificTest() { ... }

By default, traits use different behavior depending on context:

• Suite traits that are non-recursive provide their scope once for the entire suite
• Suite traits that are recursive provide their scope once for each test function
• Test function traits provide their scope once for each test case (useful for parameterized tests)

If you plan to apply a trait to an entire suite and each test in that suite, mark the trait as recursive. Otherwise, it might only run once for the whole suite. This simple oversight can cause unexpected test behaviors.

Implementation Details

Under the hood, this feature works through:

1. The TestScoping protocol with a required provideScope method that wraps test execution
2. A scopeProvider method on the Trait protocol that returns an optional TestScoping instance
3. Default implementations that handle most common cases automatically

This design cleverly avoids creating unnecessarily deep call stacks when multiple traits are applied to the same test, as only traits that actually need custom behavior participate in the execution chain.

Compared to XCTest

In short, Test Scoping Traits let you customize test behavior using Swift concurrency, without resorting to global state. It’s another step toward more composable, precise, and inherently safe testing in Swift. For more information, see the testing proposal SWT-0007 Test Scoping Traits.

Apple provides multiple security mechanisms in macOS that rely on each other.

App Execution Security

• App Sandbox: isolates an app’s activities to limit potential damage.
• Gatekeeper: ensures only trusted apps can run.
• Notarization & Developer ID: verifies software integrity and developer legitimacy.

System-Level Security

• Secure Enclave: provides hardware-level cryptographic security.
• SIP (System Integrity Protection): protects critical system files.
• XProtect: built-in anti-malware that scans for known threats.

Data & Privacy Protection

• FileVault: provides full-disk encryption to protect your files.
• Keychain: stores passwords and credentials securely.
• TCC (Transparency, Consent, & Control): manages permissions for sensitive data.

The Accessibility Permission

Accessibility permission falls under the TCC framework. It opens your system to programmatic control for certain purposes.

Applications with accessibility permission are also referred to as trusted. macOS requires explicit user permission to designate an app as trusted. This takes the form of a dialog that requires admin authentication, and a Settings panel where permissions can be revoked. Spoiler alert: there is no clean way around manual authentication.

Configuration

To be able to request accessibility permissions you need to

• Declare an entitlement if you run on a hardened runtime.
• Declare the reason you need accessibility in your Info.plist.
• Include a provisioning profile if you plan to distribute in the App Store.

In the entitlements file:

<key>com.apple.security.accessibility</key>
<true/>

In the Info.plist:

<key>NSAccessibilityUsageDescription</key>
<string>Accessibility permissions are used for window management.</string>

Request Accessibility

To find out if the application has permissions:

// Returns TRUE if the current process is a trusted accessibility client
let isGranted = AXIsProcessTrusted()

To prompt the user for permissions:

let options: NSDictionary = [
    kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true
]
AXIsProcessTrustedWithOptions(options)

The code above will either present a system dialog, or redirect the user to the Accessibility panel at Settings > Privacy & Security > Accessibility. Such panel can also be open programmatically with:

if let url = URL(string: 
"x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
) {
    NSWorkspace.shared.open(url)
}

Grant accessibility

A workflow that is reliable is to

1. Build the application
2. Remove and add back the application to Accessibility.
3. Run the application from Xcode > Product > Perform Action > Run Without Building

You will be able to debug the application, but it is of course, very inconvenient to go through all this after each build.

TCC provides a utility (tccutil) that can reset permissions, but not assign them. The TCC database is a SQLite file on disk you can read, but writing requires disabling SIP, which opens the possibility to make a catastrophic mistake that damages your system.

# clears accessibility for one app
sudo tccutil reset Accessibility $PRODUCT_BUNDLE_IDENTIFIER

# clears accessibility for all apps
tccutil reset Accessibility

# is my app authorized? 1=granted, 2=denied
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" "SELECT auth_value FROM access WHERE service='kTCCServiceAccessibility' AND client='dev.jano.orange';"

# read row
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" "SELECT * FROM access WHERE service='kTCCServiceAccessibility' AND client='dev.jano.orange';"

# write (if SIP is disabled)
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" "UPDATE access SET auth_value = 1 WHERE service = 'kTCCServiceAccessibility' AND client = 'dev.jano.orange';"

# list clients allowed in my machine
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" "SELECT client FROM access WHERE service='kTCCServiceAccessibility';"

# show all services tracked there
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" "SELECT DISTINCT service FROM access;"

Recommendations

(aka things to do to avoid problems)

Sign the application to make its identity clear to macOS. What I read online is that each build changes the app signature so permissions have to be requested again. But what I experienced is that signing with a Developer ID certificate is enough for the system to recognize it is the same app.

To sign your app

1. Go to Signing & Capabilities
2. Set a Team
3. There are several options here. I use a Developer ID certificate and a Developer ID profile tied to it.
4. Once signed, you can check the state of your app with codesign.

% codesign -d -vv OrangeApp.app

Executable=Foo/Build/Debug/OrangeApp.app/Contents/MacOS/OrangeApp
Identifier=dev.jano.orangeapp
Format=app bundle with Mach-O thin (arm64)
CodeDirectory v=20400 size=650 hashes=10+6 location=embedded
Signature size=4691
Authority=Apple Development: Ellie Williams (H6L34F7G12) 👈
Authority=Apple Worldwide Developer Relations Certification Authority
Authority=Apple Root CA
Signed Time=Jan 12, 2025 at 09:10:19 👈
Info.plist entries=28
TeamIdentifier=PPSA6C3P8Q 👈
Sealed Resources version=2 rules=13 files=2
Internal requirements count=1 size=183

Copy the product to a stable location. What I read is that the default location of ~/Library/Developer/Xcode/DerivedData/ is hidden and changes between builds, which may confuse the system. But what I experienced is that the system recognizes the application regardless where it is generated.

FYI: changing the destination folder may cause problems if one of your dependencies declares a localization bundle of its own. If this is your case, you can still work around it and change the destination folder.

There are three ways to declare a custom location:

• Set a build property.
• Xcode > project name > Build Settings > Build Location > Per-configuration Build Products Path.
• Product > Scheme > Edit Scheme… > Run > Build Configuration > Debug > Options > Build Location > Custom

CONFIGURATION_BUILD_DIR =
$(PROJECT_DIR)/Build/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)

Troubleshooting

The Console.app is your friend –despite its unfriendly UI. You can spot the Accesibility permission being denied if you paste the following in the search field (top, right):

type:error
subsystem:com.apple.sandbox.reporting
category:violation

The error will say something like

Sandbox: OrangeApp(16745) deny(1) mach-lookup com.apple.universalaccessAuthWarn

Another way to keep an eye on the console is to stream from the terminal:

log stream --predicate \
'process == "tccd" OR process == "OrangeApp" OR process="sandboxd"'

This will be the result:

let users: [UserEntity] = container.fetch()   // fetch entities
let users: [User] = container.fetch(.id("1")) // fetch domain objects

// declarative queries with fluent API
let query = EntityQuery<UserEntity>
        .all
        .ascending("lastName")
        .ascending("firstName")
        .and(NSPredicate(format: "age > %d", 18))
        .and(NSPredicate(format: "isActive == YES"))
        .limit(20)
let users = fetch(query)

Fetching Entities

This is the simplest API possible without macros or property wrappers. Can you guess the implementation?

let users: [UserEntity] = container.fetch()

let fetchRequest = NSFetchRequest<Person>(entityName: "Person")
let persons = try persistentContainer.viewContext.fetch(fetchRequest)

extension NSManagedObject {
    class func entityName() -> String {
        String("\(self)")
    }
}

extension NSPersistentContainer {
    func fetch<T: NSManagedObject>() throws -> [T] {
        try viewContext.fetch(
            NSFetchRequest<T>(entityName: T.entityName())
        )
    }
}

let users: [UserEntity] = container.fetch()

A query can also have a predicate, sort, and a limit. A problem with Core Data is that it lacks a declarative API, let’s fix that.

struct EntityQuery<T: NSManagedObject> {
    let predicate: NSPredicate?
    let sortDescriptors: [NSSortDescriptor]
    let fetchLimit: Int?
}

Integrating this query on our fetch method doesn’t change its signature, but enables query modification with a fluent API.

extension EntityQuery {
    var fetchRequest: NSFetchRequest<T> {
        // ...
    }
    
    static var all: EntityQuery<T> {
        EntityQuery<T>()
    }
}

func fetch<T: ManagedObject>(_ query: EntityQuery<T> = .all) throws -> [T] {
    viewContext.fetch(query.fetchRequest)
}

let users: [UserEntity] = container.fetch()

extension EntityQuery {
    func limit(_ count: Int) -> EntityQuery<T> {
        EntityQuery(predicate: predicate,
                    sortDescriptors: sortDescriptors,
                    fetchLimit: count)
    }
}
let users: [UserEntity] = container.fetch().limit(10)

Convenience queries are also possible with minimal additions to the API surface.

container.fetch(.minors)      // fetch by age
container.fetch(.id(user.id)) // fetch by ID

extension EntityQuery
    static func minors() -> EntityQuery<UserEntity> {
        EntityQuery(predicate: NSPredicate(format: "age < 18"))
    }
}

extension EntityQuery where T: NSManagedObject & Identifiable, T.ID == UUID? {
    static func id(_ id: UUID) -> EntityQuery<T> {
        EntityQuery(predicate: NSPredicate(format: "id == %@", id as NSUUID))
    }
}

Data First

Let’s reflect on the benefits of a declarative approach:

// Procedural
let request = NSFetchRequest<User>(entityName: "User")
request.predicate = NSCompoundPredicate(type: .and, subpredicates: [
    NSPredicate(format: "age > %d", 18),
    NSPredicate(format: "isActive == YES")
])
request.sortDescriptors = [
    NSSortDescriptor(key: "lastName", ascending: true),
    NSSortDescriptor(key: "firstName", ascending: true)
]
request.fetchLimit = 20

// Declarative
let query = EntityQuery<UserEntity>.all
    .ascending("lastName")
    .ascending("firstName")
    .and(NSPredicate(format: "age > %d", 18))
    .and(NSPredicate(format: "isActive == YES"))
    .limit(20)

Gone are the underlying mechanics of NSFetchRequest. Clients are now closer to what they want to achieve, not how. Additional benefits:

• Queries become composable and reusable
• The structure prevents invalid states
• Declarative queries are easier to inspect and test, compared to procedural code
• Separation of concerns between how and what to fetch
• Fetch mechanics are centralize in a single point that interprets data, decreasing the code and its possible mistakes

Through the brief history of computing, many have noted the convenience and power of shifting procedural complexity to declarative data.

Fetching Domain

This would be nice to have:

let users: [UserEntity] = container.fetch()
let users: [User] = container.fetch()

To implement this we know

• managed objects need to map to domain,
• both the fetch and the mapping needs to be tied to the generic type, which leads to the following solution:

public protocol DomainConvertible {
    associatedtype DomainModel
    func toDomain() throws -> DomainModel
}

extension UserEntity: DomainConvertible {
    public func toDomain() throws -> User {
        User(id: id, name: name)
    }
}

func fetch<T: ManagedObject & DomainConvertible>(_ query: EntityQuery<T>) throws -> [T.DomainModel] {
    let objects: [T] = try fetch(query)
    return try objects.map { try $0.toDomain() }
}

Persisting Domain

A similar protocol is used to map back from model to database:

public protocol EntityConvertible {
    associatedtype MO: NSManagedObject
    func toEntity(container: EntityContainer) throws -> MO?
}

struct User: EntityConvertible { ... }

For updates create a User.Update that has the same properties, but all except the ID are optional. When we submit an update, it looks for the object by ID and updates any non-nil property. For objects with relations this requires some effort, since we have to upsert the objects.

An interesting case is bidirectional relationships, for instance,

Dog.owner <--n 1--> Person.dogs

There are two solutions to avoid an infinite loop:

• change dog.owner from person to UUID
• or remove the dog.owner property

Both are valid. Prefer removing the dog.owner if you primarily access dogs through their owners.

Benefits

This architecture provides several advantages:

• Type-safe queries prevent runtime errors
• Mapping between domain and persistence
• Testable code through protocol abstractions
• Bidirectional conversion between domain models and entities
• Easier thread-safety thanks to value objects

The cost is minimal - just a thin layer over Core Data that makes it significantly more robust and maintainable. The source code for the article is in GitHub.

States

I’ll represent states as an enum, along with a LoadingProgress object for more granular updates.

public enum LoadingState<Value: Hashable & Sendable>: Hashable, Sendable {
    case idle
    case loading(LoadingProgress?)
    case failure(HashableError)
    case loaded(Value)

    public static func failure(_ error: any Error & Sendable) -> LoadingState {
        .failure(HashableError(error))
    }
}

public struct LoadingProgress: Hashable, Sendable {
    public let isCanceled: Bool?
    public let message: String?
    public let percent: Int? // 0 to 100
}

HashableError wraps any Error & Sendable to preserve Hashable/Equatable semantics while still exposing the underlying error via its error property.

Combine-Based

To standardize the handling of loadable content, we can define a protocol. A Combine-based version of this protocol might look like this:

/// An object that loads content (Legacy Combine version).
public protocol Loadable_Combine {
    associatedtype Value: Sendable
    
    /// Emits states about the loading process.
    var state: PassthroughSubject<LoadingState<Value>, Never> { get }
        
    /// Initiates the load process.
    func load()
}

This approach worked, but it relied on the PassthroughSubject, sink, and AnyCancellable boilerplate common to Combine. While powerful, modern Swift concurrency offers a cleaner path.

AsyncSequence

Apple’s focus has clearly shifted to async/await and AsyncSequence. They allow us to consume streams of values with a simple for await loop, integrating naturally with Structured Concurrency and removing the need for manual subscription management. If needed, async algorithms provides operators similar to Combine.

Our modern Loadable protocol looks like this:

@MainActor
public protocol Loadable {
    associatedtype Value: Hashable, Sendable

    /// An asynchronous sequence that publishes the loading state.
    var state: any AsyncSequence<LoadingState<Value>, Never> { get }

    /// The latest state for quick sync when views reappear.
    var currentState: LoadingState<Value> { get }

    /// Flag indicating if the loading operation has been cancelled.
    var isCanceled: Bool { get }

    /// Cancels the ongoing loading operation.
    func cancel()

    /// Resets the loadable to its initial state.
    func reset()

    /// Initiates the loading of the value.
    func load() async
}

Base implementation

Implementing this protocol is more verbose than using Combine, but that can be solved with a base implementation. Simply subclass and override the fetch() method. BaseLoadable drives the Observation-backed AsyncSequence and yields .loading, .loaded, and .failure states for you.

@MainActor
class UserLoader: BaseLoadable<User> {
    override func fetch() async throws -> User {
        // Your async loading logic here
        try await Task.sleep(nanoseconds: 1_000_000_000)
        
        // Just return the value or throw an error
        return User(name: "Jane Doe")
    }
}

The LoadingView

With this new model, the LoadingView also becomes simpler. It no longer needs a ViewModel; it can directly observe the Loadable object’s state using the .task modifier.

struct LoadingView<L: Loadable, Content: View>: View {
    private var loader: L
    private var content: (L.Value) -> Content
    @State private var loadingState: LoadingState<L.Value> = .idle

    init(loader: L, @ViewBuilder content: @escaping (L.Value) -> Content) {
        self.loader = loader
        self.content = content
    }

    var body: some View {
        Group {
            switch loadingState {
            case .idle:
                ProgressView("Loading...")
            case .loading(let progress):
                ProgressView(progress?.message ?? "Loading…")
            case .loaded(let value):
                content(value)
            case .failure(let error):
                Text(error.error.localizedDescription)
            }
        }
        .onAppear {
            if loadingState != loader.currentState {
                loadingState = loader.currentState
            }
        }
        .task {
            for await state in loader.state {
                self.loadingState = state
            }
        }
    }
}

State Persistence with Observation

A key problem with AsyncStream is that it’s a “one-time” event pipe. If you navigate away from a view, its .task is cancelled. When you navigate back, a new observer is created, but the AsyncStream doesn’t “replay” its last value. This causes the UI to revert to its .idle state, even if data was already loaded.

The latest library uses Swift’s Observation framework to back the state AsyncSequence, which means:

• The latest value is replayed to new observers automatically.
• Multiple observers can consume the same stream safely.
• currentState gives you an immediate snapshot for view re-sync on appear.

BaseLoadable, RetryableLoader, and ConcurrencyLimitingLoadable all use Observation-backed streams. For types that still use AsyncStream internally (for example, DebouncingLoadable), wrap them in another loader if you need multi-observer replay semantics.

Composing loaders

The Loadable protocol and BaseLoadable class create a powerful foundation for composition. The library includes wrappers that add functionality to any Loadable object.

Retry

Loaders can be composed. Wrapping a loader RetryableLoader provides automatic retry capabilities with exponential backoff.

// Create a loader that might fail
let flakeyLoader = FlakeyLoader(successAfterAttempts: 3)

// Wrap it to add retry logic
let retryableLoader = RetryableLoader(
    base: flakeyLoader,
    maxAttempts: 5
)

// Use it in the view. It will automatically retry on failure.
LoadingView(loader: retryableLoader) { ... }

Debounce

Another example for composition is the debouncing of values in a search field. This wrapper delays load calls until the user stops typing.

// Create a loader that performs a search
let searchLoader = SearchLoader()

// Wrap it to add debouncing
let debouncedLoader = await DebouncingLoadable(
    wrapping: searchLoader,
    debounceInterval: 0.5 // 500ms
)

// In the view, call load() on every keystroke.
// The wrapper ensures the actual search is only triggered when needed.
TextField("Search...", text: $searchText)
    .onChange(of: searchText) {
        Task { await debouncedLoader.load() }
    }

Limiting concurrency

This example uses a token bucket, see the source at ConcurrencyLimitingLoadable.

Button("Start Downloads") {
    let baseLoader = ParallelDownloadLoader(itemCount: numberOfItems)
    loader = ConcurrencyLimitingLoadable(
        wrapping: baseLoader,
        concurrencyLimit: concurrencyLimit
    )
}

Conclusion

This is what we got

• Consistency with a reusable solution
• Type-safety with an enum-based state
• Customizable views
• Progress tracking
• Composable loaders

The source is available on GitHub. The final architecture provides a reusable, powerful, and easy-to-use pattern for managing screen states in any SwiftUI application.