Terms

2026-08-23T00:00:00+00:00

Last updated: August 23, 2026

General character of the website

This website is a private, non-commercial blog with mostly informational content. It can be used without registration and without providing personal data.

The following notes are for transparency and clarity. They are not general terms and conditions and not a contract in a legal sense.

Content and opinions

The content published on this website reflects my personal views and experiences. It is not professional advice, in particular not legal, tax, medical, or financial advice.

I aim to provide correct and current information but make no warranties regarding accuracy, completeness, or suitability for a specific purpose.

Liability

Liability for damages arising from use of, or reliance on, the information on this website is excluded to the extent permitted by law.

Nothing in these notes excludes or limits liability for death or personal injury caused by negligence, or for fraud, or any other liability that cannot be excluded under English law.

External links

This website may contain links to external websites of third parties. I have no influence on their content.

The provider or operator of the linked pages is always responsible. At the time of linking, no illegal content was apparent. If legal violations become known, the links will be removed promptly.

Copyright and use of content

The content and works published on this website are subject to UK copyright law (Copyright, Designs and Patents Act 1988).

Unless stated otherwise, copying and redistribution are permitted as long as the author's attribution notice remains and the use is not commercial.

Any further use requires my prior consent.

Privacy

Information about the processing of personal data and browser storage can be found in the privacy policy.

Applicable law

These notes and the use of this website are governed by the laws of England and Wales.

Closing note

If any part of these notes is or becomes invalid, the remaining content remains effective.

Chasing a five-year-old Windows-only race condition in Zola

2026-08-18T00:00:00+00:00

A few weeks ago I started to run into constant build failures in Zola, the Rust static site generator that I planned to use for this blog:

Error: Was not able to copy file ...\content\entertainment\filename\2.png to ...\public\entertainment\filename\2.png
Reason: Another program is using this file and the process cannot access it (os error 32)

Windows error 32 is ERROR_SHARING_VIOLATION — it means another process (or another thread in the same process) had the file open when something tried to overwrite it. The build didn't fail every time, which is the classic signature of a race condition: sometimes the timing lines up badly, sometimes it doesn't.

A quick search turned up issue #1599, open since 2021, reported by another Windows user hitting the exact same error on a page with a dozen resize_image() calls. It had sat there for years labeled "Need Windows help" — understandable, since intermittent, platform-specific races are miserable to debug from a distance, and it seems that Zola's main maintainer does not run Windows day to day.

Reproducing it

I grabbed a copy of zola, set up a rust deelopment environment, and with a bit of help from our AI friends - set up a repository to troubleshoot the issue - my repository. I started out instrumenting Zola's file-copy code directly, since the error message alone didn't say much beyond "something else has this file open." I had my AI assistant add:

a small dbgfs! macro that logs a timestamp and thread ID alongside each filesystem operation, so I could see which threads were touching which paths and in what order
a retry-with-backoff wrapper around the copy/remove/hard-link calls, specifically catching raw OS error 32 and giving Windows a few tens of milliseconds to release the lock before giving up.

The retry wrapper idea came from reviewing github and spotting that Tauri does something similar - they found that antivirus services were keeping the file locked. This was a temporary issue to try and seew whether we could get past the lock — I flagged it in the commit as temporary scaffolding to confirm the theory, not something to actually ship. But the debug logging was the useful part: it showed two threads copying the same asset to the same destination path at effectively the same moment.

At this point, it pointed at Zola's and it's build system itself being the issue - rather then a 3rd party (antivirus / indexing etc). Great news!. The AI assistant did a good job at this point of working out what was going on - Pages are rendered and their assets copied in parallel via rayon, and each page is normally queued exactly once. But Zola has a transparent section feature, where a page can effectively belong to more than one section in the content tree. So, between myself, the AI, the other users on the bug and the zola developer - they had a working theory that a page under a transparent section was showing up in the page list of every transparent ancestor section, not just its immediate parent — so it was getting pushed onto the job queue once per ancestor. On Linux and macOS, two threads writing the same bytes to the same path at nearly the same time is harmless. On Windows, it's a sharing violation.

I left the diagnosis and the repro for the maintainers, since confirming and fixing it properly needed someone who understand the project and the RUST programming language. My work was done - I could build my set, and the developers hopefully had everything they needed to implement the proper fix.

The real fix

Keats picked it up and landed the fix in next: c1d0438, "Render pages only once when transparent=true." It confirmed the theory — his commit message points straight at #1599.

The fix itself is small. add_section_jobs() now takes a seen_pages: &mut HashSet<&'a Path> parameter, and every page gets checked against it before being pushed as a job:

if page.meta.render && seen_pages.insert(&page.file.path) {
    self.jobs.push(Job::Page(page));
}

HashSet::insert returns false if the value was already present, so this one line does double duty: it's both the "have we seen this page already" check and the "mark it as seen" step. Each caller — single_section, full_build, and the orphan-page pass — now threads a HashSet through the section-walking code, so a page reachable through multiple transparent ancestors only ever gets queued, rendered, and copied once.

It's a cleaner shape than my version, too — I'd stored the dedup set as a field on the Queue struct itself; threading it through as a parameter keeps it scoped to a single build pass instead of living on the struct for its whole lifetime.

An hour of work, a fix a day later, a five-year-old bug closed

It's a good reminder that "stale" and "hard" aren't the same thing. This one had been open for five years, but once it had a solid investigation, Keats landed the actual fix in about a day. I doesn't look like the bug was hard to fix — it was hard to see, because a few things had to line up before it would even show its face:

Windows, where concurrent access to the same file path is enforced at the OS level, unlike POSIX systems where it's usually silently fine
transparent sections - i'm guessing possibly a niche feature that not every project in Zola uses
Multiple images or assets on one page, since the race window is small and needs several parallel copy jobs racing for the same file to actually collide in practice

Any one of those alone wouldn't have reproduced it — which is exactly why "Need Windows help" sat unclaimed for so long despite being a completely deterministic bug once you knew where to look. The fix that mattered was in the queue's job-dedup logic, not in retrying failed filesystem calls — the retries in my diagnostic commit would have papered over the symptom without addressing why two threads were fighting over the same file in the first place.

It's a nice example of how "flaky" bugs are often not flaky at all — they're deterministic bugs whose triggering conditions are just rare enough that a good repro, not more retries, is what actually finds them.

Gaming Links

2026-08-02T00:00:00+00:00

Built a Shed From Scratch

2026-07-26T00:00:00+00:00

Not every project on here is going to be about computing. This one's from the garden rather than the terminal — a lean-to style timber shed, built from scratch against the side of the house, from the base up.

The base

A concrete pad was never really on the cards here. The patio underneath is on a noticeable slope, so I went with adjustable paving-slab pedestals instead — they let you level everything out independently of the slope, rather than trying to fight it with the base itself.

With the slabs level, the base frame went together next — treated timber joists with OSB board across the top, again all resting on the pedestals rather than fixed straight to the patio.

Cutting, painting, framing

All the timber for this came from Aylwards Fencing in Enfield. Worth a mention on its own — the staff there were genuinely helpful, talking through how to actually put the thing together rather than just selling me wood and sending me on my way.

Next came the least glamorous but most time-consuming part: cutting every piece of timber to length and giving it a coat of red wood stain before assembly — much easier to do flat on the patio than once it's upright and half-boxed-in.

Once enough pieces were cut and stained, the first wall frame went together on the ground.

Getting the roof angle right

A lean-to roof means one clean sloped line, which means getting the angle and the height right before anything gets fixed permanently. A fair bit of this stage was just measuring, checking, and measuring again.

Roof and cladding

With the angle confirmed, the roof structure went on, followed by the cladding boards, working from the bottom up so each row overlaps the one below.

The roof beam itself gets fixed directly to the house wall for support:

Then the roofing felt went on over the top:

Finished

A door, hinges, and the last of the cladding later, and it's a proper shed — narrow enough to fit down the side of the house, tall enough to actually be useful, and built to actually last.

Total build time was spread over a couple of months of weekends rather than one solid push, and that was less about scheduling than about the fact that this was the first time I'd properly built anything out of wood. A lot of the time went into just thinking — working out the design, second-guessing measurements, walking away from a problem and coming back to it rather than pushing through and getting it wrong.

And there are things I'd do differently. A few joints aren't as clean as they should be, the roof angle took more trial and error than it needed to, and there are a couple of decisions I'd make the opposite way with the benefit of hindsight. It's very much a "V1" — useful, standing, doing its job — but I've already mentally sketched out what a V2 would do differently.

Microsoft

2026-07-24T00:00:00+00:00

Projects

2026-07-24T00:00:00+00:00

AI Game

2026-07-23T00:00:00+00:00

Experiment in asking Claude to code a game

Plan: AI "cookie clicker game"

Plan to implement │ │ │ │ Plan: AI Idle Game — Initial Scaffold & MVP │ │ │ │ Context │ │ │ │ Building a new browser-based idle game with an AI/tech theme. Core inspiration is Cookie Clicker (clicker loop, big │ │ numbers, upgrades) crossed with Melvor Idle (skill depth, parallel activities). Unique feature: a hybrid world map │ │ showing geographic data centre placement with network connection overlays. Boss events are firewall attacks on data │ │ centres. │ │ │ │ --- │ │ Tech Stack │ │ │ │ ┌─────────────────┬────────────────────┬───────────────────────────────────────────────┐ │ │ │ Layer │ Choice │ Reason │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ Build tool │ Vite │ Fast HMR, TS out of the box │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ UI │ React + TypeScript │ Component model fits idle game panels │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ State │ Zustand │ Minimal boilerplate, perfect for game state │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ Map │ react-simple-maps │ Lightweight SVG world map, easy click regions │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ Network overlay │ Custom SVG │ Lines drawn over the map between DC markers │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ Styling │ Tailwind CSS │ Utility classes, dark sci-fi theme │ │ │ ├─────────────────┼────────────────────┼───────────────────────────────────────────────┤ │ │ │ Animations │ CSS transitions │ Keep it lightweight for now │ │ │ └─────────────────┴────────────────────┴───────────────────────────────────────────────┘ │ │ │ │ --- │ │ Project Structure │ │ │ │ E:\aigame\ │ │ ├── src/ │ │ │ ├── components/ │ │ │ │ ├── Map/ │ │ │ │ │ ├── WorldMap.tsx # react-simple-maps base + SVG overlay │ │ │ │ │ ├── DataCentreMarker.tsx # Clickable node on map │ │ │ │ │ └── NetworkLine.tsx # SVG line between two DC coordinates │ │ │ │ ├── HUD/ │ │ │ │ │ ├── ResourceBar.tsx # Top bar: Compute, Credits, Bandwidth │ │ │ │ │ └── GameHeader.tsx # Title + prestige info │ │ │ │ ├── Panels/ │ │ │ │ │ ├── ClickPanel.tsx # Main click button + CPS display │ │ │ │ │ ├── UpgradesPanel.tsx # Purchasable upgrades list │ │ │ │ │ ├── RegionPanel.tsx # Sidebar when a region is selected │ │ │ │ │ └── SkillsPanel.tsx # Melvor-style skill tracks │ │ │ │ └── Combat/ │ │ │ │ └── BossAlert.tsx # Overlay when firewall attack starts │ │ │ ├── store/ │ │ │ │ ├── gameStore.ts # Resources, ticks, CPS │ │ │ │ ├── mapStore.ts # Regions, data centres, connections │ │ │ │ └── combatStore.ts # Active boss events, firewall HP │ │ │ ├── data/ │ │ │ │ ├── regions.ts # Region definitions (name, coords, bonuses) │ │ │ │ ├── upgrades.ts # Upgrade tree definitions │ │ │ │ └── bosses.ts # Boss types and stats │ │ │ ├── hooks/ │ │ │ │ └── useGameLoop.ts # setInterval tick (100ms), drives all stores │ │ │ ├── App.tsx # Layout: map centre, panels left/right │ │ │ ├── main.tsx │ │ │ └── index.css # Tailwind directives + dark theme base │ │ ├── public/ │ │ ├── index.html │ │ ├── package.json │ │ ├── vite.config.ts │ │ ├── tailwind.config.ts │ │ └── tsconfig.json │ │ │ │ --- │ │ Game Data Model │ │ │ │ Resources │ │ │ │ { compute: number, credits: number, bandwidth: number, security: number } │ │ │ │ Region │ │ │ │ { │ │ id: string, name: string, │ │ coords: [number, number], // [longitude, latitude] for map projection │ │ unlocked: boolean, │ │ dataCentreLevel: number, // 0 = no DC, 1-5 = upgrade levels │ │ bonusType: 'compute' | 'bandwidth' | 'security', │ │ bonusMultiplier: number │ │ } │ │ │ │ Upgrade │ │ │ │ { id: string, name: string, description: string, cost: number, bought: boolean, effect: () => void } │ │ │ │ Boss Event │ │ │ │ { id: string, name: string, targetRegionId: string, firewallHP: number, maxHP: number, active: boolean } │ │ │ │ --- │ │ Regions (Phase 1 — 6 regions) │ │ │ │ ┌──────┬───────────────────────┬────────────┬─────────────┐ │ │ │ ID │ Name │ Bonus │ Start state │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ na │ North America │ +Compute │ Unlocked │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ eu │ Europe │ +Security │ Locked │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ apac │ Asia Pacific │ +Bandwidth │ Locked │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ sa │ South America │ +Credits │ Locked │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ mea │ Middle East & Africa │ +Security │ Locked │ │ │ ├──────┼───────────────────────┼────────────┼─────────────┤ │ │ │ ru │ Russia / Central Asia │ +Compute │ Locked │ │ │ └──────┴───────────────────────┴────────────┴─────────────┘ │ │ │ │ --- │ │ Game Loop (useGameLoop.ts) │ │ │ │ - Tick every 100ms │ │ - Each tick: add totalCPS / 10 to compute (since 10 ticks/sec) │ │ - CPS = sum of all data centre outputs × upgrade multipliers × region bonuses │ │ - Credits generated = compute earned × conversion rate │ │ - Check for boss spawn conditions on each tick │ │ │ │ --- │ │ MVP Scope (Phase 1 — what we build now) │ │ │ │ 1. Project scaffold — Vite + React + TS + Tailwind + Zustand │ │ 2. Game loop — tick-based resource accumulation │ │ 3. Resource bar — displays Compute and Credits with formatted big numbers │ │ 4. Click button — click to earn compute manually (+1 × multiplier per click) │ │ 5. World map — react-simple-maps with 6 regions, North America unlocked │ │ 6. Data centre placement — click unlocked region → build DC (costs Credits) │ │ 7. Network overlay — SVG lines connect regions that both have DCs │ │ 8. Upgrades panel — 5 starter upgrades (better click, faster DC, etc.) │ │ 9. Region panel — sidebar showing selected region details + upgrade options │ │ 10. Dark sci-fi theme — dark bg, cyan/green accent colours │ │ │ │ Phase 2 (planned, not built yet) │ │ │ │ - Boss / firewall attack events │ │ - Melvor-style skill tracks (Training, Research, Deployment, Security) │ │ - Prestige system │ │ - Save/load (localStorage) │ │ - Sound effects │ │ │ │ --- │ │ Implementation Order │ │ │ │ 1. npm create vite → install deps (react-simple-maps, zustand, tailwind) │ │ 2. Configure Tailwind + dark theme │ │ 3. gameStore.ts + useGameLoop.ts — core resource tick │ │ 4. ResourceBar.tsx + ClickPanel.tsx — working clicker │ │ 5. regions.ts data + mapStore.ts │ │ 6. WorldMap.tsx + DataCentreMarker.tsx │ │ 7. NetworkLine.tsx overlay │ │ 8. RegionPanel.tsx sidebar │ │ 9. upgrades.ts + UpgradesPanel.tsx │ │ 10. Wire everything into App.tsx layout │ │ │ │ --- │ │ Layout │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ ResourceBar: [Compute: 1.2M] [Credits: 45K] [BW: 120] │ │ │ ├──────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌──────────────────────┐ ┌────────────┐ │ │ │ │ │ ClickPanel │ │ World Map │ │ Upgrades │ │ │ │ │ │ │ │ (react-simple-maps)│ │ Panel │ │ │ │ │ │ [CLICK ME] │ │ + DC markers │ │ │ │ │ │ │ │ │ │ + network lines │ │ │ │ │ │ │ │ CPS: 1,200 │ │ │ │ │ │ │ │ │ └─────────────┘ └──────────────────────┘ └────────────┘ │ │ │ │ └── RegionPanel (when region selected) ─┘│ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ --- │ │ Verification │ │ │ │ - npm run dev opens game in browser at localhost │ │ - Clicking the button increases Compute in ResourceBar │ │ - Idle compute accumulates per tick (verify with no clicking) │ │ - Map renders world, North America clickable/highlighted │ │ - Building a DC on NA costs Credits and starts generating Compute │ │ - Two DCs show a network line between them │ │ - Buying an upgrade changes CPS/click value visibly

