v0.4.0 — the backup yard, and dirty pages stop being free

Ports the applicable parts of PGSimCity v0.10.1 through v0.19.0.

Added — the backup yard (from PG's v0.18.0 pgBackRest work, rebuilt around Firebird's actual tools)

• gbak Depot — a logical backup that runs online, and whose snapshot transaction pins the OIT for its entire run. Start one against a busy city and watch garbage collection stall and the version towers climb until it finishes: the reason a nightly backup and a mysteriously bloating database are so often the same story.
• nbackup Vault — physical backup by level. Level 0 copies the whole file, level 1 only the pages changed since level 0. The chain is enforced: level 1 without a level 0 is refused, and Restore chain reports the levels a restore would apply, in order.
• The Difference File — a new pit beside the main excavation. Locking the database (nbackup -L) freezes the main file and every page write diverts into the delta, which fills visibly and merges back on unlock. Leave it locked and it grows for as long as you watch — a real Firebird operations failure mode, now shareable with ?lock=1.
• Two scenarios: Nightly gbak on a busy DB and nbackup with delta.

Fixed — dirty buffer eviction was free (from PG's v0.16.0)

Evicting a dirty page cost nothing, which quietly understated write pressure. A dirty eviction now writes the page out first, so a reader pays for someone else's write. Commits flush their page under forced writes (Firebird's default), so dirty evictions stay rare on a healthy database (~1%) and only bite when the cache is too small for the working set (~5% at 16 buffers) — which is the honest lesson, and the new evictions (dirty N) readout shows it.

