Octa

Serving every article as an RFC-style plain text document

Thu, 09 Jul 2026 00:00:00 GMT

Every article on this site is now also served as an RFC-style plain text document at /doc/:slug.txt, alongside the existing HTML and raw Markdown (/doc/:slug.md) versions.

$ curl -s https://octa.page/doc/timezone-propagation-flow.txt | head -6
Octa Engineering Notes                                   Christian Elías
Request for Comments: OCTA-20                                  octa.page
Category: Informational                                        June 2026


     Timezone Propagation: How IANA Changes Reach Your Application

This site already hosts two articles about IPoAC and a real Internet Draft submitted to the IETF, so the format is on brand rather than a random gimmick.

Format

Header: classic two-column RFC header. The RFC number is the article's chronological position across the whole notebook — the first published entry is OCTA-1. This also keeps the header inside 72 columns, which long slugs would not.
Abstract: the frontmatter description, verbatim.
Status of This Memo: fixed IETF boilerplate, linking the canonical HTML version and the .md source.
Body: 72-column prose with 3-space indent, 1. / 1.1. numbered sections from H2/H3, o bullets, code blocks verbatim.
References: external links in the prose become label [n] markers, with URLs accumulated into a numbered References section at the end.
Footer: Author — Informational — [Page 1].

Implementation

One static endpoint, src/pages/doc/[slug].txt.ts, ~170 lines, no new dependencies. Instead of using marked's HTML renderer (already a dependency for the RSS feed), the endpoint walks marked.lexer() tokens directly and emits text: headings pick up section numbers, inline links mutate a shared refs array, and a 5-line word-wrapper handles the 72-column constraint. getStaticPaths collects all entries across collections and sorts by date to assign the OCTA number.

HTML article pages advertise both alternates:

<link rel="alternate" type="text/markdown" href=".../doc/slug.md">
<link rel="alternate" type="text/plain" title="RFC-style plain text" href=".../doc/slug.txt">

Deliberately skipped: tables and raw HTML pass through verbatim, and real RFC pagination (58-line pages, form feeds, per-page [Page N] footers) is deferred until the joke proves it deserves it.

Leap Seconds After 2035: What Was Actually Decided, and the Proposals on the Table

Wed, 08 Jul 2026 00:00:00 GMT

In November 2022, the 27th General Conference on Weights and Measures (CGPM, Resolution 4) decided that the maximum allowed value of the difference UT1−UTC will be increased by or before 2035. Read that carefully: it does not abolish leap seconds, and it does not break the connection between UTC and UT1. It raises a tolerance. The practical effect is that leap second insertions cease — but the resolution's second half is just as important: the CIPM is tasked with proposing a new maximum value that ensures UTC remains usable for at least a century, for review at the 28th CGPM in 2026. The replacement mechanism is deliberately left as future work.

A detail that gives the decision texture: the 2035 date was a compromise. Russia pushed to extend it to 2040 because GLONASS, unlike GPS, incorporates leap seconds into its signal structure — retiring them means reengineering the constellation's timekeeping.

Why leap seconds exist

UTC counts SI seconds from atomic clocks. UT1 is the Earth's rotation, expressed as a timescale. UTC was not designed to track the planet as a primary goal — it combines atomic time with occasional one-second adjustments to remain practically close to UT1. The Earth is not a stable oscillator: tidal friction with the Moon, earthquakes, solar activity, and core–mantle dynamics all perturb the rotation. Historically, the divergence has required roughly one leap second every 1–3 years, though the rotation is irregular and cannot be predicted over long horizons.

The IERS (International Earth Rotation and Reference Systems Service, whose Earth Orientation Center operates at the Paris Observatory) announces an insertion whenever |UT1−UTC| approaches the tolerated bound (0.9 s) — with less than six months of notice, via Bulletin C. Since 1972 there have been 27 leap seconds, all positive, leaving UTC 37 seconds behind TAI.

Why they cause more problems than they solve

A positive leap second produces the timestamp 23:59:60, which POSIX time cannot represent. Every system handles it differently, because there is no standard handling:

Strategy	Who	Behavior
Step	Default NTP / kernel	Repeat or freeze a second at midnight UTC
Smear	Google, AWS, others	Stretch the second across a window — but each operator picks its own window and curve
Ignore	Unsynced systems	Drift until the next NTP correction

Smearing is an operational convention, not a standards-defined behavior: Google's 24-hour linear smear and other operators' variants are mutually incompatible by design. Two NTP-synchronized systems using different strategies disagree with each other for the duration of the event.

The insertion lands first on the Stratum 1 servers of the NTP pool — they receive the leap indicator from the reference clocks (atomic/GNSS) and propagate it downward. The blast radius is asymmetric: critical infrastructure (banking, trading, telecom, distributed systems with strict ordering requirements) is where leap seconds hurt. The application layer of everyday non-critical products mostly never notices — it simply trusts whatever time NTP delivers.

And then there is the negative leap second. It has never been applied. The Earth's rotation has been accelerating in recent years, making it plausible for the first time — and it would force every system to skip from 23:59:58 to 00:00:00. It would exercise code paths that have never run in production at global scale, which makes its operational risk genuinely difficult to quantify: some software would fail, some is prepared, much of it has never been tested against the case at all.

The proposals on the table

No formal standard exists yet for what happens after 2035, and standardization work is unlikely to conclude before the late 2020s. But the design space is not empty:

The leap minute. Let the drift accumulate until it amounts to a full minute — a block spanning decades. Predictable, plannable, and it defers the operational event to a future generation. Its critics note it concentrates all the risk of today's leap second into one larger, rarer, even-less-rehearsed event.
Algorithmic rate adjustments (Levine, NIST, 2024). Judah Levine's paper "A Proposal to Change the Leap-Second Adjustments to UTC" proposes replacing discrete jumps with an algorithmic rate-adjustment (steering) method — corrections distributed over time instead of discontinuities. In one of its formulations, adjustments on the order of −13 s per decade starting in 2035.
The BIPM Task Group on Continuous UTC has been working on exactly this family of solutions, feeding into the CIPM proposal due for the 2026 CGPM.

What follows is a variant in that same family — periodic, fixed-date, rate-based — contributed as a point in the design space, not as a novelty. Its distinguishing choices are the block length, the notice period, and where in the stack the adjustment lives.

A variant: scheduled 4-year correction blocks

The current mechanism mixes two problems that deserve separate answers: how much to correct (a geophysical measurement — the IERS's job) and how to apply the correction (an engineering standard — currently left to each operator's improvisation). The variant separates them.

1. Accumulate corrections in fixed 4-year blocks, aligned to leap years. At the close of each block, the IERS publishes the net correction accumulated during it — positive or negative — and the IANA tz database and downstream standards carry the schedule.

2. Two years of notice, always. The correction published at the close of a block takes effect two years later and is applied across the following block:

Announced	Covers drift from	Applied during
2036-01-01	2032–2036	2038–2041
2040-01-01	2036–2040	2042–2045
2044-01-01	2040–2044	2046–2049

Each application window starts where the previous one ends — announcements and applications interleave, but two corrections are never active at once.

Why 4 years and not 2, 5, or 8: it aligns with the civil leap-year cycle (a familiar planning rhythm), it typically accumulates only 2–3 seconds per block (keeping the correction rate negligible and the UT1 bound single-digit), and it halves the number of standardization events versus a 2-year cycle without stretching the bound the way an 8-year cycle would.

3. One mandatory application method: proportional tick-rate adjustment. During the application block, the UTC second is lengthened or shortened by the proportional fraction of the total correction. Spreading 3 seconds across 4 years is a rate offset of ~2.4×10⁻⁸ — orders of magnitude below the crystal drift NTP already disciplines on every machine, every day.

4. The adjustment lives at the top of the stack, not the bottom. This is the architectural decision that makes it a standard rather than a smear: the rate adjustment is part of the disseminated UTC timescale itself. The reference laboratories and GNSS systems broadcast already-adjusted time; NTP Stratum 1, PTP grandmasters, kernels, and applications receive plain UTC and implement nothing. Today's smearing is the exact inverse — applied downstream, per operator, each with its own window and curve.

That is also the answer to the obvious objection, "this is just a permanent leap smear":

	Today's smear	This variant
Who decides the curve	Each operator	The standard
Where it's applied	Downstream (NTP service, kernel)	At the timescale source
Window	Hours around the event, operator-specific	The full block, fixed by schedule
Interoperability	Two synced systems can disagree	One timescale, by construction

The bound, shown

The claim is that |UTC−UT1| stays within roughly ±10 seconds. It should not have to be taken on faith:

assume a sustained high drift rate ≈ 0.7 s/year
(historically, one leap second every 1–3 years ⇒ 0.33–1.0 s/year)

accumulation window:   4 y × 0.7 ≈ 2.8 s
notice period:         2 y × 0.7 ≈ 1.4 s
during application:    4 y × 0.7 ≈ 2.8 s   (new drift, corrected next cycle)

worst-case |UTC − UT1| ≈ 2.8 + 1.4 + 2.8 ≈ 7 s

Roughly ±7 s in the sustained worst case, ~±10 s with margin for the rotation doing something the model didn't expect. Compare the trade-offs:

System	Max \|UTC−UT1\|	Notice	Correction
Today	0.9 s	< 6 months	discrete leap second
Leap minute	~60 s	decades	discrete leap minute
Levine-style rate adjustment	model-dependent	fixed dates	periodic rate steering
4-year blocks (this variant)	~10 s	2 years, always	continuous rate adjustment

The trade-off, explicitly

The price is the bound: ±10 s instead of today's ±0.9 s. What it buys is predictability, a permanent 2-year planning horizon, and one correction mechanism instead of N incompatible ones. And it makes explicit the interpretation the 2022 resolution already gestures at — this part is opinion, not fact: UTC stops chasing the Earth's rotation, because tracking the planet is UT1's job. UTC becomes what it has been in practice all along — the machines' working timescale.

The astronomers will keep debating the long-term relationship between the two scales. Every proposal above lets that debate happen on a multi-year horizon, without a six-month fuse attached to every second.

Timezone Propagation: How IANA Changes Reach Your Application

Fri, 12 Jun 2026 00:00:00 GMT

When the IANA timezone database makes a decision about how time works in a region, that change doesn't instantly reach your JavaScript Date object or your Python datetime library. Instead, it travels through a complex ecosystem of standards bodies, operating systems, language runtimes, and third-party libraries—each with their own release cycles, prioritization strategies, and sometimes their own interpretations of the rules.

This journey can take weeks, months, or in extreme cases, never happen at all. Understanding that pipeline is essential for anyone building systems that rely on reliable timezone handling.