First Run through - a bug:

"I've manually got some credits, but the option to build a DC does not enable"

Initial design of game

Day 2

Bosses Sounds Save/Load, Offline Market

what's Next?

Achievements / Milestones Passive tracking of lifetime stats (total compute earned, bosses defeated, prestiges done) with badge rewards — Neural Cores or compute bonuses. Low effort, high feel-good factor.
Use the unused resources bandwidth and security are tracked in the HUD but never spent. They could power:

Bandwidth → unlock inter-region trade routes or speed up building upgrades
Security → a passive "firewall rating" that reduces boss spawn frequency or dismiss penalty

More prestige depth

A second prestige layer ("Singularity") — spend accumulated Neural Cores on a meta-upgrade that persists even through multiple prestiges
Prestige challenges (e.g. "no mines run" for bonus cores)
More shop slots unlocked after N prestiges

Visual / UX polish

Floating damage/earn numbers on click and boss hits
Region unlock/build animations
Animated Neural Core counter in the header
Settings panel (reset save, export save string)

Endgame content

Boss escalation: bosses get harder each prestige, require strategy to beat
Region events: random bonuses/penalties on specific regions
A world-domination win condition (all 20 regions at max buildings)

Plug immediate gaps:

Bandwidth/Security spending — right now they pile up forever; giving players something to spend them on (e.g. spend bandwidth to overclock a region for 60s, spend security to pre-weaken the next boss) would make those resources strategic rather than passive
More upgrades — the Upgrades tab has only 5 items and goes empty fast; mid-game needs more rungs on the ladder

New progression layer:

Research tree — a second tree unlocked after the skill tree; nodes cost bandwidth or security instead of compute, giving those resources a real sink and adding late-game depth
Region synergy bonuses — reward having both a DC and a mine in the same region (e.g. +20% mine output if a DC is present), making region-building a strategic puzzle

Feel / polish:

Random events — periodic choice cards (not just bosses): "surplus cooling capacity — gain +X bandwidth" or "solar flare — lose Y compute for 30s, but gain Z security"; adds moment-to-moment interest
Animated network lines — the DC connection lines on the map are static; pulsing data-flow animations would make the world feel alive

My pick: Bandwidth/Security spending + a couple more upgrades. It directly completes the loop opened by the last two features (achievements + resource wiring), costs are already thematic, and it's scoped enough to ship cleanly in one pass.

What sounds right to you?

Lets give it a new idea:

"AI is expensive - I'd like a concept where we split credits into chips and money. You can sell compute power for money. Building a data centre needs credits. Unlocking a region needs money. It's possible to more money from a loan (but then game takes interest payments i.e. loan needs to be paid back."

Claude:

"● This is a strong design — it creates real economic tension (sell compute now for expansion vs. keep it for CPS) and makes loans a meaningful risk. Let me map it out concretely before planning implementation.

Proposed resource split:

┌──────────────────────────────┬───────────┬────────────────────────┬───────────────────────────────────┐ │ Resource │ Symbol │ Earned by │ Spent on │ ├──────────────────────────────┼───────────┼────────────────────────┼───────────────────────────────────┤ │ Chips ₵ (was Credits) │ chips │ 10% of passive compute │ Buildings, upgrades, skills │ ├──────────────────────────────┼───────────┼────────────────────────┼───────────────────────────────────┤ │ Money $ │ money │ Selling compute │ Unlocking regions, loan repayment │ ├──────────────────────────────┼───────────┼────────────────────────┼───────────────────────────────────┤ │ Compute, Bandwidth, Security │ unchanged │ unchanged │ unchanged │ └──────────────────────────────┴───────────┴────────────────────────┴───────────────────────────────────┘

Selling compute: Manual sell button — converts stored compute to money at a fixed rate (e.g. 1 compute = 0.01 money early game). Selling doesn't reduce CPS, just drains the compute pool.

Loans: Borrow a lump sum of money now; game deducts interest per second from your money income. Unpaid interest accrues as debt rather than pushing balance negative. Repay principal + accrued interest manually. "

Plan to implement:

Plan to implement │ │ │ │ Plan: Chips / Money Economy Split + Loans │ │ │ │ Context │ │ │ │ The user wants to split the single "credits" currency into two distinct resources: │ │ - Chips ₵ — earned passively from compute (same as current credits). Used for building infrastructure (DCs, mines, upgrades, │ │ skills, prestige shop). │ │ - Money $ — earned by selling compute power. Used exclusively to unlock regions. │ │ - Loans — players can borrow Money from a bank, but pay interest every tick; unpaid debt escalates penalties (higher build │ │ costs, eventually blocks region unlocking). │ │ │ │ This adds a meaningful economic tradeoff: spending compute to earn Money locks you out of passive Chips generation │ │ temporarily, and taking loans is risky if you can't service the interest. │ │ │ │ --- │ │ New Files (2) │ │ │ │ src/data/loans.ts │ │ │ │ Pure data — zero store imports. │ │ export interface LoanTier { │ │ id: string; │ │ label: string; │ │ amount: number; // $ principal │ │ interestRate: number; // fraction per second (applied to remaining balance) │ │ } │ │ │ │ export const LOAN_TIERS: LoanTier[] = [ │ │ { id: 'loan_sm', label: 'Small', amount: 500, interestRate: 0.0002 }, │ │ { id: 'loan_md', label: 'Medium', amount: 2000, interestRate: 0.0003 }, │ │ { id: 'loan_lg', label: 'Large', amount: 8000, interestRate: 0.0004 }, │ │ { id: 'loan_xl', label: 'Massive', amount: 30000, interestRate: 0.0005 }, │ │ ]; │ │ │ │ src/store/loanStore.ts │ │ │ │ Zero imports from other game stores — penalties queried via getters by consumers. │ │ interface ActiveLoan { tierId: string; remaining: number; rate: number; } │ │ │ │ interface LoanState { │ │ loans: ActiveLoan[]; │ │ debtAccrued: number; // total outstanding balance (sum of remaining) │ │ takeLoan: (tier: LoanTier) => void; │ │ repayLoan: (tierId: string, amount: number) => void; // calls spendMoney callback │ │ addDebt: (interest: number) => void; // called by gameStore.tick │ │ // Penalty getters │ │ getBuildCostMultiplier: () => number; // 1 + debtAccrued / 1000 (build cost penalty) │ │ canUnlockRegions: () => boolean; // debtAccrued < 1000 │ │ } │ │ takeLoan(tier) pushes a new ActiveLoan; money added via injected addMoney callback. │ │ repayLoan reduces remaining; removes loan when remaining <= 0. │ │ addDebt merges new interest into debtAccrued and each loan's remaining. │ │ │ │ --- │ │ Modified Files (16) │ │ │ │ src/store/gameStore.ts │ │ │ │ - Rename resources.credits → resources.chips throughout the interface + state │ │ - Add resources.money: number (init 0) │ │ - Add autoSellPercent: number (init 0; range 0–50) │ │ - Add COMPUTE_SELL_RATE = 0.5 constant (1 compute → $0.50) │ │ - Add actions: gainMoney(n), spendMoney(n) → boolean, setAutoSellPercent(n) │ │ - Add gainChips(n) (rename of gainCredits); keep gainCredits as alias or update all call sites │ │ - Modify tick(): │ │ - Auto-sell: computeToSell = totalCPS * deltaSec * autoSellPercent/100; deduct from compute gain, add computeToSell * │ │ COMPUTE_SELL_RATE to money │ │ - Interest: loanStore.loans.forEach(l => interest += l.remaining * l.rate * deltaSec); call loanStore.addDebt(interest) │ │ then spendMoney(interest) (clamped to available) │ │ - Modify buyUpgrade(): read loanStore.getBuildCostMultiplier(), multiply cost before spendChips │ │ - Rename spendCredits → spendChips; gainCredits → gainChips │ │ │ │ src/store/mapStore.ts │ │ │ │ - buildBuilding(): add loan penalty to costChips = baseCost * loanStore.getBuildCostMultiplier() │ │ - upgradeBuilding(): same penalty on upgrade cost │ │ - unlockRegion(): read loanStore.canUnlockRegions(); return early (or throw) if blocked │ │ │ │ src/store/skillStore.ts │ │ │ │ - unlockSkill(): spendCompute callback unchanged (skills cost compute not chips) ✓ │ │ │ │ src/store/prestigeStore.ts │ │ │ │ - buyPrestigeUpgrade(): spendChips instead of spendCredits │ │ │ │ src/utils/prestige.ts │ │ │ │ - doPrestige(): reset resources.chips → 0, resources.money → 0, autoSellPercent → 0; loans survive (debt intentionally │ │ persists across prestige as punishment) │ │ │ │ src/utils/persist.ts │ │ │ │ - SaveData.game.resources: change credits → chips; add money │ │ - Add loanStore save/restore: loans: ActiveLoan[], debtAccrued: number │ │ - Migration: chips = save.game.resources.chips ?? (save.game.resources as any).credits ?? 0 │ │ - Offline earnings: compute auto-sell offline (same autoSellPercent applied to offline compute) │ │ │ │ src/data/upgrades.ts │ │ │ │ - Upgrades already cost credits → rename field label to "chips" in description strings only; cost values unchanged │ │ │ │ src/components/Panels/RightPanel.tsx │ │ │ │ - No change needed (market tab already exists as 'market') │ │ │ │ src/components/Panels/MarketPanel.tsx │ │ │ │ Full overhaul — 3 inner tabs: MTRL | SELL | BANK │ │ │ │ MTRL tab (existing material buy/craft content, unchanged logic) │ │ │ │ SELL tab (new): │ │ AUTO-SELL COMPUTE │ │ [slider 0%──────50%] {value}% │ │ Selling {x} compute/s → +${y}/s │ │ │ │ MANUAL SELL │ │ [SELL 100] [SELL 1K] [SELL ALL] │ │ - Slider updates setAutoSellPercent │ │ - Manual sell: spendCompute(n) + gainMoney(n * COMPUTE_SELL_RATE) │ │ │ │ BANK tab (new): │ │ MONEY: $12,450 │ │ DEBT PENALTY: +23% build cost [warning if debtAccrued > 0] │ │ REGION LOCK: ACTIVE [warning if canUnlockRegions() = false] │ │ │ │ ACTIVE LOANS │ │ Small $480 remaining [REPAY $100] [REPAY ALL] │ │ │ │ TAKE A LOAN │ │ [Small $500] [Medium $2,000] [Large $8,000] [Massive $30,000] │ │ │ │ src/components/HUD/ResourceBar.tsx │ │ │ │ - Replace "CREDITS" item → "CHIPS ₵" showing resources.chips │ │ - Add "MONEY $" item showing resources.money with optional +$/s from auto-sell rate │ │ │ │ src/components/UI/OfflineModal.tsx │ │ │ │ - Rename "CREDITS" label → "CHIPS" │ │ - Add "MONEY" row if offline money > 0.01 │ │ │ │ src/components/Panels/AchievementsPanel.tsx + src/hooks/useAchievementChecker.ts │ │ │ │ - Update totalCreditsEarned → totalChipsEarned in AchievementContext if renaming that field (or keep as-is since it tracks │ │ total chips earned) │ │ │ │ src/components/Combat/BossAlert.tsx │ │ │ │ - gainCredits → gainChips for boss reward │ │ │ │ src/store/achievementStore.ts │ │ │ │ - Achievement rewards paying "credits" type → now pay chips: no interface change needed (reward callback is a closure) │ │ │ │ src/index.css │ │ │ │ - Add .bank-tab styles, .loan-card, .sell-tab, auto-sell slider styles │ │ - .resource-item for money (green #22c55e accent to distinguish from cyan chips) │ │ │ │ --- │ │ Rename Summary │ │ │ │ ┌─────────────────────┬──────────────────┐ │ │ │ Old │ New │ │ │ ├─────────────────────┼──────────────────┤ │ │ │ resources.credits │ resources.chips │ │ │ ├─────────────────────┼──────────────────┤ │ │ │ spendCredits() │ spendChips() │ │ │ ├─────────────────────┼──────────────────┤ │ │ │ gainCredits() │ gainChips() │ │ │ ├─────────────────────┼──────────────────┤ │ │ │ totalCreditsEarned │ totalChipsEarned │ │ │ ├─────────────────────┼──────────────────┤ │ │ │ 💳 CREDITS UI label │ ₵ CHIPS │ │ │ └─────────────────────┴──────────────────┘ │ │ │ │ --- │ │ Circular Dependency Check │ │ │ │ - loans.ts → nothing ✓ │ │ - loanStore.ts → loans.ts only ✓ │ │ - gameStore.ts → reads loanStore.getState() (same pattern as mapStore) ✓ │ │ - mapStore.ts → reads loanStore.getState() ✓ │ │ - persist.ts → adds loanStore import (same pattern) ✓ │ │ │ │ --- │ │ Verification │ │ │ │ 1. npx tsc --noEmit — zero errors │ │ 2. Start fresh → ResourceBar shows CHIPS ₵ and MONEY $ (both 0) │ │ 3. Build a DC → chips decrease; money unchanged │ │ 4. SELL tab → drag auto-sell to 10% → money ticks up; compute gain slightly reduced │ │ 5. SELL tab → click SELL ALL → compute drops to 0, money increases │ │ 6. BANK tab → take Small $500 loan → money +500, loan appears in active list │ │ 7. Watch interest tick: money slowly decreases; BANK tab shows remaining balance │ │ 8. Build cost penalty: at $500 debt accrued, building costs ~50% more │ │ 9. At $1000 debt accrued, unlock region button is greyed out / shows warning │ │ 10. Repay loan → debt drops → penalties reduce │ │ 11. Save & reload → chips, money, loans all persist correctly │ │ 12. Prestige → chips/money reset to 0; loans/debt survive

Day 3

So, next step, ask the AI where we are:

leaderboard/cloud save

Boss:

Map takeover ┌────────────────────────────────────────────┐
Persistent siege │ ╔══════════════════════════════════════╗ │

Network intercept │ ║ NETWORK INTERCEPT — APT-X9 ║ │ │ ║ You have 20s to respond ║ │ A terminal-style panel slides │ ╠══════════════════════════════════════╣ │ up from the bottom. You're │ ║ > [FLOOD ROUTE] cost: 800 BW ║ │ given a sequence of 3–5 action │ ║ > [SPOOF ID] cost: 500 SEC ║ │ choices (spend resources) │ ║ > [HARD DROP] cost: 1200 chips ║ │ within a time window to │ ║ > [IGNORE] penalty: -15% CPS ║ │ neutralise the threat. Quick │ ╚══════════════════════════════════════╝ │ and decisive, over in 20s. │ Slides up from bottom, resolves fast, │ │ no screen block. │ └────────────────────────────────────────────┘

Persistent siege │ ┌────────────────────────────────────────┐ │

Network intercept │ │ ⚠ SIEGE ACTIVE: Botnet Swarm │ │ │ │ Draining 2% chips/s │ 47s remaining │ │ Boss appears as a │ │ [RESIST: click to absorb packets] │ │ banner/ticker — doesn't block │ └────────────────────────────────────────┘ │ gameplay. It slowly corrupts │ │ your resources over time. You │ Left panel gets a resistance meter │ defeat it by clicking a │ instead of a full-screen modal. │ counter in the left panel │ Game continues completely normally. │ while continuing to build └────────────────────────────────────────────┘ normally. Notes: press n to add notes

Map takeover ┌────────────────────────────────────────────┐

Persistent siege │ ┌─────────────────────────────────┐ │
Network intercept │ │ WORLD MAP │ │ │ │ │ │ The boss infects a region — it │ │ [US] [CA] [⚠ CN INFECTED] │ │ turns hostile on the map, its │ │ ^^^^ red glow │ │ DCs go offline, and you │ │ [JP] [AU] │ │ reclaim it through the │ │ │ │ RegionPanel while the rest of │ │ ┌── INFECTED REGION ──────┐ │ │ the game keeps running. No │ │ │ ⚠ Exfiltration in 60s │ │ │ full-screen block. │ │ │ [PURGE — 500 SEC] │ │ │ │ │ │ [ISOLATE — 300 BW] │ │ │ │ │ └─────────────────────────┘ │ │ │ └─────────────────────────────────┘ │ └────────────────────────────────────────────┘

Day 4:

More content — upgrades ladder only goes to 7M chips, late game could use more; only 6 prestige shop items
Win/endgame clarity — singularity exists but no clear "you won" moment or narrative arc
Stats/run history — no way to see what happened in a run (bosses defeated, events resolved, etc.)
Achievements for new systems — Botnet/Intercept/Exfil bosses have no achievements yet
Polish — boss sounds for the 3 new boss types are missing (they use generic spawn sound)
Balance — new bosses haven't been tuned relative to each other's spawn rates

Day 5:

● Honest assessment: the core loop is feature-complete — there's a clear start, mid-game, late-game, and win condition. But "feature-complete" and "finished" aren't the same thing.

What's solid

Full progression arc: click → DCs → regions → prestige → singularity → ascension
6 distinct boss mechanics, each with unique UI
Materials, crafting, research, loans, skills — real depth at every tier
Save/load, offline earnings, achievements, run stats
Win condition with narrative arc

Where it still has gaps

Player guidance (biggest gap) The tutorial covers the first 5 minutes. Research, forge, loan system, boss mechanics, region synergy — none of these are ever explained. A new player hitting "REGION INFECTED" for the first time has no idea what to do.
Balance is unverified The upgrade ladder, prestige core formula, and singularity threshold have never been playtested end-to-end. The mid-to-late game curve (50k → 7M chips before the new upgrades) might feel like a wall or a breeze — impossible to know without real sessions.
Bandwidth and security feel inert They generate passively and get spent in combat (security) or burst mode (bandwidth) — but a player can fully win ignoring both. They need either more sinks or more visible rewards so players actually care about them.
The boss videos folder is empty public/videos/ is referenced in BossAlert for DDoS/Ransomware/APT but presumably has nothing in it, so those bosses show a black video panel.
Singularity shop is thin 6 items vs 12 prestige shop items and 20 skill/research nodes. The singularity layer — which should feel most impactful — has the least to buy.

Day 6:

Day 7

Bugs (actual correctness issues)

💳 per click is wrong — chipGain = gain * 1 in click() means clicking gives chips at a 1:1 rate, but passive generation is 6% of compute. Either the rate is intentional (and the tooltip I just added is wrong) or gain * 1 should be gain * 0.06. Worth deciding and fixing.
L7–10 colours missing in RegionPanel.tsx — we updated BuildingsListView.tsx but RegionPanel.tsx has its own duplicate colour maps that still only go to L6, so L7–10 buildings render with the fallback colour there.

UX / Clarity

No tooltip on "💳 CHIPS" vs "$ MONEY" distinction — new players don't know chips come from compute-to-chips conversion and money comes from auto-selling compute. The resource bar already has tooltips but this distinction is often the first stumbling block.
Prestige tier card chain isn't obvious visually — Tier II is greyed out as "Requires Tier I" but there's no visual arrow or numbering to show the progression sequence at a glance.
"MOVE HQ HERE" button has no cost/consequence explanation — players don't know it's free and instant, or that it removes upkeep.

Balance / Progression feel

💳 per click = ⚡ per click is very generous early — if intentional, it makes chips trivially easy to earn by clicking, which may short-circuit the early game economy.
Research unlock gate (prestige ≥ 1 AND 20 skills bought) — 20 skills costs a huge amount of compute. May be hitting this gate well after it feels relevant.

Minor visual polish

Skill node connector lines look like plain borders — adding a subtle arrow or clearer directionality would help players read the dependency tree.
Achievements panel category counts — showing "3/5" unlocked per category tab would let players know where to focus.
No visual feedback when you can't afford a prestige upgrade — the card dims but doesn't tell you how many more cores you need. A "need X more ◈" line would help.

Highest-priority fixes: #2 (actual visual bug from our L7-10 work), #1 (chips-per-click ambiguity), and #10 (prestige "need X cores" feedback) would have the most immediate impact. Want to start with those?

Resume this session with: claude --resume 65f42417-0b67-4c42-b115-a6367e431c17

18th March -

● The game is pretty feature-complete at this point. Here are some directions that would have the most impact:

Polish / Feel

More visual feedback on clicks, boss defeats, prestige
Animated numbers (floating +CPS on tick)
Better mobile layout

Content

More upgrade tiers (currently only 5 starters)
New boss mechanics or variants
More random events (only 12 now)
Additional research nodes

Depth / Endgame

A proper win condition / ending screen
More singularity shop upgrades
Cross-run meta progression beyond singularity

QoL

Statistics panel (lifetime totals, rates, graphs)
Hotkeys
Export/import save
Settings panel (speed, volume, etc.)

Technical

Cloud saves
Performance audit (the 100ms tick + multiple stores)

What's been feeling thin or missing when you play it?

So when challenged thatsome of the above alrerdy exists:

● Yeah, quite a bit already exists — StatsPanel, SettingsPanel, AscensionModal, DebugPanel. My list was sloppy.

Let me look at what's actually thin:

● Read 2 files (ctrl+o to expand)

● Yeah, much more exists than I said. The game is genuinely well-fleshed out:

Upgrades: 33 upgrades spanning early to endgame (1B chips) — solid
Settings: music toggle/volume, export/import save, hard reset — all there
Components: Stats panel, Ascension modal, Debug panel already exist

Genuine gaps I can see:

No win/end state — AscensionModal exists but unclear if it's wired up to anything
StatsPanel content — worth checking what's actually in it
Balance — given the recent balance passes, probably the most impactful thing is playtesting to find where the pacing breaks

Want me to check what's in StatsPanel and AscensionModal to see if those are actually finished?

Archiving a 2014 Fix: App-V, wisptis.exe, and a Wacom Mouse Lag Bug

2026-07-23T00:00:00+00:00

Part of keeping a record of past work is admitting that not all of it lives on your own site. Some of it ends up documented elsewhere, credited in someone else's write-up rather than your own. This is one of those.

Back in 2014, a Microsoft MVP running the blog applepie.se wrote up a nasty App-V 5 issue we'd been chasing: applications virtualized with App-V that used .NET Framework 4.5.2 (WPF, Silverlight, the SCOM/SCCM console, the App-V UI itself) would trigger severe mouse lag or a full hang whenever a tablet-input-capable device — most commonly a Wacom tablet — was connected. The culprit was wisptis.exe, the process responsible for handling pen input; killing it restored normal mouse behaviour immediately, which was the first clue.

The write-up is credited to the site's author, but the underlying diagnosis and several of the fixes trace back to troubleshooting I'd done at the time — it's referenced throughout as "thanks to Paul Richards" for both the initial diagnosis and a couple of the workarounds. Just happened - he got asked on Twitter by someone else as we'd been troubleshooting the issue. It's a good example of the kind of unglamorous, deep-in-the-registry sysadmin work that doesn't often get written up publicly, so it's worth keeping a pointer to it here as part of the record — alongside the website and intranet history already on this site.

For anyone landing here from a search for the same issue, the short version:

Symptom: mouse freezes when a WPF/.NET 4.5.2 app is launched inside an App-V 5 bubble, on a machine with a tablet-input device attached.
Root cause: App-V's handling of the process meant wisptis.exe failed to start correctly (STATUS_ELEVATION_REQUIRED), and the resulting stuck state locked up the mouse.
Workarounds explored: reverting to .NET 4.5.1, disabling the Tablet PC input service outright, overriding a specific WPF interface registry key inside the App-V package at sequencing time, and — the one Microsoft eventually confirmed — adding an ObjExclusions registry entry on the App-V client so the process wasn't tracked the way that triggered the hang.
Long-term fix: rolled into App-V 5.0 SP3.

The blunter workarounds, for reference — disabling tablet input via Group Policy:

...or disabling the underlying service outright:

And the more surgical fix — overriding the WPF tablet-detection interface inside the App-V package at sequencing time, scoped to just the virtualized app:

The full detail, including the exact registry paths and the community follow-up from other admins who hit the same thing on App-V 4.6, is on the original post.

It's a small thing to archive, but it's a fair snapshot of what a lot of education-sector IT work actually looked like a decade ago: less "modern web stack," more registry keys and process traces at midnight.

Making sense of Arbor's GraphQL API

2026-07-23T00:00:00+00:00

Making sense of Arbor's GraphQL API

Post 1 set out the idea: pull the desired state of every staff member's timetable out of Arbor, once per run, and hand it to a reconciliation stage that writes it to Outlook. That first half — "pull the desired state out of Arbor" — turned out to be most of the work. Arbor exposes a GraphQL API, and GraphQL's self-describing schema makes it feel like you can just ask for what you want. Arbor does publish API documentation and some example queries, and it's a reasonable starting point — but it doesn't go deep enough to get you to a working sync. In practice we hit five separate quirks before the query returned what we actually needed, and none of them were covered by the docs or examples. This post is those five things.

1. Calendars have no owner filter — so you can't just ask "give me this staff member's events"

The obvious query is something like "give me Staff X's calendar entries." Arbor doesn't have that. Calendar has no filter by owner, and the only way to reach a staff member's calendars at all is a nested field: Staff.calendarEntryMappings. Every staff member owns two calendars — School and My Lessons — and this nested field is the union of both.

So calendar-id discovery becomes its own step, separate from fetching events:

{ Staff(id_in: [123, 456]) { staffId calendarEntryMappings { calendar { id } } } }

Harvest the calendar ids per staff member, then fetch actual events by calendar id, not staff id.

2. That same nested field only sees the current academic year

Here's the field-level gotcha that cost us the most time: Staff.calendarEntryMappings takes no date arguments, and it only ever returns entries from the current academic year. In July, staff whose September timetable is already published in Arbor show up with no autumn-term entries via this field at all.

The fix is that Arbor also exposes CalendarEntryMapping as a top-level query, and that version takes real filters:

{
  CalendarEntryMapping(
    calendar__id_in: [123, 456]
    startDatetime_after_or_equal: "2026-09-01 00:00:00"
    startDatetime_before: "2026-09-08 00:00:00"
    page_size: 200
    page_num: 0
  ) {
    startDatetime
    endDatetime
    eventDisplayName
    calendar { id }
    event { __typename }
  }
}

This one respects date ranges and happily returns next year's published timetable. So the nested field is only used for step 1 (discovering calendar ids); every actual event comes from the top-level query. Two different fields, same underlying data, very different date behaviour — nothing in the schema signals this, you find it by trying both.

3. "Current staff" doesn't mean what you'd think

Staff(currentStaff: true) sounds like the right filter for "who do we sync." It isn't complete: staff who've been entered into Arbor ahead of their start date (new September hires added over the summer) are neither currentStaff: true nor false — they're excluded from both. There's no server-side filter on joiningDate/leavingDate either.

The workaround is a second, broader pass: page through externalStaff: false (the widest catch-all we found), and client-side keep anyone whose joiningDate falls on or before the end of the sync window and who has no leavingDate — merged in with the currentStaff: true set. Two full paginated queries just to get a correct staff list, because there's no single filter that means "will be relevant during this sync window."

4. New starters break calendar-id discovery too — which needs its own fallback

Combine points 1 and 3: a staff member who joins in September has no current-year calendar entries yet, so the nested Staff.calendarEntryMappings field (our only route to their calendar ids) returns nothing for them. They're invisible to discovery even though they're correctly in the staff list.

There's no staff filter on the top-level CalendarEntryMapping query either, so we can't just ask it directly. The fallback: page through the unfiltered top-level query over a short, bounded window — about two weeks from each missing staff member's joining date — and attribute rows back to a person via the mapped union field, which resolves to Staff { staffId } when a row belongs to a calendar owned by staff:

{
  CalendarEntryMapping(
    startDatetime_after_or_equal: "2026-09-01 00:00:00"
    startDatetime_before: "2026-09-15 00:00:00"
    page_size: 200
    page_num: 0
  ) {
    calendar { id }
    mapped { __typename ... on Staff { staffId } }
  }
}

This only works because it's bounded to ~2 weeks per missing person; unfiltered over a whole term would mean paging through a school's entire calendar (rooms, sessions, everything) just to find a handful of new starters. Anyone still unresolved after the probe gets reported on the console rather than silently dropped.

5. A 400 response isn't necessarily a failure

Arbor returns field-level authorization errors — HTTP 400, GraphQL errors array populated — whenever the event union in a query resolves to a type the API credential isn't allowed to read (e.g. StaffAbsence details a timetable-sync account has no business seeing). Critically, the response still carries the rest of the data: title and times for the denied event, just no location.

Treating any non-2xx or any populated errors array as fatal would mean the whole sync throws on the first restricted event type. Instead:

$nonAuth = @($errors | Where-Object { $_.extensions.category -ne 'authorization' })
if ($response.data -and $nonAuth.Count -eq 0) {
  # only authorization errors, and we still got data - summarise and continue
}

Anything that isn't an authorization-category error is still treated as fatal. 429/500/502/503/504 get a separate path: exponential backoff and retry, up to four attempts, before giving up.

The smaller stuff

A few more things that only surface once you're actually calling the API:

page_num is 0-based, unlike the 1-based pagination you'd instinctively reach for.
The free tier caps page_size at 500 and rate-limits at 100 requests per school per minute — we track a sliding 60-second window client-side and throttle at 90, leaving headroom for retries and anything else hitting the same school.
Not every event type in the union exposes locationDisplayName — figuring out which ones do meant introspecting the schema, since there's no field list to read anywhere.
Every raw request and response gets dumped to a debug folder, wiped and rebuilt each run. Once we hit our second or third undocumented edge case, "read the last run's actual wire traffic" became faster than guessing from the schema.

None of this is exotic — it's the ordinary experience of integrating with a GraphQL API that has a schema and some docs, but no guide for the specific query shapes a given use case needs. The schema and the docs tell you what's possible; neither tells you that the field you'd naturally reach for only covers the current academic year, or that "current" staff excludes people who are, for every practical purpose, current.

Next up: post 3, on the other side of the pipeline — how the reconciliation engine turns this data into safe, idempotent writes against Microsoft Graph.

Building a calendar sync you can trust to run unattended

2026-07-23T00:00:00+00:00

Building a calendar sync you can trust to run unattended

Post 1 set the bar for this tool: it has to be safe to run on a schedule, forever, without anyone watching it. Post 2 covered getting the data out of Arbor. This post is stage 2 — Sync-OutlookCalendars.ps1 and the TimetableSync module — turning events.json into writes against Microsoft Graph without ever touching an event it doesn't own.

Owning only what you created

The entire safety model rests on one thing: every event this tool creates carries an open extension named timetable-calendar-generator. When it reads a mailbox back, it filters for exactly that:

start/dateTime gt '...' and start/dateTime lt '...' and extensions/any(f:f/id eq 'timetable-calendar-generator')

Nothing outside that filter — a user's own meeting, a lunch reservation, an event from before the sync window — is ever in scope for deletion. The tool literally cannot see it. This is what makes "reconcile against desired state" safe instead of terrifying: the blast radius is bounded to the tool's own tagged events, inside the sync window, full stop.

The diff key

Reconciliation needs a way to say "is this desired event already present." A naive approach — comparing full event objects — makes trivial differences (someone retitles an event, whitespace changes) look like a delete-and-recreate every night. Instead, each event reduces to a key:

"$title|$start|$end|$location"

with one deliberate wrinkle: the title is truncated at the first -. Arbor titles like Maths: Y10Ma/1 can pick up manual suffixes after a dash, and those shouldn't cause the tool to think the event changed. Two full snapshots — what Arbor says should exist, what's currently tagged in the mailbox — get reduced to sets of these keys, and the diff is just set arithmetic: keys desired but absent get added, keys present but not desired get deleted, everything else is left alone.

Duplicate keys are handled the same way in both directions: for desired events, a Group-Object on the key keeps only the first (a defensive de-dupe on Arbor's side); for existing events, if a key has more than one tagged event, every copy past the first is queued for deletion. That's what cleans up duplicates from the next quirk.

Categories and reminders come from the title, not from Arbor

Arbor doesn't tell you "this is a duty" versus "this is a lesson" versus "this is a meeting" in a structured field — that distinction lives in how the event is titled. So category assignment is keyword matching against the title (duty, duties → Duty; meet, line management, brief, mentor, lmm, review, planning, discuss → Meeting; everything else → Timetable), with a reminder switched on specifically for duty events. The three master categories (Timetable/preset2, Duty/preset10, Meeting/preset4) get created on a mailbox the first time the tool touches it, if they're not already there.

This is inherently a bit fragile — it only works as well as the school's own timetable naming conventions — but it means zero configuration per event type, and it matches the categorisation scheme staff were already used to from makecal.

Batching and the 503-that-isn't-a-failure

Writes go through Microsoft Graph's $batch endpoint, four requests per batch — that's the concurrency limit per mailbox, not an arbitrary tuning choice. Batch requests get the same exponential-backoff retry as reads, and honour a Retry-After header when Graph sends one.

One specific failure mode drove the shape of the whole sync loop: Graph sometimes returns a 503 for an event creation that actually succeeded anyway. Retrying a "failed" request that wasn't really a failure means the event gets created twice. Rather than trying to make error handling smart enough to detect this in the moment (there isn't a reliable signal for it), the fix is structural: the whole read-diff-write cycle runs as a loop, up to five passes, and only stops early once a pass finds nothing left to add. A duplicate created by a false 503 on pass 1 simply gets caught by the diff on pass 2 and deleted. The same idea handles DELETE calls that 404 — Graph's eventual consistency can show an event as still existing on a pass after an earlier delete already removed it, so a 404 on delete is treated as success, not an error, since the desired end state (event gone) is already true.

Idempotency as the actual test

None of the above matters if running the sync twice in a row does anything at all. That's the property the whole design optimises for, and it's also the simplest possible test: run it, run it again, and the second run should report zero adds and zero deletes. If it doesn't, something in the key derivation or the tagging is wrong — and that's a much easier bug to reason about than "why did this user's calendar end up with a duplicate event."

Parallel, but no differently

25 mailboxes sync concurrently (ForEach-Object -Parallel, each runspace with its own Graph connection), because doing users one at a time against a tenant with a few hundred staff would take too long to run nightly. But it's parallel users, not parallel logic — each mailbox goes through exactly the same read-diff-write- retry cycle described above, independently. Concurrency is a property of the outer loop, not something the reconciliation logic has to know about.

Watching it work

-ShowChanges prints only the add/delete lines per mailbox — what actually moved — and -ShowEvents prints everything, including the events left untouched, which is the fastest way to convince yourself (or a colleague) that the tool really is leaving unrelated events alone. Both were built for exactly the kind of trust-but- verify checking this series has been about: not "does the code look right," but "can I watch it, on a real mailbox, and confirm it only ever touches what it's supposed to."

That's the three-part shape of this project: an idea borrowed from prior art (post 1), a data source that took real digging to use correctly (post 2), and a reconciliation engine whose entire design is in service of one property — safe to run unattended, forever.

The full source — Get-ArborTimetable.ps1, Sync-OutlookCalendars.ps1, and the TimetableSync module — is up on GitHub at REPO_NAME, MIT licensed. Issues and PRs welcome, especially from anyone hitting Arbor quirks we haven't.

Your timetable is in the wrong app

2026-07-23T00:00:00+00:00

Your timetable is in the wrong app

Every school running a MIS has the same quiet problem: the timetable — the thing that tells a member of staff where to be, when, and with which class — lives in a system that people only open to do MIS things. Register a class. Log a behaviour point. Check a report. It's not the tool anyone has open at 8:55am when they're trying to remember if period 3 moved rooms because of the mocks.

The tool people actually have open is their calendar. So the idea is simple to state: every lesson, duty, and meeting a staff member has should show up as an event in their Outlook calendar, automatically, kept in sync with the MIS, without anyone re-typing anything.

Simple to state. Less simple to do safely — because a calendar sync that gets it wrong doesn't fail quietly. It double-books someone, deletes an event they added themselves, or leaves stale entries for a lesson that got moved. Whatever we built had to be something we'd trust to run unattended, every night, indefinitely.

We didn't start from a blank page

This idea isn't ours. timetable-calendar-generator by James Gurung has been doing exactly this for schools running SIMS for a while, and it's the reason we didn't have to work out the hard part from scratch. The piece of design worth stealing wasn't "call an API and make some events" — it's how it stays safe to run on a schedule forever:

Desired-state, not deltas. Each run computes the full set of events that should exist for a user in the sync window, rather than trying to track what changed since last time. That sidesteps an entire category of bugs where a missed run or a crash leaves things half-applied.
Only touch what you own. Every event the tool creates is tagged. On the next run, it reconciles only the tagged events against the desired state — add what's missing, remove what's tagged but no longer listed, leave everything else (a user's own meetings, anything outside the window) completely alone.
Idempotent by construction. Because of the two points above, running the sync twice in a row is a no-op. That's what makes "just run it every night" a reasonable operational model instead of a leap of faith.

That's the actual idea this series is about. Everything else — which MIS, which language, which API — is implementation detail.

Except the details didn't line up

We're not a SIMS school; we're an Arbor one. Arbor's API is a GraphQL endpoint, not SIMS', with its own set of quirks we had to learn the hard way — that's post 2. So the sync logic needed rebuilding against a different data source regardless.

Given that, we also changed the implementation language: PowerShell instead of C#. Not because C# did anything wrong, but because of who has to maintain this in five years. A school IT team already lives in PowerShell — it's what provisions AD accounts, runs scheduled maintenance, talks to Microsoft Graph. There's no build step, no project to open, no framework version to keep current. Anyone on the team can open the script, read it top to bottom, and change a line. For a small tool that has to outlive whoever wrote it, that maintainability matters more than any performance or ergonomics C# would have offered.

What we built

Two stages, matching the model above:

Pull the desired state from Arbor — every current staff member's lessons, duties, and meetings for the sync window — into a plain JSON file.
Reconcile each Outlook calendar against that file: tagged events not in the file get deleted, missing ones get added, everything else is untouched.

Running stage 2 twice back to back changes nothing. Running it every night, indefinitely, is exactly the plan.

The next two posts go into how each stage actually works: making sense of Arbor's GraphQL API and its rougher edges — rate limits, fields that only ever return the current academic year, staff filters that don't mean what they say — and then the reconciliation engine itself: the diffing, the tagging, the parallel writes to Microsoft Graph, and the edge cases that only show up once real staff data hits it.

Building My New Website with Zola — Keeping It Simple

2026-07-23T00:00:00+00:00

For small to medium sized web development, people are increasingly reaching for Squarespace-type builders, or WordPress with an Elementor-type visual builder. These solutions aren't necessarily the most suitable, for a few key reasons:

You don't own your data with some of the online builders — so you're at their mercy when it comes to pricing.
WordPress can easily be abused with bloated visual builders and too many plugins. This creates performance problems, opens up security issues, and makes keeping the site up to date a major feat. Within the education space, outdated WordPress instances and plugins have been highlighted as a particular concern in 2024.

A small to medium sized digital presence needs to offer the following:

Data Ownership — You should be able to both shape your data and own it.
Durability — A website should be long-lasting, stable and easy to maintain. It shouldn't break constantly because a handful of third-party plugins are conflicting or need constant updates. It should just work, and be kept up to date with simple, occasional maintenance.
Ease of Use — A competent developer or designer should be able to set up the design, hosting, and maintenance. The end user should be able to focus purely on the content: add a new blog post weekly, update a staff member's title, swap out a photo, add an event, and so on.

A bit of history

Since the late 1990s I've had the opportunity to develop a number of websites and intranets within the education space where I've worked:

School intranet — 1997/1998 (not sure I've still got any screenshots of this one)
University project — 2001 — University Project Report
School website — Microsoft FrontPage — 2000–2003
School website — PHP — 2004/2005
School intranet — 2001–2013
School website — ASP.NET — ~2006–2011
School intranet — ASP.NET, Home Access Plus — patches contributed 2013–2014, in use until 2022
School website — PHP, Grav — 2015–2021

Between 2000 and 2013 the focus was always on building something with an integrated database. By 2015 I'd started thinking about static site generators — Grav was (and still is) great to use, but it was never quite what I wanted.

None of these were built on WordPress, so this isn't a "migration" story — it's more that WordPress and its site-builder relatives are the default a lot of people reach for, and I wanted to set out why I've gone a different way for this new site.

Keeping it simple

It's a great time to be a web developer, but I've been looking for a way to "keep it simple." This blog post on moving from WordPress to Astro makes a similar case for a static build. For this new site, after weighing up a few options, I've settled on Zola.

I initially looked A CMS Layer( see "Too many options" ) then looked at Hugo with Hugo Blox, but landed on Zola instead: it's a single self-contained binary (no Node/npm toolchain to babysit), has Sass compilation and asset processing built in, and its templating (Tera) is straightforward to pick up. Content lives as plain Markdown files in the repo — no CMS layer, no database, no admin panel to secure or update. Just files, git, and a build step.

The plan

The aim of this series of posts is to document building this new site from scratch, and to use the experience as a research exercise for evaluating Zola as a solid setup for other projects too — including, potentially, sites at the school trust I work for.

Set up the new site with Zola, managing all content as Markdown.
Build out a theme using Tailwind CSS.
Publish the site statically via Cloudflare.
Use the build as a proof of concept for:
1. Defining a clean content structure/schema for a small site.
2. Keeping the whole workflow git-based, with no CMS or database dependency.
Prove out ease of use and speed of development within a modern stack — can the above be achieved within 4–5 days?

Useful Links

2026-07-23T00:00:00+00:00

About

2026-07-22T00:00:00+00:00

Who am I?

My name is Paul Richards, based in London. I'm a Network Manager with over 20 years' experience managing school server, network, and client infrastructure, MIS/timetabling systems, and IT support teams — currently at North Star Community Trust.

What I do

I work with the Microsoft ecosystem — Power Platform (Power Apps, Power Automate, Copilot Studio), Microsoft 365, and IT infrastructure automation. Over the years I've built things like help desk systems, school timetable/calendar sync tools, and security hardening checks, alongside smaller scripts and utilities.

What's on this site

This is my personal corner of the web, covering three things I care about:

Photos — travel shots from places I've visited
Code — notes and projects from my development work, mostly around Microsoft/Power Platform tooling and general programming
Microsoft tips — practical tricks and lessons learned from working day-to-day with Microsoft 365, Power Platform, and Windows

Get in touch

You can find me on GitHub and LinkedIn, or via the contact page.

Contact

2026-07-22T00:00:00+00:00

Get in touch

Feel free to reach out via email at paul@minimoo.org, or via GitHub or LinkedIn.

Resume / Portfolio

2026-07-22T00:00:00+00:00

Too Many Options: Picking a CMS and Learning When to Stop Looking

2026-07-20T00:00:00+00:00

Most of my CMS experience comes from an older world: PHP and ASP.NET systems with a database sitting behind an admin panel. For this round, I wanted to look forward rather than back — modern static site generators, paired with a CMS built around JavaScript/Node or Go, rather than reaching for what I already knew.

What followed was a genuinely useful evaluation. It was also, if I'm honest, a bit of a rabbit hole.

What I looked at

Keystatic

Keystatic bills itself as a tool that makes Markdown, JSON and YAML content in your codebase editable by humans.

A few things stood out:

You can define both collections (repeating content, like blog posts) and singletons (one-off pages, like a homepage or settings file).
With a bit of cleverness in the config, you can approximate a block-builder-style editing experience for more flexible page layouts.

The catch, in testing against a larger dataset: with around 2,500 blog posts in a collection, Keystatic was pulling roughly 15MB from the server just to populate the admin UI. Workable for a small site, but worth knowing about before committing to it for anything with real scale.

Decap CMS

Decap CMS — the project formerly known as Netlify CMS — pitches itself as usable with any static site generator, for a faster and more flexible web project.

It's the most established option here: git-based, generator-agnostic, and with years of production use behind it. That maturity is reassuring, though the project's development pace has visibly slowed compared to some of the newer alternatives.

Sveltia CMS

Sveltia CMS is a newer, from-scratch reimplementation aimed squarely at Decap's config format — so it's largely a drop-in replacement — but with a modern rebuild under the hood and a noticeably snappier editing experience.

Gatsby + Decap CMS

Rounding things out, I also looked at a Gatsby front end paired with Decap CMS — a combination that was extremely common a few years ago and is still floating around in plenty of tutorials and starter templates.

The actual problem

None of the above is a bad option. That's precisely what made this hard.

Four viable tools, each with a slightly different trade-off — data footprint, maturity, speed, ecosystem — and each perfectly capable of doing the job. Add in the generators they can pair with, the themes, the hosting choices, and the total number of "reasonable" combinations balloons fast. At some point the research stops being research and starts being a way of avoiding a decision.

Barry Schwartz wrote about this in The Paradox of Choice: more options don't reliably make us happier with our eventual choice — past a certain point, they make us less confident in it, because there's always another combination we haven't checked yet. Software tooling has the same trap, just dressed up as diligence. Reading one more comparison post feels like progress. Often it's just a well-disguised form of procrastination.

There's a useful distinction from that same research between maximisers, who try to evaluate every option to find the objectively best one, and satisficers, who define what "good enough" looks like and stop once something clears that bar. Maximisers tend to spend far more time deciding and end up less satisfied with the result, because they can never fully rule out that something better exists. For a solo project with a deadline, satisficing isn't a compromise — it's the correct strategy.

Breaking the loop

A few things that actually helped move this from "still evaluating" to "decided":

Write down the must-haves first, before the options. Markdown/JSON/YAML source of truth, git-based workflow, reasonable editing experience, no database to maintain. Anything meeting all of those is a candidate; everything else is noise.
Set a decision deadline. Not "when I'm sure," but a date. Certainty rarely arrives — you just run out of time to keep second-guessing.
Accept that "good enough, shipped" beats "perfect, still in a spreadsheet." A CMS that's live and being used teaches you far more than another week of feature comparisons.
Write down why, not just what. The reasoning is what lets you revisit the decision sensibly later, rather than relitigating it from scratch.
Treat the choice as reversible. Content in Markdown, in git, isn't locked into any one tool. Picking "wrong" mostly costs a migration, not a rebuild.

Where I landed

For this site specifically, the honest answer turned out to be: no CMS at all. Content lives as plain Markdown files, edited directly, with Zola handling the build. It's the smallest possible surface area, and it satisfies every one of the must-haves above without adding a dependency.

That's not a verdict on Keystatic, Decap or Sveltia — all three remain solid choices, and I'd reach for Decap or Sveltia without hesitation on a project where non-technical editors need a proper admin UI. It's simply a reminder that the best tool is the one that matches the actual job in front of you, not the one that wins the most comparison points on paper. Sometimes the most productive outcome of an evaluation is realising you didn't need the extra layer in the first place.

Adding audio to your blog

2026-02-11T00:00:00+00:00

There are two practical ways to add audio to a blog: use the native <audio> element or render a custom player with JavaScript. The Zola theme Zolarwind provides two shortcodes that map to those choices: audio_simple uses the native element, audio uses a custom player. Both are usable as-is, and the choice comes down to how much control you want over the player UI.

The baseline native `<audio>`

You get built-in controls and good accessibility. If you are fine with browser-native styling, this is the fastest path.

<audio controls>
  <source src="audio.mp3" type="audio/mpeg">
</audio>

The tradeoff is consistency. Browsers style the element differently, and you get limited control over the UI.

`audio_simple` shortcode

This wraps the native element and keeps the setup small. It uses no JavaScript, like the baseline audio element, but adds a small amount of CSS for layout.

<div class="container max-w-md my-6 py-6 px-6 text-black dark:text-black bg-gradient-to-tr from-ok-600 to-primary-800 rounded-2xl overflow-hidden">
    <div class="text-center relative">
        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="h-16 w-16 inline-block">
            <path stroke-linecap="round" stroke-linejoin="round" d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z" />
        </svg>
    </div>
    <div class="mb-6 text-center relative">
        <h2 class="inline-block font-medium">Audio in your blog</h2>
        <p class="inline-block font-medium text-sm">Female Speaker | Blog of Thomas Weitzel | 2026</p>
    </div>
    <audio controls src="audio.mp3" style="width: 100%">Your browser does not support the audio element.</audio>
</div>

Audio in your blog

Female Speaker | Blog of Thomas Weitzel | 2026

Your browser does not support the audio element.

Custom player

If you want a consistent player UI across browsers, the audio shortcode renders a custom player with JavaScript. The native <audio> controls are not used; the UI is fully custom.

<div
  class="container max-w-md my-6 py-6 px-6 text-black dark:text-black bg-gradient-to-tr from-primary-600 to-warn-800 rounded-2xl overflow-hidden"
  data-audio-id="1"
  data-audio-src="audio.mp3"
>
    <div class="text-center relative">
        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="h-16 w-16 inline-block">
            <path stroke-linecap="round" stroke-linejoin="round" d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z" />
        </svg>
    </div>
    <div class="mb-6 text-center relative">
        <h2 class="inline-block font-medium">Audio in your blog</h2>
        <p class="inline-block font-medium text-sm">Female Speaker | Blog of Thomas Weitzel | 2026</p>
    </div>
    <div class="audio-controls1 flex space-x-1">
        <div class="play-div1 flex-none hover:text-fail-600">Loading ...</div>
        <div class="time-div1 flex-none pr-2">00:00 | 0:48</div>
        <div class="flex-auto cursor-pointer select-none mt-2">
            <div class="progress-container1 w-full bg-primary-700 rounded-full h-2 dark:bg-neutral-200">
                <div class="progress-bar1 bg-neutral-800 h-2 rounded-full hover:bg-fail-600" style="width: 0%"></div>
            </div>
        </div>
        <div class="speaker-div1 flex-none pl-2 hover:text-fail-600"></div>
    </div><script src="/js/audio/howler.js" integrity="sha384-B3AhJtVepaXjzRprLH6ZMkrOI+XDduqXmwhe4m+RDATUkM8o1I2STFsig6dra4XF"></script>
        <script src="/js/audio/audio-player.js" integrity="sha384-uM+RjXS/SiYym8NXLgoHFdNXVU0dZFjg9FyWhppQgkb0RJd1dnp7H+Pom5azyaMI"></script>
        <script src="/js/audio/audio-init.js" integrity="sha384-MxFc2CYeIiCM4XDzrORmIy9R06BD/FQLTHq71ZIlTY/tJCqi3Isa8/o+yKSFg1Vc"></script></div>

Audio in your blog

Female Speaker | Blog of Thomas Weitzel | 2026

Loading ...

00:00 | 0:48

I prefer the audio shortcode, because I want a stable player UI across browsers. audio_simple stays in the toolbox because it keeps the setup small and uses no extra JavaScript.

Notes

The shortcodes expect local assets, not remote URLs.
zola serve does not support range requests as of 0.22.1, so Chrome cannot seek properly. Use a static server for testing.

Search

2026-01-14T00:00:00+00:00

Diagrams with Mermaid

2023-10-29T00:00:00+00:00

What are Mermaid diagrams?

Mermaid is a syntax similar to Markdown where you can use text to describe and automatically generate diagrams. With Mermaid, you can generate Flow charts, UML diagrams, Pie charts, Gantt diagrams, Entity Relationship diagrams, and more.

An Entity Relationship diagram example

  
    %%{ init: {'theme': 'forest'} }%%
  
  
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }

Using Mermaid in your blog post

The diagram shortcode allows you to easily embed Mermaid diagrams in your blog posts, with an option to configure its appearance.

Basic Usage

To use the shortcode in your blog post, you would use the following format:


{% <diagram> %}
Your Mermaid diagram code here
{% </diagram> %}

Replace Your Mermaid diagram code here with your actual Mermaid diagram code.

To load the necessary JavaScript to render the Mermaid diagram, you need to enable it in the front matter of your blog post by setting the value for extra.diagram to true:

+++
[extra]
diagram = true
+++

Configuring the Appearance

The shortcode supports an optional init parameter that allows you to specify configuration options for Mermaid, particularly changing the appearance of the diagrams through the theme.

For example, to apply the forest theme:


{% <diagram init="{'theme': 'forest'}"> %}
Your Mermaid diagram code here
{% </diagram> %}

Providing init Configuration

When using the init parameter, the configuration should be a string wrapped in double quotes. Inside this string, use single quotes for keys and values.

Here's a more advanced example with multiple configuration options:


{% <diagram init="{'theme': 'forest', 'themeVariables': {'primaryColor': '#FF0000'}}"> %}
Your Mermaid diagram code here
{% </diagram> %}

In this example, we're using the forest theme and changing the primary color to red (#FF0000).

Note: Ensure that you use single quotes inside the double quotes for the configuration to work correctly.

Putting it all together

Use the shortcode by enclosing your Mermaid diagram code with it. To change the look of the Mermaid theme, provide values for the init parameter. Always enclose the init value with double quotes, and use single quotes inside the configuration string. With this shortcode in place, integrating and customizing Mermaid diagrams in your blog posts becomes easy.

Explaining Mermaid diagram code

Here is how the diagram rendered above is embedded in this blog post as a code block. Because it is the same code as the diagram above, extra care has to be taken to prevent Mermaid from rendering it as a diagram. Wrap it in Tera's raw block in the code block, so the code stays visible but is not executed.


{% <diagram init="{'theme': 'forest'}"> %}
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }
{% </diagram> %}

Notes from Studying for the Professional ChromeOS Administrator Exam

2023-09-15T00:00:00+00:00

I sat Google's Professional ChromeOS Administrator certification in 2023. What follows started life as a scrappy set of study notes from that prep — a mix of things I'd worked out myself, things pulled from Google's own documentation, and pointers to a handful of genuinely useful YouTube walkthroughs. I've tidied them up here, roughly following the exam's own structure, partly so future-me has a cleaner reference, and partly on the off chance it's useful to anyone else sitting the same exam.

Section 1: Admin console actions

Troubleshooting and day-to-day admin tasks

The bread-and-butter admin actions all live in fairly predictable places once you know where to look:

Wiping devices: Devices → Chrome → Devices or Devices → Overview → Mobile and Endpoints.
Collecting device logs: pulled from the device itself.
Raising tickets: the question-mark icon, top right of the console.
Connectivity issues: Devices → Networks.
First-time user login problems: usually comes down to Organisational Unit and user setup — Users → Manage Organisational Units / Add New User.
Manually checking for updates: Devices → Chrome → Reports → Versions.
Feature requests: the main menu's "Send Feedback" option.

Worth knowing about even if you never use them directly: the Trusted Tester Program, and the fact that partners are informed of release notes separately from the standard release channel.

For actual escalation to Google support: the support/help icon top-right, or support.google.com/chrome/a → "Contact us" → hardware, software/services, or troubleshooting. If self-service doesn't resolve it, "This didn't help, continue to support" gives you a phone option — you get a PIN valid for 60 minutes to call Google directly.

Update channels and rollout

This is a section worth knowing cold, since it comes up in scenario questions a lot.

Update settings live under Devices → Chrome → Settings (on a child OU) → Device Update Settings → Auto Update Settings.

Channels: Stable, Beta, Long Term Support, Long Term Support Candidate, Dev.
Rollout schedule options:
- Default — devices update as soon as a new version is available.
- Scatter updates — useful for bandwidth-constrained fleets; spreads updates over up to two weeks.
- Schedule — a staged rollout: update X% after Y days, then 100% after a further period.
Blackout windows stop automatic updates during specified times (manual updates are still possible).
Auto-reboot behaviour differs by session type: kiosk devices restart automatically after an update; user/managed guest sessions restart after the user's next sign-out. Both are configurable.
A good chunk of a typical fleet — 5% is the figure to remember — should sit on the Beta channel, to catch problems before they hit Stable.

One easy-to-miss detail: to stop an update being applied before a device is even enrolled, press Ctrl+Alt+E on the End User License Agreement screen. Skip this and a downloaded update that should have been blocked by policy can still apply itself on next restart.

For diagnostics: the Log Analyzer tool, network logs at /var/log (accessible via file:///var/log), and chrome://network for live inspection. Requesting exported logs needs the Export Logs Action admin privilege specifically.

Wiping, deprovisioning and disabling — know the difference

These three get confused easily, and the exam leans on the distinction:

Action	What it does
Clear user profiles	Removes user profile data, keeps device policy and enrollment
Factory reset	Wipes everything, returns to factory state — unless the device is subject to automatic re-enrollment
Deprovision	Can be with or without a factory reset; requires a reason (e.g. retiring from fleet, ChromeOS Flex upgrade)
Disable	Locks the device with a lock screen, optionally with factory reset

On-device, a factory reset is Ctrl+Alt+Shift+R, then Restart → Powerwash → Continue. From the Esc + Refresh + Power recovery screen you can also recover via internet connection, or press Ctrl+D to enter developer mode (blocked if forced re-enrollment is set). On tablets, the equivalent is volume up + volume down + power.

Setting up a trial

Trials hinge on domain verification: Home → Domains → Manage Domains → Add Domain, then verify ownership — either linking through your DNS provider directly, or adding a TXT record (google-site-verification). Verification can take up to 12 hours, and every user on the domain gets a notification email once it completes.

Before verification, the Chrome devices tile in the admin console sits greyed out. Once verified, the setup wizard walks you through DNS-provider-specific instructions, the tile unlocks, and you get access to Google support proper.

Pushing applications

This is another heavily-tested area — pay close attention to which method a question specifies (Chrome Web Store, Google Play Store, or App ID), and to any mention of installation policy or version pinning.

Application settings live under Devices → Chrome → Apps and Extensions, and apply to whichever OU you're configuring.

Chrome extensions: add from the Chrome Web Store. Default policy is "allow installation"; you can also force-install, or force-install and pin to the shelf.
Android apps: added via Google Play. Only apps approved in Play are available, same installation options apply, and there's a JSON configuration option for pre-setting app config.
Progressive Web Apps: added by URL, which unlocks PWA features like real-time notifications and offline access, and can open in its own window for an app-like feel.
OU-level policy: "Allow users to install other apps and extensions" can be set to allow all, Play only, Chrome only, or block all others.
Advanced settings (gear icon): granular allow/block per app, and permission-based blocking of extensions — e.g. blocking anything that requests video capture.

Device actions and licensing

Most per-device actions (gathering logs, deprovisioning, moving OU, remote desktop, screenshots, resetting profiles) live under Devices → Chrome → Devices → [select device]. Zero-Touch Enrollment tokens come from the same area, scoped to an OU: generate a 30-character pre-provisioning token, which you can copy, revoke, or regenerate. Devices show as "pre-provisioned" until they check in. ZTE itself needs a capable device, an approved manufacturer that's pre-enrolled it, and a partner relationship.

On licensing, the distinction that matters is:

Bundled/perpetual license — tied to the device for its lifetime, non-transferable.
Chrome Education Upgrade — purchased separately, transferable to another device of the same model.
Annual licenses — bought per term (e.g. for kiosk/signage use), also transferable.

Devices must be enrolled before anyone signs in — if that's missed, the only fix is wiping and restarting enrollment. A summary of assigned vs. purchased licenses lives under Devices → Chrome → Devices → Upgrades.

Admin roles

Custom roles are created under Accounts → Admin Roles, then applied to a user via Users → [select user] → Admin Roles and Privileges → Assign roles. Roles can be scoped to a specific OU — with one important exception: the support ticket privilege is organisation-wide and can't be OU-scoped. Don't mix OU-scoped and organisation-wide permissions on the same custom role.

Super Admin is a separate tier entirely: full access to everything, must be a native Google identity (not usable with SSO), and best practice is to create super admin accounts with distinct UPNs from everyday admin accounts. Certain actions — billing, accepting terms and conditions — require super admin specifically.

Section 2: Security processes

Certificates and VPN

Certificate deployment lives under Devices → Networks → Certificates. For automatic user/device certificate provisioning via SCEP (Simple Certificate Enrollment Protocol): select the OU, upload a certificate authority, then create a SCEP profile — profile name, fully distinguished name, common name (${USER_EMAIL}), subject alternative name, SCEP server URL, extended key usage (client and/or server authentication), and usually a static challenge.

Wiring that certificate into a Wi-Fi network: create the network under Devices → Networks, choose 802.1X with EAP-TLS, set the username field to ${LOGIN_ID}, and select the SCEP profile and root cert you just created.

Android VPN requires the "Advanced" tier of mobile management (toggled under Mobiles and Endpoints → Settings → Universal), and requires users to install an app to use it.

Core security tenets

A few things worth internalising rather than memorising as menu paths:

No antivirus needed — every page and app runs sandboxed.
Verified boot — every startup runs an integrity self-check; if tampering or corruption is detected, ChromeOS attempts to repair and restore itself automatically.
Client-side encryption settings live under Security → Access and Data Control.
Forced re-enrollment and Verified Access both sit under Devices → Chrome → Settings → Device.

Section 3: ChromeOS policies

Enrollment permissions are set through Chrome user/browser policies rather than an admin privilege as such: Users → [user] → Chrome User Policies → Devices → User and Browser Settings, then search "Enrollment." From there you can force devices into a specific enrollment OU, or lock enrollment down entirely at the top-level OU.

The policy surface itself is large. The practically useful thing to know going in is where a given policy lives — device-level, user-level, or specifically for kiosk mode — since kiosk-related questions came up a lot when I sat the exam. If you've never had to configure kiosk mode for real, it's worth deliberately spending time there rather than assuming general ChromeOS familiarity will cover it.

One small shortcut worth remembering: Alt+V shows system info on the sign-in screen.

Section 4: Identity management

New users are created under Directory → Users → Add New — name, auto-generated username, optional photo, OU assignment, optional secondary email for sending credentials, and an 8-character minimum password. Bulk creation uses a CSV template: first name, last name, email, password, and OU path.

Setting up SSO is a longer sequence worth having as a checklist:

Configure the identity provider (SAML or OIDC).
Enable SAML-based SSO under Devices → Chrome → User & Browser Settings → Security.
Enable transfer of SAML SSO cookies into the user session at sign-in, if wanted.
Optionally keep local ChromeOS and SAML passwords in sync — choosing whether to enforce online sign-in at the login screen only, or both login and lock screen.
Set up password expiration notifications via the passwordExpirationTimestamp attribute.
Enable IdP redirection, so users go straight to the SAML page rather than seeing a Google-branded intermediate screen.
Enable username passthrough, so the username auto-fills on the IdP's login page.
Control what's reachable from the sign-in/lock screen via blocked URLs and exceptions.

Third-party IdP configuration (sign-in URL, sign-out URL, certificate, change-password URL) lives under Security → Authentication → SSO with third-party IdP. Domain-specific service URLs can either redirect straight to the third-party IdP or prompt for a Google username.

Section 5: General tenets and hardware

Test domains: added as a secondary domain under Domains.
OS update cadence: new milestone releases roughly every 4 weeks; Long Term Support gets milestone updates every 6 months.
Password manager policy: Devices → Chrome → User and Browser Settings, search "Security" → Password Manager, with an option to disable it outright.
Lock screen: configurable idle timeout before the screen locks.
Keeping devices managed: forced re-enrollment (Devices → Chrome → Device Settings → Enrollment and Access) is on by default, and pairs with requiring verified boot mode for Verified Access.
Disabling a device: Devices → [select device] → Disable, with an optional custom message, and it's reversible.

On hardware selection, the exam expects general awareness of ChromeOS device specs, hardware capability tiers, and ChromeOS Flex as a route for repurposing existing (non-Chromebook) hardware — rather than deep specifics.

A few loose scenario notes

A couple of specific scenario-style points that stuck with me from prep:

Migrating email from IMAP into Google Workspace: the correct tool is Google's native Data Migration service, not a manual export/import.
Within the security investigation tool, one of the available actions on a user in the search results is "Restore user."
Manual enrollment shortcut: Ctrl+Alt+E on the sign-in/enrollment screen.

Further resources

A handful of the videos and docs I found genuinely useful while studying:

Internal rate of return calculation

2023-07-29T00:00:00+00:00

The internal rate of return (IRR) is a potent financial measure used in financial analysis, accounting, and portfolio management to gauge the profitability of investments. It's like the heartbeat of an investment - an indicator of health, the higher it is, the better the investment. This powerful tool can help investors compare different investment options, assisting in making informed decisions about where to allocate their capital. Especially when cash flows are irregular, as often is the case in real-world scenarios, IRR becomes invaluable. This article will first explain the concept and calculations behind IRR and then demonstrate how to implement an IRR algorithm in Rust.

IRR vs. XIRR terminology

The IRR is the rate of return that makes the net present value (NPV) of all cash flows (both positive and negative) from a particular investment equal to zero. It's sometimes used for cash flows at regular, usually annual, intervals. I will not make this assumption in this article. While Microsoft uses the name XIRR for its Excel function, I will use the term IRR throughout this article, even though the cash flows do not occur at regular intervals.

Example data and validation

A crucial part of implementing a financial algorithm like IRR is validation. That is, making sure that your algorithm is producing correct and expected results. One effective way to validate your implementation is by comparing its outputs to those of Microsoft Excel's XIRR function. I will use the data from the Excel example. Using Excel's XIRR function to compute the internal rate of return for this specific data set yields a result of $37.34\%$ .

$\textbf{i}$	ISO Date $\textbf{d}$	Years since first cash flow $\textbf{y}$	Payment $\textbf{p}$
1	2008-01-01	0.0000	-10,000
2	2008-03-01	0.1644	2,750
3	2008-10-30	0.8301	4,250
4	2009-02-15	1.1260	3,250
5	2009-04-01	1.2493	2,750

How IRR works

The IRR is calculated by finding the rate of return that would make the net present value (NPV) of an investment equal to zero. The NPV is the sum of the present values of all future cash flows from an investment. The derivative of the NPV is used to find the IRR. The derivative of the NPV is the rate of change of the NPV with respect to the interest rate.

The IRR algorithm is an instance of the Newton-Raphson method, which is a root-finding algorithm that produces successively better approximations to the roots (or zeroes) of a real-valued function. To calculate the IRR, you need an array with pairs of data: one is the date of a cash flow, and the other is its payment amount. You also need an initial guess for the IRR rate, which is often set as $10\%$ or $0.1$.

Here's the general process of the algorithm:

Compute the net present value (NPV): The NPV is calculated by summing the present values of the individual cash flows.
Compute the derivative of the NPV: The derivative of the NPV with respect to the rate is created by differentiating the NPV formula and summing these values.
Update the guess: The next guess for the rate is calculated by subtracting the ratio of the NPV to its derivative from the current guess.
Iterate until convergence: These steps are repeated until the change in guesses is below a certain tolerance or until a maximum number of iterations is reached. At this point, the guess for the rate is considered to be the IRR.

Compute the net present value (NPV)

Here, $y_i$ represents the number of years that have passed since the first cash flow, calculated as the difference in days between the date of the $i$-th cash flow $d_i$ and the date of the first cash flow $d_1$, divided by 365 (days in one year). I have pre-calculated it in the table above:

$$y_i = \frac{d_i - d_1}{365}$$

The NPV is the sum of all payments, where the correct interest rate $irr$ is applied. Its value is 0 after all transactions have been concluded:

$$\mathit{NPV} = \sum_{i = 1}^{m} \frac{p_i}{(1 + irr)^{y_i}}$$

When you plot the NPV function as a function of $irr$, you are essentially varying the interest rate and observing how it affects the NPV. Here's what you see on the graph below, which plots the NPV as a function of the rate with the values from the table above:

X-axis: The x-axis represents the interest rate $irr$. It typically ranges from $0\%$ to a reasonable upper limit, depending on the context of your problem.
Y-axis: The y-axis represents the net present value NPV. It's the cumulative sum of the discounted cash flows according to the given formula.
Shape of the curve: The curve of the NPV function will generally be downward-sloping. This is because as you increase the interest rate $irr$, the present value of future cash flows decreases. Higher interest rates mean that future cash flows are being discounted more heavily, which reduces their present value.
Break-even point: There will be a point on the graph where the NPV curve intersects the x-axis. It's where our $irr$ satisfies the condition $\mathit{NPV} = 0$. For our data, it is somewhere between $0.35$ and $0.40$, or $35\%$ and $40\%$ .

Downward-sloping NPV curve

The above formula is a sum of function terms. Applying the superposition principle, we can split the sum into individual function terms, which look all the same. For each cash flow, we have a function term, which is the present value of the cash flow. The important part is that we can apply this principle to the NPV function and the derivative of the NPV function.

With $irr$ written as $x$, each function term looks like this, where $p_i$ and $y_i$ are just constants. $f_i(x)$ represents the NPV for a single cash flow, the $i$-th one:

$$f_i(x) = \frac{p_i}{(1 + x)^{y_i}}$$

The amount $p_i$ is discounted in the NPV calculation to reflect the time value of money. Here's an explanation for why that's done:

Time value of money: Money available today is worth more than the same amount in the future because of its potential earning capacity. This core principle of finance holds that, provided money can earn interest, any amount of money is worth more the sooner it is received.
Discounting future cash flows: In the context of the internal rate of return (IRR) and net present value (NPV), this principle is applied to future cash flows. The $p_i$ represents a payment (cash flow) at some future date. To compare this future value to present values, it needs to be discounted back to its value in today's terms.
The discount factor: The expression $\frac{1}{(1 + x)^{y_i}}$ serves as a discount factor, where $x$ is the internal rate of return, and $y_i$ is the number of years that have passed since the first cash flow. This factor is derived from the formula for compounding interest in reverse (discounting rather than compounding).
Sum of discounted payments: The NPV is the sum of these discounted payments. By discounting each future cash flow back to its present value, the NPV provides a consistent basis for comparing the value of cash flows across different time periods.
Understanding the equation: The equation $f_i(x) = \frac{p_i}{(1 + x)^{y_i}}$ represents the present value of the $i$-th cash flow. It shows how each cash flow is discounted back to present value terms using the discount factor.

Discounting the $p_i$ in the NPV calculation allows for a proper comparison of cash flows across different time periods, taking into account the time value of money and the specific internal rate of return (IRR) required from the investment. It ensures that future cash flows are appropriately weighed against the potential earning capacity of money in the present.

But what happens if ...

The expression $(1 + x)^{y_i}$ can become a problem if $x < -1$ (less than $-100\%$ ), because raising a negative number to a non-integer power will result in a complex number. Within the realm of real numbers, this operation is undefined. For example, consider a case where $x = -1.1$ and $y_i$ is a floating point number like $0.4$. Then, $(1 + x)$ will be negative, and raising it to the $y_i$ power produces a complex value: ${(1 - 1.1)}^{0.4} \approx 0.12 + 0.38 i$

In the context of finance and the calculation of IRR, it doesn't make sense to have complex numbers as they don't have a practical interpretation in terms of cash flows or discount rates. Therefore, you would typically ensure that the rate $x$ stays within the range where the calculation remains within the realm of real numbers. If you're working with cash flows and discount rates, you may want to either avoid or handle situations where $x < -1$ by constraining the value of $x$ within a reasonable range or taking some other specific action if $x$ falls outside that range.

In practice, it's rare that you would come across this scenario.

Compute the derivative of the NPV

We can now apply the basic differentiation rules to get the derivative of $f_i(x)$. It represents the derivative of the NPV for a single cash flow, also the $i$-th one:

$$f_i^\prime(x) = \frac{-y_i \cdot p_i}{(1 + x)^{y_i + 1}}$$

Update the guess

The Newton-Raphson method is an iterative process used to locate the roots of a differentiable function, i.e. a solution for $x$ where $f(x) = 0$. The method begins with an initial estimate $x_n$, which is then refined into a more accurate guess, $x_{n+1}$. This stage is where the NPV and its derivative come into play. Instead of solely employing $f_i(x_n)$ and $f_i^\prime(x_n)$ for a single cash flow, we incorporate all the cash flows by adding up the NPV terms and derivative terms respectively:

$$x_{n+1} = x_{n} - \frac{\sum_{i = 1}^{m} f_i(x_n)}{\sum_{i = 1}^{m} f_i^\prime(x_n)} $$

Iterate until convergence

Instead of improving the result indefinitely, you stop when the difference between $x_n$ and $x_{n+1}$ is smaller than or equal to a given $\epsilon$, i.e. $\left| x_n - x_{n+1} \right| \le \epsilon$. It's usually a tiny number, like $0.000001$ ($1.0 e^{-6}$). This is the value used in Microsoft Excel's XIRR function.

It's also worth noting that despite using the exact derivative, the IRR algorithm is still an approximation method. It may not always converge to a solution, especially for cash flow series that have multiple changes in sign. In these cases, it may be necessary to provide a good initial guess for the rate or to use a different method to compute the internal rate of return.

Implementation in Rust

Let's move towards translating our theoretical understanding into a concrete implementation using Rust. We'll focus on implementing the IRR calculation algorithm by applying the findings and formulas mentioned in the previous sections. The final output should be close to Excel's XIRR function result within an acceptable tolerance range.

// We use the chrono crate for date handling: https://docs.rs/chrono/latest/chrono
use chrono::prelude::*;

// Function to calculate the number of days between two dates
fn days_between(start_date: NaiveDate, end_date: NaiveDate) -> i64 {
    // Calculate the duration between the two dates
    let duration = end_date.signed_duration_since(start_date);

    // Return the duration in days
    duration.num_days()
}

// Main function to calculate the internal rate of return
fn calculate_irr(transactions: &[(f64, f64)], initial_guess: f64) -> f64 {
    // Start with initial guess for the IRR
    let mut x = initial_guess;
    const MAX_TRIES: usize = 100;
    const EPSILON: f64 = 1.0e-6;

    // Loop until a maximum number of iterations is reached
    for _ in 0..MAX_TRIES {
        // Calculate NPV and its derivative for each cash flow and sum them up
        let (fx, dfx) = transactions.iter()
            .map(|(years, amount)| {
                let fx = amount / (1_f64 + x).powf(*years);                  // NPV of the cash flow
                let dfx = (-years * amount) / (1_f64 + x).powf(years + 1.0); // Derivative of NPV
                (fx, dfx)                                                    // Return both values for a single cash flow
            })
            // Sum up all NPVs and derivatives for all cash flows (reduce to a tuple of two sums)
            .fold((0_f64, 0_f64), |(fx_acc, dfx_acc), (fx, dfx)| (fx_acc + fx, dfx_acc + dfx));

        // Calculate the new guess
        let new_x = x - fx / dfx;

        // Calculate the difference between the new and the old guess
        let epsilon = (new_x - x).abs();

        // If the difference is smaller than or equal to the tolerance, we are done
        if epsilon <= EPSILON {
            return x;
        }

        // Continue the loop with the new guess
        x = new_x;
    }

    // Return a non-number if the algorithm didn't converge (see "Iterate until convergence" in article)
    f64::NAN
}

// Define the main function and our example transactions
fn main() {
    // Example from Microsoft Excel documentation:
    // https://support.microsoft.com/en-gb/office/xirr-function-de1242ec-6477-445b-b11b-a303ad9adc9d
    // The internal rate of return is 0.373362535 or 37.34%
    let cashflows = vec![
        (NaiveDate::from_ymd_opt(2008,  1,  1).unwrap(), -10_000.00),
        (NaiveDate::from_ymd_opt(2008,  3,  1).unwrap(),   2_750.00),
        (NaiveDate::from_ymd_opt(2008, 10, 30).unwrap(),   4_250.00),
        (NaiveDate::from_ymd_opt(2009,  2, 15).unwrap(),   3_250.00),
        (NaiveDate::from_ymd_opt(2009,  4,  1).unwrap(),   2_750.00),
    ];
    // Pre-calculate the years since first cash flow for each cash flow
    let transactions: Vec<(f64, f64)> = cashflows.iter()
        .map(|(date, amount)| (days_between(cashflows[0].0, *date) as f64 / 365.0, *amount))
        .collect();

    // Call our IRR calculation function and print the result
    // Expected result is 37.34%
    println!("IRR with Newton-Raphson: {:.2}%", calculate_irr(&transactions, 0.1) * 100.0);
}

The calculate_irr function is where the heart of our IRR calculation lives. It starts by defining the initial guess for the IRR, then enters a loop that calculates the new guess, checks for convergence, and continues the loop if not converged. Finally, if the algorithm fails to converge, it returns a non-number. The main function uses an example transaction set and calls our calculate_irr function.

Bonus: implementation in JavaScript

JavaScript runs natively in all modern browsers and is the lingua franca of the web. By translating the Rust code into JavaScript, the IRR calculation will be easily usable on virtually any device, regardless of operating system or hardware. This way, it should be possible to use it in a web application or even in a mobile app using a framework like React Native. Maybe you want to write a financial app that runs on iOS, Android, and the web?

// Function to calculate the number of days between two dates
function daysBetween(start, end) {
  const millisecondsPerDay = 1000 * 60 * 60 * 24;
  const millisBetween = end.getTime() - start.getTime();
  return millisBetween / millisecondsPerDay;
}

// Main function to calculate the internal rate of return
function calculateIRR(transactions, initialGuess = 0.1) {
  // Start with initial guess for the IRR
  let x = initialGuess;
  const MAX_TRIES = 100;
  const EPSILON = 1.0e-6;

  // Loop until a maximum number of iterations is reached
  for (let tries = 0; tries < MAX_TRIES; tries += 1) {
    // Calculate NPV and its derivative for each cash flow and sum them up
    const { fxs, dfxs } = transactions
      .map((tx) => {
        const fx = tx.amount / ((1.0 + x) ** tx.years);                      // NPV of the cash flow
        const dfx = (-tx.years * tx.amount) / ((1.0 + x) ** (tx.years + 1)); // Derivative of NPV
        return { fx, dfx };                                                  // Return both values for a single cash flow
      })
      // Sum up all NPVs and derivatives for all cash flows (reduce to an object with two sums)
      .reduce((acc, obj) => ({ fxs: acc.fxs + obj.fx, dfxs: acc.dfxs + obj.dfx }), { fxs: 0, dfxs: 0 });

    // Calculate the new guess
    const xNew = x - fxs / dfxs;

    // Calculate the difference between the new and the old guess
    const epsilon = Math.abs(xNew - x);

    // If the difference is smaller than or equal to the tolerance, we are done
    if (epsilon <= EPSILON) {
      return x;
    }

    // Continue the loop with the new guess
    x = xNew;
  }

  // Return a non-number if the algorithm didn't converge
  return NaN;
}

// Example from Microsoft Excel documentation:
// https://support.microsoft.com/en-gb/office/xirr-function-de1242ec-6477-445b-b11b-a303ad9adc9d
// The internal rate of return is 0.373362535 or 37.34%
const cashflows = [
  { date: new Date('2008-01-01'), amount: -10000.00 },
  { date: new Date('2008-03-01'), amount:   2750.00 },
  { date: new Date('2008-10-30'), amount:   4250.00 },
  { date: new Date('2009-02-15'), amount:   3250.00 },
  { date: new Date('2009-04-01'), amount:   2750.00 }
];
// Pre-calculate the years since first cash flow for each cash flow
const transactions = cashflows
  .map((cf) => ({ years: daysBetween(cashflows[0].date, cf.date) / 365, amount: cf.amount }));

// Call our IRR calculation function and print the result
// Expected result is 37.34%
console.log(`IRR with Newton-Raphson: ${(calculateIRR(transactions) * 100).toFixed(2)}%`);

Conclusion

The internal rate of return (IRR) is an instrumental financial measure that helps investors compare and decide between different investment opportunities. Calculating it can get complex due to irregular cash flows, making a detailed understanding of the underlying algorithm crucial. This article dived into the mathematics behind IRR calculation and provided a concrete implementation using the Rust programming language. Remember, IRR is not just a number but an insight into the potential of an investment, assisting you in making informed financial decisions.

If you have any questions, need further clarification, or want to give feedback: please let me know.

The Game of Fifteen

2020-06-11T00:00:00+00:00

The Game of Fifteen is a sliding puzzle that consists of a square with tiles numbered from 1 to 15 in random order with one tile missing. To solve the puzzle, you must place the tiles in order by moving tiles to the empty space.

How to play

Play the game online by clicking/tapping on the tile you want to move. Only tiles neighboring the empty space can be moved. Once you solve the puzzle, the tiles will not move anymore. Just play a new game by clicking the button. I can guarantee you that every game presented here is solvable. Read below for an explanation.

Hint: if your browser doesn't display the board correctly, try clearing your browser cache and try again.

Parity of a permutation

For the Game of Fifteen, a permutation of the numbers 1 to 15 is a state of the game if read line by line - like a book. Some smart people have figured out, that an even parity (is dividable by 2, like 42) is an invariant of a solvable permutation of the Game of Fifteen. In computer science, an invariant is a condition that is always true, i.e. doesn't change for a section of code.

The parity of a permutation is simply the number of inversions. An inversion happens when an element with a lower index has a higher value than a value at a higher index.

Examples:

1, 2, 3 has no inversions, all elements are in order
2, 3, 1 has two inversions, because 2 is greater than 1 and 3 is greater than 1
1, 3, 2 has only one inversion, 3 is greater than 2

There are about 1.3 Trillion (Billion for us people in Central Europe) possible permutations of the numbers 1 to 15. Only half of them have an even parity. When we calculate a random permutation for the start of a game, it then makes sense to filter out all the permutations with an odd parity. Because we do not want to present an unsolvable game.

Here is a fragment of source code that calculates the parity and checks if it's even for the examples from above.

// for (let i = 0; i < limit; i += 1) {...} vs
// range0(limit).forEach((i) => {...})
const range0 = (limit) => [...Array(limit).keys()];

const isEvenPermutation = (p) => parity(p) % 2 === 0;

const parity = (p) => range0(p.length)
  .map((i) => range0(p.length)
    .filter((j) => i < j && p[i] > p[j])
    .length
  )
  .reduce((agg, v) => agg + v, 0);

// true, 0 inversions
console.log(isEvenPermutation([1, 2, 3]));
// true, 2 inversions
console.log(isEvenPermutation([2, 3, 1]));
// false, 1 inversion
console.log(isEvenPermutation([1, 3, 2]));

Source code

I have created this GitHub Gist with the complete HTML page including the JavaScript source code. It runs in the browser and uses just Tailwind CSS for styling and plain ES6-style JavaScript. The source code can be used for all square board sizes, not only 4 by 4. You have to adjust the boards GUI or dynamically generate it - it's easy.

Tail recursion with trampoline

2019-03-16T00:00:00+00:00

In case your platform lacks support for proper tail call optimization and you want to do functional programming, you might run into stack space problems. This can be mitigated, but you have to find a way yourself to make it work. The specific platform I'm writing about here is Node.js. After a little introduction, I show one well-known solution to the problem.

In functional programming, recursion is a fundamental concept for handling mutability. Pure functional languages like Haskell do not allow mutation of variables, so you have to come up with a different solution to the problem. What you do is called update as you copy. You create new variables by calculating their values from the values of existing ones. But you never assign a new value to a variable that already has one.

Recursion

To simplify the reasoning, I will assume that a function does not rely on or modify external state, i.e. values of variables outside of its body. Math is organized this way: 1 + 2 = 3 independently of e.g. the current weather outside. It's always true, no matter what.

In order to write a useful recursive function, you have to make sure that it:

eventually returns with a value (terminates)
calls itself

By using these criteria for a recursive function, you can see that it has to either call itself or terminate. When it terminates, it's done and you have a value. Otherwise it will call itself, and you get another stack frame with this call. Depending on the number of calls this function makes to itself, the used stack space grows and you might eventually run out of stack space. This is not a good thing!

Tail recursion

What if you do not need the current stack frame anymore, once you make your recursive call? You could immediately forget it, throw it away, or reuse it, thereby saving stack space. But you have to make sure that you need no information from this stack frame once you have made your next call. This can be accomplished by returning the recursive call alone, not adding to it or modifying it once it returns, so the return value can be directly passed on. Now you have what's called a tail-recursive function.

Tail call optimization

Once you have made sure that your function is tail-recursive, your runtime environment or compiler can optimize the calls in such a way, that the existing stack frame is reused by the next call. The stack thereby never grows and you have eliminated the potential for a stack overflow. But it's not enough that it can be optimized, it has to be actually done. That's where the problem starts.

Not every runtime environment or compiler performs tail call optimization. As of this writing two of the platforms that I use do not support tail call optimization out-of-the-box:

Node.js
Java Virtual Machine (JVM) with Java 8

The JVM does support tail call optimization when used with Kotlin or Scala though.

Not all is lost: where tail call optimization is not directly supported you can implement a workaround that is straightforward. It's effective in saving you from stack overflow errors. The rest of this article shows you how to implement it. It's known under the name trampoline device.

I use the factorial function and implement it in different ways, starting with a loop that mutates values. Factorial is defined for natural numbers without the 0 (1, 2, 3, ...). Factorial(n) calculates the product of all numbers between 1 and n. It serves as an example that I chose because it's easy to understand. I'll then transform it to a recursive function and show you how to make this function tail-recursive. Afterwards I introduce the trampoline device and apply it to a function that is the modified tail-recursive function. Let's start.

Loop

If you're an imperative programmer, you would implement the factorial function with a loop. You start with a variable result that has the value 1 and then have a for-loop that starts at 2 and goes up to n. In the body of the for-loop you modify result and set it to a value that was its previous value multiplied by whatever value your loop-variable has. If you are done with the loop you return the result.

const loopFactorial = (n) => {
  let result = 1;
  for (let i = 2; i <= n; i += 1) result *= i;
  return result;
};

Something to note here is that your result variable does not contain the result. It holds the result only when the execution reaches the return statement. How do you effectively name a variable that has different meanings during its life cycle?

Recursive with info left on the stack

How do you slice a carrot? Although there are many possible ways to do it, one would be to cut off one slice from one end and then repeat the procedure with the rest of the carrot, until there's nothing left. You do the same with whatever is left until you reach the terminating condition. It's a recursive definition. And it's essentially what you do to calculate the factorial in a recursive way.

To calculate the factorial of n you multiply n with the factorial of n - 1. You now have to calculate the factorial of n - 1. And so on.

const stackFactorial = (n) => {
  if (n > 1) return n * stackFactorial(n - 1);
  return 1;
};

You need the result of stackFactorial(n - 1) before you can return from the function call, because you have to multiply it with n before that can happen. What n actually is, is stored in the context of your current stack frame. The next call will have another stack frame, where n has another value. Because you cannot forget the n of the current call, the current stack frame has to stay around.

With large n this can lead to a situation where you get an error and the entire process stops: RangeError: Maximum call stack size exceeded.

Recursive without info left on the stack

What can be done about it? As a first step, you can eliminate the need for the current stack frame once you made the next call. But you somehow have to preserve information that's needed. The solution is to pass all required information on to the next recursive call.

An extra parameter is needed to hold this information. It's commonly called an aggregator, or agg for short. For multiplication you start at 1 (identity, n * 1 === n and 1 * n === n). Along the way, you multiply the aggregator with the current value of n, thereby keeping track of how far you've come with the product. The aggregator will look like this over time:

1
1 * n
1 * n * (n - 1)
1 * n * (n - 1) * (n - 2)
etc.

When you finally hit 1 for n, you simply return the aggregator, because it already contains the correct result.

const tailFactorial = (n, agg = 1) => {
  if (n > 1) return tailFactorial(n - 1, agg * n);
  return agg;
};

As you can see, the call tailFactorial(...) is directly returned, no information from the current stack frame is required anymore.

Alternative function signature

Even though you invoke tailFactorial(5), the definition has two parameters, n and agg. The aggregator has a default value, so you need not provide it. But since it's exposed in the function's interface, someone can call tailFactorial(5, 0) and get a wrong result. Because nobody should mess with agg, it's better to hide it.

Wrap it with a function that only allows the parameter n and make it an inner function of that wrapper function. Within that wrapper function, pass the call on to the inner function.

// Alternative way (not exposing the aggregator)
const tailFactorialAlt = (n) => {
  const innerTailFactorial = (x, agg = 1) => {
    if (x > 1) return innerTailFactorial(x - 1, agg * x);
    return agg;
  };

  return innerTailFactorial(n);
};

I will not use this alternative function signature, because it's too verbose and not helping me make my point. Still, I highly recommend that you do not expose parameters in your function interface that are neither needed nor intended for public access.

Returning a function without calling it

Instead of having the tail-recursive function make the tail call itself, it returns a function (with no arguments) that can call the recursive function with all arguments already in place. This is called a thunk. You then simply have someone to call that thunk, because the tail call is no longer made by the function. If it returns another function, you call it again. And again. Until the final value is returned.

const thunkFactorial = (n, agg = 1) => {
  if (n > 1) return () => thunkFactorial(n - 1, agg * n);
  return agg;
};

Since the function returns either a value or another function without calling it, it is neither recursive nor tail-recursive anymore. The stack cannot grow and you will not run out of it. But if your first call does not give you the final result, you end up with just another function and not with the result.

Device for pulling out functions and calling them

Since you simply pull functions/thunks out of your factorial function until the final value is returned (instead of yet another function), you have to set up a device that's doing just that. The device is called a trampoline and it is handed a function that returns either thunks or a final value. If a call to that function results in another function, it is called for as long as the returned type is a function. Otherwise it returns the final result.

const trampoline = fn => (...args) => {
  let res = fn(...args);
  while (res instanceof Function) res = res();
  return res;
};

Putting it into action

You have two things right now, a function that is returning thunks and another function that can call these thunks for as long as needed, i.e. the final result is returned. The last thing that's left to do is to join these two functions together.

const trampolineFactorial = trampoline(thunkFactorial);

// Example call
trampolineFactorial(5);

All this is for Node.js and JavaScript.

Tail recursive Fibonacci numbers

The Fibonacci sequence is defined like this: F(0) = 0 and F(1) = 1. For all n > 1 you calculate them with F(n) = F(n - 1) + F(n - 2). This is a recursive definition.

What is different from the factorial example used above? You need two independent information, the two previous values of the function. When you want to solve the problem with tail recursion, instead of one aggregator parameter, you need to pass two aggregator parameters to the function: the two previous values. As a rule, you need an additional parameter for every additional information that you need in the body of your function.

Interestingly, n is used as a counter, going down to 1, but the function works its way up to the higher values. For each call, the previous value becomes the current value from the previous call, while the current value is set to current + previous. Until the function terminates for n === 1.

const F = (n, previous = 0, current = 1) => {
  if (n === 0) return previous;
  if (n === 1) return current;
  return F(n - 1, current, current + previous);
};

You can wrap it in a function with only one parameter for n, which hides the aggregators current and next if you want. Like in the example above, the original function becomes an inner function of the wrapper function.

As I recently found out, Fibonacci numbers also have a closed-form expression:

F_{n}={\cfrac {1}{\sqrt {5}}}\left({\cfrac {1+{\sqrt {5}}}{2}}\right)^{n}-{\cfrac {1}{\sqrt {5}}}\left({\cfrac {1-{\sqrt {5}}}{2}}\right)^{n}

As an aside: we were estimating story points during a sprint planing. Story points roughly follow the Fibonacci numbers, so it's natural that the topic pops up from time to time. Someone was asking if there was a closed-form expression for Fibonacci numbers, so we searched for an answer. And voilà ...

Using the trampoline device together with the modified tail-recursive Fibonacci function is left as an exercise for the reader. Hint: you have to modify the tail-recursive Fibonacci function to return a function/thunk instead of returning the result of a recursive function call.

Final thoughts

I use the trampoline device because Node.js does not support tail call optimization (TCO). At one point I thought that Node.js would eventually support TCO through its use of Google's V8 engine. Google was actively working on supporting TCO in V8. But it turned out that Google is no longer pursuing this path. Since tail-recursive functions are particularly useful in functional programming, it's extremely frustrating to see so little progress.

Privacy Policy

2019-03-11T00:00:00+00:00

General notes

Protecting your personal data matters. This website is a static information site and can be used without providing personal data.

I do not actively collect personal data: there are no contact forms, no tracking scripts, no marketing services, and no comments or user accounts. The only exception is basic aggregate traffic statistics (hit/visitor counts) via Cloudflare's dashboard — see Hosting below.

Responsible controller

The responsible controller for data processing on this website is Paul Richards, based in London, UK, reachable via the contact page.

Hosting

This website is served from a self-managed origin server that I administer directly. Traffic to the site is routed through Cloudflare, which sits in front of the origin as a content delivery network and reverse proxy, handling TLS encryption, caching, and protection against malicious traffic (e.g. DDoS attacks).

The origin server does not keep access logs — this is a static site with nothing for per-request logging to usefully record. Cloudflare's edge network does process technical connection data (e.g. IP address, requested page, timestamp, browser/OS information) as an inherent part of routing and protecting the traffic it proxies. I use Cloudflare's aggregate dashboard analytics for a basic count of hits and visitors; this is derived from the traffic Cloudflare's edge already handles, shows aggregate figures rather than tracking identifiable individuals, and does not involve any script, cookie, or code added to the site itself.

Legal basis: Art. 6(1)(f) UK GDPR
Legitimate interest: secure and stable operation of the website, and basic traffic visibility

Cloudflare processes this connection data as an independent controller/processor for its network services; details are available in Cloudflare's privacy policy.

Cookies and browser data storage

This website itself does not set cookies. Cloudflare, which sits in front of the site as described in the Hosting section above, may set its own strictly-necessary security cookies (e.g. for bot/DDoS protection) independently of this site — see Cloudflare's privacy policy for details.

Browser storage is used in one case: after an active click on the theme toggle, to store the display setting (light or dark) for this session in the browser (sessionStorage). This is exempt from consent requirements under the UK Privacy and Electronic Communications Regulations (PECR), as it is strictly necessary to provide the display preference you requested.

The data storage takes place exclusively locally in the browser. Entries can be deleted there at any time.

External content and services

This website does not embed external content (e.g., YouTube, Google Fonts, tracking scripts). All resources (scripts, images, etc.) are served locally.

SSL/TLS encryption

This website uses SSL/TLS encryption. Data transmitted during a page request cannot be read by third parties.

Rights of data subjects

You have the right to:

access to stored personal data
correction or deletion
data portability where applicable
restriction of processing
objection to processing

These rights apply to any personal data processed as described above. Note that the origin server keeps no access logs, and the traffic data Cloudflare processes at its edge is aggregate rather than data I hold or can act on for individual requests — for data Cloudflare processes directly, see Cloudflare's privacy policy for how to exercise these rights with them.

Requests relating to data I hold can be sent via the contact page.

Supervisory authority and right to file a complaint

You have the right to file a complaint with a data protection supervisory authority. In the UK, this is the Information Commissioner's Office (ICO).

Terms

General character of the website

Content and opinions

Liability

External links

Copyright and use of content

Privacy

Applicable law

Closing note

Chasing a five-year-old Windows-only race condition in Zola

Reproducing it

The real fix

An hour of work, a fix a day later, a five-year-old bug closed

Gaming Links

Built a Shed From Scratch

The base

Cutting, painting, framing

Getting the roof angle right

Roof and cladding

Finished

Microsoft

Projects

AI Game

Archiving a 2014 Fix: App-V, wisptis.exe, and a Wacom Mouse Lag Bug

Making sense of Arbor's GraphQL API

Making sense of Arbor's GraphQL API

1. Calendars have no owner filter — so you can't just ask "give me this staff member's events"

2. That same nested field only sees the current academic year

3. "Current staff" doesn't mean what you'd think

4. New starters break calendar-id discovery too — which needs its own fallback

5. A 400 response isn't necessarily a failure

The smaller stuff

Building a calendar sync you can trust to run unattended

Building a calendar sync you can trust to run unattended

Owning only what you created

The diff key

Categories and reminders come from the title, not from Arbor

Batching and the 503-that-isn't-a-failure

Idempotency as the actual test

Parallel, but no differently

Watching it work

Your timetable is in the wrong app

Your timetable is in the wrong app

We didn't start from a blank page

Except the details didn't line up

What we built

Building My New Website with Zola — Keeping It Simple

A bit of history

Keeping it simple

The plan

Useful Links

About

Who am I?

What I do

What's on this site

Get in touch

Contact

Get in touch

Resume / Portfolio

Too Many Options: Picking a CMS and Learning When to Stop Looking

What I looked at

Keystatic

Decap CMS

Sveltia CMS

Gatsby + Decap CMS

The actual problem

Breaking the loop

Where I landed

Adding audio to your blog

The baseline native <audio>

audio_simple shortcode

Audio in your blog

Custom player

Audio in your blog

Notes

Search

Diagrams with Mermaid

What are Mermaid diagrams?

An Entity Relationship diagram example

Using Mermaid in your blog post

The baseline native `<audio>`

`audio_simple` shortcode