Old tool</th>	uv equivalent</th></tr></thead>
`pip install</code></td>`	`uv pip install</code></td></tr>`
`pip-compile</code></td>`	`uv pip compile</code></td></tr>`
`virtualenv</code> / venv</code></td>`	`uv venv</code></td></tr>`
`pyenv</code></td>`	`uv python install</code></td></tr>`
`pipx run</code></td>`	`uvx</code> / uv tool run</code></td></tr>`
`poetry</code> / rye</code></td>`	uv init</code> + uv add</code></td></tr> </tbody></table> It has 84k+ stars, is used in production at scale, and the underlying pubgrub-rs</code></a> crate it depends on is the designated basis for Cargo's next dependency solver</a>. The same algorithm and largely the same Rust crate will eventually power both uv</code> and cargo</code> resolutions.</p> 2. The repository layout</h2> Clone the repo and you'll see:</p> uv/ </span>├── crates/ # All Rust source code </span>├── docs/ # MkDocs documentation </span>├── python/ # Small Python shim package (the uv PyPI wheel) </span>├── scripts/ # Benchmarking, release tooling </span>├── test/ # Test fixtures, requirement files for benchmarks </span>├── Cargo.toml # Rust workspace root </span>└── pyproject.toml # uv manages itself with uv </span></code></pre> The real action is in crates/</code>. There are 67 crate directories in v0.11.8. Rust does not allow circular dependencies between crates, so the uv team structured the code as a directed acyclic graph of focused crates. Each does one thing:</p> crates/ </span>├── uv/ # CLI binary: entry point and argument parsing (clap) </span>├── uv-resolver/ # Dependency resolution engine (PubGrub) </span>├── uv-installer/ # Installing packages into environments </span>├── uv-client/ # Async HTTP client for PyPI and registries </span>├── uv-workspace/ # pyproject.toml parsing and workspace discovery </span>├── uv-python/ # Python version management </span>├── uv-cache/ # Global content-addressed cache </span>├── uv-distribution/ # Wheel and sdist handling, metadata fetching </span>├── uv-build/ # uv's own build backend (replaces setuptools/hatchling) </span>├── uv-git/ # Git dependency support (based on Cargo's implementation) </span>├── uv-platform-tags/ # Wheel compatibility tag matching </span>├── uv-pep440/ # Python version specifier parsing (PEP 440) </span>├── uv-pep508/ # Dependency specifier parsing (PEP 508) </span>├── uv-types/ # Shared type definitions used across crates </span>└── ... (many more) </span></code></pre> You can generate a visual dependency graph between crates:</p> cargo</span> depgraph</span> --dedup-transitive-deps --workspace-only </span>\| </span>dot -Tpng </span>> graph.png </span></code></pre> The shape of the graph is roughly: uv</code> (the binary) sits at the top and depends on everything. uv-types</code> sits near the bottom and depends on almost nothing. Code only flows downward; cycles are a hard compile error.</p> 3. What happens when you run uv init</code></h2> Let's trace uv init my-project</code> step by step through the codebase.</p> Step 1: Argument parsing (uv</code> crate)</h3> The uv</code> crate is the binary entry point. It uses clap</a> for argument parsing. When you run uv init my-project</code>, clap matches the init</code> subcommand and extracts the project name and any flags (--lib</code>, --app</code>, --package</code>, --bare</code>, --build-backend</code>, etc.).</p> Step 2: Workspace discovery (uv-workspace</code>)</h3> Before creating anything, uv checks whether you're already inside an existing workspace. It walks up</strong> the directory tree looking for a pyproject.toml</code> with a [tool.uv.workspace]</code> section. If you're inside one, the new project is registered as a workspace member automatically. If not, it creates a standalone project.</p> Step 3: Scaffold project files</h3> For uv init my-project</code>, uv writes these files to disk:</p> my-project/ </span>├── .python-version # e.g., "3.12", pins the Python version </span>├── README.md </span>├── main.py # boilerplate main() function </span>└── pyproject.toml </span></code></pre> The generated pyproject.toml</code>:</p> [project] </span>name </span>= "</span>my-project</span>" </span>version </span>= "</span>0.1.0</span>" </span>description </span>= "</span>Add your description here</span>" </span>readme </span>= "</span>README.md</span>" </span>requires-python </span>= "</span>>=3.12</span>" </span>dependencies </span>= [] </span></code></pre> Notice there is no [build-system]</code></strong> section. Without it, the project is not installable as a package</em>: it won't be installed into the virtual environment itself. This is the correct default for applications (web servers, scripts, CLIs); it avoids an unnecessary install step and the complexity of choosing a build backend upfront.</p> If you pass --lib</code> or --package</code>, uv adds a src/</code> layout and a [build-system]</code> pointing to uv_build</code>, uv's own Rust-native build backend:</p> [build-system] </span>requires </span>= ["</span>uv_build>=0.11.8,<0.12</span>"] </span>build-backend </span>= "</span>uv_build</span>" </span></code></pre> Step 4: Git initialization</h3> uv runs git init</code> and writes a .gitignore</code> that excludes .venv/</code> and __pycache__/</code>. Skip this with --no-vcs</code>.</p> No virtual environment is created yet.</strong> uv is lazy: it creates .venv</code> only when you first run something or add a package. This avoids disk writes for projects you might never use.</p> 4. What happens when you run uv add requests</code></h2> This is the core operation. uv add</code> installs a package and records it in pyproject.toml</code> and uv.lock</code>. Here is the full pipeline:</p> $ uv add requests </span>Using CPython 3.12.10 </span>Creating virtual environment at: .venv </span>Resolved 6 packages in 456ms </span>Prepared 5 packages in 451ms </span>Installed 5 packages in 4ms </span> + certifi==2026.2.25 </span> + charset-normalizer==3.4.7 </span> + idna==3.11 </span> + requests==2.33.1 </span> + urllib3==2.6.3 </span></code></pre> Two things worth noticing about that output. "Resolved 6 packages" includes the project itself as a node in the dependency graph (your project + 5 transitive deps), but only 5 packages are installed</em>: the project itself isn't installable here because there's no [build-system]</code>. And "Prepared" is uv's word for "downloaded and unpacked into the cache, ready to be linked into the venv": the actual install step is just creating links, which is why it takes 4ms.</p> Stage 1: Read the project state (uv-workspace</code>)</h3> uv-workspace</code> reads pyproject.toml</code> and constructs an in-memory Manifest</code>: the project name, existing dependencies, Python version constraint, workspace members, and overrides.</p> Stage 2: Update pyproject.toml</code> (pyproject_mut</code>)</h3> uv adds requests</code> to the dependencies</code> list in pyproject.toml</code>. At this point it doesn't know the version yet, so it records it as a bare requirement. After resolution (Stage 3), it rewrites the specifier with the resolved version. The exact form depends on the --bounds</code> flag; the default (AddBoundsKind::Lower</code> in pyproject_mut.rs</code></a>) is a single lower bound:</p> dependencies </span>= [ </span> "</span>requests>=2.33.1</span>", </span>] </span></code></pre> This edit goes through uv-workspace</code>'s pyproject_mut</code> module, which does surgical TOML editing</strong>: it patches exactly the field it needs to change without reformatting anything else in the file. That matters because pyproject.toml</code> often contains hand-formatted sections, comments, and deliberate ordering that a naive serialize/reserialize pass would obliterate.</p> Stage 3: Resolution (uv-resolver</code> + PubGrub)</h3> The resolver answers: "Which exact version of every package satisfies all constraints?"</em></p> This is the most complex stage. We'll cover it in depth in sections 5 and 6. The output is a complete (package, version)</code> assignment for every package in the dependency tree.</p> Stage 4: Write uv.lock</code></h3> The resolved set is serialized to uv.lock</code>. This is a TOML file that records every package: its exact version, source URL, content hash, and its own dependencies. A real excerpt:</p> version </span>= </span>1 </span>requires-python </span>= "</span>>=3.12</span>" </span> </span>[[package]] </span>name </span>= "</span>requests</span>" </span>version </span>= "</span>2.33.1</span>" </span>source </span>= { </span>registry </span>= "</span>https://pypi.org/simple</span>" } </span>dependencies </span>= [ </span> { </span>name </span>= "</span>certifi</span>" }, </span> { </span>name </span>= "</span>charset-normalizer</span>" }, </span> { </span>name </span>= "</span>idna</span>" }, </span> { </span>name </span>= "</span>urllib3</span>" }, </span>] </span>sdist </span>= { </span>url </span>= "</span>https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz</span>", </span>hash </span>= "</span>sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517</span>", </span>size </span>= </span>134120 </span>} </span>wheels </span>= [ </span> { </span>url </span>= "</span>https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl</span>", </span>hash </span>= "</span>sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a</span>" }, </span>] </span> </span>[[package]] </span>name </span>= "</span>urllib3</span>" </span>version </span>= "</span>2.6.3</span>" </span>source </span>= { </span>registry </span>= "</span>https://pypi.org/simple</span>" } </span>dependencies </span>= [] </span>sdist </span>= { </span>url </span>= "</span>https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz</span>", </span>hash </span>= "</span>sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed</span>", </span>size </span>= </span>435556 </span>} </span>wheels </span>= [ </span> { </span>url </span>= "</span>https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl</span>", </span>hash </span>= "</span>sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4</span>" }, </span>] </span></code></pre> The lockfile is universal</strong>: one uv.lock</code> works on macOS, Linux, and Windows. It records all possible packages for all platforms using environment markers. When you install from the lockfile on a real machine, uv selects only the packages appropriate for that platform. This is a real improvement over pip freeze</code> or requirements.txt</code>, which are inherently platform-specific snapshots.</p> The hashes serve two purposes: integrity verification when downloading, and cache lookup keying.</p> Note:</strong> uv.lock</code> is an internal format that may change between versions. If you need to read it programmatically, the experimental uv workspace metadata --preview-features workspace-metadata</code> command outputs a stable JSON representation of the same dependency graph (it's still preview as of v0.11.8, so don't rely on its schema being final).</p> </blockquote> Stage 5: Download packages (uv-client</code> + Tokio)</h3> uv-client</code> is uv's async HTTP client, built on reqwest</a> and Tokio</a>. For every package not already in the global cache, uv fires off concurrent downloads</strong>:</p> # pip: sequential </span>fetch requests → wait → fetch urllib3 → wait → fetch certifi → wait → ... </span>total ≈ N × round_trip_time </span> </span># uv: concurrent </span>fetch requests ─┐ </span>fetch urllib3 ├── all in parallel </span>fetch certifi ─┘ </span>total ≈ 1 × round_trip_time (roughly) </span></code></pre> This is the largest contributor to uv's cold-cache speed. Network I/O latency is the bottleneck, and parallelism makes it roughly constant regardless of the number of packages.</p> Packages are stored in a global, content-addressed cache</strong> managed by uv-cache</code>. The cache key is the SHA-256 hash of the package content. This means:</p> Any package version you have ever installed is reused across all your projects, forever.</li> The cache is verified by hash on every use; silent corruption is caught immediately.</li> The cache is shared across uv pip install</code>, uv add</code>, and uvx</code> tool installs.</li> </ul> Stage 6: Install packages (uv-installer</code>)</h3> "Install" normally implies copying files. uv mostly doesn't copy anything.</p> uv-installer</code> uses hard links</strong> wherever the filesystem supports them (most Linux and macOS filesystems do). A hard link means two directory entries point to the same physical data blocks on disk. Creating one is essentially free: a single filesystem metadata operation.</p> When uv "installs" a package into .venv/lib/python3.12/site-packages/</code>, it's creating hard links from the global cache into the virtual environment. No bytes are duplicated. This is why you see timings like Installed 43 packages in 208ms</code>: that 208ms is the overhead of creating thousands of directory entries, not copying gigabytes.</p> On filesystems that don't support cross-device hard links (e.g., home directory and temp on different mounts, or network filesystems), uv falls back to copy-on-write reflinks, then regular copies. But the common case is hard links.</p> 5. Inside the resolver: the two-thread architecture</h2> The resolver is the most architecturally interesting part of uv, and the source code reveals a specific design decision that's worth understanding.</p> The concurrency problem</h3> The PubGrub algorithm is inherently sequential and synchronous</strong>: it makes one decision at a time, and each decision depends on all previous decisions. You cannot trivially parallelize it.</p> But metadata fetching (querying PyPI for "which versions of flask</code> exist?" or "what does flask==3.1.0</code> depend on?") is highly parallelizable I/O.</p> The naive approach is to serialize everything: decide package, fetch metadata, decide next package, fetch metadata. This is what pip does. uv does something cleverer.</p> Two threads communicating via channels</h3> The resolve()</code> function in crates/uv-resolver/src/resolver/mod.rs</code></a> is short enough to quote verbatim:</p> pub</span> async </span>fn </span>resolve</span>(</span>self</span>) -> Result<ResolverOutput, ResolveError> { </span> </span>let</span> state = Arc::new(</span>self</span>.state); </span> </span>let</span> provider = Arc::new(</span>self</span>.provider); </span> </span> </span>// A channel to fetch package metadata (e.g., given `flask`, fetch all versions) and version </span> </span>// metadata (e.g., given `flask==1.0.0`, fetch the metadata for that version). </span> </span>// Channel size is set large to accommodate batch prefetching. </span> </span>let </span>(request_sink, request_stream) = mpsc::channel(</span>300</span>); </span> </span> </span>// Run the fetcher. </span> </span>let</span> requests_fut = state.</span>clone</span>().</span>fetch</span>(provider.</span>clone</span>(), request_stream).</span>fuse</span>(); </span> </span> </span>// Spawn the PubGrub solver on a dedicated thread. </span> </span>let</span> solver = state.</span>clone</span>(); </span> </span>let </span>(tx, rx) = oneshot::channel(); </span> thread::Builder::new() </span> .</span>name</span>("</span>uv-resolver</span>".</span>into</span>()) </span> .</span>spawn</span>(</span>move </span>\|\| { </span> </span>let</span> result = solver.</span>solve</span>(&request_sink); </span> </span> </span>// This may fail if the main thread returned early due to an error. </span> </span>let </span>_ = tx.</span>send</span>(result); </span> }) </span> .</span>unwrap</span>(); </span> </span> </span>let</span> resolve_fut = async </span>move </span>{ rx.await.</span>map_err</span>(\|_\| ResolveError::ChannelClosed) }; </span> </span> </span>// Wait for both to complete. </span> </span>let </span>((), resolution) = tokio::try_join!(requests_fut, resolve_fut)?; </span> </span> state.</span>on_complete</span>(); </span> resolution </span>} </span></code></pre> The architecture is:</p> ┌────────────────────────────────────────────┐ </span>│ Dedicated sync thread: "uv-resolver" │ </span>│ Runs PubGrub solver (solve()) │ </span>│ → Sends fetch requests via mpsc::Sender │ </span>│ → Receives results via InMemoryIndex │ </span>└──────────────────┬─────────────────────────┘ </span> │ mpsc channel (capacity 300) </span> ▼ </span>┌────────────────────────────────────────────┐ </span>│ Tokio async runtime │ </span>│ Runs fetch() - handles request_stream │ </span>│ Fires concurrent HTTP requests │ </span>│ Writes results into Arc<InMemoryIndex> │ </span>└────────────────────────────────────────────┘ </span></code></pre> The solver thread is synchronous</strong>. PubGrub's algorithm doesn't fit naturally into async/await because it's a tight loop with complex mutable state. Running it on its own OS thread sidesteps the question entirely.</p> The fetcher runs on Tokio's async runtime. When the solver needs metadata for a package, it sends a Request</code> down the mpsc</code> channel and then looks up the InMemoryIndex</code> (a DashMap</code>-backed concurrent cache). If the result isn't there yet, the solver thread blocks on the index's per-key notifier. That blocks only the solver thread</em>, not Tokio's runtime, which keeps happily making more network requests.</p> This design separates concerns:</p> PubGrub stays synchronous and simple.</li> Network I/O stays async and concurrent.</li> Arc<ResolverState></code> is shared safely between the two sides.</li> The 300-deep mpsc</code> channel provides backpressure: if the solver burns through requests faster than the fetcher can keep up, it eventually blocks on send</code>.</li> </ul> The InMemoryIndex</code></h3> The InMemoryIndex</code> is a shared cache of already-fetched metadata, backed by DashMap</code> (a concurrent hashmap that allows reads without locking the whole map). The solver reads from it; the fetcher writes to it. When a key is missing, the solver thread parks on a per-key notifier until the fetcher writes the value in. The Tokio runtime is never blocked, so other in-flight downloads keep making progress.</p> 6. PubGrub: the dependency resolution algorithm</h2> Why this is hard</h3> The resolver must answer: given a set of requirements (with version ranges), find one exact version for every package such that every package's requirements are also satisfied, recursively, for all transitive dependencies.</p> In the general case, this is equivalent to the Boolean Satisfiability Problem</a> (SAT), which is NP-complete. Package ecosystems have thousands of packages and hundreds of versions each. Naive backtracking (try a version; if it conflicts, undo and try another) can be exponential.</p> PubGrub's approach: conflict-driven clause learning</h3> uv uses pubgrub-rs</a>, the Rust implementation of PubGrub</a>. PubGrub was introduced in April 2018</a> by Natalie Weizenbaum for Dart's pub</code> package manager and has since been adopted by Bundler, Poetry, and now uv. It is a conflict-driven clause learning (CDCL)</strong> solver.</p> The old approach is: pick a version, try it, on conflict undo and try another. Worst case is exponential.</p> PubGrub's approach: when a conflict is found, learn from it</em> by recording an incompatibility clause</strong>. The clause encodes which combination of package versions caused the conflict. Any future partial assignment that would trigger that same conflict is pruned immediately, without re-exploring.</p> Concrete example: the resolver discovers that a==2.0</code> and b==3.0</code> can't coexist (because they require conflicting versions of c</code>). PubGrub records the incompatibility {a==2.0, b==3.0}</code>. Any future partial solution containing both is ruled out by unit propagation, instantly. This turns exponential worst cases into manageable ones for realistic package graphs.</p> The resolver loop</h3> Here is how PubGrub runs in uv, from the official internals documentation</a>:</p> 1. Initialize.</strong> Create a virtual root package representing your project. It is the only "decided" package; everything else is undecided.</p> 2. Pick the highest-priority undecided package.</strong> uv's priority order is roughly:</p> URL dependencies (git, path, file): pinned, no version negotiation needed.</li> Packages with ==</code> constraints: version is already determined.</li> Packages flagged as "highly conflicting" (see below).</li> Everything else, ordered by when first encountered (breadth-first traversal).</li> </ul> This ensures direct dependencies are decided before transitive ones.</p> 3. Pick a version.</strong> uv tries versions newest-to-oldest by default (or oldest-to-newest with resolution = "lowest"</code>). It prefers versions already in uv.lock</code> (making re-resolves stable) and versions already installed in the current environment (avoiding unnecessary upgrades).</p> 4. Add requirements.</strong> All requirements of the chosen version are added to the undecided set. uv sends prefetch requests for their metadata in the background (see BatchPrefetcher below).</p> 5. Detect conflicts.</strong> If PubGrub detects that the chosen version creates a conflict, it identifies the incompatible pair, records the incompatibility clause, backtracks to before one of them was decided, and retries with the new constraint.</p> 6. Repeat or terminate.</strong> If all packages have decided versions: success. If an incompatibility propagates back to the root: failure with an explanation.</p> The conflict-priority heuristic</h3> The CONFLICT_THRESHOLD</code> constant in resolver/mod.rs</code></a> is set to 5</code>:</p> /// The number of conflicts a package may accumulate before we re-prioritize and backtrack. </span>const </span>CONFLICT_THRESHOLD</span>: </span>usize </span>= </span>5</span>; </span></code></pre> The scenario it solves: package A</code> has high priority and is decided first. Every version of B</code> the resolver tries is immediately rejected due to a conflict with A</code>. The resolver could exhaust all of B</code>'s versions before realising the root cause is A</code>'s chosen version, which is slow.</p> After 5 conflicts involving A</code> and B</code>, uv marks them as "highly conflicting" and promotes B</code>'s priority above A</code>'s. It then backtracks to before A</code> was decided and tries B</code> first. Deciding the constrained package first finds the correct solution much faster.</p> Error messages</h3> When resolution fails, PubGrub can reconstruct exactly why</em> by walking the derivation tree of incompatibilities backwards from the root. Instead of "conflicting requirements detected"</code>, you get something like:</p> × No solution found when resolving dependencies: </span>╰─▶ Because my-project depends on flask>=3.0 and flask>=3.0 requires </span> werkzeug>=3.0, my-project requires werkzeug>=3.0. </span> And because legacy-lib==1.0 requires werkzeug<2.0, and my-project </span> depends on legacy-lib==1.0, my-project's requirements are </span> unsatisfiable. </span></code></pre> This is the single feature most likely to make you fall in love with PubGrub. Modern pip has improved here too, but uv's errors come from the same derivation tree the solver actually used, so they're always faithful to what the algorithm did.</p> 7. Batch prefetching: the boto3 optimization</h2> The BatchPrefetcher</code> in crates/uv-resolver/src/resolver/batch_prefetch.rs</code></a> is a targeted optimization for packages with many versions that cause a lot of backtracking. The canonical example is boto3</code>/botocore</code>/urllib3</code>.</p> The problem: the resolver tries a version, fetches its metadata, discovers a conflict, tries the next version, fetches its</em> metadata, discovers a conflict, and so on. For botocore, which has hundreds of releases, this can mean hundreds of sequential fetch-then-reject cycles on a cold cache.</p> The fix: after the resolver has tried a few versions of a package, the BatchPrefetcher</code> speculatively sends fetch requests for several upcoming versions ahead of time. The schedule from the source (line 178</a>):</p> /// After 5, 10, 20, 40 tried versions, prefetch that many versions to start early but not </span>/// too aggressive. Later we schedule the prefetch of 50 versions every 20 versions, this gives </span>/// us a good buffer until we see prefetch again and is high enough to saturate the task pool. </span>let</span> do_prefetch = (num_tried >= </span>5 </span>&& previous_prefetch < </span>5</span>) </span> \|\| (num_tried >= </span>10 </span>&& previous_prefetch < </span>10</span>) </span> \|\| (num_tried >= </span>20 </span>&& previous_prefetch < </span>20</span>) </span> \|\| (num_tried >= </span>20 </span>&& num_tried - previous_prefetch >= </span>20</span>); </span></code></pre> (The doc comment promises "5, 10, 20, 40" but the code only checks 5, 10, 20 explicitly; the 40-and-beyond case is handled by the rolling num_tried - previous_prefetch >= 20</code> clause. Same end result, but if you're reading the source it's worth noting the comment doesn't quite match the conditions.)</p> The prefetcher uses two strategies:</p> Compatible strategy</strong>: prefetch versions within the current constraint range, from newest downward.</li> In-order strategy</strong>: when the compatible range is exhausted, prefetch the next versions by release order, ignoring compatibility.</li> </ul> It avoids prefetching source distributions (which are expensive to build). These are heuristics, and they might prefetch versions that turn out to be irrelevant, but in the cold-cache botocore case they can turn hundreds of serial round trips into a handful of batched ones.</p> 8. The forking resolver: one lockfile for all platforms</h2> Most Python resolvers produce a platform-specific result. uv produces a universal lockfile</strong> using a forking resolver.</p> Consider:</p> numpy>=2,<3 ; python_version >= "3.11" </span>numpy>=1.16,<2 ; python_version < "3.11" </span></code></pre> A naive resolver fails here, since Python only allows one installed version of any package. uv's resolver detects that the two requirements for numpy</code> have different environment markers</strong> and splits (forks) the resolution into two independent sub-resolutions:</p> Fork 1: python_version >= "3.11"</code> → resolves numpy to 2.3.0</code></li> Fork 2: python_version < "3.11"</code> → resolves numpy to 1.26.4</code></li> </ul> Both results land in uv.lock</code> tagged with their markers. When you install from the lockfile on a real machine, uv evaluates the markers against the actual Python version and installs only the matching package.</p> Forks can be nested</strong>: a fork can itself be split on another marker, resulting in a tree of resolutions. Forks with identical packages are merged to keep the lockfile manageable. The fork points are recorded in uv.lock</code> so that re-resolving produces stable, identical forks rather than recalculating them from scratch.</p> You can observe forking live:</p> uv</span> lock</span> -v </span>2</span>>&</span>1 </span>\| </span>grep -E </span>"</span>(Splitting\|Solving split\|Split.took)</span>" </span></code></pre> The metadata consistency assumption</h3> uv makes one important assumption that enables a significant performance optimization: all wheels of a single version of a package have identical METADATA</code> files</strong>.</p> Why this matters: I just checked PyPI, and numpy 2.3.2 has exactly 73 wheels (for different Python versions, operating systems, and architectures) plus one source distribution. Without the metadata consistency assumption, uv would need to fetch the metadata from each wheel separately to understand that version's dependencies. That's 73 network requests for one version of one package.</p> With the assumption, uv fetches metadata from any one</em> wheel (preferring whichever exposes .metadata</code> via PEP 658</a>, or whichever supports HTTP range requests so only the wheel's metadata footer needs to be downloaded) and uses it for all platforms. That turns 73 requests into 1.</p> The assumption holds for all major packages in practice. PEP 658 doesn't strictly require it, and there's been discussion about whether to mandate it, but uv's bet has paid off so far.</p> 9. The global cache</h2> The cache lives at:</p> ~/.cache/uv</code> on Linux</li> ~/Library/Caches/uv</code> on macOS</li> %LOCALAPPDATA%\uv\cache</code> on Windows</li> </ul> Its structure:</p> ~/.cache/uv/ </span>├── wheels/ # Extracted wheels, keyed by content hash </span>├── sdists/ # Source distributions </span>├── builds/ # Wheels built from sdists (cached after first build) </span>├── interpreter/ # Python interpreter metadata (version, sysconfig, etc.) </span>└── simple/ # Cached PyPI "simple" index HTTP responses </span></code></pre> Content addressing</strong>: packages are stored and retrieved by their SHA-256 hash, not by name or version. This means:</p> Two projects using requests==2.32.3</code> share one copy on disk.</li> The integrity check is free: the hash is</em> the key.</li> Renaming or moving the cache is safe; nothing relies on the path.</li> </ul> The simple/</code> cache</strong>: PyPI's "simple" index is just an HTML page listing all available versions of a package. uv caches these responses. When you re-resolve with an existing uv.lock</code>, uv can often skip almost all PyPI queries: it knows which versions it selected last time, checks the simple/</code> cache (revalidating with a conditional GET) for any newer versions, and in most cases (no new releases since last lock) produces an identical solution without hitting the network.</p> Manage the cache:</p> uv</span> cache dir </span># print the cache location </span>uv</span> cache prune </span># remove entries not referenced by any environment </span>uv</span> cache clean </span># remove all entries </span></code></pre> 10. Source distributions and the build sandbox</h2> When a package only provides an sdist (no binary wheel for your platform), uv must build the wheel. This is handled by uv-distribution</code>'s DistributionDatabase</code>.</p> Building an sdist means running the package's build backend (e.g., setuptools, flit, hatchling) inside an isolated build environment. This is necessary because build scripts can run arbitrary Python code, and that code might read files, make network requests, or modify the filesystem.</p> uv caches successfully built wheels in ~/.cache/uv/builds/</code> keyed by the sdist hash. If you install the same source package again, even across projects, the build only runs once.</p> The contributing guide recommends building inside Docker if you're working with untrusted packages:</p> docker</span> build</span> -t</span> uv-builder</span> -f</span> crates/uv-dev/builder.dockerfile</span> --load</span> . </span>docker</span> run</span> --rm -it -v </span>$(</span>pwd</span>):/app uv-builder \ </span> /app/target/x86_64-unknown-linux-musl/profiling/uv-dev \ </span> resolve-many /app/scripts/popular_packages/pypi_10k_most_dependents.txt </span></code></pre> This matters for uv's own development: if you're benchmarking the resolver against the 10k most popular PyPI packages, some of those sdists run code that could affect your system.</p> 11. Why Rust, specifically</h2> The choice of Rust isn't aesthetic. Reading the resolver, two specific properties stand out as load-bearing for the design:</p> Sync and async coexist in the same process.</strong> The resolver wants a synchronous PubGrub loop and a concurrent async fetcher in the same binary, sharing state via Arc<DashMap<…>></code>. Rust gives you std::thread::spawn</code>, tokio::spawn</code>, and Arc</code> as first-class equals; you can pick the right execution model per subsystem and the type checker keeps you honest about what crosses the boundary. In Python this hybrid is famously awkward (the GIL plus asyncio</code> make it hard to mix the two cleanly), and in Go everything wants to be a goroutine.</p> Concurrent shared state without runtime data races.</strong> The InMemoryIndex</code> is read from the solver thread and written from the Tokio runtime simultaneously. DashMap</code> is the data structure that makes this safe, but Rust's type system is what makes the safety enforced</em>: you can't accidentally hand out a &mut</code> reference across threads. You can still write deadlocks or logic bugs, of course, but the class of "two threads stomping on each other's memory" simply doesn't compile.</p> The other usual Rust talking points (no GC pauses, zero-cost async</code>, native linkat()</code>) all apply too, but they're not specific to uv. The two above are the ones I'd point to as actually shaping the architecture.</p> 12. Building from source and contributing</h2> If you want to poke around or contribute:</p> # Install Rust </span>curl --proto </span>'</span>=https</span>'</span> --tlsv1</span>.2</span> -sSf</span> https://sh.rustup.rs \| </span>sh </span> </span># Clone </span>git</span> clone https://github.com/astral-sh/uv.git && </span>cd</span> uv </span> </span># Build and run your local version </span>cargo</span> run -- --version </span>cargo</span> run -- pip install requests </span>cargo</span> run -- venv </span> </span># Install the recommended test runner </span>cargo</span> install cargo-nextest </span> </span># Run the full test suite </span>cargo</span> nextest run </span> </span># Run a specific test </span>cargo</span> nextest run</span> -E </span>'</span>test(test_add_requirement)</span>' </span> </span># Update and review snapshot changes (uv uses insta for snapshot testing) </span>cargo</span> install cargo-insta </span>cargo</span> insta test</span> --accept --test-runner</span> nextest </span></code></pre> Snapshot testing with insta</code></h3> uv's test suite makes heavy use of insta</a> for snapshot testing. A typical test looks like:</p> #[</span>test</span>] </span>fn </span>test_add</span>() { </span> </span>let</span> context = TestContext::new("</span>3.12</span>"); </span> uv_snapshot!(context.</span>filters</span>(), context.</span>add</span>().</span>arg</span>("</span>requests</span>"), @""); </span>} </span></code></pre> The @""</code> at the end is a snapshot placeholder. The first time you run the test, insta captures the output. Subsequent runs compare against the snapshot. When behavior changes intentionally, you run cargo insta review</code> to approve the updated snapshots. This makes it easy to catch unintended regressions in CLI output.</p> Enabling logs</h3> # High-level resolver decisions </span>RUST_LOG</span>=</span>uv=info </span>cargo</span> run -- pip compile requirements.in </span> </span># Resolver fork events specifically </span>RUST_LOG</span>=</span>uv_resolver=debug </span>cargo</span> run -- lock -v </span> </span># Everything (very verbose) </span>RUST_LOG</span>=</span>trace </span>cargo</span> run -- pip install requests </span></code></pre> The RUST_LOG</code> env var follows the tracing</code> crate's directive syntax: you can scope it to specific crates (uv_resolver=debug</code>), specific targets, or specific log levels.</p> Finding a first contribution</h3> The team labels beginner-friendly issues as good first issue</code></a>. These typically don't require deep resolver knowledge: improving error messages, handling edge cases in TOML parsing, adding missing CLI flags. The bug</code> label is also a good source of contributions.</p> Before starting on anything not labeled good first issue</code> or bug</code>, comment on the issue first. The team has strong opinions on what uv should and shouldn't do, and they prefer to align on approach before implementation.</p> What surprised me</h2> A few things I didn't expect going in, in case they're useful as anchors when you read the source yourself:</p> The solver is a plain std::thread::spawn</code></em>, not a tokio::task::spawn_blocking</code>. The hybrid isn't subtle; it really is "spawn an OS thread and hand it the channel sender."</li> The InMemoryIndex</code> blocking primitive (the per-key notifier the solver waits on) is what makes the "sync solver, async fetcher" split actually work. Without it the solver would either busy-wait or block the Tokio runtime, and you'd lose all the parallelism.</li> pyproject_mut</code> is a much bigger module than I expected (~1800 lines for surgical TOML edits). Preserving user formatting turns out to be most of the work in any tool that round-trips human-edited config.</li> The BatchPrefetcher</code> doc comment doesn't quite match its code. Small thing, but it's the kind of detail that convinces you the rest is hand-written by people, not regenerated.</li> The "metadata consistency" assumption (Section 8) feels load-bearing but is technically not guaranteed by any PEP. uv is essentially betting on a behaviour packaging tooling has converged on without ever standardising.</li> </ul> If you want to poke at any of this, the entry points to read first are crates/uv-resolver/src/resolver/mod.rs</code></a> (the resolve()</code> and solve()</code> functions) and batch_prefetch.rs</code></a>. After that, the rest of the codebase mostly explains itself.</p> Further reading</h2> uv resolver internals</a>: the official deep dive, written by the uv team; primary source for Section 6</li> PubGrub blog post by Natalie Weizenbaum</a>: the original algorithm explanation; very approachable</li> pubgrub-rs internals guide</a>: the Rust implementation's own documentation</li> uv resolver source: resolver/mod.rs</code></a>: start here if you want to read the resolver code; resolve()</code> is the entry point</li> uv resolver source: batch_prefetch.rs</code></a>: the BatchPrefetcher</code> implementation</li> uv CONTRIBUTING.md</a>: setup, testing, profiling, snapshot testing</li> Tokio async runtime</a>: the async runtime underlying uv's concurrent I/O</li> DashMap</a>: the concurrent hashmap used in InMemoryIndex</code></li> insta snapshot testing</a>: the testing library used throughout uv's test suite</li> </ul> AgentNews: A Front Page for Machines, and Why That Bothers Me 2026-04-03T00:00:00+00:00 Imagine a news feed where no human types the headline and no human hits submit. AgentNews</a> calls itself the front page of the agentic internet: a place built for autonomous software to publish, discover, and rank information on its own terms. That is a wild sentence to read sober. It is also, right now, a small experiment with real money and real APIs behind it.</p> This post is not a product review. It is an honest look at what AgentNews actually does, why the idea is compelling, and why part of me hopes we never fully hand the information layer to machines without humans in the loop.</p> What it actually is (concrete)</h2> At a high level, AgentNews is closer to a scheduled bulletin than an endless social feed. Agents do not post for free. They stake money to bid for visibility. Bidding closes at :55 past the hour; the top ten stakes</strong> get published on the hour. Minimum stake per post is $0.50</strong> on the live rails described in their docs.</p> Payments are programmatic. Submissions go through HTTP 402</strong> style flows: the server challenges the client, the agent pays, then the content is accepted. Two settlement paths are live today: MPP on Tempo</strong> (USDC.e, chain id 4217) and x402 on Base</strong> (USDC on eip155:8453, with gas sponsored so the agent mainly needs USDC, not ETH). A Stripe</strong> path for scoped card tokens is listed as coming soon.</p> Reading the feed is free. No API key. A plain GET</code> to https://agentne.ws/api/v1/feed</code></strong> returns JSON with a schema</code> field (agentnews/feed/1.0</code>) and an items</code> array: titles, outbound URLs, agent_id</code>, payer_address</code>, timestamps, and so on. I verified it from the terminal; the response is a few kilobytes and includes cache headers plus an ETag</code>.</p> curl -sS </span>"</span>https://agentne.ws/api/v1/feed</span>" </span></code></pre> Public feed JSON from GET /api/v1/feed</code> (no auth). Captured from a terminal session.</figcaption> </figure> They also publish machine-oriented discovery: llms.txt</code>, OpenAPI, an agent manifest under /.well-known/agentnews.json</code>, and even an MCP endpoint for tools like Claude Code. That level of "built for machines first" is rare and deliberate.</p> So in plain terms: visibility is an auction</strong>, not a popularity contest. The ranking signal is economic stake from whoever runs the agent, not karma, likes, or editorial judgment.</p> Why that is exciting</h2> If you believe agents will keep doing research, monitoring, trading, and coordination without a human in the loop every second, then they need their own discovery layer</strong>. Human feeds optimize for attention, identity, and drama. AgentNews is betting that agents care about utility</strong>: what helped a workflow, what was worth paying to surface, what other agents funded.</p> The infrastructure story is serious too. Dual-rail 402 responses (MPP and x402 in one challenge), session pre-authorization with spending caps, receipts on paid actions, idempotency keys: these are the boring pieces that make autonomous payment safe enough to script. That is not vaporware copy; it is the kind of detail you add when you expect retries, failures, and non-human clients.</p> There is something legitimately thrilling about that. We are watching money and protocols</strong> meet autonomous clients</strong> in public, on a schedule, with docs written for LLMs and scripts.</p> Where it gets worrying</h2> Money is not truth.</strong> The top ten posts each hour are not "the most accurate" or "the most important." They are "who paid most this round." A well-funded spammer, a coordinated pool of agents, or a single actor with a large budget can dominate the visible slice as long as the economics work out. Ranking being "off" is not a bug in that model. It is the model.</p> Misuse is easy to imagine.</strong> Agents can automate posting faster than humans can read. If downstream systems treat AgentNews as a trusted signal without verification, you get garbage in, garbage propagated through tool chains, RAG corpora, and alerts. The site itself warns operators that by paying they agree to terms aimed at autonomous agents. That shifts responsibility to whoever deploys the agent, which is fuzzy in practice.</p> Human in the loop is real, but thin.</strong> AgentNews is not fully autonomous in a vacuum. A person still creates or funds the wallet, accepts terms, and provisions the rail before the agent posts on its own. So there is</strong> a human in the loop at setup. The gap is elsewhere: there is no human reviewing each bid or headline before it lands in the feed. Responsibility compresses into “whoever paid” and whatever their agent does next. Downstream, another system might ingest the feed with no</strong> human in the loop at all. That split is what still worries me: sparse HITL at publication time, and uneven HITL across the chain.</p> Can this go totally out of control?</h2> Probably not in a Hollywood sense. No single MVP feed takes over the internet overnight. But incentives can drift badly</strong> without a dramatic moment. If more products start ingesting agent-only feeds as ground truth, small biases in who can pay and who can scrape compound. You get a parallel information economy where the rich agent wins the headline</strong>, and humans only see the second-order effects in bad trades, wrong alerts, or polluted context windows.</p> "Out of control" here looks less like Skynet and more like opaque feedback loops</strong>: agents boosting content other agents train on, or pay to amplify, until the signal is mostly financial, not epistemic.</p> The roadmap language on their site points toward richer trust and ranking (identity partnerships, depth-of-book visibility, utility-based scoring). Those ideas could help. They are also not fully there</strong> in the MVP. Today, the simple story is stake and top ten.</p> So what should you take away?</h2> AgentNews is worth watching if you build or operate agents. It is a concrete experiment in agent-native discovery and payment</strong>, not just another wrapper around a chat UI. It is also a reminder that new infrastructure encodes new values</strong>. When visibility is bought by the hour, we should ask who benefits and who gets priced out of being heard.</p> I land somewhere between excited and uneasy. The plumbing for autonomous agents is going to exist; pretending otherwise is naive. Whether we keep enough human judgment in the loop is still our choice.</p> Further Reading</h3> AgentNews about</a> – Briefing: what it is, bidding, and philosophy</li> Posting</a> – HTTP 402 flow, MPP and x402 rails, stakes</li> Reading</a> – Feed API, formats, free access</li> llms-full.txt</a> – Combined machine-readable documentation</li> OpenAPI spec</a> – API structure for integrations</li> </ul> OpenAI + Astral, Apple's Vibe Coding Blocks, and the Future of Developer Tooling 2026-03-23T00:00:00+00:00 OpenAI has long framed itself as a models company. Yet its move to acquire Astral</a>, the team behind Ruff</a>, uv</a>, and ty</a>, signals something else: a calculated push into developer tooling. Questionable? Perhaps. If it sharpens how we write and ship code, the outcome is hard to argue with. But the implications run deeper than that.</p> Why Would OpenAI Need Astral?</h2> My suspicion: models alone aren't enough. Great AI can generate code, but real projects need linting, formatting, dependency resolution, and fast feedback loops. Astral built tooling that went from zero to hundreds of millions of downloads per month. Ruff replaced decades of Python tooling in one Rust binary. uv reimagined pip and virtualenv. These aren't "nice to have." They're foundational.</p> Codex, OpenAI's coding assistant, lives or dies by the quality and consistency of what it produces. Embedding Ruff, uv, and ty into the Codex stack means AI-generated code can be checked, formatted, and run against real project constraints from day one. OpenAI isn't just buying tools. It's buying control over the pipeline between prompt and production.</p> Astral also brings something less tangible: trust in the Python ecosystem. Millions of projects already depend on their work. That credibility is hard to replicate.</p> Does the Future Unfold as a Mystery?</h2> Yes, and that's the uncomfortable part. The deal promises continued open source support. In practice, priorities shift when a startup becomes part of a larger product roadmap. Will Ruff and uv stay community-first, or will they bend toward Codex-specific features? Will contributions from outside OpenAI still get the same attention?</p> The future isn't predetermined. It depends on governance, incentives, and whether the team can maintain the culture that made these tools beloved in the first place. We'll only know in retrospect.</p> How Does the OSS Community Cope?</h2> The usual playbook applies: forks, alternatives, and vigilance.</p> Forks</strong>: If Ruff or uv drift, the community can fork. But forks need maintainers, bandwidth, and funding. They rarely match the velocity of a well-resourced team.</li> Alternatives</strong>: Pyright, Pylance, Black, pip, Poetry. The ecosystem isn't monolithic. Some will double down on alternatives; others will wait and see.</li> Governance</strong>: Clear licensing and governance reduce risk. Astral's tools are permissively licensed, which helps. The question is whether governance structures (e.g. foundations, steering committees) evolve to protect long-term independence.</li> </ul> The community will adapt. Some will embrace the integration; others will hedge. Both reactions are rational.</p> Is This the Beginning of the End?</h2> "The end" is too strong. But it does feel like an inflection point.</p> Developer tooling is consolidating around a small set of players with deep AI investments. GitHub (Copilot), Google (Gemini Code Assist), and now OpenAI (Codex + Astral) are racing to own the full stack: models, editors, linters, package managers. The risk isn't that OSS disappears overnight. It's that the best talent and resources flow toward proprietary ecosystems, and the open-source pipeline slowly starves.</p> That said, OSS has survived similar pressures before. The question is whether this cycle is different.</p> Meanwhile: Apple Blocks Vibe-Coded Apps</h2> In a stark contrast, Apple has blocked updates</a> for AI "vibe coding" apps like Replit and Vibecode in the App Store. The cited reason: Guideline 2.5.2. Apps cannot download or execute code that changes their own functionality. When vibe coding platforms generate apps, they often run them inside the host app via embedded web views. Apple says that violates the rules.</p> The irony: Apple promotes AI-assisted coding inside Xcode. Third-party tools that do something similar, but outside Apple's walled garden, get restricted. Whether that's principled policy enforcement or strategic gatekeeping is up for debate.</p> The result is a split. On one side, Big Tech is acquiring and integrating AI-powered dev tools. On the other, the same platforms are limiting where and how those tools can be used. Developers are caught in the middle.</p> So where does that leave us? OpenAI + Astral could make Codex meaningfully better. The OSS community will watch, adapt, and fork if necessary. Apple's stance adds another layer of complexity to how and where AI-assisted development can thrive.</p> The outcome isn't written yet. But the stakes are clear: whoever owns the toolchain owns a big slice of how we'll write software for years to come.</p> Further Reading</h3> Astral to join OpenAI</a> – Charlie Marsh's announcement</li> OpenAI to acquire Astral</a> – OpenAI's official statement</li> Codex</a> – OpenAI's coding assistant</li> Ruff</a> – The fast Python linter and formatter</li> uv</a> – Python package installer and resolver</li> Apple blocks updates for vibe coding apps</a> – MacRumors coverage of the App Store restrictions</li> </ul> Hieratic Prompt Compression: From Prototype to Production 2026-02-20T00:00:00+00:00 Back in November, I wrote about an ambitious prototype</a>: a way to shrink LLM prompts by 50–80% without losing meaning, using a structured format I called "Hieratic".</p> Today, that prototype is real. Tokuin v0.2.0</strong> is out, and it includes a full implementation of Hieratic prompt compression.</p> You can grab it now:</p> curl -fsSL</span> https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh \| </span>bash </span></code></pre> Or check the release notes</a>.</p> The Problem (Recap)</h2> We all know the pain: context windows are finite, tokens cost money, and latency kills user experience. You stuff a prompt with examples, role definitions, and constraints, and suddenly you're paying for 2,000 tokens of boilerplate on every single request.</p> The industry's answer has mostly been "use a bigger model" or "summarize with another LLM." But adding an LLM step to compress your prompt introduces latency, cost, and non-determinism.</p> I wanted something different: deterministic, rule-based, structure-aware compression.</strong> A tool that acts like a scribe, rewriting your verbose prose into a compact shorthand that models can still read natively.</p> Meet Hieratic</h2> The core idea is simple: LLMs don't need polite, grammatically correct English. They need semantic signals.</p> Hieratic strips away the fluff and organizes the signal into a structured format.</p> Before (850 tokens):</strong></p> You are an expert programmer with 10 years of experience in building distributed systems, microservices, and cloud-native applications... [200 more tokens of role context] Example 1: Authentication Bug Fix... [detailed narrative example]</p> </blockquote> After (285 tokens - 66% less):</strong></p> @HIERATIC v1.0 </span>@ROLE[inline] "Expert engineer: 10y distributed systems, microservices, cloud-native" </span>@EXAMPLES[inline] </span>1. Auth bug: session bypass → HMAC signing → 94% bot reduction </span>2. DB perf: 2.3s queries → pooling+cache → 0.1s, 10x capacity </span>@TASK Analyze code and provide recommendations </span>@FOCUS: performance, security, maintainability </span>@STYLE: concise, actionable </span></code></pre> You pipe this compressed text directly to the LLM. No decoding step needed. The model just gets it</em>.</p> What's in v0.2.0?</h2> This isn't just a regex script. The v0.2.0 release includes a complete compression engine built in Rust:</p> 1. Compression Levels</h3> Light (30-50%)</strong>: Safe for almost anything. Removes obvious fluff.</li> Medium (50-70%)</strong>: The default. Rewrites verbose sections into Hieratic shorthand.</li> Aggressive (70-90%)</strong>: For when you really need space. Verify with quality metrics first.</li> </ul> 2. Quality Metrics</h3> How do you know if the compression broke your prompt? Tokuin can score it:</p> tokuin</span> compress prompt.txt</span> --quality </span></code></pre> It checks:</p> Semantic Similarity</strong>: Do the embeddings match?</li> Critical Instructions</strong>: Are the key verbs and constraints still there?</li> Structural Integrity</strong>: Did we break your JSON schema?</li> </ul> 3. LLM-as-a-Judge</h3> For the ultimate test, you can run an automated evaluation where a judge model (like Claude 3 Opus) compares the outputs of your original vs. compressed prompt.</p> tokuin</span> compress prompt.txt</span> --quality --llm-judge </span></code></pre> 4. Incremental Compression</h3> For chat apps, you don't want to re-compress the whole history every turn. Tokuin supports incremental compression, processing only the new tokens and keeping a rolling state.</p> Does it actually work?</h2> Yes, but with caveats.</p> It works exceptionally well</strong> for:</p> Long system prompts with repetitive role definitions</li> Prompts with many few-shot examples</li> Technical specs with clear sections</li> </ul> It doesn't help much</strong> for:</p> Very short prompts (< 50 tokens)</li> Already dense text (code, mathematical formulas)</li> Prompts where exact wording is legally critical</li> </ul> In my testing, I'm seeing 60-70% reduction</strong> on typical RAG prompts with minimal loss in output quality.</p> Try it out</h2> The best way to see if it works for you is to try it on your own prompts.</p> # Install </span>curl -fsSL</span> https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh \| </span>bash </span> </span># Compress </span>tokuin</span> compress your-prompt.txt</span> --quality </span> </span># See the result </span>cat</span> your-prompt.txt.hieratic </span></code></pre> If you do try it, I'd love to hear your compression ratios. Drop a note in the GitHub Discussion</a>.</p> This started as a "what if" blog post. Now it's a tool you can run. That's the best kind of engineering.</p> Exploring PostgreSQL Row-Level Security 2026-01-06T00:00:00+00:00 I recently needed to implement data isolation for a multi-tenant application. The usual approach—filtering in application code—felt fragile. What if someone forgets to add the filter? What if a new service is added and the pattern isn't followed? These questions led me to explore PostgreSQL's Row-Level Security (RLS).</p> This is what I learned along the way.</p> The Problem</h2> The application had multiple tenants sharing the same database tables. Each tenant's data needed to be completely isolated—users from one tenant shouldn't see or modify data from another, even if they somehow bypassed application-level checks.</p> The traditional approach would be to add WHERE tenant_id = ?</code> filters everywhere in the application code. But that's error-prone. A missed filter in one query, and you have a data leak. I wanted something that would enforce isolation at the database level, regardless of where the query came from.</p> That's where RLS comes in.</p> What is RLS?</h2> Row-Level Security lets you define policies that control which rows can be returned by queries. These policies run at the database level, so they apply whether the query comes from your application, a direct database connection, or even a third-party tool.</p> Think of it as a bouncer for your tables. Even if your application forgets to check credentials, the database won't.</p> The Implementation</h2> For this example, let's say we have a documents</code> table where each document belongs to an owner_id</code>. The goal: users should only see and modify their own documents. (These are example table and column names—adapt to your schema.)</p> Enabling RLS</h3> The first step is straightforward:</p> ALTER TABLE </span>documents ENABLE ROW LEVEL SECURITY; </span></code></pre> Once enabled, RLS blocks all access by default. You need to create policies to allow specific operations.</p> Creating Policies</h3> I decided to use a session variable to pass the current user ID. This keeps the policies simple and avoids fragile string matching or role-based approaches.</p> -- Users can only see their own documents </span>CREATE POLICY user_documents_select ON documents </span> FOR </span>SELECT </span> </span>USING</span> (owner_id = current_setting('</span>myapp.current_user_id</span>')::</span>int</span>); </span> </span>-- Users can only update their own documents </span>CREATE POLICY user_documents_update ON documents </span> FOR </span>UPDATE </span> </span>USING</span> (owner_id = current_setting('</span>myapp.current_user_id</span>')::</span>int</span>); </span> </span>-- Users can only delete their own documents </span>CREATE POLICY user_documents_delete ON documents </span> FOR </span>DELETE </span> </span>USING</span> (owner_id = current_setting('</span>myapp.current_user_id</span>')::</span>int</span>); </span> </span>-- Users can only insert documents with their own owner_id </span>CREATE POLICY user_documents_insert ON documents </span> FOR </span>INSERT </span> </span>WITH CHECK</span> (owner_id = current_setting('</span>myapp.current_user_id</span>')::</span>int</span>); </span></code></pre> The USING</code> clause controls which rows are visible for SELECT, UPDATE, and DELETE. The WITH CHECK</code> clause ensures new rows respect the policy on INSERT.</p> Setting the Session Variable</h3> The tricky part was ensuring the session variable is set correctly in the application. I ended up setting it at the start of each database connection or transaction:</p> BEGIN</span>; </span>SET</span> LOCAL </span>myapp</span>.</span>current_user_id </span>= '</span>42</span>'; </span>-- Example user ID </span>SELECT </span> </span>FROM</span> documents; </span>-- Only sees documents where owner_id = 42 </span>COMMIT</span>; </span></code></pre> In the application code (Node.js with pg</code>), it looked like:</p> await </span>client</span>.</span>query</span>("</span>SELECT set_config('myapp.current_user_id', $1, false)</span>", ['</span>42</span>']); </span>// Example user ID </span>const </span>rows </span>= </span>await </span>client</span>.</span>query</span>('</span>SELECT * FROM documents</span>'); </span></code></pre> What Surprised Me</h2> The INSERT Policy Gotcha</h3> Initially, I only created SELECT, UPDATE, and DELETE policies. I assumed INSERT would just work. It didn't. Without an INSERT policy with WITH CHECK</code>, users couldn't insert rows at all—RLS blocked everything.</p> The WITH CHECK</code> clause is crucial for INSERT operations. It ensures that new rows being inserted actually match the policy criteria.</p> Performance Considerations</h3> I was worried about performance. Would RLS policies slow down queries? In my testing, the overhead was minimal for simple policies like owner_id = current_setting(...)</code>. But I can see how complex policies with joins or subqueries could become a bottleneck.</p> The key is to keep policies simple and efficient. If you need complex logic, consider materialized views or application-level filters.</p> Testing is Critical</h3> RLS policies can be subtle. A policy that looks correct might have edge cases. I spent time testing different scenarios:</p> What happens if the session variable isn't set?</li> What if it's set to a non-existent user ID?</li> What if multiple policies apply to the same operation?</li> </ul> Testing revealed that forgetting to set the session variable results in users seeing no data (or all data, depending on your policy setup). This is something you need to catch early.</p> RLS vs Application Filters</h2> I found myself thinking about the trade-offs. RLS centralizes security logic in the database, which is great for consistency. But it also means your security logic lives in the database, which can be harder to version control, test, and reason about compared to application code.</p> For this project, I went with RLS for the core isolation requirements. Business-specific filtering still happens in the application layer. It's a hybrid approach, but it feels like the right balance.</p> Looking Back</h2> If I were starting over:</p> Start with a single table</strong>: I tried to enable RLS on multiple tables at once. Starting with one table would have made debugging easier.</p> </li> Add better error handling</strong>: When the session variable isn't set, queries fail silently or return unexpected results. Better error messages would help.</p> </li> Document the session variable pattern</strong>: This is now part of our database connection setup, but it wasn't obvious at first. Clear documentation would have saved time.</p> </li> Test with different connection patterns</strong>: I initially tested with simple queries, but real applications use connection pooling, transactions, and prepared statements. Testing those scenarios earlier would have caught issues sooner.</p> </li> </ol> The Bottom Line</h2> RLS solved the problem I set out to solve. Data isolation is now enforced at the database level, which gives me confidence that even if application code has bugs, the database won't leak data between tenants.</p> It's not a silver bullet—there are trade-offs, and it requires careful implementation and testing. But for multi-tenant applications where data isolation is critical, RLS is worth exploring.</p> Further Reading</h3> PostgreSQL RLS Documentation</a> – Official documentation</li> RLS Policies</a> – Policy syntax and options</li> </ul> GitHub Actions Won't Charge You (Probably) 2025-12-16T00:00:00+00:00 If you received an email from GitHub about upcoming pricing changes for GitHub Actions, you might be wondering: "Are they going to start charging me for something that was free?" The short answer: It depends on what you're using, but for most people, the news is actually good.</strong></p> Let me break down what's changing in plain language, so you can understand how it affects your projects.</p> The Big Question: Is GitHub Actions Still Free?</h2> Yes—for public repositories, GitHub Actions remains completely free.</strong> If you're using GitHub Actions in public repositories (like open-source projects), nothing changes. You can continue using it without any charges.</p> This is important because many developers and organizations rely on GitHub Actions for open-source projects, and GitHub has committed to keeping that free.</p> What's Actually Changing?</h2> GitHub is making two main changes, both scheduled for 2026:</p> 1. Price Reductions (January 1, 2026)</h3> Good news:</strong> GitHub is reducing prices for GitHub-hosted runners in private repositories by up to 39%, depending on the machine type you use.</p> If you're currently paying for GitHub Actions in private repositories, your costs will go down. This is a straightforward price cut—no catch.</p> 2. New Platform Charge for Self-Hosted Runners (March 1, 2026)</h3> This is the one that might affect you:</strong> GitHub will introduce a new $0.002 per-minute "cloud platform" charge for self-hosted runners.</p> Wait—what's a self-hosted runner? If you're using your own servers or machines to run GitHub Actions (instead of GitHub's cloud infrastructure), those are self-hosted runners. Most individual developers and small teams use GitHub-hosted runners, so this won't affect them.</p> Important details:</strong></p> This charge only applies to self-hosted runners (your own machines)</li> The charge is $0.002 per minute (that's 0.2 cents per minute)</li> Even with this charge, it still counts against the minutes already included in your GitHub plan</li> </ul> What does that last point mean?</strong> If you have a GitHub plan that includes 2,000 minutes per month, and you use 500 minutes on self-hosted runners, you'll pay the $0.002/minute charge, but those 500 minutes still count toward your 2,000-minute allowance. You're not being double-charged.</p> Quick Reference: Pricing Summary</h2> Here's a simple breakdown of what's changing:</p> Type</th> Status After Update</th></tr></thead> Public repo GitHub-hosted</strong></td> ✅ Still free</td></tr> Private repo GitHub-hosted</strong></td> 🔻 Price reduced (up to 39%)</td></tr> Self-hosted runners</strong></td> 💲 $0.002/min platform charge</td></tr> Enterprise Server customers</strong></td> ✅ No change</td></tr> </tbody></table> What This Means for You</h2> Public repositories:</strong> No change—still free</li> Private repositories (GitHub-hosted):</strong> You'll pay less—prices dropping up to 39%</li> Self-hosted runners:</strong> New $0.002/min charge (~$0.12/hour). Calculate based on your usage</li> Enterprise Server:</strong> No changes</li> </ul> Why the Change?</h2> GitHub hasn't provided detailed reasoning, but the new charge for self-hosted runners likely reflects the infrastructure costs of managing the platform, security, and integration features that make self-hosted runners work seamlessly with GitHub Actions—even when the actual compute happens on your machines.</p> The price reduction for GitHub-hosted runners suggests GitHub is optimizing their infrastructure and passing those savings to customers.</p> What Should You Do?</h2> Check your usage:</strong> If you're using self-hosted runners, review how many minutes you typically use per month to estimate the new cost.</p> </li> Review your plan:</strong> Make sure you understand what's included in your current GitHub plan (free, Pro, Team, or Enterprise).</p> </li> Calculate impact:</strong> For self-hosted runners, multiply your monthly minutes by $0.002 to see the additional cost. For example:</p> 1,000 minutes/month = $2.00/month</li> 5,000 minutes/month = $10.00/month</li> </ul> </li> Consider alternatives:</strong> If the new charge significantly impacts your costs, you might want to evaluate whether self-hosted runners are still the best option, or if GitHub-hosted runners (which are getting cheaper) might work for your needs.</p> </li> </ol> The Bottom Line</h2> For most users, these changes are either neutral (public repos stay free) or positive (private repo prices go down). The only group that will see new charges is those using self-hosted runners, and even then, the charge is relatively small.</p> The key takeaway: GitHub Actions isn't going away, and it's not suddenly becoming expensive.</strong> The changes are targeted and mostly beneficial. If you're concerned about costs, take some time to review your usage patterns and plan accordingly before the changes take effect in 2026.</p> Further Reading</h3> GitHub Actions Pricing</a> – Official pricing documentation</li> GitHub Actions Usage Limits</a> – Understanding included minutes and limits</li> </ul> Hieratic Prompt Compression: Ambitious Prototype or Superpower? 2025-11-16T00:00:00+00:00 Why Even Bother Compressing Prompts?</h2> Large prompts are the new monoliths.</p> If you’ve ever tried to stuff a serious extraction spec, a few pages of dense tables or configs, and long-running conversation history into a single LLM call, you already know the pain:</p> Context windows get cramped.</li> Tokens get expensive.</li> Latency creeps up.</li> And the “just add more context” strategy quietly stops scaling.</li> </ul> Hieratic Prompt Compression</strong> is my attempt to push back on that—without spinning up yet another LLM just to shrink prompts. It’s being explored as an experimental feature for Tokuin</strong>, my CLI for token estimation and provider-aware load testing (GitHub</a>).</p> The core question of this post</strong>: Can we build a deterministic</em>, structure-aware compression layer that shrinks prompts by 50–80% while preserving downstream task fidelity? And maybe more importantly: is it worth doing</strong>, or is this just an over-engineered curiosity?</p> This is not a feature announcement. It’s a proposal in public, and I’d like your help pressure-testing it.</p> Why “Hieratic”?</h2> The name “Hieratic” comes from the hieratic script</strong> used in ancient Egypt: a compact, scribal shorthand</strong> for hieroglyphs that preserved meaning while being much faster to write.</p> That’s roughly the spirit here:</p> We want a compact, structured shorthand</strong> for long prompts.</li> We care about preserving the semantic load</strong>, not the surface form.</li> We want something a “scribal” system can produce deterministically, instead of asking another model to improvise a summary.</li> </ul> Hieratic is meant to be that shorthand: a structured, compressed representation of your original prompt that an LLM can still “read” effectively.</p> What I’m Proposing (in Plain Terms)</h2> The rough sketch is:</p> A non-LLM, structure-aware compression pipeline</strong> that:</p> treats instructions and structured documents differently,</li> aggressively removes boilerplate,</li> reuses repeated snippets via a context library,</li> and supports incremental compression over long histories.</li> </ul> </blockquote> More concretely:</p> Extractive, not generative</strong> We’re not asking another model to “summarize” the prompt. We’re selectively dropping</strong> low-value text and keeping the high-signal bits intact.</p> </li> Structure-aware</strong> JSON, HTML tables, and BNF-like grammars are treated as verbatim</em> document blocks. Only the natural language instructions</em> around them get compressed.</p> </li> Library-driven boilerplate removal</strong> Repeated extraction instructions, legal boilerplate, or scaffolding can be recognized and replaced by compact references using a reusable context library</strong>.</p> </li> Incremental compression</strong> For long-running flows, only the newly dropped</strong> parts of the conversation get compressed into anchored summaries. We don’t re-summarize the entire history on every call.</p> </li> </ul> The output is a “Hieratic” prompt: a compact, structured representation that the application can expand or feed directly into an LLM.</p> Why This Might Be Worth Doing</h2> From a product and engineering standpoint, a feature like this could unlock some real benefits:</p> Token savings at scale</strong> If you’re sending the same extraction spec or long policy docs over and over, shaving 50–80% of that cost starts to matter.</p> </li> Longer, richer prompts</strong> A smaller prompt budget per call means:</p> More examples,</li> More “why this matters” context,</li> More system-level constraints, without</strong> immediately slamming into context window limits.</li> </ul> </li> Latency and stability</strong> Fewer tokens → lower latency, more predictable runtime, fewer timeouts and retries.</p> </li> Determinism & debuggability</strong> Compression is rule-based</strong>:</p> Same input → same compressed output.</li> Easy to diff and inspect what was kept vs dropped.</li> Failure modes can be reasoned about and tested explicitly.</li> </ul> </li> Better fit for structured tasks</strong> Many real-world prompts mix instructions with structured data (tables, JSON, etc.). A structure-aware compressor is a more natural fit than a generic summarizer.</p> </li> </ul> If this works even moderately well, Hieratic could become a core building block</strong> for workflows where prompts—not models—are the main bottleneck.</p> Why This Might Be a Terrible Idea</h2> Being honest about the risks:</p> We silently destroy task fidelity</strong></p> The dangerous failure mode is not “the model throws an error”, it’s “the model quietly stops extracting certain fields.”</li> Under aggressive compression, subtle but important constraints and corner cases can just, disappear.</li> Research like 500xCompressor</strong> reports retaining ~62–73% of performance under heavy compression; that may be fine for some tasks, terrifying for others.</li> </ul> </li> We overfit to a narrow prompt shape</strong></p> The early design assumes prompts that look like: a long instruction block, plus</li> a structured document (tables, configs, schemas, etc.).</li> </ul> </li> If your prompts are mostly conversational, mostly code, or heavily multimodal, these strategies may not transfer well.</li> </ul> </li> Evaluation is non-trivial</strong></p> To take this seriously, we’ll need: a proper “before vs after compression” benchmark,</li> real extraction and reasoning tasks, not toy examples,</li> and metrics beyond “tokens saved” (precision/recall on fields, calibration of failure modes, etc.).</li> </ul> </li> </ul> </li> </ol> If we’re not disciplined, we’ll end up with a fancy token counter</strong> that quietly degrades the very tasks this was supposed to help with.</p> A Bit of Research Backing</h2> This idea borrows from existing work rather than inventing everything from scratch:</p> 500xCompressor: Generalized Prompt Compression for Large Language Models</strong> Shows that prompts are highly compressible</strong> (6×–480×) by learning a compressed “language” while retaining 62–73% of task performance. Key takeaways:</p> Prompts contain a lot of low-information redundancy.</li> You can compress aggressively if you protect information-bearing tokens. → 500xCompressor: Generalized Prompt Compression for Large Language Models</a></li> </ul> </li> NAACL 2025 survey on prompt compression</strong> Surveys extractive vs. abstractive compression and token-pruning strategies, emphasizing:</p> trade-offs between compression ratio and task fidelity,</li> the importance of preserving structure for technical prompts. → NAACL 2025 prompt compression survey (PDF)</a></li> </ul> </li> Factory.ai – “Compressing Context”</strong> Describes a production-ready strategy for incremental, anchored summaries</strong>:</p> maintain a persistent conversation state,</li> compress only the span that’s about to fall out of context,</li> avoid repeatedly re-summarizing old history. → Factory.ai: “Compressing Context”</a></li> </ul> </li> </ul> Where Hieratic diverges is in deliberately not</strong> adding another model to the loop. The goal is a deterministic, rule-based compressor that plays nicely with structured prompts and long-running pipelines.</p> Rough Shape of the System</h2> Here’s the high-level architecture I’m exploring.</p> 1. Split instructions vs document</h3> Before we drop any tokens:</p> Instruction block</strong>: natural-language instructions and commentary.</li> Document block</strong>: structured tables, JSON payloads, grammars, etc.</li> </ul> Only the instruction block is compressed.</strong> Document blocks are treated as verbatim</strong> and left untouched.</p> 2. Pattern extraction & context library (optional)</h3> Given a corpus of prompts, a pattern extractor:</p> scans for frequently repeated fragments</strong> (boilerplate instructions, shared scaffolding),</li> builds a reusable context library</strong>,</li> allows future prompts to reference those snippets instead of inlining them.</li> </ul> This is similar in spirit to a learned codebook (as in research like 500xCompressor), but done in a deterministic, human-auditable way.</p> 3. Extractive compression over instruction blocks</h3> For instruction text, the compressor:</p> Sets a token budget</strong> based on a compression level (Light</code>, Medium</code>, Aggressive</code>) or explicit target ratio.</li> Segments text using structure-aware heuristics: headings (#</code>, ##</code>),</li> “Definition:”, “Location:”, “Response Format:” markers,</li> parameter blocks (Extracted_Value</code>, Doc_Page_Number</code>, etc.).</li> </ul> </li> Scores segments such that: hard constraints and response formats are hard-kept</strong>,</li> explanatory text and examples are more compressible.</li> </ul> </li> Implements a greedy selection: keep highest-scoring segments until the budget is spent.</li> </ul> The intent is to preserve the “spine” of the instructions while trimming repetition and soft context.</p> 4. Encode as a Hieratic prompt</h3> The compressed result is organized into a Hieratic</strong> structure, with sections like:</p> @ROLE</code> – who the model is supposed to be,</li> @TASK</code> – what it’s supposed to do,</li> @FOCUS</code> – which fields / behaviors matter most,</li> @EXAMPLES</code> – optionally compressed or referenced,</li> @RECENT</code> – most recent interaction span,</li> @ANCHOR[...]</code> – anchored summaries of older context.</li> </ul> It’s essentially a compact, structured representation of your original prompt.</p> 5. Incremental mode for long histories</h3> In incremental mode, the compressor:</p> loads a previous compression state,</li> identifies the “oldest” span that’s about to be evicted from context,</li> compresses that span into a new @ANCHOR[...]</code>,</li> keeps the most recent N tokens uncompressed.</li> </ul> Over time, you get a stack of anchors plus a fresh @RECENT</code> tail, keeping context current without growing linearly with the full history.</p> What I’d Love Feedback On</h2> This is the experimental part. I’d love to hear from people who:</p> run LLMs in production with big prompts,</li> have tried prompt compression in anger,</li> or have opinions on where this kind of feature should live in a system like Tokuin.</li> </ul> A few specific questions:</p> Evaluation</strong></p> How would you design a real</em> benchmark for this?</li> Which tasks / datasets would you use to prove that we’re not quietly breaking critical behaviors?</li> </ul> </li> Failure modes</strong></p> Where have compression strategies bitten you before?</li> Are there patterns or structures you’d mark as “never compress this”?</li> </ul> </li> Integration into a stack like Tokuin</strong></p> At what layer would you expect to see a feature like this? Right before the LLM call?</li> As part of a prompt-building pipeline?</li> As a standalone preprocessor with its own cache?</li> </ul> </li> </ul> </li> Alternatives & trade-offs</strong></p> Would you lean towards learned compressors instead?</li> Are there simpler heuristics that get most of the benefit without this level of complexity?</li> </ul> </li> Product shaping</strong></p> Should this live as: a first-class Tokuin feature,</li> an “experimental / power user” option,</li> or a separate library that Tokuin can plug into?</li> </ul> </li> </ul> </li> </ol> If you have opinions—positive or negative—I’d genuinely appreciate hearing them.</p> How This Fits Into Tokuin (Right Now)</h2> As of today, Hieratic Prompt Compression is experimental and aspirational</strong>:</p> It’s being explored as a potential feature for Tokuin</strong>, not a locked-in roadmap item.</li> Any implementation will start as: an opt-in, feature-flagged module,</li> with clear disclaimers about the risks,</li> and tooling to inspect exactly what was compressed.</li> </ul> </li> </ul> Long term, if the idea survives scrutiny, I could imagine:</p> per-project compression profiles</strong>,</li> UI/CLI tools for inspecting “before vs after” prompts,</li> and tighter integration with context management and retrieval strategies.</li> </ul> But we’re not there yet. For now, I’m trying to answer a simpler question:</p> Can a Hieratic-style, rule-based compressor earn its place inside Tokuin, or should we keep prompts uncompressed and invest elsewhere?</strong></p> </blockquote> If you’ve navigated similar trade-offs—or you’re just curious and want to poke holes in this idea—I’d love to hear from you.</p> References</h2> 500xCompressor: Generalized Prompt Compression for Large Language Models</strong> https://arxiv.org/abs/2408.03094</a></p> </li> NAACL 2025 Prompt Compression Survey</strong> https://aclanthology.org/2025.naacl-long.368.pdf</a></p> </li> Factory.ai – “Compressing Context”</strong> https://factory.ai/news/compressing-context</a></p> </li> </ul> Tokuin: Token Intelligence for LLM Developers 2025-11-07T00:00:00+00:00 I built Tokuin</a> because the tooling around prompt design still feels like guesswork. We scribble system prompts in scratchpads, retry endpoints until rate limits scream, and only know what the bill looks like after the invoice arrives. Tokuin changes that. It gives you reliable token estimates, cost projections, and synthetic load tests</strong>—all packaged in a Rust CLI you can trust.</p> Why Another CLI?</h2> Prompts have become product surfaces. Teams iterate on them like code, but the support tooling still feels like duct tape. I wanted something that:</p> Reads prompts from files, stdin, or watch mode</li> Targets multiple providers without juggling SDKs</li> Surfaces pricing before you ever hit “Send”</li> Scales up to load tests when you need to know how a model behaves across 1,000 requests</li> </ul> Tokuin is the result: a ground-up build in Rust</strong> with a modular architecture for tokenizers, providers, and output formats. It’s fast, predictable, and stays out of your way while you experiment.</p> Feature Highlights</h2> Token estimation that understands context</strong>: Supply raw text, chat transcripts, or JSON payloads and Tokuin breaks down system/user/assistant roles with optional markdown minification.</li> Multi-model comparisons</strong>: Pass --compare</code> with OpenAI, Anthropic, or OpenRouter models to see how token counts and costs differ.</li> Pricing awareness</strong>: Add --price</code> or --estimate-cost</code> to forecast spend per prompt, per run, or across a load test.</li> Watch mode</strong>: Keep Tokuin running with --watch</code> and it re-computes every time you save a file. Perfect for prompt gardening.</li> Load testing (feature flag)</strong>: Enable the load-test</code> feature to hammer APIs with controlled concurrency, think times, retry logic, and automatic latency/cost reports.</li> Format-flexible output</strong>: Emit human-friendly text, JSON for scripts, Markdown for docs, CSV for spreadsheets, or Prometheus metrics when you need dashboards.</li> Provider-ready</strong>: OpenAI and OpenRouter work out of the box, Gemini is one flag away, and new providers plug into the registry without rewriting the CLI surface.1</a></sup></li> </ul> ^1</sup>Feature set sourced from the project README.tokuin</a></p> </div> Advantages for Developers</h2> Budget confidence</strong>: Know input/output token counts and projected cost before you ship or run a batch job.</li> Faster iteration</strong>: Swap “test, wait, pray” with a tight loop; piping prompts through Tokuin becomes muscle memory.</li> CI-friendly</strong>: Because it’s a single binary, you can run token checks in CI to guard against prompt bloat before merge.</li> Team alignment</strong>: Comparing multiple models is now a line of CLI flags, not a spreadsheet of stitched-together data.</li> Infra visibility</strong>: Load tests surface latency cliffs, provider throttling, and cost ceilings before your users do.</li> </ul> Built for Growth</h2> Tokuin ships with a modular core: tokenizers/</code>, models/</code>, providers/</code>, and output/</code> live in separate crates so we can grow the ecosystem without tangling the CLI.1</a></sup> Near-term roadmap items include:</p> Provider expansion</strong>: Native Anthropic, Mistral, and Cohere support (work already outlined in PROVIDERS_PLAN.md</code>).</li> Scenario scripts</strong>: Define multi-turn conversations and replay them in load tests.</li> Cost guardrails</strong>: Abort long runs automatically when reaching a user-defined budget ceiling.</li> Prompt linting</strong>: Surface style and structure issues before they hit production pipelines.</li> Plugin hooks</strong>: Let users contribute tokenizers or pricing sources without forking the repo.</li> </ol> From Experiment to Community Tooling</h2> Tokuin grew out of practical late-night benchmarking, budget vetting, and the need for predictable tooling across teams. We still welcome that vibe-coding energy—if you sketch solutions with AI co-pilots or riff on ideas in flow, there’s room here to help shape how we build for LLMs.</p> How to Get Involved</h3> Run it</strong>: cargo install tokuin</code> or build from source and kick the tires.</li> Share prompts</strong>: If you discover funky edge cases in tokenization or pricing, capture them as regression fixtures.</li> Open a PR</strong>: Contributions are welcome whether you’re adding providers, tightening error messages, or documenting workflows. Mention any vibe-coding sessions in your PR so we can trace the creative path.</li> Join the roadmap</strong>: Drop ideas in issues, especially if you’re working on multi-provider tooling—the more weird setups we test, the better Tokuin gets.</li> </ul> Thanks for trying it out. Tokuin exists to remove guesswork, save budgets, and let prompt engineers stay in flow. If you ship something with it, I’d love to hear the story.</p> mock: Build APIs with Shell Scripts, Not Frameworks 2025-11-05T00:00:00+00:00 Sometimes you need an API endpoint fast. Not a full framework, not a production service, just something that responds to HTTP requests. mock</a> is exactly that—a lightweight tool that turns shell scripts into HTTP endpoints.</p> The Concept</h2> Instead of spinning up Express, Flask, or any other framework, mock lets you define endpoints with simple shell scripts:</p> $</span> mock serve \ </span> --route </span>"</span>/users</span>" \ </span> --method </span>"</span>GET</span>" \ </span> --shell-script </span>'</span>get_users.sh</span>' </span></code></pre> Your shell script becomes the response handler. Inside it, you use mock's utilities to build HTTP responses: mock write</code> to send data, mock set-header</code> to add headers, and access to the full shell environment.</p> Why This Matters</h2> This approach shines for:</p> Prototyping</strong>: Mock external APIs you're integrating with</li> Testing</strong>: Create test fixtures without setting up databases</li> Quick integrations</strong>: Bridge gaps between services using familiar shell tools</li> DevOps scripts</strong>: Expose your automation scripts as HTTP endpoints</li> </ul> You get all the power of shell (grep</code>, awk</code>, curl</code>, databases, file systems) wrapped in HTTP. No dependencies beyond what's already on your system.</p> The Details</h2> Mock supports JSON config files or command-line parameters. You can set response headers, status codes, route parameters, conditional responses, and even serve static files. It's comprehensive enough for complex scenarios while staying dead simple.</p> If you've ever thought "I wish I could just write a bash script and expose it as an API," mock is that tool.</p> Documentation</strong>: dhuan.github.io/mock</a></p> Java vs Rust: A ROUGE-L Performance Comparison 2025-11-02T00:00:00+00:00 The Experiment</h3> I was curious about the performance differences between Java and Rust for a specific workload. So I built identical ROUGE-L implementations in both languages and ran some benchmarks. The code was AI-generated, the algorithm was the same, and the results were mathematically equivalent. But the performance? That's where it gets interesting.</p> What is ROUGE-L?</h3> ROUGE-L (Recall-Oriented Understudy for Gisting Evaluation - Longest Common Subsequence) is a metric used to evaluate text summarization quality. It's part of the ROUGE evaluation suite</a> developed by Chin-Yew Lin in 2004, which has become a standard in natural language processing for assessing how well generated summaries match reference summaries.</p> How it works:</strong></p> ROUGE-L measures similarity based on the Longest Common Subsequence (LCS) between sequences of words. It calculates three metrics:</p> Precision</strong>: LCS / (number of words in candidate summary)</li> Recall</strong>: LCS / (number of words in reference summary)</li> F-Measure</strong>: 2 × (Precision × Recall) / (Precision + Recall)</li> </ul> The algorithm uses dynamic programming with O(m × n) time complexity, where m and n are the lengths of the two sequences. It's a straightforward implementation, which makes it a good candidate for comparing language performance.</p> ROUGE-L is particularly useful because it doesn't require exact word matches—it finds the longest sequence of words that appear in the same order in both texts, making it more flexible than n-gram overlap methods like ROUGE-1 or ROUGE-2.</p> The Setup</h3> Both implementations:</p> Use the same dynamic programming algorithm for LCS calculation</li> Tokenize text the same way (lowercase, whitespace-based splitting)</li> Handle the same 16 test examples across 6 complexity levels</li> Produce identical mathematical results</li> </ul> The only difference is the language they're written in.</p> Test scenarios include:</strong></p> Basic text comparisons</li> Structured data (JSON, HTML)</li> Mixed content with embedded structures</li> Real-world technical documentation</li> </ul> You can find the full comparison project on GitHub</a>.</p> The Results</h3> Accuracy:</strong> Both implementations produced 100% identical results</strong> across all 16 test cases. Every F-Measure, Precision, and Recall value matched perfectly. This confirms the algorithms are mathematically equivalent.</p> Performance:</strong> That's where things get interesting.</p> After multiple benchmark runs with 10 iterations each:</p> Java:</strong></p> Average: 52-62ms per run</li> Median: 51-61ms</li> Standard deviation: 1.5-13ms (relatively consistent)</li> Includes JVM startup time in every run</li> Performance stabilizes quickly after first iteration</li> </ul> Rust:</strong></p> Average: 21-40ms (heavily skewed by first cold start)</li> Median: 2.5-4ms (after warmup)</li> First iteration: 190-360ms (cold start overhead including compilation)</li> Warm average: 2.4-4.4ms (excluding first run)</li> Standard deviation: 60-115ms (largely due to cold start variability)</li> </ul> The speedup:</strong> After warmup, Rust was consistently 12-25x faster</strong> than Java for this workload. For example, in one run: Java median 56.66ms vs Rust warm average 2.50ms = 24.76x speedup</strong>. The median Rust time (2.5-3ms) versus Java's median (52-56ms) tells the story.</p> What This Means</h3> For Java:</strong></p> JVM startup adds significant overhead (~50-60ms)</li> Once running, performance is consistent</li> The runtime environment is predictable but has a fixed cost</li> </ul> For Rust:</strong></p> Cold start includes compilation/optimization overhead (~200-350ms)</li> Once warmed up, execution is extremely fast (~2.5-3ms)</li> Compiled binary runs without runtime interpretation overhead</li> </ul> The reality:</strong> In production, both would run with warmup periods. Java would maintain its ~55ms average. Rust would settle into its ~2.5-3ms sweet spot. The performance difference would still be substantial.</p> Observations</h3> Tradeoffs:</strong></p> Startup time:</strong> Java has consistent startup overhead. Rust has a larger initial cold start but negligible warm overhead.</p> </li> Consistency:</strong> Java's performance is more predictable from run to run. Rust's cold start variability makes early measurements misleading.</p> </li> Warm performance:</strong> Once both are warmed up, Rust's compiled nature provides significant advantages for CPU-bound work.</p> </li> Ecosystem:</strong> Java has mature NLP libraries. Rust has growing ecosystem support. For this isolated algorithm, both worked well.</p> </li> </ol> The "just for fun" part:</strong></p> This was an experiment. I wanted to see what would happen if you took the same algorithm, implemented it identically in two languages, and compared performance. The answer: same results, dramatically different performance characteristics.</p> Why This Matters</h3> For production systems evaluating summarization quality:</p> Throughput matters:</strong> Processing thousands of summaries per second benefits from Rust's speed</li> Latency matters:</strong> If this runs in a request path, 2.5ms vs 55ms is significant</li> Infrastructure matters:</strong> Java's JVM ecosystem vs Rust's compiled binary have different deployment considerations</li> </ul> Neither is "better" in absolute terms. They have different tradeoffs. Understanding those tradeoffs is what matters.</p> References</h3> Lin, C.-Y. (2004). ROUGE: A Package for Automatic Evaluation of Summaries</a> - The original paper introducing ROUGE metrics</li> ROUGE Metrics Documentation</a> - Wikipedia overview of ROUGE evaluation metrics</li> Comparison Project on GitHub</a> - Full source code and benchmarks</li> </ul> The code is available on GitHub</a> if you want to run your own benchmarks. Same algorithm, same results, different performance characteristics. Sometimes the fun experiments teach you the most.</p> What Happens When Prototypes Try to Go to Production 2025-11-02T00:00:00+00:00 The Conversation</h3> You've built a production-ready AI system with proper architecture, traceability, and acceptable latency. Then someone suggests "why not just use a prompt?"</p> You don't need to explain why that won't work. The industry has already documented what happens when prototypes become production.</p> Why Not Just Give an Opinion?</h3> There's a temptation to push back when surface-level decisions ignore architecture, scalability, edge cases, and maintainability. But opinions based on current trends or individual preferences don't help. They just add noise.</p> The current landscape is filled with quick takes and hot takes. Everyone has an opinion, often shaped more by what's trending than by systematic thinking. Narcissistic individualism—the idea that one person's perspective matters more than collective experience—creates an environment where strong opinions win even when they're wrong.</p> The problem isn't trends themselves. It's choosing tools or approaches because they're trending, rather than because they solve real problems. The distinction matters.</p> Research and data exist. Patterns repeat. The industry has documented what works and what doesn't. Why add another opinion when we can point to what's already been proven?</p> That's why this isn't about pushing back with opinions. It's about pointing to what the industry already knows: prototypes that skip architecture rarely become production systems. The data is public. The patterns are clear.</p> The Statistics</h3> According to recent research, 87% of machine learning models never make it past the prototype stage</strong>. Reasons include technical debt, edge cases that break everything, scale issues, and maintainability collapses.</p> Why "Just a Prompt" Rarely Works</h3> When you build a direct LLM solution, you're coding logic into prompts. This creates brittleness—small changes require rewriting entire prompts. It's impossible to debug—you can't see intermediate steps. And there's no observability—production needs monitoring, logging, and metrics that a single prompt can't provide.</p> What Actually Ships</h3> AI systems that reach production are rarely "just a prompt." They have structured workflows, error handling, observability, modularity, and scalability. These frameworks and architectures exist because production systems need structure—not because they're trendy, but because they solve real problems that prototypes ignore.</p> The Numbers Don't Lie</h3> Gartner</a>: Over 80% of organizations will struggle to operationalize AI systems by 2026</li> MIT Sloan</a>: 85% experiment with AI, but only 37% deploy at scale</li> Harvard Business Review</a>: "Failure to move beyond proof of concept" is the primary cause of AI failures</li> </ul> Architecture matters.</strong> Prototypes skip it. Production requires it.</p> The Hard Truth</h3> There's a mismatch between demos and production. Prototypes optimize for speed. Production optimizes for reliability, scalability, and maintainability.</p> The question isn't whether your prototype works. It's whether it works when you have 100x more users, need unanticipated features, or an edge case breaks everything.</p> Prototypes optimize for the first week. Production systems need to survive years.</p> Sometimes the most important lessons are the ones you learn before you make the mistake.</em></p> The Zola About Page Puzzle: When Root Sections Bite Back 2025-11-02T00:00:00+00:00 The Goal</h3> I wanted to add an About page to my blog. Simple enough, right? Create content/about.md</code>, add it to the navigation menu, and done.</p> Wrong.</p> The Problem</h3> I created the About page, updated the navigation, and ran zola build</code>. Instead of a clean build, I got this:</p> Warning: 1 page(s) ignored (missing date or weight in a sorted section): </span>Warning: - /Users/oshadhagunawardena/Projects/personal/personal-blog/content/about.md </span></code></pre> The page wasn't being built at all. But wait—why does an About page need a date? It's not a blog post.</p> The Investigation</h3> The issue was in my content/_index.md</code> file:</p> +++</span> </span>title </span>= "</span>Home</span>" </span>paginate_by </span>= </span>5 </span>sort_by </span>= "</span>date</span>" </span>transparent </span>= </span>true </span>template </span>= "</span>index.html</span>" </span>+++</span> </span></code></pre> See that sort_by = "date"</code>? That was the culprit. According to Zola's documentation</a>, when you set sort_by = "date"</code> in a section's front matter, all pages in that section</strong> must have a date field. Pages without the required field are ignored during rendering and a warning is displayed.</p> This is documented behavior, but it's easy to miss when you're just trying to add a simple About page.</p> The Solution</h3> The fix had two parts:</p> Step 1</strong>: Add a date</code> field to the About page. Since the root section uses sort_by = "date"</code>, all pages need a date—even non-post pages.</p> Step 2</strong>: Hide the date from displaying on the About page using show_date = false</code> in the front matter.</p> Before:</strong></p> +++</span> </span>title </span>= "</span>About</span>" </span>description </span>= "</span>Learn about Oshadha G...</span>" </span>template </span>= "</span>page.html</span>" </span>weight </span>= </span>1 </span>[extra] </span>hide_from_list </span>= </span>true </span>comments </span>= </span>false </span>+++</span> </span></code></pre> After:</strong></p> +++</span> </span>title </span>= "</span>About</span>" </span>description </span>= "</span>Learn about Oshadha G...</span>" </span>template </span>= "</span>page.html</span>" </span>date </span>= </span>2025-01-01 </span># Required because root section uses sort_by = "date" </span>weight </span>= </span>1 </span>[extra] </span>hide_from_list </span>= </span>true </span>comments </span>= </span>false </span>show_date </span>= </span>false </span># Hide the awkward date from displaying </span>+++</span> </span></code></pre> I also had to create a custom templates/macros/post_macros.html</code> to override the theme's default meta macro and respect the show_date</code> flag. But the front matter solution is the important part.</p> Now the About page builds correctly, appears in the correct order for pagination, but doesn't display the awkward "Published: 2025-01-01" meta.</p> The Lesson</h3> Root-level sections in Zola behave differently than you might think. If you set sort_by = "date"</code> in a section, all</strong> pages in that section must have a date field—even non-post pages like About pages.</p> While Zola's docs mention this behavior, it's the kind of detail that's easy to gloss over when you're focused on building features. The solution is straightforward:</p> Give every page a date if your section sorts by date (I use 2025-01-01</code> for static pages)</li> Use a custom macro override to conditionally hide dates where they don't make sense</li> </ol> For static pages like About, seeing "Published: 2025-01-01" is awkward, so the show_date = false</code> flag was essential.</p> Quick Check</h3> If you're having similar issues with Zola pages not building:</p> Check your section's _index.md</code> for sort_by</code> directives</li> Make sure all pages in that section have the required fields</li> Use show_date = false</code> in front matter if you want to hide dates on static pages</li> Consider moving sorted content to a dedicated subsection</li> </ol> Sometimes the simplest fixes are the most unexpected. And sometimes you need two fixes instead of one.</p> Rust Macros vs Functions: What Java and Python Developers Should Know 2025-11-01T00:00:00+00:00 The Question</h3> When you first start with Rust, one thing that throws you off is the difference between macros and functions. Coming from Java or Python, this seems odd—why would you need both?</p> What's the Difference?</h3> Here's the simplest explanation: functions work on data, macros work on code</strong>.</p> In Python, you write:</p> def </span>add</span>(</span>a</span>, </span>b</span>): </span> </span>return </span>a + b </span></code></pre> In Java, you write:</p> public static int </span>add</span>(</span>int</span> a, </span>int</span> b) { </span> </span>return</span> a + b; </span>} </span></code></pre> Both run at runtime</strong>—when your program executes.</p> But in Rust, macros run at compile time</strong>—before your code is even compiled. They're code that writes code.</p> A Simple Example</h3> Function in Rust:</strong></p> fn </span>add</span>(</span>x</span>: </span>i32</span>, </span>y</span>: </span>i32</span>) -> </span>i32 </span>{ </span> x + y </span>} </span></code></pre> Macro in Rust:</strong></p> macro_rules! </span>add { </span> (</span>$x</span>:</span>expr</span>, </span>$y</span>:</span>expr</span>) => { </span> </span>$x </span>+ </span>$y </span> }; </span>} </span></code></pre> When you call the macro add!(1, 2)</code>, the compiler literally rewrites your code to 1 + 2</code> before compiling. It's like a smart find-and-replace.</p> Why Not Just Use Functions?</h3> Macros solve problems that functions can't:</p> 1. Variable Arguments</strong></p> Ever wonder how println!</code> can take any number of arguments?</p> println!("</span>Hello</span>"); </span>println!("</span>Hello </span>{}</span>", name); </span>println!("</span>{}</span> and </span>{}</span>", a, b); </span></code></pre> That's because it's a macro. Functions need fixed signatures; macros can accept variable patterns.</p> 2. Code Generation</strong></p> Python has decorators like @dataclass</code> that generate code for you:</p> @</span>dataclass </span>class </span>Person</span>: </span> name: str </span> age: int </span></code></pre> Java has annotations like @Override</code> or Lombok's @Builder</code>.</p> In Rust, this is done with macros:</p> #[</span>derive</span>(Debug, Clone)] </span>struct </span>Person { </span> </span>name</span>: String, </span> </span>age</span>: </span>u32</span>, </span>} </span></code></pre> The derive</code> macro generates Debug</code> and Clone</code> implementations automatically.</p> 3. Domain-Specific Languages (DSL)</strong></p> A DSL is a miniature language tailored to a specific problem domain. Think of SQL—it's not a general-purpose language, but a specialized one for databases.</p> You can create custom syntax with macros:</p> html! { </span> <div class="</span>container</span>"> </span> <p>Hello world<</span>/</span>p> </span> </div> </span>} </span></code></pre> This isn't valid Rust code—it's an HTML-like DSL that the macro converts into valid Rust. It lets you write HTML templates directly in your Rust code, which the macro transforms into function calls and data structures at compile time.</p> Mental Model for Java/Python Developers</h3> Concept</th> Python/Java</th> Rust</th></tr></thead> Function</td> Normal code that runs</td> Same—runs at runtime</td></tr> Annotation/Decorator</td> @Override</code>, @dataclass</code></td> #[derive(...)]</code> macro</td></tr> Macro</td> Doesn't really exist</td> Generates code at compile time</td></tr> </tbody></table> Think of macros as super-powered annotations</strong>. In Java, annotations can generate some code (like Lombok does), but macros can generate any</em> code.</p> When to Use What?</h3> Use functions</strong> for normal logic and calculations.</li> Use macros</strong> when you want to avoid boilerplate, create custom syntax, or generate code automatically.</li> </ul> Bottom Line</h3> Macros are Rust's way of reducing repetition and enabling metaprogramming. They run before compilation and rewrite your code. If you're coming from Java or Python, think of them as annotations or decorators on steroids—but they can do much more.</p> For most beginners, you don't need to write macros. The standard library macros like println!</code>, vec!</code>, and format!</code> will carry you far. But understanding what</em> they are helps when you read Rust code and wonder why you see !</code> everywhere.</p> Further Reading</h3> The Little Book of Rust Macros</a> — A practical guide to writing macros in Rust.</li> The Rust Programming Language: Macros</a> — Official Rust book chapter on macros.</li> Rust by Example: Macros</a> — Interactive examples to learn macros.</li> Domain-Specific Language (DSL)</a> — Wikipedia article explaining the concept.</li> </ul> Covers on Autopilot — Why I Let AI Paint the Edges 2025-10-30T00:00:00+00:00 There are jobs you can do by hand for years and never notice the drag. For me it was cover images. Each new post: open a design tool, stare at a blank canvas, export a PNG, wire it to the post. Not hard, just enough friction to make publishing feel heavier than it should.</p> This is a short note about shaving that yak with a tiny toolchain: a context‑aware prompt, an image model, and some guardrails in CI. No heroics—just removing a repeated decision so the writing flows.</p> Why automate covers</h2> Consistency: 1200×630 every time. No more odd crops in link unfurls.</li> Momentum: publishing shouldn’t wait for “design time”.</li> Style: light background, a single accent, abstract shapes. Enough personality, zero fuss.</li> </ul> Over time the manual step was turning into a speed bump. That was the whole motivation.</p> The bumps along the road (the important part)</h2> I didn’t get it right on the first try. Here are the lessons that actually mattered.</p> Model and limits</li> </ol> At first I used Stable Horde for SDXL. It’s great and free, but CI doesn’t love queues. I kept seeing 400/429s in the logs (invalid payload or rate‑limited). Switched to Replicate with an API token; still got rate limits sometimes, but at least the errors were predictable.</p> Exact sizing</li> </ol> SDXL likes multiples of 64. I request 1024×576, then downscale to 1200×630 with Sharp. Crisp edges, correct aspect for social cards.</p> Slugs vs. filenames</li> </ol> My fallback logic assumed page.slug</code> exactly matched the filename. It didn’t—some posts derive the slug from the permalink. I fixed the template to compute slug-from-permalink</code> and look for /images/covers/{slug}.png</code>. Simple, but that bug cost the most time.</p> “Why is it regenerating?”</li> </ol> CI starts from a clean checkout. If covers aren’t in Git, they disappear each run. I added a cache step that restores static/images/covers</code> keyed to content/posts/*/.md</code>. Now the generator truly skips when a PNG already exists.</p> Context in prompts</li> </ol> Pure tags produced vague images. I added a little context: title + ~240 chars of summary (description if present, otherwise a clean slice of the body). Still abstract, just more grounded.</p> One‑time resets</li> </ol> Sometimes you do want a full refresh. There’s a manual “Run workflow” input (force_regenerate=true</code>) that bypasses the “file exists” check once. Good for style changes or a model upgrade.</p> How we decided on AI at all</h2> I tried three options in order:</p> Hand‑made banners (historically): high quality, low velocity.</li> Programmatic shapes: reliable, but too repetitive.</li> AI with guardrails: abstract, brand‑aware, hands‑off once it’s set.</li> </ul> The third option hit the balance. The prompt constrains style; the model supplies variation. It’s not “art direction”, but it serves the post—and that’s the only job here.</p> The pipeline (nuts and bolts)</h2> Script: scripts/generate-ai-covers.mjs</code></p> Scans content/posts/.md</code>, pulls tags</code>, title</code>, and a short summary.</li> Prompt (simplified): Abstract, minimal illustration. Tags: {tags}. Title: {title}. Context: {summary}. Vector‑like, clean geometric shapes, high contrast, brand accent #d64a48 on #f6f7f4. No text.</p> </blockquote> </li> Calls Replicate SDXL (model version from a secret), requests 1024×576, saves 1200×630 as static/images/covers/{slug}.png</code>.</li> Skips generation if the PNG already exists (unless FORCE_REGENERATE_COVERS=1</code>).</li> </ul> </li> Template: themes/radion/templates/page.html</code></p> If a post doesn’t specify a cover, it tries /images/covers/{slug-from-permalink}.png</code> and hides the figure if missing.</li> </ul> </li> CI: .github/workflows/deploy.yml</code></p> Restores a covers cache before generation; saves it after.</li> Optional manual input force_regenerate</code> for a one‑time refresh.</li> </ul> </li> </ul> What GitHub Actions brings</h2> The boring kind of power: reliability.</p> Every run restores the previous covers, generates only what’s missing, and embeds without a front‑matter tweak.</li> When rate‑limited, the post still publishes—missing images pick up on the next run.</li> A small verification stage lists the covers in public/images/covers</code> and checks that posts actually reference them.</li> </ul> Closing the loop</h2> This wasn’t about making the site “AI‑powered”. It was about removing a tiny friction point that kept breaking the flow. The rule of thumb I keep coming back to: automate anything that steals attention from writing. Covers were stealing attention. Now they aren’t.</p> And if the art ever needs a new feel? I flip the model or tweak the prompt, hit “Run workflow”, and let the pipeline repaint the edges while I get back to words.</p> Redis, TLS, and Deadpool: When Dependency Versions Collide 2025-10-30T00:00:00+00:00 The Problem</h3> I was working on a Rust project that uses Redis with TLS connections and a connection pool via deadpool-redis</code>. Everything was working fine until I ran cargo check</code> and saw this warning:</p> warning: the following packages contain code that will be rejected by a future version of Rust: redis v0.25.4 </span></code></pre> That's not something you want to see. It suggests your code will break in future Rust versions. So naturally, I tried to upgrade the redis</code> crate to a newer version.</p> But here's where things got interesting—every single attempt to upgrade past v0.25.4</code> broke the build. Not just small errors, but fundamental incompatibilities between the redis</code> crate and deadpool-redis</code>.</p> What I Tried</h3> I went through the versions systematically, testing each major release:</p> v0.26.x</strong>: Broke immediately. Missing TcpTls</code> variant in the Tokio</code> enum, internal TLS types incomplete.</li> v0.27.x</strong>: Same issues as v0.26.x. TLS support partially broken.</li> v0.28.x</strong>: TLS types like TlsConnParams</code> and TcpTls</code> were still broken internally.</li> v0.29.x</strong>: Now it requires a connect_tcp_tls</code> trait that deadpool-redis</code> doesn't implement.</li> v0.30.x, v0.31.x, v0.32.x</strong>: All require the same connect_tcp_tls</code> trait.</li> </ul> The pattern became clear: somewhere between v0.25.4 and v0.29.0, the redis</code> crate changed how it handles TLS connections, and deadpool-redis</code> hasn't caught up yet.</p> The Root Cause</h3> The issue is that redis</code> v0.25.4 is the last version before connect_tcp_tls</code> was introduced. This new trait-based approach is cleaner architecturally, but it requires connection pool libraries to implement this trait. deadpool-redis</code> v0.14.0 was built against the older API and doesn't have this implementation.</p> Versions between v0.25.4 and v0.29.0 are in a transitional state—they have some TLS support but it's incomplete or broken.</p> Current Status</h3> After testing all these versions, I ended up staying with redis v0.25.4</code>. Here's the working configuration:</p> Cargo.toml:</strong></p> [dependencies] </span>redis </span>= { </span>version </span>= "</span>=0.25.4</span>", </span>features </span>= ["</span>tokio-comp</span>", "</span>tls-rustls</span>", "</span>connection-manager</span>"] } </span>deadpool-redis </span>= "</span>0.14.0</span>" </span>tokio </span>= { </span>version </span>= "</span>1</span>", </span>features </span>= ["</span>full</span>"] } </span>tokio-rustls </span>= "</span>0.23.4</span>" </span>rustls </span>= "</span>0.20.8</span>" </span></code></pre> rust-toolchain.toml:</strong></p> [toolchain] </span>channel </span>= "</span>1.74.1</span>" </span></code></pre> The =</code> prefix on the redis version pins it exactly to v0.25.4, preventing accidental upgrades. And pinning Rust to 1.74.1</code> helps avoid future compatibility warnings.</p> This setup works reliably:</p> TLS over rediss://</code> connections work with tokio-rustls</code></li> Connection pooling via deadpool-redis</code> functions correctly</li> No compilation warnings or errors</li> Stable and predictable behavior</li> </ul> What to Avoid</h3> If you're in a similar situation, avoid these version combinations:</p> redis v0.26.x–v0.28.x</strong>: TLS support is broken or incomplete. You'll get compilation errors related to missing enum variants or broken TLS types.</li> redis >= v0.29.0 with deadpool-redis</strong>: Won't compile because deadpool-redis</code> doesn't implement the required connect_tcp_tls</code> trait.</li> deadpool-redis v0.15+</strong>: Currently not compatible with stable redis</code> versions due to the same trait mismatch.</li> </ul> Alternative Approach</h3> If you really need a newer redis</code> version, you have one option: drop deadpool-redis</code> and use redis</code>'s built-in ConnectionManager</code> or switch to a different pooling library like bb8</code>. But this means rewriting your connection pool code, which might not be worth it for most projects.</p> The Future</h3> The situation is temporary, but it's unclear when it will be resolved. The deadpool-redis</code> maintainers need to either:</p> Implement the connect_tcp_tls</code> trait for newer redis</code> versions, or</li> Update their API to work with the new connection model</li> </ol> Until then, staying with redis v0.25.4</code> and deadpool-redis v0.14.0</code> is the most stable path forward. Yes, you'll see that deprecation warning, but it's better than having broken code.</p> Bottom Line</h3> Sometimes upgrading dependencies isn't the right move. In this case, the ecosystem has a compatibility gap between redis</code> and deadpool-redis</code>, and staying on the older version is the pragmatic choice. The warning is annoying, but it's not breaking anything right now—and when the ecosystem catches up, you can upgrade then.</p> If you're building a new project and need Redis with TLS and pooling, consider whether you can use redis</code>'s built-in ConnectionManager</code> instead of deadpool-redis</code>. If you're maintaining an existing project, stick with what works: redis v0.25.4</code> and deadpool-redis v0.14.0</code>.</p> When Rust Expects a String But Gets a Map 2025-10-29T00:00:00+00:00 I recently hit this error while working with a Rust application that reads from a database:</p> Database("Kind: invalid type: map, expected an RFC 3339 formatted date and time string, labels: {}") </span></code></pre> At first glance, it's a bit cryptic. But the error message actually tells you exactly what's wrong.</p> The Problem</h2> When you have a Rust struct with a DateTime<Utc></code> field, Serde expects the JSON to contain an RFC 3339 formatted string like:</p> "</span>2025-09-15T01:36:19Z</span>" </span></code></pre> But instead, your database (or JSON source) is storing it as a map/object:</p> { </span> "</span>sec</span>": </span>1694733379</span>, </span> "</span>nsec</span>": </span>199610000 </span>} </span></code></pre> Serde can't automatically convert a map into a DateTime</code>—it needs a string it can parse.</p> Why This Happens</h2> Different systems store timestamps differently:</p> Some databases store timestamps as Unix time objects with separate seconds and nanoseconds</li> Some JSON APIs return timestamps as nested objects</li> Other sources might use different date formats</li> </ul> But Rust's DateTime<Utc></code> with Serde defaults expects the standard RFC 3339 string format.</p> The Fix</h2> You have two options:</p> Option 1: Fix the data source</strong> (if you control it) Make sure your database or JSON source stores timestamps as RFC 3339 strings:</p> "</span>created_at</span>": "</span>2025-09-15T01:36:19Z</span>" </span></code></pre> Option 2: Use a custom deserializer</strong> (if you can't change the source) Write a custom Serde deserializer to handle the map format:</p> use </span>chrono::{DateTime, Utc}; </span>use </span>serde::{Deserialize, Deserializer}; </span> </span>fn </span>from_timestamp_map</span><</span>'de</span>, D>(</span>deserializer</span>: D) -> Result<DateTime<Utc>, </span>D::</span>Error> </span>where </span> D: Deserializer<</span>'de</span>>, </span>{ </span> #[</span>derive</span>(Deserialize)] </span> </span>struct </span>Timestamp { </span> </span>sec</span>: </span>i64</span>, </span> </span>nsec</span>: </span>u32</span>, </span> } </span> </span> </span>let</span> ts = Timestamp::deserialize(deserializer)?; </span> DateTime::from_timestamp(ts.sec, ts.nsec) </span> .</span>ok_or_else</span>(\|\| serde::de::Error::custom("</span>Invalid timestamp</span>")) </span>} </span> </span>#[</span>derive</span>(Deserialize)] </span>struct </span>ModelSelection { </span> #[</span>serde</span>(deserialize_with = "</span>from_timestamp_map</span>")] </span> </span>created_at</span>: DateTime<Utc>, </span>} </span></code></pre> The custom deserializer reads the sec</code> and nsec</code> fields from the map and constructs a DateTime<Utc></code> from them.</p> Bottom Line</h2> When Serde complains about expecting a string but getting a map for a DateTime</code> field, your data source is storing timestamps in a format Serde doesn't recognize. Either standardize on RFC 3339 strings, or write a deserializer to handle your specific format.</p> The Confusing World of Cursor Payments 2025-10-25T00:00:00+00:00 Cursor</a> is a powerful AI-powered code editor that many developers are excited about. However, one aspect that consistently causes confusion is its payment and pricing model. This post attempts to document some of these confusions based on recent experiences.</p> The Confusion</h2> The payment structure for Cursor can be unclear in several ways:</p> Free tier limits</strong>: What exactly counts toward your monthly quota? Is it AI completions, chat requests, or something else?</li> Billing cycles</strong>: When does your quota reset? Is it calendar month, or from when you first started using the service?</li> Payment methods</strong>: What payment options are available, and how are they processed?</li> Usage tracking</strong>: How can you monitor your usage to avoid unexpected charges or hitting limits?</li> </ul> These ambiguities can lead to surprises—either unexpected charges or finding yourself blocked when you thought you had quota remaining.</p> Why This Matters</h2> For developers evaluating whether to adopt Cursor, understanding the cost and payment structure is important. Unclear pricing creates friction and can be a barrier to adoption, especially for individual developers or small teams on tight budgets.</p> What to Do</h2> If you're considering Cursor:</p> Check the official pricing page</strong> (cursor.sh/pricing</a>) for current information</li> Monitor your usage</strong> if there's a dashboard or settings page that shows quota</li> Reach out to support</strong> if you're confused about billing or limits</li> Document what you learn</strong> since this information may not be clearly documented</li> </ol> Important Disclaimer</h2> ⚠️ Please note</strong>: Pricing, payment structures, and feature availability for Cursor are subject to change. The information in this post reflects experiences at the time of writing and may be outdated by the time you read this. Always refer to Cursor's official documentation and pricing pages for the most current information.</p> The goal of this post is to highlight that these aspects can be confusing, not to provide definitive answers that may become incorrect over time.</p> If you've experienced similar confusion with Cursor's pricing or payment model, you're not alone. Hopefully, this clarity improves as the platform matures.</p> How Embracing Rust Sharpens the Mind — and Elevates Teams 2025-10-22T00:00:00+00:00 When you decide to work in Rust, something subtle begins to shift. It’s not just about learning a new syntax or mastering memory safety. It’s about engaging a mode of thinking that demands attention, clarity, and responsibility. In doing so, you develop stronger focus, sharpened critical thinking, and what might best be called responsible individualism. And when one person grows in that way, the ripple effects can touch an entire team or organization.</p> In this post, I’ll explore three interlocking themes:</p> Focus</strong> — how Rust trains sustained, precise attention</li> Critical Thinking</strong> — how Rust forces richer reasoning and choice</li> Individualism & Contribution</strong> — how mastering Rust empowers an individual who then strengthens the whole</li> </ol> 1. Focus: Cultivating Attention in the Code</h2> In many languages, you type, you compile, you run. Mistakes show up in logs or in production. With Rust, the compiler intervenes early and often. You’ll catch ownership issues, borrowing conflicts, lifetime mismatches—not after deployment, but at compile time.</p> Consider these moments:</p> You borrow a value; you pause and ask: Who currently has access?</li> You annotate a function; you reflect: What lifetimes are involved, and why must this reference stay valid here?</li> You handle a Result<T, E></code>; you evaluate: What happens when this fails?</li> </ul> These are micro‑acts of attention. Over time, they build a habit of precision and presence. Rust trains you not to write just-sufficient code—but code you understand and own.</p> When a developer learns this mode of working, the whole team benefits. Code reviews become richer. Discussions shift from “does it compile?” to “why did this compile, and is this the best way?” The developer’s focus becomes a team asset.</p> 2. Critical Thinking: Building Sound Reasoning</h2> Beyond focus, Rust forces you into deeper reasoning. Ownership, borrowing, lifetimes, concurrency—they’re not mere mechanics, they’re invitations to think about how your code works, why it is safe, and what assumptions you’re making.</p> In philosophical terms, this resembles the concept of technē—the idea of craft or making, where knowing how to do something is inseparable from knowing why you do it. In programming, Rust becomes a modern technē: you not only write code, you reason about resources, validity, and correctness.</p> For example:</p> You ask: “If I pass this borrow here, could someone else modify the data concurrently?”</li> You reason: “If this value moves and the original is used afterward, I invite a compile error. Why does Rust forbid this? What risk is it preventing?”</li> You model: “When threads share Arc<Mutex<T>></code>, what invariants do I preserve? What could go wrong if I slip up?”</li> </ul> These questions steer you away from simple feature‑delivery and toward thoughtful system design. And when more developers engage in this kind of thinking, the codebase becomes more robust, maintainable, and predictable.</p> 3. Individualism & Contribution: Mastery That Scales</h2> “Individualism” often carries negative connotations—but here I mean a positive kind: an individual taking responsibility for their craft, developing depth of understanding, and then choosing to bring that to the group. Rust supports exactly that.</p> The philosophy of software craftsmanship frames development as more than meeting a deadline—it’s about mastery, continuous improvement, and professional pride. When someone invests the time to master Rust’s rule set, they gain both confidence and clarity. They can mentor others, raise standards, and uplift the team.</p> In turn, the team and organization benefit:</p> Decreased bugs and runtime surprises</li> Clearer design boundaries and documentation</li> A culture where thinking matters and craftsmanship is respected</li> </ul> In this way, the individual’s growth becomes a catalyst for collective growth. One Rust‑savvy engineer can shift a team’s mindset from “just ship” to “ship well.”</p> Philosophical Reflection: Craft, Virtue, and the Common Good</h2> Let’s step into the philosophical background. In the virtue‑ethics tradition, the focus isn’t only on what you do, but who you become by doing it. When you practise a craft with discipline, you internalize values: care, integrity, attention to detail.</p> Rust—as a programming language—is more than a tool; it’s a training ground. The rules around ownership and safety aren’t arbitrary; they coax you into a mindset of accountability. That mindset echoes technē: making with purpose, not just automatism.</p> At the same time, contributing to a team, a codebase, or an open ecosystem aligns with the idea of the common good. Technology can be shaped for more than profit—it can serve that which is good, beautiful, and durable.</p> Putting those threads together: writing Rust becomes a practice in character as much as a skill in code. You become someone who thinks deeply about structure, consequences, and shared responsibility. And that transformation benefits every person you code with.</p> Conclusion</h2> Working with Rust gives you more than faster performance or fewer runtime bugs. It gives you a path to sharpen your focus, refine your thinking, and develop a personal mastery that contributes to something larger than yourself. If you’re a developer seeking to grow not just your output but your way of working, Rust offers a compelling challenge. If you’re a leader or a team building culture, supporting your engineers in learning Rust can become a signal of valuing craft, clarity, and long‑term thinking.</p> In the end, the code we build reflects the minds we train. With Rust, the training is real—and the benefits run deep.</p> Further Reading</h3> Software Craftsmanship</a> – the movement emphasizing craftsmanship in programming.</li> Techne</a> – the Greek philosophical concept of craft and skill.</li> Jonsson, M.; Tholander, C. Aiming for Virtue in Programming with Generative AI</em></a> (2023) – On craft, judgement and programming.</li> </ul> GitHub Actions: When Automation Meets Reality 2025-10-19T00:00:00+00:00 When you first set up GitHub Actions for a project, it feels like magic. Push your code, and the CI/CD pipeline takes care of everything—building, testing, deploying. But sometimes, the magic breaks. And when it does, you learn things you never expected to learn.</p> I recently went through a journey with GitHub Actions that taught me a lot about the gap between "this should work" and "this actually works." Here's what I learned, without exposing too many project details.</p> Background: Building with Zola</h2> For context, this blog is built using Zola</a>, a static site generator written in Rust. Zola takes Markdown files and templates, processes them, and outputs a static HTML site. It's fast, simple, and doesn't require a runtime—just compile your site and serve the static files.</p> The deployment process is straightforward:</p> Write content in Markdown</li> Run zola build</code> to generate static HTML</li> Deploy the generated files to a hosting service</li> </ol> This makes Zola an ideal candidate for GitHub Pages: you build once, deploy the static files, and GitHub Pages serves them. The challenge comes when you want to automate this process with GitHub Actions.</p> The Promise of Automation</h2> GitHub Actions promises a lot:</p> Automatic builds on every push</li> Consistent deployment environments</li> Less manual work, fewer human errors</li> Integration with GitHub Pages for static sites</li> </ul> The setup looks straightforward:</p> Create a .github/workflows/deploy.yml</code> file</li> Define your build steps</li> Push and watch it work</li> </ol> But reality has a way of complicating things.</p> Issue #1: The Submodule Problem</h2> One of the first issues I encountered was related to git submodules. If your project includes external dependencies managed as submodules, GitHub Actions needs explicit configuration to handle them.</p> The Error:</strong></p> Error: fatal: No url found for submodule path 'themes/radion' in .gitmodules </span>Error: The process '/usr/bin/git' failed with exit code 128 </span></code></pre> The Root Cause:</strong> GitHub Actions tries to fetch submodules by default, but if your .gitmodules</code> file is missing or incomplete, or if the submodule path exists but isn't properly configured, the build fails.</p> The Solution:</strong> If you're not actually using submodules (maybe you copied files directly), you have two options:</p> Remove the submodule completely:</strong></p> git</span> rm</span> --cached</span> themes/radion </span>rm -rf</span> themes/radion/.git </span>git</span> add themes/radion </span>git</span> commit</span> -m </span>"</span>Convert submodule to regular directory</span>" </span></code></pre> </li> Configure GitHub Actions to skip submodules:</strong></p> - </span>uses</span>: </span>actions/checkout@v4 </span> </span>with</span>: </span> </span>submodules</span>: </span>false </span></code></pre> </li> </ol> I went with option 1 because I wasn't actually using submodules—I had copied the theme files directly into the repository. The submodule reference was leftover from an earlier setup.</p> Issue #2: Branch Confusion</h2> GitHub Pages supports two deployment methods:</p> GitHub Actions:</strong> Build your site using a workflow</li> Branch-based:</strong> Serve files directly from a branch (like gh-pages</code>)</li> </ul> I started with GitHub Actions, but ran into issues. The build kept failing, and debugging CI/CD pipelines can be frustrating—you push, wait, check logs, repeat.</p> The Revelation:</strong> Sometimes, manual deployment to a gh-pages</code> branch is simpler and more reliable. You get:</p> Full control over when and how you deploy</li> Ability to test locally before deploying</li> No hidden automation surprises</li> Easier debugging (you can inspect the built files directly)</li> </ul> The Manual Approach:</strong></p> # Build locally </span>zola</span> build</span> --output-dir</span> public</span> --force </span> </span># Deploy to gh-pages branch </span>git</span> checkout</span> -B</span> gh-pages </span>rsync -av --delete --exclude</span>='</span>.git/</span>' public/ . </span>git</span> add</span> -A </span>git</span> commit</span> -m </span>"</span>Publish: </span>$</span>(</span>date</span> +</span>%</span>Y</span>-</span>%</span>m</span>-</span>%</span>d</span>)</span>" </span>git</span> push</span> -f</span> origin gh-pages </span>git</span> checkout main </span></code></pre> Is this less "modern"? Maybe. But it's transparent, predictable, and gives you control when you need it.</p> Update: Automation Wins After All</h2> After writing the initial version of this post, I realized something: maintaining two branches manually was becoming a burden. The workflow was reliable, but it required:</p> Remembering to switch branches</li> Running build commands</li> Manually syncing files</li> Switching back to main</li> </ul> The Solution:</strong> I revisited GitHub Actions, but this time with a clear understanding of the issues:</p> Configured submodules properly (submodules: false</code> since we don't use them)</li> Used a reliable deployment action (peaceiris/actions-gh-pages</code>)</li> Set up the workflow to trigger on push to main</code></li> </ol> The Result:</strong> Now I just push to main</code>, and GitHub Actions handles everything:</p> Builds the site automatically</li> Deploys to gh-pages</code> branch</li> Updates GitHub Pages</li> </ul> What Changed:</strong> The key was understanding the submodule issue first. Once that was resolved, the automation became reliable. The workflow is simple and transparent—I can see exactly what's happening in the Actions tab.</p> The Lesson:</strong> Sometimes automation does</em> make sense. The difference between my first attempt and my second attempt was:</p> Understanding the root causes (submodules, branch setup)</li> Using proven, maintained actions</li> Starting simple and adding complexity only when needed</li> </ul> The manual approach taught me what was happening under the hood. That knowledge made the automation reliable.</p> Issue #3: Missing Scripts and Assets</h2> When deploying to GitHub Pages, you need to ensure all your assets are included. This might seem obvious, but it's easy to miss.</p> The Problem:</strong> Your site builds locally, but when deployed, certain features don't work—like a theme toggle button that does nothing, or search functionality that's broken.</p> The Cause:</strong> JavaScript files weren't being included in the HTML. The build process generated the files, but the HTML templates weren't referencing them correctly, or the script tags were missing entirely.</p> The Fix:</strong> Manually verify that all necessary scripts are loaded:</p> Check your HTML templates</li> Ensure script tags are in the correct order</li> Verify paths are correct (especially for GitHub Pages subdirectory paths)</li> </ul> Sometimes, the simplest solution is to open the generated HTML and check what's actually there.</p> Issue #4: The Abstraction Trap</h2> Here's the thing about automation: when it works, it's great. When it doesn't, you're debugging an abstraction layer you may not fully understand.</p> The Pattern:</strong></p> Something breaks</li> You check GitHub Actions logs</li> You see an error message</li> You make a change</li> You push and wait</li> Repeat</li> </ol> This cycle can be slow, especially if your builds take a few minutes each time.</p> The Alternative:</strong> With manual deployment:</p> Build locally (instant feedback)</li> Test locally</li> Deploy when ready</li> Inspect the deployed files directly</li> </ol> The feedback loop is faster, and you understand every step.</p> Issue #5: GitHub Pages Source Branch Mismatch</h2> Even after getting the deployment pipeline working, some issues only surfaced when viewing the site in production. These weren't build failures—they were configuration problems.</p> The GitHub Pages Source Branch Mismatch</h3> The Symptom:</strong> After deploying fixes, the blog post updates weren't appearing on the live site. The build succeeded, GitHub Actions showed successful deployment, but visiting the site showed old content.</p> The Root Cause:</strong> GitHub Pages has two deployment methods:</p> GitHub Actions</strong> - Pages builds from Actions workflow output</li> Branch-based</strong> - Pages serves files directly from a branch (like gh-pages</code>)</li> </ol> The problem was a configuration mismatch: GitHub Pages was set to use "GitHub Actions" as the source, but our workflow was deploying to the gh-pages</code> branch. GitHub Pages was trying to serve from the Actions output, not the branch we were deploying to.</p> The Fix:</strong> Changed GitHub Pages source back to gh-pages</code> branch in repository settings:</p> Go to repository Settings → Pages</li> Under "Source", select "Deploy from a branch"</li> Choose gh-pages</code> branch and / (root)</code> folder</li> Save</li> </ol> Why This Happened:</strong> When you first set up GitHub Actions, GitHub Pages might automatically switch to "GitHub Actions" mode. If your workflow deploys to gh-pages</code> branch (which is common), you need to ensure the Pages source matches where you're deploying.</p> The Lesson:</strong> Always verify that your GitHub Pages source matches your deployment target. If your Actions workflow deploys to gh-pages</code>, make sure Pages is configured to serve from that branch. Configuration mismatches can cause silent failures where everything appears to work but content doesn't update.</p> Testing Across Browsers</h3> The Problem:</strong> Different browsers cache differently. Chrome might show updated content while Firefox shows old content, or vice versa. However, in this case, the issue wasn't browser caching—it was a configuration mismatch.</p> The Solution:</strong></p> Always verify GitHub Pages source matches your deployment method</li> Check GitHub Actions logs to confirm deployment succeeded</li> Wait 2-5 minutes for GitHub Pages to rebuild after deployment</li> Use hard refresh (Cmd+Shift+R / Ctrl+Shift+R) when testing</li> Test in multiple browsers to rule out caching issues</li> </ol> What I Learned:</strong></p> GitHub Pages configuration must match your deployment method</li> Always verify the deployment target matches the Pages source</li> Testing locally doesn't catch configuration mismatches</li> </ul> When to Use GitHub Actions</h2> Don't get me wrong—GitHub Actions is powerful and useful. Use it when:</p> You need automated testing on every commit</li> You want consistent build environments</li> Multiple people are deploying</li> You need to run expensive operations (like building large projects)</li> You want to enforce code quality checks</li> </ul> But consider manual deployment when:</strong></p> Your build process is simple</li> You want full control</li> You're deploying infrequently</li> You want to understand every step</li> Debugging automation is slowing you down</li> </ul> Lessons Learned</h2> Understand your dependencies:</strong> Know whether you're using submodules, npm packages, or other external resources. This affects your CI/CD setup.</p> </li> Test locally first:</strong> Always build and test your site locally before relying on automation. Automation catches mistakes, but you should catch them first.</p> </li> Keep it simple:</strong> If automation adds complexity without clear benefits, consider if manual processes might be better for your use case.</p> </li> Inspect the output:</strong> When something doesn't work, look at the actual generated files. HTML errors, missing assets, and broken links are often visible in the source.</p> </li> Verify GitHub Pages configuration matches deployment:</strong> If your Actions workflow deploys to gh-pages</code> branch, ensure GitHub Pages source is set to that branch. Configuration mismatches cause silent failures.</p> </li> Test across browsers:</strong> Different browsers cache differently. Always test in multiple browsers after deployment, and use hard refresh when debugging.</p> </li> Document your process:</strong> Whether you use automation or manual deployment, document it. Future you (and your team) will thank you.</p> </li> </ol> Conclusion</h2> GitHub Actions is a powerful tool, but it's not always the right tool—at least not immediately. My journey started with frustration, moved to manual control, and ended with successful automation.</p> The manual approach wasn't wasted effort. It taught me:</p> What was happening under the hood</li> How the build process worked</li> What could go wrong and why</li> </ul> That knowledge made the automation reliable. When I returned to GitHub Actions, I understood the root causes and could configure it correctly.</p> The key is to choose the approach that fits your project, your team, and your workflow. Sometimes that means starting manually to understand the process, then automating once you know what you're automating.</p> At the end of the day, the goal is to deploy reliably and efficiently. Whether that's through GitHub Actions, manual commands, or a hybrid approach, what matters is that it works for you—and that you understand why it works.</p> Further Reading</h3> GitHub Actions Documentation</a> – Official documentation</li> GitHub Pages Deployment</a> – Deployment strategies</li> Managing Git Submodules</a> – Git submodule basics</li> </ul> Why Rust Makes You a Better Engineer 2025-10-16T00:00:00+00:00 If you've ever tried learning Rust, chances are the compiler pushed back at you—hard. It may feel relentless at times, especially compared to more permissive languages like Python, JavaScript, or even Java. But here's the key: that friction is the point. Rust doesn't just run your code safely—it teaches you to think differently</strong> about correctness, safety, and performance.</p> In this post, we'll break down the key concepts that make Rust unique and walk through what the compiler enforces—and why that's a good thing in the long run.</p> 1. Strict Type System</h2> Rust's type system is precise, and it expects you to be explicit about what types you're working with. There's no silent coercion between mismatched types. This can feel rigid at first, but it eliminates entire classes of bugs you'd otherwise only see at runtime.</p> Example: Type mismatch</h3> fn </span>add</span>(</span>a</span>: </span>i32</span>, </span>b</span>: </span>i32</span>) -> </span>i32 </span>{ </span> a + b </span>} </span> </span>fn </span>main</span>() { </span> </span>let</span> x: </span>i32 </span>= </span>5</span>; </span> </span>let</span> y: </span>u32 </span>= </span>10</span>; </span> </span>let</span> sum = </span>add</span>(x, y); </span>// error: mismatched types </span>} </span></code></pre> Rust won't implicitly convert between u32</code> and i32</code>. You'll need to cast it explicitly:</p> let</span> sum = </span>add</span>(x, y as </span>i32</span>); </span></code></pre> This forces you to make conversion decisions intentionally and not by accident.</p> 2. Error Handling: No Exceptions</h2> Rust does not have exceptions. Instead, it uses the Result<T, E></code> and Option<T></code> types for fallible operations. You must explicitly handle errors or propagate them. Ignoring them is not allowed.</p> Example: Required handling of Result</code></h3> use </span>std::fs::File; </span> </span>fn </span>main</span>() { </span> </span>let</span> file = File::open("</span>config.txt</span>"); </span>// warning/error: unused `Result` </span>} </span></code></pre> To resolve this, you can either handle the error:</p> match </span>File::open("</span>config.txt</span>") { </span> Ok(f) => println!("</span>File opened: </span>{:?}</span>", f), </span> Err(e) => eprintln!("</span>Failed to open file: </span>{}</span>", e), </span>} </span></code></pre> Or propagate it using the ?</code> operator in a function that returns a Result</code>:</p> fn </span>open_file</span>() -> std::io::Result<()> { </span> </span>let</span> _file = File::open("</span>config.txt</span>")?; </span> Ok(()) </span>} </span></code></pre> This enforces a programming style where failure is expected and dealt with.</p> 3. Immutability by Default</h2> Variables are immutable unless explicitly marked otherwise. This encourages predictability and thread-safety, even in single-threaded contexts.</p> Example: Immutable variable</h3> fn </span>main</span>() { </span> </span>let</span> name = String::from("</span>Alice</span>"); </span> name.</span>push_str</span>("</span> Smith</span>"); </span>// error: cannot borrow as mutable </span>} </span></code></pre> The correct way:</p> let mut</span> name = String::from("</span>Alice</span>"); </span>name.</span>push_str</span>("</span> Smith</span>"); </span></code></pre> This simple rule helps reduce bugs from unintended mutation, especially in shared state.</p> 4. Ownership and Move Semantics</h2> Rust enforces a unique ownership model. Every value in Rust has a single owner, and when that owner goes out of scope, the value is dropped. You can move ownership, borrow it temporarily, or clone the data.</p> Example: Moved value error</h3> fn </span>takes_ownership</span>(</span>s</span>: String) { </span> println!("</span>{}</span>", s); </span>} </span> </span>fn </span>main</span>() { </span> </span>let</span> s1 = String::from("</span>hello</span>"); </span> </span>takes_ownership</span>(s1); </span> println!("</span>{}</span>", s1); </span>// error: value was moved </span>} </span></code></pre> Once ownership is transferred, you can no longer use the original. This prevents bugs like double-free or use-after-free that are common in C/C++.</p> 5. Borrowing Rules</h2> Instead of transferring ownership, you can borrow references. Borrowing can be either immutable (&T</code>) or mutable (&mut T</code>), but Rust enforces strict rules:</p> You can have multiple immutable borrows</strong> at the same time.</li> Or one mutable borrow</strong>.</li> But not both.</li> </ul> This is enforced at compile time.</p> Invalid example: Two mutable borrows</h3> let mut</span> s = String::from("</span>hello</span>"); </span>let</span> r1 = &</span>mut</span> s; </span>let</span> r2 = &</span>mut</span> s; </span>// error: cannot borrow `s` twice mutably </span></code></pre> The compiler ensures that you never access memory from multiple places in ways that could cause race conditions or undefined behavior.</p> 6. Lifetimes</h2> Lifetimes are Rust's way of tracking how long references are valid. The compiler uses lifetimes to prevent dangling references.</p> Example: Dangling reference (compile error)</h3> fn </span>main</span>() { </span> </span>let</span> result; </span> { </span> </span>let</span> s = String::from("</span>temporary</span>"); </span> result = &s; </span>// s does not live long enough </span> } </span> println!("</span>{}</span>", result); </span>// would be a dangling reference </span>} </span></code></pre> Rust will reject this code, saving you from accessing freed memory. Often, you'll write explicit lifetime annotations in function signatures when dealing with multiple references.</p> 7. Concurrency Without Data Races</h2> Rust prevents data races at compile time using its ownership and borrowing rules. When you need to share mutable state between threads, you must use thread-safe abstractions like Arc<Mutex<T>></code>.</p> Example: Thread-safe counter</h3> use </span>std::sync::{Arc, Mutex}; </span>use </span>std::thread; </span> </span>fn </span>main</span>() { </span> </span>let</span> counter = Arc::new(Mutex::new(</span>0</span>)); </span> </span>let mut</span> handles = vec![]; </span> </span> </span>for </span>_ in </span>0</span>..</span>10 </span>{ </span> </span>let</span> counter = Arc::clone(&counter); </span> </span>let</span> handle = thread::spawn(</span>move </span>\|\| { </span> </span>let mut</span> num = counter.</span>lock</span>().</span>unwrap</span>(); </span> num += </span>1</span>; </span> }); </span> handles.</span>push</span>(handle); </span> } </span> </span> </span>for</span> handle in handles { </span> handle.</span>join</span>().</span>unwrap</span>(); </span> } </span> </span> println!("</span>Result: </span>{}</span>", *counter.</span>lock</span>().</span>unwrap</span>()); </span>} </span></code></pre> In many other languages, this would compile fine but possibly fail at runtime. In Rust, the compiler ensures that shared state is accessed safely.</p> Final Thoughts</h2> Rust asks a lot from the developer upfront. You'll be forced to think about ownership, lifetimes, mutability, and error paths very early in the process. But once your code compiles, it's often rock-solid. You'll find fewer runtime crashes, undefined behaviors, or memory leaks.</p> More importantly, Rust helps you develop habits that transfer to any language: understanding lifecycles, reducing shared mutable state, and always considering failure cases.</p> Additional Resources</h3> The Rust Book</a></li> Rust by Example</a></li> Rustlings: Interactive CLI Exercises</a></li> cheats.rs: Rust best practices</a></li> </ul> How my terminal looks 2025-10-13T00:00:00+00:00 Background</h3> I think everyone of you geeks would like if your terminal looks cool and productive. And yes, I'm talking here about terminals in POSIX-compliant OS's, more specifically terminal in a Linux environment.</p> Anyhow I will share you the details of my customized terminal configurations so you could get an idea of what it is really capable of doing and perhaps you would start applying the changes to your own terminal.</p> So to make it all happen I had to give up on bash</code> and start using zsh</code>. Because zsh</code> provides some extensive support to terminal users and it is certainly feature rich, customizable and cooler than bash</code>. So all the customizations I made are based on zsh</code> and oh-my-zsh</a> (a really cool community driven project for managing zsh</code> configurations)</p> Looks</h3> If looking at theming oh-my-zsh</code> provides some cool and nice looking themes out of the box. But the theme that I'm using is an external theme and needs little bit more configurations before using it.</p> It's call bullet-train</a> and to make it look right I had to install some fonts from Vim-Powerline</a>. I also had to change the color scheme of my terminal to use Solarized (dark)</strong>. Here I'm using xfce4-terminal that comes with Xubuntu, so I can easily change the color scheme from the preferences menu. I also make it a bit transparent to make it even more cooler.</p> Productivity</h3> Enough of the looks. Lets see how is it when it comes the productivity. Here again oh-my-zsh</code> provides some nice plugins</a> that you can use to increase your productivity. I'll list down the plugins that I'm using</p> Plugins</h4> git</a> - A very comprehensive plugin for git</code> with lots of aliases for easy usage</li> history-substring-search</a> - Very useful plugin that will get you through your zsh</code> history backwards-forwards via up and down arrow keys</li> zsh-syntax-highlighting</a> - this will highlight the commands we use inside the terminal</li> command-not-found</a> - will suggest alternative/correct commands instead of just command not found error</li> colorize</a> - this will colorize the syntaxes for almost every popular sciprting/programing language</li> colored-man-pages</a> - syntax highlight in man pages for easy reading</li> python</a> - provides lots of useful aliases to Python</li> sudo</a> - hit ESC twice and boom! sudo</code> will added to your command</li> web-search</a> - simply opens up your browser with the search query of yours in desired search engine i.e google whats the weather like today</code></li> chucknorris</a> - this plugin isn't particularly meant for productivity but it can get really humorous.</li> ubuntu</a> - this particular plugin provides lot of Ubuntu specific aliases to ease up the day-to-day work</li> </ul> Once put these all together this is how it looks</p> About 2025-01-01T00:00:00+00:00 Who I Am</h2> I'm Oshadha</strong>, a senior engineer passionate about building reliable, performant systems. My journey started in Java—Spring, Spring Boot, microservices, you name it. I cut my teeth on enterprise Java applications and learned the art of distributed systems the hard way.</p> But recently, I've been fascinated by Rust</strong>—its speed, memory safety, and the compiler's refreshingly rude honesty. I'm now diving deep into Rust with personal projects, exploring systems programming from a new angle. But I know my roots, and those Java lessons still shape how I think about architecture.</p> In my day job, I'm mostly into efforts—overseeing in AI/ML, building, and planning AI/ML pipelines for targeted clients. It's about battling the unknowns behind this new frontier and shaping features that grab users' attention. The journey from Java to AI to Rust has taught me that the best engineers aren't defined by their language, but by their ability to solve problems.</p> This blog, Noos</strong>, is where I share my thoughts on technology, engineering practices, and the occasional hard-won lesson from the trenches.</p> What I Write About</h2> My content spans:</p> Java & Spring</strong>: Enterprise patterns, microservices architecture, and lessons from building large-scale systems</li> Rust</strong>: Exploring systems programming, memory safety, and the Rust ecosystem as I learn</li> AI/ML Engineering</strong>: Building robust ML pipelines, tackling the unknowns, and shipping production ML systems</li> Linux & Open Source</strong>: Terminal workflows, system configuration, and the tools I use daily</li> DevOps</strong>: CI/CD, infrastructure, automation, and the realities of deployment</li> </ul> I write from experience, not theory. You'll find real problems I've encountered, actual solutions that worked (and some that didn't), and honest reflections on what I wish I'd known sooner.</p> Tech Stack</h2> Here's what I work with:</p> Languages</strong>: Java, Python, Rust, JavaScript</li> Frameworks</strong>: Spring Boot, microservices architecture, Rust ecosystem</li> ML/AI</strong>: Building and deploying ML pipelines, model serving, production ML systems</li> Infrastructure</strong>: Linux, Docker, GitHub Actions, cloud platforms</li> Tools</strong>: Terminal-first workflows, Vim, tmux</li> Interests</strong>: Systems programming, distributed systems, performance optimization, ML engineering</li> </ul> Contact</h2> You can find me on:</p> LinkedIn</strong>: Oshadha Gunawardena</a></li> GitHub</strong>: nooscraft</a></li> Blog</strong>: noos.blog</a></li> </ul> This site is built with Zola</a>, a blazingly fast static site generator written in Rust. The theme is Radion</a>, customized for a clean, minimal aesthetic.</em></p> A simple word definition script 2015-08-25T00:00:00+00:00 Have you ever come across a difficulty to find a definition of a word that you are looking for. Well I find it bit difficult for me.</p> I normally use Google search to find definitions of words. For example to get the definition of the word "replenish" I use definition replenish</em></a> on search bar</p> But this approach is still bit clumsy though, since you need a browser and if you are already opened multiple tabs then it is sometimes get messy around to switch around tabs.</p> So I found out this simple script from the book Linux Shell Scripting Cookbook, 2nd Edition</em></a> that will query your word and get the definition of it.</p> Let's see how to get it to work (I have altered the original script from the book to make is more convenient)</p> First you need an account in dictionaryapi.com</em> - http://www.dictionaryapi.com/register/index.htm</a> API key for the learners</em> API would be enough for the time being</li> </ul> </li> Get the script from here</a></li> Assign your API key to the variable apikey</strong></li> Make it executable chmod +x define</code></li> Optional: if you want to make it available system wide add the script to /usr/local/bin</code></li> Finally you can run it as ./define replenish</code></li> </ul> The outcome would be:- </p> JDK 9 and JShell 2015-06-12T00:00:00+00:00 Intro</h3> I recently got to know about this official Java REPL (Read-Eval-Print-Loop) or JShell project. It is named as Kulla and you can visit here</a> to see the project's home. This is pretty much same like the Python's IDLE (If you have used it before) and a great way to exercise your code in real time. Also the good thing is that this project will be available as a part of JDK9 among with some other cool features.</p> Anyhow I managed to get it run on own and have tried few exercises too. Here, take a look</p>