The Propagation Pipeline

graph TD
    tz["IANA tz Database<br/>(tzdb)"]
    
    cldr["CLDR/ICU<br/>(Unicode Consortium)"]
    os["Operating Systems<br/>(glibc, Windows)"]
    thirdparty["Third-Party Libs<br/>(Moment, Day.js, Luxon)"]
    
    bundled["Language Runtimes<br/>(Node.js, Java, Go,<br/>bundled CLDR/ICU)"]
    
    apps["User Applications"]
    
    tz -->|"CLDR adoption<br/>(1-2 months)"| cldr
    tz -->|"OS updates<br/>(varies)"| os
    tz -->|"Direct adoption"| thirdparty
    
    cldr -->|"Runtime releases<br/>(weeks-months)"| bundled
    os -->|"System updates<br/>(varies)"| apps
    bundled -->|"Direct dependency"| apps
    thirdparty -->|"Library updates"| apps

Timeline: From IANA Decision to User System

tz release (immediate)

IANA releases a new rule via the tz mailing list and updates data.iana.org/time-zones/tzdb/
Published in the NEWS file

CLDR adoption (typically 1–2 months)

Unicode CLDR interprets the tz change and integrates it into its schema
CLDR includes not just tz rules but also metadata: display names, exemplar cities, etc.
Not always a 1:1 mapping (CLDR sometimes applies its own interpretation)

OS updates (highly variable)

Linux distributions: 1–3 months (depends on distro policy)
macOS: aligned with CLDR releases, typically 1–2 months
Windows: can lag significantly; Microsoft maintains its own TZDB mirror but updates are not automatic
Android: depends on the OS version and manufacturer updates

Language runtime releases (weeks to months)

Runtimes with bundled CLDR (Node.js, Java, Go) release updates on their own schedule
Some runtimes are more aggressive (quick releases); others batch changes

Third-party libraries (unpredictable)

Some libraries depend on CLDR and are updated automatically
Others maintain their own timezone data
Maintainer activity is critical—abandoned libraries can lag for years

Node.js: The Duality Problem

Node.js presents a unique and often overlooked situation: it has two simultaneous sources of timezone information.

Source 1: Native `Date` (from the Operating System)

The JavaScript Date object relies on the system's tzdata:

const now = new Date();
now.toString(); 
// Uses the OS tzdata to determine local timezone offset

When you call new Date() and ask for the local representation, Node.js queries the operating system's timezone database (via libc on Unix-like systems, the Windows Registry on Windows). If your OS hasn't updated its tzdata yet, your Date object won't reflect the latest rules either.

Source 2: `Intl.DateTimeFormat` (from Bundled ICU)

The Intl API is built on ICU (International Components for Unicode), which is bundled into the Node.js binary:

const formatter = new Intl.DateTimeFormat('ca-AD', {
  timeZone: 'Europe/Andorra',
});
// Uses bundled ICU data, which can differ from OS data

This formatter uses the CLDR/ICU data that was compiled into your Node.js binary at build time. If your Node.js version was built 6 months ago and tz made a change last week, the Intl API will use outdated data until you upgrade Node.

The Mismatch

The same JavaScript environment can give you two different answers for the same timezone:

// Example: hypothetical timezone rule change
const d = new Date('2026-06-15T12:00:00Z');

// Using Date (OS-based)
console.log(d.toLocaleString('en-US', { timeZone: 'America/New_York' }));
// May use outdated rules if OS hasn't updated

// Using explicit Intl (ICU-based)
const formatter = new Intl.DateTimeFormat('en-US', { 
  timeZone: 'America/New_York' 
});
console.log(formatter.format(d));
// May use different rules if Node.js binary is newer than OS

This split is a well-known pain point in JavaScript environments. Different environments handle it differently—some prefer OS consistency, others prefer Intl consistency.

Case Study: British Columbia's Permanent Daylight Time

British Columbia (Canada) announced in late 2023 that it would permanently observe daylight time—effectively staying on "summer time" year-round. This created a problem that exposed the limits of CLDR's design.

CLDR's mental model assumes regions transition between a standard time and a daylight time. Every year, the clock springs forward and falls back. But British Columbia doesn't follow this pattern anymore. It stays on daylight time constantly.

When a region stops participating in the normal DST cycle entirely, CLDR has no natural way to represent it. The schema assumes transitions happen periodically (spring forward, fall back). A permanent shift breaks that assumption.

IANA's Workaround

Rather than wait for CLDR to redesign its schema, IANA's timezone maintainers invented a solution: a fictional future DST transition.

The tz database now schedules a fake DST transition far in the future. On that date, the region transitions from "summer time" to... "summer time" again. The net effect: no actual time change, but the CLDR rules engine processes it as a normal transition and produces the correct output.

From the tzdata NEWS file:

A region that wants to stay on permanent daylight time can be represented as having a DST transition that loops back to itself, effectively freezing the clock in the DST state.

This is a clever hack, but it reveals an important truth: the timezone database is constrained by the tools that consume it. IANA doesn't just define rules; it also has to work around limitations in the systems that implement those rules.

The specific discussion:

IANA tz mailing list thread on British Columbia
IANA tzdb NEWS file (search for "Canada/Vancouver" or "permanent")

Why Propagation Matters

The reality of timezone propagation creates several practical implications:

You can't rely on immediate consistency. A timezone rule change made today won't be reflected everywhere in your infrastructure for weeks or months.
Cross-system mismatches are possible. Your web server (running a freshly updated OS) might calculate time differently than the user's browser (running an older version of Node or Chrome).
Library choice matters. Moment.js might reflect changes faster than the native Date object, or vice versa, depending on when maintainers push updates.
CI/CD and testing become essential. If you care about correct timezone behavior, you can't just trust whatever system you're testing on. You need explicit tests for known edge cases and irregular transitions.

What to Do

If you're building systems that handle timezone-dependent logic:

For coordination: Always store and transmit times in UTC. Conversion to local time is a display concern, not a storage concern.
For testing: Don't assume your system's timezone data is current. Write tests that explicitly test known edge cases and transitions.
For Node.js: Be aware that Date and Intl can disagree. For critical applications, pick one and stick with it, or synchronize them explicitly.
For production: Monitor timezone-related issues in your observability stack. A timezone propagation delay is invisible until someone tries to book a flight.

Completing the IPoAC Stack: Why DoAC Had to Exist

Thu, 11 Jun 2026 00:00:00 GMT

In 2001, the Bergen Linux User Group sent actual ping packets over actual pigeons across actual Bergen, Norway. Round-trip time: 3,000 seconds. Packet loss: 55%. The experiment was a real implementation of RFC 1149, a document the IETF published in 1990 as an April Fools joke. The joke had become operational.

That experiment exposed a gap that nobody had bothered to document: the IPoAC protocol stack was incomplete. You could transmit IP datagrams over pigeons. You could not resolve a hostname.

I noticed this during a university networking course, years after the Bergen experiment. RFC 1149 came up as comic relief. I mentioned, in a remote session mid-pandemic, that there was an obvious hole in the stack. Nobody in the room understood what I was talking about. The comment went nowhere.

It came back to me earlier this year while reading the transcript of Root KSK Ceremony 61, held in April 2026. The ceremony is the process by which ICANN physically generates and signs the DNSSEC root key, a procedure involving Hardware Security Modules, auditors, Faraday cages, and multiple safety deposit boxes. It is, in its own way, as absurd as putting a DNS query on a pigeon. The connection clicked. I went back to the April Fools RFC family and wrote draft-cruzgonzalez-ipoac-dns-00.

What the IPoAC stack looked like before DoAC

The family consists of three RFCs, each technically rigorous, each published on April 1st:

RFC 1149 (1990): IP datagrams on avian carriers. Defines the physical medium (pigeon), the maximum segment size (256 milligrams), and the basic forwarding model. No higher-layer services.
RFC 2549 (1999): IPoAC with Quality of Service. Extends RFC 1149 with QoS markings. Introduces the concept of Differentiated Services on a per-feather basis.
RFC 6214 (2011): Adaptation for IPv6. Addresses the expanded address space. Notes that IPv6 addresses are too long to fit comfortably on a standard leg band.

All three assume the destination address is already known. None of them address how a host on an avian-carrier network discovers that address. For twenty years, the implicit answer was: hardcode it.

That is not a protocol. That is a workaround.

The gap

In conventional networking, DNS is so fundamental that it's easy to forget it's a separate layer. IP gives you reachability. DNS gives you names. You need both for a functional network. Remove DNS from any modern stack and you're back to editing /etc/hosts and distributing IP addresses out-of-band.

The IPoAC stack had exactly this problem. A host that wanted to reach loft.example.com had to already know the IP address of loft.example.com. If that address changed (pigeon renumbering events are, apparently, catastrophically disruptive), the operator had to manually update every message attached to every outbound Carrier. At scale, this is unmanageable. At any scale, it's inelegant.

DoAC closes this. It is to IPoAC what DNS is to IP: the naming layer the transport layer was always missing.

Design decisions

The AA resource record

DNS already has a record type for geographic location: LOC (RFC 1876). LOC encodes latitude, longitude, altitude, and precision. It was designed for documentation and geolocation, not for Carrier navigation.

DoAC needed something different. The AA (Avian Address) record encodes what a Carrier actually needs to find a Loft: coordinates for navigation, a preferred approach heading (to minimize headwind exposure and avoid raptor nesting sites), and a preferred cruising altitude band. LOC's precision encoding is irrelevant here; sub-meter accuracy matters less than knowing which side of the building to approach from.

The wire format is 12 bytes: two signed 32-bit integers for latitude and longitude in microdegrees (network byte order), a 16-bit unsigned heading in degrees magnetic north, an 8-bit altitude band, and 8 reserved bits.

                 1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           LATITUDE                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           LONGITUDE                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             HEADING           |   ALT-BAND    |   (reserved)  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Microdegrees give sub-meter precision globally. The Bergen Loft, for reference:

example.com.  86400  IN  AA  60.391263 5.322054 270 1

270 degrees: westerly approach. Altitude band 1: medium, 100–300m AGL. Bergen is on the coast. This is not a random example.

The bootstrapping problem

Every name resolution system eventually hits a version of the same problem: to use the naming service, you must first locate the naming service. DNS resolves this with hardcoded root hints. DHCP resolves it with link-local broadcast. DoH (RFC 8484) resolves it by requiring the resolver's IP address to be configured out-of-band.

