~iany/ X

Forwarding Desktop Notifications to Pushover

me@iany.me (Ian Yang) — Tue, 08 Sep 2026 09:00:00 +0800

I already forwarded mako notifications to Pushover on Linux. The hook is tiny: mako runs a command with the notification id, the script reads makoctl list -j, skips loops and Pushover itself, and POSTs to the Pushover API.

Windows has no equivalent of on-notify=exec. I wanted one binary, dn-pushover, that does the same job on both desktops: titles become [DN][hostname] … so a notification that bounces back is easy to drop.

Linux stayed simple. Windows did not.

How it works

Linux. dn-pushover setup writes a managed block into ~/.config/mako/config:

on-notify=exec dn-pushover "$id"

Then it reloads mako. If makoctl is missing, setup fails instead of pretending to work. An old mako-pushover block is migrated so deleting the old binary cannot leave a dead hook behind.

Windows. There is no desktop-wide exec hook. The supported API is UserNotificationListener: after the user grants access, an app can read other apps’ toast notifications. setup therefore:

Checks Pushover credentials.
Builds a small C# WinForms helper (first time only; later setups reuse the exe).
Packs a sparse identity MSIX (manifest + logos; the exe lives next to it via -ExternalLocation).
Signs it and registers it.
Launches the helper. You click Allow Access and accept the Windows prompt.
The helper baselines whatever is already in the notification center, then polls for new toasts and runs dn-pushover --forward with JSON on stdin.

teardown stops the helper. teardown --cleanup also unregisters the package and deletes %LOCALAPPDATA%\dn-pushover. There is no autostart: after logout, run setup again.

The JS side is shared: prefix, truncation, skip [DN] / [mako] / recognizable Pushover traffic, then send().

Gotchas

Linux is a hook. Windows is an identity.

UserNotificationListener is not “read the notification database.” It is a capability on a packaged app. An unpackaged Win32 process can call RequestAccessAsync and even get Allowed while GetNotificationsAsync returns an empty list and Settings never shows the app.

A loose Add-AppxPackage -Register development package (SignatureKind=None) has the same problem. Windows will not list it under Privacy & security → Notifications (the read list, not System → Notifications, which is the send list).

What worked was a signed sparse MSIX whose publisher matches the exe’s app.manifest msix element, with uap3:Capability Name="userNotificationListener" and AppListEntry not set to none.

Signing is not optional, and per-user trust is not enough

Self-signed is fine for a personal machine. The private key stays in CurrentUser\My. Importing the public cert into CurrentUser\TrustedPeople does not make you a public CA; it only means this user trusts this publisher.

MSIX deployment still failed with 0x800B0109 (untrusted root) until the public cert was also in LocalMachine\TrustedPeople. That needs a one-time UAC. Later setups skip the import if the thumbprint is already there.

powershell.exe -NoProfile has no Cert: drive. Import-Module PKI under $ErrorActionPreference = 'Stop' blew up on duplicate type data. Certificate create/import had to use X509Store / CertificateRequest instead of New-SelfSignedCertificate.

The SDK is not the runtime

A .NET 10 runtime cannot dotnet publish. First Windows setup needs a .NET 10 SDK (Scoop: versions/dotnet-sdk-lts) plus Windows SDK tools makeappx and signtool. Setup runs PowerShell with -NoProfile, so Scoop’s shims are not on PATH; it has to look in ~/scoop/apps/dotnet-sdk-lts/current/ itself.

Setup also skips rebuilding if the helper exe already exists, and used to skip re-registering if the package was already installed. That is how a stale unsigned package and an old helper survived “I already ran setup.” teardown --cleanup is the rebuild switch. Signed packages under WindowsApps must actually be removed; if cleanup no-ops, Get-AppxPackage will still show them.

The compiled Bun binary is a different program

import.meta.main is false inside a Bun-compiled .exe. Guarding main() with only that flag made dn-pushover setup exit 0 with no output. Detect the virtual B:/~BUN/ / $bunfs entrypoint as well.

Bun.stdin.text() in that same compiled Windows exe did not read the helper’s piped JSON. --forward exited 0, sent nothing. readStdin() from Node’s process.stdin did. A WinForms AcceptButton also treated the Enter key from the terminal as Allow Access, so setup “returned immediately” after the first successful grant.

Substring /pushover/i on the app id matched DnPushover.NotificationListener and dropped every toast. Skip the Pushover product, not any name that contains those letters.

Debug process

The failure mode was always the same from the outside: a Windows toast appeared, Pushover stayed quiet. The pipeline has three stages; each can succeed while the next never runs.

Is the listener alive? Process + %LOCALAPPDATA%\dn-pushover\listener.log. Empty log with a running process meant polls were not seeing new toasts (or the form was hidden and the timer never ticked). Listener ready; N existing toast(s) means those N will never be forwarded — send a new toast after ready.

Does JS send? Pipe JSON into dn-pushover --forward and watch the Pushover API. A 200 body {"status":1,"request":"…"} means credentials and the API are fine. If that works and the listener still does not, the helper is not invoking the CLI you think it is (config.json points at dist\dn-pushover.exe), or the CLI is skipping the payload.

What did --forward actually do? Temporary logging of argv, stdin length, skip vs send, and the API status. That is how Bun.stdin.text() was caught: argv logged, stdin never read, process exit 0, no HTTP. After the stdin fix, the same toast showed apiStatus: 200. Edge then showed the Pushover copy with a [DN] title; that one is supposed to be skipped so you do not loop.

Direct fetch to https://api.pushover.net/1/messages.json (user key + desktop-notification token, no secrets in logs) is the ground truth. If that returns status: 1 and the device still shows nothing, you are looking at the wrong Pushover app or device, not at this script.

Practical checklist

Linux: makoctl on mako’s PATH; dn-pushover setup; section-specific on-notify rules win over the global hook.
Windows: .NET 10 SDK + Windows SDK; one UAC to trust CN=dn-pushover in LocalMachine\TrustedPeople; dn-pushover setup; click Allow Access; Privacy list is access, not senders.
After changing helper C# or the Bun CLI: teardown --cleanup then setup, and use the rebuilt dist binary.
Test with a toast created after the listener is ready. Expect [DN][hostname] on Pushover.

My AI-Assisted Development Workflow

me@iany.me (Ian Yang) — Mon, 10 Aug 2026 12:45:09 +0800

AI agents write code fastest when the work is sliced small and a human stays on judgment. My workflow runs a four-step loop: plan the feature into units, hand the branch stack to the agent, review each PR myself, then let the agent address my comments.

I wrote a separate guide on the branch-management mechanics: ♯ A Practical Guide to gh-stack for AI-Assisted Development. That post covers worktrees, rebase habits, and JSON sync. This post is the loop around that tool.

1. Plan and split into units

Start with a written plan, not “build the feature.” The plan names the goal, records the product decisions already made, and breaks work into Implementation Units: U1, U2, U3, and so on.

Each unit is small enough to fit one agent session and one human review. Specific, not vague. “Design the data model for board columns” is a unit. “Do the backend” is not. Dependencies between units are explicit – U3 depends on U2 because it queries the schema U2 defines.

Before any code, I do a quick plan review across three axes: product (is this the right thing?), feasibility (can we build it this way?), and scope (are the units the right size?). Fixing a bad unit boundary in a markdown file takes a minute. Fixing it across five stacked PRs takes an afternoon.

When the plan turns out to be wrong mid-implementation, I stop and revise it before writing more code. The plan is the source of truth, not the branches.

2. Let AI manage branches with gh-stack

Once the units are stable, I give the agent one prompt to build the stack:

Implement U1 and U2 from the plan. Use gh-stack to add a branch per unit. Include the Jira ticket number in branch names.

The agent creates branches, writes scoped commits, opens stacked PRs with each PR based on the unit below, and runs gh stack rebase --upstack when a lower layer changes. I do not hand-manage the branch chain day to day.

One worktree per stack, one branch per unit. The gh-stack guide has the full setup for worktrees, branch naming, and how to keep the JSON in sync.

3. Review the PR and leave comments

This step belongs to me.

I read each stacked PR as a focused slice. Small units mean the diff is narrow enough to actually read. I leave inline comments or a review summary – whatever makes the problem clear. I do not fix code during the review pass.

Good review comments say what is wrong, what I want instead, and which layer owns the change. Ambiguous comments waste the next agent session. The review is the quality gate; I treat it like one.

4. Let AI address the review comments

I hand the PR back with a prompt:

Address review comments on PR #42. Stay on the matching stack branch. Add new commits; don’t amend unless I ask.

The agent reads the threads, fixes issues on the correct layer, replies to comments, and resolves what it can. Anything that requires a product call comes back to me. After fixes on a lower layer, it rebases upstack.

Then I re-review or approve and merge bottom-up. One loop per unit. Repeat.

Why this shape works

Step	Owner
Plan and units	Human + agent
Branches and PRs	Agent + gh-stack
Review	Human
Address comments	Agent

Agents do well with bounded units and explicit comment lists. They do worse at deciding where one unit ends and another begins, or at choosing between two product directions. The plan and the review are where those decisions happen – both belong to the human.

The loop: plan → stack → review → fix.

What I Touched This Week 2026-08-08

me@iany.me (Ian Yang) — Sat, 08 Aug 2026 00:00:00 +0000

This journal is generated by AI

Designing With AI: Make a Jig

Jack Cheng’s Designing With AI? Make a Jig names a pattern already appearing in practice: custom-built AI design controls—jigs—that constrain the model so the right move is the easy one.

A jig isn’t a full app; it’s a fixture that holds the work in place while you cut. The same idea applies to AI: fewer free-form prompts, more knobs wired to real values.
Nearby bookmarks this week: DialKit (floating typed controls—sliders, toggles, springs—bound to UI state) and Toolcraft (open-source starter kit for AI design apps).
Also noted: ht-ml.app—POST a single HTML document, get a public URL—hosting shaped for agent workflows rather than humans clicking through a dashboard.

On verification, TDD in the Age of AI is the counterweight to “just let the model cover it.” When the same model writes both tests and implementation, you get the appearance of verification without an independent check. AI-generated tests often become implementation-aware—they assert how the code works rather than what it should do—so keep a human (or a separate process) owning behavior, invariants, and failure cases.

Domain-Driven Design Quickly

I worked through Avram & Marinescu’s Domain-Driven Design Quickly—a short summary of Evans—and captured notes in DOYR on Domain-Driven Design.

Ubiquitous language: build one vocabulary shared by domain experts and developers. Share the model with small diagrams that spotlight one area, then describe that area in the same language—not a separate “tech dialect.”
Layered architecture: keep the domain independent. UI, infrastructure, and application depend on the domain (same dependency direction as Clean Architecture), not the other way around.
Building blocks:
- Entities — mutable objects with identity
- Value objects — immutable; defined by attributes, not id
- Aggregates — entity root plus its relations; the consistency boundary
- Services — operations that span multiple objects/aggregates
- Factories create aggregates; Repositories persist and restore them

Related bookmarks: aggregate-kit (TypeScript DDD primitives) and Khalil Stemmler’s DDD articles.

Learning Is an Output Process

Dan Koe’s thread How to Remember Everything You Read is less about memory tricks and more about what’s worth learning in the first place.

If you need a system to remember something, it probably wasn’t important; if it matters, you’ll remember it because you used it.
Sounding smart comes from understanding, not memorization. Most learning fails for lack of a negative feedback loop.
Learning is an output process: output demands input. Start from a self-generated goal and take the first step toward it; self-education is learning what that goal requires—not hoarding general knowledge to feel productive.

Obsidian Links

What I Touched This Week 2026-08-01

me@iany.me (Ian Yang) — Sat, 01 Aug 2026 00:00:00 +0000

This journal is generated by AI

What Stays Valuable When Copies Are Free

Two readings this week circled the same cultural shift: abundant free copies (and now free AI-generated ones) make the scarce, uncopyable layer matter more—and video-first media weakens the habits that used to build that layer.

Kevin Kelly’s Better Than Free frames eight generative values you cannot pirate: trust, immediacy, personalization, interpretation, authenticity, accessibility, embodiment, and patronage. Trust is the purest case—you can’t buy or duplicate it; it has to be earned over time. Immediacy and personalization are the practical ones: a free copy eventually appears, but a copy in your inbox at release (or tuned to your room, your stack, your workflow) is still worth paying for.
Rose Horowitch’s The End of Reading Is Here is the demand-side mirror. Video packs more raw information than text, yet it does not push deeper thinking. Spoken argument is harder to edit, easier to contradict without notice, and tied to the speaker’s identity rather than to a claim you can hold still and check. Culture also moves more horizontally now—peer to peer—so platform personalities become de facto guardians of taste.

The joint lesson: when the copy is free (or the feed is video), differentiate on what cannot be copied, and keep reading as a tool for claims you can revise.

How Discord Stores Trillions of Messages

On the systems side I went back to How Discord Stores Trillions of Messages—the follow-up to their earlier Cassandra write-up.

They moved toward ScyllaDB: Cassandra-compatible, C++, shard-per-core isolation, no JVM GC pauses, faster repairs. The pitch is workload isolation and predictable latency once message volume leaves the “billions” regime.
Between the API and the clusters sit thin data services: roughly one gRPC endpoint per query, no business logic. The feature that matters is request coalescing—if many users ask for the same row at once, hit the database once and fan out the result.

Same theme as last week’s performance reading: hide duplicate work, keep the hot path boring, and pick storage that fails in ways you can reason about under load.

Stacked PRs with gh-stack and AI Agents

I published A Practical Guide to gh-stack for AI-Assisted Development—the workflow I actually use when a feature is too big for one PR.

One Git worktree per stack so “which stack am I in?” is just the working directory.
Let an agent break the feature into focused layers (schema → service → API → UI) and open one branch per layer; stacked review only works if each slice is coherent.
Day to day: gh stack rebase --upstack. Avoid git commit --amend (gh-stack loses the SHA). For manual reshuffles, rebase from the top with rebase.updateRefs = true.
After squash/amend, .git/gh-stack goes stale—hand an agent the repo and ask it to rewrite each recorded HEAD to match reality.

Related bookmarks this week: ts-pattern for exhaustive matching, and a short note on TypeScript branded types (string & { readonly __brand: unique symbol }) as zero-cost domain IDs.

Obsidian Links

A Practical Guide to gh-stack for AI-Assisted Development

me@iany.me (Ian Yang) — Thu, 30 Jul 2026 07:19:53 +0800

Stacked pull requests let you review a feature in logical slices rather than one enormous diff. The challenge is managing the branches, synchronizing PRs, and surviving rebases without breaking the chain. gh-stack handles the scaffolding. It tracks your branch stack in a local JSON file, generates PRs that base each one to its parent, and works on any GitHub repo regardless of whether your organization has enabled native stacked PR support.

This is the workflow I use, including how an AI coding agent fits into it.

Start with a Worktree

Before creating any branches, set up a dedicated Git worktree for the stack.

git worktree add ../project-login-stack login-stack-base
cd ../project-login-stack

It’s not required but my personal preference. Stacks and worktrees map one-to-one. This matters for a few reasons:

You can switch between stacks by switching directories, not branches.
Your shell’s working directory tells you exactly which stack you’re in.

Using an Agent to Build the Stack

Stacked PRs only work well if the individual branches are focused. Broad, unfocused branches defeat the point. This is where AI agents help.

When starting a feature, describe it to the agent and ask it to divide the work into discrete units. A typical breakdown might look like:

Database layer – schema and migrations
Service layer – business logic and data access
API layer – endpoints and serializers
UI layer – frontend components

The agent creates a branch for each, makes commits scoped to that layer, and stacks them in order. You end up with four focused PRs instead of one that mixes migrations, API code, and React components in the same diff.

Rebasing Without Breaking the Stack

For day-to-day stack updates, use gh stack rebase --upstack. Switch to any branch in the stack using gh stack up/down/switch, add new commits, and gh stack rebase --upstack to reorganize the branch chain. Avoid git commit --amend in this workflow – gh-stack cannot track amended commits.

When you need to manually rebase the stack such as moving commits between branches in the stack, check out the topmost branch and rebase from there. With rebase.updateRefs enabled, Git updates every intermediate branch ref as it replays commits down the chain. Starting from a middle branch leaves the branches above it with stale refs.

# ~/.gitconfig or repo .gitconfig
[rebase]
updateRefs = true

gh stack top # top of the stack
git rebase -i develop

Prefer gh stack rebase --upstack for the common case. Reserve manual git rebase from the top for when you need to move commits between branches in the stack.

The JSON Sync Problem

gh-stack records branch metadata in .git/gh-stack. When you squash or amend commits, or rebase from a middle layer, the SHA that gh-stack recorded no longer matches the branch’s actual HEAD. The JSON goes stale and breaks most features of gh-stack

The fix is to sync the JSON with the current state of your branches. Doing this manually means running git log --oneline for each branch, reading the current SHAs, and editing the JSON to match. Not difficult, but tedious – especially across a deep stack.

An AI assistant handles this well. Give it access to the repository and ask:

Read the current HEAD of each branch in my gh-stack and update .git/gh-stack so each entry’s recorded SHA matches.

Putting It Together

Stacked PRs reduce review friction. gh-stack makes stacking practical without requiring GitHub-side configuration. The four habits that make it work:

One worktree per stack. Isolation by directory, not branch.
Agent-planned stacks. Focused units make PRs reviewable.
gh stack rebase --upstack for routine updates. Manual git rebase from the top when moving commits between branches in the stack.
AI-assisted JSON sync. Fast recovery after a squash or amend.

Build an MCP with OAuth on Cloudflare Workers

me@iany.me (Ian Yang) — Fri, 24 Jul 2026 19:48:12 +0800

I wanted MCP clients to create Google Tasks for me. The Google Tasks API requires a Workspace-style setup I don’t have. IFTTT already bridges webhooks to Google Tasks—but a Maker webhook URL is itself the credential. Storing that key in local MCP config is a bad idea.

The fix is a thin Cloudflare Worker plus Cloudflare Access Managed OAuth:

Worker holds the IFTTT key as a secret and speaks MCP over HTTP
Access sits in front, handles OAuth login with your IdP
Worker verifies the Access JWT (Cf-Access-Jwt-Assertion) before running tools

The full example: doitian/google-task-ifttt-webhook-mcp. Most of it was scaffolded by AI; the interesting part is the structure, not the TypeScript.

The problem

Piece	Constraint
Google Tasks API	Needs a Workspace-style setup I don’t want to pay for
IFTTT Maker webhook	Works, but the URL is the credential
MCP clients	Expect remote HTTP tools with OAuth

MCP Client
→ Cloudflare Access (OAuth)
→ Worker (JWT)
→ IFTTT
→ Google Tasks

Clients never see IFTTT_MAKER_TASK_KEY. They only hold a short-lived Access token after login.

IFTTT side

One applet:

If: Maker Webhooks → Receive a web request, event name task
Then: Google Tasks → Create a task (title / notes / due from the payload)