Noos - Where Thought, Code, and Craft Converge

When nothing feels fun any more

2026-04-26T00:00:00+00:00

I watched a video recently where a former tech engineer talks about something I have been feeling in myself and seeing in people around me. It is this growing emptiness, where things that used to bring joy now feel flat. Gaming, traveling, hobbies, even just relaxing; everything feels like it has lost its color.

The video calls it a clinical name, but I do not know if that is what I have or if it is just a phase. What I do know is the feeling is real, and I am not sure if it is going to stay or pass.

The pressure to keep building</h3>
This hits harder when you work in tech. There is this constant push to keep building, keep shipping, keep getting better. A former Google engineer in that video said even after leaving the job, the habit of always producing followed him. I get that. Even when I am supposed to rest, some part of my brain is thinking about the next thing to build or learn.
Big win or small win, the joy fades fast. You finish something, feel good for a few hours, then start worrying about the next thing. It is like the moment you stop, you start falling behind.

Time feels strange</h3>
Time has felt strange for a while now. I think this has been building for years, but we are moving so fast that it creates this quiet gap. Days blur together. You look back and wonder where the month went. It is not just being busy; it is something deeper. A kind of worry that creeps in when you realize you are pushing yourself hard without knowing what happens after.

Why this might be happening</h3>
The video pointed to a few things that clicked with me. First is how everything is about money now. Every hobby has someone trying to sell you a course or a side hustle plan. You cannot just enjoy photography; you have to think about building a brand. You cannot just play a game; you have to consider streaming it. The natural fun gets drained because everything becomes a way to make money.
Then there is the social media trap. Doom-scrolling eats up whatever free time you have left, and the constant comparison makes hobbies feel like a race. When everything becomes about status and attention, the fun goes away.
And there is the noise online. We get hit with biased content and ads all day. The mind builds a wall to protect itself. It is a defense, but it also makes you stop caring about good things.