In IPoAC, the out-of-band channel is physical. You go to the Loft, you get a Carrier trained to its address. DoAC names this procedure (Manual Resolver Bootstrap, MRB) and formalizes the ongoing solution: the Pigeon of Last Resort (PoLR), a pre-trained Carrier with a hardcoded destination, maintained at every host as the entry point to the recursive resolution infrastructure.

The PoLR is operationally equivalent to the configured recursive resolver in /etc/resolv.conf, with the difference that misconfiguration results in a lost bird rather than a timeout.

Hosts SHOULD maintain at least two PoLR Carriers. A single PoLR is a single point of failure, which remains, as always, inadvisable.

Retransmission

RFC 1035 recommends retransmitting after approximately 5 seconds. This value assumes the transport layer operates in milliseconds. IPoAC does not.

DoAC sets the minimum retransmission interval at 72 hours, with a seasonal jitter factor derived from average wind speed at the Carrier's latitude of origin. The retransmission limit is 1: dispatching multiple Carriers for the same query risks out-of-order delivery if one selects a more efficient flight path, producing query ID collisions that are difficult to debug and impossible to explain to management.

After 21 days without a response, the query is declared lost.

DNSSEC

DNSSEC requires cryptographic signing of DNS records. The signing key must reach the signing Loft. In DoAC, that means physical transport by Trusted Courier Pigeon (TCP), an acronym collision the document notes and considers appropriate.

Two timing problems emerge immediately.

The first is key rollover. DNSSEC rollover involves distributing new keying material before the old key expires. In DoAC, distributing keying material takes days. Rollover windows that are measured in hours in conventional deployments must be measured in weeks. Rollover MUST be scheduled outside migration season (March–May, September–November in the Northern Hemisphere) when Carriers are liable to deliver keying material to the wrong Loft.

The second is RRSIG expiry. DNSSEC signatures have validity periods. If a signature expires while the Carrier carrying the signed response is still in flight, the response will be invalid on arrival. This condition, In-Flight Expiry (IFE), is a known operational hazard with no equivalent in conventional DNS deployments. The mitigation is straightforward: set RRSIG validity periods longer than your worst-case round-trip transit time.

The interaction between IFE and migration season is, as the document notes, considered particularly hazardous.

What this is, technically

DoAC is a complete DNS transport specification for a constrained, high-latency, physically-mediated network. The constraints are real (payload size, retransmission behavior, timing assumptions) and the solutions are internally consistent. The record type is properly defined with a wire format and zone file presentation syntax. The IANA considerations request a real registry with a real policy (Standards Action for future altitude band assignments).

The humor is in the subject matter. The protocol engineering is not.

The draft is currently under consideration for publication as an Independent Submission RFC, targeting April 1, 2027, the only appropriate publication date for a document of this kind.

My First Internet Draft: DNS over Avian Carriers

Tue, 09 Jun 2026 00:00:00 GMT

I published my first Internet-Draft to the IETF Datatracker: draft-cruzgonzalez-ipoac-dns-00. It specifies DNS over Avian Carriers (DoAC) — hostname resolution for networks operating over pigeon-based transport. I've contacted the Independent Submissions Editor to target publication as RFC on April 1, 2027.

What's an Internet-Draft

An Internet-Draft (I-D) is a working document in the IETF standards process. Anyone can submit one. It expires after 6 months if not renewed. It's not an RFC — but it's the required first step to become one.

RFCs have different publication streams. Most protocol standards go through IETF Working Groups. The Independent Submissions stream is for documents outside any WG's scope, reviewed and published by the Independent Submissions Editor (ISE). That's the correct path for April Fools RFCs.

The April Fools RFC tradition

The IETF has published humor RFCs every April 1st for decades. They are technically rigorous, properly formatted, and go through the same editorial process as any other RFC. The IPoAC family is the canonical example:

RFC 1149 (1990) — IP over Avian Carriers
RFC 2549 (1999) — IPoAC with Quality of Service
RFC 6214 (2011) — Adaptation of RFC 1149 for IPv6

RFC 1149 was actually implemented in Bergen, Norway in 2001 by the Bergen Linux User Group. The example Loft in DoAC is located at Bergen's coordinates (60.391263, 5.322054). This is not a coincidence.

What DoAC specifies

DoAC closes the gap in the IPoAC protocol stack: prior work defined how to transmit IP datagrams over pigeons, but never addressed how a host on such a network resolves a hostname.

New resource record: AA (Avian Address)

                 1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           LATITUDE                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           LONGITUDE                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             HEADING           |   ALT-BAND    |   (reserved)  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

LATITUDE and LONGITUDE are signed 32-bit big-endian integers in microdegrees (degrees × 10⁶). Zone file presentation uses decimal degrees:

example.com.  86400  IN  AA  60.391263 5.322054 270 1

The Pigeon-Before-Egg Problem

To dispatch a Carrier to resolve a hostname, you first need the IP address of the resolver's Loft. If that address is in DNS, you have a circular dependency. DoAC resolves this with the Pigeon of Last Resort (PoLR): a pre-trained Carrier whose destination is hardcoded at provisioning time, analogous to a resolver of last resort. Hosts SHOULD maintain at least two.

Retransmission

RFC 1035 recommends retransmitting unanswered queries after ~5 seconds. DoAC implementations MUST NOT retransmit until 72 hours have elapsed. The retransmission limit is 1. After 21 days without a response, the query MUST be declared lost.

DNSSEC

Zone Signing Keys are physically transported by Trusted Courier Pigeon (TCP — the acronym collision is noted and considered appropriate). Key rollover MUST be scheduled outside migration season. Signatures that expire while a Carrier is in flight constitute In-Flight Expiry (IFE).

Security considerations include: Hawk-in-the-Middle (HitM) attacks, Denial of Flight (DoF), pigeon spoofing via adversarial dye application, replay attacks via taxidermied Carrier, and the Covert Feather Channel — a side channel encoded in feather arrangement that requires a licensed ornithologist to detect.

The submission process

The draft is authored in RFC XML v3 format (xml2rfc). The toolchain:

# Validate before submitting
idnits draft-cruzgonzalez-ipoac-dns-00.xml

# Submit at
# https://datatracker.ietf.org/submit/

The submission flow: upload XML → Datatracker generates TXT and HTML → confirm via email → draft is live. The only warning idnits produced was non-ASCII characters (×, −, –) used intentionally in the wire format diagrams. Zero errors, zero flaws.

After submission, I emailed rfc-ise@rfc-editor.org directly — the ISE doesn't find your draft on their own. The email referenced the Datatracker URL, noted the April Fools context, and requested an April 1, 2027 publication date.

What's next

The ISE will acknowledge, possibly assign an external reviewer, and eventually forward to IESG for conflict review (~4 weeks). If no WG objects, the RFC Editor processes it and coordinates the publication date. AUTH48 — author approval of the final text — happens in the final stretch.

The draft expires 2026-12-10. If the process extends past that, a -01 refresh is required.

Injecting git config per-process with GIT_CONFIG_KEY_n

Sun, 07 Jun 2026 00:00:00 GMT

Git refuses to operate on a repository owned by a different user than the current process:

fatal: detected dubious ownership in repository at '/var/www/html/avelor.es'
To add an exception for this directory, call:
    git config --global --add safe.directory /var/www/html/avelor.es

The standard fix is git config --global --add safe.directory <path>, which writes to ~/.gitconfig. This silently fails when the process running git has a different home directory — a systemd service running as root, for instance, has /root/.gitconfig, not the user's.

The env var approach

Since git 2.31, config can be injected per-process via environment variables without touching any file on disk:

GIT_CONFIG_COUNT=1
GIT_CONFIG_KEY_0=safe.directory
GIT_CONFIG_VALUE_0=*

This adds safe.directory = * to the config for that process only. The wildcard trusts all directories.

In Node.js, when spawning deploy subprocesses:

const env = Object.assign({}, process.env, {
  GIT_CONFIG_COUNT: '1',
  GIT_CONFIG_KEY_0: 'safe.directory',
  GIT_CONFIG_VALUE_0: '*',
}, extraEnv); // project-level env overrides last

No gitconfig writes, no sudo, no per-repo exception lists to maintain. The config lives in the process environment and disappears with it.

When this matters

Any deploy agent that runs as root (or a different user than the web server) and executes git commands against repos owned by www-data or another service account hits this. Running git config --global as your shell user does nothing for that process.

floo: a minimal deploy agent for self-hosted VPS

Sat, 06 Jun 2026 00:00:00 GMT

Every VPS deployment ends up as the same ritual: SSH in, git pull, npm install, pm2 restart. Automating it properly means either exposing SSH credentials to CI or paying for a platform that wraps a container runtime you don't need.

floo runs an HTTP agent on the server. You configure projects and their steps in a YAML file. You issue tokens — one per project, scoped, shown once, stored hashed. From your machine or a CI pipeline, you run floo myapp and the deploy logs stream back in real time via SSE.

projects:
  avelor.es:
    cwd: /var/www/html/avelor.es
    steps:
      - git fetch origin master
      - git reset --hard origin/master
      - npm ci
      - pm2 restart avelor --update-env

floo avelor.es
→ deploying avelor.es  4 steps
[1/4] git fetch origin master ✓
[2/4] git reset --hard origin/master ✓
...

Architecture decisions

Tokens hashed at rest. SHA-256, shown once at issuance. The server stores no raw token — a dump of the token file is useless to an attacker.

Per-project token scoping. A token for avelor.es returns 403 against any other project name. A compromised token can't enumerate projects or deploy anything else.

SSE for log streaming. No WebSocket, no polling. The response is a text/event-stream that stays open while steps execute. floo the client reads it and prints each line as it arrives.

systemd as the process supervisor. floo agent install writes and enables a systemd unit. No wrapper scripts, no custom daemon logic, no PID file juggling. systemctl restart floo is the ops interface.

What I ruled out

Webhook-only approaches — no streaming, no live feedback during a deploy.
Docker-based solutions — the sites running on this VPS are PHP + Node apps. A container runtime is overhead that doesn't pay for itself.
Managed platforms — Render, Railway, Fly — each has constraints on build environment or charges for what's effectively a small Node process and a git pull.

Implementation

~700 lines of Node.js across six modules. The agent is a plain http.createServer. Steps run as sh -c <cmd> subprocesses with stdout/stderr piped back line by line. The client is a fetch loop over the SSE response. Config is YAML via js-yaml, tokens stored as JSON.

Release pipeline builds platform binaries via Node SEA (Single Executable Applications) and publishes to npm and a Homebrew tap on each tag.

npm install -g @avelor/floo

v0.2.1. Repo: github.com/avelor-es/floo

Bifrost: what changed when a private tunnel became a public package