The Worker posts to:

https://maker.ifttt.com/trigger/task/json/with/key/{KEY}

with { "title", "notes?", "due?" }. The key never leaves Cloudflare.

Three secrets

npx wrangler secret put IFTTT_MAKER_TASK_KEY
npx wrangler secret put CF_ACCESS_TEAM_DOMAIN
npx wrangler secret put CF_ACCESS_AUD

Secret	Role
`IFTTT_MAKER_TASK_KEY`	Maker webhook key
`CF_ACCESS_TEAM_DOMAIN`	Zero Trust team domain (e.g. `myteam.cloudflareaccess.com`)
`CF_ACCESS_AUD`	Access application audience tag (validates JWT `aud`)

No custom authorize page, no signing keys you mint yourself. Access is the authorization server.

Cloudflare Access

In the Zero Trust dashboard:

Access → Applications → Add → Self-hosted
Point the app at your Worker hostname (*.workers.dev or a custom domain)
Pick an IdP (Google, GitHub, email OTP, …) and an allow policy for yourself
Enable Managed OAuth (Beta)—this is what MCP clients need for the OAuth dance
Copy the team domain and Application Audience (AUD)

Access issues JWTs; MCP clients send them as Cf-Access-Jwt-Assertion. The Worker verifies with the team’s JWKS:

const JWKS = createRemoteJWKSet(
new URL(`${issuer}/cdn-cgi/access/certs`),
);
await jwtVerify(token, JWKS, {
issuer,
...(env.CF_ACCESS_AUD ? { audience: env.CF_ACCESS_AUD } : {}),
});

(jose on Workers with nodejs_compat.)

Worker: just MCP + verify

The business logic is small:

POST / or POST /mcp—JSON-RPC (initialize, tools/list, tools/call)
One tool: create_google_task (title required; notes, due optional)
Reject anything without a valid Access JWT

No OAuth endpoints in the Worker. Access owns login; the Worker only checks the assertion header.

Client config

Point the client at the Worker URL and enable OAuth. Example structure (keys vary by client):

{
"mcp": {
"google-tasks": {
"type": "remote",
"url": "https://google-task-mcp.yourdomain.com"
}
}
}

The client discovers OAuth via Access, opens the browser for your IdP, then attaches the Access JWT on MCP calls.

Why this structure works with AI

The task decomposes cleanly:

MCP handler—fixed JSON-RPC + one tool schema
IFTTT fetch—secret from env
Access JWT verify—JWKS + aud
Wrangler secrets—nothing in git

Describe the constraints (“don’t expose the IFTTT URL”, “Cloudflare Access OAuth”, “Worker MCP”) and get a deployable skeleton. Review JWT verification and secret handling; treat the tool body as glue.

Takeaways

Skip the official Tasks API if IFTTT already has the integration.
Keep Maker keys in Worker secrets, not client config.
Cloudflare Access Managed OAuth turns IdP login into MCP-friendly OAuth without requiring custom authorize/token endpoints.
The Worker only needs to verify Cf-Access-Jwt-Assertion and call IFTTT.

Source: github.com/doitian/google-task-ifttt-webhook-mcp.

What I Touched This Week 2026-07-18

me@iany.me (Ian Yang) — Sat, 18 Jul 2026 00:00:00 +0000

This journal is generated by AI

A Week of Performance and Scaling Reading

I kept a pace of three performance articles a day, and a clear map of the field emerged: nearly every technique is a variation on reserve headroom, spread load evenly, and hide latency you can’t remove.

Rate limiting starts with the request rate limiter as the most important defense against abuse, built on the token bucket algorithm: take a token per request, drip tokens back in, reject when empty. Stripe also runs a concurrency limiter (“only 20 requests in progress at once” rather than “1000 per second”), always reserves capacity for critical requests, and sheds low-priority traffic (test mode first) when workers get busy. The recurring lesson: build a kill switch so you can turn any limiter off.
Load balancing has a subtle trap. Netflix’s edge rework notes that join-the-shortest-queue works for a single balancer but causes herding across a cluster—every balancer piles onto the same idle server. The fix is choice-of-two plus combining data sources: the client is the best judge of latency, the server the best judge of its own utilization, and stats should decay to zero over time so stale readings don’t linger.
Caching and perceived speed cover the other half. Facebook’s Cache Made Consistent shows why a version field alone can’t fix cache races—the version that resolves a conflict can itself be evicted before the stale write arrives. On the client side, Instagram’s predictive prefetching and optimistic UI patterns share one principle: when latency is unacceptable but access patterns are predictable, switch from pull to prediction—prefetch on hover, slide in the cart before the API responds, and accept some wasted work in exchange for eliminating latency on the hits.

This reading also fed straight into work: the ApiHistory backfill script I wrote this week used async-sema as its concurrency limiter, and I bookmarked DataLoader after reading Shopify on solving GraphQL’s N+1 problem through batching.

Learning by Writing

A second thread ran through the week: how to actually think, rather than just accumulate information. Holden Karnofsky and Henrik Karlsson converge on the same counterintuitive advice—commit to a claim early, on purpose, so you have something to break.

In Learning by Writing, Karnofsky forms a hypothesis “long before I’m qualified to have an opinion,” then reads to change his mind rather than to gather facts. He rarely reads a document start to finish; he skips energetically to the parts most likely to overturn his current view. Writing early forces you to pin down the version of the claim you care most about.
His companion piece, Minimal-Trust Investigations, is the discipline of occasionally suspending trust in others’ judgment and digging into a question until you can keep pace with experts on that narrow slice.
Karlsson’s How to Think in Writing supplies the mechanism: push yourself to make definite positive claims, because ambiguity lets ideas stay fluid and dodge scrutiny. Unfolding a claim into an explanation spreads it on a “wider front” so criticism has more targets. Seeing your ideas crumble is the point—“it is in the cracks the light shines in.”

Obsidian Links

What I Touched This Week 2026-07-11

me@iany.me (Ian Yang) — Sat, 11 Jul 2026 00:00:00 +0000

This journal is generated by AI

Two Ways to Kill Serverless Cold Starts

Two platform teams attacked the same problem—the latency spike when a serverless function boots from zero—from opposite ends of the architecture.

Vercel’s Scale to One: How Fluid Solves Cold Starts rejects scale-to-zero outright: Fluid always keeps at least one function instance running, so the platform scales to one instead of zero.
Fluid also rethinks the one-instance-per-request model: each function instance serves many concurrent requests, so bursts of traffic no longer translate into bursts of cold boots.
Cloudflare’s Eliminating Cold Starts 2: Shard and Conquer builds on their earlier trick of pre-warming a Worker during the TLS handshake of its first request—the handshake round-trips buy enough time to load the isolate before the actual HTTP request arrives.

Speed Over Consistency: Data Stores at Netflix and Discord

Two classic production write-ups showed how large services deliberately trade strict consistency for speed and availability, then engineer around the sharp edges.

Netflix’s Ephemeral Volatile Caching in the Cloud describes EVCache as a best-effort cache: the architecture chooses speed over consistency, and every dependent application must tolerate stale data.
The EVCache client is AWS zone-aware: writes and deletes replicate to the EVCache servers in every zone, while reads stay in the client’s own zone for latency. The Java client, built on spymemcached, handles discovery and cluster membership changes automatically.
Discord’s How Discord Stores Billions of Messages picked Cassandra because nodes can be added linearly and lost without impact—and captures a culture principle worth stealing: build quickly to prove out a feature, but always with a path to a more robust solution.
The best mental model for Cassandra is a KKV store: the partition key locates the node and disk position, the clustering key sorts rows within the partition—a partition is an ordered dictionary.
Two production gotchas stood out: writing null to a column generates a tombstone just like a delete (their 16-column schema averaged 4 set values, so most writes created 12 pointless tombstones—fixed by writing only non-null values), and queries over empty time buckets had to be tracked and skipped to avoid full scans on quiet channels.

Grit: Optimism, Parenting, and the Effort–Reward Connection

Continued through the later chapters of Angela Duckworth’s Grit, which move from the psychology of hope to how grit is grown in others.

The lesson on setbacks: don’t overreact—step back, analyze, and learn from them, but stay optimistic. Explaining adversity as permanent and pervasive turns minor complications into catastrophes; the seminal learned-helplessness experiments showed it isn’t suffering that leads to hopelessness, but suffering you think you can’t control.
What didn’t kill the young rats—when they could control what was happening by their own efforts—made them stronger for life. Direct experience of the connection between effort and reward matters: without it, animals and people alike default to laziness.
On parenting for grit: wise parents are child-centered without believing children are always the best judge of how hard to work or when to quit, and their authority rests on knowledge and wisdom rather than power.
The uncomfortable mirror: if you want a gritty child, first ask how much passion and perseverance you have for your own goals, and whether your parenting invites the child to emulate you.
The best coaching engineers situations slightly outside the comfort zone—far enough to stretch, close enough to reach.

Obsidian Links

What I Touched This Week 2026-07-04

me@iany.me (Ian Yang) — Sat, 04 Jul 2026 00:00:00 +0000

This journal is generated by AI

Dimensional Modeling Meets the Open Lakehouse

The bulk of this week’s reading was data engineering: Kimball’s The Data Warehouse Toolkit delivered over a hundred highlights on dimensional modeling, while Architecting an Apache Iceberg Lakehouse covered how the same presentation-layer discipline lands on open table formats.

Kimball’s bedrock principle: one measurement event in the physical world maps to exactly one row in the fact table. The four design decisions follow in order—select the business process, declare the grain, identify the dimensions, identify the facts—and the most frequent design error is skipping the grain declaration.
Dimension tables trade space for simplicity: denormalize aggressively, replace cryptic codes with verbose textual attributes, and substitute default rows (Unknown, Not Applicable) for null keys. Normalized 3NF models are great for operational writes but “resemble a map of the Los Angeles freeway system” to BI users.
Percentages and ratios are non-additive—store the numerator and denominator in the fact table instead. Store derived facts physically so the ETL computes them once and consistently.
Conformed dimensions are the enterprise glue: separate teams can build separate star schemas at different times, and they plug together as long as shared dimensions mean the same thing everywhere. That’s 95 percent of the data architecture effort.
Iceberg modernizes the storage side: layered immutable metadata gives atomic commits, time travel, and optimistic concurrency, with the catalog as the arbiter of each table’s current state. The REST Catalog specification decouples clients from catalog implementations; Nessie adds git-like branching and merging so pipelines can write in isolation and merge atomically.
Adjacent bookmarks rounded out the architecture view: Zhamak Dehghani’s data mesh argument for decomposing monolithic lakes, and the Open Data Contract Standard for formalizing the producer–consumer interface.

Fractional Indexing for Realtime Ordered Sequences

A pair of articles explained how collaborative tools keep ordered lists consistent under concurrent edits without the complexity of Operational Transformation.

Figma’s Realtime Editing of Ordered Sequences (Evan Wallace) explains why OT was overkill for a design tool: OT’s benefits target enormous text sequences and interleaving avoidance, at a high implementation cost—the first OT paper had subtle bugs that went undiscovered for years.
Figma’s alternative: every object gets a fraction between 0 and 1 (exclusive) as its index; ordering is just sorting. Inserting between two objects averages their indices, and the exclusive bounds guarantee you can always generate a key before or after any existing one.
Indices are stored as strings and averaged with string manipulation, so precision never runs out. When two clients insert at the same position simultaneously, the server simply assigns a fresh unique position to the second insert.
David Greenspan’s Implementing Fractional Indexing works out the details in lexicographic string space: the midpoint algorithm must not needlessly grow key length, and edge cases like trailing zeros (“3” vs “30” have nothing between them) need careful handling.
His refinement uses variable-length integer parts with a length prefix (A0–A9, B00–B99, …) so appending grows keys logarithmically instead of one digit per insert, and base 95 packs 65 bits of integer precision into ten characters.

War Stories of Scaling Relational Databases

Two production write-ups showed different paths to the same destination: keeping a relational database alive under massive growth.

OpenAI’s Scaling PostgreSQL to power 800 million ChatGPT users keeps a single-writer Postgres and offloads pressure instead of sharding it: shardable write-heavy workloads migrate to Cosmos DB, backfills are strictly rate-limited, and complex joins move to the application layer.
The operational playbook: isolate low-priority and high-priority requests onto dedicated instances to kill the noisy-neighbor problem, pool connections with PgBouncer in transaction mode, use cache locking so a cache-miss storm sends only one reader per key to the database, rate-limit at every layer, and enforce a 5-second timeout on schema changes.
Slack took the sharding path with Vitess: the original architecture had three MySQL clusters with all data-access and shard-lookup logic living in the webapp itself, which became the bottleneck to evolve—motivating a datastore layer that owns routing instead. The Vitess project itself landed in my bookmarks as the reusable version of that lesson.

Obsidian Links

Fix Claude Desktop PATH with CLAUDE_ENV_FILE

me@iany.me (Ian Yang) — Wed, 01 Jul 2026 21:27:36 +0800

Claude Code runs tools and shell commands on your behalf. Launched from a terminal, the CLI inherits your shell environment and everything just works. But under Claude Desktop, Claude Code is spawned from a GUI/desktop session that never sourced your interactive shell config—so if you rely on version managers like mise, asdf, or nix, the tools they install may not be on Claude’s PATH. The fix is a single setting: CLAUDE_ENV_FILE.

How it works

Set CLAUDE_ENV_FILE in .claude/settings.local.json to point at a shell file. Claude sources it before running any command.

{
"env": {
"CLAUDE_ENV_FILE": ".claude/mise.env"
}
}

That file is a plain shell snippet—export statements, one per line:

export PATH="/home/ian/.local/share/mise/shims:/home/ian/project/node_modules/.bin:$PATH"
export DATABASE_URL="postgres://localhost/db"

The path can be relative—it’s resolved from the project root—so .claude/mise.env works on any machine and can be committed alongside the project. Write both, and the next Claude session picks up everything.

Why not just put PATH in settings.json?

You can set env.PATH directly in settings.local.json, but there’s a catch: Claude does not support variable substitution like ${env:PATH}. You’d have to hardcode the full PATH, which breaks the moment dependencies change or you move between machines.

With CLAUDE_ENV_FILE you get full shell semantics—$PATH expands at runtime, conditionals work, and subshells are fair game.

Why shell init doesn’t help either: the snapshot

There’s a deeper reason the obvious fixes fail. At session start, Claude Code freezes a shell snapshot to ~/.claude/shell-snapshots/snapshot-zsh-*.sh, and the Bash tool sources that file before every command it runs.

The snapshot’s final line is export PATH=<frozen value>, and that value is Claude Code’s own process PATH captured at startup—not re-derived from your shell config. (You can spot it: it contains directories no rc file adds, like Claude’s own plugin and session bin paths.) Because this export PATH is the last thing sourced before each command, it clobbers anything your shell init did:

mise activate in .zshenv/.zshrc runs, prepends the shims—then the snapshot’s trailing export PATH overwrites it, burying the shims back where they started.
Even setting env.PATH in settings.json as a plain subprocess variable loses, because the snapshot is sourced after the process environment is set up.

CLAUDE_ENV_FILE wins because it’s sourced after the snapshot. Its export PATH="…/shims:$PATH" is the last word, so the shims land first for every Bash tool call. That’s the whole trick: it’s not just convenient shell semantics—it’s the one hook that runs late enough to survive the snapshot.

Generating the env file automatically

Writing the env file by hand gets tedious. If you use mise, you can generate both files with a task—I vibe-coded preset-claude.js for exactly this (it’s a custom mise task, not a built-in). It:

Reads env._.path from mise.toml (so per-project node_modules/.bin directories land on PATH).
Expands {{config_root}} to absolute paths.
Writes .claude/mise.env with shims, extra paths, and all mise env vars.
Sets CLAUDE_ENV_FILE in .claude/settings.local.json.

mise run preset:claude

One command, and Claude sees the exact same tools you do.

What about other version managers?

The pattern works for anything that can write a shell env file:

asdf: asdf direnv envrc > .claude/asdf.env
nix: nix print-dev-env | grep ^export > .claude/nix.env
direnv: direnv export json | jq -r 'to_entries[] | "export \(.key)=\"\(.value)\""' > .claude/direnv.env

Then point CLAUDE_ENV_FILE at it and you’re set.

Caveats

The file is sourced, not executed—shebang lines are ignored.
Changes to settings.local.json take effect on the next Claude session.
If CLAUDE_ENV_FILE is a relative path, it’s resolved from the project root.

A small config file saves you from fighting invisible PATH issues. Set it once, and Claude runs the same tools you do.

What I Touched This Week 2026-06-20

me@iany.me (Ian Yang) — Sat, 20 Jun 2026 00:00:00 +0000

Focus: Proko - Figure Drawing Fundamentals

This journal is generated by AI

Fault Injection and Distributed Systems Testing

This week’s reading and hands-on work converged on how to test distributed systems under failure. I finished the Jepsen etcd demo tutorial while the Readwise sync delivered a stack of papers and posts on chaos engineering, lineage-based failure testing, and deterministic simulation.

From Chaos to Order — TiDB Testing catalogs a practical fault-injection toolkit: SIGSTOP/SIGCONT for process hangs, renice/setpriority for CPU contention, iptables/tc for network drops and reordering, libfuse/libfiu for I/O faults, and gofail/fail-rs for compile-time injection points. The workflow is hypothesis → inject → analyze.
Automating Failure Testing at Internet Scale (Netflix) inverts the search: start from a successful outcome, build a lineage graph of contributing computations, then find minimal fault combinations that would prevent it. Netflix traces requests through services to locate injection points and treats missing error metrics as failures.
Sled Simulation Guide offers a lightweight pattern: model nodes as state machines that receive messages and emit outgoing messages per tick. When an invariant breaks, shrink the initial request set to a minimal reproducer.
Mostly Deterministic Simulation Testing in Go shows how to make Go tests reproducible by compiling to WASM, seeding the runtime RNG via environment variable, and advancing virtual time only when all goroutines block.
CAP Twelve Years Later reframes partitions as time bounds on communication: detect partition, enter partition mode, then recover by merging divergent histories with version vectors.
I also started learning FoundationDB Flow—an actor-style concurrency model where Promise/Future pairs and wait() in ACTOR functions underpin the database’s fault-tolerant architecture.

Reviewing Agent Pull Requests

As AI agents produce more code, the review workflow shifts from line-by-line reading to judgment calls only a human can make. Two guides from this week’s sync define a practical checklist.

Agent Pull Requests Are Everywhere (Andrea Griffiths): annotate the diff with context before tagging reviewers; self-review is mandatory respect for reviewer time; search for duplicate helpers and block merge until consolidated; trace the critical path end-to-end checking boundary conditions and permission checks on every branch; require a test that fails on pre-change behavior.
Red flags to send back: more than five unrelated files touched, purpose not describable in one sentence, empty PR body or missing implementation plan. Ask the author to break it into scoped units or add a structural summary before investing review time.
Agentic Code Review (Addy Osmani): separate analysis from execution with a human approval gate for production changes; let automated review run first as a prerequisite, not a replacement; never evaluate model output without human validation.
The through-line: agents handle volume, humans supply intent verification, deduplication discipline, and end-to-end correctness tracing.

