Published on 2026-08-16
]]>Published on 2026-08-16
Tags: article, commentary, llm, ocaml, software-eng, software-eng-auto
termaid, my OCaml port of mermaid.rs, is available on opam! π With that release, the work shifts to maintenance.
Given that this is a machine-driven port of an existing piece of code, I wanted to set up some infrastructure so that I'd catch any upstream bug fixes or feature enhancements. So I added an upstream-check.yml GitHub Actions workflow to execute check_upstream.sh and file an issue when it spots a change. The script uses the commit and blob references in oracle/UPSTREAM to determine changes against upstream. When the check fires, I'll ask an agent to update the oracle to the new upstream HEAD, use the oracle to generate test cases relevant to the changes, and adjust the OCaml code to make the tests pass.
Published on 2026-07-21
]]>Published on 2026-07-21
Tags: article, llm, ocaml, rust, software-eng, software-eng-auto
I saw this post from Simon Willison about running mermaid.rs β a utility from Grok Build, xAI's newly open-sourced coding agent harness, as WebAssembly in the browser. The output looks really nice, the Rust code is very self-contained, and I thought it would be interesting to use an agent to convert it to OCaml. The outcome is termaid, a minimal-dependency OCaml library for rendering Mermaid diagrams.
The package contains a minimal binary that renders a diagram from stdin, alongside the library itself, for use in other programs. Supported diagram types: flowchart/graph, stateDiagram, classDiagram, erDiagram, and sequenceDiagram.
$ termaid <<'EOF'
sequenceDiagram
A->>B: ping
B-->>A: pong
EOF
βββββ βββββ
β A β β B β
βββ¬ββ βββ¬ββ
β β
β ping β
βββββββΆβ
β β
β pong β
ββββββββ€
β β
βββ΄ββ βββ΄ββ
β A β β B β
βββββ βββββ
Published on 2026-07-09
]]>Published on 2026-07-09
Tags: article, documentation, macos, ocaml, software-eng
The OCaml.org opam documentation process does not trigger for macOS-only packages, leaving ones like osx-keychain labeled as "β οΈ No Docs".
I couldn't find a mention of this in the official documentation. In 2022, OCaml.org started serving automatically generated documentation for applicable opam packages, making use of a new ocaml-docs-ci documentation pipeline. Earlier this year, OCaml.org upgraded to odoc 3, accompanied by updates to ocaml-docs-ci for odoc 3 compatibility.
ocaml-docs-ci explicitly targets Linux platforms only. Because osx-keychain declares available: [ os = "macos" ], opam treats it as unavailable on ocaml-docs-ci's Linux workers, filtering it out of the set of packages docs-ci considers buildable before even attempting a build.
Published on 2026-07-04
]]>Published on 2026-07-04
Tags: article, macos, ocaml, security, software-eng, static-site
The osx-keychain library I built to natively pull credentials from the macOS keychain was accepted into Opam and is now publicly available as a dependency, a first for me π₯³. Here is some context on why I made it:
There are two modes in which I interact with AWS for the alexleighton.com static site: during site upload, and during image upload.
I used to rely on GitHub Actions to build and deploy all commits on the main branch, but it ended up being the worst of all worlds. Reinstalling opam, dune, the OCaml compiler, and all dependencies often took over 10 minutes, regardless of the Actions-caching I tried to apply. My static site is a private repository, so GitHub eventually started nagging about reaching the 1000 monthly build hours threshold for private repos. As a result I turned off the automation and have been building/uploading my site straight off my laptop using a bash script that does what the Action did.
Published on 2026-07-01
]]>Published on 2026-07-01
Tags: changelog, ocaml, static-site
Image variants are now served from a CDN at img.alexleighton.com instead of being bundled into the site and served by Amplify.
It seems I never came back to detail the custom image system underlying the images on this static site, so let's begin with the before, to motivate the after. The image system comprises a private S3 bucket, local filesystem cache, image "database", and an image system library.
The image system library is written in OCaml and integrated into the static site generator, to allow image reference resolution. A separate executable fronts the image system, to allow uploading and syncing of images during post authoring. Image upload through the system generates a number of variants of different sizes and formats (jpeg as the lowest common denominator, webp for most browsers, avif for modern browsers), assigns a TypeId to each image, uploads the images to the source-of-truth private S3 bucket, adds them to the filesystem cache, and adds corresponding rows to the CSV image database. The site generator reads the image database to dereference image TypeIds into source URLs, copies every referenced image into the output directory, and includes those images in the release artifact.
Published on 2026-06-15
]]>Published on 2026-06-15
Tags: commentary, llm, ocaml, rust, software-eng, software-eng-auto
Michael Bacarella has rewritten the OCaml runtime, using a coding agent to translate the existing C code to Rust line by line.
Michael Bacarella on 2026-06-09:
The headline results are "eh, just about parity, kinda"
Runtime Bytecode (cycles vs C) Native (cycles vs C) C (trunk) 1.00x: (baseline) 1.00x (baseline) Rust (stable) 1.44x, slower than C ~1.05x (range: 0.87-1.13) Rust (nightly) (ETCs) 0.91x, faster than C same as Rust stable
Michael guided a single Claude Opus 4.7 agent through a straightforward translation plan, over the course of seven days. I appreciate this result in automatic software engineering, applied to my favorite programming language. It is one more piece of evidence for the new future of software engineering we find ourselves in: a correct result on a large, non-trivial program, with minimal engineering guidance. Of note: once again, comprehensive test suites are worth their weight in gold when translating large programs.
]]>Published on 2026-03-11
]]>Published on 2026-03-11
Tags: commentary, llm, ocaml, software-eng
Drop a coding agent into any existing codebase that uses libraries and tools that are too private or too new to feature in the training data and my experience is that it works just fineβthe agent will consult enough of the existing examples to understand patterns, then iterate and test its own output to fill in the gaps.
This is my experience as well. Two years ago (gpt-4o, sonnet-3.5), there was a noticeable difference in the "smoothness" of the OCaml code generated by agents, when compared to generated Python code. The Python code was simpler, more clever, more easily involved various libraries, while the OCaml code had complicated compound expressions, unfortunate nesting (all helper functions defined inside the current function via let-binding instead of deduplicating into the file or across files), and sometimes simply failed to be written in complex situations involving Functors or circular module definitions or using popular libraries (without handing the agent interface files).
]]>Published on 2026-03-01
]]>Published on 2026-03-01
Tags: article, llm, ocaml, python, software-eng, software-eng-auto
On today's episode: a lot of code. The previous work prepared the project codebase to guide agents in generating good quality code, which is what we did.
After the Kb_service module was broken apart, the coding agent easily generated full verticals for update, resolve, and archive commands. The process I'm following:
docs/product-requirements.md.prompts/activities/implementation-plan.md for building the functionality.prompts/activities/code-review.md), and apply changes for all issues.Related commit: 0eb5584 β feat: add update, resolve, and archive commands
Published on 2026-02-26
]]>Published on 2026-02-26
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's log consists mostly of code generation. We've laid enough foundation that new functionality is easily produced.
The functionality for bs list is well defined after the work for the previous dev log. I think the experiment of directing the agents from the requirements document rather than my own intuition of what to tackle was successful, though perhaps only at the scale of a project like Knowledge Bases. The coding agent was able to select a reasonable chunk of functionality to peel off and turn into an implementation plan, with a different agent generating the implementation.
Published on 2026-02-24
]]>Published on 2026-02-24
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's changes follow on from the previous post's "next steps": nesting and ideation.
I worked with the agent to find code with deep nesting, decide how to flatten it, and generalize the approach into suggestions for a nesting principle. We then applied that principle across the codebase, and I think we were successful as the diff in the refactor commit is noticeably flatter.
]]>4. Nesting Depth
Keep expressions nested at most two or three levels deep. Deeply nested code is hard to follow because the reader must hold every enclosing context in their head at once. When nesting grows, treat it as a signal that the code should be restructured.
Approaches for reducing nesting:
- Use monadic result operators (
let*,let+). ...- Extract resource-management wrappers. ...
- Consolidate error mapping into named functions. ...
- Factor repeated control-flow shapes into helpers. ...
Published on 2026-02-20
]]>Published on 2026-02-20
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's changes build on the previous commit's unpacking of Todo, making a repository for Todos, and hooking it up to the command line to provide bs add todo ....
The implementation plan forgot to add a task for integration tests, which resulted in a bin principle saying changes to bin, where we're only keeping command-line parsing and top-level orchestration, should always be accompanied by an integration test. I also had the agent put together an architecture document guiding the structure of integration tests and their purpose.
In the hopes of keeping file sizes down, I added a line length principle to bin and lib. I'm not sure about these principles, because I think this can be automated as a lint. I will keep these in mind and improve the linting situation when I get another structural/syntactic principle that can be automated.
Published on 2026-02-19
]]>Published on 2026-02-19
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's change to Knowledge Bases is addressing my unhappiness at the beginning of the month: "Data modeling". I've returned to the work of unpacking Note into Todo, to make it easier to control the TypeID prefix, and prepare for making a Todo repository.
A handy thing about coding agents: they can make such a wide-ranging change with minimal effort (see the number of changed files in the commit). Additionally, the coding principles guidance doc paid for itself β agent code review noted the duplicated validation logic for title and content now in both Note and Todo and recommended deduplication. I redirected it to encapsulate the validation into new types, a favorite software engineering technique of mine (see "Aside: Correct Construction"), as well as adjusted the guidance.
Published on 2026-02-18
]]>Published on 2026-02-18
Tags: article, git, llm, ocaml, software-eng, software-eng-auto
I've decided to use this project as a testbed for automatic development, to explore the kinds of techniques described in recent results [1] [2], and to speed up development. I'll be making the vast majority of changes to the codebase via coding agents, exploring what controls are needed to stay hands-off yet maintain code quality.
I've played around with longer AGENTS.md and not seen much value. Agents would ignore pieces, and after a while it felt like simply a waste of context space. I'm keeping AGENTS.md short this time around, "linking" to where more information can be retrieved, with the hope that brevity keeps the content important.
Published on 2026-02-03
]]>Published on 2026-02-03
Tags: article, database, git, ocaml, software-eng
Today's update is brought to you by my lack of motivation π. I decided to work on building out a storage layer for Knowledge Bases objects, and then got burned by lack of interest.
Restating our storage requirements: we need notes, todos, etc to be persisted to disk in a way where git's diff will capably show edits, additions, and deletions, and which allows for easily querying these objects by identifier or by their relation to each other (we want to support parent-child, related-to, etc). To meet those requirements I intend to persist data in two ways. First, in an appropriately-sorted JSON or YAML file, to solve for the git-diff requirement. Second, in a SQLite database to make it easy to add/edit/delete/query. The program will mirror the SQLite database onto the JSON file unless it's determined to be out of date (i.e. when the git branch is changed), in which case we'll rebuild the database from the JSON file. For now I'm starting with the SQLite db, as that can be useful for purely local todo storage, and we'll bolt-on the ability to synchronize them over git later.
]]>Published on 2026-01-01
]]>Published on 2026-01-01
Tags: article, git, meta, ocaml, static-site
For 2024's New Year's resolution I decided I'd finally build and publish a personal website. That I'd write up my thoughts on the articles I was reading and post them instead of dumping them on friends π. In review, I'm happy to say I succeeded.
I wrote and published 164 blog posts over the past year, not counting this post. September was my most prolific month. I initialized the OCaml project that became the static site generator in late January, writing a test post at the beginning of February to work out frontmatter parsing, markdown generation, and my custom templating language. The first "real" post came at the end of June, a few days after I bought the domain name.
]]>Published on 2025-12-02
]]>Published on 2025-12-02
Tags: changelog, ocaml, static-site
I've created individual image pages. Now all images will link to their own image page, which makes it easier to see the alt text and variant images. For example, this page for the picture of my dog on Rialto Beach.
Implementing this was pretty straightforward. My static site generator makes a distinction between "normal" pages, ones where the Page structure is constructible solely from the contents of a file (HTML or Markdown body with all the necessary metadata in a YAML frontmatter), and "synthetic" pages, where the Page structure is constructed in OCaml code inside the generator. These image pages are synthetic: the generator constructs one for each image original used on the site, generated alongside other synthetic pages like the tag pages or blog post archive pages.
Published on 2025-11-30
]]>Published on 2025-11-30
Tags: article, git, ocaml, software-eng
TypeID is a micro-standard combining a number of well-thought-out decisions.
TypeIDs are a modern, type-safe extension of UUIDv7. Inspired by a similar use of prefixes in Stripe's APIs.
TypeIDs are canonically encoded as lowercase strings consisting of three parts:
- A type prefix (at most 63 characters in all lowercase snake_case ASCII
[a-z_]).- An underscore '_' separator
- A 128-bit UUIDv7 encoded as a 26-character string using a modified base32 encoding.
user_2x4y6z8a0b1c2d3e4f5g6h7j8k
ββββ ββββββββββββββββββββββββββ
type uuid suffix (base32)
Most identifiers, barring a specialized context, should include a "type" for the identifier. Interconnected computer systems are always passing around identifiers β for someone holding an identifier in their database it is really valuable to know who that identifier belongs to as well as what the identifier is for. For example in a financial institution handling investments, md_quote_2x4y6z8a0b1c2d3e4f5g6h7j8k can tell the receiver that they're holding a reference to a stock price quote, owned by the market data (md) system. Identifier types give engineers metadata, which can be especially useful when there's a bug in the system β no need to stress whether the integer identifier you're currently holding came from the user table or news table.
Published on 2025-11-01
]]>Published on 2025-11-01
Tags: article, ocaml
Short update today β the definitions of note and todo types and their basic operations.
My intention is to represent arbitrary content as a note, and represent things to be done with todo. Notes are just an identifier, a title, and some content, while Todos also have a status and eventually relationships. I've left relationships between notes and todos for later. I'm not sure if I want them represented separately or as part of the structures.
(** Note type and operations.
A note bundles an [Identifier.t] with a title and content.
*)
(** Abstract type of notes. *)
type t
(** [pp fmt t] prints the note [t] using the formatter [fmt]. *)
val pp : Format.formatter -> t -> unit
(** [show t] returns the same string that {!pp} would print. *)
val show : t -> string
(** [make identifier title content] constructs a note after validating inputs.
- [title] must be non-empty and at most 100 characters.
- [content] must be non-empty and at most 10000 characters.
@raise Invalid_argument if validation fails. *)
val make : Identifier.t -> string -> string -> t
(** [id t] returns the note identifier. *)
val id : t -> Identifier.t
(** [title t] returns the title of the note. *)
val title : t -> string
(** [content t] returns the content of the note. *)
val content : t -> string
Published on 2025-10-25
]]>Published on 2025-10-25
Tags: article, llm, ocaml
My inclination, after getting the hello world project set up in place, is to start defining the major data representations of the domain we're working in. Since I'm documenting the process, and I want to discuss decisions, I'm going to start out pretty slowly β today's update is basically just a type for representing identifiers for "notes" (whatever it is we decide to call the basic content building block).
The plan here is to expose an opaque type t for our identifier values (Identifier.t), and be explicit and deliberate about what data is exposed to the rest of the program. I liked how Beads stuck with an identifier format that's human readable, and likely prevalent in LLM training data, so we'll use the same format for our identifier: [a-z]{1,5}-[0-9]+ (e.g. kbase-12345). Decomposing that identifier gets us a namespace and raw_id.
Published on 2025-10-22
]]>Published on 2025-10-22
Tags: article, git, llm, ocaml
A couple days ago, Steve Yegge wrote about a coding agent tool he's been developing called Beads.
Beads is a lightweight memory system for coding agents, using a graph-based issue tracker. Four kinds of dependencies work to chain your issues together like beads, making them easy for agents to follow for long distances, and reliably perform complex task streams in the right order.
I haven't had an opportunity to see if it works well or not, but the feature set seems straightforward to implement and I've been looking for a project to work on which will involve OCaml and publishing to opam. I'll be documenting the development process here π.
]]>