Wed, 03 Jun 2026 00:00:00 GMT

The original relay was a single-user private tool: one hardcoded token, one active connection, no queue limits. Turning that into @avelor/bifrost — a package anyone can self-host — required changing every assumption that came from "only I will use this."

Named tunnels with subdomain routing

The original relay had one fixed public URL. Bifrost introduces named peers: each client registers under a name (e.g. preview, api) and incoming requests are routed by Host subdomain first, path prefix second.

function nameFromHost(host) {
  const m = (host || '').match(/^([a-z0-9][a-z0-9-]*)\.tunnel\./i);
  return m ? m[1].toLowerCase() : null;
}

preview.tunnel.example.com resolves to the preview peer. If no subdomain matches, the relay falls back to path-based routing (/_bifrost/{name}) and then to default. Multiple clients can be connected simultaneously — the relay holds them in a Map<name, ws>.

The trade-off from the original design stands: subdomain routing requires a wildcard cert and a wildcard ServerAlias in Apache/nginx. The relay doesn't manage those — it reads the Host header and trusts the upstream proxy to handle TLS.

Token scoping

The original auth was a string equality check against a single env var. Bifrost stores tokens as SHA-256 hashes (raw value shown once at issue time, never persisted) with a scope field.

function validate(raw, name) {
  const hash  = hashToken(raw);
  const entry = readTokens().find(t => t.hash === hash);
  if (!entry) return null;
  if (entry.scope === '*') return entry;
  return entry.scope === (name || 'default').toLowerCase() ? entry : null;
}

A token scoped to preview cannot connect as api. A token scoped to * connects to any name. This lets you issue short-lived per-subdomain tokens for CI environments without exposing a global credential.

Revocation is a list filter: tokens.filter(t => t.id !== id). No database, no key rotation ceremony — just a JSON file and a 4-byte opaque ID for human reference.

Backpressure

The original relay had no queue limit and no body size cap. Both are problems the moment multiple users share the same relay.

const MAX_QUEUE = 256;
const MAX_BODY  = 10 * 1024 * 1024; // 10 MB

if (queue.size >= MAX_QUEUE) {
  errorResponse(res, 429, req);
  return;
}

Body limit fires early, during streaming — req.destroy() is called before the full body arrives, so a 100 MB upload doesn't exhaust memory before the 413 is sent.

The queue limit of 256 is conservative. Each entry holds a live ServerResponse reference and a timer. Unbounded queue growth under a slow or disconnected peer is the obvious failure mode.

Dead connection detection

WebSocket close events aren't reliable over misbehaving networks. The relay pings every active peer every 30 seconds and terminates any that don't respond:

setInterval(() => {
  for (const [name, ws] of peers) {
    if (ws._pingPending) {
      ws.terminate(); // forceful, no close handshake
      continue;
    }
    ws._pingPending = true;
    ws.ping();
  }
}, 30_000).unref();

ws.on('pong', () => { ws._pingPending = false; });

_pingPending is set before the ping and cleared on pong. A missed pong means the next interval fires with the flag still set. Two intervals minimum before termination — 30s for the first ping, up to 60s total for a dead connection to be evicted.

Client resilience: 1008 means stop

The client reconnects on any unexpected close — except code 1008 (policy violation). That code means the server actively rejected the connection: bad token, name already taken, invalid path. Retrying is pointless.

ws.on('close', (code, reason) => {
  if (intentionalClose) return;
  if (code === 1008) {
    process.stderr.write(R + 'rejected: ' + Z + (reason?.toString() || 'unauthorized') + '\n');
    cleanup(1);
    return;
  }
  scheduleReconnect();
});

Network errors get exponential backoff: Math.min(1000 * 2^retries, 30_000). Retry counter resets on a successful open event, so a stable reconnection doesn't carry penalty from earlier failures.

Queue drain on disconnect

When a peer disconnects, the relay doesn't wait for the 30-second timeouts on pending requests — it drains the queue immediately with 502:

ws.on('close', () => {
  peers.delete(name);
  for (const [id, entry] of queue) {
    if (entry.peerName !== name) continue;
    clearTimeout(entry.timer);
    errorResponse(entry.res, 502, entry.req);
    queue.delete(id);
  }
});

The peerName stored with each queue entry is the link back. Without it, a disconnect would leave up to 256 requests hanging for 30 seconds each — a noticeable freeze for any webhook handler watching for a response.

Building @avelor/vhost: From Repeated Pain to Open Source Tool

Tue, 02 Jun 2026 00:00:00 GMT

Every new domain starts the same way. Copy a VirtualHost template, replace three strings, uncomment the SSL block after Certbot runs, verify the HTTP→HTTPS redirect is there. Repeat for aliases. The template is maybe 40 lines. After the tenth domain, you have ten variants, some with subtle differences: a missing AllowOverride All, a wrong log path, an alias that didn't make it to the RewriteCond.

The other half of the problem is invisible. Apache's default behavior when a VirtualHost doesn't match is to fall through to the first .conf alphabetically. On a server with ten domains, an unrecognized request — a crawler, a scanner, a misconfigured DNS — silently gets served content from whichever site happens to sort first. No error page. No indication anything went wrong.

The fix for both problems is the same: stop treating VirtualHost configs as files you edit and start treating them as artifacts you generate.

The tool

@avelor/vhost is a Node.js CLI that takes a sites.yml and produces Apache configs.

sites:
  avelor.com:
    aliases: [www.avelor.com]
    mode: static
    root: /home/avelor/avelor

  api.avelor.es:
    mode: proxy
    port: 3000

sudo vhost apply generates the .conf files, runs a2ensite, runs apache2ctl configtest, and reloads Apache. Every generated file has # Generated by @avelor/vhost on the first line. That comment is load-bearing — vhost check reads it to distinguish generated configs from hand-written ones.

Gradual migration

The tool was designed around an existing server with hand-written configs. Requiring a full migration upfront is a non-starter: ten domains, some with complex rewrite rules, some with custom headers. One bad config and the whole server is down.

The managed marker solves this without ceremony. Every .conf that predates vhost apply shows up in vhost check as manual config — functional, not yet under source-of-truth control:

  ✓  avelor.com        managed   /home/avelor/avelor
  !  old-client.com    manual config   not in sites.yml
  !  staging.app.com   manual config   → run: vhost apply staging.app.com to migrate

Migration is one site at a time. Add the domain to sites.yml, run vhost apply <domain>, the generated config overwrites the manual one. When vhost check shows no manual config entries, the migration is complete.

Error pages via content negotiation

vhost apply installs built-in error pages for the full 4xx/5xx range. The design constraint: a server that hosts both web apps and APIs needs error responses in the right format depending on who's asking.

The implementation uses Apache's MultiViews content negotiation with static files. Each error code has three variants:

/var/www/vhost-errors/
  404.html   404.json   404.xml
  500.html   500.json   500.xml
  ...

The ErrorDocument directive points to the path without extension:

ErrorDocument 404 /vhost-errors/404

Apache picks .html, .json, or .xml based on the request's Accept header. No PHP, no CGI, no runtime. The JSON response is {"code": 404, "message": "Page not found."}. The HTML page shows the status code large, a generic message, and Avelor · vhost fixed at the bottom.

Why open source

Avelor already publishes independent developer tools. The pattern is consistent: if the problem is universal and the solution has no coupling to private infrastructure, it goes public.

The Apache VirtualHost problem isn't specific to Avelor. Any developer running multi-domain Apache on a VPS encounters it. The tool is a YAML-to-Apache-config transformer with a CLI and nothing else. Keeping it private would be the stranger choice.

Why I Built mesh: Local Dev Proxy with Named Services and Failure Injection

Mon, 01 Jun 2026 00:00:00 GMT

Every fullstack project starts the same way: three terminals open, one running on :3000, one on :4000, one on :5000. You mix them up. You hardcode localhost:4000 somewhere and forget to change it before pushing. You test happy paths because injecting a 503 means either touching the API code or reaching for a mock library.

mesh solves both problems in a single YAML file.

services:
  app: 3000
  api: 4000

rules:
  api:
    - path: /payments
      status: 503
      rate: 30
    - path: /slow-endpoint
      delay: 2000
      rate: 100

sudo mesh route writes /etc/hosts, starts an HTTP/HTTPS proxy on 127.0.0.1, and cleans up on exit. Services are available at app.test and api.test. If mkcert is installed, HTTPS is automatic.

The failure injection part

The rules block is the reason this exists. It intercepts matching requests at the proxy layer — no mocks, no code changes, no test harness. You can fail 30% of /payments calls with a 503, delay /slow-endpoint by 2 seconds, or combine both. The rate is per-request, resolved at runtime via Math.random().

This lets you test how your frontend handles partial outages without touching the backend at all.

What I ruled out

hotel — closest prior art, abandoned since 2023, no HTTPS, no failure injection.
Caddy / Traefik — production-grade reverse proxies. Config overhead is real. Not what you reach for in a dev project.
Mocking the fetch layer — changes test behavior vs. real behavior. The proxy intercepts at the network level, so the client code runs exactly as it would in production.

Implementation

~400 lines of Node.js, no framework. The proxy is http-proxy. TLS comes from mkcert. Config is plain YAML parsed with js-yaml. Hot-reload watches the config file and mutates the in-memory service/rule maps in place so existing connections survive.

npm install -g @avelor/mesh

Repo: github.com/avelor-es/mesh

CV as Code: Generating a PDF from an Astro page with Playwright

Sun, 31 May 2026 00:00:00 GMT

The CV lives in src/pages/cv-print.astro — a fully static, print-optimized HTML page with noindex. Playwright visits it headlessly and saves the output to public/, where the download link already points.

pnpm dev          # start local server on :4321
pnpm cv:pdf       # run scripts/generate-cv-pdf.mjs

The generation script:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();

await page.goto('http://localhost:4321/cv-print', { waitUntil: 'networkidle' });
await page.pdf({
  path: 'public/Christian_Elias_Cruz_Gonzalez_esp.pdf',
  format: 'A4',
  printBackground: false,
  margin: { top: '18mm', right: '18mm', bottom: '14mm', left: '18mm' },
});

await browser.close();

The page uses @page { size: A4; margin: ... } so margins are declared twice — once in CSS for browser preview, once in page.pdf() for the headless render. In practice Playwright ignores @page margins and uses the ones passed to pdf().

Why not `astro-pdf`

astro-pdf hooks into the build and visits pages post-build via a preview server. That works but adds build time and a dev dependency that trails Astro major releases. A standalone script is simpler: edit the page, run pnpm cv:pdf, commit the PDF. No build coupling.