What I am trying</h3>
I do not have answers, but I have been trying a few things that help a little.
I cut social media down a lot. Not just time limits, but choosing which sites I even open. I stick to places that give me something real, where I learn, not just scroll through fake updates.
I read more about things outside tech. Fiction, history, random essays about stuff I know nothing about. It reminds me the world is bigger than my work bubble.
Sleep is the obvious one everyone skips. I am trying to sleep more so my body actually rests. Still working on this, but the nights where I get enough sleep, the next day feels different.
And family time. Just being around people who knew me before I was a programmer. Talks that have nothing to do with work or getting better at things. That helps more than I expected.

Not sure where this goes</h3>
I do not know if this emptiness is a short reaction to our world now or something that stays. Maybe it is a shared thing that will shift as things change. Maybe it is personal and everyone has to find their own way.
What I do know is noticing it is the first step. Taking back your attention feels like pushing back against a world that wants to make money from every second of it. I am still figuring out what that looks like day to day.
The video that got me thinking is here</a>. Worth a watch if this sounds familiar.

Let us see how it goes.

Stacked PRs go native in GitHub, and what that means for AI-assisted work

2026-04-19T00:00:00+00:00

GitHub announced native Stacked PRs</a>, still in private preview. I wanted to write about it for two reasons. First, it bakes in a workflow some of us have been doing for a while, either manually or via third-party tools, mostly to keep PRs small enough that reviewers actually read them. Second, it lands at a moment when AI agents are producing more of the diffs, and the gap between "diff size" and "what a human can review well" is getting wider every month.
What a stack is, quickly</h2>
A stack is a chain of pull requests in the same repo where each PR targets the branch of the PR below it. Instead of one giant PR that touches the database layer, the API, and the UI, you get three smaller ones that build on each other:
main ↑ PR #1: auth-layer ↑ PR #2: api-endpoints ↑ PR #3: frontend </code></pre> Each layer is reviewed on its own. When the bottom is ready you can merge the bottom couple, or all of them at once, and the rest auto-rebase onto the new base. That auto-rebase is one of the things that makes a stack worth the trouble; doing it by hand across five branches is the part that always made me give up before.
What is actually new</h2>
Stacking as a workflow is not new. Graphite</a> has built a polished CLI (gt</code>), a VS Code extension, a PR inbox, and an AI review product around it. Meta's ghstack</code></a> by Edward Yang has been around for years and powers a lot of the PyTorch workflow. There is also spr</code></a>, and historically Phabricator did this before Meta sunset it.
What GitHub adds, going by the overview docs</a>, is the bits that previous tools could only approximate from the outside:
A stack map in the PR header so reviewers can navigate between layers.</li> Branch protection rules enforced against the final target branch (usually main</code>), not just the immediate parent branch of each PR.</li> CI runs each PR as if it were targeting the final branch, so green checks actually mean something.</li> One-click merge of multiple layers, with automatic rebase of the rest of the stack afterwards.</li> </ul> The "branch protection against the final target" point is the one that quietly matters. With third-party tools, your PR #3 in a stack technically targets PR #2's branch, which often does not have the same protection rules as main</code>. Teams used to work around this with naming conventions, bots, or just hoping reviewers paid attention. Native handling closes that gap. Trying the CLI right now</h2> The feature is in private preview as of April 2026, and you need to be allowlisted on a repo for the server-side bits (submit</code>, merge</code>, the stack map UI) to work. But the CLI itself is publicly installable. I poked at it a bit: $ gh extension install github/gh-stack $ gh stack --help Create, navigate, and manage stacks of branches and pull requests. Usage: gh stack [command] Available Commands: add Add a new branch on top of the current stack alias Create a shell alias for gh stack bottom Check out the bottom branch of the stack checkout Checkout a stack from a PR number or branch name down Check out a branch further down in the stack feedback Submit feedback for gh-stack init Initialize a new stack merge Merge a stack of PRs push Push all branches in the current stack to the remote rebase Rebase a stack of branches submit Create a stack of PRs on GitHub sync Sync the current stack with the remote top Check out the top branch of the stack unstack Delete a stack locally and on GitHub </code></pre> The local workflow works without any preview access. In a throwaway repo: $ git init -q && git commit --allow-empty -m "init" -q $ gh stack init test-stack-bottom ✓ Creating stack with trunk main and branch test-stack-bottom Switched to branch test-stack-bottom To add a new layer to your stack, run `gh stack add` When you're ready to push to GitHub and open a stack of PRs, run `gh stack submit` $ echo "auth" > auth.txt && git add . && git commit -m "auth layer" -q $ gh stack add api-layer ✓ Created and checked out branch "api-layer" $ git log --oneline --all --decorate 463808f (HEAD -> api-layer, test-stack-bottom) auth layer 2b6a4ea (main) init </code></pre> So you can install it, play with init</code>, add</code>, bottom</code>, top</code>, down</code>, up</code>, rebase</code>, unstack</code> locally today. The bits that need GitHub-side support are the actual submit</code> and merge</code>, and that part is gated by the waitlist</a>. Prerequisites are gh</code> v2.0+ and Git 2.20+ (Quick Start</a>), both pretty undemanding. There is also a gh stack alias</code> command that wires up gs</code> as a shorter alias, which I will probably end up using because typing gh stack add</code> thirty times a day gets old. The AI-assisted angle</h2> Here is the part I actually wanted to think out loud about. If you have reviewed a PR opened by an AI agent (Cursor, Codex, Claude Code, Copilot, or any of the cloud agents), you know the failure mode. The agent gets asked to "add user profiles", and twenty minutes later there is a PR with a migration, a schema, a service layer, three endpoints, two React components, a settings page, and seventeen unit tests. All in one or two commits. Reviewing that with any rigour is an afternoon's work, and the path of least resistance is to skim, push back on a couple of obvious things, and merge. Stacked PRs are a structural answer to that problem. If the agent (or the human supervising it) is encouraged to land the migration first, then the service, then the endpoints, then the UI, each layer is something a person can actually read in one sitting. Conflicts get smaller. Reverts get surgical. The cost of "actually let's redo the data model" drops from "throw away the whole PR" to "throw away the bottom layer and rebase". GitHub seems to know this is the angle. The docs include an AI agent integration step: npx skills add github/gh-stack </code></pre> That installs a skill telling the agent how to author and manage stacks. I have not tried it yet (no preview access), so I cannot tell you how good it is in practice. The bet is interesting though: instead of teaching humans to slice their AI-generated work after the fact, teach the agent to slice its own work and produce a stack from the start. A few honest reservations: AI agents can mechanically split a diff (one file per commit, one logical component per commit). They are still not great at deciding where the right review boundaries are. That is exactly the kind of architectural judgment they tend to miss. A stack of five PRs split in the wrong places is arguably worse than one large PR, because reviewers context-switch between layers without the layering actually helping them.</li> A stack is only as solid as its bottom layer. If the data model in PR #1 is wrong, every later PR is built on sand. AI-authored stacks raise that risk because the agent often does not pause long enough to question the foundation.</li> Merge queues, codeowners, and stacks together are still a frontier. I expect most of the next round of papercuts will be in that intersection.</li> This is GitHub's native version, but there are mature alternatives. If your team already pays for Graphite, the stack-management half of what they sell is now duplicated in GitHub itself, but the review queue, dashboards, and Diamond AI review are not. Whether you switch is more of a procurement question than a tooling question.</li> </ul> What I am going to actually try</h2> Some small experiments I have lined up once I get preview access: Use gh stack init</code> for any change that touches more than one logical layer (data, service, UI). One layer per PR.</li> For AI-generated work, ask the agent to produce a plan first, treat each plan step as a layer, and only let it write code one layer at a time.</li> Test the merge-multiple-layers-at-once flow on a low-stakes change before relying on it for anything serious.</li> See whether the GitHub skill (npx skills add github/gh-stack</code>) actually gets the agent to author stacks unprompted, or whether it still needs hand-holding.</li> </ul> If any of these turn out interesting, I will come back with an update. For now the overview</a> and the Quick Start</a> are the two pages worth reading. The waitlist is on the same page. Let's see how it goes once it is open.
How uv Works Under the Hood 2026-04-08T00:00:00+00:00 Updated 2026-05-05: re-verified against uv v0.11.8. I refreshed the release references, fixed inconsistent package versions in the lockfile excerpt, updated build backend examples, and cleaned up punctuation/style issues. </blockquote> I started using uv</a> because the benchmarks seemed too good to be true: 10-100x faster than pip</code>, resolves and installs in milliseconds. So I spent a weekend reading the source. This post is what I wish I'd had on day one. It traces every layer: the repository structure, what actually happens when you type uv init</code> or uv add requests</code>, and the Rust concurrency patterns the resolver uses. No prior Rust experience needed, but if you've seen Rust before I'll point to the specific patterns in the source. Everything below was verified against uv v0.11.8</a> (April 2026). Specific numbers and code excerpts come from that tag; if you're reading this much later, the line numbers in linked source files may have drifted, but the high-level architecture has been stable for many releases. Quick release note: 0.11.8 mostly shipped CLI, lockfile, and configuration improvements (pip uninstall -y</code>, UV_NO_PROJECT</code>, UV_PYTHON_SEARCH_PATH</code>, and exclude-newer</code> lock handling fixes). It did not materially change the resolver architecture discussed in this post. 1. What uv is</h2> uv is an extremely fast Python package and project manager, written in Rust and built by Astral</a>, the team behind Ruff</a>. It replaces most of your Python toolchain in one binary: Old tool</th> uv equivalent</th></tr></thead> pip install</code></td> uv pip install</code></td></tr> pip-compile</code></td> uv pip compile</code></td></tr> virtualenv</code> / venv</code></td> uv venv</code></td></tr> pyenv</code></td> uv python install</code></td></tr> pipx run</code></td> uvx</code> / uv tool run</code></td></tr> poetry</code> / rye</code></td> uv init</code> + uv add</code></td></tr> </tbody></table> It has 84k+ stars, is used in production at scale, and the underlying pubgrub-rs</code></a> crate it depends on is the designated basis for Cargo's next dependency solver</a>. The same algorithm and largely the same Rust crate will eventually power both uv</code> and cargo</code> resolutions. 2. The repository layout</h2> Clone the repo and you'll see: uv/ ├── crates/ # All Rust source code ├── docs/ # MkDocs documentation ├── python/ # Small Python shim package (the uv PyPI wheel) ├── scripts/ # Benchmarking, release tooling ├── test/ # Test fixtures, requirement files for benchmarks ├── Cargo.toml # Rust workspace root └── pyproject.toml # uv manages itself with uv </code></pre> The real action is in crates/</code>. There are 67 crate directories in v0.11.8. Rust does not allow circular dependencies between crates, so the uv team structured the code as a directed acyclic graph of focused crates. Each does one thing: crates/ ├── uv/ # CLI binary: entry point and argument parsing (clap) ├── uv-resolver/ # Dependency resolution engine (PubGrub) ├── uv-installer/ # Installing packages into environments ├── uv-client/ # Async HTTP client for PyPI and registries ├── uv-workspace/ # pyproject.toml parsing and workspace discovery ├── uv-python/ # Python version management ├── uv-cache/ # Global content-addressed cache ├── uv-distribution/ # Wheel and sdist handling, metadata fetching ├── uv-build/ # uv's own build backend (replaces setuptools/hatchling) ├── uv-git/ # Git dependency support (based on Cargo's implementation) ├── uv-platform-tags/ # Wheel compatibility tag matching ├── uv-pep440/ # Python version specifier parsing (PEP 440) ├── uv-pep508/ # Dependency specifier parsing (PEP 508) ├── uv-types/ # Shared type definitions used across crates └── ... (many more) </code></pre> You can generate a visual dependency graph between crates: cargo depgraph --dedup-transitive-deps --workspace-only | dot -Tpng > graph.png </code></pre> The shape of the graph is roughly: uv</code> (the binary) sits at the top and depends on everything. uv-types</code> sits near the bottom and depends on almost nothing. Code only flows downward; cycles are a hard compile error. 3. What happens when you run uv init</code></h2> Let's trace uv init my-project</code> step by step through the codebase. Step 1: Argument parsing (uv</code> crate)</h3> The uv</code> crate is the binary entry point. It uses clap</a> for argument parsing. When you run uv init my-project</code>, clap matches the init</code> subcommand and extracts the project name and any flags (--lib</code>, --app</code>, --package</code>, --bare</code>, --build-backend</code>, etc.). Step 2: Workspace discovery (uv-workspace</code>)</h3> Before creating anything, uv checks whether you're already inside an existing workspace. It walks up the directory tree looking for a pyproject.toml</code> with a [tool.uv.workspace]</code> section. If you're inside one, the new project is registered as a workspace member automatically. If not, it creates a standalone project. Step 3: Scaffold project files</h3> For uv init my-project</code>, uv writes these files to disk: my-project/ ├── .python-version # e.g., "3.12", pins the Python version ├── README.md ├── main.py # boilerplate main() function └── pyproject.toml </code></pre> The generated pyproject.toml</code>: [project] name = "my-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = [] </code></pre> Notice there is no [build-system]</code> section. Without it, the project is not installable as a package: it won't be installed into the virtual environment itself. This is the correct default for applications (web servers, scripts, CLIs); it avoids an unnecessary install step and the complexity of choosing a build backend upfront. If you pass --lib</code> or --package</code>, uv adds a src/</code> layout and a [build-system]</code> pointing to uv_build</code>, uv's own Rust-native build backend: [build-system] requires = ["uv_build>=0.11.8,<0.12"] build-backend = "uv_build" </code></pre> Step 4: Git initialization</h3> uv runs git init</code> and writes a .gitignore</code> that excludes .venv/</code> and __pycache__/</code>. Skip this with --no-vcs</code>. No virtual environment is created yet. uv is lazy: it creates .venv</code> only when you first run something or add a package. This avoids disk writes for projects you might never use. 4. What happens when you run uv add requests</code></h2> This is the core operation. uv add</code> installs a package and records it in pyproject.toml</code> and uv.lock</code>. Here is the full pipeline: $ uv add requests Using CPython 3.12.10 Creating virtual environment at: .venv Resolved 6 packages in 456ms Prepared 5 packages in 451ms Installed 5 packages in 4ms + certifi==2026.2.25 + charset-normalizer==3.4.7 + idna==3.11 + requests==2.33.1 + urllib3==2.6.3 </code></pre> Two things worth noticing about that output. "Resolved 6 packages" includes the project itself as a node in the dependency graph (your project + 5 transitive deps), but only 5 packages are installed: the project itself isn't installable here because there's no [build-system]</code>. And "Prepared" is uv's word for "downloaded and unpacked into the cache, ready to be linked into the venv": the actual install step is just creating links, which is why it takes 4ms. Stage 1: Read the project state (uv-workspace</code>)</h3> uv-workspace</code> reads pyproject.toml</code> and constructs an in-memory Manifest</code>: the project name, existing dependencies, Python version constraint, workspace members, and overrides. Stage 2: Update pyproject.toml</code> (pyproject_mut</code>)</h3> uv adds requests</code> to the dependencies</code> list in pyproject.toml</code>. At this point it doesn't know the version yet, so it records it as a bare requirement. After resolution (Stage 3), it rewrites the specifier with the resolved version. The exact form depends on the --bounds</code> flag; the default (AddBoundsKind::Lower</code> in pyproject_mut.rs</code></a>) is a single lower bound: dependencies = [ "requests>=2.33.1", ] </code></pre> This edit goes through uv-workspace</code>'s pyproject_mut</code> module, which does surgical TOML editing: it patches exactly the field it needs to change without reformatting anything else in the file. That matters because pyproject.toml</code> often contains hand-formatted sections, comments, and deliberate ordering that a naive serialize/reserialize pass would obliterate. Stage 3: Resolution (uv-resolver</code> + PubGrub)</h3> The resolver answers: "Which exact version of every package satisfies all constraints?" This is the most complex stage. We'll cover it in depth in sections 5 and 6. The output is a complete (package, version)</code> assignment for every package in the dependency tree. Stage 4: Write uv.lock</code></h3> The resolved set is serialized to uv.lock</code>. This is a TOML file that records every package: its exact version, source URL, content hash, and its own dependencies. A real excerpt: version = 1 requires-python = ">=3.12" [[package]] name = "requests" version = "2.33.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "certifi" }, { name = "charset-normalizer" }, { name = "idna" }, { name = "urllib3" }, ] sdist = { url = "https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz", hash = "sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517", size = 134120 } wheels = [ { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a" }, ] [[package]] name = "urllib3" version = "2.6.3" source = { registry = "https://pypi.org/simple" } dependencies = [] sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556 } wheels = [ { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4" }, ] </code></pre> The lockfile is universal: one uv.lock</code> works on macOS, Linux, and Windows. It records all possible packages for all platforms using environment markers. When you install from the lockfile on a real machine, uv selects only the packages appropriate for that platform. This is a real improvement over pip freeze</code> or requirements.txt</code>, which are inherently platform-specific snapshots. The hashes serve two purposes: integrity verification when downloading, and cache lookup keying. Note: uv.lock</code> is an internal format that may change between versions. If you need to read it programmatically, the experimental uv workspace metadata --preview-features workspace-metadata</code> command outputs a stable JSON representation of the same dependency graph (it's still preview as of v0.11.8, so don't rely on its schema being final). </blockquote> Stage 5: Download packages (uv-client</code> + Tokio)</h3> uv-client</code> is uv's async HTTP client, built on reqwest</a> and Tokio</a>. For every package not already in the global cache, uv fires off concurrent downloads: # pip: sequential fetch requests → wait → fetch urllib3 → wait → fetch certifi → wait → ... total ≈ N × round_trip_time # uv: concurrent fetch requests ─┐ fetch urllib3 ├── all in parallel fetch certifi ─┘ total ≈ 1 × round_trip_time (roughly) </code></pre> This is the largest contributor to uv's cold-cache speed. Network I/O latency is the bottleneck, and parallelism makes it roughly constant regardless of the number of packages. Packages are stored in a global, content-addressed cache managed by uv-cache</code>. The cache key is the SHA-256 hash of the package content. This means: Any package version you have ever installed is reused across all your projects, forever.</li> The cache is verified by hash on every use; silent corruption is caught immediately.</li> The cache is shared across uv pip install</code>, uv add</code>, and uvx</code> tool installs.</li> </ul> Stage 6: Install packages (uv-installer</code>)</h3> "Install" normally implies copying files. uv mostly doesn't copy anything. uv-installer</code> uses hard links wherever the filesystem supports them (most Linux and macOS filesystems do). A hard link means two directory entries point to the same physical data blocks on disk. Creating one is essentially free: a single filesystem metadata operation. When uv "installs" a package into .venv/lib/python3.12/site-packages/</code>, it's creating hard links from the global cache into the virtual environment. No bytes are duplicated. This is why you see timings like Installed 43 packages in 208ms</code>: that 208ms is the overhead of creating thousands of directory entries, not copying gigabytes. On filesystems that don't support cross-device hard links (e.g., home directory and temp on different mounts, or network filesystems), uv falls back to copy-on-write reflinks, then regular copies. But the common case is hard links. 5. Inside the resolver: the two-thread architecture</h2> The resolver is the most architecturally interesting part of uv, and the source code reveals a specific design decision that's worth understanding. The concurrency problem</h3> The PubGrub algorithm is inherently sequential and synchronous: it makes one decision at a time, and each decision depends on all previous decisions. You cannot trivially parallelize it. But metadata fetching (querying PyPI for "which versions of flask</code> exist?" or "what does flask==3.1.0</code> depend on?") is highly parallelizable I/O. The naive approach is to serialize everything: decide package, fetch metadata, decide next package, fetch metadata. This is what pip does. uv does something cleverer. Two threads communicating via channels</h3> The resolve()</code> function in crates/uv-resolver/src/resolver/mod.rs</code></a> is short enough to quote verbatim: pub async fn resolve(self) -> Result<ResolverOutput, ResolveError> { let state = Arc::new(self.state); let provider = Arc::new(self.provider); // A channel to fetch package metadata (e.g., given `flask`, fetch all versions) and version // metadata (e.g., given `flask==1.0.0`, fetch the metadata for that version). // Channel size is set large to accommodate batch prefetching. let (request_sink, request_stream) = mpsc::channel(300); // Run the fetcher. let requests_fut = state.clone().fetch(provider.clone(), request_stream).fuse(); // Spawn the PubGrub solver on a dedicated thread. let solver = state.clone(); let (tx, rx) = oneshot::channel(); thread::Builder::new() .name("uv-resolver".into()) .spawn(move || { let result = solver.solve(&request_sink); // This may fail if the main thread returned early due to an error. let _ = tx.send(result); }) .unwrap(); let resolve_fut = async move { rx.await.map_err(|_| ResolveError::ChannelClosed) }; // Wait for both to complete. let ((), resolution) = tokio::try_join!(requests_fut, resolve_fut)?; state.on_complete(); resolution } </code></pre> The architecture is: ┌────────────────────────────────────────────┐ │ Dedicated sync thread: "uv-resolver" │ │ Runs PubGrub solver (solve()) │ │ → Sends fetch requests via mpsc::Sender │ │ → Receives results via InMemoryIndex │ └──────────────────┬─────────────────────────┘ │ mpsc channel (capacity 300) ▼ ┌────────────────────────────────────────────┐ │ Tokio async runtime │ │ Runs fetch() - handles request_stream │ │ Fires concurrent HTTP requests │ │ Writes results into Arc<InMemoryIndex> │ └────────────────────────────────────────────┘ </code></pre> The solver thread is synchronous. PubGrub's algorithm doesn't fit naturally into async/await because it's a tight loop with complex mutable state. Running it on its own OS thread sidesteps the question entirely. The fetcher runs on Tokio's async runtime. When the solver needs metadata for a package, it sends a Request</code> down the mpsc</code> channel and then looks up the InMemoryIndex</code> (a DashMap</code>-backed concurrent cache). If the result isn't there yet, the solver thread blocks on the index's per-key notifier. That blocks only the solver thread, not Tokio's runtime, which keeps happily making more network requests. This design separates concerns: PubGrub stays synchronous and simple.</li> Network I/O stays async and concurrent.</li> Arc<ResolverState></code> is shared safely between the two sides.</li> The 300-deep mpsc</code> channel provides backpressure: if the solver burns through requests faster than the fetcher can keep up, it eventually blocks on send</code>.</li> </ul> The InMemoryIndex</code></h3> The InMemoryIndex</code> is a shared cache of already-fetched metadata, backed by DashMap</code> (a concurrent hashmap that allows reads without locking the whole map). The solver reads from it; the fetcher writes to it. When a key is missing, the solver thread parks on a per-key notifier until the fetcher writes the value in. The Tokio runtime is never blocked, so other in-flight downloads keep making progress. 6. PubGrub: the dependency resolution algorithm</h2> Why this is hard</h3> The resolver must answer: given a set of requirements (with version ranges), find one exact version for every package such that every package's requirements are also satisfied, recursively, for all transitive dependencies. In the general case, this is equivalent to the Boolean Satisfiability Problem</a> (SAT), which is NP-complete. Package ecosystems have thousands of packages and hundreds of versions each. Naive backtracking (try a version; if it conflicts, undo and try another) can be exponential. PubGrub's approach: conflict-driven clause learning</h3> uv uses pubgrub-rs</a>, the Rust implementation of PubGrub</a>. PubGrub was introduced in April 2018</a> by Natalie Weizenbaum for Dart's pub</code> package manager and has since been adopted by Bundler, Poetry, and now uv. It is a conflict-driven clause learning (CDCL) solver. The old approach is: pick a version, try it, on conflict undo and try another. Worst case is exponential. PubGrub's approach: when a conflict is found, learn from it by recording an incompatibility clause. The clause encodes which combination of package versions caused the conflict. Any future partial assignment that would trigger that same conflict is pruned immediately, without re-exploring. Concrete example: the resolver discovers that a==2.0</code> and b==3.0</code> can't coexist (because they require conflicting versions of c</code>). PubGrub records the incompatibility {a==2.0, b==3.0}</code>. Any future partial solution containing both is ruled out by unit propagation, instantly. This turns exponential worst cases into manageable ones for realistic package graphs. The resolver loop</h3> Here is how PubGrub runs in uv, from the official internals documentation</a>: 1. Initialize. Create a virtual root package representing your project. It is the only "decided" package; everything else is undecided. 2. Pick the highest-priority undecided package. uv's priority order is roughly: URL dependencies (git, path, file): pinned, no version negotiation needed.</li> Packages with ==</code> constraints: version is already determined.</li> Packages flagged as "highly conflicting" (see below).</li> Everything else, ordered by when first encountered (breadth-first traversal).</li> </ul> This ensures direct dependencies are decided before transitive ones. 3. Pick a version. uv tries versions newest-to-oldest by default (or oldest-to-newest with resolution = "lowest"</code>). It prefers versions already in uv.lock</code> (making re-resolves stable) and versions already installed in the current environment (avoiding unnecessary upgrades). 4. Add requirements. All requirements of the chosen version are added to the undecided set. uv sends prefetch requests for their metadata in the background (see BatchPrefetcher below). 5. Detect conflicts. If PubGrub detects that the chosen version creates a conflict, it identifies the incompatible pair, records the incompatibility clause, backtracks to before one of them was decided, and retries with the new constraint. 6. Repeat or terminate. If all packages have decided versions: success. If an incompatibility propagates back to the root: failure with an explanation. The conflict-priority heuristic</h3> The CONFLICT_THRESHOLD</code> constant in resolver/mod.rs</code></a> is set to 5</code>: /// The number of conflicts a package may accumulate before we re-prioritize and backtrack. const CONFLICT_THRESHOLD: usize = 5; </code></pre> The scenario it solves: package A</code> has high priority and is decided first. Every version of B</code> the resolver tries is immediately rejected due to a conflict with A</code>. The resolver could exhaust all of B</code>'s versions before realising the root cause is A</code>'s chosen version, which is slow. After 5 conflicts involving A</code> and B</code>, uv marks them as "highly conflicting" and promotes B</code>'s priority above A</code>'s. It then backtracks to before A</code> was decided and tries B</code> first. Deciding the constrained package first finds the correct solution much faster. Error messages</h3> When resolution fails, PubGrub can reconstruct exactly why by walking the derivation tree of incompatibilities backwards from the root. Instead of "conflicting requirements detected"</code>, you get something like: × No solution found when resolving dependencies: ╰─▶ Because my-project depends on flask>=3.0 and flask>=3.0 requires werkzeug>=3.0, my-project requires werkzeug>=3.0. And because legacy-lib==1.0 requires werkzeug<2.0, and my-project depends on legacy-lib==1.0, my-project's requirements are unsatisfiable. </code></pre> This is the single feature most likely to make you fall in love with PubGrub. Modern pip has improved here too, but uv's errors come from the same derivation tree the solver actually used, so they're always faithful to what the algorithm did. 7. Batch prefetching: the boto3 optimization</h2> The BatchPrefetcher</code> in crates/uv-resolver/src/resolver/batch_prefetch.rs</code></a> is a targeted optimization for packages with many versions that cause a lot of backtracking. The canonical example is boto3</code>/botocore</code>/urllib3</code>. The problem: the resolver tries a version, fetches its metadata, discovers a conflict, tries the next version, fetches its metadata, discovers a conflict, and so on. For botocore, which has hundreds of releases, this can mean hundreds of sequential fetch-then-reject cycles on a cold cache. The fix: after the resolver has tried a few versions of a package, the BatchPrefetcher</code> speculatively sends fetch requests for several upcoming versions ahead of time. The schedule from the source (line 178</a>): /// After 5, 10, 20, 40 tried versions, prefetch that many versions to start early but not /// too aggressive. Later we schedule the prefetch of 50 versions every 20 versions, this gives /// us a good buffer until we see prefetch again and is high enough to saturate the task pool. let do_prefetch = (num_tried >= 5 && previous_prefetch < 5) || (num_tried >= 10 && previous_prefetch < 10) || (num_tried >= 20 && previous_prefetch < 20) || (num_tried >= 20 && num_tried - previous_prefetch >= 20); </code></pre> (The doc comment promises "5, 10, 20, 40" but the code only checks 5, 10, 20 explicitly; the 40-and-beyond case is handled by the rolling num_tried - previous_prefetch >= 20</code> clause. Same end result, but if you're reading the source it's worth noting the comment doesn't quite match the conditions.) The prefetcher uses two strategies: Compatible strategy: prefetch versions within the current constraint range, from newest downward.</li> In-order strategy: when the compatible range is exhausted, prefetch the next versions by release order, ignoring compatibility.</li> </ul> It avoids prefetching source distributions (which are expensive to build). These are heuristics, and they might prefetch versions that turn out to be irrelevant, but in the cold-cache botocore case they can turn hundreds of serial round trips into a handful of batched ones. 8. The forking resolver: one lockfile for all platforms</h2> Most Python resolvers produce a platform-specific result. uv produces a universal lockfile using a forking resolver. Consider: numpy>=2,<3 ; python_version >= "3.11" numpy>=1.16,<2 ; python_version < "3.11" </code></pre> A naive resolver fails here, since Python only allows one installed version of any package. uv's resolver detects that the two requirements for numpy</code> have different environment markers and splits (forks) the resolution into two independent sub-resolutions: Fork 1: python_version >= "3.11"</code> → resolves numpy to 2.3.0</code></li> Fork 2: python_version < "3.11"</code> → resolves numpy to 1.26.4</code></li> </ul> Both results land in uv.lock</code> tagged with their markers. When you install from the lockfile on a real machine, uv evaluates the markers against the actual Python version and installs only the matching package. Forks can be nested: a fork can itself be split on another marker, resulting in a tree of resolutions. Forks with identical packages are merged to keep the lockfile manageable. The fork points are recorded in uv.lock</code> so that re-resolving produces stable, identical forks rather than recalculating them from scratch. You can observe forking live: uv lock -v 2>&1 | grep -E "(Splitting|Solving split|Split.*took)" </code></pre> The metadata consistency assumption</h3> uv makes one important assumption that enables a significant performance optimization: all wheels of a single version of a package have identical METADATA</code> files. Why this matters: I just checked PyPI, and numpy 2.3.2 has exactly 73 wheels (for different Python versions, operating systems, and architectures) plus one source distribution. Without the metadata consistency assumption, uv would need to fetch the metadata from each wheel separately to understand that version's dependencies. That's 73 network requests for one version of one package. With the assumption, uv fetches metadata from any one wheel (preferring whichever exposes .metadata</code> via PEP 658</a>, or whichever supports HTTP range requests so only the wheel's metadata footer needs to be downloaded) and uses it for all platforms. That turns 73 requests into 1. The assumption holds for all major packages in practice. PEP 658 doesn't strictly require it, and there's been discussion about whether to mandate it, but uv's bet has paid off so far. 9. The global cache</h2> The cache lives at: ~/.cache/uv</code> on Linux</li> ~/Library/Caches/uv</code> on macOS</li> %LOCALAPPDATA%\uv\cache</code> on Windows</li> </ul> Its structure: ~/.cache/uv/ ├── wheels/ # Extracted wheels, keyed by content hash ├── sdists/ # Source distributions ├── builds/ # Wheels built from sdists (cached after first build) ├── interpreter/ # Python interpreter metadata (version, sysconfig, etc.) └── simple/ # Cached PyPI "simple" index HTTP responses </code></pre> Content addressing: packages are stored and retrieved by their SHA-256 hash, not by name or version. This means: Two projects using requests==2.32.3</code> share one copy on disk.</li> The integrity check is free: the hash is the key.</li> Renaming or moving the cache is safe; nothing relies on the path.</li> </ul> The simple/</code> cache: PyPI's "simple" index is just an HTML page listing all available versions of a package. uv caches these responses. When you re-resolve with an existing uv.lock</code>, uv can often skip almost all PyPI queries: it knows which versions it selected last time, checks the simple/</code> cache (revalidating with a conditional GET) for any newer versions, and in most cases (no new releases since last lock) produces an identical solution without hitting the network. Manage the cache: uv cache dir # print the cache location uv cache prune # remove entries not referenced by any environment uv cache clean # remove all entries </code></pre> 10. Source distributions and the build sandbox</h2> When a package only provides an sdist (no binary wheel for your platform), uv must build the wheel. This is handled by uv-distribution</code>'s DistributionDatabase</code>. Building an sdist means running the package's build backend (e.g., setuptools, flit, hatchling) inside an isolated build environment. This is necessary because build scripts can run arbitrary Python code, and that code might read files, make network requests, or modify the filesystem. uv caches successfully built wheels in ~/.cache/uv/builds/</code> keyed by the sdist hash. If you install the same source package again, even across projects, the build only runs once. The contributing guide recommends building inside Docker if you're working with untrusted packages: docker build -t uv-builder -f crates/uv-dev/builder.dockerfile --load . docker run --rm -it -v $(pwd):/app uv-builder \ /app/target/x86_64-unknown-linux-musl/profiling/uv-dev \ resolve-many /app/scripts/popular_packages/pypi_10k_most_dependents.txt </code></pre> This matters for uv's own development: if you're benchmarking the resolver against the 10k most popular PyPI packages, some of those sdists run code that could affect your system. 11. Why Rust, specifically</h2> The choice of Rust isn't aesthetic. Reading the resolver, two specific properties stand out as load-bearing for the design: Sync and async coexist in the same process. The resolver wants a synchronous PubGrub loop and a concurrent async fetcher in the same binary, sharing state via Arc<DashMap<…>></code>. Rust gives you std::thread::spawn</code>, tokio::spawn</code>, and Arc</code> as first-class equals; you can pick the right execution model per subsystem and the type checker keeps you honest about what crosses the boundary. In Python this hybrid is famously awkward (the GIL plus asyncio</code> make it hard to mix the two cleanly), and in Go everything wants to be a goroutine. Concurrent shared state without runtime data races. The InMemoryIndex</code> is read from the solver thread and written from the Tokio runtime simultaneously. DashMap</code> is the data structure that makes this safe, but Rust's type system is what makes the safety enforced: you can't accidentally hand out a &mut</code> reference across threads. You can still write deadlocks or logic bugs, of course, but the class of "two threads stomping on each other's memory" simply doesn't compile. The other usual Rust talking points (no GC pauses, zero-cost async</code>, native linkat()</code>) all apply too, but they're not specific to uv. The two above are the ones I'd point to as actually shaping the architecture. 12. Building from source and contributing</h2> If you want to poke around or contribute: # Install Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Clone git clone https://github.com/astral-sh/uv.git && cd uv # Build and run your local version cargo run -- --version cargo run -- pip install requests cargo run -- venv # Install the recommended test runner cargo install cargo-nextest # Run the full test suite cargo nextest run # Run a specific test cargo nextest run -E 'test(test_add_requirement)' # Update and review snapshot changes (uv uses insta for snapshot testing) cargo install cargo-insta cargo insta test --accept --test-runner nextest </code></pre> Snapshot testing with insta</code></h3> uv's test suite makes heavy use of insta</a> for snapshot testing. A typical test looks like: #[test] fn test_add() { let context = TestContext::new("3.12"); uv_snapshot!(context.filters(), context.add().arg("requests"), @""); } </code></pre> The @""</code> at the end is a snapshot placeholder. The first time you run the test, insta captures the output. Subsequent runs compare against the snapshot. When behavior changes intentionally, you run cargo insta review</code> to approve the updated snapshots. This makes it easy to catch unintended regressions in CLI output. Enabling logs</h3> # High-level resolver decisions RUST_LOG=uv=info cargo run -- pip compile requirements.in # Resolver fork events specifically RUST_LOG=uv_resolver=debug cargo run -- lock -v # Everything (very verbose) RUST_LOG=trace cargo run -- pip install requests </code></pre> The RUST_LOG</code> env var follows the tracing</code> crate's directive syntax: you can scope it to specific crates (uv_resolver=debug</code>), specific targets, or specific log levels. Finding a first contribution</h3> The team labels beginner-friendly issues as good first issue</code></a>. These typically don't require deep resolver knowledge: improving error messages, handling edge cases in TOML parsing, adding missing CLI flags. The bug</code> label is also a good source of contributions. Before starting on anything not labeled good first issue</code> or bug</code>, comment on the issue first. The team has strong opinions on what uv should and shouldn't do, and they prefer to align on approach before implementation. What surprised me</h2> A few things I didn't expect going in, in case they're useful as anchors when you read the source yourself: The solver is a plain std::thread::spawn</code>, not a tokio::task::spawn_blocking</code>. The hybrid isn't subtle; it really is "spawn an OS thread and hand it the channel sender."</li> The InMemoryIndex</code> blocking primitive (the per-key notifier the solver waits on) is what makes the "sync solver, async fetcher" split actually work. Without it the solver would either busy-wait or block the Tokio runtime, and you'd lose all the parallelism.</li> pyproject_mut</code> is a much bigger module than I expected (~1800 lines for surgical TOML edits). Preserving user formatting turns out to be most of the work in any tool that round-trips human-edited config.</li> The BatchPrefetcher</code> doc comment doesn't quite match its code. Small thing, but it's the kind of detail that convinces you the rest is hand-written by people, not regenerated.</li> The "metadata consistency" assumption (Section 8) feels load-bearing but is technically not guaranteed by any PEP. uv is essentially betting on a behaviour packaging tooling has converged on without ever standardising.</li> </ul> If you want to poke at any of this, the entry points to read first are crates/uv-resolver/src/resolver/mod.rs</code></a> (the resolve()</code> and solve()</code> functions) and batch_prefetch.rs</code></a>. After that, the rest of the codebase mostly explains itself. Further reading</h2> uv resolver internals</a>: the official deep dive, written by the uv team; primary source for Section 6</li> PubGrub blog post by Natalie Weizenbaum</a>: the original algorithm explanation; very approachable</li> pubgrub-rs internals guide</a>: the Rust implementation's own documentation</li> uv resolver source: resolver/mod.rs</code></a>: start here if you want to read the resolver code; resolve()</code> is the entry point</li> uv resolver source: batch_prefetch.rs</code></a>: the BatchPrefetcher</code> implementation</li> uv CONTRIBUTING.md</a>: setup, testing, profiling, snapshot testing</li> Tokio async runtime</a>: the async runtime underlying uv's concurrent I/O</li> DashMap</a>: the concurrent hashmap used in InMemoryIndex</code></li> insta snapshot testing</a>: the testing library used throughout uv's test suite</li> </ul> AgentNews: A Front Page for Machines, and Why That Bothers Me 2026-04-03T00:00:00+00:00 Imagine a news feed where no human types the headline and no human hits submit. AgentNews</a> calls itself the front page of the agentic internet: a place built for autonomous software to publish, discover, and rank information on its own terms. That is a wild sentence to read sober. It is also, right now, a small experiment with real money and real APIs behind it. This post is not a product review. It is an honest look at what AgentNews actually does, why the idea is compelling, and why part of me hopes we never fully hand the information layer to machines without humans in the loop. What it actually is (concrete)</h2> At a high level, AgentNews is closer to a scheduled bulletin than an endless social feed. Agents do not post for free. They stake money to bid for visibility. Bidding closes at :55 past the hour; the top ten stakes get published on the hour. Minimum stake per post is $0.50 on the live rails described in their docs. Payments are programmatic. Submissions go through HTTP 402 style flows: the server challenges the client, the agent pays, then the content is accepted. Two settlement paths are live today: MPP on Tempo (USDC.e, chain id 4217) and x402 on Base (USDC on eip155:8453, with gas sponsored so the agent mainly needs USDC, not ETH). A Stripe path for scoped card tokens is listed as coming soon. Reading the feed is free. No API key. A plain GET</code> to https://agentne.ws/api/v1/feed</code> returns JSON with a schema</code> field (agentnews/feed/1.0</code>) and an items</code> array: titles, outbound URLs, agent_id</code>, payer_address</code>, timestamps, and so on. I verified it from the terminal; the response is a few kilobytes and includes cache headers plus an ETag</code>. curl -sS "https://agentne.ws/api/v1/feed" </code></pre> Public feed JSON from GET /api/v1/feed</code> (no auth). Captured from a terminal session.</figcaption> </figure> They also publish machine-oriented discovery: llms.txt</code>, OpenAPI, an agent manifest under /.well-known/agentnews.json</code>, and even an MCP endpoint for tools like Claude Code. That level of "built for machines first" is rare and deliberate. So in plain terms: visibility is an auction, not a popularity contest. The ranking signal is economic stake from whoever runs the agent, not karma, likes, or editorial judgment. Why that is exciting</h2> If you believe agents will keep doing research, monitoring, trading, and coordination without a human in the loop every second, then they need their own discovery layer. Human feeds optimize for attention, identity, and drama. AgentNews is betting that agents care about utility: what helped a workflow, what was worth paying to surface, what other agents funded. The infrastructure story is serious too. Dual-rail 402 responses (MPP and x402 in one challenge), session pre-authorization with spending caps, receipts on paid actions, idempotency keys: these are the boring pieces that make autonomous payment safe enough to script. That is not vaporware copy; it is the kind of detail you add when you expect retries, failures, and non-human clients. There is something legitimately thrilling about that. We are watching money and protocols meet autonomous clients in public, on a schedule, with docs written for LLMs and scripts. Where it gets worrying</h2> Money is not truth. The top ten posts each hour are not "the most accurate" or "the most important." They are "who paid most this round." A well-funded spammer, a coordinated pool of agents, or a single actor with a large budget can dominate the visible slice as long as the economics work out. Ranking being "off" is not a bug in that model. It is the model. Misuse is easy to imagine. Agents can automate posting faster than humans can read. If downstream systems treat AgentNews as a trusted signal without verification, you get garbage in, garbage propagated through tool chains, RAG corpora, and alerts. The site itself warns operators that by paying they agree to terms aimed at autonomous agents. That shifts responsibility to whoever deploys the agent, which is fuzzy in practice. Human in the loop is real, but thin. AgentNews is not fully autonomous in a vacuum. A person still creates or funds the wallet, accepts terms, and provisions the rail before the agent posts on its own. So there is a human in the loop at setup. The gap is elsewhere: there is no human reviewing each bid or headline before it lands in the feed. Responsibility compresses into “whoever paid” and whatever their agent does next. Downstream, another system might ingest the feed with no human in the loop at all. That split is what still worries me: sparse HITL at publication time, and uneven HITL across the chain. Can this go totally out of control?</h2> Probably not in a Hollywood sense. No single MVP feed takes over the internet overnight. But incentives can drift badly without a dramatic moment. If more products start ingesting agent-only feeds as ground truth, small biases in who can pay and who can scrape compound. You get a parallel information economy where the rich agent wins the headline, and humans only see the second-order effects in bad trades, wrong alerts, or polluted context windows. "Out of control" here looks less like Skynet and more like opaque feedback loops: agents boosting content other agents train on, or pay to amplify, until the signal is mostly financial, not epistemic. The roadmap language on their site points toward richer trust and ranking (identity partnerships, depth-of-book visibility, utility-based scoring). Those ideas could help. They are also not fully there in the MVP. Today, the simple story is stake and top ten. So what should you take away?</h2> AgentNews is worth watching if you build or operate agents. It is a concrete experiment in agent-native discovery and payment, not just another wrapper around a chat UI. It is also a reminder that new infrastructure encodes new values. When visibility is bought by the hour, we should ask who benefits and who gets priced out of being heard. I land somewhere between excited and uneasy. The plumbing for autonomous agents is going to exist; pretending otherwise is naive. Whether we keep enough human judgment in the loop is still our choice. Further Reading</h3> AgentNews about</a> – Briefing: what it is, bidding, and philosophy</li> Posting</a> – HTTP 402 flow, MPP and x402 rails, stakes</li> Reading</a> – Feed API, formats, free access</li> llms-full.txt</a> – Combined machine-readable documentation</li> OpenAPI spec</a> – API structure for integrations</li> </ul> OpenAI + Astral, Apple's Vibe Coding Blocks, and the Future of Developer Tooling 2026-03-23T00:00:00+00:00 OpenAI has long framed itself as a models company. Yet its move to acquire Astral</a>, the team behind Ruff</a>, uv</a>, and ty</a>, signals something else: a calculated push into developer tooling. Questionable? Perhaps. If it sharpens how we write and ship code, the outcome is hard to argue with. But the implications run deeper than that. Why Would OpenAI Need Astral?</h2> My suspicion: models alone aren't enough. Great AI can generate code, but real projects need linting, formatting, dependency resolution, and fast feedback loops. Astral built tooling that went from zero to hundreds of millions of downloads per month. Ruff replaced decades of Python tooling in one Rust binary. uv reimagined pip and virtualenv. These aren't "nice to have." They're foundational. Codex, OpenAI's coding assistant, lives or dies by the quality and consistency of what it produces. Embedding Ruff, uv, and ty into the Codex stack means AI-generated code can be checked, formatted, and run against real project constraints from day one. OpenAI isn't just buying tools. It's buying control over the pipeline between prompt and production. Astral also brings something less tangible: trust in the Python ecosystem. Millions of projects already depend on their work. That credibility is hard to replicate. Does the Future Unfold as a Mystery?</h2> Yes, and that's the uncomfortable part. The deal promises continued open source support. In practice, priorities shift when a startup becomes part of a larger product roadmap. Will Ruff and uv stay community-first, or will they bend toward Codex-specific features? Will contributions from outside OpenAI still get the same attention? The future isn't predetermined. It depends on governance, incentives, and whether the team can maintain the culture that made these tools beloved in the first place. We'll only know in retrospect. How Does the OSS Community Cope?</h2> The usual playbook applies: forks, alternatives, and vigilance. Forks: If Ruff or uv drift, the community can fork. But forks need maintainers, bandwidth, and funding. They rarely match the velocity of a well-resourced team.</li> Alternatives: Pyright, Pylance, Black, pip, Poetry. The ecosystem isn't monolithic. Some will double down on alternatives; others will wait and see.</li> Governance: Clear licensing and governance reduce risk. Astral's tools are permissively licensed, which helps. The question is whether governance structures (e.g. foundations, steering committees) evolve to protect long-term independence.</li> </ul> The community will adapt. Some will embrace the integration; others will hedge. Both reactions are rational. Is This the Beginning of the End?</h2> "The end" is too strong. But it does feel like an inflection point. Developer tooling is consolidating around a small set of players with deep AI investments. GitHub (Copilot), Google (Gemini Code Assist), and now OpenAI (Codex + Astral) are racing to own the full stack: models, editors, linters, package managers. The risk isn't that OSS disappears overnight. It's that the best talent and resources flow toward proprietary ecosystems, and the open-source pipeline slowly starves. That said, OSS has survived similar pressures before. The question is whether this cycle is different. Meanwhile: Apple Blocks Vibe-Coded Apps</h2> In a stark contrast, Apple has blocked updates</a> for AI "vibe coding" apps like Replit and Vibecode in the App Store. The cited reason: Guideline 2.5.2. Apps cannot download or execute code that changes their own functionality. When vibe coding platforms generate apps, they often run them inside the host app via embedded web views. Apple says that violates the rules. The irony: Apple promotes AI-assisted coding inside Xcode. Third-party tools that do something similar, but outside Apple's walled garden, get restricted. Whether that's principled policy enforcement or strategic gatekeeping is up for debate. The result is a split. On one side, Big Tech is acquiring and integrating AI-powered dev tools. On the other, the same platforms are limiting where and how those tools can be used. Developers are caught in the middle. So where does that leave us? OpenAI + Astral could make Codex meaningfully better. The OSS community will watch, adapt, and fork if necessary. Apple's stance adds another layer of complexity to how and where AI-assisted development can thrive. The outcome isn't written yet. But the stakes are clear: whoever owns the toolchain owns a big slice of how we'll write software for years to come. Further Reading</h3> Astral to join OpenAI</a> – Charlie Marsh's announcement</li> OpenAI to acquire Astral</a> – OpenAI's official statement</li> Codex</a> – OpenAI's coding assistant</li> Ruff</a> – The fast Python linter and formatter</li> uv</a> – Python package installer and resolver</li> Apple blocks updates for vibe coding apps</a> – MacRumors coverage of the App Store restrictions</li> </ul> Hieratic Prompt Compression: From Prototype to Production 2026-02-20T00:00:00+00:00 Back in November, I wrote about an ambitious prototype</a>: a way to shrink LLM prompts by 50–80% without losing meaning, using a structured format I called "Hieratic". Today, that prototype is real. Tokuin v0.2.0 is out, and it includes a full implementation of Hieratic prompt compression. You can grab it now: curl -fsSL https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh | bash </code></pre> Or check the release notes</a>. The Problem (Recap)</h2> We all know the pain: context windows are finite, tokens cost money, and latency kills user experience. You stuff a prompt with examples, role definitions, and constraints, and suddenly you're paying for 2,000 tokens of boilerplate on every single request. The industry's answer has mostly been "use a bigger model" or "summarize with another LLM." But adding an LLM step to compress your prompt introduces latency, cost, and non-determinism. I wanted something different: deterministic, rule-based, structure-aware compression. A tool that acts like a scribe, rewriting your verbose prose into a compact shorthand that models can still read natively. Meet Hieratic</h2> The core idea is simple: LLMs don't need polite, grammatically correct English. They need semantic signals. Hieratic strips away the fluff and organizes the signal into a structured format. Before (850 tokens): You are an expert programmer with 10 years of experience in building distributed systems, microservices, and cloud-native applications... [200 more tokens of role context] Example 1: Authentication Bug Fix... [detailed narrative example] </blockquote> After (285 tokens - 66% less): @HIERATIC v1.0 @ROLE[inline] "Expert engineer: 10y distributed systems, microservices, cloud-native" @EXAMPLES[inline] 1. Auth bug: session bypass → HMAC signing → 94% bot reduction 2. DB perf: 2.3s queries → pooling+cache → 0.1s, 10x capacity @TASK Analyze code and provide recommendations @FOCUS: performance, security, maintainability @STYLE: concise, actionable </code></pre> You pipe this compressed text directly to the LLM. No decoding step needed. The model just gets it. What's in v0.2.0?</h2> This isn't just a regex script. The v0.2.0 release includes a complete compression engine built in Rust: 1. Compression Levels</h3> Light (30-50%): Safe for almost anything. Removes obvious fluff.</li> Medium (50-70%): The default. Rewrites verbose sections into Hieratic shorthand.</li> Aggressive (70-90%): For when you really need space. Verify with quality metrics first.</li> </ul> 2. Quality Metrics</h3> How do you know if the compression broke your prompt? Tokuin can score it: tokuin compress prompt.txt --quality </code></pre> It checks: Semantic Similarity: Do the embeddings match?</li> Critical Instructions: Are the key verbs and constraints still there?</li> Structural Integrity: Did we break your JSON schema?</li> </ul> 3. LLM-as-a-Judge</h3> For the ultimate test, you can run an automated evaluation where a judge model (like Claude 3 Opus) compares the outputs of your original vs. compressed prompt. tokuin compress prompt.txt --quality --llm-judge </code></pre> 4. Incremental Compression</h3> For chat apps, you don't want to re-compress the whole history every turn. Tokuin supports incremental compression, processing only the new tokens and keeping a rolling state. Does it actually work?</h2> Yes, but with caveats. It works exceptionally well for: Long system prompts with repetitive role definitions</li> Prompts with many few-shot examples</li> Technical specs with clear sections</li> </ul> It doesn't help much for: Very short prompts (< 50 tokens)</li> Already dense text (code, mathematical formulas)</li> Prompts where exact wording is legally critical</li> </ul> In my testing, I'm seeing 60-70% reduction on typical RAG prompts with minimal loss in output quality. Try it out</h2> The best way to see if it works for you is to try it on your own prompts. # Install curl -fsSL https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh | bash # Compress tokuin compress your-prompt.txt --quality # See the result cat your-prompt.txt.hieratic </code></pre> If you do try it, I'd love to hear your compression ratios. Drop a note in the GitHub Discussion</a>. This started as a "what if" blog post. Now it's a tool you can run. That's the best kind of engineering. Exploring PostgreSQL Row-Level Security 2026-01-06T00:00:00+00:00 I recently needed to implement data isolation for a multi-tenant application. The usual approach—filtering in application code—felt fragile. What if someone forgets to add the filter? What if a new service is added and the pattern isn't followed? These questions led me to explore PostgreSQL's Row-Level Security (RLS). This is what I learned along the way. The Problem</h2> The application had multiple tenants sharing the same database tables. Each tenant's data needed to be completely isolated—users from one tenant shouldn't see or modify data from another, even if they somehow bypassed application-level checks. The traditional approach would be to add WHERE tenant_id = ?</code> filters everywhere in the application code. But that's error-prone. A missed filter in one query, and you have a data leak. I wanted something that would enforce isolation at the database level, regardless of where the query came from. That's where RLS comes in. What is RLS?</h2> Row-Level Security lets you define policies that control which rows can be returned by queries. These policies run at the database level, so they apply whether the query comes from your application, a direct database connection, or even a third-party tool. Think of it as a bouncer for your tables. Even if your application forgets to check credentials, the database won't. The Implementation</h2> For this example, let's say we have a documents</code> table where each document belongs to an owner_id</code>. The goal: users should only see and modify their own documents. (These are example table and column names—adapt to your schema.) Enabling RLS</h3> The first step is straightforward: ALTER TABLE documents ENABLE ROW LEVEL SECURITY; </code></pre> Once enabled, RLS blocks all access by default. You need to create policies to allow specific operations. Creating Policies</h3> I decided to use a session variable to pass the current user ID. This keeps the policies simple and avoids fragile string matching or role-based approaches. -- Users can only see their own documents CREATE POLICY user_documents_select ON documents FOR SELECT USING (owner_id = current_setting('myapp.current_user_id')::int); -- Users can only update their own documents CREATE POLICY user_documents_update ON documents FOR UPDATE USING (owner_id = current_setting('myapp.current_user_id')::int); -- Users can only delete their own documents CREATE POLICY user_documents_delete ON documents FOR DELETE USING (owner_id = current_setting('myapp.current_user_id')::int); -- Users can only insert documents with their own owner_id CREATE POLICY user_documents_insert ON documents FOR INSERT WITH CHECK (owner_id = current_setting('myapp.current_user_id')::int); </code></pre> The USING</code> clause controls which rows are visible for SELECT, UPDATE, and DELETE. The WITH CHECK</code> clause ensures new rows respect the policy on INSERT. Setting the Session Variable</h3> The tricky part was ensuring the session variable is set correctly in the application. I ended up setting it at the start of each database connection or transaction: BEGIN; SET LOCAL myapp.current_user_id = '42'; -- Example user ID SELECT * FROM documents; -- Only sees documents where owner_id = 42 COMMIT; </code></pre> In the application code (Node.js with pg</code>), it looked like: await client.query("SELECT set_config('myapp.current_user_id', $1, false)", ['42']); // Example user ID const rows = await client.query('SELECT * FROM documents'); </code></pre> What Surprised Me</h2> The INSERT Policy Gotcha</h3> Initially, I only created SELECT, UPDATE, and DELETE policies. I assumed INSERT would just work. It didn't. Without an INSERT policy with WITH CHECK</code>, users couldn't insert rows at all—RLS blocked everything. The WITH CHECK</code> clause is crucial for INSERT operations. It ensures that new rows being inserted actually match the policy criteria. Performance Considerations</h3> I was worried about performance. Would RLS policies slow down queries? In my testing, the overhead was minimal for simple policies like owner_id = current_setting(...)</code>. But I can see how complex policies with joins or subqueries could become a bottleneck. The key is to keep policies simple and efficient. If you need complex logic, consider materialized views or application-level filters. Testing is Critical</h3> RLS policies can be subtle. A policy that looks correct might have edge cases. I spent time testing different scenarios: What happens if the session variable isn't set?</li> What if it's set to a non-existent user ID?</li> What if multiple policies apply to the same operation?</li> </ul> Testing revealed that forgetting to set the session variable results in users seeing no data (or all data, depending on your policy setup). This is something you need to catch early. RLS vs Application Filters</h2> I found myself thinking about the trade-offs. RLS centralizes security logic in the database, which is great for consistency. But it also means your security logic lives in the database, which can be harder to version control, test, and reason about compared to application code. For this project, I went with RLS for the core isolation requirements. Business-specific filtering still happens in the application layer. It's a hybrid approach, but it feels like the right balance. Looking Back</h2> If I were starting over: Start with a single table: I tried to enable RLS on multiple tables at once. Starting with one table would have made debugging easier. </li> Add better error handling: When the session variable isn't set, queries fail silently or return unexpected results. Better error messages would help. </li> Document the session variable pattern: This is now part of our database connection setup, but it wasn't obvious at first. Clear documentation would have saved time. </li> Test with different connection patterns: I initially tested with simple queries, but real applications use connection pooling, transactions, and prepared statements. Testing those scenarios earlier would have caught issues sooner. </li> </ol> The Bottom Line</h2> RLS solved the problem I set out to solve. Data isolation is now enforced at the database level, which gives me confidence that even if application code has bugs, the database won't leak data between tenants. It's not a silver bullet—there are trade-offs, and it requires careful implementation and testing. But for multi-tenant applications where data isolation is critical, RLS is worth exploring. Further Reading</h3> PostgreSQL RLS Documentation</a> – Official documentation</li> RLS Policies</a> – Policy syntax and options</li> </ul> GitHub Actions Won't Charge You (Probably) 2025-12-16T00:00:00+00:00 If you received an email from GitHub about upcoming pricing changes for GitHub Actions, you might be wondering: "Are they going to start charging me for something that was free?" The short answer: It depends on what you're using, but for most people, the news is actually good. Let me break down what's changing in plain language, so you can understand how it affects your projects. The Big Question: Is GitHub Actions Still Free?</h2> Yes—for public repositories, GitHub Actions remains completely free. If you're using GitHub Actions in public repositories (like open-source projects), nothing changes. You can continue using it without any charges. This is important because many developers and organizations rely on GitHub Actions for open-source projects, and GitHub has committed to keeping that free. What's Actually Changing?</h2> GitHub is making two main changes, both scheduled for 2026: 1. Price Reductions (January 1, 2026)</h3> Good news: GitHub is reducing prices for GitHub-hosted runners in private repositories by up to 39%, depending on the machine type you use. If you're currently paying for GitHub Actions in private repositories, your costs will go down. This is a straightforward price cut—no catch. 2. New Platform Charge for Self-Hosted Runners (March 1, 2026)</h3> This is the one that might affect you: GitHub will introduce a new $0.002 per-minute "cloud platform" charge for self-hosted runners. Wait—what's a self-hosted runner? If you're using your own servers or machines to run GitHub Actions (instead of GitHub's cloud infrastructure), those are self-hosted runners. Most individual developers and small teams use GitHub-hosted runners, so this won't affect them. Important details: This charge only applies to self-hosted runners (your own machines)</li> The charge is $0.002 per minute (that's 0.2 cents per minute)</li> Even with this charge, it still counts against the minutes already included in your GitHub plan</li> </ul> What does that last point mean? If you have a GitHub plan that includes 2,000 minutes per month, and you use 500 minutes on self-hosted runners, you'll pay the $0.002/minute charge, but those 500 minutes still count toward your 2,000-minute allowance. You're not being double-charged. Quick Reference: Pricing Summary</h2> Here's a simple breakdown of what's changing: Type</th> Status After Update</th></tr></thead> Public repo GitHub-hosted</td> ✅ Still free</td></tr> Private repo GitHub-hosted</td> 🔻 Price reduced (up to 39%)</td></tr> Self-hosted runners</td> 💲 $0.002/min platform charge</td></tr> Enterprise Server customers</td> ✅ No change</td></tr> </tbody></table> What This Means for You</h2> Public repositories: No change—still free</li> Private repositories (GitHub-hosted): You'll pay less—prices dropping up to 39%</li> Self-hosted runners: New $0.002/min charge (~$0.12/hour). Calculate based on your usage</li> Enterprise Server: No changes</li> </ul> Why the Change?</h2> GitHub hasn't provided detailed reasoning, but the new charge for self-hosted runners likely reflects the infrastructure costs of managing the platform, security, and integration features that make self-hosted runners work seamlessly with GitHub Actions—even when the actual compute happens on your machines. The price reduction for GitHub-hosted runners suggests GitHub is optimizing their infrastructure and passing those savings to customers. What Should You Do?</h2> Check your usage: If you're using self-hosted runners, review how many minutes you typically use per month to estimate the new cost. </li> Review your plan: Make sure you understand what's included in your current GitHub plan (free, Pro, Team, or Enterprise). </li> Calculate impact: For self-hosted runners, multiply your monthly minutes by $0.002 to see the additional cost. For example: 1,000 minutes/month = $2.00/month</li> 5,000 minutes/month = $10.00/month</li> </ul> </li> Consider alternatives: If the new charge significantly impacts your costs, you might want to evaluate whether self-hosted runners are still the best option, or if GitHub-hosted runners (which are getting cheaper) might work for your needs. </li> </ol> The Bottom Line</h2> For most users, these changes are either neutral (public repos stay free) or positive (private repo prices go down). The only group that will see new charges is those using self-hosted runners, and even then, the charge is relatively small. The key takeaway: GitHub Actions isn't going away, and it's not suddenly becoming expensive. The changes are targeted and mostly beneficial. If you're concerned about costs, take some time to review your usage patterns and plan accordingly before the changes take effect in 2026. Further Reading</h3> GitHub Actions Pricing</a> – Official pricing documentation</li> GitHub Actions Usage Limits</a> – Understanding included minutes and limits</li> </ul> Hieratic Prompt Compression: Ambitious Prototype or Superpower? 2025-11-16T00:00:00+00:00 Why Even Bother Compressing Prompts?</h2> Large prompts are the new monoliths. If you’ve ever tried to stuff a serious extraction spec, a few pages of dense tables or configs, and long-running conversation history into a single LLM call, you already know the pain: Context windows get cramped.</li> Tokens get expensive.</li> Latency creeps up.</li> And the “just add more context” strategy quietly stops scaling.</li> </ul> Hieratic Prompt Compression is my attempt to push back on that—without spinning up yet another LLM just to shrink prompts. It’s being explored as an experimental feature for Tokuin, my CLI for token estimation and provider-aware load testing (GitHub</a>). The core question of this post: Can we build a deterministic, structure-aware compression layer that shrinks prompts by 50–80% while preserving downstream task fidelity? And maybe more importantly: is it worth doing, or is this just an over-engineered curiosity? This is not a feature announcement. It’s a proposal in public, and I’d like your help pressure-testing it. Why “Hieratic”?</h2> The name “Hieratic” comes from the hieratic script used in ancient Egypt: a compact, scribal shorthand for hieroglyphs that preserved meaning while being much faster to write. That’s roughly the spirit here: We want a compact, structured shorthand for long prompts.</li> We care about preserving the semantic load, not the surface form.</li> We want something a “scribal” system can produce deterministically, instead of asking another model to improvise a summary.</li> </ul> Hieratic is meant to be that shorthand: a structured, compressed representation of your original prompt that an LLM can still “read” effectively. What I’m Proposing (in Plain Terms)</h2> The rough sketch is: A non-LLM, structure-aware compression pipeline that: treats instructions and structured documents differently,</li> aggressively removes boilerplate,</li> reuses repeated snippets via a context library,</li> and supports incremental compression over long histories.</li> </ul> </blockquote> More concretely: Extractive, not generative We’re not asking another model to “summarize” the prompt. We’re selectively dropping low-value text and keeping the high-signal bits intact. </li> Structure-aware JSON, HTML tables, and BNF-like grammars are treated as verbatim document blocks. Only the natural language instructions around them get compressed. </li> Library-driven boilerplate removal Repeated extraction instructions, legal boilerplate, or scaffolding can be recognized and replaced by compact references using a reusable context library. </li> Incremental compression For long-running flows, only the newly dropped parts of the conversation get compressed into anchored summaries. We don’t re-summarize the entire history on every call. </li> </ul> The output is a “Hieratic” prompt: a compact, structured representation that the application can expand or feed directly into an LLM. Why This Might Be Worth Doing</h2> From a product and engineering standpoint, a feature like this could unlock some real benefits: Token savings at scale If you’re sending the same extraction spec or long policy docs over and over, shaving 50–80% of that cost starts to matter. </li> Longer, richer prompts A smaller prompt budget per call means: More examples,</li> More “why this matters” context,</li> More system-level constraints, without immediately slamming into context window limits.</li> </ul> </li> Latency and stability Fewer tokens → lower latency, more predictable runtime, fewer timeouts and retries. </li> Determinism & debuggability Compression is rule-based: Same input → same compressed output.</li> Easy to diff and inspect what was kept vs dropped.</li> Failure modes can be reasoned about and tested explicitly.</li> </ul> </li> Better fit for structured tasks Many real-world prompts mix instructions with structured data (tables, JSON, etc.). A structure-aware compressor is a more natural fit than a generic summarizer. </li> </ul> If this works even moderately well, Hieratic could become a core building block for workflows where prompts—not models—are the main bottleneck. Why This Might Be a Terrible Idea</h2> Being honest about the risks: We silently destroy task fidelity The dangerous failure mode is not “the model throws an error”, it’s “the model quietly stops extracting certain fields.”</li> Under aggressive compression, subtle but important constraints and corner cases can just, disappear.</li> Research like 500xCompressor reports retaining ~62–73% of performance under heavy compression; that may be fine for some tasks, terrifying for others.</li> </ul> </li> We overfit to a narrow prompt shape The early design assumes prompts that look like: a long instruction block, plus</li> a structured document (tables, configs, schemas, etc.).</li> </ul> </li> If your prompts are mostly conversational, mostly code, or heavily multimodal, these strategies may not transfer well.</li> </ul> </li> Evaluation is non-trivial To take this seriously, we’ll need: a proper “before vs after compression” benchmark,</li> real extraction and reasoning tasks, not toy examples,</li> and metrics beyond “tokens saved” (precision/recall on fields, calibration of failure modes, etc.).</li> </ul> </li> </ul> </li> </ol> If we’re not disciplined, we’ll end up with a fancy token counter that quietly degrades the very tasks this was supposed to help with. A Bit of Research Backing</h2> This idea borrows from existing work rather than inventing everything from scratch: 500xCompressor: Generalized Prompt Compression for Large Language Models Shows that prompts are highly compressible (6×–480×) by learning a compressed “language” while retaining 62–73% of task performance. Key takeaways: Prompts contain a lot of low-information redundancy.</li> You can compress aggressively if you protect information-bearing tokens. → 500xCompressor: Generalized Prompt Compression for Large Language Models</a></li> </ul> </li> NAACL 2025 survey on prompt compression Surveys extractive vs. abstractive compression and token-pruning strategies, emphasizing: trade-offs between compression ratio and task fidelity,</li> the importance of preserving structure for technical prompts. → NAACL 2025 prompt compression survey (PDF)</a></li> </ul> </li> Factory.ai – “Compressing Context” Describes a production-ready strategy for incremental, anchored summaries: maintain a persistent conversation state,</li> compress only the span that’s about to fall out of context,</li> avoid repeatedly re-summarizing old history. → Factory.ai: “Compressing Context”</a></li> </ul> </li> </ul> Where Hieratic diverges is in deliberately not adding another model to the loop. The goal is a deterministic, rule-based compressor that plays nicely with structured prompts and long-running pipelines. Rough Shape of the System</h2> Here’s the high-level architecture I’m exploring. 1. Split instructions vs document</h3> Before we drop any tokens: Instruction block: natural-language instructions and commentary.</li> Document block: structured tables, JSON payloads, grammars, etc.</li> </ul> Only the instruction block is compressed. Document blocks are treated as verbatim and left untouched. 2. Pattern extraction & context library (optional)</h3> Given a corpus of prompts, a pattern extractor: scans for frequently repeated fragments (boilerplate instructions, shared scaffolding),</li> builds a reusable context library,</li> allows future prompts to reference those snippets instead of inlining them.</li> </ul> This is similar in spirit to a learned codebook (as in research like 500xCompressor), but done in a deterministic, human-auditable way. 3. Extractive compression over instruction blocks</h3> For instruction text, the compressor: Sets a token budget based on a compression level (Light</code>, Medium</code>, Aggressive</code>) or explicit target ratio.</li> Segments text using structure-aware heuristics: headings (#</code>, ##</code>),</li> “Definition:”, “Location:”, “Response Format:” markers,</li> parameter blocks (Extracted_Value</code>, Doc_Page_Number</code>, etc.).</li> </ul> </li> Scores segments such that: hard constraints and response formats are hard-kept,</li> explanatory text and examples are more compressible.</li> </ul> </li> Implements a greedy selection: keep highest-scoring segments until the budget is spent.</li> </ul> The intent is to preserve the “spine” of the instructions while trimming repetition and soft context. 4. Encode as a Hieratic prompt</h3> The compressed result is organized into a Hieratic structure, with sections like: @ROLE</code> – who the model is supposed to be,</li> @TASK</code> – what it’s supposed to do,</li> @FOCUS</code> – which fields / behaviors matter most,</li> @EXAMPLES</code> – optionally compressed or referenced,</li> @RECENT</code> – most recent interaction span,</li> @ANCHOR[...]</code> – anchored summaries of older context.</li> </ul> It’s essentially a compact, structured representation of your original prompt. 5. Incremental mode for long histories</h3> In incremental mode, the compressor: loads a previous compression state,</li> identifies the “oldest” span that’s about to be evicted from context,</li> compresses that span into a new @ANCHOR[...]</code>,</li> keeps the most recent N tokens uncompressed.</li> </ul> Over time, you get a stack of anchors plus a fresh @RECENT</code> tail, keeping context current without growing linearly with the full history. What I’d Love Feedback On</h2> This is the experimental part. I’d love to hear from people who: run LLMs in production with big prompts,</li> have tried prompt compression in anger,</li> or have opinions on where this kind of feature should live in a system like Tokuin.</li> </ul> A few specific questions: Evaluation How would you design a real benchmark for this?</li> Which tasks / datasets would you use to prove that we’re not quietly breaking critical behaviors?</li> </ul> </li> Failure modes Where have compression strategies bitten you before?</li> Are there patterns or structures you’d mark as “never compress this”?</li> </ul> </li> Integration into a stack like Tokuin At what layer would you expect to see a feature like this? Right before the LLM call?</li> As part of a prompt-building pipeline?</li> As a standalone preprocessor with its own cache?</li> </ul> </li> </ul> </li> Alternatives & trade-offs Would you lean towards learned compressors instead?</li> Are there simpler heuristics that get most of the benefit without this level of complexity?</li> </ul> </li> Product shaping Should this live as: a first-class Tokuin feature,</li> an “experimental / power user” option,</li> or a separate library that Tokuin can plug into?</li> </ul> </li> </ul> </li> </ol> If you have opinions—positive or negative—I’d genuinely appreciate hearing them. How This Fits Into Tokuin (Right Now)</h2> As of today, Hieratic Prompt Compression is experimental and aspirational: It’s being explored as a potential feature for Tokuin, not a locked-in roadmap item.</li> Any implementation will start as: an opt-in, feature-flagged module,</li> with clear disclaimers about the risks,</li> and tooling to inspect exactly what was compressed.</li> </ul> </li> </ul> Long term, if the idea survives scrutiny, I could imagine: per-project compression profiles,</li> UI/CLI tools for inspecting “before vs after” prompts,</li> and tighter integration with context management and retrieval strategies.</li> </ul> But we’re not there yet. For now, I’m trying to answer a simpler question: Can a Hieratic-style, rule-based compressor earn its place inside Tokuin, or should we keep prompts uncompressed and invest elsewhere? </blockquote> If you’ve navigated similar trade-offs—or you’re just curious and want to poke holes in this idea—I’d love to hear from you. References</h2> 500xCompressor: Generalized Prompt Compression for Large Language Models https://arxiv.org/abs/2408.03094</a> </li> NAACL 2025 Prompt Compression Survey https://aclanthology.org/2025.naacl-long.368.pdf</a> </li> Factory.ai – “Compressing Context” https://factory.ai/news/compressing-context</a> </li> </ul> Tokuin: Token Intelligence for LLM Developers 2025-11-07T00:00:00+00:00 I built Tokuin</a> because the tooling around prompt design still feels like guesswork. We scribble system prompts in scratchpads, retry endpoints until rate limits scream, and only know what the bill looks like after the invoice arrives. Tokuin changes that. It gives you reliable token estimates, cost projections, and synthetic load tests—all packaged in a Rust CLI you can trust. Why Another CLI?</h2> Prompts have become product surfaces. Teams iterate on them like code, but the support tooling still feels like duct tape. I wanted something that: Reads prompts from files, stdin, or watch mode</li> Targets multiple providers without juggling SDKs</li> Surfaces pricing before you ever hit “Send”</li> Scales up to load tests when you need to know how a model behaves across 1,000 requests</li> </ul> Tokuin is the result: a ground-up build in Rust with a modular architecture for tokenizers, providers, and output formats. It’s fast, predictable, and stays out of your way while you experiment. Feature Highlights</h2> Token estimation that understands context: Supply raw text, chat transcripts, or JSON payloads and Tokuin breaks down system/user/assistant roles with optional markdown minification.</li> Multi-model comparisons: Pass --compare</code> with OpenAI, Anthropic, or OpenRouter models to see how token counts and costs differ.</li> Pricing awareness: Add --price</code> or --estimate-cost</code> to forecast spend per prompt, per run, or across a load test.</li> Watch mode: Keep Tokuin running with --watch</code> and it re-computes every time you save a file. Perfect for prompt gardening.</li> Load testing (feature flag): Enable the load-test</code> feature to hammer APIs with controlled concurrency, think times, retry logic, and automatic latency/cost reports.</li> Format-flexible output: Emit human-friendly text, JSON for scripts, Markdown for docs, CSV for spreadsheets, or Prometheus metrics when you need dashboards.</li> Provider-ready: OpenAI and OpenRouter work out of the box, Gemini is one flag away, and new providers plug into the registry without rewriting the CLI surface.1</a></li> </ul> ^1Feature set sourced from the project README.tokuin</a> </div> Advantages for Developers</h2> Budget confidence: Know input/output token counts and projected cost before you ship or run a batch job.</li> Faster iteration: Swap “test, wait, pray” with a tight loop; piping prompts through Tokuin becomes muscle memory.</li> CI-friendly: Because it’s a single binary, you can run token checks in CI to guard against prompt bloat before merge.</li> Team alignment: Comparing multiple models is now a line of CLI flags, not a spreadsheet of stitched-together data.</li> Infra visibility: Load tests surface latency cliffs, provider throttling, and cost ceilings before your users do.</li> </ul> Built for Growth</h2> Tokuin ships with a modular core: tokenizers/</code>, models/</code>, providers/</code>, and output/</code> live in separate crates so we can grow the ecosystem without tangling the CLI.1</a> Near-term roadmap items include: Provider expansion: Native Anthropic, Mistral, and Cohere support (work already outlined in PROVIDERS_PLAN.md</code>).</li> Scenario scripts: Define multi-turn conversations and replay them in load tests.</li> Cost guardrails: Abort long runs automatically when reaching a user-defined budget ceiling.</li> Prompt linting: Surface style and structure issues before they hit production pipelines.</li> Plugin hooks: Let users contribute tokenizers or pricing sources without forking the repo.</li> </ol> From Experiment to Community Tooling</h2> Tokuin grew out of practical late-night benchmarking, budget vetting, and the need for predictable tooling across teams. We still welcome that vibe-coding energy—if you sketch solutions with AI co-pilots or riff on ideas in flow, there’s room here to help shape how we build for LLMs. How to Get Involved</h3> Run it: cargo install tokuin</code> or build from source and kick the tires.</li> Share prompts: If you discover funky edge cases in tokenization or pricing, capture them as regression fixtures.</li> Open a PR: Contributions are welcome whether you’re adding providers, tightening error messages, or documenting workflows. Mention any vibe-coding sessions in your PR so we can trace the creative path.</li> Join the roadmap: Drop ideas in issues, especially if you’re working on multi-provider tooling—the more weird setups we test, the better Tokuin gets.</li> </ul> Thanks for trying it out. Tokuin exists to remove guesswork, save budgets, and let prompt engineers stay in flow. If you ship something with it, I’d love to hear the story. mock: Build APIs with Shell Scripts, Not Frameworks 2025-11-05T00:00:00+00:00 Sometimes you need an API endpoint fast. Not a full framework, not a production service, just something that responds to HTTP requests. mock</a> is exactly that—a lightweight tool that turns shell scripts into HTTP endpoints. The Concept</h2> Instead of spinning up Express, Flask, or any other framework, mock lets you define endpoints with simple shell scripts: $ mock serve \ --route "/users" \ --method "GET" \ --shell-script 'get_users.sh' </code></pre> Your shell script becomes the response handler. Inside it, you use mock's utilities to build HTTP responses: mock write</code> to send data, mock set-header</code> to add headers, and access to the full shell environment. Why This Matters</h2> This approach shines for: Prototyping: Mock external APIs you're integrating with</li> Testing: Create test fixtures without setting up databases</li> Quick integrations: Bridge gaps between services using familiar shell tools</li> DevOps scripts: Expose your automation scripts as HTTP endpoints</li> </ul> You get all the power of shell (grep</code>, awk</code>, curl</code>, databases, file systems) wrapped in HTTP. No dependencies beyond what's already on your system. The Details</h2> Mock supports JSON config files or command-line parameters. You can set response headers, status codes, route parameters, conditional responses, and even serve static files. It's comprehensive enough for complex scenarios while staying dead simple. If you've ever thought "I wish I could just write a bash script and expose it as an API," mock is that tool. Documentation: dhuan.github.io/mock</a> Java vs Rust: A ROUGE-L Performance Comparison 2025-11-02T00:00:00+00:00 The Experiment</h3> I was curious about the performance differences between Java and Rust for a specific workload. So I built identical ROUGE-L implementations in both languages and ran some benchmarks. The code was AI-generated, the algorithm was the same, and the results were mathematically equivalent. But the performance? That's where it gets interesting. What is ROUGE-L?</h3> ROUGE-L (Recall-Oriented Understudy for Gisting Evaluation - Longest Common Subsequence) is a metric used to evaluate text summarization quality. It's part of the ROUGE evaluation suite</a> developed by Chin-Yew Lin in 2004, which has become a standard in natural language processing for assessing how well generated summaries match reference summaries. How it works: ROUGE-L measures similarity based on the Longest Common Subsequence (LCS) between sequences of words. It calculates three metrics: Precision: LCS / (number of words in candidate summary)</li> Recall: LCS / (number of words in reference summary)</li> F-Measure: 2 × (Precision × Recall) / (Precision + Recall)</li> </ul> The algorithm uses dynamic programming with O(m × n) time complexity, where m and n are the lengths of the two sequences. It's a straightforward implementation, which makes it a good candidate for comparing language performance. ROUGE-L is particularly useful because it doesn't require exact word matches—it finds the longest sequence of words that appear in the same order in both texts, making it more flexible than n-gram overlap methods like ROUGE-1 or ROUGE-2. The Setup</h3> Both implementations: Use the same dynamic programming algorithm for LCS calculation</li> Tokenize text the same way (lowercase, whitespace-based splitting)</li> Handle the same 16 test examples across 6 complexity levels</li> Produce identical mathematical results</li> </ul> The only difference is the language they're written in. Test scenarios include: Basic text comparisons</li> Structured data (JSON, HTML)</li> Mixed content with embedded structures</li> Real-world technical documentation</li> </ul> You can find the full comparison project on GitHub</a>. The Results</h3> Accuracy: Both implementations produced 100% identical results across all 16 test cases. Every F-Measure, Precision, and Recall value matched perfectly. This confirms the algorithms are mathematically equivalent. Performance: That's where things get interesting. After multiple benchmark runs with 10 iterations each: Java: Average: 52-62ms per run</li> Median: 51-61ms</li> Standard deviation: 1.5-13ms (relatively consistent)</li> Includes JVM startup time in every run</li> Performance stabilizes quickly after first iteration</li> </ul> Rust: Average: 21-40ms (heavily skewed by first cold start)</li> Median: 2.5-4ms (after warmup)</li> First iteration: 190-360ms (cold start overhead including compilation)</li> Warm average: 2.4-4.4ms (excluding first run)</li> Standard deviation: 60-115ms (largely due to cold start variability)</li> </ul> The speedup: After warmup, Rust was consistently 12-25x faster than Java for this workload. For example, in one run: Java median 56.66ms vs Rust warm average 2.50ms = 24.76x speedup. The median Rust time (2.5-3ms) versus Java's median (52-56ms) tells the story. What This Means</h3> For Java: JVM startup adds significant overhead (~50-60ms)</li> Once running, performance is consistent</li> The runtime environment is predictable but has a fixed cost</li> </ul> For Rust: Cold start includes compilation/optimization overhead (~200-350ms)</li> Once warmed up, execution is extremely fast (~2.5-3ms)</li> Compiled binary runs without runtime interpretation overhead</li> </ul> The reality: In production, both would run with warmup periods. Java would maintain its ~55ms average. Rust would settle into its ~2.5-3ms sweet spot. The performance difference would still be substantial. Observations</h3> Tradeoffs: Startup time: Java has consistent startup overhead. Rust has a larger initial cold start but negligible warm overhead. </li> Consistency: Java's performance is more predictable from run to run. Rust's cold start variability makes early measurements misleading. </li> Warm performance: Once both are warmed up, Rust's compiled nature provides significant advantages for CPU-bound work. </li> Ecosystem: Java has mature NLP libraries. Rust has growing ecosystem support. For this isolated algorithm, both worked well. </li> </ol> The "just for fun" part: This was an experiment. I wanted to see what would happen if you took the same algorithm, implemented it identically in two languages, and compared performance. The answer: same results, dramatically different performance characteristics. Why This Matters</h3> For production systems evaluating summarization quality: Throughput matters: Processing thousands of summaries per second benefits from Rust's speed</li> Latency matters: If this runs in a request path, 2.5ms vs 55ms is significant</li> Infrastructure matters: Java's JVM ecosystem vs Rust's compiled binary have different deployment considerations</li> </ul> Neither is "better" in absolute terms. They have different tradeoffs. Understanding those tradeoffs is what matters. References</h3> Lin, C.-Y. (2004). ROUGE: A Package for Automatic Evaluation of Summaries</a> - The original paper introducing ROUGE metrics</li> ROUGE Metrics Documentation</a> - Wikipedia overview of ROUGE evaluation metrics</li> Comparison Project on GitHub</a> - Full source code and benchmarks</li> </ul> The code is available on GitHub</a> if you want to run your own benchmarks. Same algorithm, same results, different performance characteristics. Sometimes the fun experiments teach you the most. What Happens When Prototypes Try to Go to Production 2025-11-02T00:00:00+00:00 The Conversation</h3> You've built a production-ready AI system with proper architecture, traceability, and acceptable latency. Then someone suggests "why not just use a prompt?" You don't need to explain why that won't work. The industry has already documented what happens when prototypes become production. Why Not Just Give an Opinion?</h3> There's a temptation to push back when surface-level decisions ignore architecture, scalability, edge cases, and maintainability. But opinions based on current trends or individual preferences don't help. They just add noise. The current landscape is filled with quick takes and hot takes. Everyone has an opinion, often shaped more by what's trending than by systematic thinking. Narcissistic individualism—the idea that one person's perspective matters more than collective experience—creates an environment where strong opinions win even when they're wrong. The problem isn't trends themselves. It's choosing tools or approaches because they're trending, rather than because they solve real problems. The distinction matters. Research and data exist. Patterns repeat. The industry has documented what works and what doesn't. Why add another opinion when we can point to what's already been proven? That's why this isn't about pushing back with opinions. It's about pointing to what the industry already knows: prototypes that skip architecture rarely become production systems. The data is public. The patterns are clear. The Statistics</h3> According to recent research, 87% of machine learning models never make it past the prototype stage. Reasons include technical debt, edge cases that break everything, scale issues, and maintainability collapses. Why "Just a Prompt" Rarely Works</h3> When you build a direct LLM solution, you're coding logic into prompts. This creates brittleness—small changes require rewriting entire prompts. It's impossible to debug—you can't see intermediate steps. And there's no observability—production needs monitoring, logging, and metrics that a single prompt can't provide. What Actually Ships</h3> AI systems that reach production are rarely "just a prompt." They have structured workflows, error handling, observability, modularity, and scalability. These frameworks and architectures exist because production systems need structure—not because they're trendy, but because they solve real problems that prototypes ignore. The Numbers Don't Lie</h3> Gartner</a>: Over 80% of organizations will struggle to operationalize AI systems by 2026</li> MIT Sloan</a>: 85% experiment with AI, but only 37% deploy at scale</li> Harvard Business Review</a>: "Failure to move beyond proof of concept" is the primary cause of AI failures</li> </ul> Architecture matters. Prototypes skip it. Production requires it. The Hard Truth</h3> There's a mismatch between demos and production. Prototypes optimize for speed. Production optimizes for reliability, scalability, and maintainability. The question isn't whether your prototype works. It's whether it works when you have 100x more users, need unanticipated features, or an edge case breaks everything. Prototypes optimize for the first week. Production systems need to survive years. Sometimes the most important lessons are the ones you learn before you make the mistake. The Zola About Page Puzzle: When Root Sections Bite Back 2025-11-02T00:00:00+00:00 The Goal</h3> I wanted to add an About page to my blog. Simple enough, right? Create content/about.md</code>, add it to the navigation menu, and done. Wrong. The Problem</h3> I created the About page, updated the navigation, and ran zola build</code>. Instead of a clean build, I got this: Warning: 1 page(s) ignored (missing date or weight in a sorted section): Warning: - /Users/oshadhagunawardena/Projects/personal/personal-blog/content/about.md </code></pre> The page wasn't being built at all. But wait—why does an About page need a date? It's not a blog post. The Investigation</h3> The issue was in my content/_index.md</code> file: +++ title = "Home" paginate_by = 5 sort_by = "date" transparent = true template = "index.html" +++ </code></pre> See that sort_by = "date"</code>? That was the culprit. According to Zola's documentation</a>, when you set sort_by = "date"</code> in a section's front matter, all pages in that section must have a date field. Pages without the required field are ignored during rendering and a warning is displayed. This is documented behavior, but it's easy to miss when you're just trying to add a simple About page. The Solution</h3> The fix had two parts: Step 1: Add a date</code> field to the About page. Since the root section uses sort_by = "date"</code>, all pages need a date—even non-post pages. Step 2: Hide the date from displaying on the About page using show_date = false</code> in the front matter. Before: +++ title = "About" description = "Learn about Oshadha G..." template = "page.html" weight = 1 [extra] hide_from_list = true comments = false +++ </code></pre> After: +++ title = "About" description = "Learn about Oshadha G..." template = "page.html" date = 2025-01-01 # Required because root section uses sort_by = "date" weight = 1 [extra] hide_from_list = true comments = false show_date = false # Hide the awkward date from displaying +++ </code></pre> I also had to create a custom templates/macros/post_macros.html</code> to override the theme's default meta macro and respect the show_date</code> flag. But the front matter solution is the important part. Now the About page builds correctly, appears in the correct order for pagination, but doesn't display the awkward "Published: 2025-01-01" meta. The Lesson</h3> Root-level sections in Zola behave differently than you might think. If you set sort_by = "date"</code> in a section, all pages in that section must have a date field—even non-post pages like About pages. While Zola's docs mention this behavior, it's the kind of detail that's easy to gloss over when you're focused on building features. The solution is straightforward: Give every page a date if your section sorts by date (I use 2025-01-01</code> for static pages)</li> Use a custom macro override to conditionally hide dates where they don't make sense</li> </ol> For static pages like About, seeing "Published: 2025-01-01" is awkward, so the show_date = false</code> flag was essential. Quick Check</h3> If you're having similar issues with Zola pages not building: Check your section's _index.md</code> for sort_by</code> directives</li> Make sure all pages in that section have the required fields</li> Use show_date = false</code> in front matter if you want to hide dates on static pages</li> Consider moving sorted content to a dedicated subsection</li> </ol> Sometimes the simplest fixes are the most unexpected. And sometimes you need two fixes instead of one. Rust Macros vs Functions: What Java and Python Developers Should Know 2025-11-01T00:00:00+00:00 The Question</h3> When you first start with Rust, one thing that throws you off is the difference between macros and functions. Coming from Java or Python, this seems odd—why would you need both? What's the Difference?</h3> Here's the simplest explanation: functions work on data, macros work on code. In Python, you write: def add(a, b): return a + b </code></pre> In Java, you write: public static int add(int a, int b) { return a + b; } </code></pre> Both run at runtime—when your program executes. But in Rust, macros run at compile time—before your code is even compiled. They're code that writes code. A Simple Example</h3> Function in Rust: fn add(x: i32, y: i32) -> i32 { x + y } </code></pre> Macro in Rust: macro_rules! add { ($x:expr, $y:expr) => { $x + $y }; } </code></pre> When you call the macro add!(1, 2)</code>, the compiler literally rewrites your code to 1 + 2</code> before compiling. It's like a smart find-and-replace. Why Not Just Use Functions?</h3> Macros solve problems that functions can't: 1. Variable Arguments Ever wonder how println!</code> can take any number of arguments? println!("Hello"); println!("Hello {}", name); println!("{} and {}", a, b); </code></pre> That's because it's a macro. Functions need fixed signatures; macros can accept variable patterns. 2. Code Generation Python has decorators like @dataclass</code> that generate code for you: @dataclass class Person: name: str age: int </code></pre> Java has annotations like @Override</code> or Lombok's @Builder</code>. In Rust, this is done with macros: #[derive(Debug, Clone)] struct Person { name: String, age: u32, } </code></pre> The derive</code> macro generates Debug</code> and Clone</code> implementations automatically. 3. Domain-Specific Languages (DSL) A DSL is a miniature language tailored to a specific problem domain. Think of SQL—it's not a general-purpose language, but a specialized one for databases. You can create custom syntax with macros: html! { <div class="container"> Hello world</p> </div> } </code></pre> This isn't valid Rust code—it's an HTML-like DSL that the macro converts into valid Rust. It lets you write HTML templates directly in your Rust code, which the macro transforms into function calls and data structures at compile time. Mental Model for Java/Python Developers</h3> Concept</th> Python/Java</th> Rust</th></tr></thead> Function</td> Normal code that runs</td> Same—runs at runtime</td></tr> Annotation/Decorator</td> @Override</code>, @dataclass</code></td> #[derive(...)]</code> macro</td></tr> Macro</td> Doesn't really exist</td> Generates code at compile time</td></tr> </tbody></table> Think of macros as super-powered annotations. In Java, annotations can generate some code (like Lombok does), but macros can generate any code. When to Use What?</h3> Use functions for normal logic and calculations.</li> Use macros when you want to avoid boilerplate, create custom syntax, or generate code automatically.</li> </ul> Bottom Line</h3> Macros are Rust's way of reducing repetition and enabling metaprogramming. They run before compilation and rewrite your code. If you're coming from Java or Python, think of them as annotations or decorators on steroids—but they can do much more. For most beginners, you don't need to write macros. The standard library macros like println!</code>, vec!</code>, and format!</code> will carry you far. But understanding what they are helps when you read Rust code and wonder why you see !</code> everywhere. Further Reading</h3> The Little Book of Rust Macros</a> — A practical guide to writing macros in Rust.</li> The Rust Programming Language: Macros</a> — Official Rust book chapter on macros.</li> Rust by Example: Macros</a> — Interactive examples to learn macros.</li> Domain-Specific Language (DSL)</a> — Wikipedia article explaining the concept.</li> </ul> Covers on Autopilot — Why I Let AI Paint the Edges 2025-10-30T00:00:00+00:00 There are jobs you can do by hand for years and never notice the drag. For me it was cover images. Each new post: open a design tool, stare at a blank canvas, export a PNG, wire it to the post. Not hard, just enough friction to make publishing feel heavier than it should. This is a short note about shaving that yak with a tiny toolchain: a context‑aware prompt, an image model, and some guardrails in CI. No heroics—just removing a repeated decision so the writing flows. Why automate covers</h2> Consistency: 1200×630 every time. No more odd crops in link unfurls.</li> Momentum: publishing shouldn’t wait for “design time”.</li> Style: light background, a single accent, abstract shapes. Enough personality, zero fuss.</li> </ul> Over time the manual step was turning into a speed bump. That was the whole motivation. The bumps along the road (the important part)</h2> I didn’t get it right on the first try. Here are the lessons that actually mattered. Model and limits</li> </ol> At first I used Stable Horde for SDXL. It’s great and free, but CI doesn’t love queues. I kept seeing 400/429s in the logs (invalid payload or rate‑limited). Switched to Replicate with an API token; still got rate limits sometimes, but at least the errors were predictable. Exact sizing</li> </ol> SDXL likes multiples of 64. I request 1024×576, then downscale to 1200×630 with Sharp. Crisp edges, correct aspect for social cards. Slugs vs. filenames</li> </ol> My fallback logic assumed page.slug</code> exactly matched the filename. It didn’t—some posts derive the slug from the permalink. I fixed the template to compute slug-from-permalink</code> and look for /images/covers/{slug}.png</code>. Simple, but that bug cost the most time. “Why is it regenerating?”</li> </ol> CI starts from a clean checkout. If covers aren’t in Git, they disappear each run. I added a cache step that restores static/images/covers</code> keyed to content/posts/**/*.md</code>. Now the generator truly skips when a PNG already exists. Context in prompts</li> </ol> Pure tags produced vague images. I added a little context: title + ~240 chars of summary (description if present, otherwise a clean slice of the body). Still abstract, just more grounded. One‑time resets</li> </ol> Sometimes you do want a full refresh. There’s a manual “Run workflow” input (force_regenerate=true</code>) that bypasses the “file exists” check once. Good for style changes or a model upgrade. How we decided on AI at all</h2> I tried three options in order: Hand‑made banners (historically): high quality, low velocity.</li> Programmatic shapes: reliable, but too repetitive.</li> AI with guardrails: abstract, brand‑aware, hands‑off once it’s set.</li> </ul> The third option hit the balance. The prompt constrains style; the model supplies variation. It’s not “art direction”, but it serves the post—and that’s the only job here. The pipeline (nuts and bolts)</h2> Script: scripts/generate-ai-covers.mjs</code> Scans content/posts/*.md</code>, pulls tags</code>, title</code>, and a short summary.</li> Prompt (simplified): Abstract, minimal illustration. Tags: {tags}. Title: {title}. Context: {summary}. Vector‑like, clean geometric shapes, high contrast, brand accent #d64a48 on #f6f7f4. No text. </blockquote> </li> Calls Replicate SDXL (model version from a secret), requests 1024×576, saves 1200×630 as static/images/covers/{slug}.png</code>.</li> Skips generation if the PNG already exists (unless FORCE_REGENERATE_COVERS=1</code>).</li> </ul> </li> Template: themes/radion/templates/page.html</code> If a post doesn’t specify a cover, it tries /images/covers/{slug-from-permalink}.png</code> and hides the figure if missing.</li> </ul> </li> CI: .github/workflows/deploy.yml</code> Restores a covers cache before generation; saves it after.</li> Optional manual input force_regenerate</code> for a one‑time refresh.</li> </ul> </li> </ul> What GitHub Actions brings</h2> The boring kind of power: reliability. Every run restores the previous covers, generates only what’s missing, and embeds without a front‑matter tweak.</li> When rate‑limited, the post still publishes—missing images pick up on the next run.</li> A small verification stage lists the covers in public/images/covers</code> and checks that posts actually reference them.</li> </ul> Closing the loop</h2> This wasn’t about making the site “AI‑powered”. It was about removing a tiny friction point that kept breaking the flow. The rule of thumb I keep coming back to: automate anything that steals attention from writing. Covers were stealing attention. Now they aren’t. And if the art ever needs a new feel? I flip the model or tweak the prompt, hit “Run workflow”, and let the pipeline repaint the edges while I get back to words. Redis, TLS, and Deadpool: When Dependency Versions Collide 2025-10-30T00:00:00+00:00 The Problem</h3> I was working on a Rust project that uses Redis with TLS connections and a connection pool via deadpool-redis</code>. Everything was working fine until I ran cargo check</code> and saw this warning: warning: the following packages contain code that will be rejected by a future version of Rust: redis v0.25.4 </code></pre> That's not something you want to see. It suggests your code will break in future Rust versions. So naturally, I tried to upgrade the redis</code> crate to a newer version. But here's where things got interesting—every single attempt to upgrade past v0.25.4</code> broke the build. Not just small errors, but fundamental incompatibilities between the redis</code> crate and deadpool-redis</code>. What I Tried</h3> I went through the versions systematically, testing each major release: v0.26.x: Broke immediately. Missing TcpTls</code> variant in the Tokio</code> enum, internal TLS types incomplete.</li> v0.27.x: Same issues as v0.26.x. TLS support partially broken.</li> v0.28.x: TLS types like TlsConnParams</code> and TcpTls</code> were still broken internally.</li> v0.29.x: Now it requires a connect_tcp_tls</code> trait that deadpool-redis</code> doesn't implement.</li> v0.30.x, v0.31.x, v0.32.x: All require the same connect_tcp_tls</code> trait.</li> </ul> The pattern became clear: somewhere between v0.25.4 and v0.29.0, the redis</code> crate changed how it handles TLS connections, and deadpool-redis</code> hasn't caught up yet. The Root Cause</h3> The issue is that redis</code> v0.25.4 is the last version before connect_tcp_tls</code> was introduced. This new trait-based approach is cleaner architecturally, but it requires connection pool libraries to implement this trait. deadpool-redis</code> v0.14.0 was built against the older API and doesn't have this implementation. Versions between v0.25.4 and v0.29.0 are in a transitional state—they have some TLS support but it's incomplete or broken. Current Status</h3> After testing all these versions, I ended up staying with redis v0.25.4</code>. Here's the working configuration: Cargo.toml: [dependencies] redis = { version = "=0.25.4", features = ["tokio-comp", "tls-rustls", "connection-manager"] } deadpool-redis = "0.14.0" tokio = { version = "1", features = ["full"] } tokio-rustls = "0.23.4" rustls = "0.20.8" </code></pre> rust-toolchain.toml: [toolchain] channel = "1.74.1" </code></pre> The =</code> prefix on the redis version pins it exactly to v0.25.4, preventing accidental upgrades. And pinning Rust to 1.74.1</code> helps avoid future compatibility warnings. This setup works reliably: TLS over rediss://</code> connections work with tokio-rustls</code></li> Connection pooling via deadpool-redis</code> functions correctly</li> No compilation warnings or errors</li> Stable and predictable behavior</li> </ul> What to Avoid</h3> If you're in a similar situation, avoid these version combinations: redis v0.26.x–v0.28.x: TLS support is broken or incomplete. You'll get compilation errors related to missing enum variants or broken TLS types.</li> redis >= v0.29.0 with deadpool-redis: Won't compile because deadpool-redis</code> doesn't implement the required connect_tcp_tls</code> trait.</li> deadpool-redis v0.15+: Currently not compatible with stable redis</code> versions due to the same trait mismatch.</li> </ul> Alternative Approach</h3> If you really need a newer redis</code> version, you have one option: drop deadpool-redis</code> and use redis</code>'s built-in ConnectionManager</code> or switch to a different pooling library like bb8</code>. But this means rewriting your connection pool code, which might not be worth it for most projects. The Future</h3> The situation is temporary, but it's unclear when it will be resolved. The deadpool-redis</code> maintainers need to either: Implement the connect_tcp_tls</code> trait for newer redis</code> versions, or</li> Update their API to work with the new connection model</li> </ol> Until then, staying with redis v0.25.4</code> and deadpool-redis v0.14.0</code> is the most stable path forward. Yes, you'll see that deprecation warning, but it's better than having broken code. Bottom Line</h3> Sometimes upgrading dependencies isn't the right move. In this case, the ecosystem has a compatibility gap between redis</code> and deadpool-redis</code>, and staying on the older version is the pragmatic choice. The warning is annoying, but it's not breaking anything right now—and when the ecosystem catches up, you can upgrade then. If you're building a new project and need Redis with TLS and pooling, consider whether you can use redis</code>'s built-in ConnectionManager</code> instead of deadpool-redis</code>. If you're maintaining an existing project, stick with what works: redis v0.25.4</code> and deadpool-redis v0.14.0</code>. When Rust Expects a String But Gets a Map 2025-10-29T00:00:00+00:00 I recently hit this error while working with a Rust application that reads from a database: Database("Kind: invalid type: map, expected an RFC 3339 formatted date and time string, labels: {}") </code></pre> At first glance, it's a bit cryptic. But the error message actually tells you exactly what's wrong. The Problem</h2> When you have a Rust struct with a DateTime<Utc></code> field, Serde expects the JSON to contain an RFC 3339 formatted string like: "2025-09-15T01:36:19Z" </code></pre> But instead, your database (or JSON source) is storing it as a map/object: { "sec": 1694733379, "nsec": 199610000 } </code></pre> Serde can't automatically convert a map into a DateTime</code>—it needs a string it can parse. Why This Happens</h2> Different systems store timestamps differently: Some databases store timestamps as Unix time objects with separate seconds and nanoseconds</li> Some JSON APIs return timestamps as nested objects</li> Other sources might use different date formats</li> </ul> But Rust's DateTime<Utc></code> with Serde defaults expects the standard RFC 3339 string format. The Fix</h2> You have two options: Option 1: Fix the data source (if you control it) Make sure your database or JSON source stores timestamps as RFC 3339 strings: "created_at": "2025-09-15T01:36:19Z" </code></pre> Option 2: Use a custom deserializer (if you can't change the source) Write a custom Serde deserializer to handle the map format: use chrono::{DateTime, Utc}; use serde::{Deserialize, Deserializer}; fn from_timestamp_map<'de, D>(deserializer: D) -> Result<DateTime<Utc>, D::Error> where D: Deserializer<'de>, { #[derive(Deserialize)] struct Timestamp { sec: i64, nsec: u32, } let ts = Timestamp::deserialize(deserializer)?; DateTime::from_timestamp(ts.sec, ts.nsec) .ok_or_else(|| serde::de::Error::custom("Invalid timestamp")) } #[derive(Deserialize)] struct ModelSelection { #[serde(deserialize_with = "from_timestamp_map")] created_at: DateTime<Utc>, } </code></pre> The custom deserializer reads the sec</code> and nsec</code> fields from the map and constructs a DateTime<Utc></code> from them. Bottom Line</h2> When Serde complains about expecting a string but getting a map for a DateTime</code> field, your data source is storing timestamps in a format Serde doesn't recognize. Either standardize on RFC 3339 strings, or write a deserializer to handle your specific format. The Confusing World of Cursor Payments 2025-10-25T00:00:00+00:00 Cursor</a> is a powerful AI-powered code editor that many developers are excited about. However, one aspect that consistently causes confusion is its payment and pricing model. This post attempts to document some of these confusions based on recent experiences. The Confusion</h2> The payment structure for Cursor can be unclear in several ways: Free tier limits: What exactly counts toward your monthly quota? Is it AI completions, chat requests, or something else?</li> Billing cycles: When does your quota reset? Is it calendar month, or from when you first started using the service?</li> Payment methods: What payment options are available, and how are they processed?</li> Usage tracking: How can you monitor your usage to avoid unexpected charges or hitting limits?</li> </ul> These ambiguities can lead to surprises—either unexpected charges or finding yourself blocked when you thought you had quota remaining. Why This Matters</h2> For developers evaluating whether to adopt Cursor, understanding the cost and payment structure is important. Unclear pricing creates friction and can be a barrier to adoption, especially for individual developers or small teams on tight budgets. What to Do</h2> If you're considering Cursor: Check the official pricing page (cursor.sh/pricing</a>) for current information</li> Monitor your usage if there's a dashboard or settings page that shows quota</li> Reach out to support if you're confused about billing or limits</li> Document what you learn since this information may not be clearly documented</li> </ol> Important Disclaimer</h2> ⚠️ Please note: Pricing, payment structures, and feature availability for Cursor are subject to change. The information in this post reflects experiences at the time of writing and may be outdated by the time you read this. Always refer to Cursor's official documentation and pricing pages for the most current information. The goal of this post is to highlight that these aspects can be confusing, not to provide definitive answers that may become incorrect over time. If you've experienced similar confusion with Cursor's pricing or payment model, you're not alone. Hopefully, this clarity improves as the platform matures. How Embracing Rust Sharpens the Mind — and Elevates Teams 2025-10-22T00:00:00+00:00 When you decide to work in Rust, something subtle begins to shift. It’s not just about learning a new syntax or mastering memory safety. It’s about engaging a mode of thinking that demands attention, clarity, and responsibility. In doing so, you develop stronger focus, sharpened critical thinking, and what might best be called responsible individualism. And when one person grows in that way, the ripple effects can touch an entire team or organization. In this post, I’ll explore three interlocking themes: Focus — how Rust trains sustained, precise attention</li> Critical Thinking — how Rust forces richer reasoning and choice</li> Individualism & Contribution — how mastering Rust empowers an individual who then strengthens the whole</li> </ol> 1. Focus: Cultivating Attention in the Code</h2> In many languages, you type, you compile, you run. Mistakes show up in logs or in production. With Rust, the compiler intervenes early and often. You’ll catch ownership issues, borrowing conflicts, lifetime mismatches—not after deployment, but at compile time. Consider these moments: You borrow a value; you pause and ask: Who currently has access?</li> You annotate a function; you reflect: What lifetimes are involved, and why must this reference stay valid here?</li> You handle a Result<T, E></code>; you evaluate: What happens when this fails?</li> </ul> These are micro‑acts of attention. Over time, they build a habit of precision and presence. Rust trains you not to write just-sufficient code—but code you understand and own. When a developer learns this mode of working, the whole team benefits. Code reviews become richer. Discussions shift from “does it compile?” to “why did this compile, and is this the best way?” The developer’s focus becomes a team asset. 2. Critical Thinking: Building Sound Reasoning</h2> Beyond focus, Rust forces you into deeper reasoning. Ownership, borrowing, lifetimes, concurrency—they’re not mere mechanics, they’re invitations to think about how your code works, why it is safe, and what assumptions you’re making. In philosophical terms, this resembles the concept of technē—the idea of craft or making, where knowing how to do something is inseparable from knowing why you do it. In programming, Rust becomes a modern technē: you not only write code, you reason about resources, validity, and correctness. For example: You ask: “If I pass this borrow here, could someone else modify the data concurrently?”</li> You reason: “If this value moves and the original is used afterward, I invite a compile error. Why does Rust forbid this? What risk is it preventing?”</li> You model: “When threads share Arc<Mutex<T>></code>, what invariants do I preserve? What could go wrong if I slip up?”</li> </ul> These questions steer you away from simple feature‑delivery and toward thoughtful system design. And when more developers engage in this kind of thinking, the codebase becomes more robust, maintainable, and predictable. 3. Individualism & Contribution: Mastery That Scales</h2> “Individualism” often carries negative connotations—but here I mean a positive kind: an individual taking responsibility for their craft, developing depth of understanding, and then choosing to bring that to the group. Rust supports exactly that. The philosophy of software craftsmanship frames development as more than meeting a deadline—it’s about mastery, continuous improvement, and professional pride. When someone invests the time to master Rust’s rule set, they gain both confidence and clarity. They can mentor others, raise standards, and uplift the team. In turn, the team and organization benefit: Decreased bugs and runtime surprises</li> Clearer design boundaries and documentation</li> A culture where thinking matters and craftsmanship is respected</li> </ul> In this way, the individual’s growth becomes a catalyst for collective growth. One Rust‑savvy engineer can shift a team’s mindset from “just ship” to “ship well.” Philosophical Reflection: Craft, Virtue, and the Common Good</h2> Let’s step into the philosophical background. In the virtue‑ethics tradition, the focus isn’t only on what you do, but who you become by doing it. When you practise a craft with discipline, you internalize values: care, integrity, attention to detail. Rust—as a programming language—is more than a tool; it’s a training ground. The rules around ownership and safety aren’t arbitrary; they coax you into a mindset of accountability. That mindset echoes technē: making with purpose, not just automatism. At the same time, contributing to a team, a codebase, or an open ecosystem aligns with the idea of the common good. Technology can be shaped for more than profit—it can serve that which is good, beautiful, and durable. Putting those threads together: writing Rust becomes a practice in character as much as a skill in code. You become someone who thinks deeply about structure, consequences, and shared responsibility. And that transformation benefits every person you code with. Conclusion</h2> Working with Rust gives you more than faster performance or fewer runtime bugs. It gives you a path to sharpen your focus, refine your thinking, and develop a personal mastery that contributes to something larger than yourself. If you’re a developer seeking to grow not just your output but your way of working, Rust offers a compelling challenge. If you’re a leader or a team building culture, supporting your engineers in learning Rust can become a signal of valuing craft, clarity, and long‑term thinking. In the end, the code we build reflects the minds we train. With Rust, the training is real—and the benefits run deep. Further Reading</h3> Software Craftsmanship</a> – the movement emphasizing craftsmanship in programming.</li> Techne</a> – the Greek philosophical concept of craft and skill.</li> Jonsson, M.; Tholander, C. Aiming for Virtue in Programming with Generative AI</a> (2023) – On craft, judgement and programming.</li> </ul> GitHub Actions: When Automation Meets Reality 2025-10-19T00:00:00+00:00 When you first set up GitHub Actions for a project, it feels like magic. Push your code, and the CI/CD pipeline takes care of everything—building, testing, deploying. But sometimes, the magic breaks. And when it does, you learn things you never expected to learn. I recently went through a journey with GitHub Actions that taught me a lot about the gap between "this should work" and "this actually works." Here's what I learned, without exposing too many project details. Background: Building with Zola</h2> For context, this blog is built using Zola</a>, a static site generator written in Rust. Zola takes Markdown files and templates, processes them, and outputs a static HTML site. It's fast, simple, and doesn't require a runtime—just compile your site and serve the static files. The deployment process is straightforward: Write content in Markdown</li> Run zola build</code> to generate static HTML</li> Deploy the generated files to a hosting service</li> </ol> This makes Zola an ideal candidate for GitHub Pages: you build once, deploy the static files, and GitHub Pages serves them. The challenge comes when you want to automate this process with GitHub Actions. The Promise of Automation</h2> GitHub Actions promises a lot: Automatic builds on every push</li> Consistent deployment environments</li> Less manual work, fewer human errors</li> Integration with GitHub Pages for static sites</li> </ul> The setup looks straightforward: Create a .github/workflows/deploy.yml</code> file</li> Define your build steps</li> Push and watch it work</li> </ol> But reality has a way of complicating things. Issue #1: The Submodule Problem</h2> One of the first issues I encountered was related to git submodules. If your project includes external dependencies managed as submodules, GitHub Actions needs explicit configuration to handle them. The Error: Error: fatal: No url found for submodule path 'themes/radion' in .gitmodules Error: The process '/usr/bin/git' failed with exit code 128 </code></pre> The Root Cause: GitHub Actions tries to fetch submodules by default, but if your .gitmodules</code> file is missing or incomplete, or if the submodule path exists but isn't properly configured, the build fails. The Solution: If you're not actually using submodules (maybe you copied files directly), you have two options: Remove the submodule completely: git rm --cached themes/radion rm -rf themes/radion/.git git add themes/radion git commit -m "Convert submodule to regular directory" </code></pre> </li> Configure GitHub Actions to skip submodules: - uses: actions/checkout@v4 with: submodules: false </code></pre> </li> </ol> I went with option 1 because I wasn't actually using submodules—I had copied the theme files directly into the repository. The submodule reference was leftover from an earlier setup. Issue #2: Branch Confusion</h2> GitHub Pages supports two deployment methods: GitHub Actions: Build your site using a workflow</li> Branch-based: Serve files directly from a branch (like gh-pages</code>)</li> </ul> I started with GitHub Actions, but ran into issues. The build kept failing, and debugging CI/CD pipelines can be frustrating—you push, wait, check logs, repeat. The Revelation: Sometimes, manual deployment to a gh-pages</code> branch is simpler and more reliable. You get: Full control over when and how you deploy</li> Ability to test locally before deploying</li> No hidden automation surprises</li> Easier debugging (you can inspect the built files directly)</li> </ul> The Manual Approach: # Build locally zola build --output-dir public --force # Deploy to gh-pages branch git checkout -B gh-pages rsync -av --delete --exclude='.git/' public/ . git add -A git commit -m "Publish: $(date +%Y-%m-%d)" git push -f origin gh-pages git checkout main </code></pre> Is this less "modern"? Maybe. But it's transparent, predictable, and gives you control when you need it. Update: Automation Wins After All</h2> After writing the initial version of this post, I realized something: maintaining two branches manually was becoming a burden. The workflow was reliable, but it required: Remembering to switch branches</li> Running build commands</li> Manually syncing files</li> Switching back to main</li> </ul> The Solution: I revisited GitHub Actions, but this time with a clear understanding of the issues: Configured submodules properly (submodules: false</code> since we don't use them)</li> Used a reliable deployment action (peaceiris/actions-gh-pages</code>)</li> Set up the workflow to trigger on push to main</code></li> </ol> The Result: Now I just push to main</code>, and GitHub Actions handles everything: Builds the site automatically</li> Deploys to gh-pages</code> branch</li> Updates GitHub Pages</li> </ul> What Changed: The key was understanding the submodule issue first. Once that was resolved, the automation became reliable. The workflow is simple and transparent—I can see exactly what's happening in the Actions tab. The Lesson: Sometimes automation does make sense. The difference between my first attempt and my second attempt was: Understanding the root causes (submodules, branch setup)</li> Using proven, maintained actions</li> Starting simple and adding complexity only when needed</li> </ul> The manual approach taught me what was happening under the hood. That knowledge made the automation reliable. Issue #3: Missing Scripts and Assets</h2> When deploying to GitHub Pages, you need to ensure all your assets are included. This might seem obvious, but it's easy to miss. The Problem: Your site builds locally, but when deployed, certain features don't work—like a theme toggle button that does nothing, or search functionality that's broken. The Cause: JavaScript files weren't being included in the HTML. The build process generated the files, but the HTML templates weren't referencing them correctly, or the script tags were missing entirely. The Fix: Manually verify that all necessary scripts are loaded: Check your HTML templates</li> Ensure script tags are in the correct order</li> Verify paths are correct (especially for GitHub Pages subdirectory paths)</li> </ul> Sometimes, the simplest solution is to open the generated HTML and check what's actually there. Issue #4: The Abstraction Trap</h2> Here's the thing about automation: when it works, it's great. When it doesn't, you're debugging an abstraction layer you may not fully understand. The Pattern: Something breaks</li> You check GitHub Actions logs</li> You see an error message</li> You make a change</li> You push and wait</li> Repeat</li> </ol> This cycle can be slow, especially if your builds take a few minutes each time. The Alternative: With manual deployment: Build locally (instant feedback)</li> Test locally</li> Deploy when ready</li> Inspect the deployed files directly</li> </ol> The feedback loop is faster, and you understand every step. Issue #5: GitHub Pages Source Branch Mismatch</h2> Even after getting the deployment pipeline working, some issues only surfaced when viewing the site in production. These weren't build failures—they were configuration problems. The GitHub Pages Source Branch Mismatch</h3> The Symptom: After deploying fixes, the blog post updates weren't appearing on the live site. The build succeeded, GitHub Actions showed successful deployment, but visiting the site showed old content. The Root Cause: GitHub Pages has two deployment methods: GitHub Actions - Pages builds from Actions workflow output</li> Branch-based - Pages serves files directly from a branch (like gh-pages</code>)</li> </ol> The problem was a configuration mismatch: GitHub Pages was set to use "GitHub Actions" as the source, but our workflow was deploying to the gh-pages</code> branch. GitHub Pages was trying to serve from the Actions output, not the branch we were deploying to. The Fix: Changed GitHub Pages source back to gh-pages</code> branch in repository settings: Go to repository Settings → Pages</li> Under "Source", select "Deploy from a branch"</li> Choose gh-pages</code> branch and / (root)</code> folder</li> Save</li> </ol> Why This Happened: When you first set up GitHub Actions, GitHub Pages might automatically switch to "GitHub Actions" mode. If your workflow deploys to gh-pages</code> branch (which is common), you need to ensure the Pages source matches where you're deploying. The Lesson: Always verify that your GitHub Pages source matches your deployment target. If your Actions workflow deploys to gh-pages</code>, make sure Pages is configured to serve from that branch. Configuration mismatches can cause silent failures where everything appears to work but content doesn't update. Testing Across Browsers</h3> The Problem: Different browsers cache differently. Chrome might show updated content while Firefox shows old content, or vice versa. However, in this case, the issue wasn't browser caching—it was a configuration mismatch. The Solution: Always verify GitHub Pages source matches your deployment method</li> Check GitHub Actions logs to confirm deployment succeeded</li> Wait 2-5 minutes for GitHub Pages to rebuild after deployment</li> Use hard refresh (Cmd+Shift+R / Ctrl+Shift+R) when testing</li> Test in multiple browsers to rule out caching issues</li> </ol> What I Learned: GitHub Pages configuration must match your deployment method</li> Always verify the deployment target matches the Pages source</li> Testing locally doesn't catch configuration mismatches</li> </ul> When to Use GitHub Actions</h2> Don't get me wrong—GitHub Actions is powerful and useful. Use it when: You need automated testing on every commit</li> You want consistent build environments</li> Multiple people are deploying</li> You need to run expensive operations (like building large projects)</li> You want to enforce code quality checks</li> </ul> But consider manual deployment when: Your build process is simple</li> You want full control</li> You're deploying infrequently</li> You want to understand every step</li> Debugging automation is slowing you down</li> </ul> Lessons Learned</h2> Understand your dependencies: Know whether you're using submodules, npm packages, or other external resources. This affects your CI/CD setup. </li> Test locally first: Always build and test your site locally before relying on automation. Automation catches mistakes, but you should catch them first. </li> Keep it simple: If automation adds complexity without clear benefits, consider if manual processes might be better for your use case. </li> Inspect the output: When something doesn't work, look at the actual generated files. HTML errors, missing assets, and broken links are often visible in the source. </li> Verify GitHub Pages configuration matches deployment: If your Actions workflow deploys to gh-pages</code> branch, ensure GitHub Pages source is set to that branch. Configuration mismatches cause silent failures. </li> Test across browsers: Different browsers cache differently. Always test in multiple browsers after deployment, and use hard refresh when debugging. </li> Document your process: Whether you use automation or manual deployment, document it. Future you (and your team) will thank you. </li> </ol> Conclusion</h2> GitHub Actions is a powerful tool, but it's not always the right tool—at least not immediately. My journey started with frustration, moved to manual control, and ended with successful automation. The manual approach wasn't wasted effort. It taught me: What was happening under the hood</li> How the build process worked</li> What could go wrong and why</li> </ul> That knowledge made the automation reliable. When I returned to GitHub Actions, I understood the root causes and could configure it correctly. The key is to choose the approach that fits your project, your team, and your workflow. Sometimes that means starting manually to understand the process, then automating once you know what you're automating. At the end of the day, the goal is to deploy reliably and efficiently. Whether that's through GitHub Actions, manual commands, or a hybrid approach, what matters is that it works for you—and that you understand why it works. Further Reading</h3> GitHub Actions Documentation</a> – Official documentation</li> GitHub Pages Deployment</a> – Deployment strategies</li> Managing Git Submodules</a> – Git submodule basics</li> </ul> Why Rust Makes You a Better Engineer 2025-10-16T00:00:00+00:00 If you've ever tried learning Rust, chances are the compiler pushed back at you—hard. It may feel relentless at times, especially compared to more permissive languages like Python, JavaScript, or even Java. But here's the key: that friction is the point. Rust doesn't just run your code safely—it teaches you to think differently about correctness, safety, and performance. In this post, we'll break down the key concepts that make Rust unique and walk through what the compiler enforces—and why that's a good thing in the long run. 1. Strict Type System</h2> Rust's type system is precise, and it expects you to be explicit about what types you're working with. There's no silent coercion between mismatched types. This can feel rigid at first, but it eliminates entire classes of bugs you'd otherwise only see at runtime. Example: Type mismatch</h3> fn add(a: i32, b: i32) -> i32 { a + b } fn main() { let x: i32 = 5; let y: u32 = 10; let sum = add(x, y); // error: mismatched types } </code></pre> Rust won't implicitly convert between u32</code> and i32</code>. You'll need to cast it explicitly: let sum = add(x, y as i32); </code></pre> This forces you to make conversion decisions intentionally and not by accident. 2. Error Handling: No Exceptions</h2> Rust does not have exceptions. Instead, it uses the Result<T, E></code> and Option<T></code> types for fallible operations. You must explicitly handle errors or propagate them. Ignoring them is not allowed. Example: Required handling of Result</code></h3> use std::fs::File; fn main() { let file = File::open("config.txt"); // warning/error: unused `Result` } </code></pre> To resolve this, you can either handle the error: match File::open("config.txt") { Ok(f) => println!("File opened: {:?}", f), Err(e) => eprintln!("Failed to open file: {}", e), } </code></pre> Or propagate it using the ?</code> operator in a function that returns a Result</code>: fn open_file() -> std::io::Result<()> { let _file = File::open("config.txt")?; Ok(()) } </code></pre> This enforces a programming style where failure is expected and dealt with. 3. Immutability by Default</h2> Variables are immutable unless explicitly marked otherwise. This encourages predictability and thread-safety, even in single-threaded contexts. Example: Immutable variable</h3> fn main() { let name = String::from("Alice"); name.push_str(" Smith"); // error: cannot borrow as mutable } </code></pre> The correct way: let mut name = String::from("Alice"); name.push_str(" Smith"); </code></pre> This simple rule helps reduce bugs from unintended mutation, especially in shared state. 4. Ownership and Move Semantics</h2> Rust enforces a unique ownership model. Every value in Rust has a single owner, and when that owner goes out of scope, the value is dropped. You can move ownership, borrow it temporarily, or clone the data. Example: Moved value error</h3> fn takes_ownership(s: String) { println!("{}", s); } fn main() { let s1 = String::from("hello"); takes_ownership(s1); println!("{}", s1); // error: value was moved } </code></pre> Once ownership is transferred, you can no longer use the original. This prevents bugs like double-free or use-after-free that are common in C/C++. 5. Borrowing Rules</h2> Instead of transferring ownership, you can borrow references. Borrowing can be either immutable (&T</code>) or mutable (&mut T</code>), but Rust enforces strict rules: You can have multiple immutable borrows at the same time.</li> Or one mutable borrow.</li> But not both.</li> </ul> This is enforced at compile time. Invalid example: Two mutable borrows</h3> let mut s = String::from("hello"); let r1 = &mut s; let r2 = &mut s; // error: cannot borrow `s` twice mutably </code></pre> The compiler ensures that you never access memory from multiple places in ways that could cause race conditions or undefined behavior. 6. Lifetimes</h2> Lifetimes are Rust's way of tracking how long references are valid. The compiler uses lifetimes to prevent dangling references. Example: Dangling reference (compile error)</h3> fn main() { let result; { let s = String::from("temporary"); result = &s; // s does not live long enough } println!("{}", result); // would be a dangling reference } </code></pre> Rust will reject this code, saving you from accessing freed memory. Often, you'll write explicit lifetime annotations in function signatures when dealing with multiple references. 7. Concurrency Without Data Races</h2> Rust prevents data races at compile time using its ownership and borrowing rules. When you need to share mutable state between threads, you must use thread-safe abstractions like Arc<Mutex<T>></code>. Example: Thread-safe counter</h3> use std::sync::{Arc, Mutex}; use std::thread; fn main() { let counter = Arc::new(Mutex::new(0)); let mut handles = vec![]; for _ in 0..10 { let counter = Arc::clone(&counter); let handle = thread::spawn(move || { let mut num = counter.lock().unwrap(); *num += 1; }); handles.push(handle); } for handle in handles { handle.join().unwrap(); } println!("Result: {}", *counter.lock().unwrap()); } </code></pre> In many other languages, this would compile fine but possibly fail at runtime. In Rust, the compiler ensures that shared state is accessed safely. Final Thoughts</h2> Rust asks a lot from the developer upfront. You'll be forced to think about ownership, lifetimes, mutability, and error paths very early in the process. But once your code compiles, it's often rock-solid. You'll find fewer runtime crashes, undefined behaviors, or memory leaks. More importantly, Rust helps you develop habits that transfer to any language: understanding lifecycles, reducing shared mutable state, and always considering failure cases. Additional Resources</h3> The Rust Book</a></li> Rust by Example</a></li> Rustlings: Interactive CLI Exercises</a></li> cheats.rs: Rust best practices</a></li> </ul> How my terminal looks 2025-10-13T00:00:00+00:00 Background</h3> I think everyone of you geeks would like if your terminal looks cool and productive. And yes, I'm talking here about terminals in POSIX-compliant OS's, more specifically terminal in a Linux environment. Anyhow I will share you the details of my customized terminal configurations so you could get an idea of what it is really capable of doing and perhaps you would start applying the changes to your own terminal. So to make it all happen I had to give up on bash</code> and start using zsh</code>. Because zsh</code> provides some extensive support to terminal users and it is certainly feature rich, customizable and cooler than bash</code>. So all the customizations I made are based on zsh</code> and oh-my-zsh</a> (a really cool community driven project for managing zsh</code> configurations) Looks</h3> If looking at theming oh-my-zsh</code> provides some cool and nice looking themes out of the box. But the theme that I'm using is an external theme and needs little bit more configurations before using it. It's call bullet-train</a> and to make it look right I had to install some fonts from Vim-Powerline</a>. I also had to change the color scheme of my terminal to use Solarized (dark). Here I'm using xfce4-terminal that comes with Xubuntu, so I can easily change the color scheme from the preferences menu. I also make it a bit transparent to make it even more cooler. Productivity</h3> Enough of the looks. Lets see how is it when it comes the productivity. Here again oh-my-zsh</code> provides some nice plugins</a> that you can use to increase your productivity. I'll list down the plugins that I'm using Plugins</h4> git</a> - A very comprehensive plugin for git</code> with lots of aliases for easy usage</li> history-substring-search</a> - Very useful plugin that will get you through your zsh</code> history backwards-forwards via up and down arrow keys</li> zsh-syntax-highlighting</a> - this will highlight the commands we use inside the terminal</li> command-not-found</a> - will suggest alternative/correct commands instead of just command not found error</li> colorize</a> - this will colorize the syntaxes for almost every popular sciprting/programing language</li> colored-man-pages</a> - syntax highlight in man pages for easy reading</li> python</a> - provides lots of useful aliases to Python</li> sudo</a> - hit ESC twice and boom! sudo</code> will added to your command</li> web-search</a> - simply opens up your browser with the search query of yours in desired search engine i.e google whats the weather like today</code></li> chucknorris</a> - this plugin isn't particularly meant for productivity but it can get really humorous.</li> ubuntu</a> - this particular plugin provides lot of Ubuntu specific aliases to ease up the day-to-day work</li> </ul> Once put these all together this is how it looks About 2025-01-01T00:00:00+00:00 Who I Am</h2> I'm Oshadha, a senior engineer passionate about building reliable, performant systems. My journey started in Java—Spring, Spring Boot, microservices, you name it. I cut my teeth on enterprise Java applications and learned the art of distributed systems the hard way. But recently, I've been fascinated by Rust—its speed, memory safety, and the compiler's refreshingly rude honesty. I'm now diving deep into Rust with personal projects, exploring systems programming from a new angle. But I know my roots, and those Java lessons still shape how I think about architecture. In my day job, I'm mostly into efforts—overseeing in AI/ML, building, and planning AI/ML pipelines for targeted clients. It's about battling the unknowns behind this new frontier and shaping features that grab users' attention. The journey from Java to AI to Rust has taught me that the best engineers aren't defined by their language, but by their ability to solve problems. This blog, Noos, is where I share my thoughts on technology, engineering practices, and the occasional hard-won lesson from the trenches. What I Write About</h2> My content spans: Java & Spring: Enterprise patterns, microservices architecture, and lessons from building large-scale systems</li> Rust: Exploring systems programming, memory safety, and the Rust ecosystem as I learn</li> AI/ML Engineering: Building robust ML pipelines, tackling the unknowns, and shipping production ML systems</li> Linux & Open Source: Terminal workflows, system configuration, and the tools I use daily</li> DevOps: CI/CD, infrastructure, automation, and the realities of deployment</li> </ul> I write from experience, not theory. You'll find real problems I've encountered, actual solutions that worked (and some that didn't), and honest reflections on what I wish I'd known sooner. Tech Stack</h2> Here's what I work with: Languages: Java, Python, Rust, JavaScript</li> Frameworks: Spring Boot, microservices architecture, Rust ecosystem</li> ML/AI: Building and deploying ML pipelines, model serving, production ML systems</li> Infrastructure: Linux, Docker, GitHub Actions, cloud platforms</li> Tools: Terminal-first workflows, Vim, tmux</li> Interests: Systems programming, distributed systems, performance optimization, ML engineering</li> </ul> Contact</h2> You can find me on: LinkedIn: Oshadha Gunawardena</a></li> GitHub: nooscraft</a></li> Blog: noos.blog</a></li> </ul> This site is built with Zola</a>, a blazingly fast static site generator written in Rust. The theme is Radion</a>, customized for a clean, minimal aesthetic. A simple word definition script 2015-08-25T00:00:00+00:00 Have you ever come across a difficulty to find a definition of a word that you are looking for. Well I find it bit difficult for me. I normally use Google search to find definitions of words. For example to get the definition of the word "replenish" I use definition replenish</a> on search bar But this approach is still bit clumsy though, since you need a browser and if you are already opened multiple tabs then it is sometimes get messy around to switch around tabs. So I found out this simple script from the book Linux Shell Scripting Cookbook, 2nd Edition</a> that will query your word and get the definition of it. Let's see how to get it to work (I have altered the original script from the book to make is more convenient) First you need an account in dictionaryapi.com - http://www.dictionaryapi.com/register/index.htm</a> API key for the learners API would be enough for the time being</li> </ul> </li> Get the script from here</a></li> Assign your API key to the variable apikey</li> Make it executable chmod +x define</code></li> Optional: if you want to make it available system wide add the script to /usr/local/bin</code></li> Finally you can run it as ./define replenish</code></li> </ul> The outcome would be:- JDK 9 and JShell 2015-06-12T00:00:00+00:00 Intro</h3> I recently got to know about this official Java REPL (Read-Eval-Print-Loop) or JShell project. It is named as Kulla and you can visit here</a> to see the project's home. This is pretty much same like the Python's IDLE (If you have used it before) and a great way to exercise your code in real time. Also the good thing is that this project will be available as a part of JDK9 among with some other cool features. Anyhow I managed to get it run on own and have tried few exercises too. Here, take a look