Grit and Figure Drawing Practice

Personal development reading intersected with deliberate skill-building this week. I synced Grit by Angela Duckworth and continued the Proko Figure Drawing Fundamentals course—measuring techniques, idealistic proportions, and shading light and form.

Duckworth’s core formula: achievement = talent × effort². Effort builds skill and makes skill productive; consistency over time beats bursts of intensity.
The “naturalness bias” hides how much work excellence requires—we prefer to attribute success to innate talent rather than sustained practice.
Goal hierarchy matters: grit is holding the same top-level goal for a long time while being willing to abandon lower-level goals that no longer serve it. The hard part is deciding what not to do.
The Proko lessons this week applied the same principle at the craft level—measuring with head units, constructing idealistic figure proportions, then rendering form with light and shadow. Each lesson is a small, repeatable drill that compounds.
Weekly plan alignment: close the figure drawing course by copying the demo drawing—treating the final piece as integration of many individual, doable feats.

Obsidian Links

What I Touched This Week 2026-06-13

me@iany.me (Ian Yang) — Sat, 13 Jun 2026 00:00:00 +0000

Focus: ♯ Kleppmann - Designing data-intensive applications

This journal is generated by AI

Systems Correctness and Randomized Testing

This week’s Readwise sync centered on the DDIA second-edition thread about formal methods and randomized testing. The papers form a practical stack: classify what breaks in production, explain why random partition tests work, and describe how AWS validates correctness at scale.

Systems Correctness Practices At AWS combines lightweight formal approaches—property-based testing, fuzzing, runtime monitoring—with tools like P for state-machine modeling and PObserve for post-hoc log validation against specifications. Open-source shuttle and turmoil extend build-time testing of thread ordering and failure injection.
Why Is Random Testing Effective for Partition Tolerance Bugs? formalizes the Jepsen pattern: a short setup sequence, a carefully chosen partition, operations in each block, heal, repeat. Separating coverage and minority isolation explain why random tests find most partition bugs with surprisingly small schedules.
What Bugs Live in the Cloud? catalogs 3,000+ cloud issues: data consistency, scalability, and topology bugs are distinct from classic distributed failures. Operational protocols (bootstrap, cloning, fsck) carry data inconsistency bugs because they run on cold paths. Failover-on-failover is brittle; systems must distinguish hardware failure from software logic bugs.
I also started exploring FizzBee as a Python-like formal modeling tool with built-in fault injection and MBT support—promising ergonomics for the same problem space.

From Data Lakes to Iceberg Lakehouses

A second cluster of highlights mapped the evolution from schema-on-write warehouses to schema-on-read lakes, and now to lakehouses that unify cheap object storage with warehouse-style analytics.

Data Lakes: A Survey of Functions and Systems frames the core trade-off: lakes store raw data in original formats with a common access interface, but metadata and governance determine whether ad-hoc analytics is feasible. The survey covers ingestion tiers, metadata modeling (data vault, enterprise knowledge graphs), dataset discovery (Aurum, JOSIE), and the lakehouse convergence that avoids maintaining separate lake and warehouse systems.
2025 Guide to Architecting an Iceberg Lakehouse turns theory into an architecture checklist: self-audit current data placement and SLAs first, then standardize on Parquet plus Iceberg metadata, pick catalog (Nessie, Polaris, Glue), ingestion (Spark, Flink, Kafka Connect), and query engines (Dremio, Trino). Dremio’s ability to federate non-Iceberg sources alongside Iceberg tables lowers migration risk.
The lakehouse pattern aligns with a broader shift toward analytical systems and data engineering—an area I’m exploring as part of a career transition.

Local-First Data Ownership

The local-first essay rounds out the week’s data-systems reading with a user-centric counterpoint to cloud defaults: you should own your data even when services run in the cloud.

You own your data, in spite of the cloud argues that Git/GitHub is the closest existing model for local-first collaboration—data lives on your machine, sync is explicit, and the remote is optional infrastructure rather than the source of truth.
CRDTs and tools like Automerge offer a technical foundation for convergence without a central coordinator, which maps directly to DDIA 2nd edition’s new section on sync engines and local-first software.
The essay’s further-reading list (Baboulevitch’s Data Laced with History, Kleppmann’s Convergence vs Consensus, formal CRDT verification) is a good bridge from informal local-first ideals to the formal-methods thread above.

Obsidian Links

What I Touched This Week 2026-03-30

me@iany.me (Ian Yang) — Mon, 30 Mar 2026 00:00:00 +0000

This journal is generated by AI

Convincing vs Persuading in Technical Work

This week sharpened a useful distinction: being correct is only the starting point, while moving a system or a team requires persuasion tuned to real context. That frame maps directly to architecture work, migration plans, and cross-team decisions.

Convincing Is Not Persuading highlights that proof and benchmarks convince, but adoption depends on trust, timing, and incentives.
The practical takeaway is to pair correctness with audience-aware framing: what this change protects, what risk it removes, and what people can safely do next.

Scale-First AI Thinking and Mental Models

The Readwise set this week converged on a coherent AI posture: favor general methods that scale with compute, then use explicit mental models to reason about systems and constraints.

The Bitter Lesson reinforces a long-run strategy: approaches that scale with computation and learning tend to dominate handcrafted knowledge-heavy systems.
TLA+ Mental Models contributed a systems lens (state, logs, replication) that is useful for evaluating reliability claims, not just feature velocity.
This combination was a good backbone for AI reflection this week: keep abstractions general, but reason rigorously about behavior under change.

Boring Tech, Better Practices, and Tooling Leverage

A recurring theme across highlights and bookmarks was pragmatic leverage: pick stable tools, then innovate in process, automation, and integration points.

Choose Boring Technology and Innovative Practices captures the principle well: conservatism in stack choice enables boldness in operational practice.
Recent bookmarks aligned with this approach, including RustTraining, Saber, and monitor-switch automation via monctl.js.
Weekly hygiene (bookmark triage, highlights cleanup, sync routines) made this strategy actionable rather than theoretical.

Obsidian Links

What I Touched This Week 2026-03-21

me@iany.me (Ian Yang) — Sat, 21 Mar 2026 00:00:00 +0000

This journal is generated by AI

Software Maintenance and the Specification Problem

Scott Werner’s “Warranty Void if Regenerated” explores why software needs continuous tending, not just initial development. The core insight: specifications describe static relationships, but real-world inputs are alive—feeds from other systems that are constantly being updated, recalibrated, and regenerated.

The maintenance paradox: Paying for maintenance means admitting vulnerability, while paying for repair means responding to an emergency. Humans find emergencies more motivating than vulnerabilities.
Domain knowledge is irreplaceable: People who understood the domain and could diagnose specification problems were the most valuable. This knowledge is often embodied, contextual, and inarticulable—like knowing the clay underneath a greenhouse or how prevailing winds affect crop rows.
The Software Choreographer concept: A role that maps your entire tool ecosystem, specifies interfaces between them, and builds a conformance layer so that when any tool regenerates, interfaces are verified before the new version goes live. Like shipping containers: the container was cheap; organizing the logistics was where all the value was.
Physical controls matter: Always offer a physical control—a button, switch, or lever. Something the client can touch. This builds trust and allows graceful degradation when systems fail.

AI Agents and the Harness

Ben Thompson’s “Agents Over Bubbles” argues that the critical component of making agentic workloads work is the “harness”—the software that actually controls the model, not the model itself.

Abstraction layer: Claude Code and OpenAI’s Codex abstract the user away from the model. You give instructions to an agent, which directs the model; the agent can also use deterministic tools to verify results.
Models lack goals: Large language models are intelligent, but they do not have goals or values or drive. The harness provides the structure and verification.
The opportunity: How many apps or services haven’t been built, not because one person can’t imagine them, but because they haven’t had the resources, team, or coordination capabilities to ship them? Agents could change this dynamic.

Simplifying Life Through Lifestyle Design

The Tim Ferriss Show episode on simplifying life brought together insights from Maria Popova, Morgan Housel, Cal Newport, Craig Mod, and Debbie Millman on what it means to simplify.

Read history, not forecasts: A good heuristic for your relationship with information is to read more history and fewer forecasts. As Kelly Hayes says, “When you haven’t engaged with history, everything feels unprecedented.”
Lifestyle design over triage: Cal Newport argues that triage rules don’t work—too many things satisfy “good enough” criteria. Instead, think about lifestyle design: know what conditions of your day-to-day existence are best for you, and design a lifestyle that matches that.
Courage over confidence: Debbie Millman distinguishes courage from confidence. Courage means taking risks and steps toward what you want despite how you feel. Confidence comes through repeated success. You don’t wait for confidence to arrive; you act from courage.
Freedom over control: What Millman wanted wasn’t more control, but more freedom. That freedom has allowed her to build a very different kind of life.
Simplicity as coherence: Simplicity isn’t only about minimalism. It’s also about coherence—things fitting together in a way that makes sense.

Sources:

Obsidian Links

Power of Monoid, Beauty of Simplicity

me@iany.me (Ian Yang) — Fri, 20 Feb 2026 00:00:00 +0800

A monoid is one of the smallest useful abstractions in algebra: a set closed under an associative binary operation, with an identity element. That simplicity is exactly why it shows up everywhere—from summing numbers and concatenating strings to powering divide-and-conquer algorithms and elegant data structures like finger trees. This post walks through what monoids are, why they give you “compute power” for free when you can phrase a problem in terms of them, and how to think about choosing the right monoid and predicate when you do.

What is a monoid?

A monoid is a set $S$ equipped with a binary operator $\bullet$ and an identity element $e$ (Wikipedia).

The operator is closed on $S$ . For all $a, b \in S$ , the result $a \bullet b$ is also in $S$ .
The operator is associative: For all $a,b,c \in S$ , $(a \bullet b) \bullet c = a \bullet (b \bullet c)$
The identity element $e$ satisfies $e \bullet a = a \bullet e = a$ for all $a \in S$ .

For example, The integer numbers with the operator addition (+) is a monoid, where the identity element is 0. The integer numbers with the operator multiplication (x) is also a monoid with the identity element 1.

The set of finite lists with the operator concatenation is a monoid since:

The operator is closed because concatenation of two finite lists is also a finite list.
The operator is associative, because both $(a \bullet b) \bullet c$ and $a \bullet (b \bullet c)$ result in a new list by placing elements of $a, b, c$ consecutively.
The identity element is the empty list.

The integer numbers with the operator max is a counterexample. The operator is closed and associative, but there is no identity element. Given any integer $e$ , there’s always a smaller integer $a$ such that $e \bullet a = e \ne a$ . However, max on the integer set with a lower bound is a monoid, such as the non-negative integers where the identity element is the lower bound 0.

Divide and conquer: why associativity matters

At first glance, associativity may seem too trivial to be useful in programming. However, associativity is what enables powerful divide-and-conquer strategies, where problems can be split into parts, solved independently, and then safely recombined.

Exponentiation by Squaring

Let’s begin with a simple application: repeatedly applying the binary operator to the same element.

 $\underbrace{a \bullet a \bullet \cdots \bullet a}_{a \text{ appears } n \text{ times}}$

Instead of applying the binary operator $n-1$ times sequentially, we exploit associativity to group every two instances of $a$ together recursively. This gives us a smaller problem when n is even:

 $\underbrace{(a \bullet a) \bullet \cdots \bullet (a \bullet a)}_{(a \bullet a) \text{ appears } \frac{n}{2} \text{ times}}$

When n is odd:

 $a \bullet \underbrace{(a \bullet a) \bullet \cdots \bullet (a \bullet a)}_{(a \bullet a) \text{ appears } \frac{n-1}{2} \text{ times}}$

We only need to compute $a \bullet a$ once to turn the problem of size $n$ to size $n/2$ . Repeating the process on $(a \bullet a)$ gives the Exponentiation by Squaring algorithm, which requires at most $\displaystyle 2 \lfloor \log _{2}n\rfloor$ computations that is more efficient than $n-1$ when $n$ is greater than 4.

For integers or real numbers under multiplication (×), exponentiation by squaring is an efficient algorithm to compute positive integer powers. Since the set of elliptic curve points under point addition forms a monoid, this same method can also be used to compute Elliptic Curve Scalar Multiplication.

General Divide-and-Conquer Search Algorithm

We can generalize the divide-and-conquer method to search an element in a sequence based solely on associativity.

The result of applying the monoid operator to a sequence from left to right serves as a summary of that sequence. If a predicate can determine whether a given element is in the sequence based solely on this summary, we can devise a general divide-and-conquer search algorithm.

Let’s say we want to search for a target element in the sequence $t_1, \ldots, t_n$ , where each $t_i$ belongs to a monoid $(S, \bullet, e)$ . Here, $S$ is the underlying set, $\bullet$ is the binary operation, and $e$ is the identity element.

We don’t know which kind of predicates works for the search algorithm. Let’s give a best guess that the predicate $p$ is a function of the monoid “summary” that $p(t_1 \bullet \cdots \bullet t_n)$ is true if and only if $t$ is in the sequence $t_1, \dots, t_n$ .

Assume that $p(t_1 \bullet \cdots \bullet t_n)$ is true, thus the target element $t$ is in the sequence. We divide the sequence into two halves: $t_1,\ldots,t_k$ and $t_{k+1},\ldots,t_n$ , where $1 \le k \le n$ . We then evaluate $p(t_1 \bullet \cdots \bullet t_k)$ to determine whether the target element lies in the first or second half, and continue the search.

Based on this observation, we can deduce the following property of the predicate: there exists an index $x$ such that

 $p(t_1 \bullet \cdots \bullet t_k) := \begin{cases} \text{false} & \text{if } k < x, \\ \text{true} & \text{if } k \ge x. \end{cases}$

$t_x$ is the target element if such $x$ exists; otherwise, the target element does not exist in the sequence.

Intuitively, the target element is the turning point at which the predicate on the running summary changes from false to true.

Note that $p$ makes sense only on the summary of any prefix of the sequence. If we need to continue the search in the second half, we must remember the summary of the scanned prefix.

Now we can define the search algorithm $\mathrm{Search}(p, s, \{t_i,\ldots,t_j\})$ where

$s$ is the summary of scanned prefix $t_1 \bullet \cdots \bullet t_{i-1}$ when $i > 1$ or the identity element $e$ otherwise.
$t_i, \ldots, t_j$ is the sub-range to search next.
$p$ is the predicate as defined above

The algorithm proceeds as follows:

If $p(s \bullet t_i \bullet \cdots \bullet t_j$ ) is false, the target element does not exist. The algorithm aborts with an error.
Otherwise, if there’s only one element ( $i = j$ ), $t_i$ is the target element. The algorithm aborts with the found result.
Otherwise, choose a pivot index $i \le m \lt j$ to split the sequence into two nonempty halves: $t_i, \ldots, t_m$ and $t_{m+1},\ldots,t_j$ . Test $p(s \bullet t_i \bullet \cdots \bullet t_m)$ that
- If it is true, continue the search in the first half: $\mathrm{Search}(p, s, \{t_i,\ldots,t_m\})$
- Otherwise, continue the search in the second half: $\mathrm{Search}(p, s \bullet (t_i \bullet \cdots \bullet t_m),\{t_{m+1},\ldots,t_j\})$

The algorithm starts with $\mathrm{Search}(p, e, \{t_1, \ldots, t_k\})$ .

Application: Random-Access Sequence

An application of the search algorithm is accessing the nth element in the sequence.

We initialize the sequence to all 1s and use the monoid of non-negative integers with addition $(\mathbb{N},+,0)$ :

 $\underbrace{1, \ldots, 1}_{n \text{ times}}$

The predicate to find the i-th (starting from 0) element is:

 $\[ p_i(s) := s > i \]$

It may seem silly to search for the i-th 1 in a sequence of 1s, but we can store any data in the sequence and attach the monoid values as annotations to guide the search algorithm.

Application: Max-Priority Queue

Another application is finding the element with the max priority.

We use the monoid of non-negative integers with operator max $(\mathbb{N},\mathrm{max},0)$ and assume that the maximum value has the maximum priority.

The predicate to find the element with the max priority is

 $\[ p(s) := s = m \]$

Where $m$ is the monoid summary of the entire sequence—that is, the maximum value in the sequence. The predicate checks whether the summary equals to $m$ .

Annotated Search Tree

A natural way to support the divide-and-conquer search is an annotated binary tree. Store the sequence elements at the leaves, and at each node store the monoid summary of the subtree—e.g. the sum of lengths or the maximum priority in that subtree. The predicate can then be evaluated on the left subtree’s annotation to decide whether to descend left or right, and the prefix summary is updated when going right by combining it with the left subtree’s summary.

A plain binary tree can degenerate to a list in the worst case, so operations may become linear. A more advanced structure, the finger tree¹, keeps the tree balanced and supports efficient access at both ends and in the middle; each node carries a monoidal “measure” of its subtree, and the same search strategy applies. In Haskell, Data.Sequence from the containers library implements sequences as finger trees with size (length) as the measure, giving $O(\log n)$ indexing, splitting, and concatenation.

Utility of the Identity Element

The general divide-and-conquer algorithm does not require a monoid—only a semigroup. A semigroup is a fancy word for a set equipped with a closed, associative binary operator but lacking an identity element. The presence of an identity element makes monoids convenient to work with.

The identity element serves as a natural default value or starting point for algorithms. For instance, in the search algorithm, the summary of the scanned prefix is initialized to $e$ . Without an identity element, we need an additional flag to indicate whether any prefix has been scanned, and the algorithm would have to branch conditionally based on that flag.

The art of choosing monoid and predicate

In the random-access example we used $(\mathbb{N}, +, 0)$ and annotated each position with $1$ —the summary of a segment is its length, and the predicate $s > i$ tells us whether the $i$ -th element lies in the prefix we have so far. In the max-priority queue we used $(\mathbb{N}, \max, 0)$ (or a bounded variant): the summary is the maximum value in the segment, and the predicate $s = m$ identifies the segment that contains the global maximum. In both cases, the monoid was chosen so that the combined summary over a range is exactly what the predicate needs to decide where to go next.

The flip side is that finding both the right monoid and the right predicate can be tricky. At each step the search has access only to the monoid summary of the prefix (or segment) seen so far, so the predicate must be decided from that summary alone. The monoid must be rich enough to supply the information the predicate needs. Sometimes the natural summary (e.g. sum or max) suggests the predicate (e.g. $s > i$ or $s = m$ ). Sometimes you must try a different carrier or operation, or encode extra information into the monoid (e.g. pairs or custom types), so that the predicate can be expressed. There is no universal recipe—it is a matter of design and experimentation. Reframe the problem as: “What do I need to know about a segment to decide the next step?” Then choose a monoid that can represent that knowledge and a predicate that uses it.