ATS considerations

The resulting PDF is text-based (not a rasterized image), so ATS parsers extract content correctly. A few patterns that break ATS even in text PDFs:

Em dashes (—) in date ranges — some parsers (Greenhouse, Lever) misread them as unknown characters. Use simple hyphens.
+N prefix on numbers inside bullets — some parsers treat + as a boolean search operator. Write más de N or over N.
→ and < in prose — replace with plain text equivalents before generating.

Feature flag services don't store user IDs — and the consequence of that

Tue, 26 May 2026 00:00:00 GMT

Tessera holds no record of which users exist. No user table, no user IDs, no stored profiles. The evaluation endpoint receives a context and returns a result. Nothing persists about the user.

This is not a privacy decision primarily — it's a correctness decision. Storing users would require a registration step that creates a coordination problem: a user must exist in Tessera before they can be evaluated. That's a distributed state dependency with no benefit.

How evaluation stays consistent without storage

For percentage rollouts, consistency comes from the hash being deterministic:

bucket = murmur3(flagId + userId) % 100
enabled = bucket < rolloutPercentage

Same userId, same flagId, always the same bucket. The result is stable across requests, across servers, across time — without ever writing the user ID to a database.

For user-list rules, the rule itself stores the IDs (userId IN ['a1b2', 'c3d4', ...]). Tessera knows who gets the flag because the operator explicitly listed them, not because users were registered.

The consequence

If you need to answer "how many users currently have this flag active?" — you can't. Not without evaluating every user ID you know about, one by one.

The correct solution is exposure events: the SDK reports each flag read back to a collection endpoint.

// POST /v1/events
{
  "events": [
    { "flag": "nueva-ui", "userId": "a1b2c3d4", "value": true }
  ]
}

The events table becomes the source of truth for analytics. This is how LaunchDarkly, Statsig, and PostHog Flags work internally. The dashboard's impression counts come from event aggregation, not from querying a user registry.

Without exposure events, the service is still complete for controlling rollouts. You just can't measure exposure rates until you add the reporting layer.

What Tessera does store about users

One thing only: user-level overrides.

user_overrides (flag_id, environment, platform_user_id, value)

When an operator adds a specific user to a permanent override (beta tester, internal account), that platform_user_id is written. It's stored as an opaque string — whatever the client passes. Tessera doesn't know or care what it represents.

Separating the flag evaluation API from the dashboard in the same monorepo

Mon, 25 May 2026 00:00:00 GMT

Tessera's monorepo has two apps:

apps/
  eval-api/    ← Hono (Node.js)
  dashboard/   ← Next.js App Router

They share types from packages/core but run as separate processes. The split exists because the eval API is in the hot path of every flag read in every client application, and Next.js API routes carry overhead that has no place there.

What "hot path" means here

Every server component render, every middleware execution, every PHP page load that reads feature flags hits POST /v1/flags. In a Next.js app with 10 flagged code paths per request, that's one network call per page render — not ten, because the SDK fetches all flags at once and caches locally. But that one call needs to be fast.

A Hono handler on Node.js for this route is approximately:

app.post('/v1/flags', async (c) => {
  const token = await verifyToken(c.req.header('Authorization'))
  const flags = await loadFlags(token.projectId)          // memory cache, 5s TTL
  const result = evaluate(flags, await c.req.json())      // pure function, no I/O
  return c.json(result)
})

No framework boot, no middleware chain, no RSC runtime, no edge config resolution. The request goes in, the hashmap comes out.

Why Next.js API routes don't belong here

Next.js API routes run inside the Next.js runtime. That runtime does useful things for a dashboard — RSC, streaming, image optimization, middleware composition — none of which matter for a JSON endpoint that does a token lookup, a cache read, and a pure function call.

The overhead isn't theoretical. Next.js API routes have:

Cold start latency when the runtime hasn't warmed up
A heavier request lifecycle (middleware, headers normalization, response wrapping)
Coupling to the deployment model of the dashboard (if the dashboard is on Vercel, the API is too)

The dashboard has none of these constraints. Page loads are user-initiated, tolerate 200–400ms, and benefit from everything Next.js provides.

The monorepo makes this cheap

Both apps live in the same repo, share types and the evaluation logic from packages/core, and are deployed independently. The eval-api gets its own process, its own port, its own subdomain (flags.tessera.dev). The dashboard is a separate Next.js app that talks to the eval-api like any other client.

packages/core/src/evaluator.ts
  ↑ imported by
apps/eval-api/src/routes/eval.ts   (runs the evaluation)
apps/dashboard/...                  (uses the dashboard's own API routes for CRUD)
packages/sdk-next/src/server.ts    (calls eval-api over HTTP)

The evaluation logic is written once in core and runs in both the API (at request time) and potentially in the SDK (for offline/cached evaluation). Neither app owns it.

CSS print layout: floats, BFC, and image containment

Mon, 25 May 2026 00:00:00 GMT

@media print breaks several assumptions that hold in screen layout. Three interact badly when you mix a floated sidebar with article images.

Float instead of grid for variable-height sidebars

CSS Grid stretches both columns to the same height. In a two-column print layout where the sidebar is shorter than the article, the grid leaves a blank column on subsequent pages — the sidebar column reserves space even when empty.

float: right on the sidebar solves this. The sidebar occupies only as much vertical space as its content; once it ends, the article expands to full width.

@media print {
  .layout { display: block; }
  .sidebar { float: right; width: 6.5cm; margin-left: 0.5cm; }
  .article { padding: 0.5cm 0.4cm 0.5cm 0; }
}

clear: both is required on any element that must start below the float — otherwise it wraps around the sidebar at its natural document position.

DOM order matters for floats

Unlike Grid (where grid-column overrides source order), floats respect DOM position. A sidebar that appears after the article in the DOM floats to the right starting at the end of the article, not at the top.

The sidebar must precede the article in the DOM. For screen Grid, explicit grid-column / grid-row assignments restore the visual order:

.sidebar { grid-column: 2; grid-row: 1; }
.article { grid-column: 1; grid-row: 1; }

`overflow: hidden` on a float sibling creates a permanent BFC

The obvious fix for images overflowing into the sidebar column is to add overflow: hidden to the article element, which creates a Block Formatting Context that shrinks it to avoid the float. This works — but the BFC persists for the entire article, so every page is rendered as if the sidebar is still present. The narrow column follows the article onto page 2 and beyond.

The correct fix: don't create a BFC on the article. Instead, constrain images directly with an explicit max-width that fits within the article column at its narrowest point (alongside the sidebar):

@media print {
  figure {
    max-width: 10.5cm; /* page width − sidebar − margins */
    break-inside: avoid;
  }
  figure img {
    width: 100%;
    max-height: 9cm;
    height: auto;
  }
}

Images are then constrained by the figure's box, not by the article's BFC. On page 2, the figure is narrower than the full page but the article itself is not — an acceptable tradeoff.

`background` on pseudo-elements does not print

Lines drawn via background on ::before / ::after pseudo-elements (a common pattern for decorative rules between flex items) are suppressed by default in print — browsers treat them as background graphics, which users typically disable.

Use border-top with height: 0 instead:

/* won't print */
.rule::before { content: ''; flex: 1; height: 1px; background: black; }

/* prints reliably */
.rule::before { content: ''; flex: 1; height: 0; border-top: 1px solid black; }

Grayscale images

@media print {
  img { filter: grayscale(100%); }
}

One line. Color is preserved on screen; print output is monochrome. No build-time conversion needed.

JSON-LD Entity Graph for Brand Disambiguation on Minimal Sites

Sun, 24 May 2026 00:00:00 GMT

When a brand name is shared by multiple unrelated entities — a watch retailer, a consulting firm, a capital fund — Google has no reliable way to determine which result belongs to which entity unless the sites themselves publish structured signals. For a minimal site with a single indexed page, the problem is acute: no content volume, no backlink density, no topical authority. The only lever is the entity graph.

The Problem with Unnamed Entities

A JSON-LD block without @id is a hint. Google reads it, may or may not associate it with a Knowledge Graph node, and continues. Two sites publishing the same "name": "Avelor" with no canonical identifier produce ambiguous signals that Google resolves arbitrarily — usually by favoring whichever has more content or backlinks.

@id changes this. It declares a URI as the canonical identifier for the entity, making the JSON-LD node addressable and linkable across documents:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://avelor.es/#organization",
  "name": "Avelor"
}

Any other document that references "@id": "https://avelor.es/#organization" is now making a verifiable claim about the same node — not about a similarly-named entity.

The Three-Node Graph

A minimal site needs at minimum three nodes to establish a coherent entity graph:

graph LR
  WS["WebSite\n/#website"]
  ORG["Organization\n/#organization"]
  WP1["WebPage\n/pronunciacion#webpage"]
  WP2["WebPage\n/manifesto#webpage"]

  WS -->|publisher| ORG
  WP1 -->|isPartOf| WS
  WP1 -->|about| ORG
  WP2 -->|isPartOf| WS
  WP2 -->|about| ORG

WebSite → Organization via publisher establishes that the domain is owned by the entity. WebPage → Organization via about tells Google that each page is about the entity, not merely hosted there. Without the about relation, secondary pages are just pages — they don't strengthen entity recognition.

In practice, both the WebSite and Organization nodes live in a single JSON-LD array on the homepage:

[
  {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "@id": "https://avelor.es/#website",
    "url": "https://avelor.es",
    "name": "Avelor",
    "publisher": { "@id": "https://avelor.es/#organization" }
  },
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "@id": "https://avelor.es/#organization",
    "name": "Avelor",
    "url": "https://avelor.es",
    "foundingDate": "2018",
    "logo": {
      "@type": "ImageObject",
      "@id": "https://avelor.es/#logo",
      "url": "https://avelor.es/og-image.png",
      "width": 1200,
      "height": 630
    },
    "sameAs": [
      "https://www.linkedin.com/company/avelor-es/",
      "https://github.com/avelor-es",
      "https://www.wikidata.org/wiki/Q139894905",
      "https://wellfound.com/company/avelor"
    ]
  }
]

sameAs as Cross-Domain Corroboration

sameAs is where external profiles become structural. Each entry is a claim that the listed URL represents the same real-world entity. Google cross-references these: if LinkedIn, GitHub, Wikidata, and Wellfound all describe something called "Avelor" with avelor.es as the website, the entity is corroborated from four independent sources.

The order of sameAs entries doesn't matter. Coverage does. Wikidata carries disproportionate weight because it is Google's primary source for Knowledge Graph entities — a Wikidata entry with P856 (official website) pointing to the domain creates a bidirectional link that Google can verify.