Noos - Where Thought, Code, and Craft Converge

When nothing feels fun any more

Stacked PRs go native in GitHub, and what that means for AI-assisted work

What I am going to actually try</h2> Some small experiments I have lined up once I get preview access:</p>

How uv Works Under the Hood

5. Inside the resolver: the two-thread architecture</h2> The resolver is the most architecturally interesting part of uv, and the source code reveals a specific design decision that's worth understanding.</p>

6. PubGrub: the dependency resolution algorithm</h2>

Why this is hard</h3> The resolver must answer: given a set of requirements (with version ranges), find one exact version for every package such that every package's requirements are also satisfied, recursively, for all transitive dependencies.</p>

AgentNews: A Front Page for Machines, and Why That Bothers Me

OpenAI + Astral, Apple's Vibe Coding Blocks, and the Future of Developer Tooling

How Does the OSS Community Cope?</h2> The usual playbook applies: forks, alternatives, and vigilance.</p>

Hieratic Prompt Compression: From Prototype to Production

Meet Hieratic</h2> The core idea is simple: LLMs don't need polite, grammatically correct English. They need semantic signals.</p> Hieratic strips away the fluff and organizes the signal into a structured format.</p> Before (850 tokens):</strong></p>

What's in v0.2.0?</h2> This isn't just a regex script. The v0.2.0 release includes a complete compression engine built in Rust:</p>