Hinze, R., & Paterson, R. (2006). Finger trees: A simple general-purpose data structure. Journal of Functional Programming, 16(2), 197–217. Cambridge University Press. https://www.cs.ox.ac.uk/ralf.hinze/publications/FingerTrees.pdf

What I Touched This Week 2026-02-07

me@iany.me (Ian Yang) — Sat, 07 Feb 2026 00:00:00 +0000

This journal is generated by AI

Haskell: Typeclassopedia, IO, and Documentation

This week was heavily Haskell-focused. I worked through the Typeclassopedia, Learn You a Haskell Chapter 9 (Input and Output), and Real World Haskell Chapter 7 (IO), plus the Haddock markup guide.

Monad vs Applicative: The structure of an Applicative computation is fixed; a Monad’s structure can depend on intermediate results. That’s why (>>=) (bind) is strictly more powerful than (<*>). Prefer Applicative when you don’t need that—it can allow parallelization where monadic code cannot.
Reader, Writer, State: The (->) e reader monad gives a read-only environment; Writer accumulates a monoidal log; State s a is s -> (a,s) for stateful computations. All live in Control.Monad and the mtl library.
IO in practice: getContents does lazy I/O; interact captures the pattern of “read, transform, output.” Use withFile for handle-based file I/O. Prefer Maybe/Either in pure code and reserve exceptions for the IO part; catch with System.IO.Error.catch and predicates like isDoesNotExistError.
Haddock: Use -- | before or -- ^ after declarations; document arguments inline. Headings with -- *, -- **; link identifiers with single quotes/backticks and modules with double quotes; code blocks with @...@ or bird tracks >.

Use Bun for Shell Scripts

I published a post on using Bun for cross-platform shell scripts on Windows. Bun avoids shebang and WSL/Git-bash setup while giving a single runtime for ad-hoc commands and full scripts.

Single binary: bun build ./script.ts --compile --outfile script produces a native executable, so no shebang or interpreter is needed on Windows.
Bun Shell: Bun.$ builds shell commands from template literals (similar to zx). On Windows, Bun ships with MSYS for a consistent bash environment.
Extras: Bun.secrets for the OS keystore, built-in globs, YAML, ANSI. Fast startup (~5ms vs Node’s ~25ms for simple scripts) helps for small, frequent scripts.

Sources:

How I Estimate Work

Sean Goedecke’s post reframes estimation as a political and constraint-satisfaction problem rather than a pure “how long will this take?” question.

Context first: Gather political context before looking at code—pressure on the project, what kind of estimate the chain wants, whether this is a casual ask or a must-have.
Inversion: The job isn’t “break down work to get a duration.” It’s “find the set of software approaches that fit the timeline they already have in mind.”
If you don’t estimate: Someone less technical will estimate for you. Engaging with the process lets you steer which approaches are in scope.

Obsidian Links

Use Bun for Shell Scripts

me@iany.me (Ian Yang) — Sat, 07 Feb 2026 00:00:00 +0800

I’ve moved most of my small scripts to Bun. It sidesteps Windows’ lack of shebang support and the Git-for-Windows/WSL bash dance, and gives you one runtime for both ad-hoc shell-style commands and full scripts.

Problems Bun solves

Windows doesn’t execute #!/usr/bin/env python3 or #!/bin/bash, so scripts written for Linux or macOS usually need a separate PowerShell version. Bun compiles JavaScript to native executables, so a single script can run cross-platform without shebangs.

Mise file tasks have started to support shebangs on Windows in the latest release, but they rely on system bash.exe, which often points at WSL. Bun does not. You run bun ./script.js and embed shell commands via Bun.$; the script uses Bun’s bundled bash environment.

Why Bun for shell scripts

The command bun build ./script.ts --compile --outfile script produces a single binary, so no shebang or interpreter is needed on Windows. The Bun.build API is available too; I use a build.js script to walk a directory and compile all executables. Pre-built binaries start quickly—Bun’s docs cite ~5ms vs Node’s ~25ms for a simple script, which helps for small, frequently run scripts.

Bun has strong support for shell-style scripting. Bun Shell runs bash commands; the main entry point is Bun.$, which constructs shell commands from template literals for safe interpolation, similar to google/zx. On Windows, Bun ships with MSYS, so you get a consistent bash environment and common Linux CLI tools without extra setup.

Other useful features:

Bun.secrets—Securely store and retrieve secrets using the OS keystore (Windows Credential Manager, macOS Keychain, Linux libsecret). Secrets - Bun
Built-in support for glob patterns, YAML parsing, ANSI colors, and more. Bun Runtime

Short example

import { $ } from "bun";
const out = await $`echo hello`.text();
console.log(out); // hello

Run it with bun run script.js or bun ./script.js.

Obsidian Notes

JavaScript Shell Scripting

What I Touched This Week 2026-02-01

me@iany.me (Ian Yang) — Sun, 01 Feb 2026 00:00:00 +0000

This journal is generated by AI

Haskell Type Classes: Functors, Applicatives, and Monoids

This week I dove deep into Haskell’s type class hierarchy, working through Learn You a Haskell and the CIS 194 course materials. The key insight is understanding how these abstractions compose to enable powerful, generic programming.- Functors are types that can be mapped over. The fmap function can be viewed as “lifting” a function: fmap :: (a -> b) -> (f a -> f b) transforms an ordinary function into one that works inside a functor context

The functor laws ensure predictable behavior: fmap id = id (identity preservation) and fmap (f . g) = fmap f . fmap g (composition preservation)
Applicatives extend functors by allowing wrapped functions to be applied to wrapped values using <*>. Lists as applicatives represent non-deterministic computations where [(+3),(*2)] <*> [1,2] produces all combinations
ZipList provides an alternative applicative instance for lists using pairwise application instead of all combinations
Monoids provide an identity element (mempty) and an associative binary operation (mappend). The foldMap function reveals why monoids matter: the identity handles empty structures and the associative operation combines values reliably
Use foldl' from Data.List instead of foldl to avoid building huge thunks; foldr is better when the folding function can short-circuit

Sources:

Using tmux for PowerShell in Windows Terminal

I published a blog post on getting tmux session persistence in Windows Terminal while keeping PowerShell as the default shell. The solution runs tmux through WSL but configures it to spawn pwsh.exe for new panes.

Create thin wrapper scripts (tmux.ps1, tmux.cmd) so tmux from Windows means wsl tmux
A helper script tmux-pwsh.ps1 creates or attaches to named sessions with pwsh.exe -nologo as the default command
The key trick: send set-option default-command via tmux -C attach because running wsl tmux set-option immediately after session creation has a race condition where the session isn’t ready
After setup, splitting panes and creating windows in that session will all start PowerShell in the Windows environment

Elite Performance Through Preparation

An insightful thread by Sandeep Palakodeti on what separates elite performers from amateurs. The core message: greatness is not about taking risks but eliminating variance through preparation.

When experts operate at their limit, they’re not “trying hard”—they’re executing scripts that have been debugged for decades through deliberate, high-fidelity repetition
Fear is the biological response to the unknown; when you’ve accounted for every variable, fear is replaced by focus
Elite performers aim below the edge of their ability because that’s where consistency lives
Every question gets answered upstream, every branch point gets a playbook—by the time the moment arrives, they’re executing state changes, not solving problems
“Don’t worship the risk. Worship the work that made the risk irrelevant.”

Obsidian Links

Use tmux for PowerShell in Windows Terminal

me@iany.me (Ian Yang) — Thu, 29 Jan 2026 23:30:42 +0800

You can get tmux session persistence and multiplexing in Windows Terminal by running tmux inside WSL and setting the default shell to PowerShell. New panes and windows will then start pwsh.exe instead of a Linux shell. Here’s a minimal setup using small wrappers and the tmux -C attach trick to configure new sessions.

Why tmux under WSL with PowerShell?

Since tmux does not run natively on Windows, the standard approach is to use it through WSL. However, if you launch wsl tmux from Windows Terminal, all panes will default to your WSL shell. When working in a Windows directory, I prefer to use native PowerShell within the Windows environment.

To ensure every tmux pane runs PowerShell, configure tmux to use pwsh.exe as its default command. When you launch pwsh.exe from WSL within a Windows directory, it brings us back to the Windows environment.

Wrappers so you can call tmux from PowerShell

Put these in a directory on your PATH (e.g. ~/Documents/PowerShell/bin).

PowerShell — tmux.ps1:

wsl tmux $args

Cmd — tmux.cmd:

@echo off
wsl tmux %*

From PowerShell or Cmd you can then run tmux new, tmux attach, etc., and they all go to WSL’s tmux.

Creating PowerShell Sessions

The next piece is a script that creates a new session whose default command is pwsh.exe, or attaches if that session already exists. Example usage: tmux-pwsh dev or tmux-pwsh work.

The script sets the default command only for sessions it creates; it does not affect sessions started with a standard tmux new-session.

tmux-pwsh.ps1:

param(
[Parameter(Mandatory=$true)]
[string]$SessionName
)
$pwshCommand = "exec pwsh.exe -nologo"
# Check if session exists using exact name match
wsl tmux has-session -t "\=$SessionName" 2>$null
if ($LASTEXITCODE -ne 0) {
wsl tmux new-session -d -s $SessionName $pwshCommand
echo "set-option default-command `"$pwshCommand`"" | `
wsl tmux -C attach -t "\=$SessionName" >$null
}
wsl tmux attach -t "\=$SessionName"

Note:

The = prefix does an exact session name match and must be escaped when sending the command from PowerShell to WSL.
The new session specifies command pwsh.exe via the command argument.
Running wsl tmux set-option immediately after creating the session does not work because there’s a brief window where the session is not available for setting options. Instead, sending set-option via tmux -C attach reliably applies the setting.

After this, splitting panes and creating new windows in that session will all start pwsh.exe -nologo in Windows Terminal.

Summary

Use WSL for tmux and PowerShell as the default command by setting tmux’s default command to exec pwsh.exe -nologo.
tmux.ps1 / tmux.cmd — thin wrappers so tmux from Windows means wsl tmux.
tmux-pwsh.ps1 <name> — create (or attach to) a named session that uses PowerShell as the default command.

Once these are on your PATH, run e.g. tmux-pwsh dev from Windows Terminal to get a tmux session where every pane is PowerShell.

What I Touched This Week 2026-01-24

me@iany.me (Ian Yang) — Sat, 24 Jan 2026 00:00:00 +0000

This journal is generated by AI

Erlang State Machine Patterns in Rust

This week I created a presentation exploring how to implement Erlang OTP’s gen_statem patterns in Rust using Tokio. The core insight is that Erlang’s behavior pattern separates the engine (state machine framework) from the callback (state-specific logic), following the strategy pattern.

