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-11
]]>Published on 2026-07-11
Tags: article, commentary, javascript, kotlin, llm, software-eng, software-eng-auto
OpenAI GPT-5.6 Announcement on 2026-07-09:
GPTβ5.6 can write and run lightweight programs that coordinate tools, process intermediate results, monitor progress, and choose the next action as work unfolds. This lets tool-heavy tasks advance with fewer tokens, fewer model round trips, and less guidance. Instead of requiring developers to script every step or passing every tool response back through the model, Programmatic Tool Calling in the Responses API can filter large amounts of intermediate data, retain only what matters, and adapt its workflow along the way.
I am getting some sweet validation from this feature they revealed. I built a similar system at work recently, and I think it fits coding agent capabilities nicely.
]]>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-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-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 π.
]]>Published on 2025-09-06
]]>Published on 2025-09-06
Tags: article, ocaml, security, software-eng
When using OpenSSH, you may see ASCII art from time to time, like:
+--[ED25519 256]--+
| |
| . |
| o |
| o o o . |
| .B S oo |
| =+^ =... |
| oo#o@.o. |
| E+.&.=o |
| ooo.X=. |
+----[SHA256]-----+
This is output[1] of the randomart SSH Key visualization algorithm, intended to leverage the user's visual pattern matching to quickly recognize (or not) a remote host key. It's known as the Drunken Bishop's algorithm, contributed to the OpenSSH codebase by Alexander von Gernler in 2008.
]]>Alexander von Gernler on 2008-06-11:
Introduc[ing] SSH Fingerprint ASCII Visualization, a technique inspired by the graphical hash visualization schemes known as "random art", and by Dan Kaminsky's musings on the subject during a BlackOp talk at the 23C3 in Berlin.
Scientific publication (original paper): "Hash Visualization: a New Technique to improve Real-World Security", Perrig A. and Song D., 1999, International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
Published on 2025-08-10
]]>Published on 2025-08-10
Tags: article, java, javascript, ocaml, static-site
I like the idea of having search for my blog, to help readers find anything related to a specific topic, or something they'd read in the past. How do I make something as dynamic as search, but statically generated?
Published on 2025-08-06
]]>Published on 2025-08-06
Tags: article, css, html, javascript, static-site
Unfortunately I spoke too soon when I wrote the Building this Site post. I had a plan in place to use hilite, along with TextMate grammars and themes pulled from Shiki (which in turn gets its grammars and themes from TextMate/VSCode), but it fell through.
The plan was to grab lightmode and darkmode themes from Shiki's trove of themes, stripping out any extraneous styles (a lot of text-editor-specific colors are given) to arrive at two sets of colors for pre-determined class names. Shiki works similarly to hilite: during processing it tags portions of the source code with CSS tags derived from the grammars. All of the TextMate grammars employed by Shiki use a consistent naming scheme, ensuring themes always line up with the grammars, resulting in colored text. With a little adjustment of the theme CSS tags to account for any differences between Hilite's and Shiki's tagging, I'd have ahead-of-time syntax highlighting, with as many supported languages as VSCode.