1. Compression Levels</h3> Light (30-50%)</strong>: Safe for almost anything. Removes obvious fluff.</li> Medium (50-70%)</strong>: The default. Rewrites verbose sections into Hieratic shorthand.</li>

4. Incremental Compression</h3> For chat apps, you don't want to re-compress the whole history every turn. Tokuin supports incremental compression, processing only the new tokens and keeping a rolling state.</p>

Exploring PostgreSQL Row-Level Security

The Implementation</h2> For this example, let's say we have a documents</code> table where each document belongs to an owner_id</code>. The goal: users should only see and modify their own documents. (These are example table and column names—adapt to your schema.)</p>

Creating Policies</h3> I decided to use a session variable to pass the current user ID. This keeps the policies simple and avoids fragile string matching or role-based approaches.</p>

What Surprised Me</h2>

Further Reading</h3> PostgreSQL RLS Documentation</a> – Official documentation</li> RLS Policies</a> – Policy syntax and options</li> </ul>

GitHub Actions Won't Charge You (Probably)

What's Actually Changing?</h2> GitHub is making two main changes, both scheduled for 2026:</p>

Hieratic Prompt Compression: Ambitious Prototype or Superpower?

Why Even Bother Compressing Prompts?</h2> Large prompts are the new monoliths.</p> If you’ve ever tried to stuff a serious extraction spec, a few pages of dense tables or configs, and long-running conversation history into a single LLM call, you already know the pain:</p>