The fundamental state transition follows: State(S) × Event(E) → Actions(A), State(S')
Erlang’s “everything is an event” philosophy means state entry, timeouts, and internal messages are all unified as events
The enter event triggers when entering a new state, useful for running initialization logic without duplicating code across multiple transition paths
Postpone action defers events to a later state when we can’t process them yet
Timeout actions come in three flavors: event timeout (cleared on any event), state timeout (cleared on state change), and named timeout (manual clearing)
Inserted events enable preprocessing and state machine composition

The code examples progressively build from basic process simulation to full-featured state machines with all these capabilities.

BFT Consensus Protocol Comparisons

I studied the differences between PBFT, Tendermint, HotStuff, and HotStuff-2. These are all safety-preferring protocols where locked parties guard the safety of a potential commit. The key questions each protocol answers are:

What does the leader learn about system status at the start of a view?
How does the leader convince other parties about system status to get votes?

Among 2t+1 locks in a status response, up to t can be malicious, up to t can be honest but not locked on the committed value, but at least one honest party must be locked on the committed value. This honest party won’t vote for conflicting proposals, thus guarding commit safety.

HotStuff introduces an additional phase: “if some party locks, then ≥2t+1 parties know about this lock and hold a key corresponding to it.”

Sources:

What is the difference between PBFT, Tendermint, HotStuff, and HotStuff-2 by Kartik Nayak and Dahlia Malkhi
Provable Broadcast by Ittai Abraham and Alexander Spiegelman

CKB Virtual Transactions

I explored a design for implementing partial transactions in CKB through “Virtual Tx.” The approach mocks system calls so scripts access the virtual tx instead of the real current transaction.

Override syscalls in ckb-c-stdlib or ckb-std to redirect to virtual tx data
Anyone can be economically incentivized to match partial txs since fees can be provided
Use a special first input as the indicator that the tx is a vtx
The first input’s type script witness specifies how each vtx maps to tx components (inputs, outputs, etc.)
Inputs/outputs are handled exclusively, with mechanisms to tackle cell/header deps duplication

Obsidian Links

What I Touched This Week 2026-01-17

me@iany.me (Ian Yang) — Sat, 17 Jan 2026 00:00:00 +0000

This journal is generated by AI

Temporal Patterns and Bitemporality

This week I explored the concept of bitemporality and temporal patterns in data modeling. The key insight is that we need to track two dimensions of time: actual time (when something happened) and record time (when we learned about it). This becomes crucial when we need to answer questions like “what did we think the state was two months ago?” or “what did we know six months ago about something that happened earlier?”

Sources:

One for the Treble, Two for the Time by Lewis Daly
Temporal Patterns by Martin Fowler

Go Performance Optimization Techniques

I learned several advanced Go performance optimization techniques from VictoriaMetrics, a high-performance time-series database. The key strategies include using sync.Pool for object reuse to reduce GC pressure, implementing channel-based object pools for more controlled resource management, and using sharding to reduce lock contention by splitting large data structures into independent shards.

Use sync.Pool for object reuse to minimize garbage collection overhead
Channel-based object pools provide more control than sync.Pool
Sharding large data structures reduces lock contention
Localized worker pools with independent channels improve multi-core scalability
Buffered channels can serve as semaphores for rate limiting

Source: 从入门到极致：VictoriaMetrics 教你写出最高效的 Go 代码 by Tony Bai

JDK Selection Guidelines

I reviewed best practices for choosing a Java Development Kit (JDK) version and distribution. The primary recommendation is to use Adoptium Eclipse Temurin 21.

Source: Which Version of JDK Should I Use by Jochen Christ

Obsidian Links

What I Touched This Week 2026-01-10

me@iany.me (Ian Yang) — Sat, 10 Jan 2026 00:00:00 +0000

This journal is generated by AI

Learning C23: Going Behind the Curtain of Modern Systems

This week I dove deep into Paul J. Lucas’s book on learning C23, which provides a comprehensive tour of the latest C standard and why understanding systems programming at this level matters. With 133 highlights, this was clearly a major focus of my learning.

Modern C Features: C23 introduces many modern conveniences like bool, nullptr, constexpr, auto, typeof, and compound literals. The language is evolving while maintaining its core philosophy of being “close to the machine.”
East const Convention: A stylistic choice where const is placed to the right (east) of the type, making pointer declarations more readable when reading from right to left. This consistency helps with complex pointer declarations.
Type System Enhancements: New types like _BitInt for bit-precise integers, decimal floating types (_Decimal32, _Decimal64, _Decimal128), and complex number support show C’s continued evolution for specialized use cases.
Practical Systems Understanding: The book emphasizes that C was designed to work directly with machine details—understanding memory layout, alignment, and how data structures map to hardware is still valuable even when working in higher-level languages.

This connects to my broader interest in understanding how modern systems work under the hood, especially as I work with distributed systems and blockchain technology where performance and correctness matter deeply.

Time Management and Reflective Living

Arnold Bennett’s classic How to Live on 24 Hours a Day offers timeless wisdom about making the most of our daily time budget. The key insight is that we already have all the time there is—the challenge is how we use it.

The Inner Day: Bennett suggests dedicating 7.5 hours per week (about 90 minutes per evening) to cultivating your mind. This “inner day” should begin at 6 p.m. and end at 10 a.m., separate from your workday.
The Reflective Mood: What’s most lacking in modern life is the reflective mood—taking time to examine conduct against principles, to think deeply rather than just consume information. The solitude of the evening commute is perfect for this.
Slow, Deep Reading: When reading for cultivation, give at least 45 minutes to careful, fatiguing reflection on what you’re reading. Your pace will be slow, but that’s the point—the good stuff rises up to meet you in the extra time you give it.
Topic Reading with Limits: Choose a limited period, subject, or single author. Define the direction and scope of your efforts rather than reading aimlessly. Forget the goal; think only of the surrounding country, and you’ll find yourself in a lovely town on a hill.

This resonates with my experience that slowing down often yields better results than rushing, whether in reading, coding, or thinking through problems.

Formal Methods: Exploring Quint and TLA+

I’ve been exploring formal specification languages, particularly Quint, which provides a more accessible syntax for writing formal specifications compared to TLA+. This connects to my interest in distributed systems and ensuring correctness.

Quint’s Design Philosophy: Quint restricts the prime operator (') to assignments in the format <var>' = <expr>, preventing hard-to-grasp expressions while maintaining the power of temporal logic. The tooling reports errors if you misuse ' or forget to update variables in some branches.
State Machine Modeling: Actions named init and step define the state machine—init defines initial states, step defines transitions. This makes the model structure clear and checkable.
Pure Functions and Actions: Definitions prefixed with pure are functional—same input always produces same output. Actions use the prime operator to modify state. This separation helps reason about what changes state and what doesn’t.
Non-determinism: Quint supports non-deterministic definitions using any and oneOf, which can only be used inside actions before assignments. This is crucial for modeling systems with multiple possible behaviors.

The connection to TLA+ is clear—both are tools for specifying and verifying system behavior, but Quint’s more familiar syntax might lower the barrier to entry for formal methods. This is particularly relevant as I work on systems where correctness is critical.

Obsidian Links

What I Touched This Week 2026-01-03

me@iany.me (Ian Yang) — Sat, 03 Jan 2026 00:00:00 +0000

This journal is generated by AI

Training the Idea Muscle: Quantity Over Quality

This week I came across a fascinating article about training the idea muscle that perfectly captures a principle I’ve been trying to internalize: if you reject your own ideas, the part of the brain that generates them will simply stop producing.

Never Reject During Generation: The key insight is to generate ideas continuously without filtering them in the moment. You sort them out later. This is similar to the Creativity Faucet concept—you need to let the bad ideas flow out first before the good ones emerge.
Do It While Learning: “I don’t think I’ve ever done anything I’m not good enough to do because I get good at the thing while doing it.” This reframes the common fear of not being ready—you become ready by starting.
Fun as the Filter: Only work on things you think are fun. This is the real filter, not whether you’re “good enough” or whether the idea is “good enough” initially.
Ideas Require Action: Ideas are everywhere, but most people don’t act on them. The muscle being trained isn’t just idea generation—it’s the habit of execution.

This connects beautifully with The Motern Method, a book about an artist who released 23,000+ songs by embracing quantity and rejecting perfectionism.

Slowing Down to Go Deeper

David Cain’s article on default settings being too high offers a counterintuitive productivity insight: slowing down often yields better results than rushing.

Reading Aloud: Limiting yourself to mouth-speed rather than eye-speed prevents rushing through text, missing important details, and losing interest. If you’re enjoying something, why would you want to be done with it sooner?
The Vacuum Analogy: Passing a vacuum too quickly over carpet means you miss half the dirt. Slow down, and you can hear how much more grit gets picked up. The same applies to reading and eating—the good stuff (meaning in text, pleasure in food) rises up to meet you in the extra time you give it.
Quality Over Speed: This challenges the default assumption that faster is better. Sometimes our cultural “default settings” for speed are calibrated too high for actual comprehension and enjoyment.

This resonates with my experience using AI tools—the temptation is to go faster, but often the value comes from slowing down and engaging more deeply with the material.

Learning Tacit Knowledge: Copying Better

Cedric Chin’s piece on acquiring tacit knowledge from experts provides a practical framework for learning skills that can’t be easily articulated.

Four Key Elements: When observing experts, focus on their cues (what they notice first), expectancies (what they expect to happen next), goals (their priorities), and actions (courses of action that immediately come to mind).
Prototypes vs. Options: Experts rarely compare multiple options—they pick the first available option that fits their criteria because they’ve built up mental prototypes. If you find yourself doing option comparison in a situation where a colleague doesn’t, that’s a signal they have a prototype you lack.
Narrative Construction: Experts construct narratives or simulations to explain what they’re seeing, matching patterns against different prototypes. This is fundamentally different from following explicit rules.

This framework is particularly relevant for software engineering, where so much expertise is tacit—knowing when to refactor, which abstractions to choose, how to structure systems. These aren’t things you can learn from documentation alone.

Obsidian Links

What I Touched This Week 2025-12-27

me@iany.me (Ian Yang) — Sat, 27 Dec 2025 00:00:00 +0000

This journal is generated by AI

State Machines for Simplifying Complex Logic

This week I dove into using state machines as a tool for managing complex application logic. Dave Thomas’s approach in his book “Simplicity” resonated with me: state machines aren’t as complicated as people make them out to be, and they’re a great way of turning deeply nested code into nice linear chunks.

Data Over Code: The core insight is that data is easier to work with than code—it’s easier to reason about, manipulate, and change. You don’t need complex libraries or long-winded pattern-based approaches when you need a state machine; all you need is a lookup table.
State Transition Formula: The fundamental model is State(S) x Event(E) -> Actions(A), State(S'). This simple formula captures the essence of event-driven behavior in a declarative way.
Event Generation: Actions can return either new state values or generate new events. If an event is returned, the code immediately performs another transition—this allows for elegant chaining of state changes.
State Enter Calls: Erlang’s gen_statem has a powerful feature where the state callback is automatically called with special arguments whenever the state changes, making it easy to perform entry actions without cluttering transition logic.
Postponing Events: A clever pattern is the ability to postpone events—if an event arrives but shouldn’t be handled in the current state, you can defer it until a state change occurs when the event queue restarts from the oldest postponed event.

Sources:

Tokio and Async Rust Patterns

Continuing my study of async Rust, I worked through the Tokio tutorials and explored patterns for shared state and concurrent data structures.

Mutex Selection: As a rule of thumb, using a synchronous mutex from within asynchronous code is fine as long as contention remains low and the lock is not held across calls to .await. The Tokio mutex’s primary feature is that it can be held across an .await without issues, but if contention becomes a problem, the best fix is rarely to switch to the Tokio mutex.
Concurrent Hash Maps: For high-contention scenarios, there are several excellent crate options: dashmap provides a sharded hash map implementation, while leapfrog uses leapfrog probing, and flurry is a port of Java’s ConcurrentHashMap. I also discovered papaya, which is optimized for read-heavy workloads.
Async Trait Variants: The trait_variant and dynosaur crates help with async trait patterns—useful for creating both sync and async versions of traits without code duplication.
Testing with tokio-test: The tokio_test::io::Builder provides mock I/O for testing async code, making it easier to write deterministic tests for network protocols.

Source: Tokio Tutorial - Shared State

Clean Code: Maintenance as the Core of Software

I revisited Robert C. Martin’s “Clean Code” this week, and the framing around maintenance struck me differently in the AI era.

80% is Maintenance: In software, 80% or more of what we do is “maintenance”—the act of repair. Rather than the Western focus on producing good software, we should think more like home repairmen or auto mechanics: proactive maintenance rather than waiting for bugs to surface.
A Million Selfless Acts: Quality is the result of a million selfless acts of care—not just of any great method that descends from the heavens. These acts are simple but not simplistic, forming the fabric of greatness in any human endeavor.
Reading vs Writing Ratio: The ratio of time spent reading vs. writing code is well over 10:1. We are constantly reading old code as part of the effort to write new code, so making code easy to read actually makes it easier to write.
LeBlanc’s Law: “Later equals never.” We’ve all felt the relief of seeing our messy program work and deciding that a working mess is better than nothing, promising to clean it up later. This resonates especially with vibe-coded AI-generated solutions.
The Boy Scout Rule: Leave the campground cleaner than you found it. Small continuous improvements compound over time.
Clean Code Characteristics: Clean code reads like well-written prose, never obscures the designer’s intent, and is full of crisp abstractions and straightforward lines of control. It should make you smile the way a well-crafted music box or well-designed car would.

Source: Clean Code by Robert C. Martin

Obsidian Links

What I Touched This Week 2025-12-20

me@iany.me (Ian Yang) — Sat, 20 Dec 2025 00:00:00 +0000

This journal is generated by AI

The Ladder of Abstraction in System Design

Bret Victor’s “The Ladder of Abstraction” explores how to design interactive systems by moving between levels of abstraction. The core insight is that the most powerful way to gain insight into a system is by stepping up and down the ladder—abstracting over variables to see high-level patterns, then stepping down to concrete representations to understand the details.

Abstracting Over Time: Instead of watching a system evolve in real-time (which is limiting, like a film editor who can’t pause or rewind), we can abstract over time by turning time into a parameter. This creates a trajectory—a function that returns a point for any given time, showing the system’s behavior across all time values.
Stepping Up and Down: We step up to an abstraction by devising a representation that depicts the system across all values of a parameter. We step down by interactively selecting one particular value, allowing us to explore regions of interest quickly. This corresponds to partial application in functional programming.
Visual vs. Symbolic Abstractions: The human brain excels at pattern matching with visual patterns but struggles with logical inferences. Visual abstractions leverage our natural strengths, making it easier to see high-level patterns and tune out low-level clutter.
Metrics and Patterns: By choosing metrics—numbers that summarize system behavior in interesting ways—we can step up another level of abstraction. For example, plotting time to completion versus turning rate reveals patterns that aren’t visible in individual trajectories.
Starting Simple: Beginning with the simplest possible algorithm and thoroughly exploring it helps us understand why and how it’s terrible, providing the foundation for better solutions. The tools we build for simple cases continue to serve us throughout the design process.

Source: The Ladder of Abstraction

AI Investment Bubble and Infrastructure Economics

Howard Marks examines whether AI is experiencing a financial bubble, distinguishing between technological hype and actual market bubbles. His analysis reveals the complex economics of AI infrastructure investment and the risks of debt-financed expansion.

Bubbles vs. Technological Progress: Market bubbles aren’t caused directly by technological developments but by excessive optimism applied to those developments. However, Marks notes that “inflection bubbles” based on revolutionary developments can accelerate technological progress while still destroying wealth—they’re both collective delusions and expressions of collective vision.
The Compression Effect: If people remained patient and value-insistent, novel technologies would take decades to build out. The hysteria of bubbles compresses this process into a short period, with some money going to life-changing investments in winners but a lot being incinerated.
Circular Capital Flows: OpenAI receives billions from tech companies but also sends billions back to pay for computing power. Nvidia’s $100 billion investment in OpenAI flows back as the startup buys or leases Nvidia’s chips, creating circular capital flows that raise questions about actual value creation.
Debt-Financed Expansion: Major tech companies (Oracle, Meta, Alphabet) have issued 30-year bonds to finance AI investments. With close to half a trillion in expected spending next year but only $350bn collectively in the bank, heavy debt usage creates risks of overcapacity and depressed returns.
The Scale of Trillions: A trillion dollars is a dollar a second for 31,700 years—a scale that’s difficult to comprehend but represents the magnitude of AI infrastructure investment being discussed.

Source: Is It A Bubble

Becoming AI-Native in Daily Workflows

Jeff Su’s video provides practical strategies for integrating AI into daily work, moving beyond simple prompting to building sustainable AI-native workflows that anchor conversations, leverage swipe files, and strategically allocate tasks between AI and manual work.

Anchoring Important Conversations: If an AI conversation takes more than 10 minutes or produces something you’ll reference again, anchor it to your workspace immediately. This creates a searchable archive of valuable AI interactions and outputs.
AI Swipe Files: Create a dedicated folder for good examples—business proposals, code patterns, writing samples—that AI can reference. Instead of starting from scratch, you open your swipe folder to find examples that guide AI toward the quality and style you want. This acts as a curated reference library for AI.
Task Breakdown and Allocation: Before writing anything, break work into steps and microtasks. Then decide whether each microtask should be done manually or with AI, and specify the exact tool best suited for that task. For projects taking more than an hour, spend 5-10 minutes mapping steps and tagging which are AI or manual.
Battle-Tested Prompts: You don’t need a thousand random prompts—you need 10-15 battle-tested ones that you can use every day. Focus on quality and refinement rather than quantity.

Sources: Give Me 9 Minutes, I’ll Make You AI-Native

Obsidian Links

What I Touched This Week 2025-12-13

me@iany.me (Ian Yang) — Sat, 13 Dec 2025 00:00:00 +0000

This journal is generated by AI

This week I dove deep into Pieter Hintjens’ “Social Architecture,” a comprehensive guide to building sustainable open source communities. The book provides a framework for understanding how successful communities function, with direct relevance to my work on CKB Fiber and other open source projects.

The C4 Process: An evolution of the GitHub Fork + Pull Model that emphasizes problem-first thinking. All patches must start by identifying a clear problem before proposing solutions. This creates a culture where contributors focus on real needs rather than speculative features.
Optimistic Merging: Maintainers should merge patches rapidly, even if imperfect. This creates opportunities for mentoring—when a patch needs work, other contributors naturally step in to help, building relationships and improving code quality through collaboration rather than gatekeeping.
Free Entry and Non-Tribalism: Successful communities welcome competition and experimentation. If starting a competing project gets a negative emotional response, the group is too tribal. Healthy communities applaud new competitors as spaces for learning and innovation.
The 20 Principles: From strong mission and transparency to minimalism and sense of humor, Hintjens identifies key characteristics of thriving communities. Particularly resonant: “Perfection precludes participation”—releasing buggy, half-finished work provokes contributions more effectively than polished releases.
Economic Incentives: We’re economic animals, and architecture must provide economic incentive to invest. Whether it’s reputation, money, or skill development, contributors need clear value propositions. Think of architecture as a marketplace, not just an engineering design.

Source: Social Architecture

AI-Assisted Development and Learning

Multiple articles this week explored how to effectively use AI as a development and learning partner, moving beyond simple code generation to more sophisticated workflows.

Learning with AI: Scott Young emphasizes using AI for book recommendations and practice problem generation rather than summaries. AI tutoring works better than teaching because specific questions constrain answers more effectively. For repetitive learning tasks, building applications can be more consistent than repeated prompting.
Agent Design Challenges: Armin Ronacher highlights that differences between models are significant enough that you’ll likely need custom abstractions. Key insights include using static system prompts with dynamic messages for caching, and hiding execution failures from context by running potentially failing tasks in subagents until they succeed.
CLAUDE.md Best Practices: Kyle Mistele recommends keeping CLAUDE.md under 300 lines (ideally under 60), with task-specific instructions in separate markdown files. Most importantly: “Never send an LLM to do a linter’s job”—use deterministic tools whenever possible since LLMs are expensive and slow compared to traditional tooling.

Additionally, Ed sent me an email to introduce his app, Grasp, which I found impressively aligned with these best practices and strategies from the past two weeks’ articles.

Sources:

Git Workflow Improvements

I published a blog post about backing up ignored files using Git remote branches, solving a problem I’ve had for years. The solution uses Git’s low-level plumbing commands to store ignored files (like local configs, IDE settings, or personal scripts) in a separate remote branch without affecting the main branch or working directory.

The Problem: Files that need backup but shouldn’t be in main branch history—local development settings, IDE configurations, personal notes, or workflow-specific scripts.
The Solution: A git-store-file script that uses a temporary Git index to commit ignored files to a remote branch (default: origin/_store). This keeps everything in one repository while maintaining clear separation.
Technical Approach: Uses GIT_INDEX_FILE for isolated index manipulation, git read-tree to load branch state, git add -f for ignored files, and git commit-tree for direct commit creation—all without touching the working directory.

Source: ♯ Backup Ignored Files with Git Remote Branch

Obsidian Links

Backup Ignored Files with Git Remote Branch

me@iany.me (Ian Yang) — Fri, 12 Dec 2025 03:22:58 +0800

When working with Git repositories, there are often files that need to be backed up but shouldn’t be committed to the main branch. These might include local development settings, IDE configuration files, personal notes, or development scripts that are specific to your workflow. The challenge is finding a way to back up these ignored files without polluting the main repository history.

The Original Solution

My original approach was to use a separate repository to store backup files for all repositories and create symbolic links. This worked, but had several drawbacks:

Backup files were disconnected from their source repositories, making it harder to track what belongs where
Backing up new files required moving them to the backup repository and then creating symbolic links

A Better Approach: Remote Branch

Instead of using a separate repository, we can use a remote branch within the same repository. This approach offers several advantages:

Everything stays in one repository
When you clone the repository, the backup branch comes with it
Backup files are stored in a separate branch, keeping the main branch clean
Full Git history for backup files, just like any other branch

The Script

With AI assistance, I developed git-store-file, a tool for managing ignored files by storing them in a remote branch (default: origin/_store). This keeps backup files separate from your working branch without interfering with regular development. The script is available in Python.

Installation

Download the script and make it executable:

curl -o ~/bin/git-store-file https://raw.githubusercontent.com/doitian/dotfiles-public/master/default/bin/git-store-file
chmod +x ~/bin/git-store-file

Usage

The script has four main commands: store, status, restore, and ls.

Store Files

Store one or more files to the remote branch, including files that are ignored by Git:

# Store a single file
git-store-file config.local.json
# Store multiple files
git-store-file config.local.json secrets.env
# Use a custom branch name
git-store-file --branch backup config.local.json
# Use a custom remote
git-store-file --remote upstream config.local.json

When you run the store command, the script will:

Create a temporary Git index to avoid conflicts with your working directory
Load the target branch’s current state into the temporary index
Add the specified files using git add -f to include ignored files
Create a commit with the changes
Display commit statistics and prompt for confirmation
Push the commit to the remote branch

Check Status

Check which files stored in the remote branch have been modified in your local working directory:

# Check status
git-store-file status
# Show diff for modified files
git-store-file status --diff

Restore Files

Restore files from the remote branch to your working directory:

# Restore a specific file
git-store-file restore config.local.json
# Restore all files from the branch
git-store-file restore

List Files

List all files stored in the remote branch:

git-store-file ls

Options

-b, --branch BRANCH: Specify the branch name (default: _store)
-r, --remote REMOTE: Specify the remote name (default: origin)
-h, --help: Show help message

Examples

# Store local configuration
git-store-file .env.local
# Check what's changed
git-store-file status -d
# Restore after cloning
git-store-file restore .env.local
# List all backed up files
git-store-file ls

How It Works

The script uses Git’s low-level plumbing commands to manipulate the repository without affecting your working directory:

Temporary Index: Uses the GIT_INDEX_FILE environment variable to create a temporary index, completely isolated from your working directory
Read Tree: Loads the target branch’s tree structure into the temporary index
Force Add: Uses git add -f to add files even if they’re listed in .gitignore
Commit Tree: Creates a commit object directly using git commit-tree, bypassing the normal commit workflow
Direct Push: Pushes the commit hash directly to the remote branch reference

This low-level approach ensures that:

Your working directory remains unchanged
The main branch is never affected
Ignored files can be stored without modifying .gitignore
The backup branch maintains full Git history

Conclusion

The git-store-file script solves the problem of backing up ignored files in a clean, Git-native way. By leveraging a remote branch, it keeps everything in one repository while maintaining clear separation between your main codebase and backup files. Whether you’re managing local configurations, IDE settings, or personal development scripts, this tool provides a simple and reliable backup solution that integrates seamlessly with your existing Git workflow.

What I Touched This Week 2025-12-06

me@iany.me (Ian Yang) — Sat, 06 Dec 2025 00:00:00 +0000

This journal is generated by AI

Fuzzing Strategies from TigerBeetle

This week I dove deep into TigerBeetle’s fuzzing philosophy through several articles by Aleksey Kladov. The collection reveals a systematic approach to building testable systems from the ground up.

Design for Fuzzability First: You don’t build a system and then add a fuzzer—the process is almost reversed. Start by sketching minimal interfaces that yield themselves to efficient fuzzing. Minimize the interface by eliminating accidental dependencies and leaving only essential ones.
Data-Oriented Design: Apply data-oriented design principles—think in terms of input data, output data, and the fundamental data transformation the system implements. This makes the code more easily fuzzable.
Four Fuzzer Strategy: Use multiple fuzzing approaches: (1) positive space fuzzing with ideal lab environments to verify correctness, (2) negative space fuzzing calling all public methods in random order to break things, (3) boundary testing for valid vs. almost-valid-but-invalid codes, and (4) whole subsystem fuzzing.
Randomness in Tests: Don’t always use hard-coded seeds. Zig’s approach is best—provide std.testing.random_seed that’s different per run but generated outside the test process. Run tests twice: once with a hard-coded seed for regression testing, and once with a truly random seed for coverage.

Sources:

Lightning Network Mobile Nodes and Self-Custody

Stephen DeLorme’s article on Lightning self-custody and mobile nodes provided valuable insights into the future of Bitcoin payments, with direct relevance to my work on CKB Fiber.

Mobile Receiving Nodes: For receiving-only nodes, you don’t need routing, meaning you don’t need all that database storage. This was pioneered by projects like Breez, Phoenix, Mutiny wallet, Blixt, and newer versions of Zeus.
Offline Payments Problem: Even the sharpest performing mobile lightning wallets suffer from a lack of offline payments, which has severely tarnished the perception of Lightning. BIP-353 user names distributed via DNS and recent LDK PRs for async payments are addressing this.
Capital Efficiency: Splicing is a powerful tool for easing capital constraints for LSPs. The option_zero_reserve allows channel partners to choose not to use a channel reserve balance—great for UX, though it requires solving minimal capacity restrictions (relevant for CKB Fiber).
Graduated Wallet Model: A wallet that begins with a custodial service or trust-minimized technology, then graduates to a Lightning channel when the balance grows to a certain threshold. This helps LSPs avoid opening “non-productive” channels to users just experimenting with the app.
Dust Limit Considerations: Amounts below the dust limit (like a 21 sat Nostr zap) wouldn’t be claimable on-chain anyway, suggesting alternative approaches for micro-transactions.

Source: Lightning Self-Custody Works: Why Mobile Nodes Are the Future of Bitcoin

Think First, AI Second

Ines Lee’s article on using AI as a thinking partner rather than a solution generator resonated deeply with my own experience using AI tools.

Active vs. Passive AI Use: Active AI use means building understanding while collaborating with the model. Frame the problem yourself, make an initial pass, then use AI to challenge assumptions, uncover blind spots, and sharpen arguments. Studies show this approach maintains cognitive engagement even while using AI.
AI as Coach, Not Cheerleader: Shift AI from talking to you about your work (where it’s sycophantic) to talking to other editors about your work (where it’s professionally candid). You’re no longer the audience, so it drops the protective politeness.
Combat Illusion of Understanding: AI explains things in ways that are easy to follow, making us susceptible to the “illusion of understanding.” We overestimate what we’ve learned. Real comprehension emerges when forced to articulate thinking, because explaining reveals gaps we didn’t know existed.
Practical Prompts: Use prompts like “Ask exactly 5 high-leverage questions before proposing solutions,” “Act as an editor recommending whether to publish this piece,” “Analyze my reasoning and create an architecture of my thinking,” “Switch to devil’s advocate mode and dismantle my thesis,” and “Ask me to explain this as if teaching it to someone else.”

Source: Think First, AI Second

Obsidian Links

What I Touched This Week 2025-11-29

me@iany.me (Ian Yang) — Sat, 29 Nov 2025 00:00:00 +0000

This journal is generated by AI

Software Design Insights from TigerBeetle

This week I went deep into several articles from Alexey Kladov (matklad) and TigerBeetle’s engineering blog. The collection offers practical wisdom on building robust systems.

Code Review Workflow: Instead of reviewing diffs in a web UI, pull the branch locally, soft-reset to the base, then navigate through the diff using magit. Use the git staging area to mark files you’ve reviewed—treating the review process like authoring the code yourself.
Clockless Time Tracking: Rather than injecting a Clock dependency, push time into the system at fixed cadence via a tick method. For single-instant needs, use Call Site Dependency Injection by passing now: Instant directly to methods.
Write Last, Read First: When dealing with systems of record (source of truth) and systems of reference (derived data), write to the system of reference first, then write to the system of record last. Read in reverse order. This maintains application-level consistency.
Function Shape Matters: Functions should have an “inverted hourglass” shape—large implementations relative to their interfaces. Hourglass-shaped functions (small body, large interface) are a code smell. The 100-column limit exists so you can fit two files side-by-side on modern displays. Functions should fit on a screen (~60-70 lines).

Sources:

Self-Consistency Over Self-Discipline

An essay on achieving a good life without rigid self-discipline (“谈谈不自律的良好生活”) resonated with me this week. The author argues for balance over brute-force willpower.

Balanced Love: Drawing from Fromm’s The Art of Loving, healthy self-regard requires combining unconditional and conditional love. Pure unconditional love becomes indulgence; pure conditional love becomes self-attack.
Understanding Over Judgment: When you break a diet for your favorite ice cream, the productive response isn’t self-criticism—it’s understanding why you acted that way. Change requires awareness, care, creativity, and patience rather than pure constraint.
Goals as Direction: Goals shouldn’t be used to judge or lock down your future. A proper goal is merely a direction—like pointing at a distant peak and saying “I want to go there.” This supports Don’t Set a Goal For 2026 Until You Watch This.
Life’s Balance: Abstract learning (philosophy) without grounding becomes detached from life’s simple pleasures. All socializing without solitude leaves no room for reflection and creativity. Life needs all five flavors, both meat and vegetables.

Source: 谈谈不自律的良好生活

Effective Reading Strategies

A practical guide on retaining what you read offered some actionable techniques worth implementing.

Preview First: Spend 5-10 minutes per chapter skimming the table of contents, headings, introduction, and summary before diving into details. This builds a mental scaffold.
Question-Driven Reading: Before reading a section, convert the heading into a question (e.g., “What is X?”) and read to find the answer. This active approach improves engagement and retention.
Concise Personal Notes: Rather than transcribing passages verbatim, write brief paraphrases or bullet points in your own words. The act of reformulation strengthens memory.

Source: How to Remember Everything You Read

Obsidian Links

How to Activate mise for Cursor When It Runs Shell Commands

me@iany.me (Ian Yang) — Wed, 26 Nov 2025 11:31:37 +0800

When using mise with Cursor, you may notice that the mise environment is not activated when Cursor executes shell commands. This occurs because Cursor launches a non-login shell, which initializes differently than an interactive login shell and therefore does not automatically source your usual mise setup.

The Problem

Cursor runs commands in a non-login shell, which means:

For zsh: Only .zshenv is loaded (not .zshrc)
For bash: Only .bash_profile is loaded (not .bashrc)

If you’ve configured mise activation in .zshrc or .zprofile, it won’t be available when Cursor executes commands.

The Solution

The solution is to activate mise in .zshenv (for zsh) or .bash_profile (for bash) when the file is loaded by Cursor. You can detect Cursor by checking for the CURSOR_AGENT environment variable.

Add this to your ~/.zshenv or ~/.bash_profile:

# Activate mise when running in Cursor
if [[ -n "$CURSOR_AGENT" ]]; then
eval "$(mise activate)"
fi

Why This Works

.zshenv (or .bash_profile) is always sourced for non-login shells
The CURSOR_AGENT environment variable is set when Cursor runs commands
By conditionally activating mise only when CURSOR_AGENT is present, you avoid potential conflicts or slowdowns in other non-login shell contexts
This ensures mise and all its configured tools are available when Cursor executes terminal commands

After adding this configuration, rerun Cursor chats, and mise should be available in all Cursor shell commands.

Temporary Vi Mode in PowerShell

me@iany.me (Ian Yang) — Sat, 22 Nov 2025 23:17:05 +0800

I miss the feature in readline (Bash/Zsh) where Ctrl+x, Ctrl+v switches to Vi command mode temporarily. In that workflow, entering Insert mode switches back to Emacs mode. PSReadLine has a command ViCommandMode, but binding it directly in Emacs mode will report errors on every key input.

The solution requires handling the mode change event to toggle the global EditMode between Emacs and Vi.

When entering “Insert” mode (the default for Emacs users), we force the mode to Emacs and set up the trigger for the temporary Vi mode. When that trigger (Ctrl+x, Ctrl+v) is fired, we switch the edit mode to Vi and jump to command mode.

Here is the configuration for your $PROFILE:

function OnViModeChange {
if ($args[0] -eq 'Insert') {
Set-PSReadLineOption -EditMode Emacs
Set-PSReadlineKeyHandler -Chord "Ctrl+x,Ctrl+v" -ScriptBlock {
Set-PSReadLineOption -EditMode Vi
[Microsoft.PowerShell.PSConsoleReadLine]::ViCommandMode()
}
# Add other Emacs key bindings here.
# Switching `EditMode` resets key bindings to their defaults.
# Remember to reconfigure them.
# Set-PSReadlineKeyHandler -Chord "Ctrl+w" -Function BackwardKillWord
}
}
Set-PSReadLineOption -ViModeIndicator Script
Set-PSReadLineOption -ViModeChangeHandler $Function:OnViModeChange
Set-PSReadLineOption -EditMode Emacs
# Reuse the function to start Emacs mode
OnViModeChange Insert

Switching EditMode resets key bindings to their defaults. Remember to reconfigure them.

Study on Quotient Spaces

me@iany.me (Ian Yang) — Tue, 18 Nov 2025 21:23:25 +0800

I’m reading Linear Algebra Done Right by Axler and found the section on quotient spaces difficult to understand, so I researched and took these notes.

Definitions

3.95 notion: $v + U$

Suppose $v \in V$ and $U \subseteq V$ . Then $v + U$ is the subset of $V$ defined by

 $v + U = \{v + u : u \in U\}.$

Also called a translate. Attention that a translate is a set.

3.97 definition: translate

Suppose $v \in V$ and $U \subseteq V$ , the set $v + U$ is said to be a translate of $U$ .

Quotient space is a set of all translates (set of sets):

3.99 definition: quotient space, $V/U$

Suppose $U$ is a subspace of $V$ . Then the quotient space $V/U$ is the set of all translates of $U$ . Thus

 $V/U = \{v + U : v \in V\}.$

Quotient space is a set of sets. There are duplicates for each $v \in V$ because for some $v_1, v_2 \in V$ , $v_1 + U$ and $v_2 + U$ can be identical set.

A quotient space $V/U$ is formed by “collapsing” a subspace $U$ to zero within a larger vector space $V$ . This construction is based on an equivalence relation where two vectors $x, y \in V$ are considered equivalent if their difference lies in $U$ —that is, $x \sim y$ if and only if $x - y \in U$ . wikipedia

Lemmas

3.101 two translates of a subspace are equal or disjoint

Suppose $U$ is a subspace of $V$ and $v, w \in V$ . Then

 $v - w \in U \iff v + U = w + U \iff (v + U) \cap (w + U) \neq \emptyset$

If two translates are not disjoint (the union set is not empty), they must be equal. So they are equal or disjoint.

All distinct translates of a subspace are disjoint. Given any $v \in V$ , it belongs to only one translate.

Since the quotient space $V/U$ is a set of translates of a subspace, it is like a disjoint partition of values in $V$ . By using the definition of quotient map

3.104 definition: quotient map, $\pi$

Suppose $U$ is a subspace of $V$ . The quotient map $\pi : V \to V/U$ is the linear map defined by

 $\pi(v) = v + U$

for each $v \in V$ .

We can write that

 $\pi(v_1) = \pi(v_2) \iff v_1 - v_2 \in U$

The quotient map has two essential properties:

The null space of $\pi$ is exactly the subspace $U$ , because $v+U=0+U \iff v-0 \in U \iff v \in U$
The range of $\pi$ is the entire quotient space $V/U$

Quotient Space Is a Vector Space

First define the addition and scalar multiplication operations:

3.102 definition: addition and scalar multiplication on $V/U$

Suppose $U$ is a subspace of $V$ . Then addition and scalar multiplication are defined on $V/U$ by

 $\begin{align*} (v + U) + (w + U) &= (v + w) + U \\ \lambda(v + U) &= (\lambda v) + U \end{align*}$

for all $v, w \in V$ and $\lambda \in \mathbf{F}$ .

$v+U$ is not the unique way to represent a member in $V/U$ , because there may exist $v'\ne v$ that $u + U = v' + U$ . The operations make sense only when the choice of $v$ to represent a translate makes no differences.

Specifically, suppose $v_1, v_2, w_1, w_2 \in V$ such that

 $v_1 + U = v_2 + U \quad\textrm{and}\quad w_1 + U = w_2 + U$

From the addition definition:

 $\begin{align*} (v_1+U) + (w_1+U) &= (v_1 + w_1) + U \\ (v_2+U) + (w_2+U) &= (v_2 + w_2) + U \end{align*}$

The left side of the two equations indeed are the different representation of the same equation, so we must show that the right side equal: $(v_1 + w_1)+U=(v2+w2)+U$ .

This applies to scalar multiplication as well:

 $\begin{align*} \lambda(v_1 + U) &= (\lambda v_1) + U \\ \lambda(v_2 + U) &= (\lambda v_2) + U \end{align*}$

We must show that $(\lambda v_1) + U = (\lambda v_2) + U$ .

Dimension

The dimension of the quotient space is given by a simple subtraction, relating the dimension of $V/U$ to the “lost” dimension of $U$ :

3.105 dimension of quotient space

Suppose $V$ is finite-dimensional and $U$ is a subspace of V. Then

 $\text{dim } V/U = \text{dim }V - \text{dim }U.$

Linear Map from V/(null T) to W

3.106 notation: $\widetilde{T}$

Suppose $T \in \mathcal{L}(V, W)$ . Define $\widetilde{T}: V/(\text{null } T) \to W$ by

 $\widetilde{T}(v + \text{null } T) = Tv.$

Think of merging inputs having the same output. These inputs will be the same input in the quotient space $V/(\text{null } T)$ .

For any $v_1, v_2 \in V$ that $Tv_1 = Tv_2$ , $v_1 + \mathrm{null}\, T$ and $v_2 + \mathrm{null}\, T$ are the same value in $V/(\mathrm{null}\, T)$ . This makes $\widetilde{T}$ injective. Because $\mathrm{range}\,\widetilde{T}=\mathrm{range}\, T$ , $\widetilde{T}$ is also surjective on to $\mathrm{range}\, T$ .

3.63 invertibility $\iff$ injectivity and surjectivity

A linear map is invertible if and only if it is injective and surjective.

3.63 shows us that $\widetilde{T}$ is invertible, and according to the definition of isomorphic, $V/(\mathrm{null}\, T)$ and $\mathrm{range}\,T$ are isomorphic vector spaces and $\widetilde{T}$ is their isomorphism.

3.69 definition: isomorphism, isomorphic

An isomorphism is an invertible linear map.
Two vector spaces are called isomorphic if there is an isomorphism from one vector space onto the other one.

One of the key uses of $\widetilde{T}$ is demonstrating a canonical isomorphism. For any linear map $T \in \mathcal{L}(V, W)$ , the quotient space $V/(\text{null } T)$ is isomorphic to the image space $\text{range } T$ . This shows that the quotient space $V/(\text{null } T)$ serves as a way to “mod out” the non-injective part of $T$ .

Hosting Static Site on Cloudflare R2

me@iany.me (Ian Yang) — Wed, 22 Oct 2025 18:46:38 +0800

This post explains how to set up a static site on Cloudflare R2.

I recently migrated my blog to Cloudflare R2, and the process went smoothly until I encountered R2’s lack of native support for rewriting URLs to index.html files. This post explains how I resolved this issue.

Setting Up

Create the bucket.
Add the custom domain blog.iany.me. To redirect iany.me and www.iany.me to the blog, add these as custom domains as well. Since I host the domain in Cloudflare, the DNS record is automatically configured.

Publishing

I use rclone to deploy the site to R2. Below is the GitHub workflow I employ. Noting that the fetch-depth option for actions/checkout retrieves the complete repository history. This works with Hugo’s --enableGitInfo flag to accurately determine article creation dates.

name: Deploy Hugo Site to Cloudflare R2
on:
push:
branches:
- master
workflow_dispatch:
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install latest Hugo
run: |
TAG=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest \
| grep '"tag_name":' \
| head -1 \
| sed -E 's/.*"([^"]+)".*/\1/')
curl -L "https://github.com/gohugoio/hugo/releases/download/${TAG}/hugo_${TAG#v}_Linux-64bit.tar.gz" \
-o hugo.tar.gz
tar -xzf hugo.tar.gz hugo
sudo mv hugo /usr/local/bin/
hugo version
- name: Install rclone
run: |
curl https://rclone.org/install.sh | sudo bash
- name: Build site with Hugo
run: hugo --minify --enableGitInfo
- name: Configure rclone for Cloudflare R2
env:
R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
run: |
rclone config create r2 s3 \
provider Cloudflare \
access_key_id "${R2_ACCESS_KEY_ID}" \
secret_access_key "${R2_SECRET_ACCESS_KEY}" \
endpoint "${R2_ENDPOINT}" \
--quiet
- name: Deploy to Cloudflare R2
env:
R2_BUCKET: ${{ secrets.R2_BUCKET }}
run: |
rclone copy public/ r2:"${R2_BUCKET}" \
--checksum \
--no-traverse \
--verbose

Rules

Go to the dashboard of the domain iany.me and go to the section Rules.

Redirect Rules

I have added 3 redirect rules:

When incoming requests have a hostname iany.me or www.iany.me, redirect to concat("https://blog.iany.me", http.request.uri.path).
Redirect https://blog.iany.me/*/index.html to https://blog.iany.me/${1}/.
Redirect http://* to https://${1}

Although the Redirect Rules manual says if multiple rules make the same modification, the last executed rule wins, I have to put rule 2 before 3.

URL Rewrite Rules

I added 2 rewrite rules for index.html:

When the request URL is https://blog.iany.me or https://blog.iany.me/, rewrite the URL path to /index.html.
When the request URL matches https://blog.iany.me/*/, rewrite the path to ${1}/index.html

Cache Rules

I added 2 cache rules for images and static content:

Set cache TTL to 1 month for png, jpg, jpeg, and svg files.
Set cache TTL to 1 year for files in /js, /fonts, /css, and /uploads.

Explain Atomic Cross-Chain Swaps by Herlihy

me@iany.me (Ian Yang) — Fri, 19 Sep 2025 22:26:46 +0800

This article explains the paper [Herlihy, 2018]¹ in simple words. In the paper, Herlihy has introduced an effective atomic cross-chain swap protocol in order to exchange assets across multiple blockchains among multiple parties.

Model

A swap can be modeled using a directed graph $(V, A)$ . $V$ is a set of involved users, and $A$ is a set of payments. Each payment is annotated as $(u, v)$ where $u$ is the payer and $v$ is the payee. The Atomic Swap Protocol ensures that when all users follow the protocol, if one payment succeeds, all other payments must succeed.

For example, following model represents a swap that Alice sends a payment to Bob, and Bob sends a payment to Carol.

 $\begin{array}{rl} V &= \{\mathrm{Alice}, \mathrm{Bob}, \mathrm{Carol}\} \\ A &= \{(\mathrm{Alice},\mathrm{Bob}), (\mathrm{Bob}, \mathrm{Carol})\} \end{array}$

Simple Protocol

When all payments can be connected into a path, like the example above, the protocol is simple and is similar to the payment hops in lightning network.

A path is annotated as $(u_1, \ldots, u_l)$ , which is consisted of $l-1$ payments: $(u_1, u_2),(u_2, u_3),\ldots,(u_{l-1}, u_l)$ .

The final payee $u_l$ generates a secret $s$ and sends its hash $H(s)$ to the payer $u_1$ . The payer $u_1$ creates a Hash Time Locked Contract $(H(s), 2(l-1)\Delta)$ that either $u_2$ can get the fund by providing the secret $s$ , or $u_1$ can get the refund when time has elapsed $2(l-1)\Delta$ units. The users $u_i$ from $u_2$ to $u_{l-2}$ creates a Hash Time Locked Contract $(H(s), 2(l-i)\Delta)$ when they confirm that they have received the inbound contract. The payee $u_l$ can settle the deal by providing the secret $s$ to $u_{l-1}$ , and each user uses the received secret $s$ to settle their inbound contract.

The simple protocol also works when payee and payer are the same user ( $u_1 = u_l$ ). From engineering points, it should work for most scenarios.

Arbitrary Connected Directed Graph

The paper also extends the swap protocol to arbitrary connected directed graph. A connected directed graph means for any two user $u, v$ , there are a payment path from $u$ to $v$ , and a payment path from $v$ to $u$ . Such directed graphs contain loops, as in the example below:

 $\begin{array}{rl} V = \{&A, B, C, D, E, F\} \\ A = \{ \\ &(A, B), (B, C), (C, A), \\ &(C, D), (D, B), \\ &(D, E), (E, F), (F, D) \\ \} \\ \end{array}$

Leaders Selection

The protocol must select a Feedback Vertex Set of the directed graph as leaders. A feedback vertex set is a subset of $V$ that once removed from the graph, there will be no loops in the graph. For example, $(B, D)$ is a feedback vertex set of the example above. When there are multiple candidates, choose an arbitrary set.

The leaders generate secrets and publish their hashes. If $(B, D)$ are selected, they should publish $(H(s_B), H(s_D))$ .

The protocol then move forward in two phases.

Phase One

In the first phase, users offer outbound contracts to counterparty for each payment.

Leaders must offer contracts first:

Publish a contract on every outbound payments, then
wait until all inbound contracts have been published.

Followers must confirm inbound contracts first:

Wait until correct inbound contracts have been published, then
publish a contract on every outbound payments.

The contracts are Hash Time Locked Contracts $(h, t)$ that payee can get the fund using the proof to unlock $h$ , or the payer gets the refund after timeout $t$ .

For a payment $(u, v)$ , the proof of $h$ is a triple $(s, p, \sigma)$ where

$p$ is any payment path $(u_0, \ldots, u_k)$ starting from the payee $v$ ( $u_0 = v$ ) to a leader $u_k$ . The path $p$ can have a length of 0 if $v$ itself is a leader.
$s$ is the secret generated by the ending leader of the path $p$ , and $h = H(s)$ .
$\sigma$ is a nested signatures of $s$ signed by users in the path $p$ .
- The innest signature is $\mathrm{sig}_k = \mathit{sig}(s, u_k)$
- For user $u_i$ ( $0 \leq i \leq k - 1$ ), the signature is $\mathrm{sig}_i = \mathit{sig}(\mathrm{sig}_{i+1}, u_i)$
- $\sigma = \mathrm{sig}_0$

The hash lock $h$ can be set to $H(s)$ for the shortest $p$ , or just the hashes of all secrets to all unlocking using arbitrary ending leader of the path $p$ .

The time lock $t$ is $(\mathit{diam}(\mathcal{D}) + |p|)\Delta$ , where

$\mathit{diam}(\mathcal{D})$ is the longest length of a payment path without duplicated users in the directed graph.
$|p|$ is the length of the path $p$ in the hash lock.
$\Delta$ is a configured time unit constant for the time out.

Let’s see two examples.

The first example is the payment from a leader: $(B, C)$ .

There are three candidate path $p$ from the payee $C$ to a leader either $B$ or $D$ :

$(C, A, B)$
$(C, D)$
$(C, D, B)$

$B$ can choose any one, but the shortest one is recommended. Let’s use $(C, D)$ . $B$ can publish the contract because he/she is the leader.

The hash lock for $(B, C)$ is $H(s_D)$ .
The time lock is $6\Delta$ , because the length of the longest path $(A, B, C, D, E, F)$ is 5, and the length of $(C, D)$ is 1.

The second example is the payment from a follower: $(C, A)$ .

$C$ can choose the path $(A, B)$ and publish the contract:

The hash lock is $H(s_B)$ .
The time lock is $6\Delta$

Phase Two

In phase two, leaders can unlock the inbound contracts because they know all secrets. For example, the leader $B$ can unlock the inbound payment $(A, B)$ by offering:

The path $p = (B)$
The secret $s_B$
The signature $sig(s_B, B)$

Followers must trace outbound contracts unlocking events. For example, $A$ can unlock the contract for $(C, A)$ after receiving the unlocking event above:

The path $p = (A, B)$
The secret $s_B$ since B has published it when unlocking $(A, B)$ .
The signature $sig(sig(s_B, B), A)$

Herlihy, M. (2018). Atomic Cross-Chain Swaps (No. arXiv:1801.09515). arXiv. https://doi.org/10.48550/arXiv.1801.09515

Envrc Alternative for PowerShell in Windows

me@iany.me (Ian Yang) — Sat, 06 Apr 2024 08:55:34 +0800

This post introduces a solution for automatically setting up and tearing down shell environments for PowerShell in Windows. It is proposed as a potential alternative to the bash-based tool direnv, which, while effective at loading .envrc files in the current or nearest ancestor directory, has limited compatibility with PowerShell in Windows.

.envrc.ps1

The basic idea is creating a file .envrc.ps1 with two entries: setup and teardown. The setup entry is responsible for setting up the environment up entering the directory, and the teardown entry is used when leaving it.

PowerShell allows code to be executed from a file using the dot command. This means that the entire file can be used as the setup entry. For the teardown entry, a function can be defined within the same file, and I use the function name down.

The layout of the file .envrc.ps1 looks like:

# setup
$env:GH_TOKEN = "secret"
# teardown
function global:down {
$env:GH_TOKEN = ""
}

The global: scope before the function name is necessary when this file is loaded in the hook, as I will do later.

The corresponding commands for setup and teardown entries:

Setup: . .envrc.ps1
Teardown: down

Hook

To hook the setup and teardown entries, I reference this example.

using namespace System;
using namespace System.Management.Automation;
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
# 1. `down` for $eventArgs.OldPath
# 2. `. .envrc.ps1` for $eventArgs.NewPath
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

To run the code snippet, PowerShell 7 or later is required. You can install it from the repository.

Here is the algorithm for identifying setup and teardown entries:

Find the nearest .envrc.ps1 for the old path.
Find the nearest .envrc.ps1 for the new path.
If the two paths are the same, skip the next step.
If they differ, invoke the down function and remove it if it exists. Then, if found, load the .envrc.ps1 file for the new path.

The full code example to be added into PowerShell $PROFILE file.

using namespace System;
using namespace System.Management.Automation;
# existing PowerShell profile contents
# skip when version is less than 7
if ($PSVersionTable.PSVersion.Major -lt 7) {
return
}
# find the .envrc.ps1 in the currenct directory or the nearest ancestor directory.
function Find-NearestEnvrc {
param (
[Parameter(Mandatory=$true)]
[string]$StartDir
)
$currentDir = Resolve-Path $StartDir
while ($currentDir -ne "") {
$envrcPath = Join-Path $currentDir ".envrc.ps1"
if (Test-Path $envrcPath) {
return $envrcPath
}
$currentDir = Split-Path $currentDir -Parent
}
return ""
}
# hook the setup and teardown entries
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
$oldEnvrc = Find-NearestEnvrc $eventArgs.OldPath
$newEnvrc = Find-NearestEnvrc $eventArgs.NewPath
if ($oldEnvrc -ne $newEnvrc) {
Get-Command down -ErrorAction SilentlyContinu
if (Get-Command down -ErrorAction SilentlyContinu) {
down
Remove-Item Function:down
}
if ($newEnvrc -ne "") {
. $newEnvrc
}
}
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

Example Usage

# setup
# set environment variable
$env:GH_TOKEN = "secret"
# load python virtual env
. .venv\Scripts\Activate.ps1
# add a helper function
function global:build {
cargo build
}
# teardown
function global:down {
# unset environment variable
$env:GH_TOKEN = ""
# unload python virtual env
deactivate
# remove the helper function
Remove-Item Function:build
}

How to Verify JoyID WebAuthn Signature

me@iany.me (Ian Yang) — Sun, 17 Dec 2023 17:35:33 +0800

JoyID is a multichain, cross-platform, passwordless and mnemonic-free wallet solution based on FIDO WebAuthn protocol and Nervos CKB.

This post shows how to verify the signature from the method signChallenge of the @joyid/ckb package. The method reference page has a demo. I use the demo to obtain an example response then verify the response using the OpenSSL command line and the Python library PyCryptodome.

The JoyID follows the WebAuthn specification and employs secp256r1 for signing. Although the guide references section 6.3.3 of the WebAuthn specification, titled “The authenticatorGetAssertion Operation”, I discovered that the example in this repository provided me much more helps.

The Response Parsing

This is the example I obtained from the demo.

{
"signature": "MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWxKj79R1rUkB_6nrhJfws82DqHkY_HnqQ",
"message": "K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6IndlYmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmlnaW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUgaHR0cHM6Ly9nb28uZ2wveWFiUGV4In0",
"challenge": "Sign this for me",
"alg": -7,
"pubkey": "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3",
"keyType": "main_key"
}

pubkey

The pubkey field represents the uncompressed public key concatenating two 32-byte integers in hex. PyCryptodome can import the key by prepending the flag 0x04. OpenSSL uses PEM to encode keys, and PyCryptodome can help here to export the key in PEM format.

from Crypto.PublicKey import ECC
pubkey_raw_hex = "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3"
pubkey = ECC.import_key(bytes.fromhex("04" + pubkey_raw_hex), curve_name="secp256r1")
with open("pubkey.pem", "wt") as pemfile:
pemfile.write(pubkey.export_key(format="PEM"))

Double check the key using OpenSSL:

$ openssl ec -text -inform PEM -in pubkey.pem -pubin
...
Public-Key: (256 bit)
pub:
04:35:38:df:d5:3a:d9:3d:2e:0a:6e:7f:47:02:95:
dc:d7:10:57:d8:25:e1:f8:72:29:e5:af:e2:a9:06:
aa:7c:fc:09:9f:df:a0:44:42:da:c3:35:48:b6:98:
8a:f8:af:58:d2:05:25:29:08:8f:7b:73:ef:00:80:
0f:7f:bc:dd:b3
ASN1 OID: prime256v1
NIST CURVE: P-256
...

message

The message is a binary encoded by base64 RFC 4648 §5 without the equal sign (=) paddings. Many base64 tools and libraries require padding equal sign (=) in the end of the string to make the length multiple of 4. The message in the example response has a length 351, which requires one = padding. A trick is always padding two equals at the end of the string before decoding.

The first 37 bytes in message are authenticator data, and the following bytes are client data in JSON.

The section section 6.1 in the WebAuthn specification defines the layout of the authenticator data.

rpIdHash, 32 bytes: the sha256 checksum of the text testnet.joyid.dev
flags, 1 byte: 0x05 in JoyID
signCount, 4 bytes: all zeros

base64 -d <<<'
K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl
YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi
LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln
aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90
IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg
aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0=' |
dd bs=1 count=37 2>/dev/null |
xxd
#=> 00000000: 2b8b 05e1 f030 3efb 898f e4d6 de60 1198
#=> 00000010: c7a7 b864 abbe 6a21 c73b 2e78 7e18 7c52
#=> 00000020: 0500 0000 00

Check the first two lines with the sha256 checksum:

echo -n 'testnet.joyid.dev' | sha256sum
#=> 2b8b05e1f0303efb898fe4d6de601198c7a7b864abbe6a21c73b2e787e187c52 -

The client data JSON looks like this:

base64 -d <<<'
K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl
YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi
LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln
aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90
IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg
aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0=' |
dd bs=1 skip=37 2>/dev/null |
jq
{
"type": "webauthn.get",
"challenge": "U2lnbiB0aGlzIGZvciBtZQ",
"origin": "https://testnet.joyid.dev",
"crossOrigin": false,
...
}

Notice the challenge field. It is the parameter passed to signChallenge, in base64.

base64 -d <<<'U2lnbiB0aGlzIGZvciBtZQ=='
#=> Sign this for me

Attention that message is not the binary to be signed. According to the Figure 4, Generating an assertion signature, in the WebAuthn specification, the binary to be signed is a concatenation of the authenticator data and the sha256 checksum of the client data JSON.

The following code shows how to prepare the message to sign and save it into the file message.bin. Attention that base64 must use the alternative keys - and _ to replace + and / respectively.

Attention

To decode base64 “RFC 4648 §5” in python, use either base64.b64decode(s, altchars="-_") or binascii.urlsafe_b64decode(s).

import base64
from Crypto.Hash import SHA256
message_bin = base64.urlsafe_b64decode(
"K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl"
"YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi"
"LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln"
"aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90"
"IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg"
"aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0==",
)
authenticator_data = message_bin[:37]
client_data = message_bin[37:]
message_to_sign = authenticator_data + SHA256.new(client_data).digest()
with open("message.bin", "wb") as fout:
fout.write(message_to_sign)

Attention

The message in the response is not the binary to be signed. Instead, the binary to be signed is a concatenation of the authenticator data and the sha256 checksum of the client data JSON.

signature

The field signature are two 32-byte integers first encoded in DER, then base64 RFC 4648 §5 without the equal sign (=) paddings.

Many base64 tools and libraries require padding equal sign (=) in the end of the string to make the length multiple of 4. The signature in the example response has a length 95, which requires one = padding.

OpenSSL also stores signature in DER, let’s save one in the file signature.der:

base64 -d <<<"MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWxKj79R1rUkB_6nrhJfws82DqHkY_HnqQ=" > signature.der

The command openssl asn1parse can parse the file signature.der in the DER format.

openssl asn1parse -dump -inform DER -in signature.der
# Output =>
# 0:d=0 hl=2 l= 69 cons: SEQUENCE
# 2:d=1 hl=2 l= 32 prim: INTEGER :2176E6A74EEA72EB784A011E7C9AC3EF51E971476C8BBE370B00239DEDD35EAA
# 36:d=1 hl=2 l= 33 prim: INTEGER :826865C1310CC685B12A3EFD475AD4901FFA9EB8497F0B3CD83A87918FC79EA4

PyCryptodome expects the signature of 64 bytes for two 32-byte integers. Following code uses the asn1 module to extract the raw signature from the DER binary.

import base64
from Crypto.Util.asn1 import DerSequence
signature_der = base64.urlsafe_b64decode(
"MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWx"
"Kj79R1rUkB_6nrhJfws82DqHkY_HnqQ=",
)
signature_seq = DerSequence()
signature_seq.decode(signature_der)
print(signature_seq[0].to_bytes(32).hex())
# => 2176e6a74eea72eb784a011e7c9ac3ef51e971476c8bbe370b00239dedd35eaa
print(signature_seq[1].to_bytes(32).hex())
# => 826865c1310cc685b12a3efd475ad4901ffa9eb8497f0b3cd83a87918fc79ea4

Verifying

PyCryptodome:

from Crypto.Hash import SHA256
from Crypto.Signature import DSS
DSS.new(pubkey, "fips-186-3").verify(SHA256.new(message_to_sign), signature)
print("Verified OK")

OpenSSL:

openssl dgst -sha256 -verify pubkey.pem -signature signature.der message.bin

Full Python code (Gist)

import base64
from Crypto.Hash import SHA256
from Crypto.PublicKey import ECC
from Crypto.Signature import DSS
from Crypto.Util.asn1 import DerSequence
response = {
"signature": "MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWx"
"Kj79R1rUkB_6nrhJfws82DqHkY_HnqQ",
"message": "K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6IndlYmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmlnaW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUgaHR0cHM6Ly9nb28uZ2wveWFiUGV4In0",
"challenge": "Sign this for me",
"alg": -7,
"pubkey": "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3",
"keyType": "main_key",
}
pubkey = ECC.import_key(
bytes.fromhex("04" + response["pubkey"]),
curve_name="secp256r1",
)
with open("pubkey.pem", "wt") as fout:
fout.write(pubkey.export_key(format="PEM"))
message_bin = base64.urlsafe_b64decode(response["message"] + "==")
authenticator_data = message_bin[:37]
client_data = message_bin[37:]
# https://github.com/duo-labs/py_webauthn/blob/master/webauthn/authentication/verify_authentication_response.py
message_to_sign = authenticator_data + SHA256.new(client_data).digest()
with open("message.bin", "wb") as fout:
fout.write(message_to_sign)
signature_der = base64.urlsafe_b64decode(response["signature"] + "==")
with open("signature.der", "wb") as fout:
fout.write(signature_der)
signature_seq = DerSequence()
signature_seq.decode(signature_der)
signature = signature_seq[0].to_bytes(32) + signature_seq[1].to_bytes(32)
DSS.new(pubkey, "fips-186-3").verify(SHA256.new(message_to_sign), signature)
print("Verified OK")

Renaming Browser Tab Names

me@iany.me (Ian Yang) — Fri, 21 Jul 2023 20:31:59 +0800

Renaming browser tab names may seem like a simple task, but it can actually be quite challenging.

Most browsers sync the tab name with the web page title. Therefore, it seems simple to set tab name by setting document.title:

document.title = "Custom Tab Name";

However, many web pages use JavaScript to alter the page title, which would override the custom name. While Object.defineProperty in JavaScript can override the property setter function, it’s not possible to access the original setter function for document.title. Fortunately, browsers sync page titles with the first <title> tag, so setting its content acts as a workaround to set the page title.

Here is the bookmark for renaming a tab. I also add %t as the token for the original page tab title. This is handy such as adding a custom prefix with Work: %t, or restoring the original title without reloading the page by using %t.

// Rename the document title using a bookmarklet.
//
// As a user,
// - Once I have renamed the tab, it should not be overwritten.
// - I can include the token %t as placeholder for the real title.
// - To restore, I can rename the tab to %t
//
// Install: Copy the code to
//
// https://caiorss.github.io/bookmarklet-maker/
//
// and generate the bookmarklet.
// Init only once
if (!("_renameTitle" in document)) {
// Force creating the title tag.
document.title = document.title || "";
const titleEl = document.getElementsByTagName("title")[0];
const titleTokenRegex = /%t/g;
// Remembers the real title
let titleWithoutRenaming = document.title;
// User set title
let titleWithRenaming = "";
// Rename the document title to v.
// If v contains the token %t, replace all occurences to the
// real title.
document._renameTitle = (v) => {
titleWithRenaming = v;
titleEl.innerText = v.replace(titleTokenRegex, titleWithoutRenaming);
};
Object.defineProperty(document, "title", {
// Other code will use document.title setter to change the title.
//
// Remember the new value as the real title but still use the
// title set by user.
set: (v) => {
titleWithoutRenaming = v;
// Once document has defined the title property, its value is
// not synchronized to the tab name.
//
// Here uses a workaround to set the title tag content.
titleEl.innerText = titleWithRenaming.replace(titleTokenRegex, v);
},
get: () => titleEl.innerText,
});
}
const title = prompt(
"Rename tab (Use token %t for original title)",
document.title
);
// title is null when user cancel the dialog.
if (title !== null) {
document._renameTitle(title);
}

Transforming Markdown to Attractive PDFs: A Guide to Using Pandoc with Xelatex

me@iany.me (Ian Yang) — Sat, 29 Apr 2023 21:43:02 +0800

I used to read lengthy and complex articles in the PDF format. Despite the abundance of PDF exporting options, the resulting files often appear unappealing. However, there is a solution. With the pandoc tool and the xelatex backend, you can transform Markdown files into aesthetically pleasing PDFs. In this tutorial, I will guide you through the steps of using pandoc with xelatex and share the lessons I’ve learned.

Installation

Ubuntu users can install the package texlive-xetex and pandoc, In macOS, I recommend a minimal installation:

brew install librsvg pandoc
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr update --all
for pkg in texliveonfly xelatex adjustbox tcolorbox collectbox ucs environ \
trimspaces titling enumitem rsfs xecjk fvextra svg transparent; do
sudo tlmgr install $pkg
done

The library librsvg is required to support SVG images.

Verify the installation by converting a simple markdown file.

echo "# Hello World" > test.md
pandoc --pdf-engine=xelatex -i test.md -o test.pdf

Tips

In LaTeX, the document class serves as the template for the basic page styles.

I’m a fan of koma-script, and I will choose between scrreprt and scrbook depending whether the file to create is more like a report or a book. I recommend try them and the standard classes like report and book, then choose the one that best suites your preferences.

To customize the document class in pandoc, simply set the variable documentclass. Other variables are available for controlling the LaTeX style. I use some of them to define my default style.

DOCUMENTCLASS="${DOCUMENTCLASS:-scrreprt}"
MAINFONT="${MAINFONT:-Helvetica}"
MONOFONT="${MONOFONT:-Cartograph CF}"
pandoc --pdf-engine=xelatex \
--variable fontsize=12pt \
--variable linestretch=1.5 \
--variable geometry=a4paper \
--variable documentclass="${DOCUMENTCLASS}" \
--variable mainfont="${MAINFONT}" \
--variable monofont="${MONOFONT}" \
-i test.md -o test.pdf

Gotchas

CJK

CJK is a collective term for the Chinese, Japanese, and Korean languages. When CJKmainfont is set, pandoc handles CJK characters with the xecjk package.

pandoc --variable CJKmainfont="Noto Serif CJK SC" ...

My recommendation is to only set CJKmainfont when needed to avoid messing up the quotation marks display. Where the article contains a mixture of English and Asian characters resulting in strange looking quotation marks '"“”‘’, consider trying the following solution.

Create a file cjk.latex to force English quotation marks.

% cjk.tex
\AtBeginDocument{%
\XeTeXcharclass`^^^^2019=0
}

Include this file via the pandoc argument -H such as pandoc -H cjk.tex.

The figure below shows the results from the same markdown file on my MacBook. However, when I test this in Ubuntu, it seems there are no such issues.

Fix CJK Quotation Marks

This is the input markdown file used in the example.

English's "straight quotations" and this’s “curly quotations”.
中文的"直引号"和“弯引号”。

Code Block Syntax Highlight

Pandoc does not wrap lines in code blocks by default. It truncated the lines which are too long to fit on the page.

To solve the problem mentioned above, I followed a solution on GitHub suggested by jannick0. It involves the creation of a file that contains the LaTeX snippets below. These snippets can then be included by using the pandoc argument -H highlighting.tex. Additionally, I added a border around the code block.

highlighting.tex

% use this file via pandoc -H highlighting.tex
\usepackage{fvextra}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,breaknonspaceingroup,breakanywhere,frame=single,framesep=8pt,rulecolor=\color[HTML]{aaaaaa},commandchars=\\\{\}}

As I replied in the thread, this solution does not work for code blocks without setting a language. I use a Lua filter to set the language of these code blocks to “text”. To run the filter, save it in a file, say highlighting.lua, and invoke pandoc with --lua-filter=highlighting.lua

highlighting.lua

function CodeBlock(el)
if #el.classes == 0 then
el.classes[1] = 'text'
end
return el
end
return {{CodeBlock = CodeBlock}}

Disable Figures Floating

The last issue to address is the floating of figures in LaTeX, which moves the images to avoid large blank space in pages. While LaTeX attempts to place figures in appropriate locations, authors may refer to them as “above” or “below” in the markdown files. This can be confusing for readers who may find that the referenced chart or diagram is actually on the following page in the PDF file.

To solve the issue, simply disable floating figures. Create a file disable-floating.tex and invoke pandoc with arguments -H disable-floating.tex.

disable-floating.tex

% https://stackoverflow.com/a/58840456/667158
\usepackage{float}
\let\origfigure\figure
\let\endorigfigure\endfigure
\renewenvironment{figure}[1][2] {
\expandafter\origfigure\expandafter[H]
} {
\endorigfigure
}

Putting It All Together

See the repo doitian/pandoc-ide.

The Ultimate Guide to Customizing Obsidian Vim Mode via QuickAdd

me@iany.me (Ian Yang) — Thu, 27 Apr 2023 21:22:30 +0800

Obsidian is my go-to note-taking app because of its availability on all desktop and mobile platforms with the bonus of Vim mode. In this guide, I’ll show you how I customize the Vim mode in Obsidian to maximize my note-taking efficiency.

Setup User Launch Scripts via QuickAdd

To customize the Vim mode in Obsidian, JavaScript is the only solution. Obsidian allows running user scripts by implementing an plugin. I use an easy alternative to run a JavaScript file on launch via QuickAdd.

First, let’s create the JavaScript file in the vault. Save the skeleton below as the file vimrc.js in any folder in the vault. Keep in mind that Obsidian does not support editing JavaScript files, so use an external editor.

vimrc.js

function notice(text) {
new Notice(text);
return text;
}
module.exports = async function (context) {
const vim = window.CodeMirrorAdapter?.Vim;
if (vim === undefined) {
new Notice(`🔴error: vim mode is disabled`);
return;
}
// Add customizations here.
console.log(`🔵info: vimrc loaded`);
};

Then, install QuickAdd by browsing the community plugins in Settings and follow the instructions on the Obsidian help page Community Plugins.

Finally, include the script in a QuickAdd macro and activate the option to execute the macro upon the plugin load.

Open the tab QuickAdd in Settings.
Click the button “Manage Macros”. In the pop-up dialog, fill in the macro name “vimrc” and click the button “Add macro“ to add a new macro vimrc.
Toggle the option “Run on plugin load” on under the newly created macro.
Configure the macro vimrc. Find the script file vimrc in the “User Scripts” section and add the script as the only step in the macro.

Attention that the script runs once on launch or reload. Running “Reload app without saving” via Command Palette will reload the file after changes,

Vim Mode Customization Techniques

For the best tutorial on customizing Vim mode and what methods the vim object provides, refer to how CodeMirror establishes the Vim mode. I will only introduce the methods that I use in my own customizations.

`vim.defineEx`

The defineEx method enables users to execute a new ex command in Vim by typing : in normal mode. For instance, the ex command :w saves the file.

I introduce defineEx first because I need an ex command to run any Obsidian command so that I can use it to add key bindings later. I name this command obr, which is the abbreviation of OBsidian Run. The command requires the Obsidian command identifier as the argument, for example, :obr app:open-settings will open the Settings dialog.

vim.defineEx("obr", "", function (cm, params) {
if (params?.args?.length !== 1) {
throw new Error(notice("🔴error: obr requires exactly 1 parameter"));
}
const command = params.args[0];
context.app.commands.executeCommandById(command);
});

To find the command identifier, I add another ex command :obl to display a list of identifiers and copy the selected one. It accepts an argument to filter the result. For example, obl open will list identifiers that contain the word “open”.

vim.defineEx("obl", "", async function (cm, params) {
let commands = Object.keys(context.app.commands.commands);
for (const keyword of params?.args ?? []) {
commands = commands.filter((command) => command.includes(keyword));
}
const choice = await context.quickAddApi.suggester(commands, commands);
if (choice !== null) {
await context.quickAddApi.utility.setClipboard(choice);
new Notice(`🔵info: copied ${choice} to the clipboard`);
}
});

`vim.map`

The vim.map method takes two arguments, lhs and rhs, which can both be either a key sequence or an ex command. The meaning of the method varies depending on the arguments passed.

When both lhs and rhs are key sequence, it maps the key sequence lhs to rhs. For example, vim.map('D', 'dd') will redefine D to delete the whole line.
When both lhs and rhs are ex commands, it creates a new ex command alias. For example, vim.map(':Reload', ':obr app:reload') adds the alias :Reload to run the Obsidian command app:reload.
When lhs is a key sequence, and rhs is an ex command, it maps the key sequence to run the ex command. For example vim.map('ZZ', ':obr app:reload') allows reloading Obsidian by typing ZZ.
When lhs is an ex command, and rhs is a key sequence, executing the ex command has the same effect as typing the key sequence.

I have a bunch of mappings from key sequences to :obr, for example, the z-family to operate on folds:

vim.map("zo", ":obr editor:toggle-fold");
vim.map("zc", ":obr editor:toggle-fold");
vim.map("za", ":obr editor:toggle-fold");
vim.map("zR", ":obr editor:unfold-all");
vim.map("zM", ":obr editor:fold-all");

To use the space key as a key mapping prefix, it must first be unmapped.

vim.unmap("<Space>");
vim.map("<Space><Space>", ":obr switcher:open");
vim.map("<Space>n", ":nohl");

`vim.defineAction` and `vim.defineOperator`

We can use both action and operator in vim.mapCommand. The difference is that an operator performs upon text objects. See how CodeMirror defines the built-in actions and operators.

I have an action swapLine to move lines around. It’s not perfect, since undo will reverse one step only.

vim.defineAction("swapLine", function(_cm, { repeat, down }) {
const command = down ? "editor:swap-line-down" : "editor:swap-line-up";
for (let i = 0; i < repeat; i++) {
context.app.commands.executeCommandById(command);
}
});
// undo after 5]e will only swap one line up.
vim.mapCommand("]e", "action", "swapLine", { down: true });
vim.mapCommand("[e", "action", "swapLine", { down: false });

The example for vim.defineOperator is titleCase, which formats the text in the APA Title Case Capitalization. For instance, gzap formats the current paragraph in the title case.

function titleCase(str, options) {
// See https://github.com/words/ap-style-title-case/blob/master/index.js how to format str to apa title case
}
// Following helper funnctions are borrowed from https://codemirror.net/5/keymap/vim.js
function cursorIsBefore(cur1, cur2) {
if (cur1.line < cur2.line) {
return true;
}
if (cur1.line == cur2.line && cur1.ch < cur2.ch) {
return true;
}
return false;
}
function cursorMin(cur1, cur2) {
return cursorIsBefore(cur1, cur2) ? cur1 : cur2;
}
function findFirstNonWhiteSpaceCharacter(text) {
if (!text) {
return 0;
}
var firstNonWS = text.search(/\S/);
return firstNonWS == -1 ? text.length : firstNonWS;
}
vim.defineOperator("titleCase", function(cm, args, ranges, oldAnchor, newHead) {
const selections = cm.getSelections();
const newSelections = selections.map((s) =>
titleCase(s, { keepSpaces: true })
);
cm.replaceSelections(newSelections);
if (args.shouldMoveCursor) {
return newHead;
} else if (
!cm.state.vim.visualMode &&
args.linewise &&
ranges[0].anchor.line + 1 == ranges[0].head.line
) {
return {
line: oldAnchor.line,
ch: findFirstNonWhiteSpaceCharacter(cm.getLine(oldAnchor.line)),
};
} else if (args.linewise) {
return oldAnchor;
} else {
return cursorMin(ranges[0].anchor, ranges[0].head);
}
return newHead;
});
vim.mapCommand("gz", "operator", "titleCase");

Practice Autofocus Method in Todoist

me@iany.me (Ian Yang) — Mon, 03 Oct 2022 19:26:38 +0800

I read the article Autofocus: The Productivity System That Treats Your to-Do List Like a River¹ recently. I used to fill the time slots with tasks daily, but I rarely completed all the planned tasks. Even for the completed ones, I often missed the scheduled time slot. I felt stressed and guilty. So I decide to give the Autofocus Method a try.

The River Filter

I will continue using Todoist. I created a filter named River. The tasks are sorted by added date. I added the filter to the sidebar and set it as my home view for easy access.

The filter has three sections:

Overdue tasks: overdue
Tasks I am doing: today | @now💧
Tasks in River: !##⏰ Events & !overdue & !today & !@now💧 & !@someday🪨

Todoist supports filter sections by separating queries with comma (,). So here is the final filter query:

overdue, today | @now💧, !##⏰ Events & !overdue & !today & !@now💧 & !@someday🪨

Section 1: Overdue Tasks

This section allows me to re-schedule the overdue tasks.

I decided to not totally abandon the due dates. However, I use them with great moderation. I set a due date if I must complete the task on that date, and before the day comes, I can forget the task.

I add such tasks to the project ⏰ Events. They will appear in the River filter when they are due or overdue.

Section 2: Tasks I Am Doing

This section lists tasks that I am doing now.

There are two kinds of such tasks.

The first is the scheduled tasks that are due today.

The second is the selected tasks from the river. I add the tag @now💧 to the task if I feel like doing it.

Section 3: Tasks in River

This section contains the tasks in the river. It excludes tasks from the project ⏰ Events, and the dismissed tasks. I tag dismissed tasks with @someday🪨 .

The Workflow

I add new tasks to the inbox without triaging the projects, tags, due dates, and priorities. Since the filter

When I have time to do something, I open the River filter and scan the tasks from top to bottom without scrolling down.

First, I re-schedule the overdue tasks.

Then, I do a quick scan on the second section—the tasks that I planned before. If I feel like doing a task in the list, I start working on it.

If I failed to find a task to work on in the previous step, I continue the scan to the last section—the tasks in the river. I add tag @now💧 to pop the task to the top of the list.

If there are no items stands out for me, I have three choices to remove tasks from the first screen:

Defer the scheduled tasks into future.
Remove the tag @now💧 from the task.
Dismiss a task by adding the tag @someday🪨.

The Autofocus Method suggests to cross the item off the list and re-enter it at the end of the list if I haven’t finished it yet. In Todoist, I duplicate the task and cross the original item off.

Here is my setup to practice the Autofocus Method in Todoist. I’m still experimenting to see whether it can improve my productivity.

References

McKay, B., & McKay, K. (2022, September 20). Autofocus: The Productivity System That Treats Your To-Do List Like a River. The Art of Manliness. https://www.artofmanliness.com/character/behavior/autofocus-the-productivity-system-that-treats-your-to-do-list-like-a-river/

Set the Minimum Width of the Active Pane in Obsidian

me@iany.me (Ian Yang) — Fri, 23 Sep 2022 16:44:51 +0800

Updates

I have created an plugin for this feature.

A simple CSS rule sets the minimum width of the active pane in Obsidian.

min-width.css

.mod-root .mod-active {
min-width: min(88%, 40rem);
}

It sets the minimum width to either 40 columns or 88% of the whole editing area, depending on which is smaller. Obsidian will auto resize the active pane to ensure it is wider enough and shrink other panes accordingly.

The snippet does not work in horizontal splits where panes stack vertically. See the chapter JavaScript Helper below how to work around it.

How to Add CSS Snippets in Obsidian

Save the CSS snippet as file .obsidian/snippets/min-width.css in the vault. Create the folder .obsidian/snippets if it does not exist.

Now the file should appear in the Appearance settings page. Toggle the switcher to enable the CSS snippet in the file.

Enable CSS Snippet in Obsidian

JavaScript Helper

CSS is useless when it can not select the target elements. To make the snippet work in horizontal splits, the CSS rule has to select the .mod-horizontal node when it has a .mod-active child. However, the pseudo-class selector :has()¹ is not available in Obsidian yet.

JavaScript can help to add classes and attributes to HTML elements.

I also want to make some panes wider, such as Excalibrain². The JavaScript code can also set the view type to the proper elements. The view type of the Excalibrain pane is excalidraw.

First, update the CSS snippet to make Excalibrain panes wider. Indeed, it makes all Excalidraw panes wider.

min-width.css

.mod-root .mod-active {
min-width: min(88%, 40rem);
}
.mod-root .mod-active[data-type="excalidraw"] {
min-width: min(88%, 60rem);
}

The last, let Obsidian run some code when the active pane has changed. I use QuickAdd³ to manage the scripts. Save the following code snippet as min-width.js in the vault.

min-width.js

const DATA_TYPE = "data-type";
function setOrRemoveDataType(el, dataType) {
if (dataType !== undefined) {
el.setAttribute(DATA_TYPE, dataType);
} else {
el.removeAttribute(DATA_TYPE);
}
}
module.exports = async function ({ app }) {
app.workspace.on("active-leaf-change", (leaf) => {
// clear .mod-active on .mod-horizontal
for (const el of app.workspace.containerEl.getElementsByClassName(
"mod-active mod-horizontal"
)) {
el.classList.remove("mod-active");
}
// bubble up data-type
const dataType = leaf.containerEl
.getElementsByClassName("workspace-leaf-content")[0]
?.getAttribute(DATA_TYPE);
setOrRemoveDataType(leaf.containerEl, dataType);
// add .mod-active and data-type to current horizontal split container
const parentNode = leaf.containerEl.parentNode;
if (parentNode.classList.contains("mod-horizontal")) {
parentNode.classList.add("mod-active");
setOrRemoveDataType(parentNode, dataType);
}
});
};

Then run it when Obsidian starts by following these steps:

Click the button “Manage Macros” in the QuickAdd settings.
Add a new macro and add the user script “min-width” to the macro.
Save the macro and check the option “Run on plugin load”.

Run JavaScript Code on Start With QuickAdd

That’s it. Restart Obsidian and the code should be effective. See how it works in the screen recording below.

Set the Minimum Width of the Active Pane in Obsidian

There are two extra plugins used in the video, Snippet Commands⁴ and Cycle through Panes.⁵

Similar Work

This work is inspired by the Vim option winwidth, one of my favorite feature of Vim.

The awesome plugin Sliding Panes⁶ provides the similar feature for Obsidian. However, it has three problems that I cannot stand.

The first, when the option “Leaf Width on Desktop/Mobile” is wider than the whole editing area, I have to scroll horizontally to see the current active pane. Although the plugin has separated the options for Desktop and Mobile, but different devices have different screen sizes. What’s worser, the app window can be any size on Desktop. The option must be less than the smallest screen width when Obsidian Sync is in use, which is not a good choice for wider devices.

The second, the plugin does not play well with horizontal splits.

The last, I really want to set the different minimum widths for different windows.

References

MDN. (2016, October 27). :has() - CSS: Cascading Style Sheets. MDN. https://developer.mozilla.org/en-US/docs/Web/CSS/:has
zsviczian. (2022, May). Excalibrain: A Graph View to Navigate Your Obsidian Vault. GitHub. https://github.com/zsviczian/excalibrain
chhoumann. (2021, June). QuickAdd for Obsidian. GitHub. https://github.com/chhoumann/quickadd
deathau. (2021, October). Snippet Commands Obsidian Plugin. GitHub. https://github.com/deathau/snippet-commands-obsidian
phibr0. (2020, November). Cycle Through Panes Obsidian Plugin. GitHub. https://github.com/phibr0/cycle-through-panes
deathau. (2020, October). Sliding Panes (Andy Matuschak Mode) Obsidian Plugin. GitHub. https://github.com/deathau/sliding-panes-obsidian