rel="me" as the HTML Layer

JSON-LD operates at the semantic layer. rel="me" operates at the HTML layer and is processed independently by Google (and IndieWeb-aware tools). Publishing both for the same set of profiles removes the dependency on Google's JSON-LD parser being authoritative:

<link rel="me" href="https://github.com/avelor-es" />
<link rel="me" href="https://www.linkedin.com/company/avelor-es/" />
<link rel="me" href="https://www.wikidata.org/wiki/Q139894905" />
<link rel="me" href="https://wellfound.com/company/avelor" />

These live in <head> on every page via the shared layout, so every URL on the domain carries the ownership signal — not just the homepage.

Choosing Which Pages to Index

The standard advice for minimal brand sites is to index only the homepage. The counterintuitive move is to index pages whose content is about the brand name itself — even if they have no conventional SEO value.

A pronunciation guide (/pronunciacion) is a page whose entire subject is the word "Avelor": its phonetics, its syllable stress, its distinctiveness. Google indexes this as a document whose topic is the brand name. A manifesto whose every paragraph invokes the same name does the same. Neither page targets keywords. Both pages reinforce entity identity.

The constraint is that these pages must not collapse the brand into a market vertical. A /services page indexed with keywords like "software consulting Mexico" creates topical associations that constrain how Google categorizes the entity. Pages about the name, the philosophy, the pronunciation — these are safe.

logo as ImageObject

Declaring logo as a plain URL string works but leaves resolution ambiguous. As an ImageObject with explicit dimensions:

"logo": {
  "@type": "ImageObject",
  "@id": "https://avelor.es/#logo",
  "url": "https://avelor.es/og-image.png",
  "width": 1200,
  "height": 630
}

Google uses the logo in the Knowledge Panel. The @id on the ImageObject makes it referenceable from other entities if the domain ever expands to multiple sub-brands.

What This Doesn't Solve

Entity graphs establish identity. They do not generate rankings for non-branded queries. A site with one indexed page and no backlinks will not appear for any search term that isn't the brand name itself, regardless of how complete the structured data is.

The graph is a precondition for Knowledge Panel appearance and branded search consolidation — nothing more. External corroboration (editorial backlinks, directory listings, Google Business Profile) is what converts a well-formed graph into visible search presence.

RSS as a cross-site content bridge in Astro SSG

Sun, 24 May 2026 00:00:00 GMT

Two static sites. One is a portfolio (christianecg.com), built with Astro and deployed to GitHub Pages. The other is this notebook (octa.page), where active writing happens. The portfolio had a /blog section — but all the articles in it were from 2021–2022. The writing had moved to octa.page and the two were completely siloed.

The technical debt: a blog section showing stale content while the active equivalent existed elsewhere and neither site knew about the other.

Why RSS and not something else

The options were roughly:

Shared CMS or database — overkill for two static sites. Introduces infrastructure neither site needs.
Git submodule or monorepo — couples the two repos, complicates deploys.
Direct fetch from the octa.page source files — would require shared repo access and tight coupling.
RSS — octa.page already exposes /rss.xml. It's a stable contract. Stateless, versionless, requires nothing from the consumer.

RSS wins by elimination. It's also the right abstraction: octa.page doesn't need to know christianecg.com exists. The feed is an implementation detail of octa's public interface, consumed unilaterally.

Build-time consumption in Astro

Astro SSG runs fetch at build time in the page's frontmatter. No runtime, no hydration — the HTML is generated once with whatever the feed returns at that moment.

let octaArticles: Article[] = [];
try {
  const res = await fetch('https://octa.page/rss.xml');
  const xml = await res.text();
  octaArticles = [...xml.matchAll(/<item>([\s\S]*?)<\/item>/g)].flatMap(([, item], i) => {
    const title = item.match(/<title>(.*?)<\/title>/)?.[1]?.trim() ?? '';
    const link  = item.match(/<link>(.*?)<\/link>/)?.[1]?.trim() ?? '';
    const pub   = item.match(/<pubDate>(.*?)<\/pubDate>/)?.[1]?.trim() ?? '';
    const tags  = [...item.matchAll(/<category>(.*?)<\/category>/g)].map(m => m[1]);
    const date  = pub ? new Date(pub).toISOString().split('T')[0] : '';
    if (!title || !date) return [];
    return [{ id: `octa-${i}`, title, date, excerpt: '', tags, source: 'Octa', url: link, external: true, idx: 0 }];
  });
} catch {
  // RSS fetch failed — show only local articles
}

A few constraints drive the implementation:

No DOMParser in Node.js. Browser APIs aren't available in the build context. Regex over the raw XML string is the pragmatic choice for a feed this simple. A proper XML parser (fast-xml-parser etc.) would be justified if the feed had CDATA sections or nested namespaces — this one doesn't.

Graceful degradation is non-negotiable. A failed fetch during build shouldn't break the site. The try/catch ensures the page builds with only local articles if the feed is unreachable.

Merging and sorting happen in-process. Local articles and RSS articles are normalized to the same Article type, merged into a single array, and sorted by date. The external flag drives rendering decisions (badge, target="_blank", ↗ vs →).

The freshness problem

Build-time consumption means the portfolio goes stale as soon as octa.page publishes something new. The obvious mitigation — a scheduled nightly rebuild — has the wrong model: it rebuilds christianecg.com on a fixed interval regardless of whether octa.page changed.

The correct trigger is octa.page's own deploy completing.

Cross-repo dispatch

GitHub Actions supports repository_dispatch: an HTTP event that triggers a workflow in another repo. The pattern:

octa.page dispatches after deploy:

trigger-christianecg:
  needs: [deploy, check-content]
  if: needs.check-content.outputs.md_changed == 'true'
  runs-on: ubuntu-latest
  steps:
    - name: Trigger christianecg.com rebuild
      run: |
        curl -s -X POST \
          -H "Authorization: token ${{ secrets.CHRISTIANECG_DEPLOY_TOKEN }}" \
          -H "Accept: application/vnd.github.v3+json" \
          https://api.github.com/repos/ChristianECG/christianecg.com/dispatches \
          -d '{"event_type":"octa-deployed"}'

christianecg.com listens for the event:

on:
  push:
    branches: [main]
  workflow_dispatch:
  repository_dispatch:
    types: [octa-deployed]

The if: needs.check-content.outputs.md_changed == 'true' condition is the key constraint. A style change, config update, or tooling commit on octa.page still triggers a full build and deploy of octa — but doesn't cascade to christianecg.com. The dispatch only fires when .md files are in the diff.

The check-content job detects this:

check-content:
  runs-on: ubuntu-latest
  outputs:
    md_changed: ${{ steps.check.outputs.md_changed }}
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2
    - id: check
      run: |
        if git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -q '\.md$'; then
          echo "md_changed=true" >> $GITHUB_OUTPUT
        else
          echo "md_changed=false" >> $GITHUB_OUTPUT
        fi

fetch-depth: 2 gives access to HEAD~1. Without it, a shallow clone has no parent to diff against.

Trade-offs


Freshness	Near-zero delay when dispatch works. Falls back to manual `workflow_dispatch` if the PAT expires or the hook fails.
Coupling	One-directional. octa.page doesn't know christianecg.com exists. christianecg.com depends on the RSS contract, which is stable.
Failure modes	RSS unreachable at build time → local-only blog, no build failure. Dispatch token expired → stale portfolio until manual rebuild.
Complexity added	One PAT, one secret, ~20 lines of YAML across two repos.

The RSS contract is the right boundary. It decouples publication from consumption, keeps both sites independently deployable, and adds no shared infrastructure.

av.js — self-hosted analytics embed

Sat, 23 May 2026 00:00:00 GMT

av.js is a minimal analytics snippet that reports pageviews and custom events to analytics.avelor.es/collect. Drop a <script> tag, set data-project, done.

Embed

<script src="https://analytics.avelor.es/av.js" data-project="project-slug"></script>

data-project is required — without it the script exits immediately. Requests from localhost, 127.0.0.1, and ::1 are also silently skipped.

What it sends on load

A POST /collect with:

{
  "project_id": "project-slug",
  "url": "/path?query",
  "referrer": "https://example.com",
  "session_id": "lxk3r2abc9d"
}

session_id is generated once per tab and stored in sessionStorage under _av_sid. It survives navigation within the tab but not across tabs or sessions.

Custom events

window.avelor.track('event-name', { key: 'value' });

Event name is truncated to 100 chars. properties is a free-form object or null. Full payload:

{
  "type": "event",
  "project_id": "project-slug",
  "session_id": "lxk3r2abc9d",
  "name": "click-cta",
  "url": "/",
  "properties": { "variant": "A" }
}

Implementation notes

keepalive: true on the fetch call — the request survives page navigation, so events sent just before a redirect are not lost.
credentials: 'omit' — no cookies or auth headers sent to the collector.
Network errors are swallowed — a dead collector does not break the host page.

Using the URL fragment as an encryption key carrier

Fri, 22 May 2026 00:00:00 GMT

The URL fragment (#everything-after-the-hash) is never sent to the server. Browsers strip it before making the HTTP request. This makes it a natural channel for passing a secret that the server must never see — specifically, an encryption key for a one-time secret.

The design

When a secret is created:

The browser generates a random AES-256-GCM key via crypto.subtle.generateKey.
It encrypts the plaintext locally. The encrypted blob (IV + ciphertext) is sent to the server as the content field.
The server stores only the ciphertext. It has no key and cannot decrypt.
The share URL is constructed as https://vault.example.com/s/{token}#{key_b64u}.

async function encryptContent(plaintext) {
  const key    = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt']);
  const iv     = crypto.getRandomValues(new Uint8Array(12));
  const cipher = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, new TextEncoder().encode(plaintext));
  const rawKey = new Uint8Array(await crypto.subtle.exportKey('raw', key));

  const combined = new Uint8Array(iv.byteLength + cipher.byteLength);
  combined.set(iv);
  combined.set(new Uint8Array(cipher), iv.byteLength);

  return {
    content: toBase64url(combined),  // sent to server
    keyB64:  toBase64url(rawKey),    // goes in the URL fragment
  };
}

When the recipient opens the link:

The browser reads location.hash.slice(1) — the key, which was never sent to the server.
It POSTs to the token URL. The server marks the secret as viewed (viewed_at = NOW()) and returns the ciphertext.
The browser decrypts locally.

const keyB64   = location.hash.slice(1);
const rawKey   = base64urlToBytes(keyB64).buffer;
const key      = await crypto.subtle.importKey('raw', rawKey, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);