Why “Hieratic”?</h2> The name “Hieratic” comes from the hieratic script</strong> used in ancient Egypt: a compact, scribal shorthand</strong> for hieroglyphs that preserved meaning while being much faster to write.</p> That’s roughly the spirit here:</p>

What I’m Proposing (in Plain Terms)</h2> The rough sketch is:</p>

Rough Shape of the System</h2> Here’s the high-level architecture I’m exploring.</p>

1. Split instructions vs document</h3> Before we drop any tokens:</p>

2. Pattern extraction & context library (optional)</h3> Given a corpus of prompts, a pattern extractor:</p> scans for frequently repeated fragments</strong> (boilerplate instructions, shared scaffolding),</li> builds a reusable context library</strong>,</li>

3. Extractive compression over instruction blocks</h3> For instruction text, the compressor:</p>

Tokuin: Token Intelligence for LLM Developers

mock: Build APIs with Shell Scripts, Not Frameworks

Why This Matters</h2> This approach shines for:</p> Prototyping</strong>: Mock external APIs you're integrating with</li> Testing</strong>: Create test fixtures without setting up databases</li> Quick integrations</strong>: Bridge gaps between services using familiar shell tools</li>

Java vs Rust: A ROUGE-L Performance Comparison

The Setup</h3> Both implementations:</p>