Added — walk-up controls (from PG's v0.17.0 autovacuum lever)

The controls that belong to a subsystem now live on the subsystem: the Sweep & GC Depot can start a sweep or switch automatic sweep off, the nbackup Vault runs levels and toggles the lock, the Difference File offers "unlock & merge", and the Transaction Hall lets you forget to commit a transaction — all from the building's own panel.

Added — docs/KNOBS.md, a knob audit (from PG's v0.13.0)

Every control and readout, what it does to the model, and whether the mechanism is real, merely scaled, or a plausible modeled stand-in — followed by the deliberate simplifications, written down so nobody has to discover them by reading sim.js.

Fixed — screenshot driver leaked browser profiles (from PG's v0.19.0)

tools/screenshot.ps1 never passed --user-data-dir, so every run grew a shared default profile with caches and crash dumps. It now uses a throwaway profile and deletes it in a finally block.

Fixed — iOS Safari page zoom (from PG's v0.14.0)

Focusing a form control under 16px makes iOS Safari zoom the whole page. Controls are now 16px on phone widths.

Changed

• The control room grew a Backup yard section; its heading now hides correctly when the panel is collapsed.
• Stats bar gained dirty evictions, backup state and delta size.
• README documents the camera honestly (there is no rotation — it is a fixed isometric projection) and links the knob audit.

Deliberately not ported

PG's environment lighting, GTAO, shadow maps, collision detection and walk-mode levers are 3D-renderer features with no meaning on a 2D canvas. Their PGlite-backed real SQL parsing is a different project's premise — FBSimCity stays a model, and KNOBS.md now says so in detail.

v0.3.0 — chain inspector, an accessible lifecycle page, and a name for where you are

Ports the applicable parts of PGSimCity v0.7.2, v0.8.0 and v0.9.0.

Added

• Live version-chain inspector (from PG's v0.8.0 row-versions work): version chains now carry the real id of the transaction that wrote each version. Click the Record Version Towers and the info panel shows the busiest table's chain live — newest version in green, kept versions with the snapshot bound that still needs them, and versions below the OIT marked as garbage awaiting GC. Concurrent updates land in arrival order, so chains are honestly non-monotonic, just like the real engine.
• The life of a query (from PG's v0.9.0 observability view): the whole pipeline as an accessible, text-first page — sixteen stations from the client library to the committed record version and home again, keyboard-navigable, screen-reader friendly, no canvas required. Linked from the top bar.
• Close-range identification (from PG's v0.7.2): zoom in past 1.45× and a chip names the building at the screen center — "You are at: Execution Hall · EXE".
• Trademark & independence notice (from PG's v0.8.0): README, About panel and the lifecycle page now state that FBSimCity is an independent educational project; Firebird® is a registered trademark of the Firebird Foundation Incorporated.

Changed

• Camera zoom limits consolidated into single constants — one set of numbers to blame for any zoom-related disorientation.
• Table version chains are seeded with transaction ids well below the initial markers, so the inspector's garbage labels are meaningful from the first minute.

Deliberately not ported

• PG's v0.9.0 measurement/telemetry system. FBSimCity makes no network calls and keeps it that way.
• Tour-advances-on-user-input — FBSimCity's tour has always worked that way.
• WAL responsiveness fixes — Firebird has no WAL; the excavation's careful writes remain the whole point.

v0.2.1 — pan no longer loses the city

A small release in the spirit of PGSimCity v0.7.1 ("zoom no longer loses the city") and the v0.6 screen-space work, ported to the isometric camera.

Fixed

• Pan can no longer lose the city. The camera clamp inverts the projection for the screen center and keeps that world point inside the (padded) world rectangle, so no combination of drag and zoom can leave you staring at empty void. Verified against seven torture cases — million-pixel drags in every direction at minimum and maximum zoom all land with city under the screen center, while sane camera positions are left untouched.

Added

• First-visit gesture hint — a small "drag to pan · scroll to zoom · click a building" pill in the middle of the view, dismissed by the first gesture (or after nine seconds), never shown again.
• Collapsible control room — the panel folds to its title bar, remembers the choice, and starts collapsed on narrow screens: the city gets the screen back.
• tools/screenshot.ps1 — the headless-Edge screenshot driver that regenerates docs/screenshot.png from a deep-linked simulation state now lives in the repository.
• A window.FBDebug hook (camera + clamp) so camera invariants can be tested without rendering.

Changed

• Building name labels now appear at a slightly higher zoom (1.0 instead of 0.9), so a city-wide view stays a city, not a sea of captions; hovered and selected buildings always keep their labels.

v0.2.0 — trace a query, scenarios, daylight, and an honest cache

Features ported from the PGSimCity release line, adapted to Firebird mechanics.

Added

• Query trace with step mode (G or the Trace a query button): follow one UPDATE station by station — harbor, Y-valve, lexer, parser, BLR generator, security, compiler, execution, cache accesses with hit/miss narration and the detour down to the database file, lock manager, record version towers, and the TIP commit — with a camera that follows the particle and Next step / Auto play controls
• Six scenario presets in the control room: steady state, cache thrash, stuck OIT / version bloat, lock contention, rush hour, and sweep storm — each sets the sliders, seeds the event log, and flies the camera to the relevant district
• Daylight theme with a visible switcher (D), persisted across visits; the whole canvas palette and UI restyle
• Page anatomy viewer (P): a labeled diagram of a Firebird data page (header, record descriptors growing down, RLE-compressed records growing up, rpb headers with transaction id and back-version pointer) beside the version-chain lifecycle from newest version to sweep-able garbage
• Sparkline vitals: sixty-second history for queries/s, cache hit ratio and stale versions in the stats bar
• Keyboard help overlay (?) and an on-screen version badge

Changed

• Pause now properly freezes the simulation (space), and a speed control runs the world at 0.5×, 1×, 2× or 4×
• The cache stopped lying: page access now follows a hot/cold working-set distribution, so the default 64-page cache lands a realistic ~85–90% hit ratio, an evictions counter joined the stats bar, and shrinking the cache below the hot set visibly thrashes

Fixed

• Record version towers rendered with a stale fill color because the tower gradient emitted a color format the face shader couldn't parse
• TIP counters over the Transaction Hall are now readable in both themes
• The canvas self-heals its size when laid out after load

Known issues

• Touch controls verified in desktop emulation only
• The traced query is spared deadlocks so the walk stays predictable — real transactions enjoy no such courtesy

v0.1.0 — FBSimCity

The first build of FBSimCity — an explorable isometric city that shows how the Firebird database actually works, with the block structure taken from the Conceptual Architecture for Firebird paper and the idea from PGSimCity.

The city

• Sixteen buildings across six districts: REMOTE harbor and Y-valve, the DSQL translation quarter (lexer, parser, BLR generator), JRD downtown (compiler & optimizer, execution hall, metadata library, security gatehouse, B-tree gardens, sort yard, transaction hall), the lock manager tower, VIO record-version towers with a sweep & GC depot, the CCH page-cache plaza, and the database-file excavation ("careful writes — no WAL needed")
• Query particles commute the full pipeline; cyan for SQL, violet after BLR compilation, green carrying results home, red for deadlock victims

The simulation

• Multi-generational record versions: every UPDATE stacks a version; towers grow and redden as chains lengthen
• Live Next / OAT / OIT transaction markers on the Transaction Hall facade
• Cooperative garbage collection plus an interval sweep with a touring truck — correctly stalled while a long-running transaction pins the OIT
• LRU page cache with hit/miss/dirty flashes and disk detours on misses
• Lock waits with occasional deadlock rollbacks

The interface

• Ten-stop guided tour, clickable building stories sourced from the paper, control room (query rate, write mix, cache size, sweep interval, long-running-transaction switch), live stats bar, pan/zoom/touch camera

Zero dependencies, no build step — plain HTML, CSS and JavaScript on a 2D canvas.

Known issues

• Cache hit ratio settles far below production-realistic values at default settings
• The simulation is a scaled model for intuition, not an emulator; corrections welcome