const res      = await fetch(location.pathname, { method: 'POST' });
const data     = await res.json();  // { ok: true, content: "<base64url>" }

const combined = base64urlToBytes(data.content);
const iv       = combined.slice(0, 12);
const cipher   = combined.slice(12);
const plain    = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, cipher);

What the server knows

Field	Stored	Value
Token	Yes	Random 32-byte hex
Ciphertext	Yes	AES-GCM output
Key	No	Never transmitted
Plaintext	No	Never transmitted
`viewed_at`	Yes	Timestamp of first reveal

A server compromise exposes token metadata and ciphertext. Without the key — which only exists in the URL fragment and the recipient's clipboard — the ciphertext is opaque.

Constraints

The fragment is in browser history. If the recipient's browser syncs history, the key travels with it. For very high-sensitivity secrets, recipients should open the link in a private window and clear it afterward.

One-time enforcement is server-side only. The burn semantics (set viewed_at, return 410 on subsequent requests) happen on the server. A network-level attacker who can observe and replay the POST before the server processes it could retrieve the ciphertext twice. Without the fragment key, ciphertext copies are equivalent — but it means "one-time" is a server policy, not a cryptographic guarantee.

The key is in the URL. Any proxy, CDN, or browser extension that logs full URLs will capture the key. The fragment exclusion is a browser-to-server guarantee — intermediaries that inspect the page before the browser processes it are outside the model.

Why not a separate key delivery channel?

Delivering the key out-of-band (email, SMS) and the ciphertext via a link would be more secure — but it defeats the purpose of a self-contained share link. The fragment approach makes the UX of "share one link" possible while keeping the server out of the trust chain for anything that happens before the browser sends the request.

A WebSocket relay as a self-hosted tunnel

Fri, 22 May 2026 00:00:00 GMT

A tunnel that exposes localhost:3000 at a public HTTPS URL doesn't need SSH. A WebSocket relay achieves the same result with nothing but an outbound connection from the developer's machine, a small Node.js process on the server, and a shared secret for auth. No keys to distribute, no port forwarding rules, no firewall exceptions.

The problem with SSH reverse tunnels in public CLIs

ssh -R 9000:localhost:3000 user@server -N works, but it requires the user to have an SSH key authorized on the server. That's fine for a private tool. The moment the CLI becomes public, every user needs their own SSH key provisioned — which means a registration flow, key management, and a security surface on the server's authorized_keys. Token-based auth is simpler and easier to revoke.

Architecture

sequenceDiagram
    participant Browser as Browser / webhook sender
    participant Apache as Apache (tunnel.avelor.es)
    participant Relay as relay.js (127.0.0.1:9001)
    participant CLI as avelor CLI
    participant Local as localhost:3000

    CLI->>Relay: WebSocket connect (Bearer token)
    Browser->>Apache: HTTP request
    Apache->>Relay: HTTP proxy
    Relay->>CLI: serialize request over WS
    CLI->>Local: forward HTTP
    Local-->>CLI: response
    CLI-->>Relay: serialize response over WS
    Relay-->>Apache: write response
    Apache-->>Browser: response

The relay process listens only on 127.0.0.1. Apache handles TLS and proxies both HTTP traffic and the WebSocket upgrade to the relay. The CLI initiates the only outbound connection — no inbound ports are opened on the developer's machine.

Request lifecycle

Every incoming HTTP request becomes a message on the WebSocket channel. The relay assigns a uuid to the request and stores a reference to the res object in a Map:

const id = randomUUID();
queue.set(id, { res, timer });
peer.send(JSON.stringify({ id, method, url, headers, body }));

The body is base64-encoded to survive JSON serialization cleanly across binary payloads (file uploads, compressed responses, etc.).

The CLI receives the message, forwards it to the local server as a plain HTTP request, and sends back:

{ id, status, headers, body }  // body is base64

The relay looks up the id in the queue, writes the response headers and body, and resolves the original HTTP request. From the browser's perspective it was a normal round-trip.

If the CLI doesn't respond within 30 seconds, the relay times out with a 504 and removes the pending entry. If the WebSocket disconnects mid-flight, all pending requests are resolved with 502.

Apache configuration

Two proxy rules are needed: one for the WebSocket handshake, one for regular HTTP traffic.

# WebSocket upgrade — must come before the catch-all ProxyPass
RewriteEngine On
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/_tunnel$ ws://127.0.0.1:9001/_tunnel [P,L]

ProxyPass        / http://127.0.0.1:9001/
ProxyPassReverse / http://127.0.0.1:9001/

mod_proxy_wstunnel handles the WebSocket leg. The rewrite rule targets only /_tunnel so that all other paths fall through to the HTTP proxy and get relayed as tunneled requests.

Auth

The CLI sends Authorization: Bearer <token> in the WebSocket handshake headers. The relay checks it before accepting the connection:

wss.on('connection', (ws, req) => {
  const auth = (req.headers['authorization'] || '').trim();
  if (auth !== `Bearer ${TOKEN}`) {
    ws.close(1008, 'unauthorized');
    return;
  }
  // ...
});

The token is transmitted only over TLS (Apache enforces HTTPS), and it lives in the CLI's local config file — never in the URL or logs. Since this is a single-user tool, there's also a hard limit of one active connection at a time: a second connect event closes the new socket immediately.

The `--run` flag

avelor tunnel 3000 --run "npm run dev" spawns the child process first, then polls 127.0.0.1:3000 with HEAD requests at 500ms intervals until the port accepts connections. Only then does it open the WebSocket. This avoids the race condition where the tunnel is active before the dev server is ready.

function waitForPort(port, timeout = 30_000) {
  return new Promise((resolve, reject) => {
    const deadline = Date.now() + timeout;
    function attempt() {
      const req = http.request({ hostname: '127.0.0.1', port, method: 'HEAD', path: '/' }, () => resolve());
      req.on('error', () => {
        if (Date.now() >= deadline) return reject(new Error(`port ${port} not ready`));
        setTimeout(attempt, 500);
      });
      req.end();
    }
    attempt();
  });
}

On SIGINT, the CLI closes the WebSocket and kills the child process.

Trade-offs

Single connection is a deliberate constraint. The relay was designed for testing webhooks locally, not for serving production traffic. One active tunnel keeps the relay stateless and the auth model trivial.

Full buffering — requests and responses are fully buffered before forwarding. This means no streaming support and an implicit limit on payload size (whatever fits in Node's default buffer). For the webhook testing use case this is fine; for anything involving large file uploads it would need chunked forwarding over multiple messages.

No subdomain isolation — there is one fixed public URL. This is intentional: a wildcard subdomain would require a wildcard TLS certificate and dynamic nginx/Apache config. The simpler model is one URL, one user, one token.

tailscale serve sets REMOTE_ADDR to 127.0.0.1 for every request

Thu, 21 May 2026 00:00:00 GMT

tailscale serve terminates HTTPS at the Tailscale layer and forwards plain HTTP to a local backend. From the application's perspective, every request originates at 127.0.0.1 — regardless of which Tailscale node made the request. This collapses the identity of all callers to the loopback address.

Why it matters

The typical pattern for Tailscale-gated PHP apps is to check REMOTE_ADDR against the Tailscale CGNAT range (100.64.0.0/10) or to trust the Tailscale-User-Login header injected by tailscale serve. These two signals are mutually exclusive:

If you check REMOTE_ADDR for Tailscale IPs → you get the real node IP, but tailscale serve is not in the picture (you're listening directly on the Tailscale interface or binding to the node's IP).
If you rely on Tailscale-User-Login → the proxy is in the picture, and REMOTE_ADDR is 127.0.0.1.

A guard like this silently bypasses all auth when tailscale serve is the deployment method:

$isLocal = in_array($_SERVER['REMOTE_ADDR'], ['127.0.0.1', '::1'], true);
if ($isLocal) return; // exits before checking Tailscale-User-Login

The Tailscale-User-Login branch is never reached. Every request is treated as a trusted local caller.

The fix

Drop the REMOTE_ADDR shortcut entirely. When tailscale serve is the proxy, the only reliable identity signal is the injected header:

function requireTailscaleAuth(): void
{
    $login = $_SERVER['HTTP_TAILSCALE_USER_LOGIN'] ?? '';
    if ($login !== 'allowed@example.com') {
        http_response_code(403);
        header('Content-Type: text/plain');
        echo 'Forbidden';
        exit;
    }
}

The isLocal escape hatch is often added for local development. It's unnecessary: dev environments using php -S route through a custom router that doesn't call the auth function, so removing the bypass doesn't break anything.

The underlying mechanic

tailscale serve is a reverse proxy, not a network-layer filter. It listens on the Tailscale interface, handles TLS, injects identity headers, and makes a new outbound connection to localhost:PORT. The application sees a fresh TCP connection from the loopback. There is no X-Forwarded-For or equivalent by default — the node IP is only available in the injected Tailscale-User-* headers.

This is architecturally correct behavior for a proxy, but it breaks assumptions borrowed from traditional firewall-based access control where IP address implies identity.

Building gob.co.nz: A Static Corrections Register

Wed, 20 May 2026 00:00:00 GMT

gob.co.nz is a public corrections register for the tech industry — a fe de erratas that documents revised positions, failed predictions, unfulfilled promises, and dissolved consensus. Each entry is a citable URL someone sends in a conversation. The aesthetic is deliberately institutional: a government gazette that happens to be on the web.

Stack decisions

The constraints were clear from the start: zero client-side JS unless strictly necessary, content portable as plain Markdown, fast enough to not think about performance.

Astro 6 for static generation. Same reasoning as Octa — pure HTML by default, islands opt-in. The difference here is that Pagefind is included from day one (deferred on Octa). At content volume, client-side search is more useful than a filter bar alone.

Tailwind CSS v4 via @tailwindcss/vite directly in astro.config.mjs. The old @astrojs/tailwind integration is incompatible with Tailwind v4 — it targets the v3 PostCSS plugin. The correct setup:

// astro.config.mjs
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

No @astrojs/tailwind in integrations. CSS theme tokens live in @theme {} blocks inside global.css.

iA Writer Quattro via @fontsource. Monospace with document aesthetics — fits the bureaucratic design brief without adding a separate font-loading strategy.

Content model

Four entry types, each a different failure mode:

posicion-revisada    → industry used to say X, now says Y
promesa-incumplida   → someone said X would happen, it didn't
prediccion-fallida   → X was forecasted, the opposite occurred
consenso-disuelto    → everyone agreed on X, no longer do

Each entry has structured fields (declaration, origin, origin_year, correction, cause, status_since) plus optional body markdown. The constraint: if correction can't reflect documented consensus — not an opinion — the entry isn't ready to publish.

Astro 6 Content Layer API footguns

Three breaking changes from Astro 4/5 that aren't obvious from the migration docs:

Config location. Content collection config must be at src/content.config.ts, not src/content/config.ts. The old path silently fails.

Glob loader required. Collections no longer auto-discover content. Every collection needs an explicit loader:

import { glob } from 'astro/loaders';

const erratas = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/erratas' }),
  schema: z.object({ ... }),
});