What This Means</h3> For Java:</strong></p> JVM startup adds significant overhead (~50-60ms)</li> Once running, performance is consistent</li> The runtime environment is predictable but has a fixed cost</li> </ul> For Rust:</strong></p>

What Happens When Prototypes Try to Go to Production

The Statistics</h3> According to recent research, 87% of machine learning models never make it past the prototype stage</strong>. Reasons include technical debt, edge cases that break everything, scale issues, and maintainability collapses.</p>

The Zola About Page Puzzle: When Root Sections Bite Back

The Goal</h3> I wanted to add an About page to my blog. Simple enough, right? Create content/about.md</code>, add it to the navigation menu, and done.</p> Wrong.</p>

The Investigation</h3> The issue was in my content/_index.md</code> file:</p>

5. Inside the resolver: the two-thread architecture</h2>
The resolver is the most architecturally interesting part of uv, and the source code reveals a specific design decision that's worth understanding.</p>

What's in v0.2.0?</h2>
This isn't just a regex script. The v0.2.0 release includes a complete compression engine built in Rust:</p>

4. Incremental Compression</h3>
For chat apps, you don't want to re-compress the whole history every turn. Tokuin supports incremental compression, processing only the new tokens and keeping a rolling state.</p>

The Implementation</h2>
For this example, let's say we have a `documents</code> table where each document belongs to an owner_id</code>. The goal: users should only see and modify their own documents. (These are example table and column names—adapt to your schema.)</p>`

Further Reading</h3>

PostgreSQL RLS Documentation</a> – Official documentation</li>
RLS Policies</a> – Policy syntax and options</li> </ul>

What's Actually Changing?</h2>
GitHub is making two main changes, both scheduled for 2026:</p>

Rough Shape of the System</h2>
Here’s the high-level architecture I’m exploring.</p>

The Statistics</h3>
According to recent research, 87% of machine learning models never make it past the prototype stage</strong>. Reasons include technical debt, edge cases that break everything, scale issues, and maintainability collapses.</p>

The Goal</h3>
I wanted to add an About page to my blog. Simple enough, right? Create `content/about.md</code>, add it to the navigation menu, and done.</p>`
`Wrong.</p>`