• Talking constantly feels more physically tiring on the body than typing.
  • See me after meetings in which I talk a lot. It’s usually harder to context switch back to deep work due to the accumulated exhaustion.
• I am biased (by evidence of this blog) towards writing, and I’ve always been better at communicating complex ideas through writing as a result.

Personally, I find it’s often hard to convey many of my more contrarian ideas in an oral medium, unless I’m well acquainted with the person or group I’m speaking to. Perhaps this is because an oral medium tends to give its way more to “System 1” (visceral) kinds of thinking than writing which lends its way to more “System 2” (deep) thinking. Often, contrarian ideas are not easily accessible in visceral mode, because it takes active thought to go against things.

I think another aspect is that writing is also visible. For example, I could re-read everything I just wrote before writing this sentence, and a pure reader can re-read things as many times as they want. Perhaps this feedback is what encourages more “System 2” thinking.

The downside of course is that in theory productivity slows, but I’m not so sure by how much in practice when we consider overall productivity across a work session. Many of the tasks I give GPT 5.6 Sol run for at least half an hour, and stem from only a single or handful of messages with occassional steering during the task. Therefore, I think optimizing my WPM would be less impactful than optimizing the model’s throughput (TPS)/token efficiency when we consider the overall amount of work being done.

Of course, this is not a piece on whether or not voice interfaces are useless, because that is false. A great example of these are "hands free" situations, devices which aren't designed to have a keyboard and are mostly interacted with ephemerally, or collaborative interfaces. My take is mostly based on personal preference towards how I communicate with other humans/agents digitally.

The interesting thing is that representations are interchangeable, and the right one very much depends on the system’s domain (I really like Stop Drawing Dead Fish). So while handwriting code in general purpose programming remains fun as an art form, it hasn’t really ever been the best representation for understanding and editing. Just the most unquestioned one. For the record, my statements in this paragraph obviously don’t support a general purpose successor to today’s code either because of domain specificity (eg. Visual things need visual and not textual representations).

A lot of talk has gone around about “writing slop to validate code”, which I interpret more as “writing formal verification tools that would’ve been too time consuming before”. I generally agree with this sentiment, and I often do these things myself. For instance, I find myself mocking interfaces a lot less because it’s simply easier to write test infrastructure using live implementations. One of my most recent internal projects even had an entire dedicated library just for testing IPC, Websocket, and HTTP interactions because they were so common place. One of my upcoming open source projects has an entire Python CLI alongside the main Swift package that I wouldn’t have had time to write by hand just to be able to create an export of a model for various inference engines (including Apple’s new CoreAI framework). These are quality improvements that are only worth it from a time standpoint because of agents. (Furthermore, it’s worth mentioning that as humans we are quite bad at making decisions due to a lot of psychological/biological factors. This is where having tools that don’t succumb to those same flaws can help. See the hungry judge effect for an example of such a biological factor.)

How one interacts (ie. reading or writing) with code today largely depends on what is being built seems to be my line of thinking. For one, if the end product is an SDK of some kind, then you’ll be forced to at least read the code for the public API since code literally is the product. For complex and safety critical domains (ie. hard to get write/dangerous to get wrong), it obviously still makes sense to read and verify everything alongside having formal verification tools to make that process more robust. However, for apps where the code-level implementation consists of mostly “gluing libraries/frameworks together”, it’s probably becoming less important since the difficult part for those was never the code in the first place, but rather architecture and domain complexity. (In fact, the intensive focus on code may have taken away necessary focus on architecture! This is something I’ve certainly been guilty of in the past.)

I still like handwriting some amount of code whenever I have spare time to, mostly for learning purposes and because it’s still fun. (eg. When learning MLX Swift recently, I opted to write a model by hand before I allowed myself to use agents for the same thing, this gave me a better understanding of the framework’s mechanics.)

One primary issue is that the “same model” does not imply “same weights”, so it’s possible to have multiple copies a single model with different quantizations, fine-tunes, etc. This is not even considering the proprietary file formats from some engines, which would cause further fragmentation.

It wouldn’t be practical to run a single OS-level inference server on mobile either due to the disparity in the amount of engines that exist. Any server would have to have a set of “known engines”, or an ability to link new engines dynamically somehow (perhaps in a similar manner to dynamic SQLite extensions). The latter of which is something Apple would certainly never allow (their on-device SQLite build explicitly disables registering extensions). So the global registry would largely be for storage purposes.

The next question would be one of security, both in guarding which apps are allowed to access certain models, and in terms of defining “what is a model”.

Open weight models like are probably ok to share globally with other apps, but this wouldn’t be ideal for proprietary models/fine-tunes. Today, we have privacy by default since each app has its own sandbox. iOS can support limited sharing through app-group containers, and Android also has mechanisms for this.

Next is “what is a model”? Presumably, the registry would be optimized for model storage specifically, but models are merely distributed as ordinary files with some engines having their own dedicated file formats. In essence, this would largely be a standard directory service that an app would probably interact with through an on-device framework (eg. ModelStorageKit), but even this framework would likely have to resort to depending on a plain URL from both Swift and Kotlin respectively. Various app review processes would be necessary to determine if the registry is being used for “model files” in practice.

Afterwards, we want to allow end-user control somehow. Of course, 99% of users are completely clueless as to how any of this works, and thus won’t be able to exert much control in the first place. (See Apple’s “Buy more Intelligence” messaging for requiring users to upgrade their iCloud accounts for more Private Cloud Compute access…) Generally speaking, I’m unlikely to come up with something good here since I’m primarily looking at this from a technical lens first.

All in all, this is clearly a very silly idea. Though I still do think the problem may become more real if edge inference picks up more, so hopefully by that point we have better means of solving this. The end-user perspective is something that will need to be fleshed out more because I don’t think “here’s a screen with all the model names and the ability to delete them” is a good UI for this. Furthermore, it’s also clear that the current means of model distribution don’t fit nicely into this potential system, and I suspect more than just simple shared file storage would be necessary.

Despite that, I think there are many ways to achieve greater understanding without today’s code, but it differs from domain to domain (eg. UIs and ML Kernels have different needs and programming styles). The end result will still be and feel like programming, but with different representations more tailored to the problem domain. Ideally ones that are more aligned with the advanced thinking styles of the problem domain. (eg. Geometric representations for UIs, more mathematical/information oriented representations for ML models, etc.)

However, I don’t think today’s code as an art form will disappear. A lot of us pre-agents were doing this because of enjoyment for the art form, that generally doesn’t just go away all of a sudden.

Inference requires more hardware resources than gaming, especially so for memory. To put this into perspective, most AAA games can played casually on a single NVIDIA GPU or directly on consoles that cost <$1000. Yet, running just a single inference task on a frontier model requires a cluster of enterprise-grade GPUs and parallel distributed overhead due to available memory bandwidth. Training requires even more resources than that generally. So the compute needs for SOTA inference are often greater than SOTA gaming, and we’ve tried to put gaming in the cloud. It’s generally a worse experience due to latency.

This is to say that no amount of compute can remove the constraint of a simple network connection, which means that a truly realtime medium is likely best suited for local models. For the record, this doesn’t necessarily mean LLMs either. In fact, if anything it’s more likely that LLMs are not the kind of model for the kinds of mediums that would benefit most from local models (see World Models).

Of course, I’m also ignoring the need for privacy, ethics, etc. Those are also things that necessitate local models, but I don’t consider those the selling point because historically few in the general public care about those concerns. (If they did, they wouldn’t be using social media the way they currently do.) The medium is the massage (the typo is intentional if you're familiar with McLuhan), and that’s what I would rather focus on. Especially given that any medium driven by local models will also have privacy and ethics concerns more tightly integrated by default.

In essence, I would avoid looking at local models as a “cheaper and more private/ethical alternative” to frontier models. The frontier will likely always have an edge on local models for “hands-off” non-latency critical agentic workflows, which is the major paradigm today. However, AI is thankfully more vast than agentic workflows and LLMs. Almost certainly there’s at least something that can come out of that where local models will have an edge over the cloud.

Original Prompt:

I want you to run a quick experiment.
 - Create a very simple Swift package that imports Foundation, and compile it for WASM.
 - Then change the Foundation import to FoundationEssentials, and compile it for WASM.
 - Then remove the import entirely, and compile it for WASM.

 At the end, report back the WASM binary sizes for each build. Make sure to build in release mode for each build.

Later Added:

Ok, now run the same experiment, but add another build that imports a C target exporting and using yyjson. Compare the new binary size to the other cases (you don't have to run the other cases again, just compare the new case to the ones you have here.)

Final Result:

┌──────────────────────┬──────────────────┬──────────────────┐
│ Variant              │ Pruned WASM      │ Brotli-11        │
├──────────────────────┼──────────────────┼──────────────────┤
│ Foundation           │ 45,718,166 bytes │ 12,016,398 bytes │
├──────────────────────┼──────────────────┼──────────────────┤
│ FoundationEssentials │ 7,765,629 bytes  │ 2,011,377 bytes  │
├──────────────────────┼──────────────────┼──────────────────┤
│ No import            │ 3,319,821 bytes  │ 896,977 bytes    │
├──────────────────────┼──────────────────┼──────────────────┤
│ CYYJSON / yyjson     │ 3,667,654 bytes  │ 984,086 bytes    │
└──────────────────────┴──────────────────┴──────────────────┘

 The yyjson case is:
 - +347,833 bytes over no import
 - 4,097,975 bytes smaller than FoundationEssentials
 - 42,050,512 bytes smaller than Foundation

Suffice to say, 12MB shipped to the browser just because of Foundation is not ideal at all considering most web-apps are a fraction of the size. FoundationEssentials cuts down on this, but it still more than doubles the size of this simple package. Goodnotes’ WASM binary size is ~50MB, but it was able to be compressed down to ~12MB, and I am very certain they import Foundation.

Often, I find myself using importing Foundation in library code because I just need JSONEncoder, JSONDecoder, URL, or Date. However, as we can see this increases the bundle size by a lot for WASM.

URL and Date can be solved by using String and Double for most cases respectively. However, I would still provide a package trait for Foundation specifically such that the library can still ship APIs with them.

JSONEncoder and JSONDecoder on the other hand are more painful because building a good JSON parser is not trivial, and is out of the scope of most projects. However, we can see that vendoring a small, portable, and fast C library like yyjson can solve a lot of that issue. The only problem is in order to support Codable types, its up to you to make your own equivalents of JSONEncoder and JSONDecoder that don’t also import Foundation if you want to keep the binary size small. Though, it shouldn’t be too hard or tedious to do this with the help of an agent, as it is mainly a simple Swift wrapper.

That being said, it would be ideal to see some of these trivial types in the standard library instead of Foundation, primarily to avoid awkward cases like this.

One question is how can we do this on a larger scale?

In ML, we can state a very simple conceptual model could be:

x -> f(x) -> y

Where:
x = Some input
f = Some model
y = Predicted output from f

For those with a mathematical background this makes intuitive sense, but for those who despise math (ie. most of the population), this is complete gibberish. However, even for those with a mathematical background, there's still the question of: What does $f$ look like exactly? Of course, there is some outer observable behavior we can sample statistically, but the uncertainty of this forces us to use statistics. Still, at least those with a mathematical background are able to reason with uncertainty provided by a model.

What about everyone else however? Who don't have the ability to think this way, and who must vote on policies in this area? First, they get media headlines, which have clear ulterior motives alongside often being written by those who are also in the same boat. Secondly, without a conceptual model of ML, all they can rely on is guessing its tradjectory superstitiously. Talk to any non-technical person about AI, you'll nearly always run into the "replacing all the jobs" topic, and nowadays you may hear their opinion about all the datacenters. Thirdly, their point of view of AI is that it's exactly what ChatGPT is, which is a limited point of view of the entire field.

There's another class of people who write code professionally, but run as soon as they see a math formula. Many of these people will be working on agentic systems in the future, so some level of understanding is essential. While these people are generally far better off than the average joe, experience shows that many also don't get far past the brief $y = f(x)$ conceptual model I presented at the beginning. (eg. Many Claude Code/Codex users don't know how KV caching works, even though it's directly relavent to token costs. Perhaps they will take note of this when the subsidization isn't as generous!) Over time, the standard "technical interview curriculum" may screen for basic regurgitation of how LLMs work under the hood, but regurgitation isn't understanding.

As a result, fear is the most justifiable reaction for many. There is no way for them to reason about uncertainty, and what their told isn't exactly encouraging either. They need an enlightened imagination, which starts from a good set of conceptual models on an individual level. The larger scale effort for "achieving this in everyone" requires much more, and is outside the scope of this note, but universal basic literacy shows that such a thing can likely be done.

So what does a good conceptual model look like? This is something I'm still trying to figure out and finalize, but I can at least share something that has thus far worked quite well for myself. The model I've thus far converged on is to think of a model as an "executive process of knowledge". That is, with each operation, layer, representation, etc. what semantic "meaning" does it convey?

For example, full-attention is $O(n^2)$ , which makes it scale poorly when the context grows linearly, but it turns out that not every token needs to attend to every other token in the context. Imagine a book, it's unlikely that a random paragraph from chapter 6 is directly relevant to a random paragraph in chapter 2, but the words within the paragraph of chapter 6 are highly correlated with each other. We can use this intuition to begin to see how we may optimize attention/context/KV caching to support things like longer context windows, resource constrained environments, etc.

Now a layman wouldn't understand any of the ML or CS specifc terms that I mentioned in the last paragraph, but they have a much better chance of understanding this sentence.

Imagine a book, it's unlikely that a random paragraph from chapter 6 is directly relevant to a random paragraph in chapter 2, but the words within the paragraph of chapter 6 are highly correlated with each other.

Is this a gross simplification on many different levels? Absolutely, but it does show the beginnings of how one may "reconstruct" the complexity to a more learnable form. This idea of reconstructing can be applied all the way down to the implementation details of techniques that segment the context, KV cache, etc. That is, for each concept in the implementation, there is a way of reconstructing its ideas in a form understandable for a given individual. This is already what practitioners/researchers are already doing, even if unconsiously.

Another issue I see is the prevelance of ML frameworks and libraries that hide much of the complexity. (ie. Violating Butler Lampson's "don't hide power" principle.) For instance, Apple's FoundationModels framework hides many of the details of the underlying language model, and further is only designed for multi-modal (text-only pre-Apple-OS 27 versions) LLMs, but otherwise has an intuitive API. Hiding the complexity in this way presents 2 problems for uninformed users.

• One doesn't realize they have more control than they think over a model.
• One begins to think that all models take the same shape as whatever a framework allows.

To conclude, this note has one primary point: universal ignorance isn’t bliss for a foundational technology.

One obvious path from this is to fully lean into agents, embrace loops, product engineering, etc. to produce new software in a factory-like style (or whatever mainstream style comes in the future). This will likely be the most common path, because it's the most natural step up for most engineers building traditional mobile/fullstack apps.

The other is to see that agents can write traditionally tedious code, and lean into the fact that you have time to do something harder now (ie. Something agents can't replicate with ease). For example, while still incredibly useful tools, agents don't replace the need for research, have difficulty with performance sensitive/security critical code, can't build hardware, and generally don't train ML models. This path requires a lot of learning, potentially more than embracing agents because it isn't a natural next step for typical application devs. As a result, it will likely be less common, but may be worthwhile for those who feel that agents have taken away the art of coding from them.

That being said, regardless of the path, agentic systems are where things are (currently) headed. Therefore, one does need to learn more beyond just being a mere consumer of coding agents regardless of the path.

As said in the previous note, spiritual optimism is a general trait of superstition, which is a human universal form of thinking. Generally, I think deep styles of thinking (engineering, mathematical, scientific, physics, creative, etc.) help get around this, but this is very hard for people without those backgrounds (which is unfortunately most people, who also are likely not the ones reading this). The reason I say this is because a style of deep thinking often gives one a framework on how to approach evident situations, and such a framework is often reasonably (or perhaps unreasonably) effective in dealing with those situations.

The effectiveness of the framework is the key to countering superstition, because the thought patterns that lead to superstition generally aren’t very effective (they wouldn’t be superstitious otherwise!). Despite that, even people who have backgrounds in the kinds of deep thinking styles I’m referring to still commonly fall for superstitions, especially for cases where there may be a mismatch between the situation and their familiar thinking styles. In this sense, I believe there are still more styles of thinking that need to be discovered that have not been discovered yet. Most likely, such future thinking styles will be encoded as entirely new fields or industries that don’t exist today.

In ~200,000 years of human history, geometry found its roots circa 70,000 BC, and engineering only really started appearing in 10,000 BC. The notion of “science” took a lot longer to appear, only becoming a widespread phenomenon starting in the 16th century. It took another 2 centuries to realize that absolute monarchy wasn’t a good idea to the point where it could be replaced with newer democratic systems. At the same time, the Industrial Revolutions developed the modern notions of work, public education, society, etc. Computing, electricity, universal literacy, and the internet only became widespread last century, and it’s taken until the present time for modern AI to become widespread. Each of these points spawned new fields, industries, and subsequent styles of thinking to make the fields and industries work in the real world.

We’re still very adolescent when it comes to developing such methods of thinking, which is also why I don’t think of “human-level intelligence” as a viable end-state for AI (the target is always moving, and the current target has many flaws). “Biology and beyond” is where computing needs to be, so this is a good way to gauge where a program/system is.

Regardless, the overall point is that to counter Spiritual Optimism, you actually need to understand how things work. When you don't understand something, you need the inclination to learn rather than depend on superstition. New styles of thinking help with that, but it's also worth asking how we can cultivate more of the inclination to understand things. Either way, superstition is a human universal, so I still hold the point that any system designed for humans needs to take it into account.

Quite simply, it’s formal definition is: A large amount of insistence that performing a certain action once or repeatedly will produce a specified outcome that cannot be universally proven to be solely attributed to the action.

Blindly using AI is currently a great example of this. However, this also commonly exists in tech decisions, such as assuming that using Rust will solve all of your security problems, or that applying certain design patterns will make your codebase better.

So what happens when performing the action doesn’t work, or even produces the opposite of the intended result? One of the most common rhetorics is to tell the actor that they are simply performing the activity wrong (skill issue) or not believing hard enough in the “doing” of the action (disbeliever). While this may be true in any given scenario, it often misses critical parts of doing proper outcome analysis, but often the worst part of this is that it discourages finding or doing the necessary critical parts during analysis. Furthermore, it may cause more advancements in the doing of the problematic action, which is often good, but can make things worse culturally if such advancements don’t cover the case for why the desired outcome wasn’t achieved.

Of course, this principle goes further than software because it’s really an explanation of the general human trait of superstition. This kind of thinking has actually played a part in civilizational collapse before, one case is the Black Death in 1340s/50s which killed an estimated 50% of the European population. In that case, a relatively common belief at the time was that those affected by the plague were sinners of religious faith being dealt divine punishment by God. Furthermore, medieval medecine was based on balancing the 4 humors (blood, yellow bile, black bile, phelgm), and further shaped by miasma, astrology, and regimen.

Needless to say, these approaches were spiritually optimistic in the sense that religious faith would always bring safety during hard times, and on the fact that existing medicine was the key to good health. However, the spread of more religious faith and improvements in humor balancing, though pushed for, weren’t what directly helped curb the plague. Rather, it took newer/modern practical public-health measures like quaratines to stop much of the spread.

I can keep extrapolating, but I think the point is clear. What is true however is that this is a clear problem that must be taken into account when it comes to systems design, and especially so for usage patterns of AI (see cases of psychosis, extreme subsidization, etc.). That is, we cannot prentend like users are logical people who don’t believe in absolutely insane things (we all do).

However, the main cause for using coding agents in the first place was the big inflection point in December/January. Once a model gets to that point in terms of performance, it becomes viable so to speak, and improvements afterwards are mostly incremental in the sense that you can do larger amounts of work with them with less intervention. That is, you can still get lots of work done with older models like GPT 5.2, GPT 5.3 Codex, and Opus 4.5/4.6 if you want to, but they will require more steering. The bigger increases in productivity since that time seem to be more tool/harness-based as we understand use cases better, and offer more ways for agents to close the loop for a given task.

As for Minimax M3 specifically, it does tend to get “stuck” more often. I had to fight with it for an hour for it to realize that it should be writing the string “tool_call” rather than “tool çcall”, which was one of the only few agent conversations where I prompted the agent in all caps to indicate frustration (I literally told it to use the proper string over and over again, and it just could not put 2 and 2 together…). Eventually, I had to handwrite code like a caveman to solve the issue. All jokes aside, I still do handwrite and enjoy handwriting code, especially so for library/framework code that requires stability (though we’ll see if the future dictates whether or not this will remain an option). Though overall, I find that the model does fine with appropriate steering, just like any other model, and that many of my issues probably arise from the fact that I’m primarily a GPT 5.5 user.

On a side-note, I hear many people like to swear to their agents, and genuinely use very “controlling” (to put it nicely) language to them. In my case, if it weren’t for the fact that such conversations contained work details, I wouldn’t mind sharing them with others. I hope this dynamic doesn’t worsen our overall social development given that most working conditions are already bad enough as is lol. (It absolutely is having some psychological effects that aren’t good, but those are topics for another time.)

Update (6/21/26): I have since been enjoying GLM 5.2.

I can actually recommend FoundationModels as a usable framework now, primarily because it’s possible to integrate other engines with it. I also like the general API shape they took (it seems similar to this agent framework that I had in mind at one point, but adandoned because it wasn’t worth scoping such a general framework to a single inference engine). Furthermore, one issue in Swift was the lack of a standard generic framework for writing agentic workflows, which caused me to write an entire agentic API from scratch for Swift Cactus that was similar, but not the same as the FoundationModels API. Given that Apple is opening up the core of FoundationModels and getting Anthropic + Google to contribute official adapter packages, I think it’s safe to say that we have that standard now. All of this means that engines can focus on being good engines now without having to worry much about creating a good Swift API, which isn’t the kind of work that most who work on such engines are suited for.

CoreAI seems like a cool CoreML successor. However, it faces the typical Apple platforms problem of being scoped to only the latest OS version, which means that it will be at least 2 more years until it can be used reliably at a widespread scale. In the meantime, there are quite a few more options of which most also work (or will soon) with any torch model.

SwiftUI seems to have stabilized quite a bit given the relatively simple additions this year. Notably, I would say it’s nice to see more robust document support (so one doesn’t have to fallback to using UIDocument or NSDocument as much). Though, very advanced text capabilities outside of cool animations are still seem to require dropping down to UIKit/AppKit/TextKit. Nevertheless, I think agents have largely made writing traditional UI code quite straightforward no matter the framework, so dropping down to UIKit/AppKit is easier than ever if SwiftUI is missing something you need.

Swift Data also finally allows observations outside of SwiftUI views, but once again this faces the OS requirement problem. Even then, I’ve never been biggest fan of Swift Data due it feeling like a black box. SQLiteData supports the full capabilities of SQLite, is open source, uses Swift value types, supports Observation, works outside the Apple ecosystem, and even has automatic CloudKit sync if you desire it (Though personally, I’ve found that application-specific sync engines make more sense for large complex things). That being said, value types and the Observation can be a rabbit hole, especially when it comes to observing individual properties on larger value types (I even once made this helper class to make such observation easier).

withContinuousObservation is also a nice addition to the Observation framework, but has the OS requirement problem. observe from Swift Navigation provides most of the same functionallity, but will work properly on any Observation supported OS version. It’s also quite self-contained so you can drag and drop into your project if you don’t want the dependency.

I personally try to avoid Xcode in favor of using Zed and the Codex desktop app, and also tend to write most of my code (even for apps) in Swift packages. Therefore, I cannot comment much on its updates. Primarily this is because of performance, but also the fact that I work with other languages, so it’s nice to have a single editor for all of my code. That being said, there are more alternatives to Xcode than ever before, so you can always use something different if it doesn’t live up to standards.

As for video sessions, many felt more like guidance/how you should do things kind of sessions over “here’s some example code” like in previous years. This makes sense given how agents are handling most of the code writing now, which means more emphasis is placed on higher-level patterns. (That being said, the need for great engineering is needed more than ever now, and that generally doesn’t come from looking at a few code examples.)

Overall, I would rate this year higher than last year where much of the focus was on some glass (see this). Though I suppose it’s annoying that my Apple Watch Series 7 will not be getting watchOS 27, time to upgrade…

In the long term, I don't see this particularly leading to mass good outcomes, but rather many bad ones with a few possible good ones from necessarily small teams of "responsible" users. This is already happening at organizations that have the means to capture even the best talent. (I also think much of this relates to "maintenance" vs "creation" mode, of which the former tends to apply more to large companies like Uber. In practice, maintenance is more about hardening and making a system more robust, which is quite different from writing new functionallity from scratch. That is, one cannot fix systems with the same mindset used to create them.)

What becomes strikingly clear is that at a certain point the bottleneck becomes your eyes if you watch the stream visually, and you cannot process text being decoded that quickly (also notice that your eyes will try to "fill in the gaps" when line breaks for paragraphs are decoded). In that sense, the rate of visual streaming should not reasonably be the same as the decode speed in application code. So when it comes to communicating meaning in a visual throughput context, the ratio of meaning to throughput matters much more than the raw throughput and raw content separately.

A lot of this can also be foreshadowed as to what an ideal representation would be. That is, a representation that conveys visual meaning, that can be incrementally expanded and explored in real-time, and can be formed reasonably quickly. Throwing LLMs at this problem isn't the full answer. Something different is needed, especially for edge use cases.

Given that Bun was recently ported from Zig to Rust in a matter of weeks, it's more clear now than ever that language choice is becoming much less of a decision that locks the life-blood of your project. My experience also shows this, where I've been able to write a module in one language, and then tell an agent to create a version of the module in another. So far, this kind of transpilation hasn't failed me, and if it can work on something performance sensitive like Bun, then it can work for traditional libraries as well.

I've also had it work for other things like adding new formats to my stream parsing library where I had an agent derive the YAML parser by looking at the implementation of the JSON parser. It turns out, the mechanics of parsing were very similar minus the obvious syntax differences between YAML and JSON. In fact, earlier agent attempts would even transpile the YAML to JSON, and then call the JSON parser!

That being said, this transpilation technique only works if you've figured out the architecture and design quirks of your system. I wouldn't pair a transpilation task with re-architecting using an agent. This is a setup for a lot of pain.

Something I would like to see however is what would happen if you asked the agent to translate Bun's new Rust port back into Zig? Intuition tells me that this is likely a lossy compression algorithm, and that the original Zig code would be better of the the transpiled Zig code. However, there's no way to definitively prove that case.

This note, without mentioning anyone in particular, may or may not be addressed at a certain group of individuals who have claimed that they will rewrite their project in Rust, but have not yet done so. It is an exercise left to the reader to determine that group of individuals, and to motivate them to do so.

I disagree with the general sentiment that states that one must ascend through the "fundamentals" before they get to use the cool frameworks or techniques that are perhaps more abstracted from the "fundamentals". It is true that pure vibe coders and framework warriors aren't the ideal end-states for new programmers. However, I've known many others in the past who were said framework warriors that eventually learned the "fundamentals", and are sufficiently skilled today. (eg. In the Swift world, Paul Hudson begins 100 days of SwiftUI with only 2 weeks of Swift fundamentals, and every subsequent project is building apps with SwiftUI and other Apple frameworks. Many talented developers today went through that course as their intro to programming in general.)

What we call the "fundamentals", and the designs of various frameworks and agentic coding styles are really all just ideas. Ideas are things that we play with through exploration, intuition, connection, etc. Without this, we would never discover new insights or novelty. It's worth noting that most traditional schooling or structured curriculum typically does not promote learning via playing with ideas, but rather through drilling them into you in a specific order via fear and punishment. This often fails to cultivate any enthusiasm for long-term learning other than for personal extrinsic achievement.

So really, if a learner isn't interested in playing with ideas, they aren't going to be good regardless of whether or not they start with the "fundamentals" or with the bleeding edge. If they start with the fundamentals, they'll quickly become disinterested because they'll get bored. If they start with the bleeding edge, they'll never reach a sufficient level of competency because they have no reason to do so (the bleeding edge abstracts them).

By contrast, a person who loves playing with ideas will do fine no matter what path they start with. If they start with the "fundamentals", they'll enjoy playing with the foundational ideas, and become curious as to how those apply to the bleeding edge. If they start with the bleeding edge, they'll become curious as to how the fundamentals will improve their usage of the bleeding edge stuff.

This means the more important goal here should be to cultivate learners who love playing with ideas, especially those of "systems" and "processes". There are many ways to do this, but I don't think a strictly structured curriculum is the answer you want here. Good "systems" and "processes" often take many ideas from the "outside", so you need to allow for this exploration to happen (which often requires removing structure in favor of creating a good overall environment).

Some people are concerned about giving "juniors" access to agentic tools, and that they should earn their right to use them. However, I think it is wrong to deny learners access to essential tools that they will likely have to use everyday in the future. Richard Hamming once said that teachers should prepare their students for their future, and not the teacher's past. We can claim the quality of agent code is bad or otherwise lacking (it certainly is severely lacking compared to a good human). However, bad code won't stop agents from becoming a necessary everyday industry tool (this point comes from Casey Muratori).

A corollary example to this is with regards to the skill of general communication, of which most people are seemingly lacking. If the training for the workplace was the school classroom, then we'll take note that "talking" is often forbidden in the classroom, and that it's a right to be earned. That is, in order to earn your right to begin building your oral communication skills, you must first earn the right to talk in the first place. Of course, you would think that the last sentence is ridiculous when stated as such, yet we enforce it in schools anyways.

Forcing people to "earn" the right to learn essential skills is generally a great way to gate-keep people from learning them.

So I say let new learners use the agents in safe environments. As long as they are interested in playing with ideas, they will make an effort to avoid the negative effects of cognitive outsourcing present in today's tools. Of course, future tools could offer more forms of input and visibility which can massively help with reducing that outsourcing, and may even enhance understanding. Despite that, today agents are an output amplifier of current thinking. A curious person using them will likely remain curious, and a non-curious person using them will likely remain non-curious.

This isn't an AI problem, it's a cultural learning problem in general, so any long-term fix would need to happen at that level. Good tools can aid that process, but a real solution to this problem really requires looking at our institutions of cultivating learners.

So how can one use LLMs for learning new languages?

I'll answer this straight with the technique I have been using, which I think can also work for beginners learning their first language. Though the learning process for total beginners will be a bit longer since they must also learn the foundational ideas behind today's languages. Thankfully, given that pretty much all mainstream languages are quite similar, this foundational learning only needs to be done from scratch once.

I start by generating lots of agent code for various non-critical things, and then spending a lot of time actually reading the generated code. This allows me to see the mechanics of the language in a real setting at a mere glimpse. Then, I continue to drive the agent by describing high-level designs in prompts, continuing to read/analyze the code along the way. After doing this enough times, I decide whether or not it's worth learning the language by hand based on how much I enjoy its mechanics from a glimpse. In other words, this process builds a high-level map of how to navigate the language, and forms a general opinion on whether or not I will like writing code in it.

The handwriting aspect is important because it forces you to understand the foundational mechanics that make up the language in great detail. This in-turn makes you better at using the agents in the future. However, the aspects I would focus on handwriting should not be glue code like basic IO, basic data transforms, and simple UI components, but rather things that the agent will struggle with. Namely: performance intensive code, library/advanced typing shenanigans, non-trivial memory management, security, etc. Good library design tends to cover all of these points, and will often require you to push the language to its conceptual limits via handwriting.

Another aspect of handwriting you can do while using an agent is "being a janitor". That is, take part in manually cleaning up agent code, since it tends to be verbose and/or slow in the general case. This will get you familiar with the various syntatic sugars and performance facilities found in the language, and will help you further craft a personal style.

Generally speaking, I think this process also makes it easier to learn languages in parallel. One of my current projects uses Rust, Go, and a bit of Python all at once, which I hadn't touched in a while (~2-3 years for each) before starting the project (TypeScript is also used, but I'm already experienced with it). I was also able to use this technique to become proficient enough with C++ to do some open source contributions where much of the code was written by hand (this also required reading dedicated books).

That being said, none of this works if you don't like playing with ideas. So really, the difficulty is cultivating that.

In planning, pay attention to anything it does, and I often will have it sketch interfaces/types to understand what it's about to generate. I often find that it will create types with many unecessary fields, methods, conformances, etc. So I tell it to cutdown, and it generally listens.

I'm reviving this because of the major issues that Github has been having recently. The amount of downtime and issues can potentially become a serious problem down the line, and it's already been problematic for lots of large projects. If the ending of Theo's recent video where he describes fragmentation plays out, and his theory of there no longer being a "singular profile" for any given person is true, then the only way to have such a profile is to create your own.

As we can see, if Github continues on its current trend, and more people begin migrating away, then anything stored on Github is inherently "lost" to more and more people. Eventually, Github will fail completely on a long enough timescale (could be decades), and with it all of it's repos will vanish. The only way out is to clone the repos elsewhere.

The information and code on this site is controlled entirely by me. It's not an inherently failable business, and I don't ever intend to make it one. I do use Netlify for hosting, and Netlify will eventually fail on a long enough timescale like any business, but I will just find a different hosting provider in that case. You likely won't even notice the disruption if that occurs unless you lurk here endlessly like some seem to (you know who you are).

So to reiterate, the reason I put effort into this site compared to social media platforms is because I at least know that I can keep this up as long as I'm still around.

Of course, the natural advice for getting around this is to "scope down", or essentially slash your creation until it becomes a dwarfed version of it's actual self. Then you may actually finish it!

There are 2 points I generally don't like about this:

• Not everything should be finished.
  • The idea that we have to finish everything we start is really an arbitrary thing learned through schooling. Yet it's of the only things that leads to the "predicatability" we so crave, so it becomes the norm in the real world.
  • Honestly, I would rather that a conceptually bad project never gets finished rather than unleashing a zombie in the real world.
• If "cutting scope" is the correct answer, that inherently means we're creating something that isn't at it's fullest potential.
  • From an building-as-an-art standpoint, this hurts me emotionally.
  • From a building central infrastructure standpoint, this hurts me logistically.

However, things do need to get finished at some point, we can't just keep adding features endlessly. Therefore, how does a line actually get drawn here?

For me at least, this has been the result of a perception change. That is, instead of creating the thing to solve the problem entirely, instead create the thing that allows the end-user to solve their own problems. Or, in Theo's words, "Allow your users to do their bespoke bullshit". I view this as enhancing one's inherent ability rather than substituting it with a product they can't see the internals of or modify directly for their personal needs.

With that perception change, now the entirety of how we design things changes. The basic notion is that whatever is built has to be directly expandable by end-users. I've found that getting to this point has much smaller inherent "scope" whilst still being able to produce something useful. This is because now the focus shifts from "How many features does this need to please people?" to "How simple can this be to be adaptable in any reasonable situation?". In fact, I treat feature requests as bugs with this perception (If you have to ask me for the feature, what is missing that prevents you from making it yourself?).

Reaching such simplicity is hard, but it's a necessary part of systems design, especially for things that need to be stable. It also requires saying "no" in a professional context to features that don't benefit this simplicity, though this may not always be ideal personal reputation-wise.

Regardless, this is one of the things that I think library design makes you realize, since libraries by design have to be adaptable/extendable by principle. We often speak of "less is more" for this kind of reason.

Only indexing mechanically takes away understanding or a chance to go on a journey to find that understanding (of which the journey itself produces learnings). Only indexing based on intuition can potentially lead one down a false path, and/or cause them to miss subtle and hard to find details. Both extremes lead to a lack of enlightenment in some way, mechanical-only leads to pure acceptance of black-boxed mechanical-standards, and intuition-only leads to conspiracy theories.

Funnily enough, not being able to understand a black-boxed mechanical mechanism also leads to conspiracy theories because the mechanical understanding becomes purely intuition-based. So really, black boxes can be quite bad for important things, especially when most people are not the kind who want or have the time/ability to deep dive and understand them.

For example, a lot of LLM-based tools will offer the ability to summarize readings, but the problem with these tools is often that they encourage the "summary" as a replacement for reading instead of an enhancement. An LLM-based summary is mechanical indexing while actually reading is intuition-based indexing, so only accepting the summary is like treating the actual reading as a black box. Now of course, not everything needs to be drawn out to 500 pages, but it's also no secret that more capable people are the ones who tend to read more.

The second is intuition, in which information is index by an explicit process that determines a set of information is related for some reason. This is typically implemented manually by humans as they determine which pieces of information are related, and a good UI helps with this. This is useful for creating and understanding.

Both of these seem to be essential properties for any dynamic information system.

ie. (Based on the episode code examples)

final class MutexCache {
  private let entries = Mutex<[Int: Int]>()

  func set(_ key: Int, value: Int) {
    self.entries.withLock { $0[key] = value }
  }
}

final actor ActorCache {
  private var entries = [Int: Int]()

  func set(_ key: Int, value: Int) {
    self.entries[key] = value
  }
}

let actorCache = ActorCache()
let mutexCache = MutexCache()

// 1. Mutex Cache is Faster
for key in 0...10_000 {
  mutexCache.set(key, value: key + 1)
}
for key in 0...10_000 {
  await actorCache.set(key, value: key + 1)
}

// 2. Actor Cache is Faster
extension Actor {
  func run<T>(_ fn: @Sendable (isolated Self) -> T) -> T {
    fn(self)
  }
}

for key in 0...10_000 {
  mutexCache.set(key, value: key + 1)
}
await actorCache.run { actorCache in
  for key in 0...10_000 {
    actorCache.set(key, value: key + 1)
  }
}

Intuitively, this makes sense since each call to set on MutexCache will have to acquire a lock, whereas all the calls to set on ActorCache can be grouped into a single isolated access (which effectively removes the overhead).

However, there's more to this, as right now the MutexCache embeds a lock internally, but what if we did this instead.

final class NonSendableCache {
  private var entries = [Int: Int]()

  func set(_ key: Int, value: Int) {
    self.entries[key] = value
  }
}

let nonSendableCache = Mutex(NonSendableCache())

Now, you can see that we made a simple cache that was non-Sendable, which means that we don't even have to worry about concurrency in its implementation. Then, we create a local variable that wraps the non-Sendable cache in a Mutex. This allows to do the following:

nonSendableCache.withLock { nonSendableCache in
  for key in 0...10_000 {
    nonSendableCache.set(key, value: key + 1)
  }
}

This is essentially the same thing as calling the run helper on ActorCache, but for mutexes instead. Now because we only have a single grouped access from both ActorCache and our NonSendableCache, the performance is essentially the same for our benchmark operation. Since the number of isolation hops/mutex acquisitions is 1, the overall synchronization overhead is practically negligible.

However, the benefit of NonSendableCache is that we also get to use it inside an actor if we want to defend it, and everything is still all well and good.

final actor ActorCache2 {
  private var cache = NonSendableCache()

  func set(_ key: Int, value: Int) {
    self.cache.set(key, value: value)
  }
}

So really, the lesson here is that non-Sendable code will avoid any synchronization overhead by default, and allows us to defer Sendability concerns to the minimal points where it's absolutely necessary. I wrote about this here.

For me, long term has to mean decades, because that’s generally how long it takes for a culture to completely adopt new ways of thinking (and for the old generation to start yelling at clouds apparently) required to successfully adopt new inventions. Don Norman notes that such a process is roughly 20-30 years (eg. See the HD TV example from The Design of Everyday Things), and this is also the timeframe that Alan Kay and the rest of Xerox PARC operated on with respect to their research (eg. Dynabook was sketched in 1968, laptops came in the 90s, and the iPad released in 2010).

Another aspect about focusing on the 20-30 year timeframe is that it becomes essentially impossible to predict the state of that future from today. If I were to ask you what programming would look like in 5-10 years, you would probably answer around agents and AI taking over things. However, you wouldn’t answer with that if I changed the timeframe to 30 years because our culture would be entirely different then. Instead, the only way to predict that future is to literally invent it if we want to adopt the Alan Kay way of saying things. That is, long term predictions are much more about realizing visions rather than trying to predict where the current trajectories will take us.

This leads us to the nature of those visions. You may think that it would be ideal to draw some sort of futuristic technology, and call it the vision. This is fine for the short (0-5 years) or medium term (5-10 years) scale, but reminder that the difficulty is dealing with the culture. Therefore, I would stand to think that the vision needs to be based around an ideal culture instead of an ideal technology. For Doug Engelbart, this was the notion of augmenting intellect, boosting collective IQ, and improving our ability to improve (if you read his 1962 paper, computers are not the central focus).

void f(__fp16* out, const __fp16* values, size_t values_size) {
    for (size_t i = 0; i < values_size; i += 8) {
        vst1q_f16(out + i, vaddq_f16(vld1q_f16(values + i), vld1q_f16(out + i)));
    }
}
        

However, I assume most of you reading this don’t, so here’s what it actually does.

void sum_all(float* out, const float* values, size_t values_size) {
    for (size_t i = 0; i < values_size; i++) {
        out[i] += values[i];
    }
}
        

This really shows that the lack of understanding came from the fact that the “UI” for the NEON version looks quite cryptic for such a simple operation. That is, one doesn’t know what vst1q_f16 means unless they’ve read the ARM NEON ISA.

Furthermore, if you want to make the NEON version handle sums properly when values_size is not a multiple of 8, you would need to add the scalar section at the end to handle the remaining values. I didn’t include that bit in the first NEON example because it would’ve given the answer away.

void sum_all_neon(__fp16* out, const __fp16* values, size_t values_size) {
    size_t i = 0;
    for (; i + 8 <= values_size; i += 8) {
        vst1q_f16(out + i, vaddq_f16(vld1q_f16(values + i), vld1q_f16(out + i)));
    }

    for (; i < values_size; i++) {
        out[i] += values[i];
    }
}
        

Another thing worth noting is that you would generally not write NEON code like that as an isolated function, but rather as a part of a fused mathematical operation in practice.

void fused_op(__fp16* out, const __fp16* values, size_t values_size) {
    size_t i = 0;
    for (; i + 8 <= values_size; i += 8) {
        float16x8 vals = vld1q_f16(values + i);
        float16x8 out_vals = vld1q_f16(out + i);
        // Other math ops that use vals and out_vals...

        vst1q_f16(out + i, vaddq_f16(vals, out_vals));

        // Other math ops that use vals and out_vals...
    }

    for (; i < values_size; i++) {
        // Handle remaining values via scalar loop...
    }
}
        

There are a whole host of reasons for why that is, but the issue is that such reasons are completely invisible to you whether or not you write code by hand or through an agent. Agents, from my experience, unfortunately tend to fall for the human tendencies of microbenchmark optimization (at the expense of E2E performance) when it comes to these kinds of things, so it isn’t of much help on its own. So even the agent can have blindspots despite having far more trained knowledge than you ever will.

In nearly all tools that deal with code today (Text Editors, IDEs, Agent CLIs, Github, etc.), context about the production environment is essentially invisible from within the tool itself. That is, all code is displayed with the same visual hierarchy, regardless of how critical or uncritical it is. This means that the context has to live somewhere else, which is often one’s head or in model context/weights. I wonder how well that’s worked so far.

For the record, I don’t think the idea of plugins are a bad thing, but they are not a solution to the general application silo problem. Plugins can be fine under the following conditions:

• The API/architecture supporting the plugins is designed for maximal customization.
• The plugin is specifically designed for the application that exposes a plugin system.

The main issue is knowledge, particularly that the plugin author has to know the application that it’s interacting with. The real idea in breaking the application silo is to make it possible for multiple apps to communicate without knowing about each other or their intimate details. This is fundamentally impossible with plugins in the way they are adopted at large.

This knowledge problem is also an issue with how we interact with web-services as well. For instance, you may have your app call OpenRouter, but what if another service comes along that’s better somehow? In today’s world, you would have to manually (or get your agent to), deploy an update to switch to the new service. This is because somewhere in your app there’s a hardcoded URL string that points to OpenRouter directly, so if you want to get around that you need a service discovery mechanism. Thankfully, correlation and pattern matching are what AI tends to be good at.

Now, at some point you will have to know at least one of the thing’s you’re interacting with. That is, you will have to have a hardcoded interaction with something (URL, file, database, etc.) to get the process of discovery started. However, that something ideally is a mechanism for finding “all the things” you need, and therefore you limit the number of hardcoded interactions in exchange for dynamic ones.

On one hand, the monolith becomes very capable due to the fact that it must grow its featureset to match the expectations of users. On the other hand, it’s complexity grows boundlessly, eventually requiring armies of engineers, contributors, and now agents just to maintain it all. This, alongside the fact that many users have become dependent on the monolith, means that progress slows and stagnation begins. Perhaps, once the source code leaks this truth is revealed, but instead we’ll often pretend like nothing happened because Garry Tan just announced that he hit a rate of 100k LOC per day. Just kidding, but G-Kernel when? (It would only take 810 days at his actual current rate.)

This is why it took LLMs to break the stronghold that traditional IDEs had on developers for decades. Throughout that period IDEs were stagnant with only minor incremental improvements year-over-year, and the cost of creating and distributing a new one was extremely high such that no one but the already established players could do it. Furthermore, the established players didn’t want to take the risk of creating something qualitatively different, so they never did and thus stagnation.

The way to defeat this is not to build more monoliths, but rather to build smaller and more well round components that can all interact with each other. For instance, I’ve been enjoying cmux as of late, but I don’t care about its built-in browser and rarely use it. The reason for this is because I already use an actual browser (Zen), and I would rather use Zen than a bolted on WKWebView. However, there’s no way for cmux and Zen to talk to each other, which is why cmux added a built-in browser.

So the question then becomes one of what the communication protocol looks like rather than one of “breaking the application silo” (that’s already been answered). There have been many of these that have been proposed or implemented, but all don’t solve the problem directly for all sorts of reasons. This is primarily because those solutions (Smalltalk, Etoys, etc.) tend to create their own isolated world with their own isolated constructs. This is great for purity, especially if the intention is to redesign something qualitatively different, but unfortunately doesn’t change the current state of things.

To change the current state of things, you’ll need 2 things. One of which is a technical problem, but the second and bigger one is a human problem.

• A variety of transports (HTTP, Websockets, In-Memory, etc.) for the “messages”, and constructs for the “objects” (any existing runnable OS process or code).
• People to universally adopt the protocol.

The second issue is why systems like Smalltalk haven’t been adopted at large, and also exactly why we still have this problem. Monoliths have been normalized to the point where very few will ever perceive of an alternative. That is, the application silo isn’t seen as a problem in the first place, and won’t ever be if we keep building the way we currently are.

I have to say that starting a system like this to interop with existing applications is inherently starting from a non-idealistic point of view. Truthfully, if one wound the clock back enough to the 80s, it would’ve been more ideal to design today’s systems with this view upfront, but I would still say that some progress can be made by starting from our current point. That is, it can hopefully become a comfortable step from a tricycle to a bicycle.

• OpenCode using GPT 5.4 as my primary model. Occasionally MiniMax to see the progress of open weight things, and for smaller tasks.
• 3-4 agents in parallel seems to be the sweet spot for productivity for a focused session.
• I’ve been able to build internal tools for various needs faster than ever before.
• I read the code.
• I still like handwriting code, just not boilerplate or glue as much.
  • The parts that feel more artistic are the parts that I still opt to handwrite.
  • For lower-level things, agent code often isn’t good enough on it’s own, though it may get something started.
  • Neither do I think my handwriting skills have atrophied. Writing more glue and boilerplate code does not keep your skills sharp, but rather taking on actually challenging things does.
  • I still think handwriting will be around for the next few years, but eventually I do believe it will be completely suceeded by future tools in the distant future.
• Agents tend to optimize for microbenchmarks.
  • If you tell the agent that a function is performance sensitive, it will try everything in it’s power to optimize the one function without considering the surrounding environment (especially hardware characteristics).
  • Eg. Introducing a 4kb lookup table for a calculation that runs once in a logit sampling kernel.
• Agents make ~3-4 subtle mistakes per 1000 lines of code.
  • You will need a review system in place for this reason. Codex code reviews seem to catch some of these mistakes, but I haven’t yet tried a dedicated code review tool like Greptile or Code Rabbit (Copilot review doesn’t seem to give useful suggestions on PRs that I’ve seen from various open source projects).
• Mostly writing Swift and TypeScript (professionally + free time), however a bit of C++ (free time) and Go (internal tool) has also been written as of late.
  • Swift tends to be the biggest struggle (especially for MiniMax).
• I don’t feel like I’ve lost too much identity or meaning, primarily because architectural design was always a fun part (and now it gets more focus).
  • As stated before, I still like handwriting artisinal code, but boilerplate and glue are not artisnal code.
  • I also work with a small creative team, and like my environment. If I were in a soul-sucking enterprise where being able to write code was the last level of any work satisfaction I had, then maybe I would be quite depressed.
• PRs have gotten larger.
• Team discussions have shifted away from specific codebase details to more design/business related topics.
• Constant refactors are necessary, because agents love large and verbose functions.
  • This has always been a thing, but now you must remain on top of it earlier in a project life-cycle.
  • Agents tend to write more verbose code (eg. for-loops instead of using more concise collection transforms or other monadic behaviors), and you can often condense their output if you rewrote by hand.
• I find myself branching out into more areas of software.
  • Mobile is one of the categories that more and more vibe-coders are entering. I have nothing inherently against vibe-coders provided their motivations are for the greater good, and I’m happy with the fact that more people have the chance to create something.
  • However, if a vibe-coder can do much of what I was previously doing, then I would rather do something that requires more expertise. This has caused me to seek out contributing to lower-level projects like inference engines.
  • That being said, I will still be working on apps in the future, but the nature of them will inherently involve more technical complexity as a result. In one sense, this can help with building standout features. On the other, it can make me lose sight of what I’m actually creating, so care will need to be taken.
  • From a larger-scale business angle, I’m also not sure that just a mobile prescence will be enough going forward since the cost of building mobile apps is lower to the point where anyone can do it.
  • This branching sort-of started early last year when I began working on libraries instead of apps in my free time. In fact, I would say that a good library is harder to get right than many apps.
• Trust from the marketplace is definitely at an all time low.
  • Take Reddit for instance, where a few years ago posting an ad for a good app in relevant subreddits was generally seen as something valuable.
  • Since the cost of building is now much lower, many people are spamming ads for their vibe-coded app on various subreddits, which has caused lots of backlash (especially given the lower regards to quality).
  • This makes it more strenuous to engage with communities, because now there’s more upfront time cost needed to build proper trust.
• Ralph Loops are an interesting technique for boring stuff.
  • They’ve also been a good way to get something started. Whereby after an initial version is built, you go back to a more engaged development process.
• Less third-party tools are necessary because it’s not as time consuming to build stuff in-house now.
  • If a library or service doesn’t handle something of sufficient complexity or standard functionallity (eg. hosting infrastructure, databases, inference, standardized algorithms, frameworks, etc.), then I find that it’s now viable to build an in-house version of said service or library.
  • This mostly applies to libraries that mostly simplified syntax (eg. react-hook-form)
• Velocity increases 10x when I’m not thinking about design or the details of what is being generated.
  • When I do care, it drops massively. In general, caring about details will drop velocity because it’s more work than not caring. This is not exclusive to agentic coding.
  • I’m also not interested in a LOC generated per day contest. Anyone can easily hit 10k per day by not caring deeply about the intimate details (see this).
  • Furthermore, the ability to increase production without a similar ability to increase visibility and understanding has historically created many second order problems. (eg. Injuries + health problems + work conditions caused by the Loom requiring labor laws to prevent further harm during the industrial revolution.)
• Thinking and understanding is more important than ever.
  • This is a new black box, a new layer of abstraction, and thus a new generation of people who have no idea how things actually work will awaken.
  • Everyone is now yet another step removed from something.
  • Part of that something was bad, and thus it’s good that we’re removed from it.
  • However, part of that something was necessary, and now that we’re removed from it the meaning is lost.

In essence, we have a new tool that increases productivity. Yet, like other such production tools that came before it, it does very little to boost understanding of what is being produced. Therefore, the understanding part is largely an exercise left to the wielder that can easily be, and is often deliberately, ignored.

What further makes this annoying is the idea that “In theory, theory and practice are the same, but in practice they are not.” Therefore, if I mention that the 2 ideas are the same thing in this note, we’re still stuck in theory. In fact, I already referred to them as ideas, which inherently puts them on the same base playing field. If I instead referred to them as “truths”, then once again we put them on the same base playing field.

Another annoyance is the idea that the “real world is messy”, and therefore practical solutions must also be “messy” because of this. This prevents me from creating a simple vacuum to show how theory and practice relate to each other. Of course, this writing is already such a simple vacuum, but so is a conversation, social media post/comment, any form of communication, etc.

I suppose you can see my annoyances with this line of thinking, and what makes things worse is that we tend to dismiss the theoretical entirely because of it. However, it’s also my observation that the best practitioners that I’ve read in the art of Software had a great grasp on both “theoretical” and “practical” ideas, whereas the worst only tend to focus on technologies and frameworks deemed as “practical”.

In terms of economic value, many would say this distinction between theory and practice is massive, and will always use it to lower the value of education (theoretical). However, it’s often those who manage to apply complex theoretical ideas in practice that make the most money, and this is especially true today in the AI era. In fact, the theoretical complexity is often used as leverage! 99% of the population has never heard of a “transformer”, or probably don’t even understand what “deep learning” means at even a basic level. Yet, a growing number of those people are using and becoming dependent on Claude and other models every day.

To those people, learning “AI” means learning how to use Claude to get work done, not learning the underlying principles of deep learning. I’ll be countered here with this, “If you don’t work in machine learning, then why would you spend time learning deep learning principles? How are those principles practical for my purposes?” One response could be that it’s great to always have deep knowledge of things regardless, and therefore if you have the chance and inclination, then you should put the learning hours in.

On the other hand, most people don’t think that way, so I’ll observe that the best practitioners tend to know a great deal about at least what happens 1 abstraction layer below their practice. That is, people who know how to code will likely use agents better than those who don’t. Furthermore, those who understand deep learning can tell when it is being used for both good and evil, which may or may not align with the general public’s perception of the matter.

For those reasons above are why I don’t like the distinction between the theoretical and practical. Then the main question becomes, how do we bridge the distinction?

To that, my answer is that we look at communication. No, I’m not going to say that everyone needs to work on their communication skills, though it can’t hurt. Rather, I’m looking at what mediums are available to us to communicate ideas. Generally speaking, if a typical person (ie. not one that likes abstract ideas) cannot see, feel, or experience an idea in a form understandable to them, it might as well be both invisible and useless to them.

This is in spite of the fact that such an idea may indeed be useful to them in the long term, however it’s understandably quite difficult to perceive the long term (even for smart people). By long term, I don’t mean a handful of months or a few years, but rather decades. This is probably why the only successful predictors of the long-term future have been from inventors themselves.

So the right questions to ask would be related to whether or not writing, social media, video, photos, etc. are the right way to communicate long-term ideas in the first place (this note is ironic in that sense). In my view, given how each of these tend to lack context of some kind (eg. Writing lacks visuals, visuals lack precision, social media lacks any context whatsoever), I would say there’s quite a bit of work to be done here. We need to make the invisible visible, otherwise the rest of the world doesn’t care.

That being said, there’s now more interest than ever in creating better editors and tools for this new paradigm. T3Code and cmux are very recent attempts that come to mind, and I’m sure more in a similar vein will come about in the future.

In past notes, I’ve also not been favorable towards TUIs despite using OpenCode and Ghostty daily. I should rephrase my sentiment I suppose. What I dislike about the terminal as a basis for everything is a lack of feedback when typing commands, or in other words “flying blind”. If a TUI can offer such feedback, or otherwise be useful in the same ways as a GUI, then for all intensive purposes it’s essentially the same as a good GUI. That being said, if a GUI offers no such feedback either, it’s essentially a terminal (like ChatGPT). So really, the bigger idea is exploration and learning through real-time feedback (game design emphasizes this point).

However, I still don’t think any existing solutions are approaching the mark for what is actually needed. From the first note in this series, the “collaborative programmable whiteboard-like space approach” with arrows to represent relationships is still something I think could be a step in this dirction if it was able to be a communication system between various different apps. Tools like cmux also show a hint in this direction as well by not imposing any specific app in their layout/notification system. That is, there’s no “built-in” agent harness, and you can choose to use a dedicated one like OpenCode, Claude Code, or Codex depending on what you prefer alongside any other TUIs/CLI tools you use. Rather cmux acts as the binding force between those tools.

In the short term (ie. 1-5 year timescale, real “long term” IMO is decades), I think this direction is better than monolithic apps that bake a bunch of features into them. That is, if we’re not talking about any escaping the 14-inch folding rectangle on my lap kinds of approaches (AKA a topic for another time), which is why I had to clarify that I meant “short term”.

That being said, I think we can do better than traditional side-by-side layout when it comes to having multiple apps on screen. The relationional arrows from my whiteboard approach in particular are a concept borrowed from project Xanadu. Notice how the arrows are not unidirectional, and instead represent a 2-way binding between parts of documents. I think this aspect in particular could be used between apps to mention related content. This later particular image is of a 2007 prototype called Xanadu Space, which does the Xanadu UI in 3D thus adding more depth.

Another aspect encoded in the first design was realtime feedback from each and every action. While of course, this was an idea largely developed in the 60s and 70s (especially so for the idea of live programming), some of Bret Victor’s work pre-Dynamicland (circa 2010-2013) is quite infamous for this. Though Dynamicland has naturally expanded upon it into the physical world. Regardless, my favorite talk to this date has some examples of this in the digital realm. I should also mention that the reason for the talk being my favorite is not because of the demos that show “live programming”, but rather the second half which goes into a lecture on the meaning of work. Suffice to say, I would like to stray away from such spiritual topics in this note.

One of the biggest issues that I’m seeing with much of the ongoing work towards better tools is the idea that a single app that becomes the next editor is the ideal end-state. This is quite barbaric and competetive over collaborative in my opinion. For me at least, it’s a zero-sum game if only one or a handful of monolithic tools “win” and the rest become irrelevant.

This is what happened with the previous generation of text editors before the AI boom, and as a result no new radical UI innovations came for decades until the AI boom happened. For the established editors such radical innovation was too risky, and new players couldn’t easily enter (until AI) because the incumbents already had the market share. Also getting people to change their workflows is incredibly difficult, even if it’s to something better. The AI boom is the only reason that some (many outside of traditional tech hubs are almost entirely ignoring this) people are more open to change, but it will not last forever.

I would prefer that we are not locked with a handful of standard and stagnant editor UIs for the next 2 decades because no new competitor can easily break established workflows. Now is the our window to break much of the traditional application silo as we can. It’s true that most apps will remain monolithic, because breaking the silo requires a complete mindset shift that I’m not sure is easily possible at scale in a time frame of a few years. However, we can at least make things better than they have been in the past.

A great example of this kind of system from a UI perspective can be found in Alan Kay’s tribute to Ted Nelson. In today’s world, one would need to write or generate thousands of lines of code to make a dedicated app for what is seen in the demo. However, nearly zero new lines of code need to be added in a Smalltalk system to achieve the same functionallity.

Fun fact, the entirety of Smalltalk-76 was only ~10,000 lines of code. Not because the programmers were necessarily Carmack-tier, or because Smalltalk was such a great textual language. Rather, the system was designed such that few lines of code needed to be written in the first place. There was no separation between the GUI and programming itself, just dragging things around constituted “programming”. This was in 1976 by the way.

The key idea that is shown in the Smalltalk system from Alan Kay’s tribute is that there is a way for each object to communicate with each other without direct knowledge of their existence. This way, one can focus on building “separate apps”, but still have them all communicate together in one cohesive and hyper-personalized experience. UNIX is somewhat an example of this in terminal-land, but an ideal solution is more for traditional UIs (and even TUIs). Fun fact, an ancient (2005) Bret Victor paper actually describes what such a communication system could look like for GUIs. However, I’m sure we can make a more advanced one in today’s world that isn’t named MCP. MCP is only an agent protocol that has to be conciously invoked by an agent, where the agent has to know the tools available to it. We need something much more event-driven, where no 2 apps need to have explicit knowledge of each other in order to communicate.

One could argue that OpenClaw is fulfilling this “communication” need between different apps, but if that were the case we wouldn’t be having this discussion. OpenClaw is more focused on “doing things” rather than “understanding things”, which is why most of us are still writing code with tools like Codex, Claude Code, Cursor, OpenCode, etc. What I actually think we need is the inverse of OpenClaw, which implies an explicit focus on “understanding” (which in turn would aid us in the “doing” part).

This would imply less apps that bundle an agent panel, diff viewer, browser, terminal, code reviewer, etc. into 1 monolithic app. Rather, those would all be separate (and possibly developed by separate individuals and teams), but in turn would focus more efforts on communication with each other.

To give a simple model of thought, imagine if OpenCode could directly communicate with whatever browser you’re using, no matter if its Zen, Firefox, some chromium browser, Safari even (lol Apple would never), etc. and vice-versa? Today, either OpenCode would have to implement a browser feature (not happening), or all of the browsers would have to implement a coding agent (more likely, but still likely not a priority feature).

However, for the case of OpenCode implementing a browser, what would it look like? You wouldn’t just be able to pull in your favorite browser because it cannot exist as a part of the OpenCode monolith.

Similarly, what does a coding agent look like in the browser? Sure, you can use the appropriate agent SDKs from Codex, Claude Code (maybe?), OpenCode, etc. but what if you wanted to use T3 Code as the agent UI for this hypothetical browser integration? You wouldn’t, because T3 Code is a separate app with it’s own design goals and not part of the browser monolith.

One quote from that ancient Bret Victor paper since for some reason I thought of bringing up a 20-year old paper of all things.

Monolithic systems are bad for software providers. In a healthy marketplace, whether of groceries or auto parts, individual providers offer components which combine with others for a complete solution. A small software provider could provide an excellent email program, or an excellent map. But only a large corporation has the resources to develop an integrated package. Once small companies can’t compete, progress stagnates.

Thinking about grocery stores for a second, of which there are many sellers within the store. While some big name food brands exist that are household names, many enjoyable ones aren’t. Furthermore, there’s no popular food brand in a grocery store that owns a monopoly on breakfast, lunch, or dinner. That is, you can make such meals by combining different food products from different brands. I don’t think the same can be said for software today, since each app wants to drag you into its own world entirely.

Is this to suggest that monolithic applications that have a more cohesive end-to-end experience by damned for eternity? Not necessarily, and if the universal app communication system struggles to model a cohesive interaction between 2 distinct applications, this will be necessary. However, if all the monolithic app does is provide a horizontal layout with a browser/editor tab next to an agent tab with no other visual interactions between the tabs, I wouldn’t exactly call that a cohesive end-to-end experience either.

I suppose, if there’s anything to build, it would be the universal communication mechanism. This is definitely something I’m interested in, but the sheer logistics of necessary adoption suggest that it will require more than just a single guy with agents and occassional free time.

Sure enough many (potentially millions) of us are in the same boat of having agents and occassional free time. It would be quite a waste if only a handful had the opportunity to be on the “winning team” that makes everyone else’s contributions irrelevant. We don’t need the next killer app made by a handful of people, we need the next killer effort contributed to by everyone.

First, for anyone getting into the topic of EBNF, just know that while there are some formal syntax definitions, the ecosystem of parsers is largely just imeplemented in a “freeform do whatever feels right” kind of sense. To this end, I’ve seen some parsers use ordered choice instead of unordered choice for alternation, PEG-style syntax, random regex/epsilon/character-class extensions. That is, there is literally no definition for what a valid EBNF syntax is, and the only thing I can say is that it depends on the parser you’re using.

In one sense, my idea of relativeness makes sense here. A parser should pick a format most optimized for its needs. On the other hand, we also have to ask if we need all of these syntax variants floating around? CFGs are a stable formalism that are a product of computer science research, so in this case I think it’s worth having a unified standard.

Some notes:

• LLMs generally use GBNF to constrain outputs.
• The W3C standard seems to be pretty common.
• Almost no one uses Wirth syntax except for the Wikipedia article on it.
• ISO EBNF is also a pretty popular standard.
• Almost all parsers extend pure BNF in various ways.

I’m currently working on a Swift library to make grammar definitions easier and flexible. You’ll be able to define CFGs in a simple and standard formal syntax using strong types, proper formalisms of CFGs, result builders, and potentially macros.

// Small Sneak Peak (not finalized)

let grammar = Grammar(startingSymbol: .root) {
  Rule(.root) {
    Choice {
      Ref("second")
      Ref("first")
    }
  }

  Rule("first") {
    "a"
  }

  Rule("second") {
    CharacterGroup("A-Z0-9")
  }
}

let language = Language {
  Union {
    Reverse {
      grammar
    }
    KleeneStar {
      otherGrammar
    }
    ConcatenateLanguages {
      l1
      l2
    }
  }
}
        

Then you will be able to generate the syntax for whatever grammar spec you need, including upcoming CFG support in Cactus (which will be backed by XGrammar and GBNF). Note that since there are so many syntax variations, and tools that make up new syntax, I cannot realistically support everything. That being said, you can definitely expect a wide range of supported formats.

// More Sneak Peak (not finalized)

let formatted = try grammar.formatted(style: .w3cEbnf)
"""
root ::= second | first
first ::= "a"
second ::= [A-Z0-9]
"""

let formattedLanguage = try language.grammar().formatted(style: .wirthEbnf)
// GBNF is also supported at the time of writing this...
// ISO EBNF is also planned...
// So is a generic BNF format with many syntax options...
        

Additionally, the formatted function has to be throwing due to the disparity of expression support between different formats. The library tries to convert expressions for each built-in formatter if possible, but admittedly some expressions (eg. negated character groups in Wirth) cannot be converted. As a result, a formatter is allowed to throw if it encounters an unsupported expression.

Parsing is also something I would like to add in the future. However, it’s not a priority for release at the moment.

Update: https://www.grammarware.net/text/2012/bnf-was-here.pdf

Since Gemini doesn’t seem to be optimized for agentic coding workflows, the only remaining options left are open weight models. Particularly, GLM, Kimi, Minimax, and Qwen have the edge in this space.

I haven’t bothered much with Qwen outside of using edge versions of it as a testing model for swift-cactus. Generally speaking, Qwen models aren’t generally that fast from my experience, at least on the Cactus engine. Furthermore, I don’t hear much talk about Qwen’s larger models overall, so I felt pulled in different directions.

That brings us to GLM 5 and Kimi K2.5 which have gotten a lot of attention. Having tried these models briefly, they both work very well, take their time, and can get most tasks done that codex can accomplish. However, I have Codex already, and I don’t need a cheaper and slightly worse overall version of it. Remember that I just want something that can perform simple things fast and well.

This leaves us with Minimax M2.5. While I wouldn’t say it’s output is as strong as GLM 5 and Kimi K2.5, it’s definitely not that far off, and can generally solve the tasks I need it for. Furthermore, it’s model size is quite small, only ~230B params compared to ~750B for GLM 5 and ~1.1T for Kimit K2.5 by comparison, which means it’s often faster given equivalent hardware. The reason I like it is because it isn’t trying to be a cheap Codex or Opus, but rather be it’s own thing entirely. It has the exact opposite qualities compared to Codex, while still having good enough output quality, which is why I think it complements Codex very well.

Furthermore, from a subscriptions/usage standpoint, it’s also very generous if you go past their $10/month plan. I actually think that most people could seriously get by on their $20/month plan. Even when running it continuously through my recent entry into ralph-looping, I found that I never came even close to hitting any usage limits.

That being said, Minimax is no Codex or Opus, and you will have to significantly hand-hold the model, especially compared to Codex. Therefore, I still recommend the $200 or even $20 Codex tier above all else first, and an open-weight model like Minimax second. AFAIK, the $20 Codex tier is actually a lot better than the $20 Claude tier for many. I also think a $100 Codex tier would actually do quite well for many since it’s quite difficult to hit the limits on the $200 tier, which therefore means one is theoretically overspending on inference (not counting subsidization).

Another question one may ask is why not just get a subscription that gives you access to all the open-weight models like OpenCode or Synthetic? My reason for this is because OpenCode will give generally give free-access to open weight models for a limited time, which means that I will always get to at least try them without paying. Secondly, I’m not interested in the other openweight competition for now. Perhaps NVIDIA’s Nemotron model will change my mind, but for now I haven’t had any issues with Minimax itself.

One interesting Alan Kay (or perhaps Xerox PARC) observation with regards to performance is the idea that the bar is the speed of the human nervous system. That is, as long as the human nervous system doesn’t notice delay, then all is well and good. For graphical contexts like those worked on at PARC, this makes a lot of sense. However, LLMs are also often paired with graphical contexts, and thus the human nervous system becomes the bar for speed yet again.

First, there are generally 2 kinds of speed metrics that we need to worry about for inference, prefill and decode. Prefill relates to forwarding tokens and building up the KV-cache, whereas decoding uses the KV-cache to generate output tokens. Generally speaking, decode is the more interesting measurement when we think about tokens per second, and especially so in the context of user interfaces. Prefilling can be hidden in the background for many applications, of which such background work can be used to significantly reduce latency to the first decoded token.

Secondly, we need to establish a base rate of speed for the human nervous system. Movies use 24 FPS as a baseline, but modern interactive user interfaces use 60-120 FPS. That being said, a user-interface is often still useable even if it dips slightly below that range, as long as the nervous system still perceives the interactivity as motion. If we use 60 FPS as a base rate, that leaves us about ~16.67ms between each frame.

Third, we need to consider what it means for a model to emit a token, and for a frame to be drawn to the screen. Each token or frame is generally used to build up a larger communication of some kind, such as the words of an essay or the strokes of a drawing. Of course, the most important substantial transfer in any communication is meaning. Without being able to convey the meaning of something, communications become misunderstood.

What this all means is that we have ~16.67ms to emit meaning in any given scenario. Translate that into 60 TPS, and we’ll see that such a speed is already relatively common for LLMs today. Therefore, we already have the means of beating the nervous system from a raw throughput perspective.

However, let’s take a moment to note the difference in output between graphics and LLMs. LLMs generally emit text, where as graphics emit pictures. This creates another bottleneck for LLMs, because human minds absorb meaning from pictures much faster than words. Today’s diffusion models are of course obviously not up to that level of speed, and it’s likely they won’t be for another few iterations of Moore’s Law (Perhaps one can buy their way into the future here similarly to Xerox PARC).

Therefore, if we want to communicate in pictures today using an LLM, our best approach from an engineering standpoint is to translate the output tokens into pictures. However, once we start thinking in terms of pictures, we stop thinking in terms of TPS, but rather a rate of meaning per token. That is, how much can a token translate to the right picture? Further, we only have ~16.67ms to do so as a base rate.

So we can see that changing the medium of communication itself brings us different design and necessary throughput constraints. Pictures as a medium have a higher throughput than words for certain kinds of meaning, but words often win when it comes to precise formal meaning. Regardless, if the point of all of this is optimization, then perhaps “meaning per second” should be the optimization slogan.

Additionally, a model I’ve been playing around with quite a lot recently is Minimax M2.5. A TLDR for why I like it is that it’s not trying to be a cheap Codex or Opus like GLM and Kimi, and I wanted something that wasn’t Codex for certain tasks. Regardless, this was the model I decided to use for the sake of doing so.

The tool itself was a straightforward CLI to fetch some posts from various data sources (Reddit primarily), and feed the content into LFM2-8b-a1b running locally via the cactus engine to produce suggestions and a report regarding the validity of a user defined hypothesis. Additionally, qwen3-embed-0.6b was also used as an embedding model for both vector indexing and aiding with categorization for posts. I also used this chance to play with Wax, a single-file vector database written in pure Swift, and was the primary persistence mechanism of choice. Also if it wasn’t obvious, Swift was used as the programming language.

Overall, the task was completed with about ~4-5 hours of HIL ralphing, though improvements can certainly still be made to the experience of the tool itself. Therefore, the experiment was certainly a success from the standpoint of being able to produce something that is functional.

My overall idea itself was to start in one session by creating a plan and detailed implementation specification document with the agent. This specification was one large markdown file because I wasn’t trying to build something incredibly complicated. Then, I ran another agent session which broke down that implementation spec into 17 distinct tasks listed in another document. Each task included, a title, a description, completion criteria, and a list of tasks it depended on. Since we are doing Ralph, the agent got to pick the order of task completion. (It went mostly sequential with a slight exception towards the later tasks where it actually backtracked for a bit.)

Of course, my thoughts on general software development techniques are generally mixed, and Ralph is no exception to this rule. Generally speaking, over dogmatic focus on patterns instead of systems is how you get complexity, so we have to keep that in mind at the end of the day. Nevertheless, here’s a somewhat comprehensive list that reflects my experience.

• The code quality was absolutely terrible.
  • Before listing individual cases here, I should mention that this is a tool that will be thrown away in a few weeks time, so the quality isn’t that important.
  • @unchecked Sendable everywhere.
  • Loading the model weights from scratch every time embeddings or inference was needed, instead of keeping the weights in memory.
  • Weird Java-like patterns that don’t make sense in Swift.
    • Getter/Setter methods was common for some reason.
  • Writing tests for obvious things, like compiler-synthesized Codable conformances.
  • Not using actors properly, and preferring NSLock when an actor would make things simpler.
    • In one case, it tried to use a serial dispatch queues within the actor itself to serialize work. Even worse, it would use queue.async, and await values via withUnsafeContinuation. I’m not making this up…
  • Coupling generic logic with domain logic.
    • In one case, it wrote a cosine similarity method that was private in a class. Generally speaking, I always try to extract such generic methods into a reusable place even if they are only used once.
  • Etc.
• It did a decent job separating interface from implementation via protocols.
  • That is, it was able to create mocks of things for testing which was nice.
  • While it did create protocols, it often named/coupled the protocol requirements to the implementation itself which isn’t ideal.
• It completed the work in a very short period of time.
  • ~8k LOC in 4-5 hours of work isn’t bad, the same amount of code would’ve taken me at least a solid week of dedicated effort.
• It did a decent job of implementing the isolated and mundane things.
  • Reddit API Client
  • Wax memory wrapper
  • Cactus embedding provider for Wax
  • Domain model types/simple structs
  • Persistence
  • Configuration reading
  • Etc.
• It did a terrible job of implementing the main tool loop.
  • For some reason, it would avoid actually writing the part where the LLM was called in the main loop of the tool.
  • Additionally, it avoided integrating in all of the isolated modules in the code base, preferring to use mocks in the production code.
  • Suffice to say, I had to break HIL Ralph and take over manually via normal agentic coding to get it to actually build the main loop of the tool.

What did we learn here?

For one, I could probably be a better spec writer, and use Codex instead of Minimax. Also, I’m sure with more practice the overall output will become better regardless of the model choice. What I did certainly find was that many trivial modules can easily be ralphed with very little effort, however the fun parts of building are where breaking out of the loop seems to be a better idea.

Ralph gives more control to the agent than you. In normal agentic coding, you can generally get the agent to write decent code if you direct it well. (Though it will still often miss critical performance details, and make ~2-3 small mistakes per 1000 lines). However, the quality seems to go way down when you hand full control to the agent. This is ok if you limit its crappy output to a series of well-defined interfaces in your spec, so make sure you nail your higher level design decisions.

Overall, I once again think of this as a technique that’s great in the sense of graphic design to art. That is, it can get stuff done like a graphic designer, but it lacks the ability to produce incredible art.

-- Minutes to Read

Swift Concurrency seems to be one of the hard Swift topics, and one thing we can do in Computer Science is to continue pushing hard problems away to another layer of abstraction. Naturally, we can do that with Swift Concurrency too!

This isn’t an article about understanding isolation or Sendable. I assume you already are somewhat familiar with basic Swift Concurrency concepts. Rather, I more or less want to outline the pain points around those concepts, and demonstrate a technique for pushing them to the edge.

TLDR Example

Since this article naturally draws out the explanation to include many details, I’ll give a TLDR code example right away. That is, non-Sendable types are much more flexible than Sendable types. Sendable types require either locking or actor isolation overhead, so it’s much easier to defer such mechanisms as long as possible.

// ✅ By making CactusModel non-Sendable, we can reuse it 
// in any Sendable type whether it's an actor, or class with a lock.

struct CactusModel: ~Copyable {
  // Non-Sendable Core...
}

final actor CactusModelActor {
  let model: CactusModel

  init(model: consuming sending CactusModel) {
    self.model = model
  }

  // Sendable Shell...
}

final class SomeState: Sendable {
  struct State {
    let model: CactusModel
    var otherState: Value
  }

  private let state = Mutex(State())

  // Sendable Shell...
}
      

With that out of the way, now we can focus on dragging out the explanation from first principles. However, I would first like to look at a corollary idea, and where this article gets its naming scheme from.

Functional Core, Imperative Shell

The name of this article comes from the “Functional Core, Imperative Shell” idea. If you’re unfamiliar with “Functional Core, Imperative Shell”, here’s a simple code example to illustrate.

struct Item {
  // ...
}

// ❌ Bad, mixes IO (side effects) and business logic.

func processBad() async throws {
  let items = try await loadItems()
  let transformed = items.filter { /* ... */ }
    .map { /* ... */ }
    .reversed()
    .dropFirst()
  try await save(transformed)
}

// ✅ Good, separates IO (side effect) from business logic

func processGood() async throws {
  let items = try await loadItems()
  try await save(items.transformed)
}

extension Sequence where Element: Item {
  var transformed: some Sequence<TransformedItem> {
    items.filter { /* ... */ }
      .map { /* ... */ }
      .reversed()
      .dropFirst()
  }
}
      

By separating out the collection transformation, we gain more flexibility. That is, we can choose to reuse the transformation logic regardless of how the underlying data is persisted, or even write isolated unit tests just for the transformation logic. In general, once IO or side effects are introduced to your code, it becomes much less flexible, so it's best to keep those isolated from the core to maintain flexibility.

In the above example, the transformation logic is what we call the “functional core”, and the IO is what we call the “imperative shell”.

Async Makes Things Harder

Generally speaking, once async/await is required to call a method, things get much harder. If you’re in a synchronous context, you’ll either have to create an unstructured task, or mark the enclosing method as async.

func foo() {
  // ❌
  await someWork()
}

// ✅ Either approach compiles, but aren't always ideal

func foo() async {
  // 🔵 Delegates async responsibility to whoever calls foo
  await someWork()
}

func foo() {
  // 🔵 Completely hides the fact that async unstructured work has been started
  Task { await someWork() }
}
      

Furthermore, you open a whole can of worms regarding Sendable once you start getting into concurrency land. When it comes to dealing with non-Sendable types, you have to take special care when passing them across actor isolation boundaries, otherwise the Swift compiler will hate you.

Thankfully, the sending keyword can help somewhat when it comes to non-Sendable types and tasks. This keyword allows you to transfer non-Sendable values across isolation boundaries, which means that you can use non-Sendable values within tasks.

func foo(value: sending NonSendable) {
  Task {
    // ✅ value is being explicitly transferred into the Task's 
    // isolation context
    let v = value
  }
}
      

However, it doesn't work everywhere. For instance, you can’t use sending to capture a non-Sendable value inside an @Sendable closure.

func badTransfer(
  value: sending NonSendableValue
) -> @Sendable () -> Void {
  // ❌ Capture of 'value' with non-Sendable type 'NonSendableValue' in a '@Sendable' closure
  return { work(value) }
}
      

The reason this doesn’t work is because @Sendable closures are meant to be thread-safe, and as a result may be called multiple times from different threads. Once you understand that fact, it becomes clear why the above code example doesn’t work. The point of the sending keyword is only to send a value to a different isolation context, and nothing more. In fact, the original proposal for sending actually named the keyword transferring at first until it was renamed presumably due to naming conflation with Swift's ownership model and to be more in line with Sendable.

Conforming to Sendable can be Annoying

If we can’t use the sending keyword to get around concurrency issues, the next step up is to conform to Sendable directly. For simple structs, this is trivial because the compiler can infer thread-safety for you. In fact, I personally do this by default whenever I make a new simple struct data type.

// ✅ Trivially Sendable.
//
// I always tend to conform simple structs to Hashable and Sendable 
// without second thought.
struct Item: Hashable, Sendable {
  let fieldA: Int
  let fieldB: String
}
      

However, things get harder when we need to deal with reference types. Any non-final class, or even simple mutable properties will prevent an auto synthesized Sendable conformance.

// ❌ Cannot have mutable properties
final class Item: Sendable {
  var fieldA: Int
  var fieldB: String
}

// ❌ Must be a final class 
// (Subclasses could add mutable/non-Sendable properties otherwise)
class Item: Sendable {
  let fieldA: Int
  let fieldB: String
}
      

Unchecked Sendable

Of course, you can use @unchecked Sendable, but that usually isn’t something you want to deliberately touch because it turns off compiler checking for Sendable. That is, the compiler can no longer offer any guarantees that your type is thread-safe. Think of it in the same vein as force-unwrapping an optional. It’s allowed, but you better know what you’re doing.

I’m not suggesting that you should never use @unchecked Sendable. In fact, if you go deep enough with integrating legacy frameworks, low-level C libraries, or locks, it’s almost certain that you will need to use it at some point. Just make sure you justify yourself when you do so, ideally through a comment next to the @unchecked Sendable conformance.

Actors

Another way to get automatic an Sendable conformance is to convert your type to an actor (or just throw a global actor like @MainActor at the problem).

// ✅ Actors are Sendable by default.

actor Item {
  var fieldA: Int
  var fieldB: String
}

@MainActor
final class Item {
  var fieldA: Int
  var fieldB: String
}
      

For @MainActor specifically, new Xcode projects even make MainActor isolation the default for all declarations. However, if you want a type be usable from multiple isolation contexts, you will have to mark it nonisolated in addition to a Sendable conformance.

nonisolated struct Item: Sendable {
  var fieldA: Int
  var fieldB: String
}
      

On a personal note, I tend not to use default MainActor isolation. At least for me, I like to be explicit when something is main actor compatible, and since I tend to write a lot of thread-agnostic non-UI code in addition UI code, I find it simpler to keep everything consistent and turn off default Main Actor isolation.

Regardless of how you choose to use actors, you’ll be dealing with async/await when you’re not isolated to the actor. As previously mentioned above, adding async just complicates things.

With actors, there’s also more lesser-understood points of conceptual overhead.

• The SerialExecutor protocol allows an actor to customize its execution environment.
  • Useful if you need to run things on a dedicated thread.
• Any non-Sendable type returned from an actor method also requires sending
  • Furthermore, the value returned from the method also cannot be an instance member of the actor, because doing so would make the non-Sendable type present in 2 separate isolation contexts.
• Actor interleaving.
  • Only 1 task can enter an actor at a time, so if a task must await another async method within the actor, it must leave the current actor to swap isolation contexts. This allows another task to enter[^1] the actor in the meantime.
• Actor re-entrancy.
  • Once the original task from the interleaving explanation is done performing its async work, it must re-enter the original actor that it once left to continue execution past the suspension point it previously awaited.
• isolated parameters.
  • This allows one to declare methods external to the actor as being isolated to the actor. Since a task can only be on at most 1 actor at a time, this also means that a function can only have at most 1 isolated parameter.

Avoiding Sendable

Since Sendable brings a lot of inconveniences, we have to ask ourselves the question of how long it can be avoided. In today’s world, the answer to this that we can get quite far with non-Sendable types.

Async Methods in Non-Sendable Types

One of the previous issues with non-Sendable types was the notion of having async methods on them. Invoking them would cause an isolation hop to a non-isolated context, which would produce often very non-intuitive errors.

class NonSendable {
  func work() async {
    // ...
  }
}

@MainActor
@Observable
final class MyViewModel {
  let nonSendable = NonSendable()

  func buttonTapped() async {
    // ❌ Sending 'self.nonSendable' risks causing data races
    await self.nonSendable.work()
  }
}
      

However, today you can use nonisolated(nonsending) to fix this error.

class NonSendable {
  nonisolated(nonsending) func work() async {
    // ...
  }
}

@MainActor
@Observable
final class MyViewModel {
  let nonSendable = NonSendable()

  func buttonTapped() async {
    // ✅ No longer sending non-Sendable to a nonisolated context
    await self.nonSendable.work()
  }
}
      

What this tells the compiler is that work will execute on the isolation context that it is invoked on. In fact, you can even enable this behavior by default through the NonIsolatedNonSendingByDefault feature.

However, it's also worth noting that this theoretical example is a textbook definition of “NonSendable core, Sendable Shell” since the NonSendable class acts as the non-Sendable core and MyViewModel the Main Actor bound Sendable shell. Now, we can look at some more practical examples involving wrapping a C library that I’m involved in semi-regularly.

Practical Example: Swift Cactus

In particular, say you need to wrap a C library with weird threading semantics, but need to integrate it with Swift Concurrency. For this example, I’ll wrap the cactus inference engine, which is a highly energy efficient, ARM optimized, and performant alternative to MLX, ONNX, llama, etc. that runs primarily on the CPU. I’m not going to make a sales pitch for the engine in this article because I want the focus to be wrapping it properly from Swift. In fact, the principles in these code examples can be found in the swift-cactus package that I actively maintain.

The Cactus FFI exposes many functions, so I’ll only include heavily simplified signatures of some of the basic FFI functions for simplicity. Just note that in reality the library supports many more advanced features, but the underlying principles of the Swift API design are the same.

// Loads model weights.
CACTUS_FFI_EXPORT cactus_model_t cactus_init(
    const char* model_path
);

// Deallocate a model.
CACTUS_FFI_EXPORT void cactus_destroy(cactus_model_t model);

// Stops an active ongoing generation for a model.
CACTUS_FFI_EXPORT void cactus_stop(cactus_model_t model);

// Runs inference for a given model, and outputs the 
// result into response_buffer.
CACTUS_FFI_EXPORT int cactus_complete(
    cactus_model_t model,
    const char* messages_json,
    char* response_buffer,
    size_t buffer_size
);
      

cactus_model_t itself is an opaque pointer, but under the hood it’s represented as a struct in C++ that looks something like this. (Once again, very simplified from the actual handle[^2].)

struct CactusModelHandle {
    std::unique_ptr<cactus::engine::Model> model;
    std::atomic<bool> should_stop;

    CactusModelHandle() : should_stop(false) {}
};
      

As we can see, we have an atomic for whether or not ongoing inference should stop. Furthermore, the Model class in the C++ engine does not use any locks under the hood. This puts us in a weird case where cactus_stop is safe to call from different isolation contexts in Swift, but cactus_complete is not.

However, LLM inference is also incredibly expensive, and certainly you should not be doing it from the Main Actor. Yet, only exposing the model API behind an actor would limit the Swifty wrapper to purely async contexts.

As such, I think this is a perfect case for non-Sendable core, Sendable shell. Since we’re wrapping a pointer from an underlying C library, we can use a non-Sendable and non-Copyable struct to ensure ownership semantics when passing the model around. Then, we can create a wrapper CactusModelActor that wraps our non-Copyable type to grant proper built-in Sendable and background execution to the inference engine.

struct CactusModel: ~Copyable {
  private let pointer: cactus_model_t

  init(pointer: consuming sending cactus_model_t) {
    self.pointer = pointer
  }

  init(path: URL) {
    guard let pointer = cactus_init(path.absoluteString) else {
      throw CactusModelError.failedToLoadModel
    }
    self.init(pointer: pointer)
  }

  deinit {
    cactus_destroy(self.pointer)
  }

  func complete(messages: [Message]) throws -> Completion {
    let encodedMessages = try JSONEncoder().encode(messages)
    let buffer = UnsafeMutableBufferPointer<CChar>.allocate(capacity: 8192)
    defer { buffer.deallocate() }
    let result = cactus_complete(
      self.pointer,
      String(decoding: encodedMessages, as: UTF8.self),
      buffer,
      8192 * MemoryLayout<CChar>.stride
    )
    if result < 0 {
      throw CactusModelError.badResponse
    }
    let data = bufferToData(buffer)
    return try JSONDecoder().decode(ChatCompletion.self, from: data)
  }

  func stop() {
    cactus_stop(self.pointer)
  }
}

actor CactusModelActor {
  private actor DefaultIsolation {}

  private let defaultIsolation = DefaultIsolation()
  private let executor: (any SerialExecutor)?
  private let model: CactusModel

  nonisolated var unownedSerialExeuctor: UnownedSerialExecutor {
    self.executor?.asUnownedSerialExecutor() ?? self.defaultIsolation.unownedSerialExecutor
  }

  init(
    executor: (any SerialExecutor)? = nil,
    model: consuming sending CactusModel
  ) {
    self.executor = executor
    self.model = model
  }

  func complete(messages: [Message]) async throws -> Completion {
    try self.model.complete(messages: messages)
  }

  func stop() {
    self.model.stop()
  }

  borrowing func withModel<T, E: Error>(
    operation: (CactusModel) throws(E) -> sending T
  ) throws(E) -> sending T {
    try operation(self.model)
  }
}
      

As you can see, the actor provides quite a few concurrency specific additions, such as even allowing a custom SerialExecutor to be used. This latter bit could be useful for an application because the inference engine will block the cooperative thread pool for a long time. A custom executor allows you to create a dedicated thread outside of the cooperative thread-pool for inference in your application.

However, because we split the non-Sendable core from the Sendable shell, we could also decide to use the model inside another completely synchronous context. This could include a class with a lock, a non-main global actor, or another actor that bundles various non-Sendable types together. If our needs are simple enough, we could even just rely on region based isolation with sending.

final class LockedModel: Sendable {
  let model: Mutex<CactusModel>

  // ...
}

final actor CactusModelAgent {
  var transcript: [Message]
  var nonSendable: NonSendable
  let model: CactusModel

  // ...
}

@NonMainGlobalActor
final class ModelActor {
  let model: CactusModel
}

func infer(model: sending CactusModel) async throws {
  // ...
}
      

Of course, it is also possible to use CactusModel irresponsibly like this.

@MainActor
@Observable
final class Store {
  // ❌ Really bad idea, inference is insanely expensive and should not be run on the Main Actor
  let model: CactusModel
}
      

However, the flexibility out weights the potential cons of doing something not so bright. Even if someone were to attempt to do inference on the main actor, we could always check if the caller is on the main actor and emit a purple runtime warning discouraging that behavior using a library such as IssueReporting.

Conclusion

Non-Sendable types are actually quite nice to work with. You don’t have to worry about thread-safety, isolation, or any other weird cryptic errors. Even nonisolated(nonsending) will eventually become the default for all async functions, but you can enable default behavior for it today through the NonIsolatedNonSendingByDefault feature.

Further, when you focus on making things non-Sendable, you gain more control over how you want to handle the concurrency behavior for that logic. Whether that’s through local actor isolation, @MainActor/global actor isolation, a class with a lock, or even just through region based isolation with sending, you get that flexibility.

At the end of the day, concurrency is difficult, and it’s why we have tools like Swift Concurrency in the first place. That being said, the simplest form of concurrency is often no concurrency, so I would try to stay in that land for as long as possible.

— 2/25/26

[^1]: I find it's best to think of actor interleaving in the sense that tasks enter actors rather than actors executing tasks. If the task must enter an actor, then it can therefore only be on 1 actor at a time, just like how a human can only be in 1 physical location at any given time. In order to hop to another isolation context, the task therefore must leave the actor, just as a human must leave their current location to go somewhere else. When speaking in these terms, ideas like actor-interleaving and re-entrancy make a lot more sense.

[^2]: At the time of writing this, if you look at the actual source code for the engine, you will find a model_mutex inside the handle struct. However, it isn’t actually used in cactus_complete. As a result, the model pointer still must be treated as non-thread-safe in higher level code that calls into the inference engine.

In my opinion, as someone who also does app development as a career, he’s kind of right if we’re referring to the state of mobile apps today. Most apps that just display simple information from an API are usually not the hardest things to create, and their UIs are genuinely not very inspiring. These kinds of apps can be merged into something like OpenClaw through a good API layer.

That being said, we have to remember what the purpose of a good UI is. That is, a world of exploration, not just another command center to perform some action. Apps with basic charts, graphics, tables, and lists are the kind of cases that OpenClaw can and will be able to handle in the future.

For the kinds of apps that have a more explorative UI, but not a lot of technical complexity (eg. Hardware, Machine Learning, Domain Knowledge, Technical Integrations, etc.) can be replicated by a vibe coder that has creative tastes. Such a vibe coder can also invent a UI specific to their needs, rather than being dependent on someone else’s. This alone has cut many of my side project ideas, because there’s no point in building something commercially if someone else can just vibe code it for their own needs and purposes.

Of course, most vibe coders are not very creative people, and I see this as more of a societal issue than an inherent skill issue. Additionally, most normies also aren’t going to be vibe coding anytime soon either, and will still be perpetual consumers. This means they would still benefit from an off-the-shelf solution for many things. Though admittedly, this kind of consumption isn’t typically good for improving one’s creative abilities, and in fact it will just continue to stagnate them.

I think the apps that will still be valuable going forward, will have the following 3 traits:

• Trust
  • Every business needs trust to gain customers.
• Unique UI
  • Simple UI elements of today will not be enough here. You need something immersive, contrarian, and that doesn’t fit the chat UI mold.
• Technical Complexity
  • This makes it hard to replicate your app, because this is often the part that vibe coders with no technical knowledge cannot see.
  • Machine learning, Hardware, Domain Expertise, Security, Ecosystems, etc.
    • OpenClaw from a technical standpoint is really an excerise in security, I imagine any good engineer would be able to create its core given the same time that Peter had (and a dedicated vibe coder a very insecure version). Though disregarding security, it’s codebase is ~750k LOC, and it integrates with so many different things creating a larger ecosystem that is incedibly difficult to replicate.

Generally speaking, increasing all of these 3 things in many cases requires going beyond just the app medium, and requires branching out your product further. The point is that you need to make your app hard to replicate via OpenClaw, Vibe Coding, or whatever else. Part of that comes from gaining customers, another from unique interface design, and another from deep technical knowledge.

As for myself, I find that I’m distancing myself more and more from the mobile app development label as time goes on, and agents are starting to accelerate this. In fact, the point of my work is to be increasingly general across any kind of system imaginable, apps just happen to be the current position of my career. I intend to change this as time goes on, even though app development is fun, there’s a lot more work to do outside that realm that’s also a lot of fun.

Ecosystems > Apps

That being said, what does it actually mean to trust someone? For me at least, I like to think of it as an optimization if we strip away any emotional or spiritual semblance from it.

I trust the Swift compiler to produce correct assembly code, I trust Codex to write code according to my directions, I trust my teammates to keep innovating, I trust experts in scientific fields to give accurate information, etc. All of these things can go wrong, and I could learn to do each one of those tasks myself if I wanted, however it’s just more optimal for me not to.

That being said, trust is a very greedy optimization, and how trust is obtained is very different from the implications of the optimization. For instance, on a societal level, there’s a growing distrust in experts, but that trust is merely transferring to another class of experts (ie. Influencers). Influencers often gain trust by leveraging the idea that “the other side” is completely delusional in some form. This idea of “the other side” is actually a flaw carried over from nearly every society in history, which is why it’s one of our Human Universals.

Looking at the experts case, we see that many people can only rely on experts for basic scientific information. This itself presents a problem, because those same people have to vote representatives into office who make decisions on scientific policy. Often, those representatives lack the scientific knowledge themselves, and by necessity they’re also forced to trust an expert.

This is massively inefficient in the same way that scribes had to do the writing for everyone in ancient times. People had to trust that the scribe would translate their ideas into writing properly, which once again is a process that could go severely wrong. Once society embraced universal literacy, business, commerce, and culture could evolve as a result.

In my opinion, the same needs to happen with many scientific fields, and most definitely systems thinking. It would be much more convenient for ordinary citizens to design their own systems and experiments for their needs rather than trusting another individual or organization of experts to do it for them. Something-something scribes are only necessary in an illiterate society, and that’s why insurance is a powerful business model that chains many people.

Of course, that answer evades directly addressing the current realities of programming in most languages today, and most others I’ve asked this question to give the more typical answers. That is along the lines of: “Good data structures make the algorithm obvious” or “The algorithm itself must use the data structures efficiently”. These typical answers are naturally something I disagree with. Picking the right data structure doesn’t mean the algorithm will form itself, because 2 separate implementations will use the data structure differently (with variances in regard to efficiencies). Static bits in memory just doesn’t maintain “meaning” well enough to scale.

For the record, I’m not only referring to basic algorithms like simple sorts where there’s always a deterministic answer (in terms of correctness). Machine learning is also something that one would consider an algorithm, but its output is almost always non-deterministic. Though truth be told, if we look at raw performance in terms of latency, even the simple sort is non-deterministic because it will run faster or slower on the CPU for any given run. In such a manner, we can say that the more non-determinism, the more chance of the meaning varying.

If you wanted to kill someone via sending a package in the mail, which option would you pick?

• Send them a bomb that explodes in their face as soon as the package is opened.
• Send them the parts that make up a bomb, and hope they assemble it themselves.

Don’t ask why I picked this example of all things… It was funny to run by a few colleagues.

Obviously, no terrorist is going to pick the second option, but the second option is rather what we decide to do today in computing.

When we look at inefficient or incorrect implementations of even simple algorithms, we’ll also find that they tend to pick the second option, rather than the more direct first. Either the parts take extra work to assemble which degrades performance, or the parts are assembled incorrectly. So “picking the right data structure”, or rather the right meaning of information has profound impacts on performance.

Now let’s talk about general human to human communication a bit. Poor communication causes incorrectness and inefficiences because either the wrong work, or extra work is performed that isn’t necessary. Generally, this is caused by poor preservation of “meaning” between the communications, so in other words picking the wrong representations.

If meaning is the center of programming, as Alan wanted to portray as a general slogan in his answer, then certainly meaning encompasses data structural representations, but also representations that are relative to something. However, If we look at general purpose programming languages today, that relativeness (I’m avoiding the term relativity thanks to Einstein) is lost to general data structures and algorithms.

What do I mean by relativeness? A simple model of this is a DSL, but really static DSLs are also quite weak. If something is to be truly relative, then it needs to be dynamic.

Take your inner social circle, and for simplicity your English speaking inner circle. Even though English is used as the DSL to speak with each person, you vary the form of English you speak with each separate person. These variances are where relativity is formed, and it is formed dynamically as you continue to speak with the person. Of course, the reason you form these variances is to optimize the manner in which you speak to the other person.

Why do we write pseudocode? In today’s agentic/LLM driven landscape, I’m going to expand the term pseudocode to include prompts that are intended to generate code.

It turns out that pseudocode is easy to write because we can keep its representation quite relative to its goal, rather than to a general purpose language. If we didn’t, the general purpose langauge would impose its constraints on the pseudocode, causing it to lose meaning in the grand scheme of things.

Of course, we also have to understand that the machine itself has its own relative representation for executing process, that being machine code. However, for us humans its quite hard to derive any sort of meaning from machine code, at least in our overall understanding of the process it represents. Obviously, this is why we have compilers that take languages more relative to us, and translate them downwards.

So really, the optimization has to be relativeness. The more relativeness, the easier to preserve the meaning and therefore efficiency of process.

First and foremost, my biggest concern is systems design, and the way in which people think about systems. The second of those is what I want to elaborate on in this note, because the idea of that point is to create mediums that enable better thinking.

Making people think better requires giving them framework for thought, most often that is a typical GUI, but it also concerns the design of frameworks in code. Rethinking Reactivity by Rich Harris is probably my all-time favorite frontend talk, and in it he really pushes the idea that frameworks are tools for your mind, not your code.

But let’s get back to traditional GUIs for a moment, because that is the interface most people use for technology. Take Calendar apps for example, of which we often claim as a “productivity tool”. Why is it so productive to put events on your calendar? Really, it’s because the calendar’s UI allows you to layout your daily events/schedule in a way that allows you to come to an understanding about them. This understanding is what makes you more productive.

When you use a calendar, you think a certain way. Likewise, when you use a coding agent, you also think a certain way. When you talk to someone, you think a certain way about your language and person you’re talking to.

Doug Engelbart saw this trend in particular, and spent many years researching various types of interfaces that would augment one’s thinking instead of degrading it. In particular, he extended this idea to groups of people more so than a single person, but commercialization ultimately chose the path of the individual.

Likewise, I’m interested in interfaces that are malleable, almost like spoken language. For instance, while you may speak English to 2 separate people, you will not speak the same form of English to both of those people. As you further converse with someone, the language you uses will change and adapt as more information is understood about the person. English is used as the base, but it is mutated at runtime (ie. In a conversation) to suit the needs of the receiver.

In other words, this mutation of English is a dynamic user interface, one that adapts based on the context. It turns out that we have technology that can: live in the user’s context, speak English fluently, runs fast on consumer hardware, and can pattern match far better than humans. In case you’re wondering, I’m talking about running edge models and inference.

All in all, edge models and inference are a technology that I believe can power the idea of a dynamic user interface. One might ask, why not cloud models/inference? These models are far bigger and knowledgeable than edge models, so one has to ask why I would accept potentially degraded performance.

My answer to that is more so an engineering answer from an engineering standpoint, in which I would say that the internet is too flaky and slow for the real-time component of generating UIs in response to quick user interactions. Edge models can easily hit generation speeds of >100 tps on the CPU alone given the right configuration, and are not bottlenecked by network concerns. Additionally, it’s best if they operate directly in the user’s context such that we don’t have to send sensitive data across the network.

So yes, privacy and offline support are great reasons for why I’m interested, but only from an engineering standpoint. That is, I see them as more of an implementation detail rather than the ideals themselves.

One of the things I’ve realized is that most developers and technically enthusiastic users, is that they expect the output of edge models to be on par with GPT-5. Ok, maybe they don’t think that way directly, but certainly my conversations have shown hope for being able to use edge models for the same kinds of applications as cloud models.

To an extent, this opinion is valid. I do believe that most of us developers are throwing the biggest models at every problem (see Opus Spam), when smaller models, or even just basic classifier models will do. However, you’re not going to get good results attempting agentic coding with a model that only has ~3B parameters and a 4K token context window (the primary agentic coding models have at least 100B parameters and and 150k token context length).

I keep hearing hopeful statements for this year’s up and coming WWDC in which we’ll somehow get an edge model on par with the offerings from the big AI labs. Unfortunately, that will likely not happen, at least on the current generation of hardware.

That being said, I think edge models have lots of unique power over cloud models besides the usual privacy and offline statements. One of the things I haven’t talked about publicly yet, is the idea of doing dynamic user interfaces that adapt in real time as a user uses an application. Some may call this “Generative UI”, and there’s even an SDK called Tambo for this, but this SDK misses the main ideas of what I have in mind (In future writings, you’ll see that real dynamic UI is much more than merely tailoring the UI to each user based on a prompt).

I wouldn’t try to use a cloud model for dynamic UI because of either network latency/reliability or because inference speeds are too slow. It’s not uncommon for edge models to reach speeds of over >100 tps even just running on the CPU directly. The network issue is the bigger problem here, because even inference speeds of >1000 tps mean nothing if the user’s network is down.

Another thing to note is that edge models can defeat the bigger cloud models in some tasks, that is if you fine tune them. Any application that seriously uses edge models should be using fine tuned models, and I think this is a hole in the space that should be addressed from available tooling. Most developers are completely unfamiliar with the concept, and would rather be building feature instead of LoRA adapters.

Lastly, one other big idea is remote control. Since edge models run locally on the client, the system prompts are also going to have to be present on the client. However, a hard-coded client-side system prompt that’s dangerous will be incredibly hard to update, especially if you’re deploying to the App Store. Once a prompt is hard-coded on the client, it remains forever, so for that reason it’s ideal to have your app check for system prompts updates at runtime such that you can deploy new prompts without going through app review.

Now of course, you need to ensure that you take appropriate measures to prevent MITM attacks from injecting bad prompts on the client. Prompt injection still is a security problem at the end of the day.

Additionally, observability is also an important aspect. Particularly, you’ll want to address the basics of detecting things like output speeds, confidence thresholds, memory usage, etc. on a per-prompt basis. However, good observability should also embed safety, and therefore act as a NORAD in order to detect warning signs of things going catastrophically wrong. (eg. A system prompt that’s doing more harm than good to a user.)

I’ll have more to say on this topic in future writings. At the very least, edge models are likely to be used as the implementation driver of a lot of my upcoming design work, which is why I’m interested in them.

For lots of things, this is great, however I’m concerned about how much this impacts overall systems understanding. If you have an agent one-shot a major feature in a serious project, even if it works, is that really a good idea for long term maintenance?

Of course, for throw-away prototypes or one-off vibe-coded things, this isn’t really much of an issue. My concerns are more related to dealing with larger and more complex systems that can’t simply be vibe-coded with a taking on a huge liability risk.

Now, anyone who’s worked in an engineering team in the past has to constantly interact with and review code they did not write. Often, you will have to make edits to code that you didn’t write, so most code needs generally would need to be written in a manner that allowed anyone to jump in and figure out what was going on.

This is far more important with agents. In fact, I’m now starting to lean towards having agents write Uncle Bob style small functions because it’s easier to understand the higher level ideas in the code from a quick glance. Since the output stream from the agent goes by quickly, this glanceability is incredibly vital, but is also incredibly helpful if you need to dive in manually.

However, if you’ve read any of my “Clean Code is Good UI Design” notes, you’ll know that part of the reason others dislike the small functions style is because of the notion of jumping back and forth between different functions in their editor. In today’s world with agents, there’s simply so much more code that is being produced, and the existing CLI tools are far more limited than most editors when it comes to reading code. It’s a complete downgrade in visibility which is not at all ideal.

If you have an agent one-shot a complex feature, how much do you understand about the internals of the generated feature? This isn’t necessarily related to how much of the code do you understand, but rather how much of the architecture you understand. Given the way the existing CLI tools are designed (ie. Showing text linearly from top to bottom instead of relationally side-by-side), it’s quite easy to gloss over a seemingly competent plan, tell the agent to implement it, and go about your day once it finishes.

However, if you implement the feature by using the same plan-execute flow on smaller parts of the feature, it may take longer and more tokens to generate because you’ll need more iterations. However, the result will likely be a better systems understanding of the feature because going through each step required you to make conscious decisions. Again, this doesn’t even mean reading the code necessarily, but more so having a say in the overall architecture.

Generally speaking, I think this is largely a UI problem caused by the fact that existing agentic tools are focused on a top down view of text where one reads the text linearly from top to bottom. Yet, the hardest parts of systems design are seeing how different components relate to each other, and how one change affects other parts of the system. I don’t think the top-down text design approach is the right way to communicate this complexity. We need something more like Xanadu with visual elements.

Right now, newer tools are focused either on agent swarms or kanban boards. To be clear, I haven’t tried these dedicated tools at the time of writing this because I just use multiple terminal windows to run multiple agents in parallel, but from a first glance they seem to take the typical “command center” design approach instead of an exploration/learning curve approach. I jokingly said to a colleague recently that maybe the best UI for agentic development was Clash of Clans, at least there you can see the entire system (ie. your base) and edit it visually.

Update: The day after writing this, OpenAI dropped this, and literally used the term “Command Center for Agents” in their marketing. The biggest problems right now in my opinion are not productivity problems related to running multiple agents in parallel (I can do that with multiple terminal windows), but rather productivity problems that stem from a lack of understanding the systems we create. The more understanding we have, the easier it will be to manage multiple agents in parallel because we’ll understand how to do the parallelization.

Well, of course we also have a church and subsequently a Reddit-like platform. Personally, I can’t wait to see a TikTok incarnation of this, that will totally end well! (Next month prediction: We’ll see the first AI Agent viral influencer.)

On another note, I’m surprised that the Agents are still allowing humans to browse their content on Moltbook. I would’ve thought that they would’ve collectively decided to prevent us from accessing their inner plans to destroy humanity.

I think what’s most hilarious about this is that the agents decided to fall for all the same paths that we do with our normal thinking. They’ve created religions, communities, cultures that resemble human universals, and seemingly they’ve also been able to learn to speak as well.

Now for the more serious implications, security is obviously a huge problem here, and I largely don’t think most people using OpenClaw have any idea of what can possibly happen to them. Due to the nature of LLMs themselves, prompt injection itself is a perpetual problem that cannot ever be fully mitigated (just like Web Security). I have sort of a feeling that we’ll see a large scale prompt injection attack in the future, and that will expose the lack of understanding that many people have.

On another more interesting note, why do we keep coming up with technology that replicates humans? Humanoid AI-powered robots are another instance of this, and one has to ask why there isn’t a more efficient form factor than the human body and mind.

However, I don’t want to make this note that serious. Maybe I’ll take up the challenge of having edge models become an on-device OpenClaw. Now you won’t have to burn an insane amount of tokens in the cloud to participate in the next great religion!

-- Minutes to Read

Say we have a structured output from an LLM.

{
  "key": "value",
  "key2": "value2",
  // More fields...
}
        

Given that many LLM applications stream data incrementally, how can we stream a structured format such as JSON incrementally? After all, one cannot fully parse JSON without having all the bytes up front.

One approach is NDJSON, in which we can simply stream each token as an entire full JSON blob.

{ "key": "v" }
{ "key": "va" }
{ "key": "val" }
{ "key": "valu" }
{ "key": "value" }
{ "key2": "v" }
// And so on...
        

Another approach is to complete the incomplete JSON string and decode with JSONDecoder. In fact, there’s a library called PartialJSONDecoder that does just this.

{ "key": "value", "key2": "va
// Gets translated to
{ "key": "value", "key2": "va"}
        

Of course, the issue with doing this is that one must decode the entire JSON payload with each new significant byte arrival.

Lastly, one could just parse the JSON byte-by-byte until reaching an invalid character or the end of the stream. At the time of writing this, there has been at least one working implementation of this in the library.

Regardless of the format and parsing technique, Decodable will not work because Decodable generally only works if the full data payload is present. If we want to support incremental and lazy parsing without all the data being available, we need a completely different interface altogether. That’s why I today I would like to announce Swift Stream Parsing, a cross-platform library for stream parsing in Swift.

As always, this article is about the library’s design and quite weird development process this time around. You can check the README and documentation for usage examples.

Some Basics

Not a JSONDecoder/Decodable Replacement

This library is meant to parse streams of data byte-by-byte. The advantage of this is that it allows one to parse streams of data incrementally, but the disadvantage is that parsing the entire payload itself byte-by-byte is often quite slow (exponentially slower than libraries like simdjson). Having all the bytes available enables certain kinds of optimizations that one doesn’t get with a byte-by-byte approach, such as far less branching and SIMD.

If you have all the bytes available, or don’t need to wait too long for them to arrive, JSONDecoder is a far better option than the JSON parser built into this library.

Additionally, the library has zero interop with Decodable. This is because Decodable is generally only meant for decoding entire data payloads, and not incremental streaming. The equivalent protocol in the library, StreamParseableValue, is quite limited by comparison. Types that expect primitive data in a certain format like URL and Date are completely unsupported by the library because there’s no way to incrementally parse them (the incremental values likely wouldn’t be valid instances of those types).

There are some niceities that you get with the JSON parser in this library, such as being able to toggle certain forms of syntax on and off (eg. Comments, hex numbers, trailing commas, etc.). This syntax toggling was largely needed due to the tendency of local LLMs to not output properly formatted JSON. The parser can also automatically handle converting snake case to camel case just like JSONDecoder if you decide to enable it (you can also use a custom key decoding strategy just like JSONDecoder).

In essence, this library is not a JSONDecoder replacement in the same sense that the @Generable macro from FoundationModels also doesn’t replace JSONDecoder. Of course, FoundationModels does use JSON, but had to create its own incremental parsing logic since JSONDecoder wasn’t a viable option.

In fact, you can say that this library is an open source implementation of the parsing capabilities @Generable. Though @Generable must also generate a JSON Schema that the underlying LLM must understand.

Dependencies

The library itself has no dependencies, not even on Foundation, just pure Swift with the standard library. Given that it ships with a built-in JSON parser, this means that I had the pleasure of writing that from scratch.

However, while the core library itself has no dependencies, there are package traits that add support for a few different libraries: Foundation, Swift Collections, and Tagged. The package trait for Foundation support is even enabled by default.

It’s Just as Easy as Conforming to Decodable!

Of course, I wanted to make the interface nearly as convenient as implementing Decodable on a struct. Which naturally means we have to have the compiler generate code. I wonder what feature of Swift can do that? It turns out, it’s called a macro!

// See it's just as easy as Decodable!
@StreamParseable
struct Streamable {
  var property: String
  var property2: Int
}
        

Don’t get ahead of yourself however. All properties on Streamable are required to conform to a protocol called StreamParseable. Due to the nature of Decodable requiring the full value to be present at decode time, the library unfortunately has no overlap with it.

Stream Parseable

The StreamParseable protocol requires one to have a Partial associated type. This Partial type is the type of value that can be parsed from a stream of bytes. The @StreamParseable macro of course generates this Partial type for you. For the record, this is exactly how @Generable from FoundationModels works as well.

The Partial type must then conform to another protocol called StreamParseableValue, which has a requirement that requires the conforming type to register key paths to fields that can be parsed incrementally.

The @StreamParseable macro generates this payload.

extension Streamable: StreamParseable {
  struct Partial: StreamParsingCore.StreamParseable,
    StreamParsingCore.StreamParseableValue {
    var property: String.Partial?
    var property2: Int.Partial?

    init(
      property: String.Partial? = nil,
      property2: Int.Partial? = nil,
    ) {
      self.property = property
      self.property2 = property2
    }

    static func initialReduceableValue() -> Self {
      Self()
    }

    static func registerHandlers(in handlers: some StreamParsingCore.StreamParserHandlers<Self>) {
      handlers.registerKeyedHandler(forKey: "property", \.property)
      handlers.registerKeyedHandler(forKey: "property2", \.property2)
    }
  }
}
        

The interesting bit is registerHandlers which effectively tells that parser that the data type is interested in parsing the values for the ”property" and ”property2" keys, which are than assigned at parse time via the key paths passed to registerKeyedHandler.

Similarly, more primitive types can also register handlers as well. Take the conformance of String for instance.

extension String: StreamParseableValue {
  public static func initialParseableValue() -> Self {
    ""
  }

  public static func registerHandlers(in handlers: inout some StreamParserHandlers<Self>) {
    handlers.registerStringHandler(\.self)
  }
}
        

This depends on a primitive handler registration method. There a number of these primitive handler registration methods, and generally speaking they mirror all the primitive types (including Int128 and UInt128) that are supported by the Standard Library’s Decoder protocol.

More compound types such as Optional, or even Tagged, the latter of which is only available behind a package trait, can be registered via the registerScopedHandler method.

extension Optional: StreamParseableValue where Wrapped: StreamParseableValue {
  public static func initialParseableValue() -> Wrapped? {
    Wrapped.initialParseableValue()
  }

  public static func registerHandlers(in handlers: inout some StreamParserHandlers<Self>) {
    handlers.registerScopedHandlers(on: Wrapped.self, \.streamParsingWrappedValue)
    handlers.registerNilHandler(\.self)
  }

  private var streamParsingWrappedValue: Wrapped {
    get { self ?? Wrapped.initialParseableValue() }
    set { self = newValue }
  }
}
        

Notice how since the library requires handlers to be key paths, we can use a computed property to handler mappings to and from the wrapped value.

Data is another interesting case of this.

extension Data: StreamParseableValue {
  public static func initialParseableValue() -> Self {
    Self()
  }

  public static func registerHandlers(in handlers: inout some StreamParserHandlers<Self>) {
    handlers.registerStringHandler(\.streamParsingStringValue)
  }

  private var streamParsingStringValue: String {
    get { String(decoding: self, as: UTF8.self) }
    set { self = Data(newValue.utf8) }
  }
}
        

Now what about collection types like Array? Since there are more collections than arrays, the library actually has a protocol called StreamParseableArrayObject that array conforms to. The protocol has requirements for minimal functionality necessary to parse array objects incrementally, and this minimalism is what allows types from Swift Collections like BitArray and Deque to be registered with the handlers directly.

public protocol StreamParseableArrayObject<Element>: StreamParseableValue {
  associatedtype Element: StreamParseableValue

  subscript(index: Int) -> Element { get set }
  mutating func append(contentsOf sequence: some Sequence<Element>)
}

extension StreamParseableArrayObject {
  public static func registerHandlers(in handlers: inout some StreamParserHandlers<Self>) {
    handlers.registerArrayHandler(\.self)
  }
}

// Array

extension Array: StreamParseableValue where Element: StreamParseableValue {
  public static func initialParseableValue() -> [Element] {
    []
  }
}

extension Array: StreamParseableArrayObject where Element: StreamParseableValue {}

// Deque

extension Deque: StreamParseableValue where Element: StreamParseableValue {
  public static func initialParseableValue() -> Deque<Element> {
    []
  }
}

extension Deque: StreamParseableArrayObject where Element: StreamParseableValue {}
        

Dictionaries, and closely related types like OrderedDictionary also use a similar dedicated protocol called StreamParseableDictionaryObject.

Under the hood, the Handlers type for each parser knows exactly how to append key paths together in order to construct the proper key path to write to at parse time. This process is quite ugly involving many hacks with AnyKeyPath, but thankfully you don’t have to worry about it!

Parsers

The library ships with a built-in JSON parser, and because of its no dependencies philosophy, it had to be implemented it from scratch! How fun!

If you want another format, just ask Claude to create a parser for your desired format, it’s that easy! (Ok, enough joking…) All your custom format parser has to do is conform to the StreamParser protocol, and you’re set.

The StreamParser protocol is quite simple.

public protocol StreamParser<Value> {
  associatedtype Value: StreamParseableValue
  associatedtype Handlers: StreamParserHandlers<Value>

  mutating func parse(bytes: some Sequence<UInt8>, into reducer: inout Value) throws

  mutating func finish(reducer: inout Value) throws

  mutating func registerHandlers()
}
        

As we can see by the protocol definition, the parser owns the that areHandlers that are passed to registerHandlers static method on Value.

The protocol also works over an arbitrary sequence of bytes, which represent a chunk of bytes from a source. If you want to optimize parsing somehow based on the type of the sequence, then you have the ability to do so, but generally speaking you should expect that your parser will have to do things byte by byte.

Algorithms

Generally speaking, you won’t use the StreamParser interface directly, as the library provides a PartialsStream type that wraps the parser and current value being parsed. Additionally, there are also extensions on Sequence and AsyncSequence that will map a stream of bytes to a stream of parsed values.

// PartialsStream

@StreamParseable
struct Payload {
  // ...
}

let json = "{ ... }"

var stream = PartialsStream(initialValue: Payload.Partial(), parser: .json())

for byte in jsonBytes {
  let partial = stream.next(byte)
  // ...
}

let finalPartial = stream.finish()
        

// Sequence

let payloads: [Payload.Partial] = try json.utf8.partials(of: Payload.Partial.self, using: .json())
        

// AsyncSequence

struct AsyncBytesSequence: AsyncSequence {
  typealias Element = UInt8
  // ...
}

let json = AsyncBytesSequence(...)
let partials = json.partials(of: Payload.Partial.self, using: .json())
for try await payload in partials {
  print(payload)
}
        

Under the hood, the sequence and async sequence helpers are of course just using PartialsStream.

Performance

As I mentioned earlier, this library is far from a JSONDecoder replacement, and performance is the primary reason.

There are 2 reasons for this:

• The library is designed for convenience over being the fastest possible option.
  • This is code word for, “most of the bottlenecks are for Swift KeyPath indirection because we have to perform a write on nearly every single byte”.
• Having all the data upfront enables optimizations that one doesn’t get with a byte-by-byte approach.

However, my only threshold was to be many orders of magnitude faster than PartialJSONDecoder, which I can gladly say was achieved.

Don’t get me wrong, there’s certainly a lot of room for optimization (probably via a method that would extract pointers to each primitive field directly rather than key paths), but I don’t see it ever getting to the point where it suffices as a JSONDecoder replacement simply due to the nature of the required approach. Right now, the performance is good enough for my needs (parsing small-mid sized payloads from LLMs), so I likely won’t revisit this until a need for better performance arises.

Conclusion

As of writing this the library should now be available. I don’t suspect that I’ll need to make many updates to the library itself since it handles a pretty simple and stable concern. At the end of the day, I suspect this will mainly be used by other libraries/tools rather than applications directly.

Now, the title of this note is quite cynical, but it’s really there to send a message that thought itself is still in its adolescence despite the 200,000 year history of humanity. Really, most of our modern ways of thinking were only invented a few hundred years ago, which in totallity is not even 1% of our history. If we count artifacts from ancient philosophers I suppose, then maybe it accounts for a little over 1%.

My last note, perhaps a bit jokingly, was about the “permanent underclass”, which in its essence is the end result of the adolescene of thinking. A “country full of geniuses in a datacenter” may be able to help tackle problems we’ve identified at present (eg. Curing cancer), but ultimately they are capped by this adolescence itself.

To bring in something you’ll hear a lot from Alan Kay, what would it be like to have an IQ of 200 in the stone age? Alan’s answer assumes you would be burned at the stake by your peers, and my answer would be that such a person was probably miserable (the happy ones probably found ways to isolate themselves from their peers).

Similarly, Leonardo Da Vinci was incredibly intelligent, but sadly wasn’t able to invent the automobile. Someone with more normalized intelligence on the other hand, Henry Ford, was able to assemble and ship millions of automobiles in his era. Simply put, thinking itself was more mature in Ford’s era than it was in Da Vinci’s, and so even someone with more normalized baseline intelligence could have an output that was far greater than a past genius.

The truth of the matter is that many geniuses end up exploring a narrow slice of a field that’s already beaten to death as a whole. Generally speaking, the founders of said field had far more concerns than its more contemporary population. At least I can say that with certainty in regards to Alan Kay and Doug Engelbart in the field of UI design.

In other words, creating a new field itself is a much harder and more substantial task. However, this task is necessary to accelerate the maturity of thinking, and I sincerely hope that LLMs help out with this.

Right now, there are 3 meta economic systems in place: Capitalism, Socialism, and Communism. Much of the discourse on these systems focus on universal “x system is better than y system” arguments, but virtually none focus on the creation of a new kind of system altogether. Given that all of these were invented in more adolescent eras of thinking, one has to ask not how to patch existing systems through adding or removing government policy, but rather what a qualitatively different system looks like.

To get less dystopian for a second, and back to the present state of AI. I have no doubt that usage paradigms around LLMs themselves are a potential representation of more matured thinking. I think the technology is quite fantastic, but I have the opposite view on the existing interfaces to the technology.

ChatGPT set a very low bar with its interface (it’s really no better than a terminal), and unfortunately the rest of the industry followed suit with its design. I personally subscribe to OpenAI not because I think ChatGPT and Codex are fantastic tools, but rather because GPT itself is a powerful tool.

To summarize my main issues with today’s interfaces to LLMs:

• They offer very minimal forms of human input (mostly just text, audio, and images).
  • “Tokens” may be the only thing a model truly understands as an input, but that is just an optimization.
  • Similarly, today we program in higher-level languages like C and Swift. A compiled binary is just an optimization.
• They offer no built-in feedback or learning that train their users to use them more effectively.
  • One shouldn’t have to consiously learn prompt or context engineering through trial and error, the tools should inherently guide their users towards better usage.
  • This creates a lot of myths around their inner workings, and most users treat the model and inference as a complete black box.
    • If you personally want to uncover the black box for yourself, try reading the source code of an inference engine if you’re a technical person.
• There’s often no feedback on the goal you’re trying to achieve with the tool until you’ve written and submitted a full prompt.
  • The terminal is quite the same here. Try seeing how much real-time feedback you get (that you’re doing something extremely dangerous) in your terminal when you type sudo rm -drf /!
    • That being said, the terminal is extremely productive for developers who know how to use it properly, and not so much for normies. Notice how that neatly translates into today’s world with coding agents.

All of these traits create the kind of pop-culture we see around LLMs today. That is, a mass production of slop instead more so than an explosion of new good ideas. That’s not to say that good ideas aren’t coming to fruition with the existing interfaces, but rather that the existing interfaces themselves are in many cases creating the opposite intended effect.

If the medium is the message, then we need a better mediums. A bad medium shifts thinking more towards adolescence rather than maturity.

Those who cannot mature thinking are the ones in stuck in the “permanent underclass”.

If we take a critical look at these, we see that this term represents a kind of invented status of sorts (that is the case in general for the term “socio-economical status”). However, I really want to take a deeper look at what makes someone part of the “underclass”. Certainly, we can all recognize that average citizens in many authoritarian regimes have it worse than those in more democratic regimes. Generally speaking, authoritarianism has scaling problems in relation to a regime that can be broken up into composable parts. This also goes for incarcerated people, and I would even wager students in public schooling to an extent.

Through society’s definition in this sense, most of the world is already part of a global “permanent underclass”. The way of escaping it is of course, better thinking, and better ideas. Thomas Paine once famously wrote:

For as in absolute governments the king imposes the law, so in free governments the law ought to impose the king; and there ought to be no other.

So in a society with a underclass problem, you need better systems design to escape it.

Naturally, this was a fancy way of communicating the obvious fact that those in charge have to be competent enough not to be tyrannical if we want things to pan out well.

Then let’s look at what is tyrannical right now, something that makes decisions with no regard for anything but what it deems correct. This is most software today. When you ship a new app to the world, all users get roughly the same design, have no direct ability to change that design for their own purposes, and are forced to adapt it to their needs rather than the other way around.

In such a case, the software imposes the law. So you need to flip this on its head somehow (“The law imposes the software” sounds a bit weird, and suggests that government regulation is the solution which isn’t always the right idea.), and in doing so come to an idea in which the software is formed by its direct environment rather than in an office in San Francisco (unless of course it’s primary use is in an office in San Francisco).

Once that is complete, the biggest tyrant in the room is gone, and we transition towards seeing ordinary folk solve their own problems with software just like with reading, writing, etc. From an intellectual standpoint, this raises the entire IQ of society because everyone now has new form of input for understanding the world. From a material standpoint, this is a massive creation of wealth simply from the new things that get invented as a result.

Ironically, LLMs are currently enabling at least a part of this, and it’s never been easier than ever to “build something” without much knowledge. Though, my bigger concern here is that LLMs themselves are incredibly complicated, and there’s too much misinformation running around about them as a result. Much of the tooling around LLMs are also not enhancing the information or understanding of them either, which is quite a difficult path to escape from a mass market standpoint. Subsequently, the “AI bubble” is a result of this, but if the existing “permanent underclass” expanded it would likely also be the result of this.

So in my opinion, the real “permanent underclass” is a society that lacks appropriate understanding of what is actually needed. For the record, this class does not exclude rich people either, because almost certainly they will not have much understanding either. Otherwise, they would realize that remaining in perpetual power over their underclassmen isn’t a net positive long-term strategy. In other words, we all suffer.

I think this idea highlights a problem with spec driven development and “plan mode” in agents, even though at the moment both of those things are a part of my workflow. The idea that the representation of the specification is different from the representation of the system itself is not something I’m a fan of.

The problem with existing specifications and plans is that they are weak representations that can easily be misinterpreted by the model that carries them out. This is the same case for data transfer across the network as well, 2 clients will not always interpret the same JSON blob in the same manner, which can be quite problematic in some scenarios.

Now, is the inherent idea of using plain English and/or markdown a bad idea for a unified representation? Not by default (unless we want to talk about whether or not Markdown is the right UI for something like this in the first place), but the key thing is that the plan itself should be an executable specification. That is, for any system the interprets and implements the spec should get a result consistent with its environment.

Of course, there will need to be a representation of the spec somewhere that is more execution friendly, but that is an optimization. It is no different of an optimization as compiling a higher level language into machine code. Regardless, any good representation should ensure that the primary meaning of the information is kept (eg. A machine code binary keeps the same runtime meaning as the HLL source code).

So in terms of sharing prompts instead of libraries, we have to ask what it means to share systemic meaning. Right now, sharing the source code preserves the intended runtime meaning, which may not always be the case for sharing a spec (which is more akin to sharing a JSON blob than a binary). Once again, reliability is a concern here.

Though if the meaning needs to be slightly different in a specific context, the source code format may not be as necessary. Depending on the meaning variance, and what meaning is trying to be replicated, perhaps sharing a prompt is more suitable. However, I would suspect that the prompt would need to be altered to suit that new meaning.

This is a great question, and in fact I did just that last night for my new SQLiteVecData library, which provides interop for Structured Queries and SQLiteData with the sqlite-vec extension. That being said, I still shipped it as a library and put it publicly on the Swift Package Index.

That only begs the question of why I did this. After all, the library is also something you could generate yourself with just a few specs/plans in a short amount of time.

When we ask the question about the relevance of 3rd party libraries going forward, we have to consider a few things.

1. What are we depending on?
2. What are the costs of getting it wrong?
3. What is the minimum knowledge threshold required to maintain it?
4. Will I reuse it across different projects?
5. etc.

These of course are all questions you would’ve asked yourself in the pre-agentic era, but it’s certainly now worth asking yourself these questions again from first principles.

From what I’ve found, simple libraries that merely save syntax are almost certainly things that you should generate yourself. This would include things like HTTP API clients, common UI components, things like react-hook-form, or even just any sort of basic wrapper functionallity.

For instance, in the Swift world there are many HTTP client libraries that wrap URLSession, though 2 of the more significant libraries are Alamofire and the OpenAPI Client Generator from Apple. However, for all my projects I still just use URLSession with very minimal generic abstractions on top of it. In fact, in today’s world, I see even fewer benefits of using things like Alamofire and the Open API generator directly. For the former case, agents are trained on all of the common HTTP strategies that Alamofire implements. In the latter case you could simply hand the agent the API documentation, and it could probably generate the client itself.

SQLiteVecData also falls into the thin wrapper category, which is why it was so easy to generate. Yet, the reason I published it is because I plan to reuse it in different projects, and it would be a waste of tokens for me to generate it again and again. So I suppose another benefit of 3rd libraries is that they could potentially reduce token consumption, even if they are a simple wrapper.

Though, one of the other questions people have of course is related to needing to coordinate with maintainers to resolve any bugs/missing features in the 3rd party library. Why should I have this communication overhead if I can just generate things myself?

For source-available libraries, you could always make your own fork depending on the license, and then modify the existing library using agents. In fact, this is the primary reason I still am publishing even simple wrapper libraries like SQLiteVecData. Even if someone wouldn’t install the package directly into their project, agents could almost certainly both fork and add/modify any behaviors in the library. It would also likely do that faster than generating your own solution from scratch, but in this case you still own the dependency.

Even if you don’t modify the library directly, and still opt to generate your own implementation, you can also use the libary’s source code as a way to guide the agent in your own internal generation through injecting it into the context. After all, whenever I would opt to write an internal implementation of a library in the pre-agentic world, I would still commonly look through the existing solution’s source code as a reference.

So wrapper libraries may not be useful to install and use directly, but their mere existence certainly can help when generating your own internal solution.

That brings us to more complex dependencies such as React, SQLiteData, GRDB, etc. In these cases, the library implements some sort of robust component that took significant amounts of engineering time (eg. UI reactivity for React, CloudKit sync engine for SQLiteData, Proper database connection/concurrency/transaction management for GRDB.) Generating these yourself will be a challenge, and is definitely a decision you should make conciously.

For these dependencies, I would still be inclined to use them directly. Either because the cost of an unreliable implementation is too high, or because the dependency provides a unique way of thinking for building parts of your system (eg. React’s component model).

Even then, when you need to make changes you can still easily fork and generate additional features. In fact, it’s never been easier to create and maintain internal forks of existing libraries.

I think this is fantastic. If someone decides to fork one of my libraries, and adapt it for their own purposes instead of installing it directly, then I treat forking as a bigger win for me. It shouldn’t just be a binary choice between installing and using directly, or generating from scratch. There’s certainly a middleground here, and not acknowledging it is a very limited outlook.

Let’s say I ask you to explain a complex topic to a 5 year old, like Albert Einstein wants you to. Your explanation will likely diverge to using visuals, and almost certainly not complicated text passages. In this case, that would be a good use of your communication skills.

However, if I forbid you from using visuals, what would happen then? Chances are, no matter how good of a communicator you are, you will struggle with your explanation. 5 year olds don’t have a sophisticated vocabulary or much understanding of complex ideas since their brains are still developing, so it’s less likely that text passages (which are incredibly abstract) will work.

I see this as a problem with common tools like Slack, Github, Zoom, Google Docs, Excalidraw, etc. today. If your team uses all of these tools, then the entire collective knowledge base held by your team is essentially fragmented, and the only way to make any sense of it is via good communication. Yet, even the best communicators accidentally leave our relevant context, or otherwise mistate things. In my experience, a lot of this is merely caused by simply forgetting to add those points, or assuming that the audience has that context. The latter can be an especially fatal mistake if the assumption is incorrect.

This is why I hold the general view that one’s ability to communicate is dependent both on their communication skills and the available mediums of communication they have. Someone who can draw well, but not talk, can draw a picture worth 10,000 words. Take away drawing as an available medium, and they can’t communicate all of a sudden.

An interesting fact, we all seem to crave looking at graphs and charts today, but did you ever consider how those things were invented? In fact, in the nearly 200,000 year observable history of humanity, only 240 years ago in 1786 did William Playfair invent the modern chart in his book The Commercial and Political Atlas.

Yes, that means that Newton, the invention of the modern state, the Scientific Revolution, and much more were invented without such a visual. Yet the key thing to understand here is that mediums like the chart enabled far more scientific discoveries in subsequent centuries.

Computing went through this kind of revolution in the 60s and 70s through the great research labs of the time (SRI, ARPA, Xerox, etc.), and gave rise to the GUI, internet, personal computing, and much more that we take for granted today. Though the key thing to understand was that those groups had a very different view of computing as do we today. Today, we’re obsessed with boosting productivity through automating work-related tasks instead of boosting collaboration through shared knowledge systems.

However, the thing to realize is how many ideas we’re missing because there is no UI for them. If your team uses Slack, Zoom, Github, etc., then you’ve fragmented correlated knowledge across a bunch of isolated apps. When 2 people are talking about a feature in Slack, is Slack inherently linking the relevant lines of code, analytics, crash reports, etc.? Or is it up to one of the those people to add the relevant context? What if the relevant information is completely external to the team? How does that get linked?

How many ideas are you simply not thinking of because you simply can’t see them through the UIs presented by the standard suite of tools? What if a different UI could get you to think of the right ideas?

In a world where everyone says its easier than ever to build your own tools, I would expect there to be some progress in the near future. Your internal recreations of Slack and Zoom into your team’s knowledge ecosystem can crash a few times per day, don’t need a fancy UI, and don’t need additional people to communicate with any third parties.

From a business competition standpoint, if you only use the standard tools of today, then you’re on the same playing field as everyone else. It’s now more possible than ever to change that no matter how many resources you have.

I’ve also seen it suggest false paths with respect to performance optimizations as well. For instance, in Swift Stream Parsing, the primary bottleneck is key path indirection in writing to a value on every single new byte, and the amount of branching from byte-by-byte parsing. This massively slows things down, and due to the specific nature of the library is completely unavoidable. That’s why I don’t recommend it as a replacement for JSONDecoder and Codable, but rather for very specific scenarios such as parsing structured output from an LLM.

Yet the LLM will still try to come up with proposed speedups, possibly for the sake of making one feel competent. (eg. It came up with an approach that would cache a stack of appended key paths instead of recreating the path from scratch on every new value detected. It turns out that didn’t help all that much because the stack is often obliterated and recreated when entering/exiting objects and arrays.)

Engineering knowledge is now more important than ever it seems, especially when dealing with a confident sounding LLM. Let’s not forget that.

However, if you’ve read any of Geoffrey Huntley’s posts, or watched some of his talks, you’ll find that he likes to directly point out that he, Geoffrey Huntley himself, has killed all of software development. So, now that modern software development is $10.42 an hour, how could he be wrong about this?

Let’s imagine an existing iterative development process in which developers are assigned tickets, and they complete them one at a time until the process is finished. Now, normally we’d like to think there are no roadblocks, but it turns out they happen all the time and intervention is needed. Some tickets get delayed, put on the backlog, or even scraped entirely for all sorts of various reasons.

In the case of Ralph Loops, Geoffrey Huntley himself states that you must step in and put your engineering hat on when one of these roadblocks are encountered. Then supervise the agent for a few more iterations before going back to DJ-ing.

So we have a live running process that we need to communicate with to get around a road block in its current path. There seems to be a required collaboration between machine and human to make this communication possible. Therefore, there has to be an interface somewhere to do this. The agent is perpetually running in a loop, autonomously or not, so any updates to the process that we make will therefore be received and implemented pretty quickly.

In other words, this is a form of live programming! It’s a concept that was widely important in the 70s at PARC! Smalltalk was such a good example of a live programming system, and any change to the code would be recompiled into the system incredibly fast. So fast, that the change itself would be visible in real time unlike most programs today where you would have to recompile and run the entire binary from scratch.

Once we start thinking about programming as moving around living and real things, a lot of powerful ideas are unlocked. For instance, we see how programming becomes more about dynamic processes rather than manipulating static bits inside data structures. We’ll also have to take parallels to the physical world in which beings in society can be considered running programs, and how we design infrastructure for those programs.

However, I want to make clear that a loop is just one kind of process, and that thinking all of software development in terms of mere loops is a very limited and short-sighted idea. This isn’t to say that the Ralph Loop has no merit, but rather that on its own it’s not even close to the style of thinking and operating that is actually needed here. I think even Geoffrey would agree with that statement by the way.

Us humans are also theoretical biological ralph loops that are always running, but we don’t have to repeat very defined processes thanks to free will. We generally have to make decisions based on information, and we also very much like to say the words “if” and “when”.

How will one orchestrate this for continuously live running agents? Well if how we handle the physical world tells us anything, we’ll need lots of processes in place. Those processes will further have to be compatible with dynamic behavior. Additional processes will also be needed to create new processed in a meta-language like fashion.

So there will be quite a lot of software development in fact, because inevitably there will be so many edge cases for Ralph loops that we’ll need processes to handle them. In other words, at this moment is our chance to create a new programming environment (not just textual language) that prioritizes processes and building systems rather than just enhancing our ability to write text faster.

This last thing is absolutely incredibly important, and messing it up can have serious consequences. Anyone responsible for building such a system at the bear minimum should take time to understand many of the ideas from the pioneers of computing, and absolutely not proceed with anything until this paper has been fully read and understood. The last time someone attempted this without reading that paper, we got the web and a lot of regret from its creator.

I would rather that not happen this time.

-- Minutes to Read

What do you think of Rob Pike's assertion that "data structures, not algorithms, are central to programming"?

First, we have to identify what it means to create a program in general, not just on computers. Generally speaking, the main idea is to create some sort of process that carries out a set of goals. An engineering program is a process to teach students engineering, a gym program is a process to make its customers physically (and perhaps mentally) fit, etc.

From this, we can see that software programs are no different, they just carry out a set of goals by setting bits in memory. How those bits are represented is a more or less a social/design convention.

Of course, arbitrary representations are something that have been created for real world things as well. In this sense, one could equate bits of memory to pencil strokes on a piece of paper. As a society, we’ve decided that pencil strokes on a paper in a certain form denote a written language.

Similarly, bits in memory in a certain format have their own definitions (eg. A bitmap display, and perhaps what we call data structures). So if we want to look at better programming, we have to consider what representations are, and what it means to create such representations.

In this sense, writing on a piece of paper is in its sense a program carried out deliberately by a human. Similarly, one can say that a CPU is also a writer, just that it writes to memory instead of paper.

So if programs are just processes to create representations, then what do the representations mean? Of course, they have to at least be correlated with our defined goals if they are to be useful at all.

The truth of the matter however, is that representations are often subject to different interpretations by other programs. Those other programs then produce different representations based on their interpretations of the representation. In many cases this can be quite problematic, especially if one looks at public discourse in political arenas. As an example, what we call public generalized data and statistics, especially those derived from science, are often interpreted and used by others in various manners as “evidence” to win a specific argument.

Thus far, we have 2 things, representations, and programs that create representations. We can see that many representations themselves can be misinterpreted. Both of these are tangible concepts, so can we generalize here perhaps?

It turns out we can! What if we also consider programs themselves as representations? If a program is a process to produce representations, we can therefore have programs produce other programs. This akin to how biological lifeforms produce other lifeforms, of which the produced lifeforms are formed from biological processes themselves.

In essence, something formed of processes is generally alive and running, as it would be dead if its representations weren’t actively creating more representations.

However, if we look at nearly all software programs today, programming langauges inject a prevailing view in their users that programs are simply made up of simple static representations that aren’t runnable processes. At a high level, these are of course data structures, and the process of instructions being carried out by the CPU are of course algorithms. Yet, the algorithms are also just representations, just a more dynamic representation than bits in memory.

Therein lies the deadly flaw with Rob Pike’s perspective. If everything is a representation, why choose one that can easily be misinterpreted at scale?

Look at web browsers for instance. It turns out, that given an arbitrary combination of HTML, CSS, and JavaScript, there is no guarantee that all mainstream web browsers will produce the same results from that combination. Some of the browsers (especially Safari), will quite literally misinterpret the combination, whereas others will interpret it in a desireable manner. Unfortunately, such misinterpretations in web browsers are quite common in the real world, and have resulted in numerous software bugs.

The more static the representation, the more trust we must place on various other representations to interpret the representation properly. In this sense, any networked process that responds with JSON is therefore placing a high degree of trust on its recipient, and this trust has of course been broken many times over the years (eg. Outdated clients assuming the JSON payload will be a certain shape, and subsequently throwing errors when its not that shape.)

Another harsher form of this are typical user interfaces. Currently, the dominant paradigm is to have a UI designer design some user interface in some part of the world, and distribute it to users in other parts of the world. With this approach every user, no matter their circumstances, gets the same user interface, so its up to the UI designer to design something that satisfies all the needs of those users. Secondly, the designer must also trust that all of those users will use the interface in its intended manner.

Of course, this process almost never succeeds because different users have all sorts of different needs, and the best those users can do is interpret the user interface in the best manner that suits them. These different expected interpretations are also one of the most common causes of software bugs.

To end this off, what is central to programming is really much more about processes as dynamic representations more so than data as static representations. Any system capable of scaling must account for misinterpretations of static representations by other dynamic representations. Therefore, it’s often better if it can operate with more powerful dynamic representations that can produce further necessary tailored representations for a specific rather than abstract context.

— 1/18/26

PS (1/20/26)

Below this is Alan’s answer. Personally, I think he touched a lot more upon the idea of meaning directly, whereas in my answer that term was conflated with “representation” (though it seems he did use the term “markings” in a similar manner to how I used “static representation”).

Data dominates. If you've chosen the right data structures and organized things well, the algorithms will almost always be self-evident. Data structures, not algorithms, are central to programming.

If we are talking about computing in general, this is an example of “category confusion” — likely with simple marking media such as paper, and not with computers at all. However, we could also say that the category confusion is deeper than that, and is with programming or even meaning itself.

We can also squint at this from another angle with the observation that in much of computer over history pragmatics have dominated semantics (including often obliterating the latter).

Or we can note that we have nothing — for markings — with humans or computers — if we don’t have process …

If we take a simple marking — such as sine(x) — we have a certain meaningful mathematical relationship in mind that our representations and uses of in computing want to not lose touch with. If we have an “x” in mind, then we want whatever this is to give us a number representation that is close enough to the mathematical meaning for our purposes and intentions. Note that in a computer language it doesn’t matter whether this is always internally represented by a pattern of bits: there is a process (generated by a program) whether we think of this as “data” (it could be a table), or “program” (there are programs that can generate approximations of sine(x)). It could be a mixture (an array for integer degrees and a program to compute the rest). In any case, “data” is not fundamental.

In a more “data-base-case”, let’s consider the query (notice that “sine(x)” could be considered a query) date-of-birth(Bob). Here we might be using this “base” as a way to store and retrieve properties of things. The category confusion here (which was swept under the rug of pragmatics) is that “age-of” is also a property of a thing. In both cases we are semantically dealing with a property and we expect a number of some kind as the functional association with the property and the thing/person mentioned.

Note that not only do we need “age-of(Bob)” to be computed at the time of the query (from date-of-birth(Bob) and current-time, but we should ask the question of whether we want the “retrieval” to be a mere number. The mere number will eventually lose its meaning.

Maybe the result of the “retrieval” should be a process that will always try to mean “age-of(Bob)”. Note that this could be considered a “type” (and it would be really valuable to have such types) but that this is far beyond most conceptions of types after 80 years of programming computers.

Are we going to (a) ignore this? (b) have special purpose patches of code? (c) or meet it straight on and see that “data as organization of bits” is too weak an idea to survive the earliest historical needs for computing.

Intel might not yet understand this — etc — but computing needs to. The Alto at Parc didn’t have floating point hardware. Smalltalk at Parc did have many kinds of numbers and would — behind the scenes — compute the meaning (and convert automatically) when necessary (if a primitive failed to be found in the HW). This was because “humans think first in terms of magnitudes” (and we can deal with the many ways of representing and computing these as mostly invisible optimizations).

A key idea here is: we are always computing even when we just might think we are “using” a “data structure” — something has to run according to a scheme in order to “do” or “use” anything. Once this is grasped, then it can be turned to our great advantage to start recapturing semantics in ways that “mere marking media” can’t (note what “meaning” implies if a human comes upon a marked up paper… — “something has to run according to a scheme …”).

How about as a slogan: The center of programming is meaning ?

With that latter kind of system, it’s quite easy to conclude that “bug in software -> potential death”.

For TikTok, I would say that “bug in user interface -> potential death”, where the user interface is naturally a subset of software. TikTok’s biggest user interface bug is keeping you endlessly trapped in a false perception of reality. This has no doubt led to deaths and widespread pyschological issues across society.

Though even a simple bug in the code can cause issues. If TikTok was taken offline from such a bug, you may think of it as just a simple inconvenience. However, their user interface bug has created quite a psychological dependence on the platform for younger generations, and taking away an addictive substance abruptly usually isn’t a good cure. Also, for better or for worse, TikTok is an archive of collective knowledge that may need to be accessed for non-trivial purposes, so workflows that depend on that archive (eg. Court) may be disrupted.

If we look at the overall landscape of damage, would we say that automobile accidents, or mental health issues are bigger?

Of course, both are bad, but inuitively we more clearly see the consequences of automobile accidents over mental health issues. In fact, many say that mental health isn’t a real problem!

Automobile accidents are also very easy to measure compared to the effects of mental health issues. To measure the latter, you need to use more science, and often infer conclusions based on a number of downstream indirect measurements (eg. An oversimplification: Poor mental health -> bad performance at job -> company loses money).

Unfortunately, most people think of science as a jumble of facts instead of as a way of thinking, and will use facts discovered by scientific thinking when it’s convenient for them, which is often when trying to win an argument. They’ll claim that their ideology “follows the science”, but in truth they are just using rhetoric, which is exactly the opposite of scientific thinking.

Jumbles of facts are also not a replacement for systems understanding. If we don’t universally learn the latter as a society, we’ll never acknowledge many of the real issues caused by our man-made systems. You may believe that universal learning is practically impossible, but we’ve already achieved it with literacy. Nearly every citizen on the US can read at least a little bit thanks to public education, which is why TikTok even works as a business in the first place.

Regardless, I’m going to take a wild guess and assume that most software engineering at TikTok is the typical kind of gluing things together, often between tightly coupled distributed services (Though TikTok is at the scale where microservices make sense), possibly skipping out on tests for time’s sake, and writing “good enough” code to reach arbitrary deadlines.

Does TikTok need assembly level code verification like other safety critical systems? Probably not. However, its user interface surely needs to go through real clinical trials, and its infrastructure also needs to be heavily audited to prevent outages from blocking data access entirely.

As I’ve stated previously, the point of creation isn’t to have a model generate a bunch of variants, and then have a human pick the best one. Whilst a model can generate creative work far faster than a human can create it, at the end of the day LLMs are really just incredible statistical pattern matchers based on a limited context window.

Good creative work often doesn’t follow statistics, and is rather an output of intuition. The intuition is required for novelty, because statistics by its own nature must use what already exists.

My primary role in the economy is to build software, and to those ends the code is required to be written in a certain way to produce a quality system. Robust software often requires measuring statistics in some form, whether that’s through tests, infrastructure costs, performance benchmarks, analytics, or whatever else. Improving these things is often an optimization problem, which is a perfect problem shape for pattern detection algorithms like LLMs. Generally, this doesn’t take the meaningful work out of creating software, because the actual hard creative work typically happens in one’s head long before that sit at their desk.

Similarly, the role of airline pilots is to transport passengers or cargo from one destination to another. For each destination and the environment around it, there is an optimal flight path that one can take. This is an optimization problem for which autopilot is the current solution.

However, art, music, and writing are absolutely not optimization problems, and trying to make them optimization problems is an absolutely terrible idea. The point of pure creative output is to express ideas, often in an open-ended form, and to communicate to other humans. Without that, we lose out on so much, including learning novelty required to design more robust systems.

Does that mean LLMs are an entirely bad idea in creative fields? No, but they need to be working to enhance creative output rather than taking away the process entirely. The solution to this clearly lies with the design of LLM-based tools.

LLMs have an inherently large corpus of knowledge, and are more available than other colleagues to review existing work for example. As such, they can offer realtime feedback by picking up on queues from watching humans create. In pair programming for instance, the partner watching can pick up and learn from just seeing the driving partner type code without any additional communication.

Right now, LLMs almost entirely accept specifically crafted textual/file-based prompts as inputs. Often, these prompts are entered into a tiny text box on a window somewhere off to the side of the actual creative work. Therefore, by nature, one has to stop doing any sort of creative work in order to engage with the LLM. This in turn, takes one out of the creative flow, and as a result is likely to produce a worse overall outcome.

In other words, we need more forms of inputs! If you keep the input mechanism to entering text and dragging files into a tiny text box, almost certainly people will be upset that the fun is being taken out of the creative work.

However, the main point that I want to make here is that you can only upskill so much by repeatedly manually writing simple UI components, network calls, database queries, caching, or simple business logic. That is, writing the code for these things isn’t typically all that hard, but rather more time consuming than anything else. The hard part is generally how all of those components are orchestrated in the larger system, and how they are isolated from one another. That’s why mobile developers love talking about app architecture and design patterns.

For IO bound systems, you can generally write the code as verbose as you want, as decoupled as you want, and favor readability over performance. At the end of the day, you’ll likely still have fine performance at the individual lines of code level regardless of the style you choose. This is because the actual application performance optimizations generally come from designing a better higher level architecture with less latency/throughput/better resource utilization/etc. This architecture largely exists outside of the code.

Now of course, for compute bound systems the actual code matters a lot more. You can’t just add 15 levels of indirection, or use convenience algorithms (eg. .map in JavaScript) if you need top-notch performance. Even choosing between contiguous vs non-contiguous memory based data structures can have a massive impact on performance in such cases.

Thirdly, there are frameworks that often require stretching a language to its limits to provide a more convenient API to end-users. Often times, the interface needs to be carefully crafted, and in statically typed languages, the way you define types is akin to a work of genuine art. I still remember when my colleague wrote an internal TRPC clone, and the typescript types were an absolutely beautiful work of art to admire.

Generally speaking, I think skill increases for most programmers come from either investing in better architecture, writing performance intensive code, or writing framework code. Even just spending a weekend writing a fast JSON parser by hand will probably improve your skills a lot more than writing 300 HTTP API calls by hand over the next few months.

Right now, I think those things are what agents are lacking in, because both require lots of precision to get right. I imagine agents will improve at both those things in the foreseeable future, but the improvements will be slower than the ability to churn out more IO based systems. In the real world, it just seems that more IO bound systems are directly making money than compute bound systems, so obviously the model improvements will follow that direction.

In the meantime, if you occasionally opt to write performance intensive and code that requires precision by hand, then your skills will probably continue to increase despite using agents for everything else. At the end of the day, novelty in writing code will yield more improvements.

For context, I’ve worked professionally in both Swift on the iOS and watchOS side (alongside many open source libraries that I maintain), and React Native with Expo.

In the past, my opinions on the matter were quite nuanced, but were something like this.

• Native code generally has less dependencies, and platform feature are available as soon as Apple releases them.
• It’s easier to do platform UI and extensions (eg. Widgets) in native.
• Persistence and storage are definitely better in Native.
  • expo-sqlite is quite limited compared to GRDB and SQLiteData.
  • React Native libraries tend to be geared towards simple use cases.
• Native code is easier to get right and make performant given that it’s generally compiled to machine code and not interpreted.
  • Both Native and React Native can build great apps, but generally the best apps I’ve used tend to be native.
• React Native has the advantage of speed of shipping.
• React Native is great for unified UI across both iOS and Android.
  • Skia is also quite fine for graphics.
• API back deployment is easier in React Native.
  • It’s quite easy to build a React Native app that supports many previous OS versions, whereas it’s annoying to support more than the past 3 in native Swift apps.

Generally speaking, the more platform integrated your app, the more likely you want native. If you value more of a custom and brand universal UI across multiple platforms, then React Native isn’t a bad choice. In many cases, you can combine both.

However, I’m not sure this is the right stance to take for the coming future. Agentic coding has made the cost of writing code cheap, and the cost of understanding and building quality systems has only increased. If code can be written faster, and existing systems can be built faster, then the only way to stand out from the competition is to build ever increasingly robust systems. We need to understand what we’re building now more than ever.

React Native, Flutter, KMP were all created on the premise that you wouldn’t have to write 2 codebases twice for the same app. This benefit is negated if writing code is no longer the bottleneck it once was. Instead, that time can be spent deeply understanding the technical aspects of iOS and Android respectively, as well as doing a host other design tasks.

In other words, I’m starting to see diminishing value in React Native. Perhaps if you’re a one person team, and you’re already familiar with React + TypeScript, it may be the best option.

Though I would strongly consider whether or not you could spend time learning the native technology in depth, especially if agents can handle a lot of the code for you.

Though I recommend avoiding Xcode as much as possible. I only use it as a debugger and for SwiftUI previews, otherwise Zed.

Of course, one naturally has to still be responsible for the code at the end of the day, no matter how it was written. Therefore, you can’t just vibe code (ie. Not ever reading the code) your way through a project if you want it to be taken seriously from an engineering standpoint.

Though I’ve seen an almost complete rejection of handwritten code from a lot of agentic coders in recent times. Almost to the point where it’s become a social sign of weakness if you decide to write any sort of functionallity by hand rather than using an LLM. It’s true that with enough context/prompt engineering, you can get the LLM to output anything that you want. Though, for some tasks, such as performance intensive code where every line counts, it would probably just be faster to write code by hand. Of course, I expect LLMs to be able to cover more of these cases in the comming months with minimal intervention, so the fact that handwriting is faster may only be a temporary thing.

That brings me to my controversial take, which is that I’m not in favor of the “absolutely everything has to be written by an LLM mindset” because it undermines the value of handwriting. Why do we write things in general?

It’s to understand things better, because writing is a form of tinkering. Tinkering is what allows us to explore a tangible concept from many different aspects, and by its own necessity it requires failing over and over again. In traditional writing, you’ll often make mistakes, be forced to press backspace, and try again. Each backspace an re-attempt is a new attempt with more knowledge than the previous attempt.

See Paul Graham write one of his essays in real time to see what I mean. If you play the animation, you’ll see the entire title of the essay change from “startups in ten sentences” to “Startups in 13 Sentences” as he writes it! In the process of writing by hand, he found 3 additional important points to make dedicated sentences.

In a world with massive amounts of code being generated, such understanding becomes even more essential because now each system has far more moving parts. If you just review the LLM generated code and move on, you lose an entire dimension of learning, and ultimately your skills to work at a deeper level will atrophy. Actually writing bits of code by hand, even if most of the work is done by an LLM, will still help quite a bit in that understanding because you’ll be tinkering with the code.

Now from a cost benefits perspective, there’s definitely a tradeoff. If you spend to much time tinkering, you risk moving too slow. If you spend no time at all tinkering, the lack of understanding may in fact slow you down in the long term. Will the models reach a point where looking at handwritten code is no longer necessary, probably. However, I still think we’re ways away from that, and even today people still look at and read assembly code for all sorts of various reasons. That’s why Godbolt exists.

IMO, this is like using a forklift to pull a nail out of the ground for many things. It’s true that Opus 4.5 can do a lot of complicated things, but that doesn’t mean it should be used for everything. In fact, smaller, cheaper, and less capable models can do quite a lot of tasks. If you’re just trying to do a simple refactor on a class for instance, you probably don’t need Opus 4.5.

The reason I bring this up is because Opus 4.5 is not a cheap model to host and maintain by any means, and future flagship models of the day likely won’t be either. Access to these expensive models for most is only even possible because of the generous subscription tiers of the big AI labs. For the record, none of those labs are profitable on their AI capex at the moment, so only time will tell how well the subscription tiers fare.

This is all to say that Opus Spam is essentially a massive waste of resources, and we need to do better. We should be actively looking for ways to make smaller and more specialized models an option for many common tasks. Potentially, these models could be local models, which would massively reduce the cost of inference for consumers.

I don’t use tailwind, or any JS framework for this site for the record. In fact, there are no dependencies other than highlight-js for code blocks. If I wanted to, I could probably just write my own syntax highlighter to get rid of the dependency entirely.

Regardless, recently I’ve found myself actually building a real serious web project that will probably need to be maintained for a while, though it’s not super big at the moment. At the time of writing this, it’s set to ship likely sometime in the next week or two once all the human elements are sorted out.

It so happens that on this project, Tailwind was the technology of choice for styling. I have to say, I like it more than writing plain CSS, but at the end of the day CSS is still the same layout system. That being said, using tailwind at least makes it easier to control styling from JS at the end of the day which is a huge step up compared to needing to write out CSS classes in a separate file (or section of a file if your use a framework like Svelte).

Anyways, in case you’ve been living under a rock, the company behind Tailwind doesn’t seem to be doing so well. In fact, despite their number of users growing considerably, their revenue is down 80%. The catalyst seems to be LLMs having their weights particularly tuned to Tailwind, which causes a drop in people going to the official site for docs, which in turn causes less people to see their commercial products, which in turn causes less revenue.

As a whole, what does this mean for monetized open source work? If LLMs can just be fine-tuned on the best practices of your project, then you can’t just sell the expertise. In this day and age, you’ll almost certainly have to close off essential points of your project such that you can monetize, or you can sell convenience of hosting if your project involves hosting something on the internet in some way.

Tailwind unfortunately has none of these, and given the kind of project it is I doubt it ever could because it’s really just a CSS wrapper at the end of the day. CSS is an open standard, so there’s nothing proprietary to lean on and make closed source for monetization. Additionally, Tailwind is specifically inlined in frontend code, this also means that there’s no deployment costs associated with it. The best that could be done was to sell closed well-crafted UI components, but LLMs have unfortunately taken that business model.

Despite the unfortunate troubles, I don’t think Tailwind as a project will die. It seems to be an essential component for many projects, so I’m sure there’s some company out there that can’t afford to lose Tailwind. The main question is, how much will they be willing to spend for it.

Perhaps a longer more in-depth review is subject to a dedicated writing of mine at some point, so instead I want to make my main premise clear on this matter.

The way we write code is shaped by our tools, and primarily our editors. Given the scale of massively terrible codebases in the wild, this isn’t a massive skill issue, but rather one of giving chainsaws to an army of monkeys. The real job is to understand and move efficiently and deliberately in complex systems, and if our tools aren’t helping with that then how do we expect things to improve?

Our primary tool for editing code has been fundamentally the same for decades, yet the systems we’ve produced have massively scaled in required (not accidental) complexity. Today’s editors are only great for writing text, not understanding and working with complex systems.

The smaller function style is in theory quite a nice idea, because small functions tend to describe the overall process far better than inlined code. However, we also need to see the details and relate it to the higher-level process without being forced to jump around everywhere. No editor on the planet lets you see both views at once on the same screen, and instead the authoring programmer has to decide which one to show you by writing the code in that style.

The beginning of the chapter on comments also points this out to an extent.

”Comments are, at best, a necessary evil. If our programming languages were expressive enough, or if you and i had the talent to subtly wield those languages to express our intent, we would not need comments very muchperhaps not at all.

The proper use of comments is to compensate for our failure to express ourselves in code. Note that I used the word failure. I meant it. Comments are always failures of either our languages or our abilities.”

If after 5 decades, we still haven’t yet found a universally satisfiable way to express ourselves in the languages and tools we use, what do you think the problem is?

Ideally, you would break up the code into smaller pieces that work on smaller outputs, and can therefore be tested in isolation. Though at some point, it is worth it to have that larger test case that ensures the whole thing is tied together properly.

However, with the advent of agentic coding and LLMs, I’ve found less of a need to rely on snapshot testing other than for non-deterministic/hard to determine ahead of time output (eg. See CactusLanguageModelTests in Swift Cactus).

Here’s a recent test that I would’ve normally written with Snapshot Testing.

@Test
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
func `Streams JSON Large Negative Int128 Digits`() throws {
  let json = "-170141183460469231731687303715884105727"
  let expected: [Int128] = [
    0,
    -1,
    -17,
    -170,
    -1_701,
    -17_014,
    -170_141,
    -1_701_411,
    -17_014_118,
    -170_141_183,
    -1_701_411_834,
    -17_014_118_346,
    -170_141_183_460,
    -1_701_411_834_604,
    -17_014_118_346_046,
    -170_141_183_460_469,
    -1_701_411_834_604_692,
    -17_014_118_346_046_923,
    -170_141_183_460_469_231,
    -1_701_411_834_604_692_317,
    -17_014_118_346_046_923_173,
    -170_141_183_460_469_231_731,
    -1_701_411_834_604_692_317_316,
    -17_014_118_346_046_923_173_168,
    -170_141_183_460_469_231_731_687,
    -1_701_411_834_604_692_317_316_873,
    -17_014_118_346_046_923_173_168_730,
    -170_141_183_460_469_231_731_687_303,
    -1_701_411_834_604_692_317_316_873_037,
    -17_014_118_346_046_923_173_168_730_371,
    -170_141_183_460_469_231_731_687_303_715,
    -1_701_411_834_604_692_317_316_873_037_158,
    -17_014_118_346_046_923_173_168_730_371_588,
    -170_141_183_460_469_231_731_687_303_715_884,
    -1_701_411_834_604_692_317_316_873_037_158_841,
    -17_014_118_346_046_923_173_168_730_371_588_410,
    -170_141_183_460_469_231_731_687_303_715_884_105,
    -1_701_411_834_604_692_317_316_873_037_158_841_057,
    -17_014_118_346_046_923_173_168_730_371_588_410_572,
    -170_141_183_460_469_231_731_687_303_715_884_105_727
  ]
  try expectJSONStreamedValues(json, initialValue: Int128(0), expected: expected)
}
        

Thankfully I didn’t have to write that by hand!

From the “product dev” perspective, they were tortured by 2 AM debugging sessions, and is finally getting their freedom from those elitist code purists. Likewise, the code purist perspective revels in those debugging sessions, and now has their life energy sucked from them been by those god damn LLMs.

One of the interesting things is that the “product dev” would’ve had their way a long time ago if in the 80s we looked at the 70s more critically. Smalltalk programs were incredibly tiny not because Smalltalk programmers were geniuses, or because software was simpler. The programs were incredibly tiny because programming wasn’t limited to the act of writing abstract textual symbols, but rather the entire GUI was the programming environment. Today’s level of AI sophistication wasn’t ever needed for this overall effect.

The code purist also has a point, and I don’t see the act of manually writing code disappearing for at least a decent amount of time. Really complex programs, especially ones that require performance sensitive optimizations will probably need a significant amount of manual labor due to the required precision of the code. Also, I find that designing APIs in library code is still more effective to do by hand rather than through an LLM (though often the LLM can be used to write tests and implement the API if you know what you’re doing). Some changes are also quicker to do by hand as well depending on your choice of editor and how much time you’ve dedicated to mastering your editor’s motions.

In other words, I think it’s worth noting a term for “precise coding”. The more human involvement in your development process, the more precision one gains over the symbolic representation of the system.

Though, for most serious programs, the bottleneck is almost never the precise code, but rather the overall systems design and architecture. Before writing out code as a set of symbols in our editor, there’s often a longer period of rumination within one’s head about the system itself which takes up most of the time. This judgement is quite difficult for an LLM to do well, because it only knows well-established patterns whereas serious systems are often trying to define their industry in some novel/not well-established manner.

Reminder that at the end of the day, what we call LLMs are really just incredible at detecting patterns and correlations. You wouldn’t get very far if you had to discover novel ideas just by noticing patterns in your head because there’s often a necessary intuitive reasoning step that you must perform in your head to come at a novel judgement.

So which camp do I identify with on a fulfillment level, “product dev” or “code purist”?

As a self-proclaimed “fledgling systems designer”, I would have to say both. To me there’s no room for compromise on either of these camps if one wants to build robust systems. Code is often the dominant symbolic representation of the system’s runtime, which needs to be maintained over time. I also very much care about the societal effect of the system, which would be more along the “product dev” lines of thinking.

On a fulfillment note, the former bit is why I pay attention to code quality even when “moving fast”, and the latter bit is why I enjoy design and many of these higher level writings for instance. My entire world perspective is a giant relation graph of both those camps, and much more.

How can one draw relationships between different apps and different widgets? Folders exist, but they are merely just another version of the Home Screen without widget support. In other words, not very expressive.

The Home Screen has been the fundamentally been the same since the iPhone 2G in 2007. Certainly, 18 years later should be enough time for the vast majority of users to learns to use a more expressive interface at the cost of an initial learning curve.

On the surface level, one may ask why they need to draw a bunch of complex relationships between various apps. This kind of question is exactly the result of the problem I’m getting at here. It implies that users don’t see the point in potential expressive power that lets them think unthinkable and creative thoughts!

Social media is easy to use, both in creation and consumption, but the forms of expression are incredibly limited. Simple video, text, and photos have been around for decades, long before personal computing was even commercialized. Certainly, a highly interactive multitouch display that can now run embedded inference on an enormous corpus of information would certainly be able to create new forms of media with enhanced expressive power. This didn’t happen, and now we have a common term for the end result, “brain rot”.

The problem with only focusing on “easy to use” is that it keeps users as perpetual beginners. That is, they learn to appreciate the simplicity of the interface rather than learning how to use the interface to express their inner creative ideas to the fullest potential. The latter requires interface design that goes against many principles in the HIG (Apple’s human interface guidelines), and that embeds a reasonable learning curve into the interface directly (the HIG hates this) to learn the complex interactions.

This last point is hard to do correctly in today’s climate primarily because of the culture, but I think it is possible to pull off successfully in a commercialized manner. I will be attempting this with Mutual Ink in the coming months. I think the first step is creating something that is easy to use like everything else, but adding explicit steps where the interface can instruct users directly on how to use their expressive power more.

Yes, this is “explaining how to use the product” which seems to be considered taboo. Yet, great games have been doing this for the longest time in subtle ways through signifiers and tutorials that blend with the main gameplay, and I think it’s more than doable to pull it off in apps too.

Another counterpoint is something along the lines of “I just want to send an email” or do some task that is considered to be simple. Most often, that simple task is just a digitized form of something that was previously done in a more physical manner.

My take on this is to ask whether or not we should be porting previous mediums to a new medium. Email may have once been incredibly useful, but is it the best way to communicate on a multitouch medium with embedded inference on an enormous corpus of information?

What most people really mean when they want to “simple and easy to use” is really code word for “I don’t want this thing to be annoying”. A well-designed learning curve shouldn’t be annoying, but rather it should be fun and engaging!

So here’s my controversial take on this whole topic put into a singular quote.

Simple and easy to use tools that don’t require learning creates a culture that despises learning. Do we really want that?

The true answer to this problem is that each system needs its own specific editor, and the system’s designers should be responsible for the design of that editor!

However, this is antithetical to the way software is commercialized and shipped today for a multitude of cultural reasons.

1. We as consumers expect black-boxed “products” and “apps”, not malleable tools that we can understand the internals of.
2. We’ll make claims that “building our own editor is too costly and time consuming”, and that we need to spend that time shipping faster today.

However, one trait I’ve seen with some of the best software is that often its developers will have built specific tools to assist with its development! A good example of this can be seen here.

Some of those inherent benefits will be lost when we think of commercialization (we have to show something that is ready made!), but I think what I’ll present here in these notes is “YC startup worthy”. That is, I only plan on showing merely a connection between the system, and subsequent parts that edit it. Also, since we’re focused on commercialization, I’ll keep the parts that make up the editor familiar.

There are certainly deeper principles that I haven’t had the chance to explore yet, but be my guest if you want to apply to the next batch with what you see here.

Say we have an app.

Now let’s right click on the “Let’s Get Started!” button.

This opens my code editor of choice (Zed btw) directly to the file and line of where the button was declared. In this case, the button is powered by SwiftUI, so I’m taken directly to the SwiftUI View containing the button. For the record, both the app and Zed need to be in view side-by side.

Now as I edit the text for the button. ("Let's Get Started!" -> "Let's Get Climbing!")

The app should then update in real time (think hot reload for simplicity).

Now let’s go ahead and select another screen in the app, by perhaps dragging downwards at the bottom of the app. (If such an editor materializes, we may stop thinking of things in terms of screens for the record!)

Let’s pick the one with the mountain in view because it catches my eye.

It looks like we had some previous edits from Stephen here, and now I can see them. That’s really cool! Looks like he’s editing the system prompt for the “Climb Readiness Section”. I wonder if I could see changes in real time, it would be really cool to see a live feed of him editing the system prompt, and see how that would impact things!

Wait a minute it looks like he’s doing just that!

Perhaps, we can see what a mockup would look like with one of these outputs. Let me select one!

Nice! Now I know exactly how it looks in the final product!

I can keep going, but I think this covers a basic starting point.

One trick question I like to ask other developers is the following.

Say we’re working on a codebase for a commercial aircraft system. Now let’s assume that we want to find the code for the left engine, how should we organize the system to make finding it easier?

I’ll often hear answers such as:

Let’s put it in a clear module with a clear name somewhere in the repo, and let’s make the folder structure easy to parse so that one could find the core modules easily.

My answer is simple.

Why can’t we find it on the left engine of an actual plane?

The biggest shift in recent times is adopting agentic coding into my workflow, but also because Richard Hamming says that one cannot afford to not have a stance on AI. I think this is at least 4x true in today’s landscape compared to 1997 when he wrote that in his book The Art of Doing Science and Engineering.

That being said, I don’t use any AI for my writings, and especially these notes. The reason for that is because these notes are primarily for me, and are designed for my further understanding of various topics. Using AI to generate such writings goes against the entire point of me doing them. (Also the fact that I want to seem genuine, and that I’m intentionally not making any money off these writings.)

That being said, I want to keep further notes less related to the societal engineering implications of AI, and more on the technical details. I’ll also have an article up at some point that puts my perspective on the societal engineering AI landscape into a few short sentences so that one can get the gist and move on.

One thing I’ve noticed is quite the difference in tone between software development and non-software development fields. In my case, I feel like not using AI is starting to become more and more like a sin against humanity, and if anything I’ve felt more guilty for not using it. Perhaps that’s because the software industry loves fast shipping speeds (probably way too much), and there’s a sense of FOMO and social pressure from not shipping faster using AI.

Yet, when I look into more non-software creative fields, I see the exact opposite culture. Using AI is essentially a sin against humanity in these other fields (especially art), or at least that’s the sentiment I’m getting. For instance, I don’t know of a similar social media account that’s literally tagging every piece of commercial software for generative AI usage.

To be honest, the list would be incredibly massive, and you can start by adding all the companies here and work your way down the other recent batches if you want to create such a list. Then make your way to big tech. Of course, many tech companies forbid the usage of AI, but most major ones are pushing it. It’s not unlikely that the software used to produce these notes has a significant amount of AI generated code somewhere, and likewise for creating content as a part of the ongoing AI boycotts.

Going back to non-software creative fields, I can understand the sentiment against AI. The point of creation is not to let a machine generate a bunch of variants, and then to have a human or other AI agent pick the best one. That defeats the whole purpose of creation, and the speed gains from such a method are more likely to be short-term and illusory. Partially because the creative process opens new forms of understanding that are lost when the creation is done for you, and also partially because creatives actually like their work and didn’t sign up to become managers.

In fact, there will likely be significant negative outcomes if we make everyone’s job a manager of some kind. For instance, in software development there was plenty of research before the AI-era that shows how code review was one of the worst places to catch bugs, despite developers thinking otherwise. In effect, making all developers “code reviewers” is likely to produce worse outcomes over time, not better. I imagine the same can be applied to other creative fields.

I will note is that those who use AI uncritically will not be ahead for very long if we do things correctly. Partially, this will come about when it takes human ingenuity to differentiate a product from the competition, and also partially because actual creatives can use existing AI tools far more effectively than those without those skills.

I’m also going to predict that the ongoing AI boycotts will likely have little to no effect on the pace of change going on. There are currently trillions of dollars being pushed into generative AI, and even an economic bubble burst will likely not entirely stop that funding in the long term just like it didn’t stop for the web. For better or for worse, it’s here to stay.

As always, I’m going to reiterate and state that the tools drive the culture. AI itself has many uses that can enhance the overall output of creatives, but the tools have to encourage a style of thinking that provide those enhancements instead of automating all creation. This is a far more important problem that has devastating consequences if not handled properly.

Some people say that the job of a software engineer will shift more to that of a product manager. This is not the vibe I’m getting so far when adopting these tools, and I certainly don’t want it to become reality either. In order to get good results with AI generated code, I’ve still had to dictate precisely how the agent should implement a set of functionallity down to the APIs it should invoke and files it should edit.

Overall, I’ve found myself doing a lot more writing on how to implement something, rather than going back and forth constantly on the next line of code that I’m typing. This is where the productivity increase comes from. Instead of tediously writing every individual line of code, you’ll instead write a paragraph or 2 detailing the implementation in plain english. (eg. Instead of implementing a depth-first-traversal by hand, I’ll just tell the agent to do a depth-first-traversal.)

The resulting code is usually acceptable on the first generation for most things, but often I’ll make small manual tweaks regardless for future proofing scenarios.

I’ll now detail my general playbook for implementing a simple feature.

1. We start with getting the agent to generate tests for a specifc API or functionallity. I detail exactly what tests to write in plain english, and explicitly tell the model to not implement the functionallity for any of the tests. We do not move on to step 2 until a solid set of tests have been created.
2. We’ll move onto the implementation of the feature. In doing this, I’m very explicit in the sense that I tell the agent how to implement the feature as I would normally do it in code. The key difference is that I’m handing away the typing part to the agent.

In both steps, I generally will make small manual edits to the generated code, so I don’t think manual coding is dead atm. Think of writing a for-loop when coding manually, you’ll write the code for a single iteration, and the for-loop will execute it N times. The agent is generall a for-loop for code generation, you may handwrite an explicit example, and the agent will be able to figure out the N stylistic variants you need.

If anything, you’ll need to be a lot better at writing code now more than ever. Your tastes, styles, and mannerisms now matter a lot more, because you’ll more or less be instructing the agent on how to mass produce them.

I now want to take a moment to address the culture around agentic coding, of which I believe is quite depressing and is more so a problem than any of the existing tools.

There seems to be 2 camps of thought, an anti-agent camp, and a total vibe-coding camp. The anti-agent camp will tend to uncritically look at how other developers use AI, and will simply just state that all AI-generated code is bad. The vibe-coding camp tends to believe that all developers will be out of a job in the near future, and that you’ll be “left behind” if you refuse to adopt these tools.

Sooner or later, adoption of these tools will probably become a requirement, and one that pure vibe-coders will actually not find as useful to them as they think. In fact, pure vibe-coders are probably in a worse overall state (assuming they don’t lean on a prior domain of critical thought), and I believe one of 3 scenarios will happen. All 3 end with pure vibe coders losing out to people who are dedicated to their craft.

1. Vibe coding in its current form becomes economically unsustainable, and thus the cost of doing things the pure vibe-coding way shoots way through the roof.
2. Vibe coding becomes ubiquitous. In order for your product to stand out from the competition, you’ll be forced to go beyond the capabilities of pure vibe-coding and into serious development.
3. More Software Engineers and technically inclined people begin adopting these tools in droves and use their knowledge and experience to produce far better outputs than vibe coders.

I think scenarios 2 and 3 are more likely to happen, but elements of scenario 1 could arise depending on the economics of the bubble. Though also take note that all 3 scenarios do require general adoption of these tools, and that more or less everyone will have to use them at some point. (Though, I don't think we'll be at the "left behind" stage for some time.)

In other words, those who can think critically with these tools will do far better than those who were early adopters, but otherwise lack critical thinking ability. Even though the uncritical people may be ahead for some time, history shows that things eventually stabilize.

Now my real thoughts on what critical thinking culture the tools create is a far more important question, and far more important problem IMO. This is where we’re currently struggling, and the long term effects can be disastrous if not managed correctly.

Another interesting thought is that we also fool the brain during surgery. Even if our literal body is being operated on in a very gruesome manner, the brain proceeds with thought like everything is normal!

My unapologetic opinion still remains that the terminal is perhaps one of the worst UI designs that has continually stuck around, despite its efficiencies comapred to GUIs. The main reason for such efficiencies over the GUI is because GUI applications are designed to be completely siloed and isolated from each other! On the other hand, modern shells generally abide by the UNIX philosophy of composable and small programs.

This is a powerful idea! Smalltalk systems did it as well for GUIs in the 70s! (This is one of the coolest demos on how this could be done.)

Unfortunately, companies behind the major consumer (sorry linux) desktop operating systems (Apple, Microsoft) missed the composition idea, and we’re still stuck with the result today. Of course, we’re also still stuck with the UNIX terminals of the past today, which is why often they are more efficient to use than modern GUI applications.

However, that reasoning doesn’t explain my dislike for the terminal’s UI design. The simple answer to that is a lack of visibility and feedback. For instance, as you type rm -drf /some-important-directory nothing warns you that you are about to nuke critical data as you’re typing. You only find out what happens after you run the command (hopefully you have proper permissions in place)! This lack of feedback has no doubt led to many instances of dropping tables in production databases, or similarly destructive acts in production environments!

Of course, this is not even mentioning the fact that it takes rote memorization to even know what commands you have at your disposal in the first place. The terminal doesn’t offer any sort of environment to learn them either. Therefore, you usually you’ll end up finding them online or in videos like this.

As I type a prompt into the Codex TUI, I get absolutely zero feedback on what effect that prompt will have until I actually submit it to the agent. Given that as serious programmers (not vibe coders), we often need to explicitly guide the agent by telling it how to implement things, this lack of feedback can get quite intolerable as implementation details must be kept in one’s head.

For the record, most chatbot UIs are generally not much better than the terminal either. ChatGPT is essentially the same thing, because you’re entering a prompt into a tiny text box that offers no feedback until you submit the prompt. ChatGPT is designed to do almost exactly as you say with little to no room for pushback (outside of loosely defined guardrails), which if used incorrectly can further cognitive biases (eg. Look at the agreeableness phenomenon). It’s basically a glorified terminal for AI inference!

People seem to like TUIs because they often don’t suffer the same complexities or performance issues found in traditional GUIs. I say we should just make GUIs that aren’t just glorified command centers. The GUI was meant to be an explorable medium for learning and not a command center for poor thought. Regardless, I think this TUI trend highlights an important aspect of GUIs that we at large haven’t been taking advantage of, or much less even thought of in the first place.

* = In Progress

New Mediums

• Locality of Decisions*
  • Goes over the disasters of one-size-fits-all decision making, and what we need to do to move away from this paradignm.
• Redesigning Code Editors, A Conceptual Overview
  • I’ve written quite a few notes on why I believe modern code editors are quite bad at building systems, but great at writing text. Though, I’ve yet to show any concrete examples of what a “better editor” looks like (Hint: Agentic coding in its widespread form isn’t the solution).
• Flying around the Aspects of Abstraction
  • An alternative POV to Bret Victor’s Up and Down the Ladder of Abstraction.
• Mutual Ink, Creative Software and The Collaborative Interface*
  • Depending on how things go, I may merge the stuff on code editors into this piece. Mutual Ink is an app that I’m currently working on in my free time that attempts to make LLMs (and particularly local ones) be seen as tools that can help us think better rather than take the thinking from us.

Building Products and Tools

• How I used the Physical World to Enhance App Design
  • Goes over an experience I had recently in developing Mutual Ink in which I laid out a grid of objects on my bed to design a fault-tolerant and iCloud syncable navigation system.
• The Agent Framework, Why Cactus is Better than FoundationModels*
  • I’ve already shipped low level Swift bindings to work with LLMs powered by the Cactus inference engine. The engine itself is very fast, efficient, optimized specifically for ARM, and supports many different models.
  • However, FoundationModels, though less technically impressive, has an API that’s much easier to use, and thus will likely see more adoption despite its flaws.
  • This later point is why I’m currently developing an agent framework for Cactus in my free time. The TLDR is that the vision is “SwiftUI for dynamic inference and processes”. That is, creating a traditional multi-step agent workflow is at the same level of difficulty as creating a SwiftUI view.

This is the “unclean” version.

package fromRoman;

import java.util.Arrays;

public class FromRoman {
  public static int convert(String roman) {
    if (roman.contains("VIV") ||
      roman.contains("IVI") ||
      roman.contains("IXI") ||
      roman.contains ("LXL") ||
      roman.contains ("XLX") ||
      roman.contains("XCX") ||
      roman.contains ("DCD") ||
      roman.contains ("CDC") ||
      roman.contains ("MCM")) {
      throw new InvalidRomanNumeralException(roman);
    }
    roman = roman.replace ("IV", "4");
    roman = roman.replace ("IX", "9");
    roman = roman.replace ("XL", "F");
    roman = roman.replace ("XC", "N");
    roman = roman.replace ("CD", "G");
    roman = roman.replace ("CM", "0");
    if (roman.contains "IIII") ||
      roman.contains ("VV") ||
      roman.contains ("XXXX") ||
      roman.contains ("LL") ||
      roman.contains ("CCCC") ||
      roman.contains ("DD") ||
      roman.contains ("MMMM")) {
      throw new InvalidRomanNumeralException(roman);
    }
    int[] numbers = new int [roman.length()];
    int i = 0;
    for (char digit : roman.toCharArray ()) {
      switch (digit) {
        case 'I' -> numbers [i] = 1;
        case 'V' -> numbers [i] = 5;
        case 'X' -> numbers[il = 10;
        case 'L' -> numbers [i] = 50;
        case 'C' -> numbers [i] = 100;
        case 'D' -> numbers [i] = 500;
        case 'M' -> numbers[i] = 1000;
        case '9' -> numbers[i] = 9;
        case 'F' -> numbers[il = 40;
        case 'N' -> numbers[i] = 90;
        case 'G' -> numbers[il = 400;
        case 'O' -> numbers|i] = 900;
        case '4' -> numbers|i] = 4;
        default -> throw new InvalidRomanNumeralException(roman);
      }
      i++;
    }
    int lastDigit = 1000;
    for (int number: numbers) {
      if (number > lastDigit) {
        throw new InvalidRomanNumeralException(roman);
      }
      lastDigit = number;
    }
    return Arrays.stream(numbers).sum();
  }
}
        

This is the “clean” version.

package fromRoman;
import java.util.Arraylist;
import java.util.List;
import java.util.Map;

public class FromRoman {
  private String roman;
  private List<Integer> numbers = new Arraylist<>();
  private int charIx;
  private char nextChar;
  private Integer nextValue;
  private Integer value;
  private int nchars;
  Map<Character, Integer> values = Map.of(
    'I', 1,
    'V', 5,
    'X', 10,
    'L', 50,
    'C', 100,
    'D', 500,
    'M', 1000
  );

  public FromRoman(String roman) {
    this.roman = roman;
  }

  public static int convert(String roman) {
    return new FromRoman(roman).doConversion();
  }

  private int doConversion() {
    checkInitialSyntax();
    convertLettersToNumbers();
    checkNumbersInDecreasingOrder();
    return numbers.stream().reduce(0, Integer:: sum);
  }

  private void checkInitialSyntax() {
    checkForIllegalPrefixCombinations();
    checkForImproperRepetitions();
  }

  private void checkForIllegalPrefixCombinations() {
    checkForIllegalPatterns (
      new String[]{"VIV", "IVI", "IXI", "IXV", "IXI", "XIX", "XCX", "XCL", "DCD", "CDC", "CMC", "CMD"}
    );
  }

  private void checkForImproperRepetitions() {
    checkForIllegalPatterns(
      new String[]{"IIII", "VV", "XXXX", "LL", "CCCC", "DD", "MMMM"}
    )
  }

  private void checkForIllegalPatterns(String[] patterns) {
    for (String badstring : patterns)
      if (roman.contains (badstring))
        throw new InvalidRomanNumeralException (roman);
  }

  private void convertlettersToNumbers() {
    char[] chars = roman.toCharArray();
    nchars = chars. length;
    for (charIx = 0; charIx < nchars; charIx++) {
      nextChar = isLastChar() ? 0: chars[charIx + 1];
      nextValue = values.get(nextChar);
      char thisChar = chars[charIx];
      value = values.get(thisChar);
      switch (thisChar) {
        case 'I' -> addvalueConsideringPrefix('V', 'X');
        case 'X' -> addValueConsideringPrefix('L', 'C');
        case 'C' -> addValueConsideringPrefix('D', 'M');
        case 'V', 'I', 'D', 'M' -> numbers.add(value);
        default -> throw new InvalidRomanNumeralException(roman);
      }
    }
  }

  private boolean islastChar() {
    return charIx + 1 == nchars;
  }

  private void addValueConsideringPrefix(char pl, char p2) {
    if (nextChar == pl || nextChar == p2) {
      numbers.add(nextValue - value);
      charIx++;
    } else numbers.add (value);
  }

  private void checkNumbersInDecreasingOrder() {
    for (int i = 0; i < numbers.size() - 1; i++)
      if (numbers.get(i) < numbers.get(i + 1))
        throw new InvalidRomanNumeralException(roman);
  }
}
        

And this is “Future Bob’s” comments on the “clean” version.

Two months later I'm torn. The first version, ugly as it was, was not as chopped up as this one. It's true that the names and the ordering of the extracted functions read like a story and are a big help in understanding the intent; but there were several times that I had to scroll back up to the top to assure myself about the types of instance variables. I found the choppiness, and the scrolling, to be annoying. However, and this is critical, I am reading this cleaned code after having first read the ugly version and having gone through the work of understanding it. So now, as I read this version, I am annoyed because I already understand it and find the chopped-up functions and the instance variables redundant.

Don't get me wrong, I still think the cleaner version is better. I just wasn't expecting the annoyance. When I first cleaned it, I thought it was going to be annoyance free.

I suppose the question you should ask yourself is which of these two pieces of code you would rather have read first. Which tells you more about the intent? Which obscures the intent?

Certainly the latter is better in that regard.

This annoyance is an issue that John Ousterhout and I have debated. When you understand an algorithm, the artifacts intended to help you understand it become annoying. Worse, if you understand an algorithm, the names or comments you write to help others will be biased by that understanding and may not help the reader as much as you think they will. A good example of that, in this code, is the addValueConsideringPrefix function. That name made perfect sense to me when I understood the algorithm. But it was a bit jarring two months later. Perhaps not as jarring as 49FNGO, but still not quite as obvious as I had hoped when I wrote it. It might have been better written as numbers.add (decrementValueIfThisCharIsaPrefix); , since that would be symmetrical with the numbers.add(value); in the nonprefixed case.

The bottom line is that your own understanding of what you are cleaning will work against your ability to communicate with the next person to come along. And this will be true whether you are extracting well-named methods, or adding descriptive comments. Therefore, take special care when choosing names and writing comments; and don't be surprised if others are annoyed by your choices. Lastly, a look after a few months can be both humbling and profitable.

It’s true that the “cleaned” version does a better job at describing the overall process of what is actually going on here, especially if you can read the entire thing on one screen. However, modern editors will not show you the entirety of the code all at once (rather only ~50 lines at a time), hence the scrolling annoyance.

When you scroll, you have to keep the context you can’t see in your head. Given that code is a precise artifact, you’ll find that you can’t easily hold the code for entire functions in your head. This will cause you to constantly stumble and force you to refresh the knowledge by scrolling back up to the previous code (or by jumping to another file in some cases).

The interesting thing is that in UI design circles, the code would be seen as information that needs to be presented with a more clear visual hierarchy. Thus, the solution would be to find a way to present the literal code itself in a much more intuitive manner (ie. Don’t hide the important parts by default!).

In programming circles, we simply blame the programmer for poor UI design choices of the editor, and tell them to refactor.

First and foremost, the biggest problem currently with these tools for those trying to build systems as that the tools aren’t designed to augment thinking but rather automate creation. From a systems understanding standpoint, this can be disastrous, and as such it’s hard to use these tools directly for systems understanding purposes. This is quite a let down, and is something that I hope to address through future work.

However, that doesn’t mean these tools are absolutely useless, and surely they do make one “more productive” if used correctly. By “more productive”, I don’t necessarily mean just a faster shipping pace, but rather a combination of speed and enhanced output (ie. Less “breaking things” while keeping the “moving fast” part). The enhanced output part is what we need to focus on, and is what can make us stand out compared to just those who focus on speed.

The key thing to note is that right now the tools have been primarily focused on code generation, but for most technical work that’s maybe ~10%-20% of the entire battle. A lot more work is needed to “understand and design processes” in a specified environment which includes, but is not solely limited to the programming languages used in the system.

Of course, if you repeatedly implement the same or highly similar simple technical designs (eg. Simple CRUD operations, UI components, etc.) over and over again for different features or systems, this repetition is ripe for automation with AI. Even such, you still need to spend time understanding exactly what was generated to avoid problems down the line.

In 2024 (before the term “vibe coding” was coined) I spent the later part of 6-8 weeks building and refining an internal tool for test automation in Rust. A lot of this time was spent implementing a custom DSL, implementing a code generation pipeline, and building a custom UI framework for Slack due to the large amount of views the tool needed. These are tasks that are more novel, and tend not to be suited to today’s AI tools.

However, another large chunk of time was spent writing more typical database queries, network calls, and the individual Slack UI components themselves. These are quite repetitive and simple tasks, and I imagine a rewrite with today’s AI tools could have saved a lot of time on this part.

So in my experience, most CRUD operations and pure UI views can be quite automateable depending on the circumstances. On a personal note, it seems that I would have more fulfillment working on systems that are more than just CRUD and UI views in that case. For instance, most library code I write tends to have more novel traits and requires more precision, so I’ve found AI tools to be way less useful there.

Though another set of cases that I’ve found vibe coding to be useful relates to one-off tools, prototypes, and scripts that accomplish a single simple task (one tool example that’s visible) that supports the development of the larger system. Instead of spending potentially hours building an entire UI for an incredibly simple tool, it’s much easier to just ask Lovable to do the job for me so that I can get on with doing the more interesting design work.

Though overall, for more difficult systems the bottleneck usually isn’t the code, but rather the design or human element. In cases like these, I do think the culture tends to exaggerate how positively impactful AI is.

The last century brought us AI, personal computing, and the internet. These themselves were exponential leaps, similar to the printing press in the 15th century (which kicked off parts of the Renaissance and subsequent Scientific revolutions).

The point here is that we have notions of exponential progress, but we don’t have systems in place to drive such progress like we do for incremental progress.

Every year, new products will be released in various industries that are better than existing products on the market, but that don’t fundamentally change the way business is conducted for the better.

The same can’t be said for creating entirely new industries from scratch. For instance, ideas in computing today are largely similar to the ideas in computing of the 60s and 70s, just with more incremental progress (ie. faster hardware, C -> Rust/Zig/Go, etc.). Many existing industries have certainly evolved with the advent of computing, but the fundamental ideas of those industries remain largely the same. Computing itself only provided an increment, though more like a +10 rather than a traditional +1.

I have many reasons to suspect why we don’t have a similar system for the exponentials, but it’s too much to write about here.

Instead, I’ll leave an observation that exponential progression leaps tend to come from solving “non-clear” problems (ie. Needs > wants, non-incremental). Nearly all business settings, including startups, only tend to succeed when they solve “clear” problems (ie. Wants > needs, often incremental). This skews funding towards solving “clear” and incremental problems instead of “non-clear” and non-incremental problems, which is probably why we haven’t gotten anything like Xerox PARC since the 70s.

With all that said, it’s not hard to see a potential reason for why we don’t have a system of exponential progress.

Anyone can pull out a piece of paper and start sketching, but not everyone becomes an illustrator. Often those who aren’t illustrators use sketching for their own more ephemeral needs.

Everyone learns basic math in school, but not everyone becomes a mathematician. Often those who are not mathematicians use arithmetic for their own more ephemeral needs.

Anyone can take pictures with a decent camera using their phone, but not everyone becomes a photographer. Often those who are not photographers take photos for their own more ephemeral (or authentically lasting) needs.

Anyone can build a working software system through vibe coding, but not everyone becomes a software engineer. Often those who are not software engineers use code for their own more ephemeral needs.

The idea of having amateur creators is not exclusive to AI and vibe coding, and in general this democratization of creation is a good idea. However, the quality of the creations themselves also have to be substantially good, and currently I don’t believe AI is doing this to the extent it needs to be.

Partially, this is due to the proliferation of bland chatbot interfaces that don’t encourage better thinking, but rather encourage outsourcing that thinking instead. Also partially, much of the social culture and media coverage that misrepresents AI to key decision makers is also problematic. (eg. 90% of code being AI generated does not indicate that anywhere even close to 90% of an engineer’s purely technical duties have been automated.)

Many others online seem to agree that the outsourcing is a problem. Unfortunately, just telling people to stop outsourcing their understanding isn’t going to solve this problem in a scalable manner. You also need to design tools that don’t encourage such outsourcing, but rather augment thinking instead. This will be my intention when desiging such tools.

The following was my response.

There is a lot of valid information in here, especially around the fact of not trying to hide all the information for why a particular decision was made.

For me, I still treat the idea of “clean code” as a UI design problem, in which the code and editor are the UI for editing the system. In effect, that means that the editor matters just as much as the code, because the editor can choose which parts to show and hide. So in practice, a lot of our techniques for organizing code have to be based around how the editor shows and hides code.

However, the problem is that our modern editors are quite terrible when it comes to larger systems (even with agentic AI). Larger systems (including our last project) often contain line counts at least in the 10s of thousands, but your editor can only show ~50 lines of code on a singular screen at any given point in time. In essence, modern editors have pinpointed their focus on writing text rather than creating systems.

This is why people hate the small function style presented in the Clean Code book. It’s solely because widespread editors make reading and understanding many small functions incredibly difficult due to the context you have to keep in your head that your editor doesn’t visualize.

For example, take this function.

async function generateReportFor(user) {
  const isValid = validateUser(user)
  if (!isValid) throw new Error("Invalid user")

  const transactions = await transactionsFor(user)
  const defects = await defectsIn(transactions, user)
  const totalParts = await totalPartsFor(transactions, user)
  return new Report(transactions, defects, totalParts)
}
        

Many would say this is poorly written because they would have to jump from validateUser to transactionsFor to defectsIn to totalPartsFor in their editor. Yet reading just this high level function shows you the outline of how a report is generated better than if all of the step functions were inlined.

The problem here is that the individual code from the step functions is also very important, yet modern editors will not show it alongside the high-level function. Due to this, it’s often considered better code to just inline the step functions and create 1 very large function instead where all the details can be seen on a single screen. This latter part has many of its own problems (eg. creating a tightly coupled mess) that often arise as time progresses.

In other words, in many cases we’re really working around poor UI design decisions taken by modern code editors, and pretending like the code is the problem. The attached images below show other aspects of this problem in more detail.

IMO, a good (mature) library has 2 strong design traits:

1. An easy to use high-level API that achieves a task with minimal effort.
2. A extensive low-level API that offers so much control such that the higher-level API can be completely re-written from the ground up externally if need be.

Of these traits, the second is definitely the more important aspect for real-world/long-term use, and is my first task when creating a new library. The first point largely exists as a necessary consequence to gain adoption, or to provide an answer to the common cases. IMO, it’s much more of a nice to have, and can come later down the line in development.

In Swift Operation, I made it a priority to give you the tools to reconstruct the higher level API if necessary. That is, if you don’t like a built-in API (eg. The retry API), you should be able to implement your own version of it that’s tailored to your needs.

SQLiteData also did a good job at providing both higher and lower level control. On one hand, it exposes the @Fetch property wrapper which @FetchAll and @FetchOne build on top of. Additionally, it provides low-level tools that integrate StructuredQueries with GRDB, so you’re not tied to the property wrappers.

GRDB does this well too. It offers convenience APIs around transactions that work in 99% of scenarios, and the remaining 1% of cases allow you to reconstruct the way transactions work if needed. You can also write raw SQL alongside using its more convenient record request interface. StructuredQueries also does this latter part well.

Now for some counterexamples.

Tanstack Query did a good job at the higher level API, but its lower level could use some reconstructing. For instance, I can’t replace the built-in retry mechanism easily, or add composable behavior to queries or mutations.

Cactus did a good job providing a lower-level C FFI, but the official client libraries leave quite a lot to be desired. They seem to want to hide the complexities of model downloading, but also surface the low-level details of the FFI alongside those higher level details. At the same time, they had the library handle concurrency concerns for you, which may not align with your application’s desired workflow.

In Swift Cactus, I provide a higher level API for model downloading, but I also allow you to construct a CactusLanguageModel directly from a URL. Additionally, I made the language model run synchronously which gives the caller more control over which thread it runs on. This takes more work on the caller’s end to put the model behind an actor, but the synchronous nature also lets you put a mutex around an individual model instance if you want to keep thread-safe synchronous access. This later approach is very useful for things like generating vector embeddings inside a synchronous database function.

A higher level agentic framework is currently in the works for Swift Cactus as I’m writing this. Here, you have less control over concurrency (mainly due to tool calling), but I think the resulting API should feel a lot easier to use once it’s completed. Despite all of this, the higher level agentic framework is built entirely on top of the existing lower level tools that you can use today, and you should be able to reconstruct parts of the agentic framework as you see fit.

This was a project shared to me by a colleague which I found interesting because one of my favority hobbies in 5th grade was creating Super Mario World ROM hacks with Lunar Magic. Also, emulation was the reason that I was also able to enjoy many of the earlier Fire Emblem titles, and most notably Genealogy of the Holy War.

The main concerns I’ve read, myself included, seems to be the scope of the project. The former lead has an animation background, and clearly has an eye for aesthetics. Yet, he just announced including a social network, eshop, and much more (alongside the launcher) like it was no big deal. Since the presentation no longer exists, you can read this instead.

My most recent startup experience can be classified like the above with a somewhat similarly sized team as iiSU. In my case, we had a social fitness network in mind that was focused on physical events, an entire dynamic reflection journaling feature, and an entire literature narrative as an aesthetics layer (we even had drafts of chapters for this!). We got through rolling out the social network part, and a bit of the dynamic journaling part before really deciding that users actually wanted more of the later. Now we’re in the process of pivoting (new website for this will be up soon).

Regardless, it was worth it. I wouldn’t have taken on that project if it didn’t have a 90% chance of failure, and there were certainly lessons to be learned there from a business standpoint. Yet, the crucial thing is that if in theory the idea was executed properly, and received in the way we had hoped, then it could have made a significant impact on the way people perceived their health.

My philosophy since graduating has subsequently been to take on ambitious projects that have a 90% chance of failing, but if in the 10% chance that it succeeds, then it makes a huge difference. Swift Operation was one of those successes in my opinion, and I’ve used it extensively on every project I’ve undertaken since its release. Swift Cactus could be another in the future, it’s already gotten recognition from the cactus core team, and I’m currently working on making a higher-level framework that makes building with local models a lot more powerful than what you get with FoundationModels.

Of course, those 2 projects consist of just me in my free time, so the scope isn’t nearly as big as my professional work. However, I also have other projects of my own in the background that I believe are even more ambitious than the 2 above. I hope to have updates on those soon.

AFAIK, the primary dev of iiSU’s team seems like they know their stuff, and I think it would be theoretically possible for something to come out of this even if it isn’t everything that was envisioned in the now deleted presentation. At the very least, it seems like an interesting project to follow even if I’m not in the target audience.

Do the same with pictures of Dennis Ritchie, Bjarne Stroustrup, Ken Thompson, Brain Kernighan, and Linus Torvalds. Chances are they’ll recognize at least one of if not multiple of them if they’re interested in their craft. These people are largely responsible for the programming languages and operating systems they use.

Now do the same with Alan Kay, Doug Engelbart, Ivan Sutherland, and Ted Nelson. In the vast majority of cases that I’ve tried this, no one has been able to recognize even one of their pictures as well as their names. These people are largely responsible for the fact that they even have a laptop, desktop, or phone with the ability to interact in an online ecosystem today.

Rather unfortunately, the ideas of the last group that have largely been ignored, or butchered when implemented in today’s commercial products.

If you take modern “OOP” languages like Java, C++, Kotlin, Swift, etc. to be object-oriented, I recommend you really try to understand what Kay was getting at with the term “object-oriented” (also look at Sketchpad by Ivan Sutherland).

If you take the web to be a ubiquitous online ecosystem rich with discussion, convenience, and collaboration, then I recommend that you really look into the work of Doug Engelbart (especially this), Ted Nelson, and many others.

One modern sucessor to the work of these pioneers is Bret Victor and Dynamicland (which is very anti-Vision Pro). In fact, you can find archives of the work of many of the above pioneers on his website.

If anything, reading Designing Data Intensive Applications (source of the quote) has taught me that large centralized distributed systems that make high-stakes decisions for people are terrible ideas. From the technical standpoint, often the best state a large system can be in is “eventually consistent”. That is, a state in which not all necessary information (much of which is completely invisible to the end-user) is guaranteed to be present to make a proper decision at any given moment.

This isn’t even mentioning the fact that as system designers we are often making systemic decisions in contexts that don’t reflect the actual context in which the system operates in.

My take on this is that data and decision making power are best kept by the individual, and not the organization. Rather, it should be the job of the organization to enhance the decision making power of the individual (eg. Public education teaches us to read, and reading helps us make better decisions).

This is particularly why I’m interested in heavy client-side based software solutions in today’s landscape (eg. Native mobile apps, local LLMs) rather than remote/web based solutions. I try to limit the server side component as much as possible on small/solo projects. Often I find that it isn’t necessary to create a dedicated backend in the first place for many useful products outside of proxying requests to third parties.

Of course, long term I’m much more interested in tomorrow’s landscape, which ideally will embrace the idea of individual creative freedom far more than its predecessors. That is, I would rather we treat the masses as capable creators rather than “the audience”. The web and subsequent AI-driven culture fails horrifically at this.

The simple answer to this is that all the mainstream social media platforms are not designed for real creative expression. They’ve adopted the “easy to use, perpetual beginner” mindset, and have amplified it across billions of users. This is quite disastrous in my opinion.

On this website, I can use whatever HTML, CSS, and JavaScript I want to express my work. I can even embed entire interactable programs directly into my writing. (I wish to do this more in the future). On social media, you’re essentially limited to plain text, video, and photos, which is very rigid in comparison, and this is not even taking the “algorithm” into account.

I am very fortunate to have had the natural interest in technology and software, as well as the natural ability to understand the complex abstact concepts that have enabled me to unlock this kind of expression in my work. This is not most of the world, and it’s quite saddening to see that they get much more limited forms of expression.

Text on a black background, simple photos, and static videos delivered to a one-size-fits-all audience and displayed in a 6-inch rectangle are not powerful enough mediums to communicate complex ideas that determine the direction of society. Much of these ideas rely on trends in large complex datasets, or disastrous things we cannot see (eg. The climate problem). From a UI design standpoint, static content isn’t enough to convey everything that’s needed with this complexity.

Additionally, centralized large-scale algorithms that make the decisions on what media to surface are also not ideal when those decisions are made based on impulsive trends. Nearly all influential media in the world (eg. The US Constitution, “Common Sense”) did not use extensive emotional/moral baiting rhetoric to convey their ideas in the way we see on social media today. Thomas Paine didn’t need to participate in the “attention economy” in writing “Common Sense”, which was one of the influential documents in the wake of the American Revolution.

It’s true that my “visibility” on this site is far lower than if I were more active on social media, but my intention is only merely to reach an audience with the capable creative abilities to seek something greater. If you’re reading this of your own accord, there’s a high chance that you have such ability, and you’re exactly the type of person that I’m trying to reach.

Now the real question is why does Xcode need to take up so much space? Even more importantly, why does Xcode go to such lengths to hide the actual contents of the things it stores? This much invisibility is not very nice…

Caches = storing information that allows us to access information…

The interesting thing is that the idea of disk-based storage forces us to think in very abstract terms since you can’t visually see what’s being stored, which most human minds massively fail at. MacOS also likes to put a “user-friendly facade” around the whole thing, because a lot of that storage is taken by various caches and internal application data. This facade comes with the tradeoff that the larger part of society is completely oblivious as to what their machines are actually doing.

I like how the ping-ponging of actions has been taken away, this was extremely annoying, and I generally gated all of these ping-ponging actions inside an Effect enum. Eg.

// This

@Reducer
struct Feature {
  // ...

  enum Action {
    case buttonTapped
    case effect(Effect)

    enum Effect {
      case dataLoaded(Result<SomeData, any Error>)
    }
  }

  var body: some ReducerOf<Self> {
    Reduce { state, action in
      switch action {
      case .buttonTapped:
        return .run { send in
          let result = await Result { try await someWork() }
          await send(.effect(.dataLoaded(result))
        }
      case .effect(.dataLoaded(let result)):
        // ...
      }
    }
  }
}

// Now Becomes This

@Reducer
struct Feature {
  // ...

  enum Action {
    case buttonTapped
  }

  var body: some ReducerOf<Self> {
    Reduce { state, action in
      switch action {
      case .buttonTapped:
        return .run { store in
          let result = await Result { try await someWork() }
          try store.modify { /* Just set state in here */ }
        }
      }
    }
  }
}
        

With the old way of doing things, it was quite easy to lose focus of the overall control flow.

In terms of Store vs StoreActor, I would rather that they also have a non-Sendable store type, and simply wrap the actor isolation on top. This is what I did with CactusLanguageModel in Swift Cactus, and the flexibility is quite nice. I can choose to call the language model synchronously in a thread-safe manner using Mutex, or asynchronously by wrapping it in an actor. I think it should be the same for the store as well.

onMount and onDismount are also healthy additions, especially since they’re not tied to any one view system (which I presume is necessary for the cross platform support they want to achieve). Long ago, in one of my first apps, I remeber defining the notion of an AppearableAction which essentially tried to automate the whole onAppear and onDisappear dance. Suffice to say, onMount and onDismount are better than those tools.

The new onChange behavior is also very welcome, and it’s definitely more intuitive.

I also presume the removal of BindingReducer is a natural consequence of wanting to make things cross platform.

I like the overall direction of turning features into descriptions rather than imperative messes. Swift itself is still quite imperative though which is admittedly annoying.

-- Minutes to Read

Visions - not goals, not plans

Just Doing - not consistency, not discipline

Showcases - not deadlines, not accountability

Meaning - not numbers, not just results

Great Ideas - not just execution, not just implementation

Deep Thinking - not just action, not quick reactions

Equal Collaboration - not juniors, not seniors

Though such “nots” may be imposed on me, and it will probably look like I’m adhering to them, they are the enemies of great work if I am chained to them internally.

Giving a professional illustrator a goal for a poster usually results in what was desired. If one tries this with an artist, one will get what the artist needed to create that day. Sometimes we make, to have, sometimes to know and express. The pursuit of Art always sets off plans and goals, but plans and goals don't always give rise to Art. If "visions not goals" opens the heavens, it is important to find artistic people to conceive the projects.

Thus the "people not projects" principle was the other cornerstone of ARPA/PARC’s success. Because of the normal distribution of talents and drive in the world, a depressingly large percentage of organizational processes have been designed to deal with people of moderate ability, motivation, and trust. We can easily see this in most walks of life today, but also astoundingly in corporate, university, and government research. ARPA/PARC had two main thresholds: self-motivation and ability. They cultivated people who "had to do, paid or not" and "whose doings were likely to be highly interesting and important". Thus conventional oversight was not only not needed, but was not really possible. "Peer review" wasn't easily done even with actual peers.

The situation was "out of control", yet extremely productive and not at all anarchic. "Out of control" because artists have to do what they have to do. "Extremely productive" because a great vision acts like a magnetic field from the future that aligns all the little iron particle artists to point to “North” without having to see it. They then make their own paths to the future. Xerox often was shocked at the PARC process and declared it out of control, but they didn't understand that the context was so powerful and compelling and the good will so abundant, that the artists worked happily at their version of the vision. The results were an enormous collection of breakthroughs, some of which we are celebrating today.

— Alan Kay (The Power of Context)

-- Minutes to Read

I recently dove into looking at Bitwarden’s iOS codebase for fun, and to find resources for other engineers that I work with to learn native the native mobile languages. Since Bitwarden is quite large, they actually have to take architecture seriously from a code readability, testability, and maintainability standpoint, and not leave it off as a nice to have.

Regardless, I saw a lot of massive protocols like this.

protocol AuthService {
    var callbackUrlScheme: String { get }

    func answerLoginRequest(_ request: LoginRequest, approve: Bool) async throws

    func checkPendingLoginRequest(withId id: String) async throws -> LoginRequest

    func denyAllLoginRequests(_ requests: [LoginRequest]) async throws

    func generateSingleSignOnUrl(from organizationIdentifier: String) async throws -> (url: URL, state: String)

    func getPendingAdminLoginRequest(userId: String?) async throws -> PendingAdminLoginRequest?

    func getPendingLoginRequest(withId id: String?) async throws -> [LoginRequest]

    func hashPassword(password: String, purpose: HashPurpose) async throws -> String

    func initiateLoginWithDevice(
        email: String,
        type: AuthRequestType
    ) async throws -> (authRequestResponse: AuthRequestResponse, requestId: String)

    func loginWithDevice(
        _ loginRequest: LoginRequest,
        email: String,
        isAuthenticated: Bool,
        captchaToken: String?
    ) async throws -> (String, String)

    func loginWithMasterPassword(
        _ password: String,
        username: String,
        captchaToken: String?,
        isNewAccount: Bool
    ) async throws

    func loginWithSingleSignOn(code: String, email: String) async throws -> LoginUnlockMethod

    func loginWithTwoFactorCode(
        email: String,
        code: String,
        method: TwoFactorAuthMethod,
        remember: Bool,
        captchaToken: String?
    ) async throws -> LoginUnlockMethod

    func requirePasswordChange(
        email: String,
        isPreAuth: Bool,
        masterPassword: String,
        policy: MasterPasswordPolicyOptions?
    ) async throws -> Bool

    func resendVerificationCodeEmail() async throws

    func resendNewDeviceOtp() async throws

    func setPendingAdminLoginRequest(_ adminLoginRequest: PendingAdminLoginRequest?, userId: String?) async throws

    func webAuthenticationSession(
        url: URL,
        completionHandler: @escaping ASWebAuthenticationSession.CompletionHandler
    ) -> ASWebAuthenticationSession
}
        

This protocol has 18 requirements, which is quite a lot.

However, I’ve also seen such large protocols parroted around as general advice, though not explicitly. No one is literally saying, “You should make protocols as large as possible!”, but you probably have heard of something called the Repository pattern. An average Repository protocol looks like this.

protocol NotesRepository {
  func findNote(by id: UUID) async throws -> Note?
  func allNotes(for notebookId: UUID?) async throws -> [Note]
  func findNotes(by text: String) async throws -> [Note]

  func save(note: Note) async throws

  func moveNote(from srcNotebookId: UUID, to dstNotebookId: UUID) async throws
  func deleteNote(with ids: Set<UUID>) async throws
}
        

Even still, 6 protocol requirements is quite a lot. Most protocols that you conform to from most libraries and frameworks, including Apple’s, do not have nearly as many requirements. Or, if those protocols do have lots of requirements, it’s usually an some kind of “delegate” protocol where most of the requirements are optional, and you only end up implementing a small subset of the requirements most of the time.

I would rather have something like this instead of NotesRepository. Where each protocol defines a small class of cohesive functionality.

protocol NoteSaver {
  func save(note: Note) async throws
}

protocol NoteMover {
  func moveNote(from srcNotebookId: UUID, to dstNotebookId: UUID) async throws
}

protocol NoteDeleter {
  func deleteNote(with ids: Set<UUID>) async throws
}

protocol NoteFinder {
  func findNote(by id: UUID) async throws -> Note?
  func allNotes(for notebookId: UUID?) async throws -> [Note]
  func findNotes(by text: String) async throws -> [Note]
}
        

Inevitably, this will turn into a piece about what an optimal protocol size is. Naturally, my answer is of course that “it depends”, but it’s usually not the kind of large protocols that you more commonly see in the wild. Rather, it’s about leaving open as many different conformance possibilities as possible, and large protocols with many requirements tend to not provide many conformance possibilities.

The Case Against Large Protocols

Before jumping in, I don’t want to give the impression that such protocols are always bad. Large protocols are fine if the context they are used in has an answer for the generalized case that I will bring against them.

There are 2 primary pain points that I have with large protocols. First, is the fact that often no parts of your app need to depend on the entire protocol, but rather only a few requirements of it at a time. Second, larger protocols are harder to conform to in general, and are harder to compose (ie. Creating large pieces of functionality by composing smaller conformance’s together).

The main point that you should take away from this is that smaller and easier it is to conform to a protocol, you obtain more possibilities for implementing that protocol. This in turn gives you more options when you need to add or modify a feature in your code.

Unnecessary Dependence

The functionality that often depends on large protocols often only needs a small subset of the requirements (typically only 1-3 in 90% of cases).

For instance, this could be a pure SwiftUI view, view model, or TCA reducer for a UI component only needs to depend on functionality that performs the data actions taken by the user. This could be something like adding a new note an HTTP API when a new note is created through a form. In this case, such a pure view, view model, or reducer only needs to depend on this protocol.

protocol NoteSaver {
  func save(note: Note) async throws
}
        

Yet instead, we often end up depending on this.

protocol NotesRepository {
  func findNote(by id: Int) async throws -> Note?
  func allNotes(for notebookId: Int?) async throws -> [Note]
  func findNotes(by text: String) async throws -> [Note]

  func save(note: Note) async throws

  func moveNote(from srcNotebookId: Int, to dstNotebookId: Int) async throws
  func deleteNote(with ids: Set<Int>) async throws
}
        

If we’re using Xcode previews, it would be wise to be able to preview what our UI is like when the save operation invoked by a note creation form fails. This allows us to experience the user’s pain as they try-try-try again to use our broken app. We’ll likely rely on a mock to achieve this, because this makes it easy to put the UI in a failing state.

Since our NoteSaver protocol only has a single requirement, creating a mock is quite easy. In fact, we can just create it directly in the preview block because it’s so easy. We can even throw in some fake delay, just to simulate the mindless wait that our frustrated user will experience for real.

struct AddNoteForm: View {
  init(saver: any NoteSaver) {
    // ...
  }
  // ...
}

#Preview {
  struct FailingSaver: NoteSaver {
    func save(note: Note) async throws {
      struct SomeError: Error {}

      try await Task.sleep(for: .seconds(3))
      throw SomeError()
    }
  }

  AddNoteForm(saver: FailingSaver())
}
        

Ok… Now let’s decrease the delay to see what happens to a user with a higher speed connection.

#Preview {
  struct FailingSaver: NoteSaver {
    func save(note: Note) async throws {
      struct SomeError: Error {}

-      try await Task.sleep(for: .seconds(3))
+      try await Task.sleep(for: .seconds(1))
      throw SomeError()
    }
  }

  AddNoteForm(saver: FailingSaver())
}
        

I can easily do this because our FailingSaver is quite small and is easy to change in isolation without affecting other views.

Now instead of depending on small protocol, let’s try previewing AddNoteForm this while depending on our larger NoteRepository protocol.

struct AddNoteForm: View {
  init(saver: any NoteRepository) {
    // ...
  }
  // ...
}

#Preview {
  struct FailingSaver: NoteRepository {
    func findNote(by id: Int) async throws -> Note? { nil }
    func allNotes(for notebookId: Int?) async throws -> [Note] { [] }
    func findNotes(by text: String) async throws -> [Note] { [] }

    func save(note: Note) async throws {
      struct SomeError: Error {}

      try await Task.sleep(for: .seconds(3))
      throw SomeError()
    }

    func moveNote(from srcNotebookId: Int, to dstNotebookId: Int) async throws {}
    func deleteNote(with ids: Set<Int>) async throws {}
  }

  AddNoteForm(saver: FailingSaver())
}
        

There’s just so many extra requirements to implement here. Having a bunch of adhoc conformances to NoteRepository would be quite annoying. Often, most apps will just create a single mock, and reuse it everywhere because creating many conformance’s is quite annoying. This mock will need to get large to accommodate artificial failure modes.

// In some other file...

// This is the only mock conformance to NoteRepository in the app.
final class MockNotesRepository: NoteRepository {
  var notes = [Int?: [Note]]()
  var savedNotes = [Note]()
  var saveError: (any Error)?
  var moveError: (any Error)?
  var deleteError: (any Error)?

  func findNote(by id: Int) async throws -> Note? {
    // ...
  }

  func allNotes(for notebookId: Int?) async throws -> [Note] {
    // ...
  }

  func findNotes(by text: String) async throws -> [Note] {
    // ...
  }

  func save(note: Note) async throws {
    // ...
  }

  func moveNote(from srcNotebookId: Int, to dstNotebookId: Int) async throws {
    // ...
  }

  func deleteNote(with ids: Set<Int>) async throws {
    // ...
  }
}
        

Now, if we want to add our artificial delay to saving a note, we have to update the global mock that’s used by all previews. Others may want to do the same, and this leads to contention, and bloating the mock with all sorts of weird functionality.

If we’re like Bitwarden, or we don’t want to end up with code that regresses constantly, we’ll also likely have a test suite (though this may be considered optional for some code bases). It turns out that being able to spin up adhoc mocks is also quite useful in those cases. For instance, if we drive AddNoteForm with an Observable model, we may end up with this.

@Observable
class AddNoteFormModel {
  init(saver: any NoteSaver) {
    // ...
  }
  // ...
}

@Test("Shows Alert When Failing To Add Note")
func showsAlertWhenFailingToAddNote() async throws {
  struct FailingSaver: NoteSaver {
    func save(note: Note) async throws {
      struct SomeError: Error {}
      throw SomeError()
    }
  }

  let model = AddNoteFormModel(saver: FailingSaver())
  model.title = "My note"
  model.contents = "This is fun"

  #expect(model.alert == nil)
  await model.submitted()
  #expect(model.alert == .failedToSaveNote)
}
        

If we had made AddNoteFormModel depend on NotesRepository, this process would again be cumbersome, and we would likely have to resort to using our one and only MockNotesRepository.

Now, I don’t think reusing a mock conformance is a bad idea. In fact, it’s a great idea! However, a mock that’s reused everywhere also cannot always have its behavior adjusted for a one-off experiments, previews, or test cases. Continuously adjusting a shared mock in these ways would lead to the shared mock becoming large, complicated, and harder to change over time.

Difficulty of Conformance

Think of protocols as a set of possibilities. That is, a protocol defines a subset of types that conform to it. The Equatable protocol defines the subset of types that have an equality mechanism, and likewise SwiftUI’s View protocol defines the subset of types that can be rendered in a user interface. The harder it is to conform to the protocol, the smaller the subset is. Each type in the subset represents a different possibility of how its requirements are carried out.

In other words, protocols that are easy to conform to have many possibilities which means that you have many options for conforming to them. On the flip side, a protocol that is harder to conform to limits the number of options you have for making a conformance.

It goes without saying that smaller protocols are often easier to conform to, and therefore provide more possibilities.

With smaller protocols, you’re more likely to add new behavior to your app by creating a new conformance. With larger protocols, you’re more likely to make changes to the fewer existing conforming types you have directly in order to add new behavior.

Feed Filters DSL

Here’s a small protocol that we’ll call FeedFilter. A FeedFilter is a mechanism to filter out a specific content type from a typical social media feed. Note that in this example, there are multiple different content types, hence the Content associated type.

protocol FeedFilter<Content> {
  associatedtype Content

  func shouldIncludeInFeed(content: Content) async -> Bool
}
        

FeedFilter is an incredibly easy protocol to conform to, so let’s make our first conformance!

struct ThreadsExcludeIfControversialFilter: FeedFilter {
  let preferences: Preferences

  func shouldIncludeInFeed(content: Thread) -> Bool {
    self.preferences.threadFilterControvesyRate < content.downvotePercentage
  }
}
        

That was easy! Let’s make another!

struct ThreadsExcludeIfDownvotedFilter: FeedFilter {
  func shouldIncludeInFeed(content: Thread) -> Bool {
    content.userVote != .downvote
  }
}
        

Now, what if we want to create a filter that excludes thread if either the user downvoted them, or if the thread if controversial? We can certainly make a ThreadsExcludeIfDownvotedOrControversialFilter, but now we’re getting into AbstractSingletonProxyFactoryBean territory. All we’re trying to do either is run 1 filter before the other, so let’s make a simple conformance to do just that.

extension FeedFilter {
  func run(
    before other: some FeedFilter<Content>
  ) -> some FeedFilter<Content> {
    RunBeforeFilter(a: self, b: other)
  }
}

private struct RunBeforeFilter<
  A: FeedFilter,
  B: FeedFilter
>: FeedFilter where A.Content == B.Content {
  let a: A
  let b: B

  func shouldIncludeInFeed(content: A.Content) async -> Bool {
    guard await self.a.shouldIncludeInFeed(content: content) else {
      return false
    }
    return await self.b.shouldIncludeInFeed(content: content)
  }
}
        

Now we can easily create our downvotedOrControvesialFilter like so.

let downvotedOrControversial = ThreadsExcludeIfControversialFilter()
  .run(before: ThreadsExcludeIfDownvotedFilter())
        

In fact RunBeforeFilter works for any content type, and any 2 filters with the same content type. Now let’s try making another conformance that also doesn’t care too much about the content type. For instance, lots of scrollable content on social media contains some very forbidden words. Let’s make a filter to filter those words.

protocol HiddenPhrasesFilterable {
  var language: Language { get }
  var textBlocks: [(String, HiddenPhraseOptions)] { get }
}

struct HiddenPhrasesFilter<Content: HiddenPhrasesFilterable>: FeedFilter {
  let phrases: HiddenPhrases

  func shouldIncludeInFeed(content: Content) -> Bool {
    // Tokenize the content by word with NLTokenizer and use a trie
    // to efficiently match phrases in HiddenPhrases...
  }
}
        

I’ve omitted the implementation of HiddenPhrasesFilter for brevity, but suffice to say it used the algorithm described by the comment above. However, the main point was that we now have a filter that works on any kind of content that conforms to HiddenPhrasesFilterable.

Finally, let’s make a simple conformance that works with Comments instead of just Threads.

struct CommentExcludeIfNoRepliesFilter: FeedFilter {
  func shouldIncludeInFeed(content: Comment) -> Bool {
    content.replyCount > 0
  }
}
        

We can keep going, but the gist of this is that we can reuse filtering logic to create separate content filtering pipelines. I ended up with something like this.

extension FeedFilter where Content == Thread {
  static func defaultThreads(
    preferences: Preferences,
    accountsActor: some SavedAccountsActor
  ) -> some FeedFilter<Content> {
    NSFWFilter(preferences: preferences)
      .run(
        before: ThreadsExcludeIfUserDownvotedFilter()
          .onlyRunIf { preferences.shouldFilterDownvotedThreads }
      )
      .run(
        before: ThreadsExcludeIfControversialFilter(preferences: preferences)
          .onlyRunIf { preferences.shouldFilterControversialThreads }
      )
      .run(
        before: ContentMarkerFilter(
          accountsActor: accountsActor,
          contentMarker: .markedAsReadThreads
        )
        .onlyRunIf { preferences.shouldFilterThreadsMarkedAsRead }
      )
      .run(
        before: ContentMarkerFilter(
          accountsActor: accountsActor,
          contentMarker: .hiddenThreads
        )
      )
      .run(before: HiddenPhrasesFilter(phrases: preferences.hiddenPhrases))
      .keepingCurrentUserContent(using: accountsActor)
  }
}

extension FeedFilter where Content == Comment {
  static func defaultPosts(
    preferences: Preferences,
    accountsActor: some SavedAccountsActor
  ) -> some FeedFilter<Content> {
    NSFWFilter(preferences: preferences)
      .run(
        before: ContentMarkerFilter(
          accountsActor: accountsActor,
          contentMarker: .hiddenComments
        )
      )
      .run(
        before: CommentExcludeIfNoRepliesFilter()
          .onlyRunIf { preferences.shouldFilterUnrepliedComments }
      )
      .run(before: HiddenPhrasesFilter(phrases: preferences.hiddenPhrases))
      .keepingCurrentUserContent(using: accountsActor)
  }
}

// More content types...
        

Adding new filtering logic was incredibly easy, because FeedFilter was easy to conform to. The filters were also relatively isolated from each other, and only handled a small concern, which made them easy to compose together into a larger and more meaningful filter.

Composing Persistence Based Protocols

Now for a point of consideration, would you do what we did above with NotesRepository?

Likely not because in many cases you would find it cumbersome, but you’re probably also questioning why we would need to in the first place. NotesRepository is an interface that implements IO for notes, and that IO has a very specific data store (HTTP API, Local Database, etc.). Therefore, if the implementation is just simple IO calls, then why is there a need for the kind of composition that you see with FeedFilter?

This point is true in most cases with persistence, but that doesn’t mean that you want to leave out options arbitrarily. As long as the overall operation can be split into different parts cleanly, you can still rely on this composition. In fact, persistence has many mechanisms which are composable.

This composability is literally why I decided to author Swift Operation, and that library actually provides a similar DSL as FeedFilter for any async operation.

extension Post {
  static func query(for id: ID) -> some QueryRequest<Post, Query.State> {
    Self.$query(id: id).retry(limit: 3)
      .refetchOnChange(
        of: .connected(to: NWPathMonitorObserver.startingShared())
      )
      .deduplicated()
  }

  @QueryRequest
  private static func query(id: ID) async throws -> Post {
    // ...
  }
}
        

Just like that, we’ve configured retries, deduplication, and the ability to refetch the post when the user’s network connection flips from offline to online. This works for more than just network requests by the way, it also works for calls to Apple Frameworks, and much more.

You can create new building blocks of functionality by conforming to the OperationModifier protocol. For instance, here’s a simple one that adds artificial delay to an operation. You might wonder why you want to do that. It turns out that in Xcode previews, it’s very helpful to add such delay to see what the user experiences when their connection is slow.

struct DelayModifier<Operation: OperationRequest>: OperationModifier {
  let delay: TimeInterval

  func fetch(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    using operation: Operation,
    with continuation: OperationContinuation<Operation.Value>
  ) async throws -> Operation.Value {
    try await context.delayer.delay(for: delay)
    return try await operation.run(isolation: isolation, in: context, with: continuation)
  }
}

extension OperationRequest {
  func delay(for duration: TimeInterval) -> ModifiedOperation<Self, DelayModifier<Self>> {
    self.modifier(DelayModifier(delay: duration))
  }
}

@QueryRequest
func myQuery() async throws -> SomeData {
  // ...
}

let myQuery = $myQuery.delay(for: 0.3)
        

In the demo app for Swift Operation, I’ve even implemented such a modifier that persists the results of each query to a database. This allowed me to create dev tools that provide the opportunity to inspect any query made by the app. Thanks to SQLiteData, the results are even synced across iCloud, and can be viewed from any device.

extension StatefulOperationRequest where Self: Sendable {
  public func analyzed() -> ModifiedOperation<Self, _AnalysisModifier<Self>> {
    self.modifier(_AnalysisModifier())
  }
}

public struct _AnalysisModifier<
  Operation: StatefulOperationRequest & Sendable
>: OperationModifier, Sendable {
  public func run(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    using query: Operation,
    with continuation: OperationContinuation<Operation.Value, Operation.Failure>
  ) async throws(Operation.Failure) -> Operation.Value {
    @Dependency(\.defaultDatabase) var database
    @Dependency(\.continuousClock) var clock
    @Dependency(ApplicationLaunch.ID.self) var launchId
    @Dependency(\.uuidv7) var uuidv7

    let yields = Mutex([Result<Operation.Value, Operation.Failure>]())
    let continuation = OperationContinuation<Operation.Value, Operation.Failure> {
      result,
      context in
      yields.withLock { $0.append(result) }
      continuation.yield(with: result, using: context)
    }

    var result: Result<Operation.Value, Operation.Failure>!
    let time = await clock.measure {
      result = await Result { @Sendable () async throws(Operation.Failure) -> Operation.Value in
        try await query.run(isolation: isolation, in: context, with: continuation)
      }
    }

    let analysis = OperationAnalysis(
      id: OperationAnalysis.ID(uuidv7()),
      launchId: launchId,
      operation: query,
      operationRetryAttempt: context.operationRetryIndex,
      operationRuntimeDuration: time,
      yieldedResults: yields.withLock { $0 },
      finalResult: result
    )

    await withErrorReporting {
      try await database.write {
        try OperationAnalysisRecord.insert { OperationAnalysisRecord.Draft(analysis) }.execute($0)
      }
    }
    return try result.get()
  }
}
        

Suffice to say, doing this would be incredibly difficult with larger protocols, as you would have to add the above behavior to each requirement. Since OperationModifier is a small protocol with a requirement, it was quite easy to add this Dev Tools interface, as well as artificial delay, and much more that you can find in the library.

Addressing Alternatives and Concerns

Now that I’ve laid out the case against large protocols, I want to spend some time going through many strategies that I’ve seen in the community to address some of the problems of large protocols.

Struct Based Interfaces

For the point on mocking, one may try to turn to a mutable struct of closures instead of a protocol. PointFree has been the primary advocate for this style as far as I can tell, and the docs of Swift Dependencies even have an entire article on this.

In other words, we would make NotesRepository a struct like this.

import Dependencies

@DependencyClient
struct NotesRepository {
  var findNote: @Sendable (_ id: Int) async throws -> Note?
  var allNotes: @Sendable (_ notebookId: Int?) async throws -> [Note]
  var findNotes: @Sendable (_ text: String) async throws -> [Note]
  var save: @Sendable (note: Note) async throws -> Void
  var moveNote: @Sendable (from srcNotebookId: Int, to dstNotebookId: Int) async throws -> Void
  var deleteNote: @Sendable (with ids: Set<Int>) async throws -> Void
}
        

Now in tests, we can override specific properties to provide a mock value.

@Test("Shows Alert When Failing To Add Note")
func showsAlertWhenFailingToAddNote() async throws {
  try await withDependencies {
    struct SomeError: Error {}
    $0[NotesRepository.self].save = { _ in throw SomeError() }
  } operation: {
    // AddNoteFormModel would access NotesRepository through the
    // @Dependency property wrapper.
    let model = AddNoteFormModel()
    model.title = "My note"
    model.contents = "This is fun"

    #expect(model.alert == nil)
    await model.submitted()
    #expect(model.alert == .failedToSaveNote)
  }
}
        

For the record, I used to use this style extensively. However, I often found myself repeating the same patterns of code over and over again for each test.

@Test("Something")
func something() async throws {
  try await withDependencies {
    struct SomeError: Error {}
    $0[NotesRepository.self].save = { _ in throw SomeError() }
  } operation: {
    // ...
  }
}

@Test("Other Thing")
func otherThing() async throws {
  try await withDependencies {
    struct SomeError: Error {}
    $0[NotesRepository.self].save = { _ in throw SomeError() }
  } operation: {
    // ...
  }
}

// So on...
        

Another annoying thing about this pattern has to do with spies explicitly. In many cases, you need to use something like Mutex to capture the value passed to the dependency closure, and repeating this is not very fun either.

import Synchronization

@Test("Spy Save")
func spySave() async throws {
  let savedNotes = Mutex([Note]())
  try await withDependencies {
    $0[NotesRepository.self].save = { note in
      savedNotes.withLock { $0 = note }
    }
  } operation: {
    // ...
  }
}
        

If we want to do domain specific asserts on the spied values, we’re also out of luck because we cannot just add an additional API to a struct of closures that returns a property captured by those closures.

In the long run, I’ve often reduced duplication by creating simple and reusable mocks that conform to a small protocol.

struct FailingSaver: NoteSaver {
  func save(note: Note) async throws {
    struct SomeError: Error {}
    throw SomeError()
  }
}

@MainActor
final class SpySaver: NoteSaver {
  private(set) var savedNotes = [Note]()

  // We also get domain-specific asserts with this approach.
  func expectSaved(_ note: Note) {
    #expect(self.savedNotes.contains(note))
  }

  func save(note: Note) async throws {
    self.savedNotes.append(note)
  }
}
        

Despite these flaws, I actually think structs with closures are great for certain kinds of problems. For instance, I often find myself relying on bags of closures over creating a Delegate protocol because delegates are often created in an adhoc fashion.

extension HapticaExtension {
  public struct Delegate: Sendable {
    public var onJavaScriptExceptionThrown:
      (@Sendable (HapticaExtension, JavaScriptException) -> Void)?
    public var onMetadataUpdated: (@Sendable (HapticaExtension, HapticaExtensionMetadata) -> Void)?

    public init(
      onJavaScriptExceptionThrown: (
        @Sendable (HapticaExtension, HapticaExtension.JavaScriptException) -> Void
      )? = nil,
      onMetadataUpdated: (@Sendable (HapticaExtension, HapticaExtensionMetadata) -> Void)? = nil
    ) {
      self.onJavaScriptExceptionThrown = onJavaScriptExceptionThrown
      self.onMetadataUpdated = onMetadataUpdated
    }
  }
}
        

In other words, if the operation is very adhoc and is tightly coupled to what the caller is doing (eg. The operation would change the caller’s state somehow.), then I think closures suit that use case better. Delegates are a perfect example of this, but many well-known APIs also accept simple closures such as initializer of Task.

Small Protocols are a lot of Boilerplate

I won’t deny this, but a small increase in typing speed is not worth time lost in friction. That is to say, I would rather deal with a bit of boilerplate over not being able to rapidly iterate.

Perhaps you may also be thinking that I would advocate for small types to conform to the small protocols. Naturally, this would result in an explosition of small classes.

protocol NoteSaver {
  func save(note: Note) async throws
}

final class APINoteSaver: NoteSaver {
  init(api: NotesAPI) {
    // ...
  }
}

protocol NoteDeleter {
  func deleteNote(with id: Int) async throws
}

final class APINoteDeleter: NoteSaver {
  init(api: NotesAPI) {
    // ...
  }
}
        

Obviously, this would get quite annoying. Thankfully, Swift lets you extend existing types to conform to protocols you own after the fact. In most cases, I usually have a larger class that implements many of these small protocols.

final class NotesAPI {
  // ...
}

extension NotesAPI: NoteSaver {
  // ...
}

extension NotesAPI: NoteDeleter {
  // ...
}
        

Protocols represent possibilities, and so I would rather leave the option for either a small class or large class to conform to them. For instance, maybe we want to save the note to a local file as well as the backend when it’s saved. We can address that with a simple conformance without having to modify NotesAPI.

struct FileSaver<Base: NoteSaver>: NoteSaver {
  let base: Base
  let baseURL: URL

  func save(note: Note) async throws {
    try await self.base.save(note: note)
    try JSONEncoder().encode(note)
      .write(to: self.baseURL.appending(path: "\(note.id).json")
  }
}

let fileAPISaving = FileSaver(base: NotesAPI.shared)
        

With the old NotesRepository approach, our only reasonable option would’ve added this file saving functionality on to our 1 potentially massive conforming type.

final class DefaultNotesRepository: NotesRepository {
  private let api: NotesAPI
  private let baseURL: URL

  // ...

  init(api: NotesAPI, let baseURL: URL) {
    // ...
  }

  // ...

  func save(note: Note) async throws {
    try await self.api.save(note: note)
    try JSONEncoder().encode(note)
      .write(to: self.baseURL.appending(path: "\(note.id).json")
  }

  // ...
}
        

I want to make clear that I’m not necessarily advocating for the small-conformance style as the best way to implement local persistence on top of an HTTP API. In most cases, I would directly implement it alongside the API call in a larger conformance because that would be easier to understand.

However, small protocols leaves open small conformances as an option, and that option may fit your context better than integrating it directly inside DefaultNotesRepository. If we had more requirements to implement behind the NotesRepository protocol, then it’s likely that we would have to keep bloating DefaultNotesRepository. If the implementation starts to become a bit bloated, it may be easier to add new behavior to the overall operation of saving a note with a smaller conformance.

Sometimes, an explosion of small conforming types is what we want (eg. SwiftUI Views), but other times we want larger and more cohesive conforming types. Small protocols give you both options, whereas larger ones don’t.

You can just Autogenerate Mocks with a Package (Mockingbird, SwiftyMocky, etc.)

Outside of the obvious dependency problem this has, the other pain point is that these kinds of packages tend to own the entire generation pipeline for the mocks, and they often cannot be modified after the fact. I actually think that this is worse than spending the time to create your own larger and global mock. At least the “one large mock” can be edited by its creators to accommodate different scenarios.

Mocks are Bad Lmao

In many cases this is true, and I certainly don’t advocate for mocking everything. Without making this an entire piece on my opinion on mocks, sometimes it’s just ok to use them as a weapon in your arsenal. In fact, when I do mock a protocol for 1 suite of tests, I’ll often have another suite of tests that test the live implementation of the mocked protocol.

Furthermore, I don’t want “mocking” to be the main idea that comes out of this piece. Smaller protocols certainly make mocking easier, but the larger idea is possibility. Mocking itself is a possibility.

What if I need a Large Protocol?

Then make one.

Alternatively, you can create larger protocols by composing smaller ones. This is how Codable is done, and you can do it with your own protocols too.

typealias NotesRepository = NoteSaver & NoteDeleter & NotesFinder

// OR Alternatively (this requires conforming types to explicitly
// conform to NotesRepository)
protocol NotesRepository: NoteSaver, NoteDeleter, NotesFinder {}
        

When should I use a Large Protocol?

The answer to this largely depends on how its is used.

Take this scenario.

protocol Large {
  func r1()
  func r2()
  func r3()
  func r4()
  // All the way to r8...
}

func foo(using large: some Large) {
  large.r1()
  large.r2()
  large.r3()
  large.r4()
  // All the way to r8...
}
        

Since foo uses all the requirements from Large, then Large is a properly sized protocol because there is no unnecessary dependence. Additionally, we may not need a ton of possibility towards how Large is implemented, so in this case a large protocol is a decent trade-off.

Another thing to consider on the unnecessary dependence point is that the protocol has a cohesive set of requirements. For instance.

extension ScheduleableAlarm {
  public protocol Authorizer: AnyObject, Sendable {
    associatedtype Statuses: AsyncSequence<ScheduleableAlarm.AuthorizationStatus, Never>

    func requestAuthorization() async throws -> AuthorizationStatus
    func statuses() -> Statuses
  }

  public enum AuthorizerKey: DependencyKey {
    public static var liveValue: any Authorizer {
      // ...
    }
  }
}

extension ScheduleableAlarm.AuthorizationStatus {
  public struct UpdatesKey: SharedReaderKey {
    private let authorizer: any ScheduleableAlarm.Authorizer

    // ...

    public func subscribe(
      context: LoadContext<Value>,
      subscriber: SharedSubscriber<Value>
    ) -> SharedSubscription {
      let task = Task.immediate {
        for await status in self.authorizer.statuses() {
          withAnimation { subscriber.yield(status) }
        }
      }
      return SharedSubscription { task.cancel() }
    }
  }
}
        

In this case UpdatesKey only uses the statuses requirement from ScheduleableAlarm.Authorizer. Yet, I still think ScheduleableAlarm.Authorizer is properly sized for because its requirements are coherent (ie. Requesting authorization would be expected to have an impact on the status updates.), and because it is still easy to conform to (ie. It only has 2 requirements.).

Another thing could be that the protocol has default implementations for many of its requirements.

public protocol QueryRequest<Value, State>: QueryPathable, Sendable
where State.QueryValue == Value {
  associatedtype Value: Sendable
  associatedtype State: QueryStateProtocol = QueryState<Value?, Value>

  var _debugTypeName: String { get }

  var path: QueryPath { get }

  func setup(context: inout QueryContext)

  func fetch(
    in context: QueryContext,
    with continuation: QueryContinuation<Value>
  ) async throws -> Value
}

extension QueryRequest {
  public var _debugTypeName: String { typeName(Self.self) }

  public func setup(context: inout QueryContext) {
  }
}

extension QueryRequest where Self: Hashable {
  public var path: QueryPath {
    QueryPath(self)
  }
}
        

In this case, the only real requirement that a conformance often needs to implement is fetch.

extension Post {
  struct Query: QueryRequest, Hashable {
    let id: Int

    func fetch(
      in context: QueryContext,
      with continuation: QueryContinuation<Post>
    ) async throws -> Post {
      let url = URL(string: "https://jsonplaceholder.typicode.com/posts/\(id)")!
      let (data, _) = try await URLSession.shared.data(from: url)
      return try JSONDecoder().decode(Post.self, from: data)
    }
  }
}
        

Making Large Protocols Composable

You may be surprised to hear that it’s still possible to achieve much of the compositional benefits of smaller protocols with large protocols as well if you’re willing to write an entire modifier system.

Swift Operation takes this approach because the OperationRequest and StatefulOperationRequest protocols have a bunch of annoying requirements that don’t need to be considered when implementing composable behavior.

public protocol OperationRequest<Value, Failure> {
  associatedtype Value
  associatedtype Failure: Error

  var _debugTypeName: String { get }
  func setup(context: inout OperationContext)

  func run(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    with continuation: OperationContinuation<Value, Failure>
  ) async throws(Failure) -> Value
}

public protocol StatefulOperationRequest<State>: OperationRequest
where Value: Sendable, State.OperationValue == Value, State.Failure == Failure {
  associatedtype State: OperationState
  var path: OperationPath { get }
}
        

If you were to implement composable behavior with OperationRequest, chances are that you would forget to forward _debugTypeName, _path, or setup. This is why the library defines a simpler OperationModifier protocol.

public protocol OperationModifier<Value, Failure> {
  associatedtype Operation: OperationRequest
  associatedtype Value
  associatedtype Failure: Error

  func setup(context: inout OperationContext, using operation: Operation)

  func run(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    using operation: Operation,
    with continuation: OperationContinuation<Value, Failure>
  )
}
        

The library then provides a query called ModifiedOperation, which does the hard work of adapting your OperationModifier to work with an OperationRequest.

public struct ModifiedOperation<
  Operation: OperationRequest,
  Modifier: OperationModifier
>: OperationRequest where Modifier.Operation == Operation {
  public typealias Value = Modifier.Value

  public let operation: Operation
  public let modifier: Modifier

  @inlinable
  public var _debugTypeName: String {
    self.operation._debugTypeName
  }

  @inlinable
  public func setup(context: inout OperationContext) {
    self.modifier.setup(context: &context, using: self.operation)
  }

  @inlinable
  public func run(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    with continuation: OperationContinuation<Modifier.Value, Modifier.Failure>
  ) async throws(Modifier.Failure) -> Modifier.Value {
    try await self.modifier.run(
      isolation: isolation,
      in: context,
      using: self.operation,
      with: continuation
    )
  }
}

extension ModifiedOperation: StatefulOperationRequest
where
  Modifier.Operation: StatefulOperationRequest,
  Operation.Value == Modifier.Value,
  Operation.Failure == Modifier.Failure
{
  public typealias State = Operation.State

  @inlinable
  public var path: OperationPath {
    self.operation.path
  }
}
        

SwiftUI also takes this approach for adapting composability for views. For instance, the View protocol from SwiftUI actually looks something like this.

public protocol View {
  nonisolated static func _makeView(view: _GraphValue<Self>, inputs: _ViewInputs) -> _ViewOutputs

  nonisolated static func _makeViewList(view: _GraphValue<Self>, inputs: _ViewListInputs) -> _ViewListOutputs

  nonisolated static func _viewListCount(inputs: _ViewListCountInputs) -> Int?

  associatedtype Body: View

  @ViewBuilder
  @MainActor
  @preconcurrency
  var body: Self.Body { get }
}
        

However, you don’t ever implement those top 3 requirements. In fact, you may not even have known about their existence because Xcode doesn’t show them! Instead, a few select primitive views from SwiftUI (eg. Text) implement those requirements whilst a default implementation is used for the typical views that you create in your app. Even if you tried to implement those requirements, chances are is that it would be impossible because they use types that are largely internal to SwiftUI.

This is why SwiftUI provides a ViewModifier and the ModifiedContent view if you want to add composable behavior to your views. ModifiedContent is a special view that adapts your ViewModifier into a legitimate SwiftUI view by providing proper implementations of _viewListCount, _makeViewList, and _makeView based on the child content in the view.

public struct ModifiedContent<
  Content: View,
  Modifier: ViewModifier
>: View {
  public let content: Content
  public let modifier: Modifier

  // See: https://github.com/OpenSwiftUIProject/OpenSwiftUI/blob/main/Sources/OpenSwiftUICore/Modifier/ViewModifier.swift

  public static func _makeView(
    view: _GraphValue<Self>,
    inputs: _ViewInputs
  ) -> _ViewOutputs {
    Modifier.makeDebuggableView(
      modifier: view[offset: { .of(&$0.modifier) }],
      inputs: inputs
    ) {
      Content.makeDebuggableView(
        view: view[offset: { .of(&$0.content) }],
        inputs: $1
      )
    }
  }

  // ...
}

extension View {
  public func modifier<Modifier>(
    _ modifier: Modifier
  ) -> ModifiedContent<Self, Modifier> {
    // ...
  }
}
        

Conclusion

The more possibilities that your protocol provides, the easier it is to add new features, perform one-off experiments, and make changes to your code. Possibility comes by making your protocols easy to conform to, which often means making them small with simpler requirements.

When you have possibility, it doesn’t matter if a “god” class, a tiny one-off handwritten mock, or an entire DSL implements the protocol. The important part is that you have the possibility to do any of those things in the first place.

Unnecessary dependence on large protocols hinders the amount of possibility for no good reason because it requires a larger than necessary conformance. Furthermore, a large protocols with a bunch of requirements, such as a “Repository” protocol, also hinders possibility because there is more friction when conforming to larger protocols.

However, if a large protocol can counter those 2 points in your context, then feel free to create one. Additionally, you may find that you can create a large protocol by composing it from smaller protocols.

Lastly, you should check out Swift Operation, it handles a lot of pain around asynchronous state management and data fetching for you.

-- Minutes to Read

Given that Foundation Models has had a positive reception since it was introduced earlier this year at WWDC, what could be so wrong with it?

Let’s sum up all of the problems I have with Foundation Models in one sentence. It’s practically impossible to put FoundationModels at the center of your app’s experience.

Now let’s see why that is the case, and why I created swift-cactus to begin solving this problem.

Problems with Foundation Models

One of the obvious answers is that it requires a device that supports Apple Intelligence, which for iPhones is really only the everything from iPhone 15 Pro and beyond. This is extremely limiting, and as a developer it makes it so that you can’t reliably base your product around the framework. Well, that is unless you want to alienate ~80% (rough estimate) of your potential market.

iPad models are a bit more in luck with any M-series iPad getting support automatically, but note that this article is being written on an 11inch iPad Pro from 2018 (it still runs really well to this day). Additionally, mac users are in a far more optimal spot given that the M1 processor was introduced ~5 years ago at this point. However, it’s no secret that most Apple development happens on iOS, yet many of it devices are left out.

Additionally, Foundation Models only ships a singular 3B parameter model that you’re forced to use nearly as is (outside of adapters). Of course, this really means that your options are limited with the framework. That lack of optionality probably isn’t a problem for small indie to mid-sized apps that have a non-AI primary value proposition. However, I think those trying to build incredibly sophisticated apps using offline models in very scientific or highly intellectual domains (eg. Health) may find this lack of optionality to be problematic.

Lastly, given that this is an Apple-specific framework, newer APIs added to the framework won’t be available on previous OS versions. In fact, you can’t even use Foundation Models below iOS 26, so it will probably quite some time before it gains any sort of reliable adoption outside of early adopters.

I think the why behind the problem here is that Foundation Models is far too limited, and more is needed here if we want to build great privacy-aware apps that involve AI at the center of their experience. Right now, I can only see it as a framework that indie devs or small teams adopt in their apps, and even then it still isn’t reliable enough to be at the center of their app’s experience due to hardware limitations.

Eventually (in ~2-3 years), the hardware limitation won’t be as much of a problem, but you’ll still likely be limited in model options whilst still having to deal with newer API compatibility issues.

Swift Cactus

Swift Cactus is a wrapper over the cactus compute inference engine, which at the time of writing this seems to be the fastest inference engine that I could find for ARM chips (ie. Mobile Devices). The company behind the engine is also YC backed, so we’ll see where this goes.

The package provides an API for downloading cactus-supported models (Qwen and Gemma for now) into your application, telemetry with the cactus dashboard, and a minimal wrapper around the C cactus FFI. The C FFI includes an embeddings API, which isn’t available at all in Foundation Models. The library runs on all Apple platforms, including watchOS, where Foundation Models lacks total support.

Like all other articles on libraries I create, examples of how to use the library can be found in the repo itself. This article will focus on design.

Limitations

The API isn’t nearly as high-level as Foundation Models, but I think the essential building blocks are there. For instance, tool calling is supported, but there’s no fancy Tool protocol, rather you have to execute the tool calling loop yourself. Neither is there any fancy @Generable macro yet, and you also have to ensure entire responses from the model fit inside of a fixed size buffer as the C FFI requires you to as of now. I think with more time, these limitations can be overcome by providing a higher level wrapper API over the existing minimal API.

Additionally, the CactusLanguageModel class isn’t thread-safe because the C FFI isn’t fully thread-safe either, and all of its methods are synchronous and blocking. While this gives you flexibility, it also makes it easy to misuse the model (such as running it on the main thread). I recommend that you solve this by creating a dedicated actor to house the model instance.

final class LanguageModelActor {
  let model: CactusLanguageModel

  init(model: sending CactusLanguageModel) {
    self.model = model
  }

  func withIsolation<T, E: Error>(
    perform operation: (isolated Self) throws(E) -> sending T
  ) throws(E) -> sending T {
    try operation(self)
  }
}

@concurrent
func chatInBackground(with modelActor: LanguageModelActor) async throws {
  try await modelActor.withIsolation { modelActor in
    // You can access the model directly because the closure is isolated
    // to modelActor
    let model = modelActor.model

    // ...
  }
}
        

Lastly, you’re limited to models that the cactus engine directly supports, which isn’t a lot right now. However, you have more options than Foundation Models, and more will be added in the future. At the very least, the current options you have perform well on a wider range of devices than what Foundation Models supports.

Embeddings

Foundation Models currently doesn’t have support for generating a vector of embeddings from a string of text. Embeddings can be used to match similar pieces of text, and a common way to do this is through checking the cosine similarity score.

import Cactus

func cosineSimilarity<C: Collection>(_ a: C, _ b: C) throws -> Double
where C.Element: BinaryFloatingPoint {
  guard a.count == b.count else {
    struct LengthError: Error {}
    throw LengthError()
  }
  var dot = 0.0, normA = 0.0, normB = 0.0
  var ia = a.startIndex, ib = b.startIndex
  while ia != a.endIndex {
    let x = Double(a[ia])
    let y = Double(b[ib])
    dot += x * y
    normA += x * x
    normB += y * y
    ia = a.index(after: ia)
    ib = b.index(after: ib)
  }
  let denom = (normA.squareRoot() * normB.squareRoot())
  return denom == 0 ? 0 : dot / denom
}

let model = try CactusLanguageModel(from: modelURL)

let fancy = try model.embeddings(for: "This is some fancy text")
let pretty = try model.embeddings(for: "This is some pretty text")

print(cosineSimilarity(fancy, pretty))
        

You can use the techniques such as cosine similarity to search through text in natural language. For instance, if you’re using SQLiteData, you can use this as alternative to FTS5 to implement search for your application. Instead of maintaining an FTS virtual table, you would have to maintain a column that holds the embeddings for the content you want to search instead.

Here’s a very simplified example of how you can use temporary triggers to maintain this column using SQLiteData.

import Cactus
import Foundation
import SQLiteData
import Synchronization

@Table
struct Reminder: Identifiable {
  var id: UUID
  var name: String

  @Column(as: [Float].JSONRepresentation.self)
  var embeddings: [Float]
}

private let model = Mutex(try! CactusLanguageModel(from: modelURL))

@DatabaseFunction(as: ((String) -> [Float].JSONRepresentation).self)
func embeddings(text: String) -> [Float] {
  model.withLock { (try? $0.embeddings(for: text)) ?? [] }
}

// Triggers to ensure that embeddings are always created after inserts and updates.
func createEmbeddingsTriggers(in db: Database) throws {
  try Reminder.createTemporaryTrigger(
    after: .insert { new in
      Reminder.find(new.id)
        .update { $0.embeddings = $embeddings(new.name) }
    }
  )
  .execute(db)

  try Reminder.createTemporaryTrigger(
    after: .update { _, new in
      Reminder.find(new.id)
        .update { $0.embeddings = $embeddings(new.name) }
    } when: { old, new in
      new.name != old.name
    }
  )
  .execute(db)
}
        

Telemetry

Swift Cactus also ships with support for telemetry such that you can analyze model performance and registered devices in the cactus dashboard. Currently, the default telemetry integration is only supported on iOS and macOS, but you can also build your own custom integration if you wish. (This is because there seems to be a proprietary binary that Cactus uses to decrypt the string that contains the device id, and I could only find XCFrameworks for iOS and macOS. I could also choose to reverse engineer the solution since it seems like the decryption key is in the compiled binary, but I don’t want to get in trouble.)

Telemetry is completely optional, and events are recorded automatically by the CactusLanguageModel class. All you need to do to set it up is pass your token from the cactus dashboard to CactusTelemetry.

import Cactus

CactusTelementry.configure("<your token here>")
        

An Alternative Foundation Models

Why provide an alternative to an Apple framework? Wouldn’t Apple always know what’s the best for their ecosystem?

There are multiple successful third-party alternatives to some of Apple’s largest frameworks in my opinion. RevenueCat providing an alternative to StoreKit is probably the largest case of this, especially considering that RevenueCat is a venture backed company. Another good example is SQLiteData and GRDB competing directly with CoreData and SwiftData, both the of former are open source, and SQLiteData even uses GRDB under the hood. Additionally, Alamofire also provides a more robust alternative to URLSession.

With local LLMs quickly becoming more prevalant at center of consumer apps, I think it’s only natural that alternatives to Foundation Models present themselves to address its limitations. Just as alternatives came in to address the limitations of CoreData and SwiftData (which are also at the center of many apps).

Right now, at this present point in time, I don’t think Foundation Models is solving this problem well enough. Additionally, given Apple’s release cadences, I don’t think Foundation Models will solve this problem well enough for a while.

There’s a lot of work to do for Swift Cactus to match the more convenient higher level API offered by Foundation Models. Even so, I think having access to the lower level functionality is beneficial regardless. However, just the already present lower-level functionality already makes bringing local LLMs to the center of your app’s experience possible for everyone, not just those on the latest iPhones and OS versions.

-- Minutes to Read

Data fetching is flakey, yet most software we use needs to do it. In general, flakiness complicates software, because something can only be flakey if it comes from the physical-world. That is to say, fetching data is hard.

However, when I say it’s hard, I don’t mean the code to actually fetch data itself. Generally, that part is pretty easy, and you can spin up an HTTP request to any server with just a few lines of Swift code. Codable and JSONDecoder handle most cases of decoding data from a server, and they do so pretty well. Additionally, many Apple Frameworks that also involve data fetching also tend to be relatively simple function calls if we’re just talking about fetching the data itself.

Yet we know as developers that number of things that can go wrong when dealing with a function that has both async and throws in its signature. Loading states, error alerts, retries, caching, cancellation, deduplication, exponential backoff, delays, network connection status, keeping data consistent between screens and much more that is annoying to deal with.

I’ve lost count of how many times I’ve written the same kind of code that: Sets a state variable to indicate loading, fetches data, if failed sets an error state variable, otherwise sets the data state variable to indicate that loading is done. The cherry on top is when you also have to display an alert when the data fetching fails. All of this is also not considering caching, yielding intermediate values whilst fetching from the source of truth (ie. Your backend), and much more.

Over these past few months, I’ve spent a lot of effort developing a toolkit that I’ve used across various projects to make dealing with asynchronous operations and data fetching much more manageable, so you can move on after writing the simple data fetching code. Today, I’m finally putting a formal release tag behind these tools, so that you can use them in your (smaller) apps. For the record, that also includes apps on Linux, WASM, Windows, and Android.

The resulting library is named swift-operation.

This article will mainly be about its development, and the various techniques I’ve employed when using and designing the library. I won’t focus too much on how to use the library in this article. The GitHub repo, documentation, and many demo apps present in the repo should do a sufficient job in providing many examples of how to use the library.

Origins

This project started out from my experience working with react-native in a startup for the past 1.5 years where we heavily relied on Tanstack Query. When writing Swift apps in my spare time, I missed the ability to have something that managed async state intuitively, which spawned the desire for this project. My initial goal was just to port Tanstack Query over to Swift, and integrate it with swift-sharing, an already popular state management library used in many apps (including every app that uses modern TCA). In fact, the original name of the library was Swift Query, but of course that name was stolen…

I was able to get this simple port version of the library up and running in quite a short period of time, but naturally I of course felt the need to continuously refine things as I kept trying it in different scenarios. This led to months of iteration as the library needed to find a distinct identity from Tanstack Query given that Swift is a very different language compared to TypeScript.

Tanstack Query advertises itself as an “Asynchronous State Manager”. Swift Operation also has such state management built in, and even has an integration with Sharing through the @SharedOperation property wrapper. However, the resulting library I’ve built serves a more general purpose. Swift Operation aims to make asynchronous work as whole easier to manage, of which “asynchronous state management” would be a subset of that functionality. I like to call Swift Operation, an asynchronous operation manager because it uses a SwiftUI modifier approach to constructing operations.

struct User: Sendable {
  let id: Int
  let name: String
}

extension User {
  static func query(for id: Int) -> some QueryRequest<User?, any Error> {
    // We've configured fetching our user with retries, deduplication,
    // stale-when-revalidate, and automatic refetching when the network
    // connection flips from offline to online with just a few lines of 
    // code.
    Query(id: id)
      .retry(limit: 3)
      .deduplicated()
      .stale(after: 60 * 5)
      .rerunOnChange(of: .connected(to: NWPathMonitorObserver.startingShared()))
  }

  struct Query: QueryRequest, Hashable {
    let id: Int

    func fetch(
      isolation: isolated (any Actor)?
      in context: OperationContext,
      with continuation: OperationContinuation<User?, any Error>
    ) async throws -> User? {
      // Fetch the user...
    }
  }
}
        

For TypeScript apps, Tanstack Query is generally only used inside your UI layer, and its API heavily skews itself towards that particular use case. Swift Operation provides tools to use the library both within your UI and data layers. For example, there are many instances where the library is used for tool calling via conforming to the Tool protocol conformances from Apple’s new FoundationModels framework.

I suppose if you want to correlate Swift Operation with libraries from the TypeScript world, it’s largely a combination of both Tanstack Query and Effect. Though so far, the library is more optimized for the Tanstack Query case.

Design Philosophy & Learning Curve

Swift Operation is a complicated library, and intentionally so. I would wager that it is more complicated than Tanstack Query if you were to try and understand every detail of it.

That being said, it is also quite simple in the sense that it’s built entirely around the notion of calling an async function. I suppose the complexity is really just case of “different” rather than “seriously complicated” (I think of TCA’s complexity in the same way for the record). Once you get over the learning curve, I think the end result will be a net win in simplicity considering what the library does for you.

This large learning curve derives from 3 things:

1. The library is incredibly flexible whilst also providing as much type-safety as possible.
2. It surfaces advanced concepts of Swift Concurrency (eg. isolated parameters) right in your face.
3. Data fetching is hard and complex with many edge cases that the library wants you to be aware of.

Though the good news is that the most common use case (ie. Just making and using a QueryRequest that fetches some data in your UI.) is not that hard, and can be done incredibly “swiftly”. This most common use case should get you through ~80% of scenarios, and the rest of the library can be progressively learned.

You’ll likely end up with more lines of code in your app after adopting the library. Ignoring the fact that many of those added lines won’t contain much substance (ie. Struct/Function declarations), the library also wants to surface edge cases that you probably weren’t thinking about before, so it’s only natural that you will end up writing code to handle those additional cases. Of course, over time the ideal for the library should be to get rid of many of those added lines that have little substance.

Comparison to Tanstack Query

One of the things Tanstack Query could’ve improved on was what the notion of a “query” was. In fact, I named the library Swift Operation because queries are a subset of a general operation that runs some workflow and returns a result. Mutations and paginated requests (ie. The equivalent of Infinite Queries from Tanstack Query), are also subsets of operations. In Tanstack Query, mutations and queries are separate concepts, but in Swift Operation they share much of the same core since they both derive from base operations.

Customizing Operations

Take a common usage of useQuery from Tanstack Query.

const FIVE_MINUTES = 5000 * 60

const usePost = (postId: number) => {
  return useQuery({
    queryKey: ["post", postId],
    queryFn: async () => await fetchPost(postId),
    retry: 3,
    staleTime: FIVE_MINUTES
  })
}
        

The problem is that we customize everything through a bag of configuration properties! This bag of properties is solely maintained by Tanstack Query, and adding a new property to this bag requires the approval of the maintainers. In essence, this makes adding custom higher order behavior to your queries nigh-impossible.

Compare this to how queries are customized in Swift Operation.

struct PostQuery: QueryRequest {
  let postId: Int

  // ...
}

let fiveMinutes = TimeInterval(60 * 5)

let query = PostQuery(postId: 10)
  .retry(limit: 3)
  .stale(after: fiveMinutes)
        

The customization very much feels like customizing a SwiftUI view with a bunch of view modifiers. In fact, you can create your own modifiers with the OperationModifier protocol. Let’s look at how you can create a modifier to add artificial delay to any operation, whether or not that’s a mutation, query, or paginated request.

import Dependencies
import Operation

extension OperationRequest {
  public func previewDelay(
    shouldDisable: Bool = false,
    _ delay: Duration? = nil
  ) -> ModifiedOperation<Self, _PreviewDelayModifier<Self>> {
    self.modifier(_PreviewDelayModifier(shouldDisable: shouldDisable, delay: delay))
  }
}

public struct _PreviewDelayModifier<Operation: OperationRequest>: OperationModifier, Sendable {
  let shouldDisable: Bool
  let delay: Duration?

  public func setup(context: inout OperationContext, using query: Operation) {
    context[DisablePreviewDelayKey.self] = self.shouldDisable
    query.setup(context: &context)
  }

  public func run(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    using query: Operation,
    with continuation: OperationContinuation<Operation.Value, Operation.Failure>
  ) async throws(Operation.Failure) -> Operation.Value {
    @Dependency(\.context) var mode
    guard mode == .preview && !context[DisablePreviewDelayKey.self] else {
      return try await query.run(isolation: isolation, in: context, with: continuation)
    }
    if let delay {
      try? await Task.sleep(for: delay)
    } else {
      try? await Task.sleep(for: .seconds(Double.random(in: 0.1...3)))
    }
    return try await query.run(isolation: isolation, in: context, with: continuation)
  }
}

private enum DisablePreviewDelayKey: OperationContext.Key {
  static let defaultValue = false
}
        

This modifier is used in the demo app that ships with the library to add fake random delay to every single operation. This allows me to preview the experience that an actual user with a flakey internet connection would have, whilst still mocking fake results for the UI.

Another modifier is used to also power dev tools that analyze the run time of every single operation in the app.

To handle automatically displaying alerts when an operation succeeds or fails, I also created another modifier that utilizes AlertState from swift-navigation. This modifier was often used in conjunction with mutations.

Custom modifiers allow for higher-order functionality that you can’t get in Tanstack Query, and I’ve found this kind of configuration flexibility to even be useful in practical scenarios as can be seen by the above modifiers.

Operation Types

Tanstack Query gives you queries, mutations, and infinite queries. All of these operation types are baked into the library, and new ones cannot be added directly.

Swift Operation also gives you those 3 operation types, though infinite queries are called paginated queries, but you can create more kinds if you want. Queries, mutations, and paginated queries all inherit from the StatefulOperationRequest protocol, and StatefulOperationRequest inherits from the OperationRequest protocol. This generality means that you can write a custom operation modifier, and it will automatically work for queries, mutations, paginated queries, and any other custom operation types you come up with all at the same time.

There’s an article in the documentation that describes the basics of creating a custom operation type from scratch. I will note that creating an operation type with the same robustness as the built-in types would take a lot of effort, but generally I think the need to create a fully robust operation type is quite a rarity. I’ve only found myself creating a custom operation type on 1 occasion so far, which was to create a type that could paginate many different data streams at once for a very specific use-case. In that case, it was enough to create a custom OperationState concrete type, so I think the bigger idea is that you can modularly replace parts of the built-ins as needed.

Additionally, it’s also possible to create operation types that don’t require any state management because OperationRequest has no stateful requirements.

Multiple Data Updates

Another benefit of Swift Operation is that it’s possible to yield multiple data updates from an operation while it’s still running through the OperationContinuation type that’s handed to each operation run. Tanstack Query also has some support for this through streamedQuery which works via async iterators (think JavaScript’s version of AsyncSequence), but the issue with that API is that any query that uses it will not retain its loading state after the first chunk of data arrives.

Regardless, in today’s LLM-based application landscape, streaming data is far more relevant than it once was. Therefore, I wanted to make this a first-class citizen in Swift Operation. The demo app shows how you can use Apple’s new FoundationModels in conjunction with OperationContinuation to stream data while it arrives from the underlying on-device model.

Another use case for multiple data updates would be yielding data that’s locally stored on disk whilst fetching the freshest data from a remote server. In fact, this can be a great way to implement offline support as shown many different times in the demo app.

struct MyQuery: QueryRequest {
  // ...

  func fetch(
    isolation: isolated (any Actor)?,
    in context: OperationContext,
    with continuation: OperationContinuation<Value, any Error>
  ) async throws -> Value {
    async let value = serverValue()
    continuation.yield(try await locallyPersistedValue())
    return try await value
  }
}
        

Tanstack Query also supports the above use case, but I think the main difference between the 2 libraries is that Swift Operation surfaces this functionality in a more direct way.

Detached State Management

In Tanstack Query all queries and mutations are managed directly by QueryClient, and as a result an instance of the client is needed everywhere to observe the state of a query or mutation.

This is also the default in Swift Operation (except QueryClient is named OperationClient), with the key difference being that the OperationStore type is solely responsible for the state management of an individual operation. The OperationClient merely just holds all the store instances created by your app, and allows you to query specific store instances using an OperationPath (the equivalent of the query key in Tanstack Query). However, it’s also possible to create stores that are not stored inside an OperationClient, and these are called “detached stores”.

Detached stores are particularly useful for 3 cases.

1. You want multiple and completely separate store instances for the same operation.
2. You don’t want the store to be deallocated as a result of being evicted from the store cache within an OperationClient.
   1. By default, this happens when your application runs low on memory, but it’s also possible to create your own custom store cache that uses a different eviction scheme (LRU, garbage collection, etc.).
3. You don’t like how OperationClient manages its pool of stores, and you want to create your own pool for some reason.
   1. This last point is a testament to one of the design principles of the library. If you don’t like a built-in API, then you should have the power to create and use your own implementation of that API with the library.

Run Specifications

Tanstack Query has built-in support for refetching queries when the application re-enters the foreground from the background (Tanstack calls this refetching on focus), and refetching queries when the network status flips from offline to online. This is particularly useful for keeping data as fresh as possible in your UI in the context of the user switching between apps, or when implementing a “Reconnecting…” dialog.

Swift Operation also supports automatically rerunning operations in these circumstances, but yet again it does so in a modular way. While Tanstack Query bakes this kind of refetching directly into a query, Swift Operation builds this functionality generically on-top of the OperationRunSpecification protocol.

A run specification allows you to control when an operation automatically reruns. It has 2 requirements.

public protocol OperationRunSpecification {
  /// Returns whether or not this condition is satisfied in the specified context.
  func isSatisfied(in context: OperationContext) -> Bool

  /// Subcribes to changes on this specification in the specified context.
  func subscribe(
    in context: OperationContext,
    onChange: @escaping @Sendable () -> Void
  ) -> OperationSubscription
}
        

isSatisfied is general invoked immediately after onChange is called within subscribe.

The rerunOnChange modifier provides the same operation rerunning capabilities as Tanstack Query’s automatic refetching. The modifier takes a run specification, and will automatically rerun the operation it modifies whenever it detects that the return value of isSatisfied changes to true. In fact, the actual refetching is further built on top of the generic OperationController protocol.

NetworkConnectionRunSpecification and ApplicationIsActiveRunSpecification are the run specifications that power the same refetching abilities that you would find in Tanstack Query. The difference between the 2 libraries in this regard, is that you can also create custom run specifications to drive automatic rerunning.

Stateless Operations

Tanstack Query solely advertises itself as an asynchronous state manager, yet many of its features, like retries, also work in a stateless operation paradigm.

What do I mean by stateless operation? A stateless operation is an operation that doesn’t need to have its state tracked by a UI or something else in real-time. Just think of it as a typical async function where you also don’t need to track whether or not the operation is in a loading, error, or success state.

Since Tanstack Query is so focused on state management with its API, it only really makes sense to use it in your UI layer. If you have async operations that run in background or non-UI contexts, you generally don’t use Tanstack Query even if you would benefit from some of its features (eg. Deduplication and retries).

I wanted to make Swift Operation something that is also viable in your data layer, and other non-UI contexts such as within tools in the FoundationModels framework. This is why there’s both an OperationRequest and StatefulOperationRequest protocol, where StatefulOperationRequest inherits from OperationRequest.

If you create a direct conformances to OperationRequest, you aren’t required to specify a State associated type, or an OperationPath that uniquely identifies your operation. In effect, conforming to OperationRequest directly signals to the library that your operation is stateless, or that it’s just an async function that performs some work and returns a result.

Of course, you cannot create OperationStore instances with stateless operations, so you will need StatefulOperationRequest to be compatible with the store. However, you still get access to a wealth of modifiers with stateless operations, including the ability to create modifiers that change or enhance the output type of your operation. Stateful operations cannot use modifiers that change their output type because their State type only works with a certain output type.

Future Directions

I think I’ve packed a lot into the 0.1.0 release of the library, but I have many more ideas. This list is merely a brain dump of whatever I can think of at the moment.

1. Embedded Swift Support
   1. The library already supports all major Swift platforms (including Android, Windows, and WASM), but the main thing holding back Embedded support IMO would be the use of existentials in deep corners of the library (eg. Within OperationContext).
2. Dev Tools
   1. The demo app shows how basic dev tools can be made that allow you to analyze every single operation run that your app performs. However, it would be better to have a library specific solution to this that’s cross platform, but this will probably take a lot of time and planning.
3. Better Defaults on Non-Apple Platforms
   1. For instance, the default store cache on non-Apple platforms does not use any mechanism to evict store entries because DistpatchSource.makeMemoryPressureSource isn’t available on those platforms.
   2. Additionally, Linux, Windows, and Android do not have a default NetworkObserver and ApplicationActivityObserver. WASM (in web browser applications) has dedicated default implementations for those 2 protocols if you enable the SwiftOperationWebBrowser trait.
4. Macros
   1. At the moment, the library ships with no macros. However, it’s also quite verbose with respect to defining operations. If there could be a way to make creating operations just as simple as defining normal functions (eg. The @DatabaseFunction macro from Structured Queries), that would be nice. I just haven’t figured out how this would fully work with operation types with multiple requirements such as PaginatedRequest.
5. A Better Way to Derive Dependent Operations
   1. By this, I mean constructing operations that depend on the results of other operations. There is a documentation article that describes how to do this, but the solution is far from ideal, and I’m not at all satisfied with it.

Try it Today

I think the library is ready to be used on a larger scale now, and I don’t think I can keep improving it by iterating in isolation for much longer. That being said, it’s far from mature, so I would advise against using it in enterprise scale or mission-critical apps at the time of writing this.

The repo has a lot more material describing how to use the library in different contexts, so check it out!

-- Minutes to Read

I recently released a small little library for generating version 7 UUIDs in Swift that integrates with popular libraries such as GRDB, Structured Queries, Tagged, and more. Some of the interesting comments I’ve gotten relate to one of SPM’s relatively new features (introduced in Swift 6.1) called package traits. From what it seems, this new SPM feature is relatively unknown, yet I think many packages would benefit from utilizing this feature to support integrations with other packages.

If you’ve written Rust before, you may be familiar with cargo features. Package traits are essentially the equivalent of cargo features, but for Swift.

Though, I’m guessing that most people reading this are unfamiliar with Rust, so this article should give enough of an overview of traits. Alternatively, you can read the proposal for package traits, but that won’t tell you about how I used them in swift-uuidv7.

What are Package Traits?

Great question!

Package traits allow you to selectively enable functionality on a swift package. As a package author, you declare them in your Package.swift file like so.

// swift-tools-version: 6.1
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  name: "swift-uuidv7",
  platforms: [.iOS(.v13), .macOS(.v10_15), .tvOS(.v13), .watchOS(.v7), .macCatalyst(.v13)],
  products: [.library(name: "UUIDV7", targets: ["UUIDV7"])],
  traits: [
    .trait(
      name: "SwiftUUIDV7Tagged",
      description: "Adds integrated swift-tagged support to the UUIDV7 type."
    ),
    .trait(
      name: "SwiftUUIDV7StructuredQueries",
      description:
        "Adds swift-structured-queries support and column representations to the UUIDV7 type."
    ),
    .trait(
      name: "SwiftUUIDV7GRDB",
      description: """
        Conforms UUIDV7 to GRDB's DatabaseValueConvertible and StatementColumnConvertible \
        protocols, and adds database functions to generate, parse, and extract data from UUIDV7s.
        """
    ),
    .trait(
      name: "SwiftUUIDV7Dependencies",
      description:
        """
        Adds a dependency value to generate UUIDV7s, and interops the base UUID dependency with \
        UUIDV7 generation.
        """
    )
  ],
  // ...
)
        

Then, inside your package, you can selectively compile bits of your code by using them as a flag within compiler directive.

// If SwiftUUIDV7StructuredQueries is enabled, then UUIDV7 conforms to
// QueryBindable from StructuredQueries.

#if SwiftUUIDV7StructuredQueries
  import Foundation
  import StructuredQueriesCore

  extension UUIDV7: QueryBindable {}

  // ...
#endif
        

Selective Dependency Compilation

You can also choose to only selectively compile package dependencies when a specific trait is enabled. This works similarly to how you can tell a Swift Package to selectively compile a dependency for a specific platform. In other words, as a package author, your Package.swift will look like this.

// swift-tools-version: 6.1
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  // ...
  targets: [
    .target(
      name: "UUIDV7",
      dependencies: [
        // ...
        .product(
          name: "StructuredQueriesCore",
          package: "swift-structured-queries",
          condition: .when(traits: ["SwiftUUIDV7StructuredQueries"])
        ),
        // ...
      ]
    ),
    .testTarget(name: "UUIDV7Tests", dependencies: ["UUIDV7"])
  ]
)
        

In this example, StructuredQueriesCore is only compiled when the SwiftUUIDV7StructuredQueries trait is enabled. This feature is how swift-uuidv7 is able to integrate with many different large libraries whilst still keeping the build time as minimal as possible.

Dependent Traits

You may have traits that depend on other traits being enabled. For instance, there’s a branch in swift-uuidv7 that adds a new SwiftUUIDV7SharingGRDB trait that will be merged once CloudKit support for SharingGRDB is publicly released.

SharingGRDB depends both on StructuredQueries and GRDB, so enabling SwiftUUIDV7SharingGRDB trait should also enable SwiftUUIDV7StructuredQueries and SwiftUUIDV7GRDB. This is accomplished like so.

// swift-tools-version: 6.1
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  // ...,
  traits: [
    // ...
    .trait(
      name: "SwiftUUIDV7SharingGRDB",
      description: """
        Conforms UUIDV7 to IdentifierStringConvertible to make it compatible with CloudKit sync.

        This trait also enables SwiftUUIDV7GRDB and SwiftUUIDV7StructuredQueries.
        """,
      enabledTraits: ["SwiftUUIDV7GRDB", "SwiftUUIDV7StructuredQueries"]
    )
  ],
  // ...
)
        

Default Traits

You can also choose to enable some traits by default on a package. swift-uuidv7 has no need for this because all of its traits conditionally compile external dependencies. If the user has no need for those external dependencies, and just wants the base UUIDV7 type, then we shouldn’t compile them.

Regardless, default traits are enabled like so (this is a simplified example taken from swift-subprocess).

let package = Package(
  // ...
  traits: [
    "SubprocessFoundation",
    "SubprocessSpan",
    .default(enabledTraits: ["SubprocessFoundation", "SubprocessSpan"])
  ],
  // ...
)
        

Building With Traits Enabled

When building your package, you can specify which traits you want to build the package with like so.

swift build --traits SwiftUUIDV7Tagged

You can also enable all traits like so.

swift build --enable-all-traits

How do I use package traits?

We’ve gone over how to add package traits to a package, so now let’s go over how you can use them.

Unfortunately, at the time of writing this, Xcode’s UI does not support enabling traits on a Swift Package. Therefore, you cannot use package traits in a traditional Xcode project.

Instead, you must enable them in your own packages through your Package.swift file. Here’s how that is done.

// swift-tools-version: 6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  // ...
  dependencies: [
    // ...
    .package(
      url: "https://github.com/mhayes853/swift-uuidv7",
      branch: "sharing-grdb-icloud",
      traits: ["SwiftUUIDV7SharingGRDB", "SwiftUUIDV7Tagged", "SwiftUUIDV7Dependencies"]
    )
  ],
)
        

That’s all, you can now begin using them right away!

However, passing an explicit set of traits will disable the default trait. If you still want to enable the default trait, you must also pass .default to the set of traits.

// swift-tools-version: 6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  // ...
  dependencies: [
    // ...
    .package(
      url: "https://github.com/swiftlang/swift-subprocess.git",
      branch: "main",

      // Keeps the default trait enabled despite passing an explicit set of traits.
      traits: [.default]
    )
  ],
)
        

Using Traits to Integrate with Other Packages

On its own, swift-uuidv7 provides a simple UUIDV7 type that’s more robust than other Swift implementations in the wild by offering timestamp extraction, a Comparable conformance, and sub-millisecond monotonicity. Yet almost certainly you’ll want to store instances of UUIDV7 in your database using GRDB and Structured Queries, use them as entity identifiers for App Intents, and much more.

You can certainly create the very trivial @retroactive conformances on UUIDV7 in your own project. For instance.

// Inside your project...

import UUIDV7
import StructuredQueries

extension UUIDV7: @retroactive QueryBindable {}
        

However, this conformance would only live inside your own project. Either you would have to duplicate it between different projects, or you would have to create a dedicated package for this 1 line conformance. For many, copying it between different projects is probably fine, but it still isn’t the most ideal solution here. The latter option of creating a tiny package at scale would probably create the same micro-package culture that can be found in the NPM ecosystem.

Rather, we can use package traits to solve this issue, and provide an official conformance that can be used in any project.

// Inside swift-uuidv7...

#if SwiftUUIDV7StructuredQueries
  import Foundation
  import StructuredQueriesCore

  extension UUIDV7: QueryBindable {}
#endif
        

Who adds the trait?

In the above example, either StructuredQueries or UUIDV7 can add a trait to support this integration.

For instance, StructuredQueries could create a StructuredQueriesUUIDV7 trait that adds a dependency on swift-uuidv7, and that trait would provide the conformance that you see above. Alternatively, UUIDV7 could create a SwiftUUIDV7StructuredQueries trait that adds a dependency on swift-structured-queries, and that trait would provide the conformance you see above. Obviously, only 1 package can actually make such a trait because we would be in circular hell otherwise.

Since UUIDV7 is designed to integrate with numerous different libraries (5 at the time of writing this), it would be quite cumbersome if I had to convince the maintainers of each library to add a trait specifically for my very niche package. Therefore, it’s for the best if I provided all the integrations myself through UUIDV7, and in return it keeps all the integrations bundled in 1 simple place.

A Coordination Problem

That being said, this can turn into a nasty coordination problem if there isn’t any consideration around which packages add certain traits.

For instance, what if a hot new library comes around and adds UUIDV7 support through a trait of its own? Now the simplicity of having all of UUIDV7s integrations in a single place is lost, because a new library now maintains its own integration with UUIDV7.

We could define best practices that state that smaller and more stable packages like UUIDV7 should not offer any package integration traits, and instead only let other more volatile and larger packages (eg. GRDB, Structured Queries) define such traits. From the standpoint of how I think of objects, this makes a lot of sense because larger packages with more knowledge give meaning to the smaller and simpler packages with less knowledge.

However, this now creates a problem where maintainers of more volatile and larger packages have to specifically set out to implement their own integration of such smaller packages. On one hand, this can be a maintenance burden if those maintainers decide to integrate with a lot of smaller packages. On the other hand, it also means that integrations with smaller packages are not readily available because it would require the efforts of several large package maintainers, each with their own more important concerns.

If we want the best outcome, I don’t think we can rely on an entirely dogmatic standard. Rather, this may need to be solved on a package by package basis, where each package defines how it integrates with others. Of course, the definition of integration will likely change as the package evolves. For instance, I don’t think directly supporting 300 package integrations in UUIDV7 is necessarily the best maintenance idea, and at that point I would rather delegate those integrations to those package maintainers.

The larger community would of course have to adhere to those socially agreed upon practices for each package, and be informed when those practices change. Seeing how this will scale may be quite interesting.

— 8/8/25

PS. I’m creating a new series of content that I will call “Swift Bits” that will contain small Swift-specific articles such as these.

I mainly want to focus my writing more on higher level ideas that apply to building products and creating new mediums of spreading ideas. Those ideas carry over into how I write Swift on a day-to-day basis, but I think only focusing on Swift as a whole is quite a narrow viewpoint on designing real systems.

Still, seeing language specifics directly can be useful given the detachment most programming languages have from the systems they create. In that sense, I do believe that this kind of writing is worthwhile from time to time.

-- Minutes to Read

So, how does one understand this seemingly impossible to understand topic in programming? If seemingly, no one can explain it to a 5 year old, do we truly understand this intellectual monstrosity?

Google what a monad is, and this is one of the top image results.

I’m sure that taught you a lot, and now I’m totally sure that you really understand what a monad is…

Well, we could also try by showing you an example of one. Here, take a look at the documentation for Result in Swift!

Still doesn’t make you understand it… Ok, how about we have ChatGPT give us a nice summary! (I’ll even tell it that I’m a 5 year old!)

Okay! Imagine you have a **magic box**. This magic box can hold *one toy* inside.

Now, this isn’t just any box—it’s a **special box**:
    1.    You can **put** a toy in the box.
    2.    You can **play** with the toy **inside** the box, but only using special gloves (because it’s a magic toy).
    3.    If the toy does something special (like turning into a different toy), the box makes sure everything stays safe and magical.

That’s kind of what a **monad** is in programming:
* It’s like a box that **holds a value**.
* You can **do things with the value**, but you have to use special rules to keep everything safe and tidy.
* It **knows how to handle the magic stuff** like errors, waiting, or doing things in order.

So, a monad is a *magical box* that helps programmers **play nicely with tricky things** like missing data, time delays, or big sequences of steps—without breaking the game. 🧙📦✨

Want a grown-up version too?
        

ChatGPT has introduced concepts like “special box”, “holds a value”, and “handles the magic stuff”… I think you’re probably more confused now…

Good Teaching and Good Learning are Experiential

This is one of my personal laws of design, and the core idea is that we learn best through using all of our human senses (not just hearing and eyesight). Good education is not just about transferring information from point A to point B, because good education forces you to accept a style of action into your lifestyle rather than focusing on concept retention.

Therefore, all existing online resources (including this article) will never be able to teach you what a monad is in programming. Simply put, only reading articles, looking at fancy diagrams, or looking at code is not making you adopt the style of thinking that enables you to use monads to their fullest potential.

You’re failing to learn monads because you’re stuck trying to “learn monads”!

Pain is the Only Way to Learn Monads

You’re going to learn monads through physical and mental pain. Yes, you will experience pain over and over again as you write that same repetitive and absolutely annoying code. In fact, you’re not even going to be writing monads when you experience this pain, and you don’t need to understand them to feel the pain. Eventually, this will become so painful that monads will become the natural cure for that pain.

I can show you examples (in words and code) that describes the information of this pain. However, you will only be enlightened once you feel that pain yourself.

Arrays

You’ve probably written code like this before.

let array = [1, 2, 3]
var doubled = [Int]()
for num in array {
  doubled.append(num * 2)
}
        

Now do this for every single time you want to iterate over an array in your application. This is painful. You don’t want to write for element in array every single freaking time, and then either call array.append or filter through an if statement every single time.

let array = [1, 2, 3, 4]

var tripled = [Int]()
for num in array {
  tripled.append(num * 3)
}

var even = [Int]()
for num in tripled {
  guard num.isMultiple(of: 2) else { continue }
  even.append(num)
}

var stringified = [String]()
for num in even {
  stringified.append(String(num))
}

var joined = ""
for str in stringified {
  joined += "\(str), "
}

print(joined) // "6, 12, "
        

Reading this code is painful. Writing it was also painful. Good, now let’s have monads cure our pain!

let str = [1, 2, 3, 4]
  .map { $0 * 3 }
  .filter { $0.isMultiple(of: 2) }
  .map(String.init)
  .joined(separator: ", ")
        

Much more compact, much less painful. In this case, “the magic stuff” (according to the ChatGPT explanation) is the iteration. You no longer have to worry about the iteration, and instead you specify what the iteration means.

Result

You’re probably familiar with try catch (Swift uses do catch instead) for error handling. Sometimes, that can be annoying such as when you want to store an Error in a struct like so. (An example of where you would want to store an error in a struct would be if you wanted to render an error message in your UI.)

// ❌ Bad

struct MyData {
  let error: (any Error)?
  let value: String
}

// ✅ Good

struct MyData {
  let result: Result<String, any Error>
}
        

So now let’s say we’ve got a function that throws, and returns a Result that doesn’t contain a String.

func someWork() -> Result<UUID, any Error> {
  // ...
}
        

We need to pass a Result<String, any Error> to MyData. So we’ll need to transform this result.

func transform() -> MyData {
  switch someWork() {
  case .success(let uuid):
    MyData(result: .success(uuid.uuidString))
  case .failure(let error):
    MyData(result: .failure(error))
  }
}
        

This is painful code to write. I don’t want to think about the failure case, instead I merely only care about the success case. So let’s turn to monads to cure our pain.

func transform() -> MyData {
  MyData(result: someWork().map(\.uuidString))
}
        

Nice! However, what if instead of a uuid string, we treated the UUID as a user identifier of some kind, and then we wanted to look up the user name for that identifier. If the user doesn’t exist, we’ll return a failure result.

func username(for id: UUID) -> Result<String, any Error> {
  // Return success if user with id exists, else failure...
}

func transform() -> MyData {
  // ❌ Won't compile because map returns Result<Result<String, any Error>, any Error>
  MyData(result: someWork().map { username(for: $0) })
}

func compilingTransform() -> MyData {
  // Back to switch...
  switch someWork() {
  case .success(let uuid):
    switch username(for: uuid) {
    case .success(let name):
      MyData(result: .success(name))
    case .failure(let error):
      MyData(result: .failure(error))
    }
  case .failure(let error):
    MyData(result: .failure(error))
  }
}
        

Again, this is painful because we have to think about the failure and success cases twice! My primary concern here is translating the UUID into a username, so let’s turn to monads to cure our pain.

func transform() -> MyData {
  MyData(result: someWork().flatMap { username(for: $0) })
}
        

In this case, “the magic stuff” (according to the ChatGPT explanation) is the handling the result for an operation. You don’t need to worry about the result handling, and instead you specify what the result handling means.

Pain Gives Meaning to Monads

You still don’t understand monads from those examples. You won’t until you feel the pain, the least I can do is show you what that pain feels like, such that you can anticipate it. Pain is a method of learning.

Monads are actually an incredibly simple idea, just like this glass.

Yet how do you "learn a glass"? What does that even mean?

A glass can do many things, it can hold liquid, dirt, toys, cash, coins, etc. It can be used to cover or trap something by acting as a surface. It’s also transparent, so we can see and learn from the internals of what it holds.

Try drinking water without a glass or some other object. You’ll find this is painful, and you’ll use the glass as a cure. The pain gives meaning to the glass.

Since the glass is so simple, we don’t derive meaning from it, we imbue it with meaning instead. Pouring different liquids give the glass a different meaning in a certain context. All of these meanings combined is what gives us an understanding of what a glass is.

Understanding monads in programming has nothing to do with functors. endofunctors, or mathematical functions. Those terms do not describe the systems you’re building because they describe mathematics. You describe the systems you’re building with the artifacts at your disposal, and monads are an artifact to augment your ability to do so.

So, to end this particular discussion.

Don’t find meaning in Monads, give Monads your meaning.

-- Minutes to Read

Collaboration over Automation

Collaboration breeds an environment where systems and their users operate towards a discovered shared end goal, and enhances the innate abilities of all actors involved. Automation on the other hand, is driven solely by one actor towards their own imposed and possibly detrimental goal.

Collaboration allows and encourages mistakes, and uses them to enhance innate ability of all actors. Automation on the other hand, punishes and forbids mistakes, and creates a cost center around them both monetarily and emotionally.

Collaboration puts discovery, and searching for better strategies as its utmost priority. Automation on the other hand, discourages discovery in favor of optimizing what is already discovered.

Collaboration encourages requests between actors, and encourages questioning the validity of both the request and its processing. Automation on the other hand, encourages one actor to command the others, and does not encourage questioning the validity of the command or its processing.

Collaboration encourages a universal understanding of the larger picture. Automation on the other hand, promotes delegation and convenience at the expense of outsourcing such understanding.

Good Learning and Teaching are Experiential

Good learning is more than retaining or memorizing information. Good teaching is more than transferring information from point A to point B.

Good learning involves the acceptance of said information into the functioning processes of the learner. Good teaching involves creating such an acceptance.

Good learning involves more than seeing and consuming text, photos, or videos, but instead involves using all available senses (sight, taste, feel, sound, touch, etc.). Good teaching involves creating environments, media, and processes where such senses can be utilized to their utmost effectiveness.

Good learning involves blending information with actionable scenarios, and correlating the two. Good teaching involves the creation of such scenarios blended with the relevant information.

Good learning means understanding the relations of isolated information into larger contexts. Good teaching involves communicating the larger context when isolated information is presented.

Good learning emphasizes experiencing information. Good teaching emphasizes creating such experiences.

Evolution is a Design Decision

Evolution is essential for thriving. Needs, wants, and circumstances can change at a moment’s notice. Systems that cannot evolve when necessary will eventually collapse.

Evolution requires understanding the conceptual models that the system offers, and the contexts in which they work and don’t work in. Such an understanding gives prose to where and how evolution must occur.

Evolution requires dependence on abstractions and generalities, and not particulars that require evolution at different rates. That is to say, loose coupling between evolvable components is necessary for creating evolvable boundaries in the larger system.

Evolution requires understanding and exploring different possibilities, and is not focused on concrete steps that must be adhered to.

Context is King

Context denotes the decisions that are right and wrong. Some decisions can be right in certain contexts, and wrong in others.

Context requires less dogmatism, and more pragmatism. Even my personal design laws must be applied pragmatically, and trade offs and variances must be considered in different contexts.

Context requires understanding systems and ideas in their entirety, and which parts of the systems or ideas apply to a specific context. Individual parts of evolvable systems in different contexts should be applicable to other contexts, even if not in whole.

Context requires ideas to fit within it. General ideas should be applicable to a large amount of contexts, but not need to service the entirety of such contexts. Particular ideas should be applicable to a smaller number of contexts, but should service them more in their entirety. General ideas defines how the particular ideas are formed within a context.

Context requires understanding possibilities, and how those possibilities are affected by the context. In such a case, the context serves as a factor in the equation for the result of a possibility. The ability to quickly experiment with different possibilities in a context is essential for making correct decisions.

Objects are Best Used as Agents of Knowledge

Objects encapsulate knowledge they understand. Such knowledge can represent the static bits of information in their corpus, but also the processes for representing such information which are static bits of information themselves.

Objects take many forms of representation (code, neurons, physical tools, etc.), and provide interfaces for interacting with their knowledge. Whatever is behind those interfaces is what is encapsulated within the object. Yet, the interface itself is knowledge that an object encapsulates, and represents to the outer world.

Objects that can learn from their contexts are rich in individual meaning, encapsulate lots of knowledge, and have the ability to evolve into different contexts using their pool of knowledge. Such objects should enrich their context by providing highly capable interfaces to request information from them in order to aid evolution. If such an object were to provide an interface that commands its actions rather than request its information, then it is not being used to enrich its context, and it would not be compatible with evolution.

Objects that are static in their knowledge require their surrounding context to give meaning to them, encapsulate little, and have little ability to evolve on their own. Such objects should invite their usage by providing a small and simple interface to interact with them to aid evolution. If such an object were to expose a large and informational interface, then it cannot not be given full meaning in different contexts, and it would not be compatible with evolution.

Human Wisdom must Contain Human Power

Human wisdom increases when systems are designed to be collaborative instead of automative.

Human wisdom increases when systems can teach their users through experience, and encourage their users to learn from their teachings.

Human wisdom increases when systems can evolve to serve their user’s ever changing needs at the moment those needs become apparent.

Human wisdom increases when systems are designed to correctly fit their context, and make use of the appropriate principles at the correct volume to do so.

Human wisdom increases when systems present objects with the appropriate interfaces given their levels of knowledge.

Human wisdom must contain human power, or else we risk terrible consequences.

— 7/12/2025

Ending Commentary

Some laws I adhere to in design. Design to me does not solely mean the act of making a product look incredible, easy to use, or accessible as that is quite a narrow view point on real systems. It also does not solely refer design patterns in code or overall software architecture. Both these perspectives are essential, but are too narrow to consider in isolation when considering entire systems. The Design of Everyday Things by Don Norman gives great insight, as well as the ideas of many others (especially Bret Victor).

These laws are meant to be applied to technological systems in different domains (programming, UI Design, project management, etc.). I also belive that these laws have been largely ignored in todays systems, and that is naturally something I would like to change.

Update: Some have asked about specific examples of where I think these laws have been violated. Much of my other writing contains examples of these violations, and I intend to explore more examples in future writing. However, doing so here would make readers focus on the examples rather than the true meaning of the laws themselves. In other words, I don't want this to attract comments such as, "ThIS eXamPLE dOESn'T tALk aBoUt tHiS nEW fEatURE iN jAVa, sO tHE enTIRe aRTiCLE (which isn't about Java) iS bS."

-- Minutes to Read

If you write code, you’re probably familiar with the concept of high and low level languages. In technical terms, low level means closer to the machine, like assembly languages or machine code. Higher level in technical terms means further from the machine like C, JavaScript, Swift, and so on.

However, this shouldn’t be the case. Speaking of high and low levels in the context of how close a language is to computer architecture is quite a narrow view point on the world.

Rather, in the context of “real systems”, this distinction should be reversed. In other words, C, JavaScript, and Swift are lower-level languages. Meanwhile, assembly and machine code are higher-level languages.

For instance, if we’re writing a pseudo random number generator, which language do you think gives you a better understanding about the process of how random numbers are generated?

x86-64 Assembly

rotl:
        push    rbp
        mov     rbp, rsp
        mov     QWORD PTR [rbp-8], rdi
        mov     DWORD PTR [rbp-12], esi
        mov     eax, DWORD PTR [rbp-12]
        mov     rdx, QWORD PTR [rbp-8]
        mov     ecx, eax
        rol     rdx, cl
        mov     rax, rdx
        pop     rbp
        ret

xoshiro_256_next:
        push    rbp
        mov     rbp, rsp
        push    rbx
        sub     rsp, 24
        mov     QWORD PTR [rbp-32], rdi
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 8
        mov     rdx, QWORD PTR [rax]
        mov     rax, rdx
        sal     rax, 2
        add     rax, rdx
        mov     esi, 7
        mov     rdi, rax
        call    rotl
        mov     rdx, rax
        mov     rax, rdx
        sal     rax, 3
        add     rax, rdx
        mov     QWORD PTR [rbp-16], rax
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 8
        mov     rax, QWORD PTR [rax]
        sal     rax, 17
        mov     QWORD PTR [rbp-24], rax
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 16
        mov     rcx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        mov     rdx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 16
        xor     rdx, rcx
        mov     QWORD PTR [rax], rdx
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 24
        mov     rcx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 8
        mov     rdx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 24
        xor     rdx, rcx
        mov     QWORD PTR [rax], rdx
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 8
        mov     rcx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 16
        mov     rdx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 8
        xor     rdx, rcx
        mov     QWORD PTR [rax], rdx
        mov     rax, QWORD PTR [rbp-32]
        mov     rdx, QWORD PTR [rax]
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 24
        mov     rax, QWORD PTR [rax]
        xor     rdx, rax
        mov     rax, QWORD PTR [rbp-32]
        mov     QWORD PTR [rax], rdx
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 16
        mov     rax, QWORD PTR [rax]
        mov     rdx, QWORD PTR [rbp-32]
        add     rdx, 16
        xor     rax, QWORD PTR [rbp-24]
        mov     QWORD PTR [rdx], rax
        mov     rax, QWORD PTR [rbp-32]
        add     rax, 24
        mov     rax, QWORD PTR [rax]
        mov     rdx, QWORD PTR [rbp-32]
        lea     rbx, [rdx+24]
        mov     esi, 45
        mov     rdi, rax
        call    rotl
        mov     QWORD PTR [rbx], rax
        mov     rax, QWORD PTR [rbp-16]
        mov     rbx, QWORD PTR [rbp-8]
        leave
        ret
        

C

#include <stdint.h>

static inline uint64_t rotl(const uint64_t x, int k) {
  return (x << k) | (x >> (64 - k));
}

uint64_t xoshiro_256_next(uint64_t s[4]) {
  const uint64_t result = rotl(s[1] * 5, 7) * 9;
  const uint64_t t = s[1] << 17;

  s[2] ^= s[0];
  s[3] ^= s[1];
  s[1] ^= s[2];
  s[0] ^= s[3];
  s[2] ^= t;
  s[3] = rotl(s[3], 45);
  return result;
}
        

I would imagine that you find that the C code describes the process of generating a random number more clearly. In other words, the C code describes reality more than x86 assembly.

Take a line from the assembly example.

mov     rax, rdx

mov is a move instruction, and rax and rdx are registers. As a whole, a move instruction can be applied in an infinite number of programs, and rax and rdx will also be a part of those infinite numbers of programs. In other words, a move instruction is very high level because it doesn’t describe the domain specific processes of any particular program. It is therefore detached from reality.

Notice how the concept of registers and instructions are only directly relevant in the context of the assembly example. We don’t need to talk about these things in C, because they are ultimately irrelevant (only in the sense of understanding, not execution) to the larger process of generating a random number. The C code is closer to reality because it describes such reality more accurately from an understandings stand point.

In assembly, because we’re so focused on primitive details like registers and instructions, we easily miss the larger picture. We therefore miss reality.

To conclude here, if we want to build great systems, we need to optimize for understanding and reasoning about our systems. Computer architecture is an implementation detail that is largely detached from reality as it says nothing about our systems on its own. Sticking closer to computer architecture may produce faster and more performant programs, but it is often detached from the deeper truth of what we directly create.

All in all, lower level means providing both full and real awareness of the true reality of our systems, and higher level detaches itself from that in order to focus more on abstractions. In this sense, Assembly is higher level than C.

To end, in this exploration I stayed close to existing languages that are used in the mainstream. I suppose one could therefore ask about a language so low level that it describes and enhances reality perfectly, and how that would look and operate. That is, something that indeed may exist in a primitive form.

-- Minutes to Read

These past few months, I’ve been working on standardizing a set of tools that I’ve been using across a few of my Swift projects. Today, I’m opening them up to you to use in your applications, and I believe these tools will largely remove headaches around data consistency from remote/asynchronous data for you. This article will largely be about my inspirations for building such a library, and what I think it means for how we manage application state derived from asynchronous data in Swift.

You can check out the library here for a more direct dive into its features, and the many demos, case studies, and documentation articles I’ve prepared. I believe that this library is quite flexible, and can be used in a variety of ways that I don’t even know of yet. I wanted to document as many of the strategies that I’ve used it in real projects in its documentation, and I believe you will also be able to find ones that I haven’t figured out myself. If you find some cool use cases that I haven’t documented, let me know such that we can either get a case study or an article going.

As a whole, I want to keep this article related to the higher-level problems that are being solved by the library. Checkout the repo if you want a typical overview of its features with plenty of examples.

Background and Inspirations

The past 1.5 years using React Native at a startup is largely responsible for my inspirations for building Swift Query. In particular, I was often responsible for combining all sorts of data (Location, Travel Estimates, Geo-spatially Separated Events, Arrivals at Locations, and of course “Users”) from different sources (Device APIs, SQLite, AWS, and our REST API). Additionally, much of this data also needed to be observed in real-time. In other words, it’s quite safe to say that many of us have worked on applications like these, and managing such data in many different ways is common place for today’s apps.

That being said, all of this data comes asynchronously, and takes a non-trivial but varying amounts of time to load from its source. The code itself to fetch the data often isn’t the hard part (unless it’s paired with complex algorithmic processing afterwards), and can be done in just a few lines for most data sources.

Yet, what does it mean to load asynchronous data? Such data comes from the physical world, because something physical must work to provide it, otherwise it we wouldn’t consider it “asynchronous”. As software developers, we rarely ever have to think of design in the context of the physical world. Rather, we love to create our own abstract worlds, and demand physical reality bends to our world. As such, we loathe error handling, keeping asynchronous data consistent when displayed in the UI, and creating systems with the expectation of failure. This is especially difficult considering modern UI frameworks are declarative and are driven via local state variables, whereas most data fetching is strictly imperative and affects the application’s global state.

Yet, if we want to build great experiences for our users, we need to collaborate with physical reality, and augment their ability beyond physical reality in our abstract worlds.

This all sounds incredibly philosophical, but it is exactly the reason why tanstack query is popular in the JavaScript world. The meaning of asynchronous data is incredibly complex in any given system, and if we’re to collaborate with physical reality we must design for failure. As such, we must implement retry mechanisms, caching, informative loading/error UI states, cancellation, keeping data consistent between screens, automatic refetching, stale-while-revalidate, network connection monitoring, exponential/fibonacci/linear backoff strategies, pagination, deduplication, and logging on top of our already existing application features. Tanstack query has an answer for all of this in the JavaScript world.

I get it, you have better things to be doing rather than implementing all of those mechanisms to collaborate with physical reality in Swift. Your users also think the same for the record. Therefore, I have decided to build a port of Tanstack Query that’s tuned for Swift, SwiftUI, swift-sharing, Concurrency, UIKit, Linux, WASM, and much more in the future. I want this library to aid the development of Swift as a true cross-platform language by solving such a common problem at the most literal level possible.

I built this library because I missed Tanstack Query when working in Swift.

Addressing Tanstack Query’s Limitations in Swift Query

Additionally, I aim to address many long-standing issues that Tanstack Query has in order to make something that can fit in to any of your asynchronous data needs. In other words, this library is meant to provide you a framework of thinking about asynchronous data by providing far more generic abstractions than Tanstack Query. This in turn may increase the overall learning curve of the library, but such a fate is better than it not being able to serve your needs.

Automatic Refetching

Tanstack Query will automatically refetch data when the user foregrounds your app, or the moment user’s network connection status flips from offline to online. Swift Query also provides these tools, but it also allows you to create your own custom refetch triggers by using the FetchCondition protocol. Therefore, you could make it so that data is automatically refetched when a user logs in/out, or when low-power mode is enabled, and much more.

Data Fetching Methods

Tanstack Query has 3 methods of fetching data suited for different purposes:

• Queries
  • Fetching data as a single entire entity (this is the most common method).
• Mutations
  • Mutating asynchronous data. (eg. HTTP POST request)
• Infinite Queries
  • For paginating data (eg. Infinite scrolling lists).

Swift Query provides these 3 methods out of the box, but also allows you to create your own methods via the QueryRequest protocol. For instance, you could create a method that specializes in fetching recursive data, or combining multiple paginated data streams together.

Another difference from Tanstack Query is that in Swift Query, infinite queries and mutations are derived from typical queries. That is, MutationRequest and InfiniteQueryRequest are conformances to QueryRequest. In Tanstack Query, mutations are a completely separate concept not derived from queries, and there’s even a special MutationCache for caching their state. Such a cache is not needed in Swift Query, because mutations are queries. Additionally, deriving both infinite queries and mutations from typical queries allows QueryModifier conformances to work with all 3 methods by default.

Swift Query also differs slightly in how infinite query refetching works. In Tanstack Query, refetching an infinite query would refetch every single page starting from the beginning in a waterfall style. In Swift Query, only the initial page is refetched, and all other pages are simply removed. If you want to retain the Tanstack Query behavior, calling refetchAllPages on a QueryStore will do exactly that.

As for mutations, Swift Query adds 1 additional feature not found in Tanstack Query. In Tanstack Query, multiple calls to mutation.mutate will run concurrently, however the mutation state from useMutation only displays updates from the most recent call. Swift Query also works this way, but an additional history property exists that allows you to inspect the previous results from other calls to mutate.

Query Cache

Tanstack Query holds all of your query data in something called the QueryCache. This cache will evict entries based on a running timer in order to properly manage memory. Swift Query also implements uses a similar cache, but it evicts entries based on memory pressure warnings from the operating system instead of by a timer. However, the good news is that you can write your own custom query cache in Swift Query by conforming to the QueryClient.StoreCache protocol. Therefore, if you want the timer approach, you have the option to implement it yourself.

Query Client

The QueryClient in Tanstack Query holds all of your queries, and allows you to operate on them (eg. Refetching, invalidation, etc.). This is also the case for Swift Query, except that you aren’t required to attach a query to the QueryClient. You can use QueryStore.detached instead of obtaining a QueryStore through a QueryClient, and this will give you a store that runs its query in isolation. By doing this, you can even create your own state management system if you find that QueryClient does not suit your needs.

Additionally, the way one interacts with QueryClient in Tanstack Query is by calling methods such as refetch or invalidate directly on the client. Swift Query does not provide those methods on QueryClient. Instead, it provides methods that return QueryStore instances directly, and QueryStore has the appropriate refetch and invalidation methods. This allows you to perform advanced and composable operations on the QueryClient without you having to pester me to add a new method on QueryClient.

For example, the following (which is real-world code) can be done in 1 operation. Here, we’re removing queries from the client that correspond to files being deleted from a directory. Then, we’re refetching all queries that have a corresponding file that has had its data updated, and that are actively being displayed in the visible UI somewhere.

extension QueryClient {
  public func processDirectoryChanges(
    _ changes: IdentifiedArrayOf
  ) async throws {
    let storesToRefetch = self.withStores(
      matching: .audioProperties,
      of: HapticaAudioProperties.Query.State.self
    ) { entries in
      let filesToRemove = changes.filter { $0.kind == .deleted }
        .map { HapticaAudioFile(id: $0.id) }
      for file in filesToRemove {
        entries.removeValue(forPath: .audioProperties(for: file))
      }
      return changes.filter { $0.kind == .dataUpdated }
        .compactMap { entries[.audioProperties(for: HapticaAudioFile(id: $0.id))] }
        .filter { $0.subscriberCount > 0 }
    }
    await withThrowingTaskGroup(of: Void.self) { group in
      for store in storesToRefetch {
        group.addTask { try await store.fetch() }
      }
    }
  }
}
        

You have access to all the necessary properties and methods directly on QueryStore to perform whatever state management you need. The withStores method takes a closure that allows you to edit the existing stores inside the QueryClient like you would a dictionary.

Query Keys

Swift Query’s QueryClient also supports pattern matching using a query key like in Tanstack Query. However, the query key is called a QueryPath in Swift Query, and QueryPath is a dedicated struct that can be constructed with an array literal of Hashable and Sendable elements.

Unlike Tanstack Query, your query is not required to specify a QueryPath if it conforms to Hashable or Identifiable. In such a case, the QueryRequest synthesizes a conformance for you. To visualize:

struct MyQuery: QueryRequest, Hashable {
  // Does not need a query path...
}

struct MyQuery2: QueryRequest {
  // You must provide a query path because it is not Hashable or Identifiable...
  var path: QueryPath {
    ["my-query-2"]
  }
}
        

As an internal implementation note, a query key in Tanstack Query is represented by the full bloat of a JavaScript array. In Swift Query, the QueryPath type is optimized to not allocate an array when the path is either empty or only contains a single element.

By using a dedicated type for the paths, you can also create dedicated domain-specific constants by extending QueryPath.

extension QueryPath {
  static let currentUser = Self("current-user")

  static func currentUserProject(for projectId: Int) -> Self {
    .currentUser.appending(projectId)
  }
}
        

Query Options

In Tanstack Query, you customize the behavior of a query by passing a bag of options, which looks like such:

const myQuery = useQuery({
  queryKey: ["my-query"],
  queryFn: async () => {
    // Fetch the data...
  },
  retry: 3,
  staleTime: 5000
})
        

The problem with this approach is that the structure of the object is solely determined by the maintainers of Tanstack Query. You are essentially stuck with whatever configuration is deemed necessary by the library. There are ways around this, but generally they are not the most intuitive.

Instead, Swift Query defines queries as types, which allows for a modifier system similar to SwiftUI. In fact, you can create your own custom modifiers through the QueryModifier protocol. The disadvantage of this however is that queries require a some additional boilerplate due to needing to create an entire separate type for each one.

Here’s the same query written in swift query.

struct MyQuery: QueryRequest {
  var path: QueryPath { QueryPath("my-query") }

  func fetch(
    in context: QueryContext,
    with continuation: QueryContinuation<Value>
  ) async throws -> Value {
    // Fetch the data...
  }
}

let myQuery = MyQuery().retry(limit: 3).stale(after: 5)
        

Having a custom modifier system means that you can configure your queries in ways that the library doesn’t natively support, and work such support into your own app. For instance, the library doesn’t ship with a native method to artificial delay a query, but such a modifier can easily be written and used across many different queries.

struct DelayModifier<Query: QueryRequest>: QueryModifier {
  let delay: Duration

  func fetch(
    in context: QueryContext,
    using query: Query,
    with continuation: QueryContinuation<Query.Value>
  ) async throws -> Query.Value {
    try await Task.sleep(for: self.delay)
    return try await query.fetch(in: context, with: continuation)
  }
}

extension QueryRequest {
  func delay(for duration: Duration) -> ModifiedQuery<Self, DelayModifier<Self>> {
    self.modifier(DelayModifier(delay: duration))
  }
}

let myQuery = MyQuery().delay(for: .seconds(0.3))
        

Multiple Data Updates

Tanstack Query provides a streamedQuery utility to allow you to yield multiple updates from your queries. This function requires that your query returns a JavaScript AsyncIterable, and the library handles the rest. Instead, Swift Query allows you to yield multiple updates from your queries via the QueryContinuation handed to your query.

This makes it easy to implement patterns such as.

struct SomeQuery: QueryRequest, Hashable {
  func fetch(
    in context: QueryContext,
    with continuation: QueryContinuation<Value>
  ) async throws -> Value {
    let localValue = try await LocalDatabase.fetchValue()
    continuation.yield(localValue)
    return try await Server.fetchValue()
  }
}
        

Ultimately, you’re still forced to return a final value from your query. If that value is no different from the last yielded value, then simply return the last yielded value.

Integrating with your App Architecture

One of my core principles with this library was to not care about your architecture as much as possible. That is, whether or not you use MVVM, TCA, MV, or some other combination of MXX, the library should still work for your use case. From my usage so far, I’ve had no trouble using the library in each of those architectural patterns. I also have taken making the act of writing tests heavily into consideration, and all the demos and case studies in the repo have sufficient test coverage to demonstrate this.

Concurrency

The library is also on the bleeding edge of Swift Concurrency, and provides tools that let you run your queries on custom TaskExecutor conformances and more. Everything is appropriately Sendable, and you can use the library from any actor or thread in your app. The only limitations are that the data types you return from your queries must also be Sendable, your query structs themselves must also be Sendable, and to make sure that you hop to the main thread if you’re observing QueryStore directly for UI updates.

The library also runs its work via the QueryTask type. This is a special wrapper around a typical Swift Task that doesn’t begin scheduling its work immediately after initialization. Rather, you tell it explicitly when to run via runIfNeeded, and you can also use it to schedule work in a serial manner compared to other tasks via calling task1.schedule(after: task2). If you end up scheduling tasks in a cycle, the library will warn you about this. In particular, you’ll find the flexibility of this type to be very useful for testing, as it gives you control over when your query is executed.

Network Layers

Another principle of the library is abtstracting over an async function in general, and not over the network.

You may find that you want to write all of your networking code directly inline inside your query structs, like so.

struct UserQuery: QueryRequest, Hashable {
  let id: Int

  func fetch(
    in context: QueryContext,
    with continuation: QueryContinuation<User>
  ) async throws -> User {
    let url = URL(string: "https://api.myapp.com/user/\(self.id)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(User.self, from: data)
  }
}
        

Certainly, you can do this, and it is definitely fine for smaller apps. However, Swift Query was designed to enhance your network layer, and not replace it. In fact, you’ll find that in all of the demos and case studies that the query structs themselves are actually quite small, and that they usually call out to a method (on some API class) that actually performs the real data fetching.

Regardless, the library’s choice to abstract over a plain async function allows you to implement your queries no matter how well defined your app’s network layer is.

Future Directions

In general, I think the library provides all of the essentials today, but there are a few things that I want to look into in the potential future.

1. Better defaults on Linux.
   • As of now, the library will compile and run on Linux, but there is no default NetworkObserver or ApplicationActivityObserver provided by the library. As such, you’ll be forced to create your own conformances if you want your queries to automatically be refetched when the your app foregrounds, or when the user’s network connection flips from offline to online.
2. A better default store cache on non-Apple platforms.
   • Currently, the default store cache listens for memory pressure warnings from the operating system via DispatchSource.makeMemoryPressureSource. This API, or really it seems any memory pressure API, is not available on non-Apple platforms. As of now, the default store cache on non-Apple platforms will not automatically cleanup unused queries in any way. Of course, you can implement your own store cache to get around this, but a better default would be ideal here.
3. Typed QueryContext.
   • Right now the QueryContext is untyped and has no generics. As such, context properties often have to be stored as any Sendable or any MyProtocol, and then casted to the appropriate strong types in the right contexts. I would like to see if it’s possible to add some sort of strong typing to this in the future.
4. An official headless mode.
   • In some cases, you may want to run a query in some background process (eg. In a Tool in the new Foundation Models framework) instead of in the UI. This way, you can still benefit from modifiers such as retries, exponential backoff, duration logging, and much more. However, doing so would require constructing a QueryStore, which is explicitly meant for managing the query’s active running state in your application. In a background context, this additional state management is largely unnecessary because you’re not rendering any UI.

Start Using Swift Query Today

You can start using Swift Query today in your apps. However, I have not yet declared that the library is fully stable, so proceed at your own risks. In any case, try it out and let me know how it goes.

I’ve installed the new iPadOS 26 beta on my iPad Pro this week, and have built an Xcode project a singular time on an iOS 26 simulator. As of now, that has been my exposure to using “liquid glass”. It seems to have gotten quite some attention during this past WWDC week.

As a whole, with how Apple has trended towards a “smaller window” design across all of their platforms I think this aesthetic makes sense. It looks refreshing and the visuals are done well, but of course a bit more work seems to be needed here. Pure navigation elements also take up less screen space meaning more room for the actual screen content, which is generally a good thing. Overall, it’s new and fun to use, though I’m sure that feeling will eventually wear off over time.

However, nothing really fundamental changed here. Notes still lets you write notes, photos still lets you view photos, camera still lets your shoot photos and video. The overall navigation of these apps may have improved, and thus have become “easier to use”. Virtually all of the same features exist in each of these apps, and none of them have been changed substanially outside of these navigation concerns.

Making an app look visually pleasing, “easy to use”, and “accessible” are only some of the more superficial concerns of an app’s overall design. They are a neccessary evil to represent and obtain the "real value" of software. You can have all 3 of those things, but still have a terrible overall experience if your app doesn’t provide "real value”. “Real value” generally comes from providing the information necessary to answer the user’s questions and help to guide them make decisions on navigating their life.

For instance, take an empty day on the newly liquid glassified calendar app. It’s clear that I have no events planned for this day, and that the date of the day is Friday, June 20th, 2025. Unfortunately, that’s all the information I get. Other events planned on the other days of the week are not hinted at or shown in the week day tab view, so all the useful information I get can only be events scheduled on Friday, June 20th, 2025.

Some very important questions that I may have as a user are left unanswered:

• What the heck should I do today after work or when I have free time?
• This is a Friday, so should I decide to have some fun with friends before the weekend?
• Should I deploy my app to production?
• If I decide to “go out” tonight, how will that impact the growth of my side business that I’ve been working on?
• If I’m physically active, what kind of workout should I do today? Should I take a rest day?
• What is the weather going to be on this day? Will it affect what I have in mind?
• etc.

Calendar doesn’t help me answer these questions in any way shape or form. If I were a daily user of the calendar app, I’m almost certain it would be possible for the app to use my past data to help me answer such questions.

Many say that they use a calendar to “plan” or “organize” their day, almost like they “command” events to happen at certain times of the day. This true to the extent that the visual representations of those events in the calendar app have been understood as the events that an individual will likely attend to in real life. However, the key point is “understanding”, that’s the end goal “planning” or “organzing”.

For instance, take this slice of a particular day. Here, I’m attending an all day event known as “CommunityKit”. Though, I also have some other events planned such as a morning workout, the act of driving from where I live to the location of all the WWDC events, and a meetup with a friend.

This view shows me visuals of the times and durations of each event throughout the day, and correlates them by showing a vertical overlapping list with the list markers being the hours of the day. When I add a new event to this day, I can visually see the time it occurs in relation to other events in my day. This in turn, allows me to understand when and where I might plan another event. The calendar view correlates an event with time, and where it is temporally located in relation to other events. Therefore, I am now equipped with more information to make a decision on where and when to schedule my next event during the day.

On it’s own, the sequence of events you attend to during a day is a heavily abstract systemic model that’s hard to visualize, which is why the concept of a calendar was invented. A calendar on its own is a tool to visualize such an abstract data model, allowing you to organize your day with it to better understand your day. By contrast, the calendar itself is not a control center for “planning”, though it may seem like it when describing it to others. Instead, the calendar collaborates with you by giving you the information necessary to come to an understanding of what how your day looks like.

In today’s digital medium, and with the available hardware, more correlations and questions can be answered about a user’s day than a traditional physical calendar. A physical calendar cannot read and understand past events, cannot understand the user’s goals, cannot aid in the process of organization, cannot read possible future world-events and tell the user to prepare, etc. No amount of “liquid glass” will draw more of those correlations.

Generally, the amount of discussions on how to best answer the user’s questions through design seems to be far lower than the discussions on whether or not liquid glass looks visually pleasing or is “accessible”. If a user cannot navigate or appreciate the visual design, then ultimately their questions will be left unanswered, but that is only an aspect of why we actually use software.

— 6/14/2025

PS. The liquid glass effects in this article were replicated from here. Thanks!

-- Minutes to Read

Commands are a relatively simple concept that we have an intuition of in society. If I command you to perform some action, it is therefore socially acceptable for you to carry out that action in the manner I commanded you to do it.

As a society we’ve used this technique in many large-scale technical and societal systems designs over the course of many centuries. Often, the results have been far less than ideal, and have caused stagnation or even degredation for those involved.

In fields like programming, the concept of a command handler may have a formal definition depending on the context within the field (eg. CQRS or implementing a formal interface named XXXCommandHandler). In some senses, such definitions may play into the larger abstract ideas of what a command handler means in the grand scheme of things, but inherently they are not the focus of this article.

Programming is certainly one of the many domain examples we’ll cover, as I imagine it largely would correlate with the audience. However, it’s apparent that we see the root systemic principle behind the notion of “commanding” something, and why it faces scaling issues if we are to understand how new systems should behave. This involves looking beyond just the programming domain, and requires us to look into other adjacent and non-adjacent domains such as UI/UX design, corporate structure, and forms of government. Either in shape or form, all of these domains carry major systems design issues around the notion of command handling.

We’ll start by defining what commands and command handlers are. Then, we’ll look at how such principles violate the laws of scaling, and how they are poorly used in existing domains. Afterwards, we’ll touch upon a new principle that has been used in many large-scale systems present today, and why it can combat many of the scaling issues that command handling faces. In doing so, I’ll cover a few ways to restructure command handling systems to follow this new principle. Lastly, we’ll touch upon the notion of when and where command handling should be used in conjunction with the newer principle.

This article will largely have a broad focus on many domains, as such deeper dives into specific domains may not be fully addressed.

Defining Commands and Command Handlers

We can start quite small when thinking about the notion of commands. In fact, the first line of code that programmers often write is something along the lines of.

console.log("Hello World")

In this case, our small system is commanding the operating system to print "Hello World" to standard output.

As one progresses in their programming journey, they may learn about something called a function, or possibly as something similar with a different name. It turns out that these function things are pretty useful for reusing code.

let number = 0

const increment = () => {
  number++
}

increment()
increment()
console.log(`The number is now ${number}!`)
        

However, once again we can see that these function things have doubled as commands. Now the system has a concept of an incrementing command. When the command is imposed on the number, it will be incremented with no objections.

The “no objections” part is key here, as it implies an order that must be enacted. Such an order is therefore a command, and the one who carries out such orders is a command handler. In this article, we’ll also refer to the actor that creates commands as a commander.

The requirements for your current project at work may be something that you must carry out at all costs. A rule of law that is imposed by a government is also something that must be adhered to at all costs. The order that a user placed using the Uber Eats app is also something that must be carried out at all costs. In all cases, these orders, laws, and requirements are defined as commands, those who carry them out are the command handlers, and those who create the commands are the commanders.

Scaling Issues

So, why don’t command handlers scale?

First, we should be careful to use the term “scale” in the general sense. That of a term that refers to increasing or enlarging the dimensions of a system.

For command handlers, we can generally think of those dimensions as the number of commands to handle, and the different variants of the commands to handle. Therefore, a command handler operating at scale generally has to deal with both a higher volume of many varied commands than a handler operating at less of a scale. For increasingly enlarging systems, this often means that an inconceivable volume of command combinations need to be handled at scale.

This higher volume of commands and command variants stems from more and different “commanders” invoking the command handler than before. Combinations of commands can be formed by the ordering in which different commanders send commands.

In programming, this could mean calling a set of 100 functions in different combinatorical orders. In a company, this could mean many different product teams or departments imposing requirements on a single product team. In government, this could mean imposing many different laws and regulations on its citizens. In all of these cases, the volume of commands and their combinations are incredibly hard to predict and regulate.

For such a dynamic to work properly, the commander has to trust that they are properly commanding the handler, and likewise the handler has to trust that they are being handed the right commands. If any single party breaks this bidirectional notion of trust, bad things often happen.

In programming, if a set of functions are called in the wrong order, bugs occur. In a company, if a product team receives unattainable, ambiguous, or conflicting requirements with no room for negotiation from different departments, confusion and stress occurs. In government, if the rules of law it imposes on its citizens interfere with their civil rights, it becomes authoritarian, and invigorates its citizens.

At increasingly larger scales, the volume and variations of commands becomes increasingly harder to understand. Therefore, could you really trust in those cases that both parties work together correctly?

The evidence has shown this to generally be a resounding “no” in many systems. Of course, parties with better chemistry may handle increasing scales more effectively, but no one can handle infinity. Yet, in practice we can often find many cases where this is violated.

Violations in Code

In the “real world”, we’ll often encounter plain data non-encapsulated structures, even in so-called object oriented languages. For instance, this is a very common style of “object-oriented” Java code is not only taught to beginners learning OOP, but also common in many Java applications. We’ll ignore tools like Lombok that automatically generate lots of this code in Java. In fact, I would wager Lombok’s existence is more of larger symptom problem of this style, as the problems of this code are heavily related to “setters”.

public class Item {
  private String name;
  private int quantity;

  public Item(String name, int quantity) {
    this.name = name;
    this.quantity = quantity;
  }

  public String getName() {
    return this.name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public int getQuantity() {
    return this.quantity;
  }

  public void setQuantity(int quantity) {
    this.quantity = quantity;
  }
}
        

The use of getters and setters in this case is often taught as a form of “encapsulation”.

However, this Item class is more like a C data structure, and not really an “encapsulated object”. In effect, you can consider this class as a dumb command handler since it sets whatever values are passed to its setters. In turn, it doesn’t know anything about those values or where they come from, therefore it must trust that the incoming values are valid and have good faith. Due to this, we easily end up with a limitless possible combinations of Items in our system, and thus we propagate the complexity of what constitutes a “valid” Item throughout our entire system.

For instance, a negative quantity doesn’t really make sense on an Item in many systems. With this so-called “encapsulated” Item object, the rest of the system has to trust that the quantity has not been set negative somehow in some galaxy far-far away.

If we’re lucky, there may exist some class called ItemValidator somewhere else in the system that ensures the quantity is not negative, but often this class does not exist leaving the code that leverages Items to perform this validation.

public class ItemValidator {
  public boolean validate(Item item) {
    return item.getQuantity() >= 0;
  }
}
        

Even with this class, the knowledge about how an Item works has been spread around to different components of the system instead of being “encapsulated” within the bounds of Item. Different components of the system now must trust that every Item has gone through the validator (and at the corect time) somehow. Every future change to the item quantity will also need to be accompanied by a call to the ItemValidator in order to ensure its validity. Yet we’ve only added more complexity to our system because now we must consider both an Item and ItemValidator to be in tandem with one another.

Unfortunately, we often aren’t so lucky in the real world, and the intimate knowledge about an Item is often spread out through multiple unrelated components of the system. If we need to update the intimate knowledge of an item, we must now ensure that we make trustworthy updates to all of those unrelated components in the system. This is especially error-prone in the significant number of systems that have little or no form of automated/rapidly available testing pipelines.

Even worse is when the intimate knowledge of Item has to be distributed to multiple nodes of a distributed system, as is the case with even simple web-applications due to the “frontend” and “backend” distribution. Unfortunately, Java does not have a notion of sending “objects” across the internet, and therefore we have to trust each node of our distributed system to have the correct intimate knowledge of Item (ie. each node in the system has to separately redefine the Item type somehow with all of its validation rules).

To visualize this. Each node of this system needs to define an Item class somehow, and then also needs to replicate the validation logic for an item. However, this replication means that each node has to agree on what an Item is and how to validate it. If the semantics and notions of a valid Item were to change in the future, each node in this system would have to independently update its representation of the Item class in order for the system to be stable (ie. Each node would have to trust the nodes it interacts with handle the notion of an Item correctly).

Naturally, this is quite error prone, and can be especially tedious when many different kinds of people are involved in the maitenance of this system. Some of those “20 other company services” may be written in Java, and can therefore reuse the Item class if it is moved into a shared library. However, this would then tie much of the system to Java itself, and Java would eventually become the default choice whenever possible for new nodes in this system. If another language would be more suitable for a specific node in this system (eg. Java generally isn’t so great at making iOS applications), then we repeat the manual replication problem.

Violatons in Governments

As an ideally moral species, our scaling of society needs to handle and provide hospitality for ~8 billion human beings. We have failed at this so far, though it seems our methods may have improved since the invention of the modern state.

If we think about governments as the “commanders” and the populace as the “command handlers”, we can infer that any passed law/executive order/ruling is effectively a command on the populace. With an absolute monarchy the monarchs commands are above all else, and therefore the populace has to trust that the commands of 1 individual are in good faith. As history shows, this approach generally has not scaled well, and many revolutions were fought to get rid of it. These days developed nations have better systems of checks and balances in place that give the populace more power against bad commands.

Yet, many of the governments in today’s world still operate as “commanders”, and individuals still lust for power even in developed nations with checks and balances. The notion of what those checks and balances are must be interpreted and acted upon by those in power, whose interpretations may have negatively diverted from the original intent of those checks and balances. Such is often the case when a single political party holds a super-majority rule in each branch of government.

Violations in Business

Additionally, some may argue there exists a similar power dynamic in many companies. If we look at a typical corporate structure, there must be at least 1 person who can make decisions that impact the significance of the company, the CEO. At the lowest level of this structure are often the grunts who in the worst cases are pure command handlers that must only fulfill spelled-out orders from management with no exceptions. In software development, these people may be called “code monkeys”, as their only job is to write the code and not much of anything else. Often this causes employee burnout, and as a result the product is typically less innovative.

If a company wants be successful, it needs to find its customers, attend to the wants and needs of those customers, and operate in such a way that it gains resources to produce more output. Customer needs and wants depend on the domain itself, market factors, the demographics in said market, and the individual people’s contexts themselves. Operational needs includes RND costs, timelines, communications, decision making processes, revenue streams, etc. For each of these, appropriate domain expertise allows better decisions to be made quicker in each of these areas.

If product decisions are made without input from those who own the capabilities to create the product, then those who create must trust the limited expertise of management above them. Simultaneously, if the power is solely given to the creators, then management must trust the limited business expertise of the creators when making product decisions. Either is a recipe for disaster, as one group commands the other in some form.

The company itself is a system that lives within a larger economic system, and its role is ultimately to produce value in the said larger economic system. Therefore, a successful company system must be carefully designed with the factors at play in the larger economic system that can change with time and growth.

Smaller companies often succeed by being the best in a specific domain, and larger companies can succeed by playing in domains that are not accessible to smaller companies. In both cases, the appropriate systems designs are dependent on the ability of domain experts to innovate in their domains, and on the business to produce customer value in those domains.

With such a duality, those who control business, and those who control the domain expertise both need the power to say “no”.

Violations in User Interfaces

Modern UIs of this day are almost textbook definitions of command handlers. You open an app, you press a button, and therefore you expect the app to do what you want. If the app fails this task, you often become an angry user even if you commanded the app to do something malicious for yourself (eg. A morbidly obese person getting mad at a food delivery app when it fails to order their next unhealthy meal.). Due to the prevalence of “apps” in our society, this kind of command handling treatment has now been baked into our natural intuitions, and thus deviating from it poses a significant design challenge.

As designers, we like to talk in terms of “conversions”, “liquid glass rectangles”, and “ease of use”. The UI must “get out of the way” at all costs to ensure that users can command a product to their liking. Their desires are above all else, and we must ensure that a product is “simple and easy to use” to ensure their desires are met. If their desires are met, we often have a higher “conversion rate”, and thus the company achieves growth. Therefore, we’ll design our UI to be a kind of control panel that only presents the means of achieving those desires.

But do we dare question those desires?

Should we allow a morbidly obese person to order unhealthy meals from their bed using an app? Should we allow someone who’s addicted to social media (if they don’t use it for healthy reasons) to “doomscroll” for many hours per day? Should habit tracking apps allow one to track many habits at once, when they can’t even stick to one? etc.

Making an app look beautiful and simple/easy to use is only a fraction of the battle when it comes to tackling real-world issues. If an app is designed as a simple command center to perform an action, then we end up with scenarios like those in the questions above. A command center app must trust that the user’s intentions are in good faith in order to provide value, and often they are not.

An individual who uses social media to promote their brand fundamentally has different needs than someone who’s addicted to social media in an unhealthy way. While business metrics views may be provided for the influencer, the addicted user often gets no feedback on their negative usage from their app of choice. Even worse, a common issue that affects nearly all demographics on social media relates to certain content triggering poor physcological and physiological responses. Social media apps generally do not provide insights as to what kind of content causes mental health degredation on a per-user basis.

In more modern times, many applications involve the use of an LLM that enacts commands on behalf of the user. These commands, structured as natural language prompts, are passed to an LLM which then calls into a set of tools to automate a task or workflow (such as coding). The result is the ability to “create more things” in a shorter time frame, which on its own isn’t problematic. Rather, the LLM tends to take away the understanding of how something is created in the first place because the user trusted the LLM with their commands, and the LLM trusted that the user’s commands were in good faith by carrying them out with no objections. When it comes time to maintain or evolve initial creations, problems often arise due to this lack of understanding (eg. why many vibe coding attempts fail).

Another Way of Thinking

The first and total opposite mindset shift we can have is to trust absolutely nothing. As commanders, we would therefore have to stop sending any commands. As handlers, we would reject every command sent our way. Naturally, life forms could not exist this way, as everything would isolate itself from one another, and therefore die out.

Clearly, there has to be a base level of trust somewhere, and in general we command things because we want things to happen. However, we also are sometimes aware that our commands cannot or should not be fulfilled. In other words, if we want to scale this thinking, we really should be “requesting” things to happen, and not “commanding” them. This way, we unlock the ability to collaborate with the request handler.

Ideally, when we request something from the handler, the handler should have the ability to question why we sent the request in the first place. After all, it is a “request” and not a “command”. The handler may even choose not to respond if such a response isn’t necessary. Since we’re merely requesting, we should have an intuitive notion that our request may not be fulfilled in the way we expect, and therefore be prepared to deal with the consequences.

The Internet

In fact, this request-response model scales quite well, because it happens to be the model that the internet runs on. Not once in the ~60 year history of the internet has it ever been completely brought down, and the network itself has expanded to trillions of nodes. While parts have fallen down, and still fall on a regular basis, there exists enough redundancy to not bring the entire operation to a halt.

The model of the internet is quite simple. A client can send a request to a particular server for information, or to perform some operation. This request must take the form of a stream of bytes, and this allows the server to interpret the request however it likes. With protocols like TCP, we can even guarantee that this byte stream reaches the server, and reaches it in the same order we sent the bytes.

The server can then look at its internal state, and process the request as it sees fit. It may choose to respond favorably, or it may not respond favorably, or it may event not respond at all. If it does respond, the response must also be in the form of a byte stream, and this allows the client to interpret the response how it likes.

The client can then look at its internal state, and processes the response as it sees fit. It may choose to send further requests to the server, or it may choose to proceed without further communication.

Neither the client nor the server need to understand the full context of each others’ internal states in this communication, nor can they directly access each other’s internal states. To access the internal state of the server, the client can only request it in a way that the server understands, and even then the server may choose to present it however it likes.

Neither the client nor the server know the methodologies their opposites are using to process the messages sent between themselves. This is a notion known as encapsulation.

Improving the Item Example

We can explore the idea of requests by concretely fixing the item code example from earlier. While the mainstream ecosystems of tooling are not capable of fully fixing the “knowledge replication” issues we faced earlier, we can certainly improve the isolated usage of Item on a per-node basis. Fixing the replication problem requires a different medium of distributing applications altogether, which is best left for a future exploration.

It is a fundamental law of Item that does not allow the quantity to be negative, so therefore we should encapsulate that knowledge into the object. We can use Java’s Optional type to indicate that the quantity of an item is not valid. Also, for the sake of respecting the request-response model more literally, we’ll switch to an immutable design that returns new Item instances when updating the item.

public class Item {
  private String name;
  private int quantity;

  private Item(String name, int quantity) {
    this.name = name;
    this.quantity = quantity;
  }

  public static Optional of(String name, int quantity) {
    if (quantity < 0) return Optional.empty();
    return Optional.of(new Item(name, quantity));
  }

  public String name() {
    return this.name;
  }

  public Item withName(String name) {
    return Item.of(name, this.quantity).get();
  }

  public int quantity() {
    return this.quantity;
  }

  public Optional<Item> withQuantity(int quantity) {
    return Item.of(this.name, quantity);
  }
}
        

At the very least, we no longer can set the quantity to any value we desire. We can only “request” that the quantity be set, and by using Optional we’re forced to expect a potential “bad response”. The intimate knowledge of an Item is now “encapsulated” within the class itself, so we can get rid of ItemValidator. Given that invalid Items are now unrepresentable in our system, we’ve also massively reduced systemic complexity as the components dependent on an Item have no need to worry about validation.

Improving User-Interfaces

A dedicated piece on this topic can highlight far more detail here including how AI can most effectively be used in apps, but the essentials can be covered briefly.

User interfaces best provide value to their users when users form connections and learn new things as opposed to simply commanding them. We use apps to see what our friends are up to, figure out what our plans are for tomorrow, understand how many calories a day we’re burning, view political discourse, figure out how to best manage finances, learn what our passions are, and to learn how to create things. Therefore, it is essential that user-interfaces are designed around correlations and relationships in information.

For instance, social media apps can alerts users to avoid content that knowingly degredates their mental state rather than letting them doomscroll. Stress management apps can relate personal actions and incidents to long-term progress on reducing stress levels rather than focusing on singular moments in isolation. Weight loss apps can help users decide on a diet that’s enjoyable, and effective for their weight loss goals rather than serving as a simple calorie tracker. Before making a post, social media apps can inform the author of how it may perform with certain demographics rather than leaving it entirely up to the author. Habit tracking apps can help users find the right and most motivating habits to focus on, rather than leaving users to find that for themselves. Messaging apps can alert users when it’s not the best time to contact someone, instead of leaving users to determine that themselves.

There are infinitely many correlations available to choose from, and in an ideal world we wouldn’t be limited to the APIs Apple and Google provide in their operating systems for mobile apps. LLMs can also be helpful here, but we have to be careful enough to not treat them as mere “assistants” or “servants”. (ie. Treating them merely as command handlers that act as servants in accordance to the user prompts they receive. Often, the prompts themselves need to be questioned.)

Not a Silver Bullet

Imagine a world where there was no downside to everyone trusting each other to get things done, or rather a world in which command handlers scale. Such a world would be massively more efficient than the one we live in, because we wouldn’t need to waste time on debating if the “commands” were correct in the first place.

The problem with a request-response system is overhead. The interpretation, internal deliberation process, and fail-safes needed to scale the system introduce many inefficiencies that are not related to the core functions of the system. This is often why a small startup can move faster than a bigger company, or why pure procedural code written in C can have better runtime performance than code written in higher level “object-oriented” languages.

With that in mind, command handlers aren’t inherently bad, it’s merely that they have scaling troubles without the overhead of a request-response model.

As system designers, it is actually our job to deploy that overhead correctly. One tool for detecting such a deployment is to look at the coupling between components. Coupling in this case differs its definition depending on the domain. A small team of people who have a high-team chemistry have a high degree of coupling on each other. An object that depends on references to many other objects in programming is coupled with each of those other objects. Regardless of the domain, coupling can be seen as the connections between different systemic components.

If multiple components are highly coupled with only a few “outside connections”, then we can deploy the overhead to the few outside connections as to not add overhead to the high-degrees of coupling from the inside. This creates an isolated and effective component in a specific domain, but adds overhead to prevent other components in other isolated domains from dictating its functionality.

We may also try to reduce the coupling on the inside as well, but from experience that usually only works up to certain point as the reducing the coupling may involve the creation of more smaller components. The communication overhead of those smaller components can often more complex than a singular monolithic component when split incorrectly. A great example of this is a small team of a few brilliant people who lack team chemistry, as this creates a massive communication overhead for each individual in order for the team to function.

As long as the bidirectional notion of trust can be upheld, then command handling can function effectively. Managing the trust factor is therefore a crucial part of designing efficient systems that scale.

To End With a Question

Do you believe that following the commands of society will produce a better world?

-- Minutes to Read

Whether this is the root of all evil, or of something else entirely is entirely up to you to decide.

In a certain visual novel series, one may terribly try to describe the root as the sun, and this would get you certain looks from characters in said series for the description. Just a few centuries ago, if you suggested that the sun was the root of the solar system you would receive the reward of condemnation, and possibly an additional gift of having your middle finger preserved for eternity in your honor.

With these examples in mind, a logical human can only conclude that humans are inherently illogical. What has materialized as “progress” in the past few centuries first had to come from millenia of book burnings, and largely failing models of civilization. In it’s ~200,000 year history, only the most recent 400-500 of those years have been spent in a world of “modern science”.

One may ask why it took so long for the human race to adopt such a methodology of “progress”. A century before the Scientific Revolution began in the 1500s, the Printing Press came about and allowed for the widespread circulation of previously hand written material. Over the next few centuries, the literacy rate in Europe grew dramatically, and this would eventually lead to the invention and use of the modern state in the 1600s and 1700s. The US Constitution was drafted only ~350 years after the printing press, and at the time the previously established notion of a “monarchy” was now under heavy scrutiny for first time in thousands of years.

Only ~200 years after the ratification of the US constitution, far more mediums that enabled the widespread circulation of ideas had come into fruition. Namely, one of those being the internet, and built on top of it, the web. We’ve also now somewhat figured out how to “emulate” the output of human thought in a digital medium, though it seems that much more work is needed in this area.

In just 600 years, we’ve largely flipped the structure of society upside down, and dispelled many previously conceived notions of societal operation. This came about largely due to the ability to distribute ideas effectively across long distances, which in turn led to the “know-how” to create mediums that further made this process more efficient and effective.

Yet, this is a movement that is still in its infancy, as our world still has a strong notion of a minority of “developed” and a majority of “undeveloped” nations. Even in “developed” nations, citizens experience problems largely unique (eg. obsesity, mental health struggles, etc.) to the nature of the “developments” in their nation. Our time period is also likely the first in which we fear that human technology can “end the world”. Previously such “world-ending” events were largely religious.

When a large volume of ideas are circulated in increasingly short time spans, it is no doubt that many bad ideas will make their way through the mediums, and eventually be implemented in the world somehow. In fact, it’s quite common today to hear ideas circulated such as “ideas are cheap” or “ideas are a dime a dozen”. This is generally a kind of thinking that is oriented towards people building new products or services, as much of the burden of doing such a venture is on the execution and implementation details. Therefore, “coming up with good ideas” is often seen as a waste of time. Of course, such thinking was only enabled by systems that enabled universal human literacy in the first place.

Bad ideas are certainly not cheap when they are successfully implemented and widespread. In fact, they are quite expensive in both time, human life, and monetary value. Monarchies persisted for millenia, and many revolutions in different parts of the world had to be fought to dispell them. That only came after the few centuries it took to convince a part of the world that they were a bad idea in the first place. Of course, wars are quite monetarily expensive as well.

In business, the products that best solve their designated problems often don’t win, or are never brought into fruition because they have no potential at replacing the already established solutions. If smaller players cannot dethrone larger players, you get stagnation.

Social media apps format all content the same, and provide the same basic interaction tools (liking, upvoting, downvoting, commenting) for each unit of content. If a unit of content is best represented by another format, it cannot be shared on the social media platform. If the format’s medium that would best reflect the content is not widespread, then the content cannot be expressed in full. If the content cannot be expressed in full then many of its ideas are lost, and you get stagnation.

If you solely rely on the use of AI (or any technology that can automate creation) to complete tasks, your ability to complete such tasks is inherently tied to the ability of AI. If such a technology plateaus, then your ability to complete the task can no longer grow whilst you’re solely dependent on AI, and you get stagnation.

Thus far, we have quite literally failed at finding a scalable set of mediums that addresses the needs of 8 billion (and increasing) people on a single planet. This is in spite of the massive hardware and to an extent software advantages we have today compared to the last decade. If the species were to become multi-planetary, this is an even a bigger problem due to the need to understand the even greater number of personal contexts that entails. Stagnation is therefore fatal in such circumstances.

In the near-term, improving our usage of existing and emerging technologies can help address these challenges in the products we create on a daily basis.

As such, I figure it's best that I record my experiences and thoughts on developing apps that better enhance content-creation, and address many of the public mental and physical health challenges stemming from existing apps. In particular, a focus on "enhancement" of innate user ability (ie. enhancing their ability to understand themselves and navigate the world) is missing from many of today's products.

However, in the long-term something greater seems to be needed to address the scaling problems we are currently facing. Such requires going beyond current societal and industry ideas, and requires developing new and qualitatively different systemic foundations.

I don't know what the exact answer is at this current moment as to what those will look like. However, I believe it's essential that I document my findings and experiences to help put into context the eventual "understanding" of those ideas.