render() is a module import, not an instance method. In Astro 4 you'd call entry.render(). In Astro 6:

import { render } from 'astro:content';

const { Content } = await render(entry);

Calling entry.render() throws at runtime with no useful error message.

OG image generation

Per-entry OG images are generated at build time using sharp to convert SVG to PNG. The SVG is composed in TypeScript — layout, type badge with color, title wrapping, subtitle.

Two issues that took iteration to fix:

Font rendering in SVG. The original used iA Writer Quattro for the OG image — predictably, librsvg (what sharp uses internally) doesn't have that font. The SVG renders with a fallback that breaks the layout. Fix: use Arial, Helvetica, sans-serif in the SVG. Predictable across environments.

Title overflow. wrapText() was splitting at 52 characters assuming 52px font. At 52px on a 1040px canvas, the actual character limit is ~26 for proportional fonts. The fix is to split conservatively (maxChars=26) and cap at 2 lines, truncating with … if needed.

text-transform: uppercase doesn't work in SVG attributes — apply .toUpperCase() in JS before inserting the text node.

Pagefind

Pagefind runs post-build as a separate command:

"build": "astro build && pagefind --site dist"

It requires a data-pagefind-body attribute on the content container. Without it, Pagefind indexes all pages including nav and footer text. With it, pages without the attribute are excluded — which means the index is scoped to entry bodies only.

Not available in dev. The tradeoff is acceptable: search is a production concern.

git hygiene

The .astro/ directory (generated files: content modules, data store, type declarations) was committed by mistake in the initial setup — the bootstrapped .gitignore only excluded node_modules/ and dist/. The fix:

git rm -r --cached .astro/

Then add .astro/ to .gitignore. This removes the directory from the index without deleting local files, so Astro's dev server continues working.

Design system

The design brief was "government gazette" — white background, dense information, no decoration. Three decisions that define the aesthetic:

Color only for type classification. Each of the four entry types has one muted color used exclusively for its badge. No other color in the UI except structural rules.

Dark mode via CSS custom properties. All colors are var(--color-*) tokens. The @media (prefers-color-scheme: dark) block overrides the tokens — no class toggling, no JS. The dark palette is soft: #1e1e1b background, not pure black.

Band colors decoupled from paper. The header masthead is a dark band (--color-band-bg). In dark mode, if the band uses the paper color as text and the paper color inverts, the contrast breaks. The fix: dedicated --color-band-text and --color-band-muted tokens that are independent of --color-paper, so the band stays legible regardless of mode.

Building Octa: Architecture Decisions for a Static Engineering Notebook

Wed, 20 May 2026 00:00:00 GMT

Octa is not a blog. It's a structured notebook for engineering thinking — closer to an internal memo system than a publishing platform. This document records the decisions made during its initial construction.

What it needs to do

The core requirement is durable technical writing that stays readable without maintenance. That means:

No database. No CMS. No API dependencies.
Content portable as plain Markdown.
Fast enough to not think about performance.
Simple enough to not break over time.

The anti-requirements were equally clear: no SEO optimization, no engagement mechanics, no social features.

Framework: Astro 6

Static generation with minimal client-side JavaScript was the primary constraint. Astro satisfies this better than the alternatives:

Next.js (static export) ships a React runtime by default. Even a static export loads the hydration layer. For a content site that needs exactly one interactive feature (Mermaid diagrams), that's excess weight.

Astro generates pure HTML by default. JS islands are opt-in per component. The entire site — sidebar, navigation, article layout — runs zero client JS except the Mermaid renderer on article pages.

The tradeoff: Astro's Content Layer API (v5+) has a strict isolation requirement for getStaticPaths. Any module-level constant referenced inside the function must be re-declared inline, because the function runs in a separate build scope. This is a footgun worth documenting.

Content model

Six content types map to six Astro collections:

/content/architecture   → system design, tradeoffs
/content/runtime        → browser behavior, scheduling
/content/pulse          → the Pulse observability project
/content/systems        → long-form reasoning
/content/notes          → short-form technical notes
/content/investigations → (legacy, not exposed in navigation)

All share a single frontmatter schema:

title: string
date: date
tags: string[]
project: string?      # cross-cutting — links to /project/:name
series: string?       # groups sequential posts
pinned: boolean       # surfaces in sidebar "Pinned" count
status: published | draft

The project field is the key architectural choice. Types categorize what kind of content something is. Projects categorize what it's about. An architecture note about Pulse's ingestion pipeline has type: architecture and project: pulse. Both lenses are available from the sidebar without duplication.

URL structure

/doc/:slug      → individual articles
/type/:type     → type index pages
/project/:name  → project index pages

Flat /doc/:slug means slugs must be unique across all content directories. This is a mild constraint in practice — filenames that describe the content are naturally unique. The benefit is clean URLs without implementation leaking into them. A document about scheduler behavior doesn't need /runtime/ in its URL.

Sidebar design

The sidebar has three groups in a single scroll:

Index — aggregate views (all, this month, pinned, drafts)
Types — the five active content types
Projects — derived at build time from project frontmatter values across all collections

The Projects group is dynamic: it only renders if at least one published document has a project field. No configuration required to add a new project — write a document with the field and it appears.

Originally the sidebar had a tab switcher between Sections and Projects. This was removed. Tabs imply that only one view is useful at a time, which creates a navigation hierarchy that doesn't exist conceptually — Types and Projects are parallel classification systems, not alternatives.

Design system

The visual system follows the Observatory brief: dark-only, no rounded corners, no gradients, hairline rules, monospace metadata.

The accent color (oklch(74% 0.07 240) — desaturated blue) is used structurally, not decoratively:

Active nav item
Type labels in tables
Project badge in article breadcrumb
Build status dot

Nowhere else. This keeps the accent meaningful as a signal rather than a decoration.

Fonts are self-hosted Geist variable fonts (woff2) copied from the geist npm package to /public/fonts/. This avoids Google Fonts requests and keeps the font stack self-contained. The variable format covers the weight range (300–500) used across the UI in a single file per typeface.

Mermaid diagrams

Diagrams render client-side using the mermaid npm package. The approach:

Astro renders \``mermaidcode blocks as
```
...
```
` in the HTML.
A <script> in ArticleLayout.astro queries all .language-mermaid elements, replaces each <pre> with a container <div>, and calls mermaid.render().

This works for both .md and .mdx files without a remark plugin or build-time headless browser. The tradeoff is that diagrams require JS — acceptable for a technical audience.

The mermaid theme is configured to match the Observatory design system:

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor:       '#171c25',
    primaryTextColor:   '#dde0e6',
    lineColor:          'rgba(255,255,255,0.35)',
    fontFamily:         'Geist Mono, ui-monospace, monospace',
  },
});

Example diagram — the content routing architecture:

graph LR
  A["/content/**/*.md"] --> B["Astro Content Layer"]
  B --> C["/doc/:slug"]
  B --> D["/type/:type"]
  B --> E["/project/:name"]
  B --> F["/index"]

What was left out

Search (Pagefind) — deferred. The table layout on the homepage already functions as a scannable index. Search adds value at volume (50+ documents).

Series linking — the series field is stored in frontmatter and displayed in article metadata, but there's no "previous / next" navigation yet. At low volume this isn't needed.

Light mode — explicitly out of scope. A dark engineering notebook with a single theme is simpler to maintain and fits the target aesthetic.

Octa

Serving every article as an RFC-style plain text document

Format

Implementation

Leap Seconds After 2035: What Was Actually Decided, and the Proposals on the Table

Why leap seconds exist

Why they cause more problems than they solve

The proposals on the table

A variant: scheduled 4-year correction blocks

The bound, shown

The trade-off, explicitly

Timezone Propagation: How IANA Changes Reach Your Application

The Propagation Pipeline

Timeline: From IANA Decision to User System

Node.js: The Duality Problem

Source 1: Native Date (from the Operating System)

Source 2: Intl.DateTimeFormat (from Bundled ICU)

The Mismatch

Case Study: British Columbia's Permanent Daylight Time

IANA's Workaround

Why Propagation Matters

What to Do

Completing the IPoAC Stack: Why DoAC Had to Exist

What the IPoAC stack looked like before DoAC

The gap

Design decisions

The AA resource record

The bootstrapping problem

Retransmission

DNSSEC

What this is, technically

My First Internet Draft: DNS over Avian Carriers

What's an Internet-Draft

The April Fools RFC tradition

What DoAC specifies

The submission process

What's next

Injecting git config per-process with GIT_CONFIG_KEY_n

The env var approach

When this matters

floo: a minimal deploy agent for self-hosted VPS

Architecture decisions

What I ruled out

Implementation

Bifrost: what changed when a private tunnel became a public package

Named tunnels with subdomain routing

Token scoping

Backpressure

Dead connection detection

Client resilience: 1008 means stop

Queue drain on disconnect

Building @avelor/vhost: From Repeated Pain to Open Source Tool

The tool

Gradual migration

Error pages via content negotiation

Why open source

Why I Built mesh: Local Dev Proxy with Named Services and Failure Injection

The failure injection part

What I ruled out

Implementation

CV as Code: Generating a PDF from an Astro page with Playwright

Why not astro-pdf

ATS considerations

Feature flag services don't store user IDs — and the consequence of that

How evaluation stays consistent without storage

The consequence

What Tessera does store about users

Separating the flag evaluation API from the dashboard in the same monorepo

What "hot path" means here

Why Next.js API routes don't belong here

The monorepo makes this cheap

CSS print layout: floats, BFC, and image containment

Float instead of grid for variable-height sidebars

DOM order matters for floats

overflow: hidden on a float sibling creates a permanent BFC

background on pseudo-elements does not print

Grayscale images

JSON-LD Entity Graph for Brand Disambiguation on Minimal Sites

The Problem with Unnamed Entities

The Three-Node Graph

Source 1: Native `Date` (from the Operating System)

Source 2: `Intl.DateTimeFormat` (from Bundled ICU)

Why not `astro-pdf`

`overflow: hidden` on a float sibling creates a permanent BFC

`background` on pseudo-elements does not print

The `--run` flag