Changelog

Kernel Milestone: 3 of 6 Previous: Milestone 2 — Financial Immutability and State Machines (v5.15.0) Next: Milestone 4 — Provenance

System Impact
-------------
Ledger integrity:         strengthened
Ledger mutation:          unchanged — no posted records modified
Tenant isolation:         unchanged
Financial immutability:   unchanged
State machine:            unchanged
Breaking changes:         none
Replay determinism:       preserved

Invariant Change
----------------
VAT polarity is now enforced at database level: a non-zero VAT component
must share the sign of its net amount. All monetary arithmetic across
financial routes operates exclusively in integer pence, eliminating
floating-point intermediates and unit-conversion errors introduced by
the M3 schema migration.

Why This Matters

The M3 schema migration moved monetary storage from decimal pounds to integer pence across the financial kernel. That migration was correct at the database layer, but several application-layer arithmetic paths were authored before M3 landed and continued treating pence values as if they were decimal pounds, applying conversions that were no longer appropriate. The result was monetary values inflated by a factor of one hundred in ledger endpoints, dividend calculations, and PDF generation — silent errors that produced no exceptions but delivered incorrect figures to any user who saw them.

This release corrects all identified sites, extracts VAT arithmetic into the canonical monetary module so no route layer can implement its own calculation path, and closes the final M3 enforcement gap by adding a database constraint that makes sign-inconsistent VAT states structurally impossible. SpeyBooks now enforces the pence domain end-to-end: from database storage through arithmetic to API response, with no floating-point intermediates and no alternate calculation paths.

Monetary Correctness Fixes

Dividend profit sufficiency (P1)

• Retained earnings calculated 100x too large The profit sufficiency check underpinning dividend approvals read a pence aggregate from the database and multiplied it by one hundred, treating an already-converted value as if it still required conversion. Every dividend approval or rejection produced since the M3 migration was arithmetically incorrect. Corrected to integer parsing with no scaling. The legal significance of this path — dividend approvals are a director obligation — justified P1 classification.

PDF invoice rendering (P1)

• All monetary values rendered 100x too large The PDF generation service applied a formatting function that divided by one hundred to all monetary values, but the function was receiving values that had not yet been divided. The net effect was that every PDF invoice showed figures one hundred times their correct value. Resolved by separating the formatting path for pence-domain values from the path for rate and unit-price values, which remain in their original representation.

Transaction ledger endpoint (P2)

• Ledger balances, debits, credits, and running totals inflated 100x The account ledger endpoint applied a decimal-to-pence conversion to values that were already integer pence following the M3 migration. Opening balance, all per-entry debit and credit columns, and the closing balance were all affected. Corrected to integer arithmetic throughout, removing the decimal library dependency from this path entirely.

• Transaction list totals inflated 100x Aggregate debit and credit totals on the transaction list endpoint were subject to the same conversion error. Corrected to integer parsing.

• Transaction line detail inflated 100x Individual line amounts and VAT amounts on the transaction detail endpoint were affected by the same pattern. Corrected.

VAT arithmetic centralisation (architectural)

• VAT calculation moved out of the route layer VAT was computed inline inside the transaction creation route using ad hoc arithmetic. This violated the architectural rule that all monetary calculation must occur in the canonical monetary module. Two functions have been added to that module covering exclusive and inclusive VAT treatment, both implemented in integer arithmetic with half-up rounding and no floating-point intermediates. The route now calls these functions directly. Enforced by: architectural boundary rule — no monetary arithmetic in routes. Proof: monetary module addition, migration_075 session.

Suspense line parsing

• Float coercion on integer pence column The category suggestion endpoint parsed a pence-domain value using floating-point coercion. Corrected to integer parsing. No financial output was persisted from this path, but the domain assertion was incorrect.

VAT Sign Constraint

The final M3 enforcement gap: VAT polarity was previously guaranteed only by application logic. A non-zero VAT amount must share the sign of its net amount — positive on invoice lines, negative on credit note lines. Without a database constraint, nothing prevented a code path from writing a structurally impossible combination.

A CHECK constraint now enforces this at the database layer. The valid states are: positive VAT with positive net (standard invoice line), negative VAT with negative net (credit note line), or zero VAT for any net (zero-rated or exempt supply). Any write that violates this invariant is rejected by the database regardless of application behaviour.

Pre-flight verification confirmed zero pre-existing violations across all tenants before the constraint was installed. Validation was performed against the application role to ensure RLS-scoped visibility was clean, not only the superuser view.

Enforced by: database CHECK constraint — Class M. Proof: migration_075.

Threat Closure

Security Posture Change

VAT sign consistency moves from Class O (application-level enforcement — bypassable by any write path that bypasses the service layer) to Class M (database constraint — enforced unconditionally on every insert and update regardless of origin). This closes a bypass vector that existed for any bulk import, migration, or direct write that did not route through the invoice service.

Verification Record

Pre-flight:
  2/2 checks clean
  migration 074 present and confirmed as latest applied
  zero sign-violating rows across all tenants (verified as application role)

Migration:
  COMMIT — clean
  All 3 guard blocks passed (baseline, data cleanliness, idempotency)

Post-commit:
  V1  constraint present, convalidated = true, definition matches invariant
  V2  zero violations visible to application role under RLS
  V3  migration recorded at 2026-03-06 20:56:26 UTC

Adversarial review:
  Migration 075 reviewed independently on pre-flight query, guard logic,
  constraint semantics, lock strategy, and role separation

Architectural Context

M3 established the integer pence domain at the database layer. This release closes the application-layer gap: every route that reads monetary data from the database now interprets it correctly as integer pence. M4 (Provenance) can now build on a foundation where monetary values have a single, unambiguous representation end-to-end. Without M3 completion, provenance chains anchoring financial events would be computed against inflated values and produce incorrect audit trails.

Operational Impact

• Dividend profit sufficiency checks now produce arithmetically correct results
• PDF invoices render correct monetary values
• Account ledger balances, running totals, and transaction summaries are correct
• VAT calculation is centralised — no route implements its own arithmetic path
• Sign-inconsistent VAT states are structurally impossible to write
• Floating-point intermediates eliminated from all affected monetary paths

Kernel Status

Files Changed

Backend:

• api/db/migrations/075-vat-sign-constraint.sql — VAT sign CHECK constraint with two-phase locking, pre-flight guard, and post-commit verification queries
• api/src/routes/transactions.ts — corrected monetary interpretation at six sites; removed decimal library dependency from ledger path; VAT calculation replaced with canonical helpers; float coercion on pence column corrected
• api/src/routes/dividends.ts — corrected retained earnings aggregate interpretation; float-with-scaling replaced with integer parsing at both calculation sites
• api/src/services/pdf-service.ts — separated pence-domain formatting from rate-domain formatting; corrected monetary rendering for all invoice value fields
• api/src/lib/api-amounts.ts — added canonical VAT helpers for exclusive and inclusive treatment, both in integer arithmetic

M4 (Provenance) begins with a complete and arithmetically correct monetary foundation.

Why This Matters

A hardening migration that applied row-level security to the wrong table produced a silent deny-all on authentication — every login attempt returned INVALID_CREDENTIALS on service restart, with no error in application logs. This is the class of defect that a mechanical pre-flight system exists to catch: an invariant applied correctly in principle but incorrectly scoped. The fix is a single DDL statement; the forensic trail is a formal migration with pre-flight, post-flight, and a schema record. A second defect — invoice preview arithmetic diverging from the canonical calculation path — was identified and corrected in the same session.

Both fixes strengthen the audit posture: the authentication defect is now formally documented in the migration chain rather than silently remediated, and the invoice preview endpoint now produces figures that are guaranteed to match the values stored when an invoice is created.

Defect A — Authentication Failure on Service Restart (Migration 074)

Root Cause

Migration 071 (Milestone 3, PHASE 0) applied ENABLE ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY to the users table as a gap closure for tenant isolation. This was architecturally incorrect. The users table is a cross-tenant identity store — users are resolved by the authentication layer before any organisation context is established, and no tenant session context is available at that point. Row-level security with no policies denies all rows for application roles. Every authentication query returned zero rows.

The defect remained latent while existing pooled connections were active. It became fully visible on service restart when new connections executed the authentication query under the application role.

Fix

Row-level security disabled on the users table — migration 074. Sessions and password reset tokens, which are also cross-tenant by the same architectural argument, were verified clean as part of the same migration.

The correct architectural boundary: tenant-scoped tables (all financial data, audit records, import state) carry RLS enforced by app.current_org_id. Cross-tenant identity tables (users, sessions, password reset tokens) sit outside the RLS envelope because authentication occurs before tenant context is established.

Enforcement: Migration 074 — pre-flight confirmed defect present, post-flight confirmed RLS disabled, self-recorded in schema_migrations.

Connection Search Path Hardening

The database role’s default search_path was hardened at the PostgreSQL level. This ensures the correct schema is active for every new connection even if the application connection pool hook is bypassed or fails to execute. The pool hook remains in place, but is no longer a load-bearing control.

Defect B — Invoice Preview Arithmetic Divergence

Root Cause

The invoice preview endpoint — which calculates line totals, VAT, and invoice totals for real-time UI display without persisting anything — used a different arithmetic path than the invoice creation service. Specifically:

• Preview used native JavaScript integer multiplication and Math.round for VAT
• The invoice service uses Decimal.js with global ROUND_HALF_UP configuration, operating in pounds-space after converting from pence

The two paths produce the same result for most inputs. They diverge at rounding boundaries: any line where VAT at the applied rate produces a half-penny value would display one figure in the preview and store a different (correct) figure on save. A user creating an invoice would see a total that didn’t match the saved record.

Fix

The preview calculation now uses the identical arithmetic path as the invoice creation service, which implements the ADR-003 monetary kernel (Decimal arithmetic, ROUND_HALF_UP, and pence-domain conversion). The preview is now guaranteed to produce the same figures that will be stored.

This also closes an AX-RND-006 violation — inline monetary arithmetic outside the canonical service computation path.

Axiom: AX-RND-001 (canonical rounding mode), AX-RND-006 (no alternate arithmetic path).

Threat Closure

Verification Record

Migration 074 pre-flight:
  PF-1  Baseline confirmed: 073-schema-migrations-bootstrap.sql
  PF-2  RLS confirmed enabled on users table (defect present)
  PF-3  No policies on users table (deny-all confirmed)

Migration 074 post-flight:
  RLS confirmed disabled on users table
  sessions: RLS already disabled — no action required
  password_reset_tokens: RLS already disabled — no action required
  Self-recorded in migration tracking table

Invoice preview fix:
  Decimal import added to invoices route
  Arithmetic path verified to match invoice-service.ts exactly
  Boundary case confirmed: 0.5p VAT values now round correctly under ROUND_HALF_UP

Files Changed

Database migrations:

• api/db/migrations/074-users-rls-defect.sql — disable RLS on cross-tenant identity tables, formal pre/post-flight verification

Backend:

• api/src/routes/invoices.ts — invoice preview endpoint rewritten to use canonical Decimal arithmetic path matching invoice-service.ts

This release closes two blocking defects introduced by Milestone 3 and establishes the migration tracking infrastructure required for pre-flight baseline verification in all future kernel migrations.

Defect A — Invalid Default on Organisation VAT Scheme (Breaking)

The organisation VAT scheme column carried a default value that the Milestone 3 validity constraint rejects. Any new organisation registration that did not explicitly supply a VAT scheme would fail at the database boundary with a constraint violation — a silent insert-path defect introduced at the point of adding the constraint.

Fix: The default is removed entirely. The service layer must supply an explicit VAT scheme on every organisation creation. This aligns with the kernel principle that financial columns must not carry silent defaults — no fallback, no assumption.

Breaking change: Any code path that omits VAT scheme on organisation creation now fails at the database boundary. All such paths must supply an explicit value.

Enforcement: Default removed — migration 072. Class M (database constraint rejects any non-permitted value; removal of the default forces explicit supply at the service boundary).

Defect B — VAT Sign Enforcement (Class O → Class M)

Invoice line VAT sign alignment — the rule that VAT must carry the same sign as net — was previously enforced only by the arithmetic behaviour of the canonical reduction function. Correct by construction, but not independently verified by the database. A bug in the function, a direct update, or any future code path bypassing the function could silently produce a sign-inverted VAT value with no database-level rejection.

A dedicated database constraint now enforces sign alignment independently. Any row where VAT carries the opposite sign to a non-zero net value is a fatal database exception — regardless of how the row was written.

The constraint permits zero VAT against non-zero net values (exempt, zero-rated, outside-scope). Sign enforcement applies only where both net and VAT are non-zero.

Enforcement: Database CHECK constraint — migration 072. Class M. Two independent layers now cover VAT sign: the reduction identity constraint (enforces exact computed value) and the sign constraint (enforces directional alignment independently). The sign constraint provides a lightweight invariant that remains valid even if the canonical reduction function or its constraint were altered in a future migration.

Migration Tracking Infrastructure

Prior to this release, SpeyBooks had no mechanical record of which migrations had been applied to production. Pre-flight baseline checks in kernel migrations had no table to query, making sequencing verification impossible at the database layer.

Migration 073 introduces a dedicated migration tracking table recording the unique migration filename and apply timestamp for every migration. All previously applied migrations are backfilled with approximate timestamps derived from file modification history. Operational scripts — rollback scripts, verification scripts, test data scripts — are explicitly excluded from the record.

Each migration filename is unique and may appear only once in the table. Migration records are append-only. Existing rows must never be updated or deleted. The table represents the historical execution log of the schema and is authoritative for migration baseline verification. The migration record is inserted as the final step before transaction commit, ensuring the record exists only for migrations that committed successfully.

From this point forward, every migration self-records on commit, and pre-flight checks can mechanically verify the expected baseline before making any changes.

A future enhancement (planned, not yet implemented) will add a checksum column recording the cryptographic hash of the migration file contents at apply time. This will allow detection of post-apply edits or tampering with migration files — a common silent corruption vector in long-lived systems.

Threat Closure

Verification Record

Apply order (migration 073 must precede 072 — 073 creates the tracking table):

Migration 073 post-commit:
  47 migration records inserted (46 backfill + 1 self-record) ✓
  Milestone 3 monetary migration present in record ✓
  Defect closure migration present in record ✓

Migration 072 pre-flight:
  PF-1  Baseline confirmed: tracking table present (migration 073 applied first)
  PF-2  Invalid VAT scheme default confirmed present
  PF-3  VAT scheme validity constraint confirmed present (from migration 071)
  PF-4  VAT sign constraint confirmed absent (not yet applied)
  PF-5  Zero sign-violation rows confirmed

Migration 072 post-commit:
  V1    VAT scheme column default removed ✓
  V2    VAT sign constraint present and validated ✓
  V3    VAT sign constraint definition matches expected expression ✓
        (verified via constraint definition query)

Kernel Milestone: 3 of 6 Previous: Milestone 2 — Financial Immutability and State Machines (v5.12.x) Next: Milestone 4 — Provenance and Audit Chain

System Impact
-------------
Ledger integrity:         strengthened
Ledger mutation:          all monetary columns converted to integer pence storage
Tenant isolation:         strengthened — FORCE RLS gap on core identity tables closed
Financial immutability:   enforced at database layer
State machine:            unchanged
Breaking changes:         API layer must not apply pound-to-pence conversion to DB results
Replay determinism:       preserved

Invariant Change
----------------
All monetary amounts are now stored as exact integers in pence. Fractional penny
storage, non-canonical rounding, and internally inconsistent invoice arithmetic
are rejected by the database on every write — not by application code.

Why This Matters

Every financial system makes implicit choices about how it stores money. Most store decimal values and rely on application code to round consistently. The problem is not floating-point error — decimal storage is exact. The problem is inconsistent state: when different code paths perform the same calculation differently, the stored results diverge silently. An invoice line subtotal that doesn’t match its quantity times unit price. A VAT figure with a different sign than the net amount it belongs to. A total that doesn’t equal the sum of its components. These aren’t hypothetical edge cases — they’re the natural consequence of arithmetic scattered across an application without a single enforced canonical form.

Milestone 3 closes all of these paths. Every monetary column in SpeyBooks is now an integer count of pence. Every invoice line’s arithmetic — net, VAT, gross — is verified correct by the database on every write against four canonical functions that are the sole permitted source of monetary computation. No application code path, no import engine, no SQL query can produce a stored amount that doesn’t conform to these functions without the database immediately rejecting the write with a hard constraint violation.

This is the foundation that makes Milestones 4 through 6 meaningful. Provenance, audit chains, and cryptographic ledger integrity are only valuable if the values they protect were correct to begin with.

Integer Pence Storage

The Monetary Foundation

All monetary amounts are now stored as exact integers representing pence. Twenty-five monetary columns across nine tables were migrated. Where a column was previously optional (the amount may legitimately be absent — for example, a bank feed row where the feed didn’t supply a running balance), the column stores NULL rather than an integer, preserving the distinction between “zero” and “unknown.”

Three domain types were introduced to the database schema:

• pence — a signed integer, not-null by construction, used for all amounts that must exist
• pence_nonneg — a non-negative variant for future use where amounts cannot be negative
• iso_currency — a three-character currency code, enforced at the storage layer

These are not application conventions. They are database-level types. A value that violates them cannot be stored.

Canonical Rounding

A single rounding function governs all monetary arithmetic. It implements symmetric half-up rounding: ties (exactly halfway values) round away from zero, consistently, for both positive and negative amounts. This eliminates the class of bugs where rounding a positive amount and rounding the equivalent negative amount produce asymmetric results — a silent correctness failure that affects credit notes and refunds.

No other rounding method may be used in the monetary computation path. This prohibition is a kernel doctrine, not a convention.

Invoice Line Algebraic Closure

Three Columns, Three Invariants

Every invoice line now carries three monetary figures: the net amount, the VAT amount, and the gross total. All three are stored as integers in pence. Three database constraints enforce their algebraic relationship on every write:

• The net amount must equal the result of applying the canonical net computation function to the line’s quantity and unit price
• The VAT amount must equal the result of applying the canonical VAT function to the net amount and VAT rate
• The gross amount must equal net plus VAT

These constraints mean it is impossible to store an invoice line where the arithmetic doesn’t balance. There is no code path, no import, no direct database write that can produce an internally inconsistent line. The database rejects it.

Precision Boundaries

Unit prices are enforced to penny granularity. A unit price cannot be stored with sub-penny precision in v1 — this is a deliberate conservative choice that aligns with how HMRC and standard UK accounting expect prices to be expressed. Fractional pricing (for high-volume per-unit billing scenarios) is a planned future capability with a defined extension path.

Quantities are enforced to three decimal places. VAT rates are enforced to the range 0–1 (decimal multiplier form). Percentage form VAT rates are rejected at the database layer.

VAT Sign Algebra

Credit notes produce negative net amounts. The VAT on a credit note must be negative — it is VAT being reversed, not VAT being charged. Before this release, sign consistency between net and VAT figures was an application-level responsibility. From this release forward, the canonical VAT function propagates sign from net to VAT mathematically, and the stored result is verified by constraint.

A zero net amount must produce zero VAT. A positive net must produce non-negative VAT. A negative net must produce non-positive VAT. These are now database invariants, not coding conventions.

Reporting Views

Five reporting views — account balances, balance sheet, profit and loss, aged receivables, and monthly P&L — were rebuilt to operate on integer pence throughout. Views return pence; the display layer is responsible for formatting. This is consistent with the API boundary specification established in Milestone 1: the kernel works in pence, the presentation layer converts for humans.

Tenant Isolation Gap Closure

A gap from Milestone 1 was closed as part of this release. Two core identity tables were missing forced row-level security — a configuration that ensures no query, regardless of how it is constructed, can bypass tenant isolation on those tables. This gap has been closed. All tenant-scoped tables in the accounting schema now have both row-level security enabled and forced.

Threat Closure

Security Posture Change

Prior to this release, monetary correctness was a Class O guarantee: it depended on application code following conventions consistently across all code paths. Any service, import engine, or direct database operation that didn’t follow those conventions could produce inconsistent financial state without any database-level rejection. From this release, monetary correctness is Class M: the database enforces algebraic closure on every write, independent of which code path performs the write. The constraint violation is immediate, the transaction is aborted, and no inconsistent state reaches committed storage.

Enforced by database domain types, CHECK constraints referencing IMMUTABLE canonical functions, and forced row-level security — migration 071.

Verification Record

Pre-flight:
  9/9 validation checks clean
  PF-01: RLS enforcement confirmed on all tenant tables
  PF-02 through PF-09: schema state, data integrity, vat_scheme values verified

Data corrections (applied before migration):
  8 rows: VAT rate stored in percentage form — corrected to decimal multiplier
  8 rows: VAT-inclusive gross stored as net subtotal — invalid test data, removed

Migration:
  COMMIT
  All 10 invariant verification blocks passed
  INV-01: No decimal monetary columns remain
  INV-02: 4 canonical functions, all deterministic and parallelism-safe
  INV-03: invoice_lines net/VAT/gross columns carry correct domain types
  INV-04: No silent zero-defaults on monetary columns
  INV-05: All invoice lines satisfy gross = net + VAT
  INV-06: All invoices satisfy total = subtotal + VAT
  INV-07: All three domain types created
  INV-08: Unit price penny constraint installed
  INV-09: VAT scheme columns and constraints verified
  INV-10: All 5 reporting views recreated

Post-commit schema signature:
  eeea9331618a60af5d62d6be029de014

Adversarial review:
  Two independent kernel-level reviews conducted during development session.
  Review 1: surfaced unit_price constraint vs ADR contradiction, NUMERIC
             vs float claim, axiom ID drift, nullable column domain gap.
  Review 2: confirmed action plan correct, added VAT sign constraint as
             required (migration 072), confirmed API double-conversion as
             highest operational risk item.
  All critical findings accepted and actioned or formally deferred with rationale.

Amendment:
  VAT sign algebraic constraint deferred to migration 072 (constraint addition
  on already-committed table — clean separation).
  ADR-003 corrections pending (unit_price policy, rounding rationale,
  no-alternate-arithmetic doctrine).

Architectural Context

The kernel milestone sequence has a strict dependency order. Tenant isolation (M1) had to precede everything — without it, no financial guarantee has meaning because data from one tenant could contaminate another. Financial immutability (M2) had to precede monetary correctness (M3) — there is no value in enforcing that amounts are correct integers if those amounts can be silently mutated after the fact.

Milestone 3 enables Milestones 4 and 5. Provenance (M4) — recording the origin of every financial value — only matters if the values being recorded are themselves correct. Schema-derived categorical boundaries (M5) — enforcing that account categorisation follows structural rules — requires the monetary foundation to be settled first, because categorisation errors manifest as wrong amounts in wrong accounts.

Operational Impact

API layer: The database now returns integer pence directly for all monetary columns. Any code path that previously converted decimal pounds to pence must not apply that conversion to values already returned as integers. A verification pass of the conversion boundary is required before this release is considered fully complete.

Import engines: The bank import pipeline, invoice import engine, and opening balance engine all write to tables covered by this migration. All monetary writes now go through the canonical function path enforced by constraints. Malformed amounts that previously stored silently will now produce constraint violations — which is the correct behaviour.

VAT scheme: Organisations previously recorded as “not VAT registered” using a legacy scheme value have been migrated to the canonical scheme vocabulary. The service layer must supply an explicit VAT scheme on every new organisation — no silent default is permitted.

Kernel Status

Files Changed

Database migrations:

• api/db/migrations/071-preflight-data-fix.sql — pre-migration data corrections: VAT rate normalisation and invalid test data removal
• api/db/migrations/071-preflight.sql — 9-check pre-flight validation suite
• api/db/migrations/071-milestone-3-monetary.sql — 17-phase migration: domain types, canonical functions, 25 column migrations, 5 view reconstructions, 8 algebraic constraints, 10 in-transaction invariant verifications

Milestone 4 (Provenance and Audit Chain) will establish cryptographic proof of origin for every financial value entering the ledger, completing the traceability guarantee from source document to committed transaction.

Why This Matters

A deterministic financial kernel is only as trustworthy as the governance system that surrounds it. Code can be correct today and drift tomorrow — through a well-intentioned refactor, a changelog claim that overstates enforcement, or a new developer who inherits the system without understanding its invariant model. This release addresses that risk directly.

SpeyBooks now has a formal, machine-verifiable governance stack: every architectural invariant is classified, registered, and linked to a proof anchor. Public changelog entries are bound by a mathematical honesty rule that prevents enforcement claims from outrunning what the system actually guarantees. The development contract governs not just what to build, but how to reason about what has been built.

This is infrastructure for the kernel sequence. Milestones 3 through 6 depend on this governance layer being in place before the work begins.

Governance Infrastructure

Development Contract v1.5

The kernel development contract has been hardened with structural additions that close the gap between architectural intent and verifiable reality.

• Invariant classification introduced Every invariant is now formally Class M (mechanically enforced, violation is fatal) or Class O (operationally enforced, with a declared bypass vector, mitigation, and upgrade path to Class M). No invariant may claim enforcement it does not have.

• Two-layer minimum rule formalised Any invariant affecting money, tenancy, ledger integrity, or state machines must be enforced by at least two independent layers, one of which must be database-level.

• Drift Governance section added Canonical truth sources defined in priority order, drift ban encoded, axiom registry requirement specified. Mismatch between the live schema and migration history is a defect, not documentation lag.

• Axiom Stability Rule Once registered, an axiom may not be modified or removed without an ADR. Weakening a class (M to O) is a kernel architecture change requiring the same ADR process as a schema change affecting financial tables.

• CI Proof Verification Rule Proof anchors in the registry must resolve to real artifacts — named tests, migration invariant queries, or verification scripts. CI fails if a proof anchor references a missing or renamed artifact.

• Migration Envelope formalised All migrations touching tenant or financial tables must include timeout controls, in-transaction invariant DO blocks that RAISE EXCEPTION on breach, post-commit verification queries, and pre-flight read-only checks. Silent failures are structurally impossible.

• RLS Canonical Predicate Rule Policy predicates have a single canonical form stored in docs/kernel/rls.md. No alternative formatting permitted. Canonical string form is a contract.

• State machine morphism model Transitions are formally defined as f: S → S with declared arrows enforced at DB trigger, TypeScript, and test layers simultaneously. Undeclared transitions are impossible by construction.

• Audit trail hardened Canonical JSON enforced by a single function. Required fields expanded to include source and schema_version. Upgrade path to Class M documented against Milestone 6.

• Changelog communication rules added Two-tier format with proof anchors required for all enforcement claims. No internal implementation details in public entries. Class O guarantees must be described as operational controls, not invariants.

Kernel Axiom Registry

docs/kernel/axioms.yml introduced as the single source of truth for all architectural invariants. The registry is machine-verifiable by design: every axiom carries its enforcement class, required and current layers, proof anchors with delivery status, and upgrade path where applicable.

Initial axioms registered:

• AX-KERNEL-001 — Dual-Layer Enforcement Mandate (self-referential meta-axiom)
• A1.1 — Absolute RLS
• A1.2 — Mutation Containment
• A2.1 — The Posted Set
• A2.2 — State Machine Forward-Only
• A4.1 — Audit Trail Completeness
• L1.1 — Canonical Time Axis (Milestone 6)
• M1.1 — Money Singularity
• M1.2 — Sub-Penny Prohibition
• D1.1 — Double-Entry Conservation
• O1.1 — Rounding Policy Integrity (Class O, upgrade path to M3)
• AX-AUD-001 — Audit JSON Canonical Form (Class O, upgrade path to M6)

A known ADR collision was identified and corrected: ADR-003 is the UIE hypothesis solver, not the rounding policy. The rounding policy ADR is pending assignment and must be written before Milestone 3 begins.

Session Bootstrap Documents

Two governed development session documents introduced:

• speybooks-ai-bootstrap.md — canonical session brief covering system identity, invariant classification, milestone roadmap, monetary rules, deterministic SQL, concurrency model, audit requirements, and drift governance.

• speybooks-m3-bootstrap.md — scoped brief for the Milestone 3 monetary domain migration session. Covers completed milestone state, M3 axiom targets, migration envelope skeleton, risk vectors, and deliverables in priority order.

Operational Impact

Governance: Every architectural invariant now has a stable ID, enforcement class, and proof anchor. Drift between documentation and implementation is detectable by CI.

Milestone readiness: M3 has a complete scoped brief. The ADR-003 collision is identified and corrected before it could produce a false proof anchor in production.

Changelog integrity: The completeness rule and proof anchor requirement close the gap between template and published record. Entries are engineering documents, not partially-filled forms.

Files Changed

Backend: None — no application code changed.

Governance:

• docs/kernel/axioms.yml — kernel axiom registry v1.2, 12 axioms registered
• docs/kernel/rls.md — canonical RLS predicate store introduced
• docs/kernel/speybooks-ai-bootstrap.md — canonical session brief
• docs/kernel/speybooks-m3-bootstrap.md — Milestone 3 scoped session brief
• docs/dev/development-contract.md — development contract updated to v1.5

Milestone 3 — Monetary Domain Migration — is the next kernel release, converting all financial columns to integer pence and elevating rounding policy to a mechanically enforced database invariant.

Why This Matters

SpeyBooks uses a domain-specific linter (lint.py) that enforces architectural boundaries standard AST linters cannot catch — RLS context enforcement, monetary calculation boundaries, hardcoded secret detection, and type safety. The linter is a build gate: any ERROR level finding blocks the path to production.

This release resolves the first two classes of findings identified after Milestone 2 deployment: a genuine misclassification in the log retention job, and a set of false positives in documentation fixture files and the health check probe. Both categories required careful diagnosis before resolution — suppressing a genuine finding is a security regression; fixing a false positive by changing legitimate code is unnecessary churn.

BE002 — Log Retention Job

Finding

The linter flagged api-log-retention.ts for direct database pool access, which in the API server context bypasses the RLS session variable set on request.dbClient. This is a genuine and important rule — any query running outside the tenant-scoped client can read or write across tenant boundaries.

Resolution

This is a legitimate false positive for this specific file. The log retention job is a standalone cron process that runs entirely outside the API server. It has no Fastify request context, no tenant session, and no request.dbClient to use. The api_request_log table it operates on is an administrative table with no organisation_id column and no tenant-scoped RLS policy — it is explicitly not a tenant-scoped table.

The suppression directive was already present in the file but positioned incorrectly — on the line above the while loop rather than directly above the pool.query() call. The linter’s preceding-line suppression checks lines[line_index - 1] exactly, so placement matters. The directive was repositioned to the line immediately preceding the flagged call.

A secondary improvement was made at the same time: the RETENTION_DAYS constant was being interpolated directly into the SQL string (INTERVAL '${RETENTION_DAYS} days'). While not a security risk — RETENTION_DAYS is a hardcoded integer constant — string interpolation in SQL is a pattern worth eliminating categorically. The interval is now fully parameterised using PostgreSQL’s ($1 || ' days')::INTERVAL cast.

UN001 — Documentation Fixtures and Health Probe

Finding

Five UN001 findings across three files: three whsec_... webhook signing secret examples in webhook-endpoints.doc.ts, one TOTP demo secret in auth.doc.ts, and synthetic probe credentials in health.ts.

Resolution

All five are confirmed false positives. The UN001 rule correctly detects the pattern of a secret-named field assigned a non-trivial string value — this is exactly the right heuristic for catching real hardcoded secrets. These specific instances are not real secrets:

• The whsec_... values in webhook-endpoints.doc.ts are documentation examples showing the format of a webhook signing secret in curl examples and response fixtures. The repeating hex pattern makes their illustrative intent unambiguous.
• JBSWY3DPEHPK3PXP in auth.doc.ts is the canonical TOTP demonstration secret used in virtually every TOTP library’s own documentation and test suite.
• health@check.internal and health-check in health.ts are synthetic probe credentials whose entire purpose is to be rejected by the authentication service — a 400 or 401 response proves the auth stack is processing requests. A real credential would defeat the purpose of the probe.

webhook-endpoints.doc.ts and auth.doc.ts received file-level suppressions (// lint-ignore-file UN001) since every example value in a documentation fixture file is by definition not a production secret. health.ts received a line-level suppression positioned directly above the flagged body: line.

Linter Integrity

These resolutions follow the principle that suppression directives are documentation, not escape hatches. Each suppression carries a reason that explains why the finding is a false positive and what property makes the suppressed code safe. A future developer reading the suppression understands immediately why it exists and can verify the reasoning has not been invalidated by subsequent changes.

The linter rule itself is correct in all five cases — the pattern it detects is a genuine risk pattern. The suppression acknowledges the rule, not overrides it.

Operational Impact

• BE002 error count: 1 → 0
• UN001 error count: 5 → 0
• Total backend errors: 125 → 120
• Log retention SQL fully parameterised — no string interpolation in query
• All suppressions carry explicit documented reasons

Files Changed

Backend:

• api/src/jobs/api-log-retention.ts — lint-ignore BE002 repositioned to correct line, RETENTION_DAYS parameterised via ($1 || ' days')::INTERVAL
• api/src/routes/health.ts — lint-ignore UN001 added directly above flagged body line, stray suppression comments from earlier attempts removed, missing closing brace restored
• api/src/routes/webhook-endpoints.doc.ts — lint-ignore-file UN001 added
• api/src/routes/auth.doc.ts — lint-ignore-file UN001 added

Remaining 120 backend errors are BE005/BE006 — any type usage and type assertions. These are resolved structurally by Milestone 5 (schema-derived categorical boundary and generated types). Manual remediation before that milestone would mean doing the work twice.

Kernel Milestone: 2 of 6 Previous: Milestone 1 — Tenant Isolation (5.14.0) Next: Milestone 3 — Monetary Domain Migration

System Impact
-------------
Ledger integrity:         strengthened
Ledger mutation:          structurally impossible after posting
Tenant isolation:         unchanged
Financial immutability:   enforced at database layer
State machine:            forward-only transitions enforced
Cascade deletion:         closed on core financial tables
Breaking changes:         none
Replay determinism:       preserved

Invariant Change
----------------
Axiom 2.1 (Posted Set) is now mechanically enforced at the database layer.

Why This Matters

An accounting system’s most fundamental guarantee is that posted financial records cannot change. Without this property the ledger is not a ledger. It is a mutable table that happens to hold numbers. Auditors, regulators, and the mathematics of double-entry bookkeeping all depend on the same invariant: once a transaction is posted, its lines are permanently fixed.

Before this release that guarantee existed only at the application layer. The application code respected immutability, but the database did not enforce it. A direct database connection, a future developer shortcut, or a defect in application logic could silently modify or delete posted transaction lines. No error would be raised. The ledger would simply drift.

This release moves that guarantee to the only layer that cannot be bypassed: the database itself.

There is also a deeper architectural reason this matters. If posted records never change, the entire financial history of a tenant can be reconstructed from first principles by replaying the ordered ledger event stream. Deterministic replayability is the prerequisite for the cryptographic ledger verification arriving in Milestone 6.

Financial Immutability

Posted Transaction Line Protection (Axiom 2.1 — The Posted Set)

The SpeyBooks kernel defines the Posted Set: once a transaction is posted, its lines are immutable at three independent enforcement layers:

1. Database triggers (this release)
2. Ledger append-only policy (Milestone 6)
3. PostedTransaction TypeScript type with no mutation methods

These layers eliminate any single point of failure. Bypassing one does not bypass the others.

Two trigger functions now execute before any modification or deletion of a transaction line. If the parent transaction is posted or void, the operation is blocked before execution with a fatal exception.

• Modification blocked Amounts, account assignments, directions, and all other values on a posted line are permanently fixed. Reversal is performed through the void mechanism, which generates a compensating entry rather than mutating history.

• Deletion blocked Lines belonging to posted or voided transactions cannot be removed. Financial records are never destroyed. This is enforced by database exception, not application convention.

• Orphan detection If a trigger fires on a line whose parent transaction cannot be found, an integrity exception is raised. In a correctly functioning system this state is impossible. Failures surface loudly rather than passing silently.

The Void Principle (Axiom 2.2 — No Cascade Destruction)

Financial records in SpeyBooks are never destroyed. This release eliminates the primary destruction pathway: cascade deletion on core financial tables.

Three foreign key constraints have been converted from CASCADE to RESTRICT, creating a three-sided enclosure around every posted transaction:

1. Lines cannot be modified or deleted individually (Axiom 2.1 triggers)
2. Parent transactions cannot be deleted while lines exist (Axiom 2.2 restrict)
3. Lines cannot be cascade-destroyed through parent deletion (Axiom 2.2 restrict)

There is no remaining deletion path.

State Machine Enforcement

Forward-Only Transitions (Axiom 4.1 — The Arrow of Time)

Transactions follow a strict lifecycle: draft > posted > void

Before this release the database validated allowed status values but did not enforce transition direction. A posted transaction could be reverted to draft. A voided transaction could theoretically be reposted.

A new trigger enforces forward-only transitions at the database layer:

• draft > posted — permitted, subject to existing zero-sum and line-count preconditions
• posted > void — permitted
• All other transitions — fatal exception before execution

Invoices receive equivalent protection. Once issued, an invoice cannot revert to draft.

This enforcement matters for deterministic replay. If transactions can be un-posted, the relationship between transaction state and ledger history becomes ambiguous. The hash chain in Milestone 6 becomes unverifiable.

Threat Closure

Security Posture Change

Financial mutation pathways previously guarded only by application logic are now structurally closed at the database layer.

This release converts several operational guarantees into mechanically enforced invariants (Class O to Class M). Database enforcement ensures the ledger cannot be altered even if application logic fails or is bypassed.

Verification Record

Pre-flight:
  4/4 validation checks clean
  No invalid transaction or invoice states detected
  CASCADE constraints confirmed before migration

Migration:
  COMMIT
  All three invariant validation blocks passed

Post-commit:
  V1  immutability triggers present on transaction_lines
  V2  state machine triggers present on transactions and invoices
  V3  foreign keys converted to RESTRICT

Adversarial review:
  9.6 / 10 Production Gold

Amendment:
  Orphan detection guard added to both immutability triggers

Architectural Context

Kernel invariants are introduced in dependency order. Tenant isolation must precede immutability because immutability of cross-tenant data is not a useful property. Both must precede the monetary domain migration, which operates on a tenant-isolated and immutable schema.

After Milestone 2, three foundational invariants are enforced mechanically at the database layer:

• Tenant isolation — row-level security enforced for all roles including table owners
• Financial immutability — posted records cannot be modified or destroyed
• State machine correctness — transactions and invoices move forward only through their lifecycle

These three properties together make deterministic ledger replay possible.

Operational Impact

Immutability: Posted transaction lines immutable at the database layer. Orphan detection prevents silent corruption.

State machine: Forward-only transaction lifecycle enforced. Invoice reversion to draft prevented.

Data safety: Cascade deletion removed from core financial tables. No deletion path exists for posted transactions by any route.

Deployment: Migration fully transactional. Invariant checks executed inside migration. Adversarial review applied before deployment.

Kernel Status

Files Changed

Backend:

• api/db/migrations/069-milestone-2-immutability-state-machines.sql — transaction line immutability triggers (Axiom 2.1), transaction and invoice state machine triggers (Axiom 4.1), cascade to restrict conversion on core financial foreign keys (Axiom 2.2), structural invariant validation blocks, post-migration verification queries

Milestone 3 — Monetary Domain Migration — introduces integer minor-unit currency representation with deterministic reduction functions and algebraic database constraints.

Why This Matters

The principle of least privilege requires that every component holds only the permissions it needs to function, and nothing more. For a financial application, this is not a best practice — it is a structural security requirement. The database role the application connects as is the most exposed identity in the system: every API request, every authenticated user action, every background job runs under that role. Any privilege it holds that is not needed for legitimate operation is an attack surface.

This release removes three privileges from the application database role that had no legitimate runtime use case. Each represented a distinct and non-trivial risk class.

This finding emerged during the role audit conducted immediately after Milestone 1 deployment, as part of the pre-Milestone 2 verification process. The SpeyBooks database has a clean role architecture: a superuser (postgres) for emergency OS-level operations, a schema owner (william) for DDL and migrations, and an application role for all runtime operations. The application role should hold exactly the four privileges needed for data access: SELECT, INSERT, UPDATE, DELETE. It was holding seven.

Application Role Privilege Reduction

TRUNCATE — Revoked

The most significant of the three. TRUNCATE is categorically different from DELETE: it bypasses row-level security entirely, removes all rows from a table in a single atomic operation, does not fire per-row triggers, and leaves no per-row audit trail. In a multi-tenant system with RLS as the isolation boundary, TRUNCATE is the single operation that renders RLS irrelevant.

There is no legitimate reason for the application runtime to hold this privilege. No API endpoint, no background job, and no business operation requires it. In the hands of a compromised session — a stolen API key, an injection vulnerability, a dependency supply chain attack — TRUNCATE would constitute a complete, immediate, and largely unrecoverable data wipe of a tenant’s financial records.

TRIGGER — Revoked

Allows creating and dropping triggers on tables. Triggers are schema-level DDL: they modify how the database behaves in response to data changes. Trigger management belongs to the schema owner role operating during planned migrations. The application runtime has no business modifying trigger definitions. Holding this privilege created an unnecessary escalation path: a compromised application session could drop an immutability trigger, make changes that would otherwise be blocked, and optionally restore the trigger — leaving no trace in the data of what had been changed.

REFERENCES — Revoked

Allows creating foreign key constraints referencing tables. Foreign key relationships are established at migration time by the schema owner and do not change at runtime. No API operation requires this privilege. It was superfluous and has been removed.

Verified Posture

The application role now holds exactly four privileges across all tables in the accounting schema: SELECT, INSERT, UPDATE, DELETE. Verified by direct catalog query after revocation. No application behaviour is affected — all legitimate runtime operations use only these four privileges.

Role Architecture

SpeyBooks maintains a clear three-tier database role structure:

• postgres — superuser, OS peer authentication only, emergency access
• william — schema owner, runs migrations, holds DDL privileges, cannot be used by the application
• speybooks_app — application runtime, SELECT/INSERT/UPDATE/DELETE only, no DDL, no bypass RLS

The separation between schema owner and application role is the structural control that makes minimum privilege meaningful. The application role cannot modify its own constraints, drop its own triggers, or alter its own policies — because it does not own the schema.

Operational Impact

• Application role reduced from 7 table privileges to 4
• TRUNCATE revoked — RLS bypass via bulk delete eliminated
• TRIGGER revoked — trigger DDL escalation path closed
• REFERENCES revoked — foreign key creation at runtime eliminated
• Minimum privilege posture verified by catalog query
• No application behaviour affected — all runtime operations use only the four retained privileges

Files Changed

Backend: No application code changes. Privilege revocation applied directly to the database role via the schema owner.

Discovered and resolved during the pre-Milestone 2 role audit. The clean role architecture it establishes is a prerequisite for the trigger-based enforcement arriving in Milestone 2 — triggers that the application role can now neither create nor drop.

Why This Matters

Multi-tenant accounting software has one non-negotiable guarantee: a tenant’s financial data must be structurally impossible to read, write, or reassign to another tenant — not merely unlikely, not protected only by application logic, but enforced at the database level regardless of how the application behaves.

Before this release, SpeyBooks enforced tenant isolation at the application layer through row-level security policies that filtered every query by organisation. That protection was real. But it had two structural gaps that this release closes permanently.

The first gap: several tenant-scoped tables had row-level security enabled but not forced. In PostgreSQL, the distinction matters precisely at the boundary where security is most needed — the database owner role. A session operating as the table owner bypasses RLS entirely unless FORCE is set. That means the role used to run migrations, perform administrative operations, or respond to a production incident could read or write any tenant’s data without the policies firing. This was not a theoretical risk. It was the default behaviour.

The second gap: every update policy in the schema was missing a WITH CHECK clause. The USING predicate on a policy controls which rows are visible to a query, but it does not re-evaluate after a mutation. Without WITH CHECK, an UPDATE that passes the visibility check can change the organisation_id of the row it touches — moving a financial record from one tenant to another. The row is visible to the session at the start of the update and belongs to a different tenant at the end. WITH CHECK closes this by re-evaluating the predicate against the post-mutation row state, making any organisation reassignment a fatal policy violation.

Both gaps are now closed mechanically at the database layer, with structural invariants inside the migration transaction that verify correctness and fail closed if any violation is detected.

This release also formalises the complete SpeyBooks kernel architecture as a locked specification — the design foundation all subsequent milestones build on.

Tenant Isolation Hardening

Row-Level Security: Enable and Force (Axiom 1.1)

Row-level security has been enabled and forced on all tenant-scoped tables across the schema. The categorical definition of a tenant-scoped table throughout this work — and encoded in the structural invariant that verifies it — is any table carrying an organisation_id column. This definition is derived from schema structure, not from a developer-maintained name list. A table added in a future migration that carries an organisation_id will be caught by the same invariant automatically.

• FORCE ROW LEVEL SECURITY on all tenant tables Enabling RLS alone is insufficient. Without FORCE, the table owner role — which runs migrations, performs schema changes, and responds to incidents — bypasses all policies. FORCE makes RLS unconditional: it applies to every role, including superusers acting as the table owner. Both ENABLE and FORCE are now required and verified for every tenant-scoped table in the schema.

• Two pre-existing schema defects resolved by invariant checks The structural invariant checks inside the migration surfaced two defects not visible in the original audit. Seventeen tables had been created under a different database role and were not owned by the schema owner, which would have prevented the DDL operations from completing. One table had RLS forced but not enabled — an anomalous and contradictory state that the invariant correctly rejected. The migration failed closed on both, the defects were resolved, and the migration was re-run cleanly. This is the intended behaviour: invariants that catch real problems in production are doing their job.

Update Policy Containment (Axiom 1.2)

• WITH CHECK on all update policies Every update policy now carries a WITH CHECK clause that is identical to its USING predicate. The canonical predicate — organisation_id = current_setting('app.current_org_id')::uuid — is evaluated both before and after every mutation. Any attempt to change the organisation_id of a row will pass the pre-mutation check (the row belongs to the current tenant) and fail the post-mutation check (the row would now belong to a different tenant). The result is a fatal policy violation. This applies to all 25 tenant update policies across the schema.

• Policy name independence The structural invariant that verifies this property checks all UPDATE policies on all tenant-scoped tables, regardless of policy name. An ad-hoc policy added in future without a WITH CHECK clause is caught by the same invariant as any other. The protection is categorical, not name-coupled.

Axiomatic + Categorical Kernel Architecture — Specification Locked

The complete SpeyBooks kernel architecture has been formalised, adversarially reviewed by multiple independent reviewers, and locked as a specification. This is the design foundation all subsequent milestone work is built against. The specification does not describe aspirations — it describes the delivered and target state of the system, with every gap named, classified, and assigned to a milestone.

Design Paradigm: Axiomatic + Schema-Driven Categorical Design

SpeyBooks is a deterministic financial kernel — not a CRUD SaaS application. The design paradigm is Axiomatic + Schema-Driven Categorical Design, which requires two properties simultaneously:

• Mathematical honesty — no claim is made beyond what is mechanically enforced. Where an invariant is partially enforced, that partial status is named explicitly with its upgrade path to full mechanical enforcement stated. There are no security claims that rely on developer discipline.
• Mathematical closure — every threat class has a named axiom enforced at a minimum of two independent layers. Bypassing one layer does not bypass the other. This is the difference between defence-in-depth as a policy and defence-in-depth as a structural property.

Axiom Classification System

Architectural invariants are classified into two tiers that make the current enforcement state of every invariant explicit:

Class M — Mechanically enforced. Violation produces a fatal database exception. No developer action required at runtime. Includes: database constraints, triggers, row-level security policies, and verified build tooling.

Class O — Operationally enforced. Relies on external audit, policy, and incident process. Every Class O axiom carries a named upgrade path to Class M enforcement with a milestone assignment. Class O exists not as a permanent state but as an honest accounting of where enforcement is today.

Monetary Domain Partition

All monetary values in the system are partitioned into three formally distinct domains with no overlap. Domain A: monetary amounts — integer pence, no floating-point, no fractional currency. Domain B: rates — exact rationals reduced to integer pence via deterministic database functions before any value enters the ledger. Domain C: quantities — exact rationals with declared precision constraints. Sub-penny values are prohibited by schema constraint. The monetary domain is closed: no fractional penny can exist anywhere in the reduction chain.

Schema-Derived Type System

The database schema is the single source of truth for both the TypeScript type system and API input validation. Types and validation schemas are generated from the schema, not hand-authored. A dedicated codec layer is the sole location for the snake_case (PostgreSQL) to camelCase (TypeScript) data boundary translation — no business logic is permitted at that layer. Hand-authored types that can drift from the schema are a build failure.

Append-Only Cryptographic Ledger

The ledger architecture uses a per-tenant Merkle chain. Each entry carries a SHA-256 hash over a canonical encoding of its content and the hash of the previous entry. The canonical time axis is the ledger sequence number — a database-generated identity column assigned at commit, not at statement start. Timestamp columns are cosmetic. The chain can be verified from first principles: any tampered entry breaks the chain. This architecture arrives in Milestone 6 but is specified here because Milestones 1 through 5 are prerequisites.

Operational Impact

• Zero tenant-scoped tables with row-level security enabled but not forced — verified by structural schema introspection, not name lists
• Zero update policies on tenant-scoped tables missing or mismatching WITH CHECK — verified across all UPDATE policies regardless of policy name
• Organisation reassignment closed as a mutation pathway — WITH CHECK makes it a fatal policy violation
• Table owner RLS bypass closed — FORCE makes isolation unconditional for all roles
• Two pre-existing schema defects surfaced and resolved by invariant checks before commit — ownership drift across 17 tables, anomalous RLS state on one table
• All DDL changes transactional — full commit or full rollback, no partial application possible
• Fail-fast timeouts prevent hung deployments
• Adversarial review applied across two independent reviewers — four amendments incorporated

Files Changed

Backend:

• api/db/migrations/068-milestone-1-tenant-hardening.sql — ENABLE and FORCE RLS on 5 tables, WITH CHECK on 25 update policies, two structural invariant validation blocks using schema introspection, three post-commit verification queries

Architecture:

• CONST-KERNEL-v2.3-FINAL.md — Kernel constitution, locked. Eight ADRs, six delivery milestones, axiom classification system, monetary domain partition, ledger architecture, verification protocol.
• speybooks-dev-contract-v2.3-FINAL.md — Development contract, locked. Layer boundaries, forbidden patterns, codec layer specification, verification checklist.
• speybooks-schema-audit-report-v2.3-FINAL.md — Schema audit report, locked. 58 findings across six milestones, pre-flight queries, schema anchor sign-off table.

Milestone 1 establishes the tenant isolation foundation. Milestone 2 — immutability and state machine enforcement — follows next.

Why This Matters

Type safety is not cosmetic. In accounting software, an untyped database access is a latent pathway to data corruption, tenant leakage, or silent miscalculation. SpeyBooks was built rapidly with correct runtime behaviour, but the TypeScript type system was not fully leveraged to enforce that correctness at compile time.

This release is a systematic hardening pass across the entire backend. Every any cast was examined for what it concealed — and in most cases, the underlying code was correct but the types were not proving it. The goal: make the compiler verify what was previously only guaranteed by developer discipline.

RLS Centralisation

• System-level queries now flow through a single controlled channel Cross-tenant operations (consensus evaluation, global rule lookups, health checks) previously accessed the database pool directly. All system-level queries now route through a centralised module with structured logging and background query support.

• Standalone jobs documented as architectural exceptions Scheduled tasks that run outside the API server lifecycle are now explicitly annotated, distinguishing intentional direct pool access from accidental bypass.

• Consensus evaluation engine fully migrated The TMADD 2.0 batch evaluation pipeline — which aggregates categorisation votes across all tenants — now uses the system query pattern exclusively, with pool parameter threading removed from all seven internal functions.

Admin Route Typing

• 57 type assertion casts eliminated from admin routes Every (request as any).dbClient, (request as any).user.id, and (request as any).organisationId cast across admin, billing, and verification routes has been replaced with direct typed access via the Fastify declaration layer.

• GDPR cascade deletes migrated to system client Hard-delete operations for users and organisations now use the system client wrapper with automatic transaction management, replacing manual pool connection handling that was typed as any.

• Cache flush operations properly guarded The admin cache-clear endpoint now uses runtime type narrowing instead of unchecked method calls, handling both Map and node-cache implementations safely.

• Pool statistics accessed through the correct interface Admin health diagnostics now read connection pool metrics from the server-level pool instance rather than attempting to access pool properties through a request-scoped client.

Service Layer Typing

• Row-level interfaces introduced for database results Invoice and invoice line queries now return typed row interfaces that match the exact PostgreSQL column shapes. This is the foundation for a systematic snake_case-to-camelCase translation layer.

• Migration engine fully typed All TMADD 7.0 gate checks, state machine transitions, proof assembly, and execution functions now accept typed database clients instead of untyped parameters.

• Rate limiting, duplicate detection, and seed rules typed Utility modules across the library and service layers now use typed Fastify request objects and database clients, eliminating implicit any at function boundaries.

• Error handling standardised Catch blocks across the CSV parser, migration executor, and contact import service now use unknown with instanceof Error guards instead of any, preventing untyped error property access.

Invoice Number Integrity

• Unique constraint added per organisation A compound unique constraint on organisation and invoice number prevents duplicate invoice numbers under concurrent creation. The original global constraint was correctly removed in an earlier migration; this restores the protection at the correct scope.

Operational Impact

• Type safety violations reduced from 300 to 125 (58% elimination)
• Zero direct pool access in request-scoped code paths (excluding documented standalone jobs)
• All admin routes compile-time verified against Fastify declaration types
• Invoice number uniqueness enforced at the database level
• System-level database access consolidated to a single auditable module

Files Changed

Backend:

• api/src/db/system.ts — centralised system query module with background query support
• api/src/db/index.ts — health check migrated to system query
• api/src/lib/consensus-evaluator.ts — full migration to system query, pool threading removed
• api/src/routes/categorisation-rules.ts — typed database client, system query for global rules
• api/src/routes/admin.ts — 20 type assertion casts removed, pool stats corrected
• api/src/routes/admin-additions.ts — 26 casts removed, GDPR deletes migrated to system client
• api/src/routes/admin-bug-reports.ts — 5 casts removed
• api/src/routes/billing.ts — 3 casts removed
• api/src/routes/email-verification.ts — 2 casts removed
• api/src/routes/transparency.ts — 1 cast removed
• api/src/services/invoice-service.ts — row interfaces, 18 field-level casts eliminated
• api/src/services/pdf-service.ts — address interface, 6 casts eliminated
• api/src/services/mwce/gates.ts — typed database clients across 8 gate functions
• api/src/services/mwce/state-machine.ts — typed database client
• api/src/services/mwce/proof.ts — typed database client
• api/src/services/mwce/executor.ts — typed database client, error narrowing
• api/src/services/seed-rules.ts — typed database client
• api/src/services/contact-import-service.ts — typed query result
• api/src/lib/auth-rate-limits.ts — typed request objects across 6 rate limiters
• api/src/lib/metadata.ts — typed parameter arrays
• api/src/lib/bank-import/duplicate-detection.ts — typed database client
• api/src/lib/bank-import/csv-parser.ts — error narrowing
• api/src/scripts/run-consensus.ts — system database initialisation for standalone execution
• api/src/middleware/idempotency.ts — single-winner claim pattern, stale detection
• api/src/types/fastify.d.ts — canonical request augmentation declarations
• api/db/migrations/v5.9.6-unique-invoice-number.sql — compound unique constraint

Known Issues

• 125 type violations remain across route handlers and import pipelines. These are predominantly untyped handler parameters and untyped database result mapping — symptoms of the snake_case/camelCase boundary between PostgreSQL and TypeScript. A systematic translation layer is being designed to resolve these at the architectural level rather than individually.

• The snake_case-to-camelCase translation currently happens in route handlers. Services return raw database rows and routes perform the mapping. The target architecture moves this translation into the service layer via typed mapper functions, allowing routes to receive camelCase domain objects directly.

This release establishes the type safety foundation for the data boundary redesign that will complete the remaining violations architecturally.

Why This Matters

The database is the only irreplaceable asset in the SpeyBooks stack. Code is in git. Config is versioned. Build output is regenerated on every deploy. But if the database is lost without a verified backup, the business is gone.

The previous backup script was a minimal shell wrapper — it dumped, uploaded to S3, and appended a single line to a log. No locking, no verification that the dump was restorable, no structured logging, and a permissions bug that prevented the log file from being written. This release replaces it with a script that treats database backup as the critical operation it is.

Backup Script v2.0.0

• Dump verification After every pg_dump, the script runs pg_restore --list to read the table of contents without restoring. If the dump file is corrupt or truncated, this fails before the S3 upload. No more shipping broken dumps to storage.

• Minimum size check A dump under 1KB is treated as a failure. Catches edge cases where pg_dump exits cleanly but produces an empty or near-empty file.

• flock-based locking Prevents concurrent backup runs. The previous script had no protection against overlapping cron executions or manual runs during a scheduled backup.

• Structured logging Timestamped, levelled log entries with UTC timestamps. Each phase logs its outcome. The summary includes file name, size, S3 path, and local retention count.

• Typed exit codes Lock failure (1), dump failure (2), S3 failure (3), verification failure (4). Ready for external monitoring integration without parsing log files.

• Permissions fix The log directory is now owned by the postgres user, matching the crontab context. The previous setup had root-owned log files that the postgres user could not write to.

What was removed

The restic-based approach was evaluated and rejected. SpeyBooks does not need file-level backup of /var/www or /etc — all code is in git, all config is versioned, and mirroring node_modules to S3 is waste. The backup script focuses exclusively on the database, which is the single irreplaceable asset.

Operational Impact

• Backup cycle completes in under 2 seconds (dump + verify + S3 upload)
• STH op-backups module passes immediately after a successful run
• Corrupt dumps are caught before S3 upload, not after
• Concurrent backup runs are safely prevented
• Log output is parseable by any monitoring tool without regex gymnastics

Files Changed

Infrastructure:

• /usr/local/bin/speybooks-backup.sh — v2.0.0: complete rewrite
• /var/log/speybooks/ — directory ownership corrected to postgres:postgres
• /var/backups/speybooks/postgres/ — staging directory ownership corrected
• postgres crontab — removed log redirect (script handles its own logging)

A verified, restorable backup that runs in two seconds and fails loudly — the foundation everything else depends on.

Why This Matters

The footer trust strip is the only place SpeyBooks makes verifiable security claims to visitors. Until now, those claims were rendered as a monospace text block indistinguishable from static copy. Visitors had no visual signal that the data was live, no proof the grade was earned, and no way to verify claims without leaving the page. One claim — “OpenAPI canonical” — had no verification behind it at all.

This release closes that gap. Every item in the trust strip is now backed by the Security Test Harness, the content contract, or the lock engine. Every claim links to its verification source. And the presentation communicates rigour rather than just asserting it.

Trust Strip Visual Redesign

• Three-domain architecture The trust strip is now a three-column grid separating Security Posture, Jurisdiction & Data, and Technical Integrity into distinct visual domains. Each domain has its own icon, hierarchy, and hover state.

• Shield badge with grade The security grade renders inside an SVG shield. Green for A/A+, amber for B and below. The grade is visible at a glance without reading text.

• Pulsing status dot A CSS-only animated dot signals active monitoring. No client-side JavaScript, no hydration — pure build-time rendering with a CSS animation.

• Module count proof “22/22 modules” shows visitors the grade is earned by an automated harness, not self-awarded. Links directly to the transparency report.

• Every claim is clickable Audit date links to the transparency page. Data Residency links to the security page. Lock links to the changelog. API Surface links to the docs API reference. OpenAPI links to the live spec. Six new verifiable links in total.

• Cross-domain parity maintained Both marketing (Tailwind) and docs (BEM/CSS) renderers updated with identical structure, satisfying I2b ordering parity. Link parity gate now verifies 50 links per page, up from 44.

Footer Component Versions

• Marketing Footer.astro → v6.0.0
• Docs Footer.astro → v3.0.0

OpenAPI Specification Verification

• New STH module: sc-openapi A high-severity module that validates the canonical OpenAPI spec through seven checks: file exists, valid JSON, OpenAPI 3.x version field, required info fields, non-empty paths, operation count consistency with the published endpoint count, and bit-identical comparison between the API source and the docs copy.

• “OpenAPI canonical” is now an earned claim The trust strip previously asserted this without verification. The new module ensures the spec exists, is valid, matches the published API surface, and is identically deployed to docs. If the docs copy drifts from the canonical source, the module fails — not warns.

• STH module count: 21 → 22 The new module sits in the secure-config area alongside TLS, SSH, and environment exposure checks.

Deploy Orchestrator Fix

• Undefined variable bug in trust injection Phase 0b of deploy-ui.sh referenced $BASE and $MKTG_ROOT, neither of which were defined in the script. The trust injection block silently failed on every deployment. Fixed by adding INJECT_TRUST to the configuration block, consistent with the script’s pattern of deriving all paths from named constants.

• Preflight honesty Trust injection now runs before the “All checks passed” message, so the preflight summary accurately reflects what succeeded.

Security Hardening

• Nginx hardening on docs site Added dotfile deny rules and probe path blocking (wp-admin, phpmyadmin, server-status) matching the configuration already in place on the marketing site.

• STH A+ grade tier Added A+ to the grade thresholds (score of 100). Previously, a perfect score still reported as A.

• Production-only npm audit pm-npm-audit.sh v2.0.0 now runs with --omit=dev, auditing only production dependencies. Exception mechanism with expiry dates for known upstream vulnerabilities (xlsx, fast-xml-parser — both expire 28 March 2026).

• Final grade: A+ (100%, 22/22 modules passing)

Operational Impact

• Every trust strip claim is now verifiable in one click
• OpenAPI spec drift between API and docs is a build-failing condition
• Deploy orchestrator trust injection works correctly for the first time
• Security posture upgraded from A to A+ with zero exceptions in production dependencies
• Link parity gate covers 50 links per page across both domains
• No client-side JavaScript added — trust strip animations are CSS-only

Files Changed

Infrastructure:

• deploy-ui.sh — v2.1: fixed undefined variable bug in Phase 0b trust injection
• inject-trust.sh — v1.0.0: STH → footer-data.json bridge (wired and operational)

STH:

• modules/sc-openapi.sh — new module: OpenAPI spec validation (7 checks)
• modules/pm-npm-audit.sh — v2.0.0: production-only audit with exception mechanism
• audit-exceptions.json — documented vulnerability exceptions with expiry

Marketing site:

• src/components/Footer.astro — v6.0.0: three-domain trust strip with shield badge
• src/content/changelog/5.13.1.md — this entry

Docs site:

• src/components/Footer.astro — v3.0.0: matching trust strip for I2b parity
• nginx config — dotfile deny and probe path blocking

These changes close the gap between what the trust strip claims and what the infrastructure can prove — establishing a verifiable trust surface ahead of soft launch.

Why This Matters

The footer is the only UI surface that appears identically on both speybooks.com and docs.speybooks.com. Until now, each site maintained its own footer independently — content drifted, links diverged, and there was no mechanism to detect or prevent inconsistency. For a platform that positions itself on engineering discipline, this was a structural gap.

This release introduces a formally specified shared footer system governed by a single JSON content contract, validated at build time with Zod, synchronised via a deterministic lock token, and rendered through parallel Astro components that share a common logic utility. The footer now includes a three-block institutional trust strip that surfaces security grade, jurisdiction, and integrity metadata — visible only when the security posture warrants it.

A unified deployment orchestrator (deploy-ui.sh) treats all three UI surfaces — marketing, docs, and portal — as a single atomic unit, verifying nine formal invariants before promoting to production.

Shared Footer Architecture

Content Contract (Single Source of Truth)

• footer-data.json drives both sites All footer content — brand, columns, secondary columns, social links, legal metadata — lives in a single JSON file in the monorepo. Both renderers consume it identically. No hardcoded strings in either component.

• Zod schema validation at build time Every build validates footer content against a strict schema. Malformed JSON, empty columns, duplicate labels, or invalid URLs fail the build before deployment.

• Schema version gating Both renderers enforce schemaVersion: 1. A schema change without updating both renderers is a build failure, not a silent regression.

Cross-Domain Build Integrity

• Deterministic lock token (I5b) count-lines.sh now generates a SHA-256 lock token from the version string and git HEAD SHA. This token is embedded in loc.json and verified by the docs footer at build time. If the monorepo deploys a new version without syncing to docs, the docs build fails.

• Lock projection (I5c) The full 64-character hash is stored in data-lock on the <footer> element for audit. The first 8 characters are displayed in the trust strip for human verification.

• deploy-ui.sh orchestration The marketing deploy script generates loc.json, syncs it along with footer-data.json, footer-schema.ts, footer.ts, and footer-logic.ts to the docs site, then builds. The sync is atomic — partial states are prevented.

Shared Logic Utility

• footer-logic.ts eliminates drift Link resolution, current page detection, build date formatting, and security grade gating are now implemented once and imported by both renderers. Context-aware functions accept 'marketing' or 'docs' parameters to handle domain-specific behaviour (e.g. relative links on marketing, resolved links on docs).

Trust Layer (SEC-1)

Three-Block Institutional Trust Strip

• Security Posture Displays security grade, perimeter protection status, and last audit date. All values are build-time injected — no runtime fetches.

• Jurisdiction & Governance Shows jurisdiction, data residency, and ICO registration. Sourced from footer-data.json legal metadata.

• Deterministic Integrity Displays the 8-character lock short-hash and API surface count (endpoints from OpenAPI spec). Signals spec-first architecture without requiring the reader to navigate to the docs.

Grade-Gated Visibility

• Confident or silent The trust strip renders only when gradeRank >= 4 (security grade A or A+). Below that threshold, the entire strip is omitted. No degraded state is ever shown to users.

• Numeric rank model Grades use a numeric mapping (A+: 5, A: 4, B: 3, C: 2, F: 1) to prevent the lexicographic misclassification bug where "B" > "A+" in string comparison.

Unified Deployment Orchestrator

deploy-ui.sh — Lock-Sync-Build-Gate-Promote

A new production-grade orchestrator treats all three UI surfaces as a single deployment unit, eliminating the distributed build race condition where marketing and docs could deploy with different footer content.

• Five-phase pipeline Preflight, Lock, Sync, Build, Gate, Promote — with --dry-run and --skip-portal flags for safe testing and footer-only changes.

• Nine formal invariants verified at deploy time I1 (single source), I2 (link count parity), I2b (link ordering parity), I5 (version equality via lock), I5b (lock equality), I5c (lock projection), I6 (docs resolution totality), I7 (schema version safety), T3 (race elimination).

• Multi-page lock sampling Extracts data-lock from multiple rendered pages per site (index plus one deep page), verifying consistency across page layouts. Detects multi-lock corruption where a page accidentally renders two different footer instances.

• Link parity gate Extracts footer hrefs in DOM order from rendered HTML, compares ordered sequences across domains after resolving marketing relative links to absolute. Verifies docs has no unresolved relative hrefs. Works correctly on minified single-line HTML by targeting <footer role=contentinfo> with PCRE substring extraction.

• rsync safety model Only marketing rsyncs to a separate production root. Docs and portal serve dist/ in-place. Pre-promotion safety checks prevent rsync into source directories.

• Configurable and auditable DEPLOY_OWNER environment variable, Node/pnpm version logging in banner, atomic file sync via tmp-then-rename, and schema version constant for upgrade tracking.

Docs Landing Page Fixes

Card Grid Restoration

• Three-column grid restored The .sd-card-grid base rule was missing from speydocs.css — only responsive media query overrides existed. Without the base display: grid; grid-template-columns: repeat(3, 1fr) rule, cards defaulted to block layout (single column). Added the missing base rule. Responsive collapse to 2 columns (769-1024px) and 1 column (below 768px) now works correctly.

Footer-Below-Fold Layout

• Correct flexbox architecture The .sd-landing container now uses flex: 1 0 0% (not auto) so flex-grow claims all remaining viewport space, pushing the footer below the fold on 1080p displays. Hero padding reduced from 72px 24px 44px to 48px 24px 32px, reclaiming 36px of vertical space without sacrificing design.

• .sd-cards-section fills remaining space Uses flex: 1 0 auto to grow into available space after the hero, with padding: 20px 24px 80px for breathing room above the footer.

Footer Design (Wireframe v3)

Layout & Responsive Behaviour

• Five-column primary grid Brand + tagline + social icons, then Product, Developer APIs, Legal, and Service columns. Collapses to 2 columns at 640px and 1 column below that.

• Secondary columns centred SpeyTech and Open Source columns align to grid positions 2-3 on desktop, using explicit grid-column placement rather than fragile spacer divs.

• Trust strip centred on desktop, stacked on mobile Blocks wrap naturally on smaller screens. white-space: nowrap applies only above 640px to prevent horizontal overflow.

Bottom Bar

• Version and build date Version links to the changelog. Build date uses ordinal formatting (“Saturday 28th of February 2026”) via the shared utility.

• Status indicator Animated ping dot with “All Systems Operational” link. Single green dot — the only colour element in the footer.

• Legal metadata Copyright, jurisdiction, data location, ICO registration, and support email.

Accessibility

• Landmark role — <footer role="contentinfo"> (A11Y-1)
• Per-column navigation groups — each column wrapped in <nav aria-label="Footer navigation — {heading}"> (A11Y-2)
• Focus rings — 2px solid outline with 2px offset on all interactive elements (A11Y-6)
• aria-current="page" — computed at build time via shared isCurrentPage(), with constraint that at most one link across the entire footer carries this attribute (A11Y-5)
• Trust region — role="region" aria-label="Security and trust information" with non-interactive content (no focus traps)

Operational Impact

• Zero content drift between marketing and docs footers
• Build failure on schema violation, version mismatch, or missing lock token
• Deterministic lock token prevents stale cross-domain deployments
• Nine formal invariants verified before every production promotion
• Link ordering parity enforced across domains at deploy time
• Trust strip omitted automatically when security grade drops below A
• Single utility file governs all shared logic — no duplicated implementations
• Docs landing page card grid restored to 3-column layout with correct responsive breakpoints
• Footer below fold on standard 1080p displays
• 118,120 lines of code across the platform, 198 endpoints across 31 resources

Versioning

• Marketing Footer.astro → v5.1.0
• Docs Footer.astro → v2.1.0
• sd-footer.css → v3.0.0 (full rewrite, BEM naming, trust layer)
• footer-logic.ts → v1.0.0 (new shared utility)
• count-lines.sh → SD-BUILD-LOC-1.2 (lock token generation)
• deploy-ui.sh → v2.1 (new unified UI orchestrator)

Files Changed

Backend: None

Frontend / Marketing site:

• src/components/Footer.astro — v5.1.0

  • Rewritten to consume footer-data.json content contract
  • Zod validation and schema version gating at build time
  • Trust layer with SEC-1 three-block architecture
  • Lock token imported from loc.json
  • Shared logic imported from footer-logic.ts

• src/data/footer-data.json — content contract (schemaVersion 1)

• src/data/footer-schema.ts — Zod validation schema

• src/types/footer.ts — TypeScript type definitions

• src/utils/footer-logic.ts — shared logic utility

• scripts/count-lines.sh — SD-BUILD-LOC-1.2

  • Lock token generation added (SHA-256 of version + git SHA)
  • loc.json output now includes lock field

Frontend / Docs site:

• src/components/Footer.astro — v2.1.0

  • Rewritten to match wireframe v3 with BEM class naming
  • Lock token verification from loc.json
  • Shared logic imported from footer-logic.ts
  • Secondary columns use explicit grid-column placement

• src/styles/sd-footer.css — v3.0.0

  • Complete rewrite: BEM naming, token contract, trust layer styles
  • Responsive collapse algebra: 1 → 2 → 5 columns
  • Status ping animation, focus ring tokens

• src/styles/speydocs.css

  • Added missing .sd-card-grid base rule (3-column grid)
  • Removed duplicate .sd-card stub
  • .sd-landing flex basis changed from auto to 0% for footer-below-fold
  • .sd-hero padding reduced for shorter viewport accommodation
  • .sd-cards-section flex-grow for remaining space fill

• src/data/footer-schema.ts — synced from monorepo

• src/types/footer.ts — synced from monorepo

• src/utils/footer-logic.ts — synced from monorepo

Infrastructure:

• /var/www/deploy-ui.sh — v2.1 (new)
  • Unified UI orchestrator: Lock-Sync-Build-Gate-Promote
  • Nine-invariant integrity gate with multi-page sampling
  • Link parity and resolution verification across domains
  • Handles minified HTML via PCRE role=contentinfo targeting
  • --dry-run and --skip-portal flags
  • Configurable ownership, atomic sync, rsync safety guards

Known Issues

• Trust layer values (security grade, audit date, perimeter status) are currently hardcoded placeholders. STH integration is the next step — the gating logic is production-ready, only the data source needs wiring.
• “OpenAPI canonical” in the trust strip is plain text — will become a link to docs.speybooks.com/openapi.json in a follow-up.
• The data-git-sha audit attribute is not yet exposed on the <footer> element.

This release establishes the architectural foundation for cross-domain UI parity, moving the footer from an independently maintained component to a formally verified shared contract — and the deployment pipeline from independent builds to invariant-gated atomic promotion. The same engineering discipline applied to the API surface is now applied to the presentation layer and its deployment lifecycle.

Why This Matters

The changelog is one of the most content-rich pages on the marketing site, with 111 releases documented across four major versions. Until now, every release existed as a section inside a single page — invisible to search engines, unshareable as individual documents, and lacking per-release metadata.

This release promotes each changelog entry from a page fragment to a first-class document with its own canonical URL, structured data, and link preview. It also establishes the description field as a forward-looking enrichment for RSS subscribers and search engines.

Canonical Per-Release Pages

Every changelog entry now renders as its own page at /changelog/{releaseSlug}/.

• 111 release pages generated at build time Each entry in the changelog content collection produces a static HTML page with full rendered markdown content, breadcrumb navigation, and consistent typography matching the changelog index.

• JSON-LD structured data Every release page includes a SoftwareSourceCode schema with version, date, author, and publisher metadata. We use SoftwareSourceCode to model versioned releases as indexable software updates; this is stable and machine-readable across search surfaces.

• OpenGraph and meta tags Each page has distinct og:title, og:description, og:url, and article:published_time tags, enabling rich link previews in Slack, iMessage, Twitter/X, and other sharing surfaces.

• Build-time collision guard getStaticPaths() detects duplicate slugs and fails the build rather than silently overwriting pages. Invalid data never deploys.

• Trailing slash standardisation Canonical URLs use a trailing slash to match site routing and avoid duplicate indexable variants.

Slug Infrastructure

• releaseSlug frontmatter field Each entry has a URL-safe slug derived from version number and title keywords. Named releaseSlug (not slug) to avoid collision with Astro’s reserved slug property on content collection entries.

• Backfill automation add-changelog-slugs.mjs generated slugs for all 111 existing entries in a single run. The script is idempotent — safe to run multiple times, skips entries that already have a releaseSlug.

• Schema validation The content schema enforces slug format (^\d+-\d+-\d+(-[a-z0-9]+)*$) and date format (YYYY-MM-DD) at build time. Malformed frontmatter fails the build.

The URL segment is referred to as slug in routing ([slug].astro) and is sourced from the releaseSlug frontmatter field.

RSS Canonical Permalinks

RSS entries now resolve to stable, dereferenceable permalinks instead of fragment-based anchors.

• Canonical <link> and <guid> Both now point to /changelog/{releaseSlug}/ instead of /changelog/#vX.Y.Z, giving each RSS item a permanent, dereferenceable URL with isPermaLink="true".

• Per-item descriptions Every RSS item now includes a <description> element. New entries use the enriched description frontmatter field; existing entries fall back to a title-based summary.

Description Enrichment

A new optional description frontmatter field provides a 1–2 sentence summary of what changed and why.

• Three audiences served simultaneously The description appears in RSS feed readers, search engine result pages (as meta description), and link previews when sharing release URLs.

• Forward-looking adoption The field is optional to avoid breaking the 111 existing entries. All new releases from v5.12.0 onwards include an enriched description that adds signal beyond the title.

• Preview-safe constraint description is capped at 200 characters to remain readable in RSS readers and link previews.

Changelog Index Wiring

The changelog index page at /changelog/ now links each release through to its canonical page.

• Version number links The v5.11.0 version badge now navigates to /changelog/5-11-0-speydocs-production-gold-search-hardening-footer-redesign/ instead of self-referencing with a #v anchor.

• Title links Release titles are now clickable, navigating to the same canonical page with a subtle hover transition.

• Legacy anchors preserved Each <article> retains its id="v5.11.0" anchor, so existing external links and in-page scrolling continue to work.

Compatibility

• Legacy fragment URLs (/changelog/#vX.Y.Z) continue to resolve via preserved <article id="vX.Y.Z"> anchors on the index page.
• Canonical URLs (/changelog/{releaseSlug}/) are now the preferred share and RSS targets.

Operational Impact

• 111 individually indexable release pages with distinct OpenGraph previews
• JSON-LD SoftwareSourceCode structured data on every release page
• RSS items with stable canonical permalinks and meaningful descriptions
• RSS <description> derived from frontmatter, improving feed readability without requiring click-through
• Build-time validation prevents malformed slugs, dates, or duplicate routes from deploying
• Zero breaking changes to existing changelog content or external links

Files Changed

Backend: None

Marketing site (speybooks.com):

• src/content/config.ts

  • Added description (optional string, max 200 chars)
  • Added releaseSlug (optional, regex-validated)
  • Added date format validation (YYYY-MM-DD)

• src/pages/changelog/[slug].astro — new file

  • Per-release page template with JSON-LD, OpenGraph, tag badges
  • Build-time slug collision detection
  • Light theme typography matching changelog index

• src/pages/changelog/rss.xml.ts

  • Canonical slug URLs for <link> and <guid>
  • <description> from frontmatter with title-based fallback

• src/pages/changelog/index.astro

  • Version and title now link to canonical release pages
  • Added getSlug helper for releaseSlug resolution

• add-changelog-slugs.mjs — new file

  • Backfill script: generated releaseSlug for 111 existing entries

• src/content/changelog/*.md

  • All 111 entries updated with releaseSlug field

This release establishes the changelog as a versioned document system — each release independently addressable, machine-readable, and built to scale with the platform.

Why This Matters

Search is the primary navigation surface for developer documentation. Hardening the search kernel improves resilience under mobile network conditions, guarantees ARIA state correctness, and ensures that the documentation shell remains deterministic under rapid user interaction.

These changes eliminate edge-case state corruption and formalise SpeyDocs’ search layer as production-grade infrastructure rather than a decorative interface element.

Search & Enhancement Layer Hardening

A focused audit of the SpeyDocs search kernel (search.js) and progressive enhancement layer (enhance.js) identified five functional defects and three architectural fragilities. All issues have been resolved and regression-tested across desktop and mobile browsers.

Functional Fixes

• Stale search no longer fires into a closed modal
  Pressing Escape during the 120 ms debounce window previously allowed a queued search to execute after the modal closed, corrupting ARIA expanded state on a hidden combobox. The close handler now cancels the pending debounce timer.

• Single corrupt result no longer blanks the entire set
  Pagefind result hydration previously used Promise.all, meaning one failed result discarded all results. The implementation now uses Promise.allSettled with fulfilled filtering, ensuring partial failure degrades gracefully.

• Search excerpt truncation corrected
  CSS line-clamp rules were missing display: -webkit-box, causing excerpts to overflow instead of truncating to two lines. The missing declaration has been added.

• Mobile search modal height corrected (iOS Safari)
  A duplicate CSS rule used 100vh instead of the --sd-vh viewport unit, causing clipping when the dynamic Safari toolbar collapsed or expanded. The duplicate rule has been removed, leaving a single authoritative mobile search height definition.

• Duplicate .sd-search-esc rule removed
  A legacy standalone selector duplicated styles already defined in .sd-search-close, .sd-search-esc. The redundant block has been removed.

Architecture Improvements

• Viewport height ownership consolidated
  enhance.js now exclusively owns the --sd-vh CSS custom property. search.js previously computed and set this independently on modal open, introducing coordination risk. The search module now reads the token without mutating it.

• Sidebar focus trap yields to active modal dialogs
  When both the mobile sidebar and search modal were open, focus traps could conflict. The sidebar trap now detects an active aria-modal="true" dialog and yields control, preventing cross-trap collisions.

Landing Page Search Rewrite

The documentation landing page search trigger (docs.speybooks.com) has been rebuilt for reliable cross-platform behaviour.

• Button replaces readonly input
  The landing search bar is now a <button> rather than an <input readonly>. iOS Safari may suppress keyboard activation and ignore pointerdown events on readonly inputs, preventing reliable modal activation. Buttons emit consistent click events across touch, mouse, switch-access, and screen reader environments.

• Container-level event binding
  The click listener binds to the .sd-landing-search container rather than a child element. Tapping anywhere within the search surface (icon, label, or shortcut badge) opens the modal.

• Cache-busting script versioning
  enhance.js and search.js now include versioned query suffixes (e.g., ?v=1.1.0, ?v=1.2.0) to ensure browsers immediately fetch updated assets after deployment.

Footer Redesign

The documentation landing page footer has been redesigned to match the marketing site (speybooks.com), ensuring visual and structural continuity across properties.

• Four-column grid layout
  Brand, Product, Developers, and Legal columns replace the previous flat link row.

• Cross-site link taxonomy
  Product and Legal columns link to marketing site pages. Developer links remain within the documentation domain.

• Consistent bottom bar
  Status indicator, copyright line, and dynamic build date now match the marketing site.

• Responsive behaviour
  Grid collapses from four columns to two at ≤768px, mirroring the marketing site layout.

Operational Impact

• Zero ARIA state corruption under rapid open/close interaction
• Graceful degradation when Pagefind hydration partially fails
• Mobile Safari search modal no longer clipped by dynamic toolbar
• Elimination of duplicate CSS and dead selectors
• Reduced layout fragility via single-source viewport height ownership
• Verified across iOS Safari, Chrome (Android), macOS Safari, and Chromium-based desktop browsers

Accessibility

All changes were validated against the ARIA combobox and listbox state machine. The search modal guarantees clean state on close and prevents cross-trap focus conflicts with the sidebar.

The landing search trigger is accessible to switch-access devices and screen readers via semantic button markup and container-level event handling.

Versioning

• search.js → v1.2.0
• enhance.js → v1.1.0

Versions increment due to behavioural changes in concurrency handling, event binding, and focus trap coordination. No public API surface has changed.

Files Changed

Backend: None

Docs site (docs.speybooks.com):

• public/js/search.js — v1.2.0

  • clearTimeout on close
  • Promise.allSettled hydration
  • container-level event binding
  • viewport ownership removed

• public/js/enhance.js — v1.1.0

  • sidebar focus trap yields to active modal

• public/css/speydocs.css

  • excerpt line-clamp correction
  • duplicate mobile rule removed
  • duplicate .sd-search-esc rule removed
  • footer grid layout
  • landing search button styles

• src/pages/index.astro

  • semantic button search trigger
  • footer redesign
  • cache-busting script tags

These changes establish a hardened foundation for future expansion of SpeyDocs search across API, SDK, and guide content domains.

Quote Preview API

• New endpoint: POST /quotes/preview — calculates line totals, VAT, and quote total without persisting. Supports decimal quantities and uses Decimal.js arithmetic to match the create route exactly.
• API documentation — full SpeyDocs entry with curl examples, parameter descriptions, and sample response. Appears under Quotes in the docs site.

Server-Side Calculation Enforcement

• Quote creation — the new quote form now uses the backend preview endpoint for all line-level and summary calculations. The frontend no longer performs any VAT or monetary arithmetic.
• Quote editing — edit mode on the quote detail page uses the same backend preview. Totals update live as you modify line items.
• Invoice editing — edit mode on the invoice detail page now uses the existing /invoices/preview endpoint, replacing the previous client-side calculation.
• Decimal quantity support — quote preview accepts fractional quantities (e.g. 1.5 hours), matching what the create endpoint already supports.

Currency Boundary Fixes

• Unit price display in edit mode — when editing an existing quote or invoice, unit prices now display correctly in pounds rather than raw pence values.
• Unit price submission — form submission now converts pounds to pence consistently via toPence(), fixing a latent boundary bug where pounds could be sent where the API expects minor units.

Form State Stability

• Event-driven hydration — quote and invoice edit forms now populate via an explicit user action rather than a background effect. This prevents unsaved changes from being overwritten if the browser refreshes data in the background.
• Select component — resolved the “changing from uncontrolled to controlled” React warning globally. The Radix UI Select primitive now stays in controlled mode for its entire lifecycle.
• VAT rate guard — selecting an account no longer clears the VAT rate dropdown when the account’s default rate doesn’t match a standard option.

Dashboard

• Chart aggregation clarity — revenue trend and status donut calculations are now clearly documented as visualisation-only, separated from accounting logic.

Code Quality

• Frontend linter: zero violations — the custom linter now reports 0 errors and 0 warnings across the entire frontend codebase. All temporary suppressions from the currency consolidation work have been removed, with only permanent suppressions remaining for legitimate chart aggregations.

Bug Fixes

• Fixed quote and invoice edit forms sending unit prices in pounds instead of pence on save.
• Fixed unit price fields showing pence values (e.g. 10000) instead of pounds (e.g. 100.00) when entering edit mode.
• Fixed Select component causing React state warnings across all pages using dropdowns.

Custom Linter

SpeyBooks now has a bespoke Python linter enforcing the principle that the frontend is a view layer — all monetary calculations belong on the backend. The linter runs across both frontend and backend codebases with distinct rule sets.

• Frontend rules — detects client-side monetary aggregation, VAT calculations, debit/credit arithmetic, rounding on currency values, and inline pounds-to-pence conversions.
• Backend rules — enforces Row Level Security (all queries via request.dbClient, never pool.query), structured error handling, and logging via Fastify’s request logger.
• Universal rules — catches hardcoded secrets, console logging, and overly broad exception handlers.
• Inline suppression — // lint-ignore FE003 on the preceding or same line, with file-level // lint-ignore-file for generated files and sanctioned utilities.

The linter integrates into CI with exit code 1 on any unsuppressed error.

Currency Boundary Consolidation

All inline pounds-to-pence conversions (Math.round(parseFloat(x) * 100)) and pence-to-pounds display formatting ((pence / 100).toFixed(2)) have been replaced with two centralised utility functions.

• toPence() — the single sanctioned conversion from form input (pounds) to integer pence, used at every form submission boundary.
• penceToPounds() — converts integer pence back to a pounds string for form input pre-fill, without a currency symbol.
• formatMoney() — existing utility now used consistently across all toast messages and display contexts.

This eliminates 16 scattered conversion patterns across 9 files and ensures every monetary boundary goes through tested, lint-enforced code.

API Client Correction

• invoicesApi.recordPayment() — now accepts pence directly, matching the API contract. The pounds-to-pence conversion moved to the form boundary where it belongs.

Bug Fixes

• Fixed parseInt() used instead of parseFloat() for refund amounts in the admin panel — partial-pound refunds were silently truncated.

Known Issues

• Invoice and quote edit modes still compute VAT client-side for live preview. Suppressed with documented rationale. The production fix requires wiring useDocumentPreview into edit modes and creating a /quotes/preview endpoint. Scheduled for a future release.

Docs Landing Page

Revised the hero copy on docs.speybooks.com to better reflect the documentation site’s purpose as a wayfinding page rather than a marketing surface.

• New headline — “Deterministic accounting, specified as an API.” replaces the previous title, avoiding repetition of the brand name already present in the logo.
• Constraint-style subtitle — “Schema-validated. Versioned. Formally ordered.” Three declarative statements that read like a spec header, not a sales pitch.
• Stats badge — resource and endpoint counts now display in a pill badge below the search bar, matching the visual language used on the features page.
• Tightened vertical rhythm — reduced spacing between headline and subtitle, increased spacing before the search bar, creating a clearer separation between the statement block and the search tool.
• Removed redundant copy — the previous trust line and monospace stats line replaced by the single badge, reducing visual noise around the search bar.

All changes apply to both light and dark themes. Badge tokens follow the existing design token system with no raw hex values.

Marketing Site Copy — Engineering Voice Pass

A full copy review pass across the five main marketing pages, assisted by a structured GPT session with a calibrated prompt. The goal: remove abstract virtue language, replace rhetoric with mechanism, and ensure tax-adjacent copy is clearly framed as tooling rather than advice.

What Changed

Hero & Features Grid

• Subtitle rewritten — “A programmable accounting engine for UK developers who want control, correctness, and a clean API” replaced with a mechanically descriptive summary: double-entry enforced by PostgreSQL triggers, OpenAPI-described REST API, VAT returns (Box 1–9), zero floating point.
• Abstract virtues removed — “clean”, “control”, “correctness”, “Everything you need” replaced with constraint-based language throughout.
• Evidence trail specificity — Auto-categorisation copy now states what is stored per decision: rule ID, field, operator, and reason. Previously “full evidence trail” was unspecified.
• Trigger vs CHECK constraint — Code snippet and SVG alt text corrected to reflect the actual PostgreSQL trigger mechanism rather than a CHECK constraint.
• Migration copy — “Mathematical proof” replaced with the actual verification mechanism: trial balance equality and closing balance checks that block execution unless opening balances reconcile to the penny.
• “Self-Improving” renamed to “Rule Generalisation” — the mechanism is accurate; the label was ML-adjacent abstraction.
• Section header — “Production-ready from day one” replaced with “Complete feature set”.

Features Page

• Hero paragraph — four concrete constraints replace three abstract virtues.
• Ltd company section — heading and intro reframed as tooling, not advisory. Explicit disclaimer added: “These features calculate statutory amounts based on current rules. SpeyBooks does not provide tax, accounting, or legal advice.”
• DLA Tracking card — S455 rate (33.75%), BIK at HMRC official rate (average method), and P11D deadline tracking now explicit.
• Year-End Snapshots card — S455 deadline calculation (9 months + 1 day after period end) surfaced.
• Connected persons — spouse, child, parent, associate relationships named in Safety Checks card.
• Tax Set-Aside card — “Always know how much is actually yours to keep” removed; replaced with “Calculated for reference — not tax advice.”
• API Request Log — “Stripe-level observability” replaced with the actual retention fields: headers, bodies, timing, IP, status code.
• “Helpful errors” → “Structured errors”.
• VAT card — “(MTD-compatible export)” added for consistency.

Pricing Section (React island)

• Heading — “Simple, flat pricing” replaced with the prices directly: “£15/mo sole trader. £25/mo limited company.”
• Usage traps — “No usage traps” → “No per-invoice fees. No per-user pricing.”
• DLA features — expanded from one line to six, surfacing S455 exposure (33.75%), BIK at HMRC official rate, connected persons aggregation, DLA snapshots, and deadline tracking.
• Tax disclaimer added below Ltd feature list.
• “MTD-ready” → “MTD-compatible export” throughout.

Pricing Page (static)

• MTD wording standardised to “MTD-compatible export” in Reports section and FAQ.
• DLA “warnings” → “S455 exposure (33.75%) and BIK calculations (HMRC average method)”.
• Corporation tax → “Estimated Corporation Tax set-aside (19%/25% marginal rates)”.
• Bank import → “Bank CSV import (schema auto-detected, Smart Map overrides)”.
• Export language → “Full ledger export via API, CSV, or SQL”.
• Pagination label corrected from “Cursor pagination” to “Page-based pagination” to match actual page/per_page response format.
• Meta description — “UK tax compliance” → “UK tax features” (avoids unqualified compliance claim).
• Dashboard — “real-time data” → “reads directly from the ledger — no delayed sync” (confirmed: localhost PostgreSQL, no caching layer).

About Page

• Audience paragraph — shifted from demographic labels to behaviour: “generate invoices from code, reconcile transactions programmatically, export their ledger without permission or proprietary tooling.”
• Bank import card — “Universal” and “any bank’s CSV” removed; “proves” → “verifies row conservation and balance integrity before committing the import.”
• Privacy principle card — now names self-hosted Umami explicitly; adds “Full ledger export via API, CSV, or SQL.”
• Ltd company card — “real-time S455 exposure” → statutory rate (33.75%) and HMRC official rate, consistent with other pages.
• locData import restored — endpoint and resource counts are now dynamic, sourced from loc.json regenerated on each deploy.

Tax & Advisory Containment

This pass explicitly contains advisory risk across all pages. Tax-adjacent features (VAT, MTD, S455, BIK, dividends, corporation tax set-aside) are now consistently framed as calculation aids with explicit non-advisory language. The Features page Ltd section carries a visible disclaimer. Individual cards use “for reference — not tax advice” or “for review with your accountant” throughout.

Sidebar Chevron Indicators

• SVG replaces Unicode character — the sidebar disclosure indicator now uses an inline SVG chevron instead of the Unicode ▸ glyph. The previous character rendered as an ambiguous dot on iOS Safari and varied across platforms. The SVG renders pixel-perfect on every browser and device, with hardware-accelerated rotation animation between collapsed and expanded states.

Mobile Scroll Stability

• Sidebar scroll position preserved across page navigation — clicking a link in the sidebar no longer resets the scroll position to the top. Position is saved before navigation begins and restored seamlessly using a visibility-based anti-flicker pattern.

• Light theme flash eliminated — a brief flash of unstyled content on the light theme during scroll restoration has been resolved. The sidebar is now hidden with visibility: hidden during the restore window, preventing any bleed-through.

• iOS Safari URL bar jitter resolved — on iOS Safari, scrolling triggers the URL bar to collapse, which fires a resize event and recalculates the viewport height mid-scroll. The resize handler now only recalculates when the viewport width changes (device rotation), ignoring vertical-only resize events caused by the URL bar animation.

API Reference Documentation

Five new reference pages in the API Reference section, all with scroll-synced code panel examples:

• Authentication — covers API key authentication via X-API-Key header, JWT bearer token login flow, two-factor authentication (TOTP) with the full temporary token handshake, token refresh, scoped permissions table, account lockout behaviour, and security recommendations.

• Errors — documents the error response envelope, all HTTP status codes and error codes, idempotency error behaviour, and a five-point integration guide for handling errors programmatically.

• Pagination — covers request parameters, response metadata, a JavaScript iteration example, sorting and filtering patterns, empty result handling, and rate limiting considerations.

• Conventions — describes the response envelope, prefixed ID system, monetary values in minor units, ISO 8601 date formats, custom metadata with merge semantics, idempotency keys, content type requirements, and the versioning policy.

• Rate Limiting — documents the default 100 requests per minute limit, per-endpoint auth rate limits (login, TOTP, refresh, registration, password reset, email verification), response headers, and an exponential backoff example.

Static Content Pipeline

• API Reference pages migrated to static Markdown — all API Reference preamble pages now use the same static page pipeline as Getting Started, Concepts, and Guides. Content lives in api-reference/*.md files with full frontmatter support for code blocks and scroll sync points. New pages can be added by dropping a Markdown file into the directory.

• Sidebar now merges static and preamble sources — the API Reference sidebar section pulls pages from both the static Markdown pipeline and the OpenAPI snapshot, with automatic deduplication. Static pages are sorted by sidebar_position frontmatter.

• Getting Started authentication route fix — renamed the Getting Started authentication tutorial to avoid a route collision with the new API Reference authentication page.

SEO Foundations

The documentation site at docs.speybooks.com now ships with proper search engine metadata across all 273 pages.

• Canonical tags — every page declares its canonical URL, preventing duplicate content indexing.
• Open Graph tags — title, description, URL, type, and site name are set for every page, improving link previews on social platforms.
• JSON-LD schema — the homepage includes structured WebSite data with publisher and author markup for richer search results.
• Title truncation — page titles are capped at 66 characters to display cleanly in search results, accounting for multi-byte characters.

Duplicate Content Cleanup

• Resource landing pages — API reference titles now include “API Reference” to differentiate from guide pages with similar names.
• Ghost route removed — a legacy /api/introduction/ path that duplicated the API overview now redirects to /api/.
• Redundant guide removed — a duplicate “How It Works” page was consolidated into the existing “Your First Invoice” guide.

Accessibility (WCAG AA Compliance)

Lighthouse accessibility score is now 100 on both mobile and desktop.

• Colour contrast — twelve colour tokens across light and dark themes were adjusted to meet WCAG AA 4.5:1 minimum contrast ratios, keeping the Spey blue aesthetic intact. Every token was verified computationally against its background.
• Link distinguishability — prose and description links now carry a persistent underline with a subtle colour tint, strengthening on hover.
• Form field attributes — the search modal input now includes id and name attributes, resolving browser autofill warnings.

Heading Hierarchy

• API reference pages — section headings corrected from h3 to h2 across 198 pages, resolving heading level skip warnings with zero visual change.

Performance

• Layout reflow eliminated — the enhance.js initialisation now batches all DOM reads before writes and defers viewport height correction via requestAnimationFrame, removing a 40ms forced reflow from the critical path.
• Resize debouncing — window resize events are coalesced into a single animation frame using cancelAnimationFrame, preventing layout thrashing during drag-resize.
• bfcache scroll restore — sidebar scroll position now restores correctly on back/forward navigation via the pageshow event, using a double-rAF technique to avoid reflow when setting scrollTop after layout invalidation.
• Font loading strategy — switched from font-display: block to font-display: swap with a metrics-matched Inter Fallback font face (size-adjust: 107%, ascent-override: 96.9%). Text now paints immediately using the fallback, with zero layout shift on swap. Eliminates the 220ms LCP render delay on the introduction page.
• Non-composited animation — added will-change: transform, opacity to the landing page status ping animation, promoting it to the compositor layer.
• Module preload — search.js is now preloaded via <link rel="modulepreload">, collapsing the critical request chain from sequential to parallel loading.

Mobile Ergonomics

• Fluid typography — font size tokens scale up inside the mobile breakpoint (--sd-text-base from 14px to 16px, --sd-text-xs from 11px to 12px), improving readability on phone screens without adding any new CSS classes.
• Touch targets — sidebar links widened to 12px 14px padding, search trigger expanded from 36px to 44px height, collapsible category titles given min-height: 44px, and search results spacing increased to prevent misclicks.
• Mobile panel depth — the slide-out sidebar now uses a box-shadow instead of a flat border, giving the drawer a premium floating appearance.

Sidebar Modernisation

• Active state — replaced the heavy blue background fill with a subtle gray background and a 3px left accent line in Spey blue (box-shadow: inset 3px 0 0 0). Matches the Stripe/Vercel pattern.
• Search pill — the search trigger now uses a transparent border with a soft background, revealing the border on hover rather than starting with a hard outline.
• Category labels — letter-spacing tightened from 0.08em to 0.04em and the bullet glyphs removed from top-level section titles, creating a cleaner visual hierarchy.
• Link spacing — added margin: 2px 0 between sidebar links for breathing room.

Stylesheet Maintenance

• Duplicate section removed — a duplicate Section 27 (Landing Page) block was stripped, reducing the stylesheet by 290 lines with no functional change.

Lighthouse Scores (Mobile, Slow 4G)

API Documentation Guides — Full Coverage

Completed the remaining four guide pages for docs.speybooks.com, bringing the static documentation to 23 pages covering the entire API surface.

• Invoices & Quotes — full invoice lifecycle state machine, quote-to-invoice conversion, payment recording, PDF generation, and email delivery. Covers both vatTreatment enums (transaction lines vs categorisation endpoint).
• Contacts & Directors — contact types with inclusive filtering, metadata merge semantics, safe deletion behaviour, director shareholding, connected persons for S455 aggregation, and the resign workflow.
• Transactions & Journals — the absolute balance constraint, VAT annotation system (tax reporting metadata, not balancing lines), draft/posted lifecycle, bank import categorisation, and the account ledger.
• Opening Balances — the OBCE 5-tier mapping strategy, balance proof with rounding injection, clearing mode for outstanding document imports, the singleton constraint, and the triple confirmation gate.

All guides validated against source code and cross-referenced with endpoint schemas.

Docs Site Rendering Fixes

Resolved two visual flicker issues on the documentation site.

• Light mode FOUC eliminated — moved theme initialisation from the external enhance.js into an inline <head> script that runs before CSS parse. The browser now applies the correct colour palette on the first frame. Also respects OS prefers-color-scheme for new visitors who have not toggled manually.
• Sidebar jitter eliminated — added @font-face declarations with font-display: block for Inter and JetBrains Mono, matching the self-hosted font filenames. Added <link rel="preload"> directives in the layout <head> so fonts download at the same priority as CSS. Added overflow-y: scroll on html to prevent horizontal layout shift between pages of different lengths, and reserved min-height on the search container to prevent sidebar links jumping during initialisation.

Static page overhaul

All 17 static documentation pages on docs.speybooks.com have been audited, corrected, and rewritten where necessary. Every page now uses accurate endpoints from the live API, correct pricing, and honest feature claims.

Critical fixes

• VAT Returns - removed false claim that SpeyBooks is “HMRC-recognised for MTD VAT submissions”. Replaced with accurate language: SpeyBooks generates MTD-compliant nine-box VAT return data, with direct HMRC submission on the roadmap. Removed fabricated /v1/vat/submit and /v1/vat/submissions endpoints that do not exist. Page now references the real GET /v1/reports/vat endpoint.
• Bank Reconciliation - replaced fabricated /v1/bank/import and /v1/bank/transactions/*/match endpoints with real ones: /v1/bank-imports/upload, /v1/transactions/{id}/categorise, /v1/transactions/{id}/reconcile. Added Universal Ingestion Engine documentation, Smart Map column remapping, balance proof verification, and the categorisation rules engine with confidence scoring.
• CSV Import - removed “Coming soon” labels for invoices and opening balances (both shipped). Documented all five import pipelines with real endpoints: bank imports, contact imports, opening balances, invoice imports, and bill imports. Added migration wizard reference.
• Dividends - corrected pricing from £24.95 to £25/month. Added retained profit check, board minutes, dividend tax calculator, void with reversal journals, and dividend summary. Changed freetext shareholder field to linked director record matching the actual API shape.
• Authentication - added scoped API keys with all 17 granular permissions, key rotation via API, idempotency keys with 24-hour expiry, and corrected response envelope to include meta field.

Content improvements

• Quick Start - corrected trial terms (90-day for first 50 users, card required), added Developer Shell section, updated response format with meta field.
• Introduction - rewritten with accurate feature inventory (197 endpoints, 37 resources), correct pricing table, and honest MTD-ready language.
• Multi-Currency - removed from documentation. Feature needs further development before public documentation is appropriate.

Consistency fixes

• Response format - all code examples now show the correct { success, data, meta } envelope rather than the outdated { success, data } format.

Scroll-sync code panel

Guide pages on the documentation site now display API code examples in a sticky right-hand panel that follows you as you read.

• Prose and code stay in sync - as you scroll through a guide, the code panel highlights and scrolls to the relevant request or response. The panel uses minimal-scroll logic so previous code blocks remain visible for context.
• Built from frontmatter - code blocks are defined in each page’s frontmatter with explicit sync points mapping sections to code blocks. No raw HTML in markdown.
• Responsive stacking - on screens narrower than 1200px, the layout falls back to a clean single-column stack with code blocks inline. No horizontal overflow, no broken layouts.

Infrastructure

• static-pages.ts v2.0 - extended frontmatter parser to extract codeBlocks array with id, label, lang, method, path, status, and multiline code fields. Backwards compatible - pages without code blocks render identically.
• CodeBlock.astro - added optional id prop for scroll-sync DOM targeting.
• code-sync.js - new IntersectionObserver-based scroll sync script. Pauses auto-scroll for 1.5 seconds after manual interaction with the code panel. Disconnects on mobile viewports where the panel is stacked.

Mobile responsiveness

The documentation site now renders correctly across all mobile viewports.

• Tables scroll horizontally - wide tables (error codes, account lists, scope tables) are swipeable on mobile rather than being clipped.
• Code blocks constrained - prose code blocks and the right-hand code panel respect their container width.
• Inline code wraps - long identifiers break cleanly instead of forcing horizontal overflow.
• Search overlay keyboard fix - the search modal anchors to the top of the screen on mobile so the virtual keyboard does not squash the results area.

Search improvements

• Race condition fixed - fast typers no longer see a false “Search unavailable” message when Pagefind is still loading.
• Background scroll locked - the page behind the search modal no longer scrolls when the modal is open.
• First result auto-selected - pressing Enter immediately opens the top result without needing to arrow-key down first.

Sidebar correction

• Migration moved to Import & Migration - the Migration resource (10 endpoints) was incorrectly nested under the Admin category due to a singular/plural tag mismatch in the OpenAPI spec generator. Fixed the x-tagGroups mapping and regenerated both snapshots.

Bug fixes

• Fixed position: sticky failure on the code panel caused by an overflow-x property on a parent container.
• Fixed code block styling on guide pages where custom labels generated unrecognised CSS modifier classes.

Marketing Site Overhaul

A comprehensive audit and rewrite of the public marketing site to accurately reflect the platform’s current capabilities. The features, pricing, and homepage were all underselling what SpeyBooks actually does.

Features Page (v4.0)

• 5 spotlight features — Developer Shell, Migration Wizard, Auto-Categorisation, Limited Company, and API-First Design each get dedicated sections with visuals and capabilities grids.
• Migration Wizard spotlight — new SVG illustration showing the full migration flow: provider selection, 5-phase pipeline (contacts, opening balances, invoices, bills, execute), mathematical verification proof block, and completion stats.
• 18-card feature grid — expanded from 15 to include Opening Balances, OmniSearch (Cmd+K), and UK Data Residency.
• Trust strip — compact security confidence signal before the CTA: SSL Labs A+, HSTS, Argon2id, Row-Level Security, CSRF, rate limiting, UK data residency, double-entry triggers, and monthly security reports.
• Monthly security reports — automated security verification published to /insights, covering TLS configuration, HTTP headers, authentication hardening, and infrastructure checks.
• Stale badges removed — five “New” badges removed from features shipped weeks ago.
• Auto-Categorisation enhanced — copy now references the lattice-scored inference engine and includes a fifth capabilities card for the Rules API (create, test, reorder via endpoints).

DemoShell v2.0

The interactive shell demo on the features page now mirrors the real Developer Shell v3.0.

• Category-grouped routes — 38 curated routes across 6 categories matching the real shell’s layout, with the full 197-endpoint count shown in the banner.
• 9 new canned responses — Director Loan Accounts (transactions, balances, S455 exposure), Dividends (list, profit check, summary), and Reports (Profit & Loss, Balance Sheet, Directors).
• 25 clickable ID types — all production prefixes with longest-first regex matching.
• Route filtering — routes invoice, routes DELETE, or any keyword to narrow results.
• env command — shows API base, auth mode, endpoint count, and history length.
• Updated ghost suggestions — includes director-loans, dividends, and reports paths.

Pricing Page (v4.11)

• Fixed API docs link — now points to the correct reference at docs.speybooks.com/api/v1/.
• Fixed contact prefix — con_ corrected to cont_ in the terminal example.
• Fixed pagination key — "pagination" corrected to "meta" to match the actual API response format.
• Migration Wizard added — now listed in Core Accounting and in the pricing card feature list.
• Universal bank import — copy updated from “CSV bank import with UK bank presets” to reflect the ingestion engine’s automatic schema detection.
• Self Assessment added to roadmap — alongside MTD VAT, now described as “actively in progress” with HMRC recognition.
• OmniSearch added — listed under Developer Tools.

Homepage Updates

• Launch date corrected — “Soft Launch February 2026” updated to “Early Access · March 2026”.
• 197 endpoints — referenced in the hero copy and feature grid cards.
• Feature grid expanded — 6 cards to 9, adding Migration Wizard, Universal Bank Import, and Financial Reports.
• Contact prefix fixed — con_8x corrected to cont_8x across all instances.
• API reference link fixed — updated across all pages to the correct docs URL.
• Pricing section enhanced — migration wizard and universal bank import added to the feature list, trial days now dynamic from the early access API.

Dynamic Developer Shell

The Developer Shell now reflects the full API surface automatically. Previously, autocomplete and the routes command showed a small subset of endpoints maintained by hand. Now the shell is driven by the same OpenAPI spec that powers the documentation site.

• 197 endpoints available — every path in the API is discoverable via tab completion, ghost text, and the routes command. Previously only 24 were shown.
• Category-grouped route display — routes organises endpoints into 8 categories (Core, Accounting, Banking, Company, Import & Migration, Integration, Platform, Admin) matching the docs site hierarchy.
• Filtered route search — routes invoice or routes DELETE narrows the display to matching endpoints with a count.
• 25 clickable ID types — response IDs like inv_29, dir_3, txn_382, and dla_6 are all clickable, loading the resource with a single click. Previously only 7 prefix types were recognised.
• Build-time code generation — a new codegen step reads the IR and sidebar snapshots from the documentation site and emits a typed route file consumed by the shell. Routes update automatically on every portal build.

Build Pipeline Improvements

• Single-parse spec analysis — the deploy script now extracts all OpenAPI statistics in one Node invocation instead of nine, reducing overhead during deploys.
• Error trap — the deploy script now prints the failing line number when something goes wrong, making deploy failures easier to diagnose.
• Automated shell codegen — the portal build script now runs the route generator before TypeScript compilation, so shell routes stay current without manual steps.
• Portal rebuild reminder — after an API deploy, the script reminds you to rebuild the portal if shell routes may be stale.

Release 100

This is the 100th SpeyBooks release.

Documentation Landing Page

The docs site now has a dedicated landing page at docs.speybooks.com. Previously the root URL had no content — visitors had to navigate directly to a resource page or arrive via the sidebar.

• Search-dominant hero — a full-width search input as the primary interaction. Clicking or focusing it opens the Pagefind-powered search modal, giving instant access to all 31 resources and 197 endpoints.
• 3×3 navigation grid — nine cards organised by developer workflow: Quick Start, How It Works, Authentication, API Keys, Accounts, Banking, Company, Billing, and Imports & Migration.
• Full theme support — light and dark themes with theme state persisted across pages and restored before first paint.
• Complete legal footer — links to Privacy, Terms, Sub-processors, Cookies, Security, and Anti Tax Evasion. Includes live system status indicator and build timestamp.

API Reference Entry Point

A new overview page at docs.speybooks.com/api/v1/ serves as the entry point for the entire API reference.

• Structured table of contents — all 8 categories, 31 resources, and 197 endpoints presented in categorised tables with endpoint counts and one-line descriptions.
• Dynamically generated — the page content is built from the IR at compile time, so resource lists and endpoint counts stay in sync automatically across releases.
• Sidebar integration — appears as “Overview” under the API Reference heading.

Collapsible Sidebar Navigation

The sidebar now uses collapsible sections throughout, reducing the default visible navigation from 50+ links to 12 lines.

• All sections collapse — Getting Started, Concepts, Guides, API Reference, and all resource categories (Core, Accounting, Banking, Company, Import & Migration, Integration, Platform, Admin) are collapsible.
• Self-revealing navigation — sections auto-open when you navigate to a page within them, so you always see where you are without manual expansion.
• Two-level nesting — resource categories collapse to show their resources, and individual resources collapse to show their endpoints. The same <details>/<summary> pattern used throughout, no JavaScript required.

Technical Details

• Token integrity — all new styles derive from canonical speydocs.css tokens. No hardcoded colours.
• Formally specified — the landing page is governed by SD-SRS-LANDING-1.0 and TMADD-SD-LANDING-1.0.
• Markdown table support — preamble pages now render tables, headings, links, and inline code with full styling.

API Schema Enrichment

Every route in the SpeyBooks API now carries production-grade OpenAPI schema metadata — params, body, querystring, and response codes — so the documentation site renders complete, accurate reference pages instead of placeholder defaults.

Route Schema Enrichment

• 195 routes audited across 36 files — systematic pass ensuring every endpoint declares its params, body schema, response codes, and descriptions aligned with the handler behaviour.
• Response schema synthesis — the OpenAPI generator now infers schema.properties from sibling example bodies, eliminating the “Default Response” placeholder on 150+ endpoints.
• Params schemas added — routes with URL parameters (:id, :accountId, :key) now declare typed params schemas so the docs site renders parameter descriptions and types.
• Body schemas added — POST and PATCH routes that accept request bodies now have inline OpenAPI schemas with field types, enums, constraints, and descriptions matching their Zod validators.
• Error response codes declared — 400, 404, 409, and 422 responses added where handlers return them but schemas didn’t declare them. The docs site now shows the full error surface for each endpoint.

Files Enriched

• Core resources — invoices, transactions, categorisation-rules, quotes
• TMADD pipeline — invoice-imports, bill-imports, contact-imports, opening-balances, migrations
• Integration — api-keys, webhook-endpoints
• Admin — admin, admin-additions

Audit Tooling

• Route audit script — Python script scanning all 36 route files and 37 sibling doc files, detecting missing schemas, undeclared response codes, and sibling gaps. Produces a prioritised issue queue.
• Variable-reference detection — the script now recognises params: sharedSchema variable references, not just inline params: { ... } blocks, eliminating false positives on well-structured files.
• Zod fallback detection — routes using .parse(request.body) in the handler are recognised as having body validation, even without an inline schema block.
• Action endpoint heuristic — bodyless POST routes (confirm, void, validate, execute) that have params and response schemas but never reference request.body are correctly identified as action endpoints rather than flagged as missing body schemas.

Results

• 175 of 195 routes fully compliant — up from 19 at the start of the session.
• 21 remaining flags — all either intentional design choices (action endpoints using 422 instead of 400) or non-paginated list endpoints.
• Zero sibling gaps — every route file has a matching .doc.ts with descriptions, curl examples, and response examples.

API Documentation Landing Page

The docs site now has a dedicated landing page at docs.speybooks.com. Previously the root URL had no content — visitors had to navigate directly to a resource page or arrive via the sidebar.

What’s New

• Search-dominant hero — the landing page centres a full-width search input as the primary interaction. Clicking or focusing it opens the Pagefind-powered search modal, giving instant access to all 31 resources and 197 endpoints.
• 3×3 navigation grid — nine cards organised by developer workflow: Quick Start, How It Works, Authentication, API Keys, Accounts, Banking, Company, Billing, and Imports & Migration. Each links to the corresponding documentation page.
• Full theme support — light and dark themes match the existing documentation surface, with theme state persisted across pages. Theme is restored before first paint to prevent flash.
• Keyboard shortcuts — press / or ⌘K from the landing page to open search, matching the behaviour on all other documentation pages.
• Complete legal footer — links to Privacy, Terms, Sub-processors, Cookies, Security, and Anti Tax Evasion policies. Includes live system status indicator and build timestamp.

Technical Details

• Token integrity — all landing page styles derive from canonical speydocs.css tokens via CSS custom property references. No hardcoded colours in component CSS.
• Standalone layout — the landing page does not use the three-column Layout.astro shell. It shares the same topnav, theme toggle, and search infrastructure but renders a full-width surface without sidebar or code panel.
• Formally specified — the landing page is governed by SD-SRS-LANDING-1.0 (requirements) and TMADD-SD-LANDING-1.0 (closure design), ensuring outbound route closure, deterministic card ordering, and search shortcut totality.

SpeyDocs Deep Enrichment

Every route file in the API now carries property-level documentation — query parameters, request bodies, response codes, and field descriptions are all enriched directly in the route schemas. SpeyDocs renders these automatically, so the public API reference at docs.speybooks.com reflects the full detail without any manual page editing.

What Changed

• 467 descriptions added across 36 route files — covers every public and admin endpoint in the API. Parameter types, enum values, default behaviours, and error responses are all documented at the schema level.

• Deep enrichment on 7 core route files — invoices, transactions, dividends, director loans, categorisation rules, bank imports, and migrations received full property-level treatment. Every query parameter, request body field, nested object, and response status code now has a description explaining what it does, what values it accepts, and what the constraints are.

• Response-level enrichment on 3 admin route files — admin, admin additions, and admin bug reports now document every response status code across all 31 admin endpoints.

• Batch enrichment on 26 remaining route files — endpoint-level summaries, operation IDs, and response descriptions across accounts, contacts, reports, quotes, auth, billing, and all import pipelines.

Documentation Site Fix

• Request code block wrapping — long curl commands in the SpeyDocs API reference now wrap properly instead of requiring horizontal scrolling. JSON response blocks are unaffected and keep their indented structure.

Documentation Renderer Upgraded

The API documentation at docs.speybooks.com now renders endpoint pages with Stripe-quality layout and progressive disclosure.

Endpoint Pages

• Semantic section structure — parameters, request body, response, and error codes render as distinct visual blocks with section dividers, replacing the previous flat field dump.
• Progressive disclosure — response fields are collapsed by default behind “Show response fields” toggles. Nested objects and arrays collapse behind “Show child attributes”. The response shape is visible at a glance; detail on interaction.
• Envelope unwrapping — the {success, data} response envelope is stripped automatically. Response sections show the data-level fields directly (e.g. accounts, meta), matching what developers actually work with.
• Field metadata badges — nullable fields show a NULLABLE badge, timestamp fields show DATE-TIME, and enum values render as discrete chips instead of inline text.
• Required-first ordering — fields sort required before optional, then alphabetically within each group.

Resource Landing Pages

• Terminal-style endpoint list — the right column now shows endpoints in a dark code-block container with method badges and paths, matching the existing code block aesthetic. Each row is a hyperlink to the endpoint detail page.
• Object example — resource landing pages now display the resource’s JSON object example below the endpoint list, giving developers the full picture without navigating away.

Code Panel Elevation

• Visual separation between request and response — the request block uses a deeper background (Deep Obsidian) while the response block uses a lighter elevated background (Elevated Slate). The luminance shift creates an immediate sense of input vs. output without breaking syntax highlighting contrast.
• Light mode contrast fixed — code block labels, copy buttons, and language tags now use fixed dark-background tokens, ensuring visibility in both light and dark themes.
• Missing codeblock-comment token defined — resolved an undefined CSS variable that caused the COPY button to be invisible in light mode.

CSS Token Compliance

• No raw hex in component CSS — all new styles use the existing --sd-* token system from the design token contract. No [data-theme] overrides required.
• Existing class names preserved — the renderer reuses sd-param-*, sd-child-params-*, sd-section-title, and sd-response-* classes from the production stylesheet. Six new classes added for badges, enum chips, and error rows.

Bug Fixes

• Fixed code panel background switching to white in light mode, breaking contrast for all code blocks.
• Fixed COPY button invisible in light mode due to undefined --sd-codeblock-comment CSS variable.
• Fixed response fields rendering fully expanded by default, causing excessive vertical scroll on endpoints with complex response schemas.

Lighthouse Perfect Score

SpeyDocs now achieves 100 Performance, 100 Accessibility, 100 Best Practices, and 100 SEO on Google Lighthouse mobile audit. This is the maximum possible score on an emulated Slow 4G connection.

• Zero layout shift — a synchronous inline script sets the JavaScript state class before the browser’s first paint, eliminating the sidebar flash that caused a 0.466 CLS penalty.
• Zero render-blocking resources — stylesheets are inlined directly into each HTML page, removing the external CSS network request.
• Zero total blocking time — no long tasks on the main thread.

SD-SRS-RESP-1.0 Implementation

The new Responsive Shell Specification formalises mobile behaviour as a deterministic state machine over viewport width. This release implements the full specification.

• iOS viewport height correction — a custom --sd-vh property replaces native 100vh, eliminating Safari’s dynamic toolbar layout jumps.
• Touch targets — all interactive elements on mobile now meet the 44px minimum (Apple HIG compliance).
• Safe area support — viewport-fit=cover with env(safe-area-inset-bottom) padding prevents iPhone notch and home bar overlap.
• Mobile sidebar focus trap — Tab key cycles within the sidebar overlay and menu button when open, preventing focus from leaking into hidden content.
• Scroll restoration — sidebar scroll position restores after double requestAnimationFrame for layout stabilisation, with pageshow listener for Safari’s bfcache.
• Resize state normalisation — rotating the phone or resizing past the mobile breakpoint automatically closes the sidebar overlay.

Mobile Navigation Polish

• Proportional 76px header — the mobile top navigation bar is taller with balanced visual weight against content headings.
• 48px control targets — hamburger menu and theme toggle are symmetrical 48px tap boxes with proportionally scaled icons (22px burger, 24px sun/moon for perceptual weight balance).
• 40px logo — the SpeyBooks wordmark scales proportionally to the header height with automatic width scaling.
• Compact layout — the “API Reference” text link is hidden on mobile (redundant with sidebar navigation), freeing horizontal space for the logo and controls.

Content Overflow Fixes

• Callout code blocks — <pre> blocks inside callouts now wrap long lines with dark code block styling instead of overflowing the page.
• Endpoint URLs — long API paths on endpoint detail pages wrap with word-break instead of blowing out the content column.
• Endpoint summary list — on mobile, the full URL is hidden and the endpoint name displays prominently next to the method badge.

Structural Improvements

• Meta descriptions — every page now has a <meta name="description"> tag, completing the SEO requirements.
• Heading hierarchy — sidebar category titles changed from <h3> to <div>, preserving the semantic document outline for screen readers.
• Duplicate copy button removed — the progressive enhancement script no longer injects copy buttons since they are now rendered inline by the code block component.
• Backdrop aria state — the mobile backdrop correctly toggles aria-hidden in sync with sidebar open/close state.

Static Documentation Pages

SpeyDocs now serves 15 hand-written documentation pages alongside the 251 API reference pages. The sidebar is reorganised into clear sections: Introduction, Getting Started, Concepts, Guides, API Reference, and the existing resource categories.

• Getting Started — Quick Start, Authentication Setup, Developer Shell, and Your First Invoice walk new developers through onboarding step by step.
• Concepts — How It Works, Double-Entry Bookkeeping, Chart of Accounts, VAT Handling, and Multi-Currency explain the accounting model behind the API.
• Guides — VAT Returns, Bank Reconciliation, CSV Import, Dividends, and Webhooks cover practical workflows end to end.

Docusaurus-style admonitions (note, tip, caution, warning, danger) are converted at build time and render with colour-coded callout styling.

Schema Resolution for Request Bodies

Sixteen endpoints across Accounts, Contacts, Transactions, Directors, Dividends, Organisation, Webhooks, and Director Loans previously showed empty request body sections. The build now resolves writable fields from component schemas at load time, filtering out read-only fields like id, createdAt, and isSystem. Every POST and PUT endpoint now shows the full list of submittable fields with types, required badges, and descriptions.

Parameter Defaults & Validation Constraints

• Defaults — Query parameters and request body fields now display their default values inline (e.g. active defaults to true on list endpoints).
• Constraints — Validation rules surface directly on fields: min length: 8 on passwords, format: date on date fields, min items: 1 on invoice lines, pattern on date strings.

Nested Parameter Expansion

Array-of-object and nested object fields now include a collapsible “Show child parameters” toggle. Invoice lines, quote lines, and categorisation rule batch fields expand to reveal their child schemas with types, required badges, and descriptions.

Code Panel Enhancements

• Method + path header — Request blocks now display the HTTP method and endpoint path (e.g. POST /v1/invoices/) with method-coloured badges.
• COPY button — Every code block includes a copy-to-clipboard button with visual feedback.

Branding Update

The docs site logo is now the SpeyBooks API wordmark with the river wave element, matching the main brand identity. Theme-aware fills ensure it renders correctly in both light and dark modes.

Bug Fixes

• Fixed code blocks on static pages rendering with a white overlay caused by inline-code background styles leaking into fenced code blocks.
• Static pages now use the standard two-panel grid layout (content + empty code panel) instead of collapsing to full width, maintaining visual consistency with the API reference.

SpeyDocs Public API Documentation

SpeyBooks now has a dedicated documentation site at docs.speybooks.com. Every public endpoint, object schema, and authentication flow is documented with interactive examples.

What Shipped

• 252 pages generated — every resource, endpoint, and object schema has its own page with curl examples, JSON responses, and field-level documentation.
• Two-panel layout — content on the left, code examples on the right. Sticky code panels follow as you scroll through attributes and parameters.
• Full-text search — powered by Pagefind with a keyboard-first modal (⌘K / Ctrl+K / /). Indexes all content, excludes code examples from results.
• Light and dark themes — respects system preference with manual toggle. Code panels stay dark in both themes.
• Sidebar navigation — grouped by resource with method-coloured dots (green GET, blue POST, amber PATCH, red DELETE). Arrow key navigation and scroll persistence across page loads.
• Build-time compression — HTML, CSS, and JS minified automatically via astro-compress. ~966KB saved across all pages.

Markdown Rendering Fix

• YAML block scalar indentation — endpoint descriptions written as multi-line YAML were rendering as code blocks instead of formatted text. A dedent step now strips the common indent before passing to the markdown renderer.

Keyboard & Accessibility

• Visible-only arrow navigation — sidebar arrow keys skip items inside collapsed resource groups, preventing focus from disappearing into hidden elements.
• Left/Right on resource groups — ArrowRight opens a resource section, ArrowLeft closes it.
• Focus management — opening the mobile sidebar moves focus inside; closing it restores focus to the menu button.
• Global focus-visible fallback — ensures all interactive elements have visible keyboard focus indicators.

Infrastructure

• Sidebar scroll persistence — uses sessionStorage with pagehide and visibilitychange events. Scroll position restores via requestAnimationFrame after layout settles.
• Content Security Policy — wasm-unsafe-eval added to support Pagefind’s WebAssembly search index.
• Sitemap — auto-generated at build time for all 252 pages.

SpeyDocs Component Spec Sheet

Complete visual contract for the SpeyDocs documentation frontend, covering all four page kinds defined in TMADD-SD-2.0 §2.2: preamble, resource landing, object, and endpoint.

What’s Included

• Four page kind specifications — each with URL pattern, IR source annotations, middle/right column content mapping, mini wireframe preview, and column annotations. The resource landing page — entirely missing from the prior spec — is now fully specified.
• IR data access patterns — boxed code blocks showing exactly which IR path to read from per page kind. The object page explicitly documents ir.tags[].extensions['x-speydocs-object'], correcting the prior bug where schema data was read from endpoints.
• Light and dark theme previews — endpoint page shown in both themes, validating token contrast ratios visually. Code panel background switches with theme; code blocks inside are always dark.
• Preamble content authoring spec — frontmatter schema (title, slug, order, hasCodeExamples) for hand-written markdown files in src/content/preamble/.
• Mobile sidebar behaviour — collapsed by default behind a hamburger button, slide-in overlay, backdrop, close triggers, body scroll lock, and no-JS fallback.
• Top navbar contents — logo/wordmark, nav links, separator, and theme toggle with HTML elements and ARIA attributes.
• GET vs POST display rules — query parameters and request body fields use the same .sd-param component; the difference is the H3 section title and curl format.
• SchemaView breadcrumb format — separator (→), array indicator ([]), terminal type name, and construction algorithm.

Rendering Contract Amendments (TMADD-SD-2.0 §9.3, §9.4)

• ExampleNF block count invariant — endpoint pages must have exactly 2 code blocks (request + response), object pages exactly 1, resource landing pages exactly 1.
• RC-E1 (Example Totality) — every endpoint must have both curl and response examples. Checked in CI Pass A.
• RC-S1 (Schema Field Bijection) — rendered fields on object pages must exactly equal schema fields. Checked in CI Pass B.
• closure.json — two new flags: exampleTotality and schemaFieldBijection.

Bug Fixes

• Corrected heading hierarchy — H2 is reserved, H3 for all section titles per TMADD-SD-2.0 §9.
• Added missing --sd-sidebar-category token to the design token reference.
• Added max-width: 720px to resource landing content area, matching endpoint pages.
• Corrected code panel theming — --sd-code-bg switches with theme, only --sd-codeblock-bg is fixed dark.

API Documentation — Verified Against Every Route

SpeyBooks now ships with a complete .doc.ts documentation layer covering all 165 endpoints across 37 resources. Every example response has been stress-tested against the actual Fastify routes, Zod schemas, and database queries to ensure what the docs say is exactly what the API returns.

This is the documentation that will power the developer portal at launch.

What’s Documented

• Universal Ingestion Engine — full preview arrays (rows[], lines[], mappings[], preview[]) exposed in upload, GET, and map responses. Developers building import wizards get everything they need in a single round-trip.
• Universal Contact Index — DSU graph outcomes (CREATE, MERGE, CONFLICT) with evidence arrays showing why contacts were linked, including hard-key matches and soft-similarity scoring.
• Opening Balance Closure Engine — 5-tier account resolution (exact, code, dictionary, fuzzy, clearing redirect) with confidence scores and clearing mode documentation.
• Outstanding Document Engine — per-row contact resolution showing UCI-lite matching outcomes (match, fuzzy, create) with Levenshtein similarity ratios.
• Migration Wizard — full formatMigration payloads at every state transition, so frontends can render wizard progress without secondary requests.
• Auth & Security — complete user profile objects across login, TOTP verify, and /me endpoints. Token lifecycle, Argon2id hashing parameters, and rotation grace periods all documented.
• Reports — VAT return breakdown array with per-rate net/VAT amounts, liability movement, and all nine HMRC boxes. Dashboard tax set-aside calculations with corporation tax banding.
• Admin — omni-search, GDPR hard-delete cascade, system health monitoring, and settings management.

Consistency Fixes

• Pagination envelope — standardised to meta: { page, perPage, total, pages } across all paginated endpoints. Previously, some documentation examples used a pagination key that didn’t match the paginatedResponse helper.
• Organisation address asymmetry — the GET/PUT shape difference (nested address object in responses, flat addressLine1/city/postalCode fields in requests) is now explicitly documented to prevent 400 validation errors.
• Audit timestamps — createdAt and completedAt now appear in all import and migration response examples.

Developer Experience

• No extra round-trips — upload and map responses return the full preview payload, so there’s no need for a subsequent GET call.
• UI hydration — auth endpoints return complete user context (email, isAdmin, totpEnabled) immediately, eliminating the need for a follow-up /me request after login.
• Transparency endpoints — full severity breakdown (critical, high, medium, low) and lastUpdated timestamp for the public transparency page.

Migration Wizard

SpeyBooks now has a guided migration wizard at /migration. Upload a single FreeAgent .xlsx export and the wizard walks you through a six-stage pipeline: upload, verify contacts, verify opening balances, verify outstanding invoices, verify outstanding bills, and reconciliation proof.

FreeAgent XLSX Import

• Single-file upload — drop your FreeAgent export (.xlsx) and the wizard splits it into four sheets: Contacts, Trial Balance, Outstanding Invoices, and Outstanding Bills. No manual CSV splitting required.
• Two-phase upload — contacts and opening balances are parsed immediately. Invoices and bills are deferred until the opening balance is confirmed (clearing accounts must exist first). The wizard handles this automatically.
• Provider-aware UI — the upload stage shows which sheets were found, which uploaded successfully, and which are waiting for the balance confirm.

Clearing Verification

• Real-time clearing proof — the Outstanding Invoices and Bills stages now show live data from the backend: opening balance on the clearing account, total imported documents, and the difference. Previously showed £0.00 for both.
• Backend-computed values — all monetary calculations happen server-side. The frontend displays pre-formatted pounds strings with locale-aware comma separators (£20,100.00). No pence-to-pounds conversion in the browser.
• Match/mismatch logic — if invoices don’t account for the full clearing balance, the difference is shown in red and the confirm button is disabled. When they match, you see “These match perfectly” in green.

Opening Balance Verification

• Balance proof display — total debits and credits are fetched from the backend and displayed with proper formatting. Previously showed £0.00 when accessed through the migration wizard.
• Account mapping — the auto-mapper now correctly resolves FreeAgent account names to SpeyBooks chart accounts. Fixed a data type mismatch that caused all accounts to appear unmapped.

Contact Verification

• Import statistics — the contacts stage now fetches real stats from the contact import record (8 new contacts, 0 conflicts) instead of showing “0 new contacts”.
• UCI identity resolution — duplicate key handling now uses database savepoints to prevent transaction poisoning. If a VAT number already exists, the import continues gracefully instead of failing.

Service Architecture Refactor

• Eliminated HTTP simulation — the migration orchestrator previously used fastify.inject() to call standalone upload endpoints. This caused a race condition where the injected request’s transaction could commit after the parent route tried to reference the new records, causing foreign key violations. The upload logic has been extracted into service functions that run directly within the caller’s transaction.
• Single-transaction guarantee — contacts, opening balances, invoices, and bills are all parsed and stored within a single database transaction. No timing races, no pool hopping, no manual RLS reapplication.
• Three new service modules — contact import, opening balance import, and document import (direction-agnostic for both invoices and bills). Each accepts a database client, organisation ID, and CSV buffer, and returns the import record ID.

Bug Fixes

• Fixed £0.00 display on opening balance verification — the component was reading from a preview field that is null during provider uploads. Now fetches real data from the import record.
• Fixed £0.00 display on clearing verification — same root cause. Now fetches clearing proof and outstanding totals from the backend.
• Fixed “0 new contacts” display — contact statistics were not being loaded from the import record.
• Fixed transaction poisoning on duplicate identity keys — UCI contact confirm could fail with a 25P02 error if a VAT number already existed. Wrapped identity key inserts in savepoints.
• Fixed foreign key violations on import ID attachment — eliminated the fastify.inject() timing race that caused intermittent FK constraint errors when linking import records to migrations.
• Fixed account mapping failure — the opening balance service returned database column names (snake_case) instead of the camelCase property names the mapper expected, causing all accounts to appear unmapped.
• Fixed redundant upload call after confirm — the frontend was calling the upload endpoint again after confirming contacts, which returned a validation error.

Known Issues

• Clearing verification confirm button — when invoices don’t match the clearing balance (expected for test data), the confirm button is disabled. In production, a real FreeAgent export should have matching totals. A manual override for known discrepancies is planned.
• Invoice and bill detail views — the “View invoice details” and “View bill details” expandable sections show placeholder text. Detailed line-item display is planned for a future release.
• ProofPage values — the reconciliation proof page uses frontend formatting with pence values from the validate endpoint. This works correctly but should be migrated to the same backend-formatted pattern as the other verification stages for consistency.

Outstanding Document Import

You can now import outstanding (unpaid) invoices and bills from your previous accounting system. This completes Phase 3 of the Universal Data Import pipeline — the last piece needed for a full self-service migration.

Invoice Import

• CSV upload at /invoices/import — drag-and-drop your outstanding invoices CSV with columns for contact name, invoice number, date, due date, total, and amount paid.
• Contact resolution — every contact in your CSV is matched against existing contacts using fuzzy matching (Levenshtein similarity ≥ 85%). Unmatched contacts are auto-created on confirm.
• Partial payment detection — invoices with amounts already paid are handled correctly. The gross amount flows through clearing; a synthetic payment records the paid portion.
• Clearing proof — before you can confirm, the system verifies that your imported invoices account for the full Trade Debtors balance from your opening balances. No double-counting, no orphaned balances.

Bill Import

• CSV upload at /bills/import — mirror of the invoice importer for supplier bills, with the same contact resolution and clearing proof against Trade Creditors.

Opening Balance Clearing Mode

• New option on OB upload — when importing opening balances, you can now enable Clearing Mode. This posts Trade Debtors to a Migration Clearing account (1198) and Trade Creditors to another (2198) instead of the control accounts directly.
• Why it matters — clearing mode enables the zero-sum invariant. When you subsequently import outstanding invoices totalling your Trade Debtors balance, the clearing account nets to zero — mathematical proof that nothing was lost or double-counted during migration.
• Backwards compatible — existing opening balances continue to work in Direct Mode. To use the invoice/bill importers, void and re-import with Clearing Mode enabled.

Cash VAT Protection

• Structured error for Cash VAT — if your organisation uses Cash VAT accounting, invoice and bill import is blocked with a clear error message. Accrual-basis outstanding documents and cash-basis VAT recognition don’t mix safely. This will be supported in a future release.

Account Mapping Improvements

• 17 new dictionary mappings — the opening balance mapper now correctly resolves common account names from Xero, FreeAgent, and QuickBooks exports. Previously unmapped accounts like Wages & Salaries, Advertising, Corporation Tax, Office Equipment, Telephone & Internet, and Suspense now map automatically to the correct SpeyBooks chart accounts.

Technical Details

• Atomic commits — invoice and bill confirms run inside a single database transaction. Contacts, invoices, invoice lines, clearing journals, and synthetic payments are all created or none are.
• 5 new API endpoints per direction — upload, retrieve, confirm, void, and delete for both /invoice-imports and /bill-imports.
• Direction-agnostic engine — the underlying closure engine doesn’t know whether it’s processing invoices or bills. Routes inject the direction; the engine enforces the invariants.

Opening Balance Import

SpeyBooks now supports importing opening balances from a trial balance CSV — the critical first step for users switching from another accounting platform.

Upload & Auto-Map

• Smart column detection — automatically identifies Account, Debit, and Credit columns (or a single signed Amount column) from trial balance exports.
• Deterministic account mapping — source account names are matched to your SpeyBooks chart of accounts using exact match, a known dictionary of common names from Xero, FreeAgent, and QuickBooks, or fuzzy similarity. Unmapped accounts are flagged for manual resolution.
• Cutover date — defaults to the last day of the previous month. Must be a month-end date.

Balance Proof

• Hard-gated trial balance — the import cannot be confirmed unless total debits exactly equal total credits. No tolerance, no warnings, no “fix it later”.
• Rounding injection — if the imbalance is ≤ £0.05 (a common rounding artefact from other systems), a mathematically valid rounding line is automatically injected to close the balance.
• Retained Earnings required — the system does not infer or auto-create balancing entries. You must provide the Retained Earnings (or Profit and Loss Account) row explicitly.

Singleton & Immutability

• One active opening balance per organisation — enforced at the database level. A second import is structurally blocked until the first is voided.
• Locked on commit — the opening balance journal cannot be edited or deleted after confirmation. Only an explicit void restores the ability to re-import.
• Audit-safe void — voiding marks the journal with a timestamp rather than deleting it. No audit gaps.

API Endpoints

Seven new endpoints power the opening balance lifecycle:

• Check if an opening balance exists
• Upload and preview a trial balance CSV
• Retrieve a stored preview
• Update account mappings or cutover date
• Confirm (atomic commit with triple gate)
• Void an active opening balance
• Delete a pending (uncommitted) import

Database Migrations

• 063 — Adds source, locked, voided_at, and voided_by columns to support migration journals. Singleton partial unique index. Immutability triggers on journals and journal lines. Delete protection triggers.
• 064 — Extends the source type constraint to include migration.
• 065 — Allows nullable created_by on imports for API key authentication contexts.

Opening Balance Import — Frontend Wizard

A 4-step wizard for importing opening balances, matching the bank import and contact import patterns.

• Upload — drag-and-drop CSV upload with singleton guard. If an opening balance already exists, shows the active journal reference with a “Void & Re-import” option.
• Map Accounts — auto-mapped accounts shown with method badges (Exact, Dictionary, Fuzzy). Unmapped accounts get a dropdown to select from your chart of accounts. Balance proof card shows Total DR, Total CR, and delta in real time. Cutover date picker restricted to month-end dates.
• Preview — journal lines table with account code, name, type, debit, and credit columns. Rounding injection lines highlighted. Confirm button gated on balance proof — disabled unless debits equal credits.
• Done — transaction reference, balance proof confirmation, and links to the journal and reports.

Contact Import — Table Redesign

• Consolidated preview table — the 5-column layout (Action, Contact, Email, Hard Keys, Evidence) has been replaced with a 3-column layout (Action, Contact, Email) that eliminates horizontal scrolling on standard viewports. Hard keys and evidence are now stacked vertically within the Contact cell.
• Responsive email column — the Email column hides on small screens and displays inline within the Contact cell instead.

Known Issues

• The account mapping dictionary does not yet cover all common account names from Xero, FreeAgent, and QuickBooks. Some accounts that should auto-map (e.g. Wages & Salaries, Advertising, Insurance) currently appear as unmapped and require manual selection. A dictionary expansion is planned.

Contact Import Wizard

SpeyBooks now supports bulk contact import from CSV files with automatic duplicate detection and identity resolution.

Smart Column Detection

• Auto-detected columns — Upload any contacts CSV and SpeyBooks automatically maps Name, Company, Email, Phone, Address, City, Postcode, Country, VAT Number, Company Number, Contact Type, and Payment Terms. No manual column selection needed.
• Generic domain exclusion — Email addresses from shared providers (Gmail, Outlook, Yahoo, etc.) are not treated as identity signals, preventing false matches between unrelated businesses sharing a common email provider.

Identity Resolution Engine

• Hard key matching — VAT numbers, Companies House registration numbers, and company email domains are used as definitive identity signals. If two records share a VAT number, they are the same entity.
• Soft similarity — When no hard keys exist, name and email similarity are scored against configurable thresholds to detect probable matches.
• Three outcomes — Each imported row is classified as Create (new contact), Merge (update existing), or Conflict (needs human review). The preview screen shows every decision with full evidence before anything is written.
• Idempotent imports — Re-importing the same CSV produces merge outcomes with no data duplication. The system is safe to run repeatedly.

Import Preview

• Stats summary — See contacts in file, new contacts, merges, and conflicts at a glance.
• Evidence trail — Every match decision shows why it was made: which hard key matched, or what the soft similarity score was. Fully auditable.
• Conflict blocking — Imports with unresolved conflicts cannot be confirmed until every ambiguity is resolved.

Identity Graph

• Identity anchors — Each contact is linked to a unique identity anchor that persists across imports. Future imports, invoices, and bank transactions all resolve to the same anchor.
• Hard key registry — VAT numbers, company numbers, and email domains are stored as unique keys per organisation. The same key cannot be claimed by two different contacts.
• Progressive adoption — Existing contacts are linked to identity anchors on first merge, with no migration required.

Bug Fixes

• Fixed API key authentication scope for new import endpoints — keys with contacts access now work correctly with the import wizard.

Known Issues

• Conflict resolution UI not yet available — conflicts must be resolved via the API. Frontend conflict resolution will ship in a follow-up release.
• Import history page not yet linked from the main navigation.

Dependency Audit

All three codebases audited and patched:

• Axios DoS vulnerability resolved — upgraded to patched version, eliminating the prototype pollution vector in request config merging.
• Marketing site clean — zero vulnerabilities. Upgraded Astro integrations and removed stale dependencies.
• API clean — zero vulnerabilities.
• One residual dev-only advisory — esbuild in the frontend dev server (Vite). Does not affect production builds or deployed code.

Build Pipeline Cleanup

• Marketing site flattened — removed the legacy Turborepo monorepo structure. The Astro site now builds directly at the project root without Turbo orchestration, cutting build complexity and eliminating an unused packages/ui workspace.
• Deploy script rewritten — numbered phases, build timer, page count, and clean ASCII output. No more emoji.
• Line counter fixed — the LOC script now correctly counts marketing site source after the directory restructure. Total codebase: 81,486 lines across API, frontend, docs, and marketing.

Internal Documentation

Added a docs/ directory to the app codebase covering architecture (system overview, database, API, frontend, infrastructure), operational runbooks (deploy, database, monitoring, incident response, Stripe), TMADD index, and three Architecture Decision Records (RLS, minor units, UIE).

Smart Map Column Overrides

The Universal Ingestion Engine (UIE) auto-detects your bank’s CSV format, but until now there was no way to correct it if the detection got a column wrong. v5.3.0 closes that gap.

What’s New

• Editable column mapping — every column in the Smart Map step is now a dropdown instead of a read-only chip. Change any column role (Date, Description, Amount, Debit, Credit, Balance, Reference, Type, or Skip) without re-uploading the file.
• Re-analyse button — after changing one or more columns, click Re-analyse to re-run the partition, balance proof, and duplicate detection against the same CSV. No second upload required.
• Inline validation — invalid mappings (no date column, mismatched debit/credit pairs) show clear error messages and prevent re-analysis until corrected.
• Reset button — reverts all overrides back to the auto-detected mapping with one click.
• Provenance downgrade — any user-corrected schema is tagged as User Corrected, the lowest trust level. This prevents manually overridden schemas from being promoted into the preset library.
• Evidence trail — the original auto-detected schema and all user corrections are preserved in the import record, creating a complete audit trail of what changed and why.

Balance Proof Behaviour

• If you remove the balance column, the balance proof correctly shows “not applicable” with an amber warning. You can still proceed — balance proof is advisory, not blocking.
• If you remap and the balance proof fails, the mismatch warning appears immediately, giving you feedback before you reach the Preview step.

How It Works

The CSV is parsed once on upload and stored alongside the import record. When you change the column mapping and click Re-analyse, the backend re-partitions the same matrix with your corrected schema — no network re-upload, no re-parsing. The Total Row Conservation Law (|H| + |V| + |I| + |E| = m) is enforced after every remap, guaranteeing no rows are lost or created.

Automatic CSV Format Detection

SpeyBooks no longer asks you to select your bank format when importing a CSV. The new Universal Ingestion Engine (UIE) analyses your file automatically — detecting the header row, column roles, date format, and amount model without any manual configuration.

What’s New

• Auto-detection for any CSV — drop a file from NatWest, Starling, Monzo, HSBC, Lloyds, Tide, or any other bank. The engine identifies the layout from the data itself.
• Verified bank presets — known UK bank formats are recognised instantly with a green “Recognised format” banner. Unknown formats are analysed heuristically and shown with a blue “Format auto-detected” banner.
• Balance proof — when a balance column is present, the engine mathematically verifies that the sum of all transactions matches the difference between opening and closing balances. A green “Balance mathematically verified” badge confirms the import is correct.
• Smart Map step — the import wizard now shows exactly what the engine detected: column mapping, date format, amount model, and balance proof status. You can review before proceeding to the preview.
• Buried header handling — CSVs with metadata rows above the header (common in NatWest downloads) are handled automatically. The engine finds the real header row regardless of how many lines of account information sit above it.
• Three amount models — signed single column, separate debit/credit columns, and amount-with-direction (DR/CR) are all detected and parsed correctly.
• Date disambiguation — when dates could be DD/MM or MM/DD, the engine scans the full column to find a disambiguating value. UK format (DD/MM) is used as the default when truly ambiguous.
• Pending transaction filtering — rows marked as pending or with empty dates are automatically excluded from the import and counted separately as “Ignored”.

Import Wizard Changes

• Simplified upload — the bank format dropdown has been removed. You now only need to select your bank account and drop a CSV file.
• New Smart Map step — replaces the old column mapping step. Shows the auto-detected schema with column roles, date format, and amount model at a glance.
• Balance badge in preview — the preview step now shows whether the balance was mathematically verified, giving you confidence before committing.
• Partition stats — the response now includes counts for valid, ignored, and error rows, so you can see exactly what the engine did with every row in your file.

Technical Details

• Row conservation — every row in the CSV is classified into exactly one of four partitions: Header, Valid, Ignored, or Error. The sum is enforced to equal the total row count — no rows are silently dropped.
• Deterministic parsing — the same file always produces the same result. No randomness, no machine learning, no external API calls.
• Zero new dependencies — the engine uses only csv-parse, which was already in the project.

Known Issues

• Column mapping overrides are not yet available in the Smart Map step. If auto-detection gets the mapping wrong, there is currently no way to correct it before import. This will be added in a future release.

Dashboard Fixes

The dashboard now pulls all financial calculations from the same backend logic as the Reports page, eliminating discrepancies between the two views.

• P&L figures now match Reports exactly — revenue, expenses, and net profit on the dashboard are computed using the same shared calculation path as the Profit & Loss report. Previously, the dashboard used a simplified query that could double-count transactions with contra entries.
• Bank Balance shows ledger balance — the Bank Balance card now displays the actual book balance from your current account (1200), rather than an unrelated account.
• Year-to-date date range — the dashboard now caps at today’s date rather than projecting to the financial year end, matching industry practice used by Xero and FreeAgent.
• Tax Set-Aside computed server-side — Corporation Tax and VAT estimates are now calculated on the backend using precise arithmetic, removing all financial calculations from the browser. The frontend purely displays what the API returns.

Organisation Security

• Production-grade organisation identifiers — all organisation references now use proper random UUIDs, replacing development-era test values across the entire database.

Bug Fixes

• 429 rate limit responses — rate-limited authentication endpoints now correctly return 429 status codes instead of 500 errors. Affects login, TOTP verification, token refresh, registration, and password reset routes.

Business-Type Partitioning (TMADD 2.0 §4.4)

The community categorisation engine now evaluates consensus per business sector. When different types of business categorise the same merchant differently — for example, construction firms categorising a supplier as Materials while IT contractors categorise it as Equipment — the system recognises this and promotes separate rules for each sector.

• Business type setting — a new dropdown in Organisation Settings lets you identify your business sector (IT/Software, Construction, Consulting, Creative, and more). This feeds into the categorisation signal pipeline so your categorisation choices inform the right consensus partition.
• Partitioned consensus evaluation — when a merchant is contested at the universal level, the daily consensus job now evaluates each business type independently. If a sector reaches consensus on its own, a conditional global rule is promoted for that sector.
• Business-type-aware matching — when global rules are evaluated for your transactions, rules matching your business type take priority over universal rules. If you’re a construction business, you see construction-relevant categorisations first.
• Signal threading — all four categorisation signal emission points (rule creation, rule editing, rule updates, and import categorisation) now carry your organisation’s business type. Previously this field was always empty.

Pagination

• Transactions page — now paginated at 50 per page with server-side pagination. Page state is preserved in the URL so you can bookmark or share specific pages. Previously showed only the first 50 of all transactions with no way to navigate further.
• Rules page — now paginated at 25 rules per page with client-side pagination across all provenance levels (local, verified, global). Switching provenance tabs resets to page 1. Priority reordering continues to work correctly within the paginated view.
• Reusable pagination component — consistent navigation with ellipsis for large ranges, keyboard accessible, auto-hides when all items fit on one page.

Bug Fixes

• Fixed transactions page showing “Showing 50 of 116 transactions” with no working navigation — the Next button had no effect. Pagination now works correctly with full page controls.

Collective Categorisation Intelligence

SpeyBooks now learns from how businesses categorise their bank transactions and surfaces that knowledge back to every user. When enough businesses agree on how to categorise a merchant, a global consensus rule is created — giving new users instant auto-categorisation from day one.

This is a foundational shift from single-tenant rules to community-powered intelligence, delivered through a new system called the Global Rule Repository (GRR).

How It Works

• Signal collection — every time you categorise a transaction (during import, via rules, or manually), SpeyBooks records an anonymous signal capturing the pattern, operator, and target category.
• Consensus evaluation — a background process aggregates signals across all tenants using a confidence-weighted voting system. When enough distinct businesses agree (meeting the promotion threshold), a global rule is created.
• Provenance-aware matching — the rules engine now evaluates local rules, verified defaults, and global consensus rules together. A 7-dimension lattice score determines the winner, with your local rules always taking priority over community suggestions.

Provenance System

Every categorisation match now carries a provenance level explaining where the rule came from:

• Local — your own rules, created manually or during import.
• Verified — seed rules provided by SpeyBooks as sensible defaults.
• Global — community consensus rules, backed by agreement across multiple businesses.
• System — fallback behaviour (Suspense account).

Your local rules always win. Global consensus is a suggestion, never an override.

Rules Page Enhancements

• Provenance tabs — filter rules by Local, Verified, or Global to see exactly what’s driving your categorisation.
• Global consensus section — read-only view of community rules showing confidence scores, the number of businesses that agree, and how each global category maps to your chart of accounts.
• Enhanced test panel — test any transaction description and see the full score vector as labelled chips, the provenance badge, and social proof for global matches.
• Override indicators — when your local rule disagrees with global consensus, an amber banner shows what the community thinks, letting you make an informed choice.

Import Preview Enhancements

• Provenance dots — each auto-categorised row in the import preview shows a coloured dot indicating whether a local rule (blue) or global consensus (green) made the suggestion.
• Global consensus matching — the import engine now evaluates global rules alongside your local rules, increasing auto-categorisation rates for new users.

Privacy

All signals are aggregated using blind hashing. No tenant can see another tenant’s rules, accounts, or categorisation decisions. The global rules table contains only normalised merchant keys, standard categories, and aggregate statistics.

Known Issues

• Global rules currently operate at the Universal level only. Business-type partitioning (where “SCREWFIX” maps to Materials for construction businesses but Equipment for IT contractors) is designed but not yet active.
• The taxonomy mapping for OtherExpense resolves to Repairs and Renewals, which may not be the most intuitive default for all businesses. This will be refined as more signal data is collected.

Security Test Harness

SpeyBooks now runs an automated security test harness against live production infrastructure. The harness checks 21 controls across six areas and publishes the results as a transparency report on the Insights page.

• 21 automated controls — covering firewalls, secure configuration, patch management, access control, malware protection, and operations. Every test runs against the real system, not a staging copy.
• Monthly transparency reports — results are published to Insights within 24 hours of each assessment. Grade, findings, and remediation plans are all public.
• Grade C to A (100%) — the first published assessment started at Grade C with real findings. Every issue was investigated and resolved, finishing at Grade A with zero failures and zero skipped tests.

Rate Limiting Fix

A bug in the error handler meant rate limit responses were returned as generic 500 errors instead of proper 429 status codes. The rate limiter was firing internally but clients never received the rate limit signal.

• Correct 429 responses — all rate-limited auth endpoints now return HTTP 429 with a clear message and retry timer.
• Three protected endpoints — login, registration, and password reset are all verified by the test harness.

Auth Audit Logging

Authentication events are now logged to a dedicated audit table for security monitoring.

• Pre-authentication logging — failed login attempts, unknown user probes, and password reset requests are captured with IP address, user agent, and timestamp.
• Anomaly detection — the test harness checks for brute force patterns, credential spraying, and suspicious post-failure logins.

Infrastructure Hardening

• Probe path blocking — common scanner paths now return 404 instead of being caught by the SPA fallback.
• Node.js 22 LTS — upgraded from Node 20 (maintenance) to Node 22 (current LTS). All three applications rebuilt and verified.
• Fail2ban whitelist — the server’s own IP is now whitelisted to prevent the security harness from triggering its own defences.
• Security headers — all four domains now pass all six security header checks.

Bug Fixes

• Fixed rate limit error handler returning 500 instead of 429 on all auth endpoints.
• Fixed probe paths returning 200 via SPA fallback instead of 404.

Interactive Developer Shell Demo

The features page now has a live, interactive terminal instead of a static screenshot. Visitors can type real commands, use Tab autocomplete, see ghost text suggestions, and click entity IDs in responses — exactly like the real Developer Shell inside the app.

• Auto-typing intro — the shell auto-types GET /invoices when it scrolls into view, showing syntax-highlighted JSON with clickable inv_142 and cont_8 IDs before the visitor touches anything.
• Full interaction — Tab completion, arrow-key history, ghost text acceptance with →, coloured method input (green for GET, blue for POST, amber for PUT, red for DELETE).
• Clickable entity IDs — click any prefixed ID in a response (inv_142, cont_8, txn_501) and it populates the input ready to fetch the detail view.
• Canned demo data — invoices, contacts, transactions, chart of accounts, organisation, and categorisation rules. Unknown routes return a friendly 404 with a hint.
• No auth required — runs entirely client-side with sample data. Hydrated on scroll via client:visible so it doesn’t affect page load.

The header now reads “Developer Shell — Give it a spin” with copy that invites interaction rather than describing a screenshot.

Pricing Page Sync

The pricing page feature lists were out of date — still showing generic bullets like “Bank reconciliation” and “Dividend vouchers” while the app had shipped scoped API keys, TMADD lattice scoring, DLA with S455 warnings, and more.

Pricing Cards (PricingCard.tsx)

• Sole Trader card — now shows 9 feature bullets covering double-entry, invoices, CSV bank import, auto-categorisation, VAT returns, REST API, Developer Shell, scoped API keys, webhooks, and dark mode.
• Limited Company card — uses “Everything on Sole Trader, plus:” pattern with 7 Ltd-specific bullets: director management, DLA with S455 & BIK, year-end snapshots, dividend wizard, board minutes, corporation tax set-aside, and dividend tax calculator.

Pricing Page (pricing.astro)

• Everything Included grid — all six feature categories updated to match the features page. Added auto-categorisation, contacts, scoped API keys, idempotency, webhooks, custom metadata, Row-Level Security, and public bug tracker.
• Roadmap section — removed Webhooks (shipped) and Open Banking (uncertain). Added Payroll integration.
• Version bumped to v4.10.1.

Homepage Pricing (PricingSection.tsx)

• Updated the toggle card feature bullets from generic items to shipped features with accurate Ltd-gated items.

Changelog Stats Redesign

• Card-based layout — replaced inline flex stats with three gradient stat cards (Lines of Code, Releases, API Endpoints) matching the transparency page design.
• API Endpoints card — now links to the API documentation at docs.speybooks.com/api-reference/overview with a “View API docs →” link.
• Breakdown line — dot separators between code breakdown spans for better scannability at small sizes.

Board Minutes PDF Generation

SpeyBooks now generates professional board minutes PDFs directly from the director detail page — no templates, no third-party tools.

• Companies Act compliant layout — resolution text, attendee list, financial summary, dividend allocations table, and dual signature blocks (Chair and Company Secretary/Director) on a single A4 page.
• Resolution reference traceability — each set of minutes carries a reference (e.g. BM-2026-02-DIV-06) that cross-references to the dividend voucher, giving HMRC a complete paper trail from board approval to shareholder payment.
• Verification ID — deterministic hash-based ID for document authenticity, matching the voucher verification pattern.
• Separate API route — board minutes PDF is served from its own endpoint, keeping the resource model clean.

Dividend Voucher & Minutes Downloads

Both documents are now accessible directly from the Dividend History table on the director detail page.

• Clickable voucher numbers — the voucher column now links directly to the voucher PDF download. Click DIV-0004 to download DIV-0004.pdf.
• Minutes download link — a “Minutes ↓” link beneath each voucher number downloads the associated board minutes PDF as Minutes-DIV-0004.pdf.
• Meaningful filenames — downloaded PDFs use the voucher number and resolution reference rather than internal IDs.

DatePicker Migration

All native date inputs across the Directors and Dividends flows have been replaced with the custom Radix UI DatePicker component.

• Consistent dd/mm/yyyy format — calendar popover with UK date formatting across all six date fields: Director create (appointed date), Director edit (appointed and resigned dates), DLA transaction form, Profit check (financial year end), and Board minutes (meeting date).
• Dark mode support — the DatePicker uses semantic tokens for full theme compatibility.

Dividend Table Alignment

• Auto layout — the table uses content-driven column widths instead of fixed proportions, preventing layout shift as data changes.
• Actions column — uses shrink-to-fit sizing so Pay, Void, and download controls sit flush-right without wasted space.
• Tabular numbers — amounts render in JetBrains Mono with tabular figures for vertical decimal alignment.

Button Hierarchy

• Declare Dividend promoted to primary — the main dividend action on the director detail page now uses brand blue (btn-primary), establishing clear visual hierarchy over secondary actions like Edit.

Director Detail Dashboard (v4.9.3)

The director detail page moved from a 7-section vertical stack to a 3-row dashboard grid, reducing scroll by roughly 50%.

• Row 1 — Stat cards — DLA balance, transaction count, and warnings for instant context.
• Row 2 — Profile vs Ledger — director information, shareholding, and S455 connected person in a fixed-width left column. DLA transaction ledger and year-end snapshots stack in the right column.
• Row 3 — Dividend history promoted — full-width row with horizontal breathing room for actions. No longer buried as section 7 of 7.
• Snapshots always visible — year-end snapshots are a permanent card rather than a collapsible accordion. In accounting, hidden equals unverified — S455 exposure and BiK data are too important to tuck behind a toggle.

UI Polish & Hydration Resilience

This update focuses on refined navigation patterns and resolving technical discrepancies between server and client rendering. We’ve introduced automated content awareness in the navigation and a more sophisticated mobile experience.

Navigation & UX

• Automated RSS Badges — The header now performs build-time checks on the Insights and Changelog feeds. “New” or “Update” badges appear automatically if content has been published within the last 48 hours.
• Mobile Action Zone — The mobile menu has been restructured to separate informational links from account actions. Primary CTAs now live in a dedicated, high-contrast footer area for better reachability.
• Glass-morphism Architecture — Implemented backdrop-blur and translucent backgrounds across header and mobile navigation for a modern, layered interface.
• Tactile Interactions — Added micro-animations to primary links and social icons, including sliding arrow transitions and scaling effects on hover and active states.

Technical Fixes

• Hydration Error #425 Resolved — Fixed a common React hydration mismatch caused by dynamic date strings in the footer. Implemented suppressHydrationWarning on time-sensitive elements to ensure stability between SSR and client-side takeover.
• Footer Grid Realignment — Corrected a column-span discrepancy in the secondary footer row. SpeyTech and Open Source columns are now perfectly aligned with the primary navigation columns above.
• Semantic SEO — Wrapped all navigation clusters in proper <nav> elements with ARIA labels and aria-current states to improve crawlability and screen-reader accessibility.

Infrastructure

• Consistency Sync — Synchronized the “Start Free Trial” and “Sign In” patterns between the Header and Footer to maintain a unified design language across the platform.

Changelog RSS Feed

Subscribe to SpeyBooks releases directly in your feed reader. The new dedicated changelog feed publishes every version with tags, release date, and a link back to the full entry.

Available at /changelog/rss.xml

What’s Included

• Dedicated feed — separate from the Insights articles feed at /rss.xml, so you can subscribe to releases without the blog noise
• Autodiscovery — feed readers detect the changelog feed automatically from any page on the site
• Full version history — every release from day one, sorted newest first

Infrastructure

• Changelog page restructured — moved from changelog.astro to changelog/index.astro to support the feed endpoint alongside the page. The URL hasn’t changed
• Footer updated — RSS Changelog Feed link added to the Service column

Marketing Site Rewrite

The homepage and features page now reflect what SpeyBooks actually ships — not what’s planned.

Homepage

• Hero copy rewritten — removed references to unshipped features (CLI, MTD submission, SDK libraries). The hero now leads with what’s real: double-entry ledger, invoicing, bank reconciliation, and a typed REST API.
• Features grid replaced — the six-card grid previously showed four planned features and one incorrectly marked as available. All six cards now show shipped, live capabilities: REST API with prefixed IDs, scoped API keys, immutable ledger, developer shell, auto-categorisation, and row-level security.
• Tech stack section — replaced “API libraries coming for Node/Python/Go” (none existed) with “Built with Fastify, React, PostgreSQL, TypeScript”.
• Pricing fix — removed “SQL” from “Full data export (SQL, CSV & API)” as SQL access is not yet available.

Features Page

• Four spotlight sections — API-first design, auto-categorisation, Ltd company support, and double-entry architecture each get a dedicated section with custom SVG illustrations.
• Fifteen-card feature grid — every card represents a shipped feature, badged as “Live”. Section title changed to “Production-ready from day one”.
• Copy refinements — headline updated to “Accounting as Code infrastructure developers enjoy using”, auto-categorisation reframed as “Categorisation you can audit, explain, and trust”, and trial language corrected (card required, 90-day for early access).

Schema-Driven API Documentation

API docs are now generated directly from the Zod validation schemas in the route files, eliminating drift between what the API accepts and what the docs describe.

Documentation Generator

• Single-command pipeline — pnpm run docs extracts schemas from route files, generates Docusaurus-compatible markdown, and rebuilds the documentation site.
• Two-source architecture — field names, types, required/optional, and constraints come from Zod schemas (always the source of truth). Descriptions, examples, and business rules come from context metadata files (written once, updated rarely).
• Missing field warnings — the generator reports any schema fields that lack descriptions, so new fields are never silently omitted from docs.

Resources Documented

Six core API resources now have accurate, schema-derived documentation:

• Invoices — 9 endpoints including create, update, status transitions, payments, email, and PDF download.
• Contacts — 6 endpoints including create, update, delete (with soft-delete for contacts with invoices), and financial summary.
• Transactions — 9 endpoints including create (with balance enforcement), status transitions, reconciliation, categorisation, and account ledger.
• Quotes — 7 endpoints including create, update, status transitions, and quote-to-invoice conversion.
• Accounts — 7 endpoints for chart of accounts management including hierarchy, balances, and account types.
• Organisation — 3 endpoints for company details and accounting settings.

Bug Fixes

• Invoice API: items vs lines — the API expects lines for line items but the documentation specified items. Documentation now matches the implementation.
• Invoice API: vatRate type — the API expects an integer (e.g., 20) but the documentation specified string values ("standard"). Documentation corrected.
• Invoice API: invoiceType undocumented — the invoiceType field is required on invoice creation but was completely missing from the documentation. Now documented with accepted values sales and purchase.

API Documentation Audit

A full audit of the API surface identified 99 public endpoints across 17 resources. The invoices documentation alone had 12 discrepancies with the implementation. The remaining 11 resources (categorisation rules, bank imports, API keys, reports, webhooks, directors, director loans, dividends, and supporting resources) are scheduled for Phase 2 documentation.

Dividend Management

SpeyBooks now has comprehensive dividend management — something neither Xero nor FreeAgent offer as a built-in feature.

Dividend Wizard Refactor

• Streamlined four-step wizard — the dividend declaration flow (profit check → board minutes → allocate → summary) has been refactored into focused, maintainable components while keeping the exact same user experience.
• Shared dividend library — payment methods, status labels, tax calculations, and voucher downloads now come from a single source of truth, eliminating inconsistencies across pages.

Mark as Paid & Void

• Mark dividend as paid — declared dividends can now be marked as paid with a payment date. This creates the corresponding payment journal automatically.
• Void dividends — dividends can be voided with a reason, which creates reversal journals and releases the amount back to the board minutes allocation.

Dividend Summary

• Per-director breakdown — a new summary page shows each director’s total declared, total paid, and outstanding amounts for the current financial year with visual progress bars.
• Navigation links — the dividend history table now links directly to the summary page for quick access.

Board Minutes

• Board minutes page — browse all board meeting resolutions at /dividends/board-minutes. Each entry shows the meeting date, status, approved amount, and a progress bar showing how much has been declared against it.
• Expandable detail — click any board minutes entry to see the associated dividends with director names, voucher numbers, amounts, and payment status.

DLA Year-End Snapshots

• Snapshot capture — take a year-end snapshot of any director’s loan account from their detail page. The system automatically calculates S455 corporation tax exposure, the S455 payment deadline, and Benefit in Kind liability using HMRC’s average method.
• Expandable snapshot cards — each snapshot shows the period end date, S455 status, and BIK applicability at a glance. Expand for full details including S455 rate, deadline, BIK official rate, average balance, overdrawn days, and P11D deadline.
• Duplicate protection — the system prevents creating multiple snapshots for the same director and period end date.

Director Detail Page

• Richer layout — the director detail page now includes DLA balance cards with warnings, editable director information, loan transaction history, year-end snapshots, and dividend history — all in focused, composable sections.

Bug Fixes

• Fixed snapshot API client using incorrect endpoint paths, which caused “Endpoint not found” errors when creating DLA snapshots.
• Fixed board minutes status badges displaying raw database values instead of human-readable labels.

Improvements

• Login page clarity — the login form now shows “Email address” with a helper hint instead of the ambiguous “Username” label. Tab order flows naturally from email to password to Sign In. The “Forgot your password?” link has moved below the form for a cleaner layout.
• Collapsible admin sidebar — the admin panel sidebar now collapses and expands identically to the main app, with keyboard shortcut (Cmd+B), localStorage persistence, and SpeyBooks favicon when collapsed.
• Invoice and quote numbering — the sequence number preview in Organisation Settings now displays five digits (INV-00001) instead of three, supporting businesses with higher document volumes.
• Bug report composer — the internal update textarea in the admin bug reports panel is taller and vertically resizable for pasting longer resolution notes.

Bug Fixes

• Stripe checkout — removed the “Save my information for faster checkout” option from the payment page to avoid appearing pushy during signup.

Bug Fixes

• API request logging restored — request logs stopped recording after the Row Level Security deployment on 7 February. The logger’s database context was silently discarded because it used a transaction-scoped setting outside of a transaction. Logging now works correctly for all API key authenticated requests, with a proper transaction wrapper ensuring the security context is applied.
• DLA transaction form layout — the “Record Transaction” form on the director detail page no longer displaces the section heading on narrow viewports. The form now renders as a full-width block below the header row.

Improvements

• Log detail panel formatting — the Response Body section in the API request log detail panel now displays large responses as formatted, readable JSON with a truncation notice showing original size, instead of displaying raw internal metadata. Binary responses (PDFs, file downloads) show a clean content type and size indicator.

Dividend Declaration Wizard

A guided four-step wizard for declaring dividends, accessible from the Director detail page or directly at /dividends/new.

• Profit sufficiency check — verifies retained earnings before you can proceed, showing available profits after deducting any previously declared dividends for the financial year.
• Board minutes recording — captures meeting date, attendees, total dividend amount, and optional notes. Creates a formal board resolution reference automatically.
• Per-shareholder allocation — distribute dividends individually or use “Split Equally” / “Split by Shares” for quick allocation. A progress bar tracks allocated vs approved amounts in real time.
• Voucher generation — each declared dividend generates a numbered voucher (DIV-0001, DIV-0002, etc.) with PDF download available immediately from the summary screen.

Dividend History on Director Detail Page

• Inline dividend table — the Director detail page now shows all declared dividends for that director, including voucher number, date, payment method, status, amount, and a one-click PDF download.
• Running total — a summary line shows total dividends declared across all entries.
• Empty state — when no dividends exist, a direct link to the wizard makes it easy to get started.

Improvements

• Plan-based feature gating — Directors and dividends features are only visible and accessible to limited company accounts. Sole trader accounts see a clean sidebar without these items, and direct URL access redirects to the dashboard.
• Allocation input fix — the dividend allocation amount field now allows free typing with updates committed on blur, rather than recalculating on every keystroke.

Directors Management UI

A full management interface for company directors and shareholders, following the same page architecture as contacts, invoices, and accounts.

• Directors list — view all directors at a glance with role badges (Director, Director & Shareholder), status indicators, share counts, and appointment dates.
• Add Director — full-page form with sections for role selection, basic information, shareholding details (share class, shares held), and S455 connected person relationships.
• Director detail — view and inline-edit director information, with a Director Loan Account section showing balance, transaction history, and warnings ready for Phase 3.2.
• Connected persons — track S455 relationships (spouse, civil partner, child, parent, sibling) between directors for aggregated tax exposure calculations.

Plan-Based Feature Gating

Limited company features are now hidden from sole trader accounts across three layers, ensuring a clean experience for every business type.

• Sidebar filtering — the Directors navigation item only appears for limited company accounts. Sole traders see a streamlined sidebar without features that don’t apply to them.
• Route guard — direct URL access to directors pages redirects sole traders to the dashboard silently, preventing confusion from bookmark or shared links.
• API enrichment — the authentication endpoint now returns organisation plan information, enabling the frontend to make plan-aware decisions without additional requests.

Improvements

• Navigation architecture — sidebar navigation is now plan-aware with a filtering system that scales to future plan-restricted features without additional infrastructure.

Dividend Voucher PDFs

You can now download a professional dividend voucher as a PDF directly from the API. Each voucher is designed to be HMRC-ready and audit-friendly.

• Board Resolution Reference — every voucher includes a traceable reference linking it to the board minutes that authorised the dividend, making inspections straightforward.
• Per-share calculation — shows dividend per share and number of shares held, ready for multi-shareholder companies. A footnote clarifies the per-share figure is rounded down for display and the total dividend amount is authoritative.
• Verification ID — a deterministic hash printed on each voucher for document authenticity checks. Regenerating the same voucher always produces the same ID.
• PAID watermark — paid dividends display a subtle diagonal watermark behind the content, providing instant visual confirmation of payment status.
• Dynamic date labelling — the metadata header shows “Date Declared” or “Date Paid” depending on the dividend’s status, removing ambiguity.
• Companies Act signatures — signature blocks use “Authorised Director” and “Shareholder Acknowledgement” wording for legal compliance, anchored at the foot of the page with generous space for signing.
• Machine-readable metadata — PDF keywords include voucher number, company number, and resolution reference, making vouchers searchable in document management systems.

Bug Fixes

• Retained earnings calculation — profit sufficiency checks now correctly calculate retained earnings using proper double-entry sign conventions. Previously, profits could show as negative, preventing valid dividend declarations.
• Corrupted PDF downloads — voucher PDFs were being silently corrupted by the response pipeline before reaching the browser. The serialisation, caching, and logging layers now detect binary content types and pass them through untouched. Downloads produce valid, single-page documents that open correctly in all standard PDF viewers.
• Two-page overflow — the voucher layout engine now uses dynamic vertical positioning rather than fixed offsets, ensuring consistent single-page output regardless of how many payment breakdown rows appear.
• Account seeding — the migration for new dividend-related accounts now uses the correct schema, ensuring accounts are created reliably for all limited company tenants.

Directors & Shareholders

Full CRUD management for company directors and shareholders. Track appointments, resignations, shareholdings by class, and connected persons (spouses, children, associates) for aggregated compliance calculations.

• Director registry — add, update, and soft-delete directors with appointment dates, share class, and shareholding details.
• Connected persons — link family members and associates for aggregated S455 exposure calculations.

Director Loan Accounts

Complete Director Loan Account (DLA) tracking with automatic double-entry journal creation, HMRC compliance warnings, and year-end snapshot calculations.

• Loan transactions — record loans to/from directors, repayments, salary offsets, dividend offsets, and write-offs with automatic journal entries.
• Real-time balances — per-director and aggregated balances with overdrawn/credit status and warning levels.
• S455 Corporation Tax exposure — automatic calculation at current HMRC rates with deadline tracking. Rates update automatically for the April 2026 change.
• Benefit in Kind (BiK) — flags loans exceeding the £10,000 threshold with HMRC official rate calculations and P11D deadline tracking.
• Bed and breakfasting detection — warns when a repayment of £5,000 or more is followed by a new loan within 30 days, as HMRC may disregard the repayment for S455 purposes.
• Write-off warnings — high-severity audit entries when a director loan is written off, with clear guidance on the tax implications (treated as earnings, not dividend).
• Year-end snapshots — freeze DLA position at period end with full S455 and BiK calculations for filing.

Dividends

Declare and manage dividends with board minutes, profit sufficiency checks, voucher generation, and DLA offset support.

• Board minutes — record the resolution approving a dividend, with attendee tracking and a running allocation balance.
• Profit sufficiency check — validates retained earnings before allowing a declaration. Previously declared dividends for the same financial year are deducted automatically.
• Dividend declaration — issue dividends per director with auto-generated voucher numbers and double-entry journals.
• DLA offset — declare a dividend that offsets against an overdrawn director loan account in a single step, creating both the dividend and DLA journals automatically.
• Payment tracking — mark dividends as paid with a separate payment journal entry.
• Tax calculator — estimate UK dividend tax liability across basic, higher, and additional rate bands with the £500 dividend allowance applied. Shows effective rate and net dividend.
• Dividend summary — per-director breakdown of declared, paid, and unpaid dividends for any financial year.

Plan Gating

All Directors’ Loans and Dividends features are restricted to limited company accounts. Sole trader accounts receive a clear error message explaining the feature is not available for their account type. Subscription status is also verified — lapsed subscriptions are blocked with a prompt to reactivate.

Bug Fixes

• Fixed an issue where certain API routes were not receiving the correct database context, causing queries to return empty results. All routes now operate correctly under the multi-tenant architecture.

The Full TMADD Implementation

This release completes the True Mathematical Architecture Design Document (TMADD) — a four-phase overhaul of SpeyBooks’ transaction categorisation engine. What was a simple “first match wins” system is now a deterministic, explainable, auditable matching engine built with the same engineering discipline used in safety-critical systems.

Every categorisation decision now produces typed results, scores rules on a six-dimension vector, logs the decision with full evidence, and ships with sensible defaults for UK contractors. Six versions shipped in a single session: v4.3.0 through v4.6.0.

Rules Management Page (v4.3.0)

A dedicated Rules page where you can view, edit, delete, and reorder your categorisation rules.

• Full CRUD interface — table view with name, field, operator, value, target account, priority, and active toggle for every rule.
• Test panel — enter any transaction description and see which rule matches, why it matched, and the score breakdown. Essential for debugging categorisation before you import.
• Priority ordering — drag rules up and down or set explicit priority numbers. Auto-assigned priorities use gaps of 10 so you always have room to insert.
• Sidebar integration — “Rules” appears in the main navigation alongside Transactions and Import.

Phase 1: Typed Results & Evidence (v4.4.0)

Replaced the old “account or nothing” return with a proper typed result. Every categorisation now returns either Known (with the matched account and evidence) or Unknown (with a typed reason explaining why).

• Four failure reasons — NoMatch (no rules matched), AmbiguousTopScore (multiple rules tied with different accounts), InvalidRule (matched rule references a deleted account), and MissingField (transaction has no data in the target field).
• Evidence on every decision — the test panel shows exactly which field matched, which operator was used, what the normalised input looked like, and how many alternative rules were considered.
• Server-side rule creation — rule creation during import moved from the frontend to a dedicated API endpoint (v4.4.1). Rules are created atomically alongside the categorisation decision.

Phase 2: Lattice Scoring (v4.5.0)

Replaced sequential “first match wins” with a lexicographic lattice scorer. When multiple rules match the same transaction, the engine scores each one on six dimensions and picks the mathematical maximum.

The Six Dimensions

• OperatorStrength — equals (5) beats starts_with (4) beats contains (3). An exact match is inherently more specific than a substring match.
• FieldStrength — reference and contact fields score higher than description, which scores higher than amount. More informative fields produce more reliable matches.
• PatternSpecificity — longer match values are more specific. “COSTA COFFEE” (12 chars) beats “COSTA” (5 chars).
• ValueFit — how much of the input the rule covers. A rule matching the entire description scores higher than one matching a substring.
• Priority — your explicit priority number. When you deliberately set a rule to priority 100, it wins. Priority resolves intent; specificity resolves ambiguity.
• TieBreak — earliest creation date, then lowest ID. Guarantees absolute determinism under all conditions.

What This Means in Practice

If you have a contains "UBER" rule pointing to 7320 Travel and a contains "UBER EATS" rule pointing to 7460 Subsistence, the engine automatically picks the more specific rule for food deliveries — without you touching priority numbers. The score vector is visible in the test panel so you can see exactly why a rule won.

Regex rules include a specificity safeguard: literalChars − 2 × wildcards. A lazy .* pattern always loses; a precise TESCO.*LTD pattern scores comparably to equals.

Phase 3: Audit Trail (v4.5.1)

Every categorisation decision is now persisted with full evidence, enabling “why was this categorised here?” queries and regulatory audit readiness.

• Score vector stored — the six-dimension vector is persisted as an integer array alongside every decision, not just displayed in the test panel.
• Evidence as structured data — the full evidence object (matched field, operator, normalised input, rule count, reason) is stored as structured data for each decision.
• Row Level Security — audit entries are tenant-isolated using the same security model as all other SpeyBooks data.

Phase 4: Enhanced Logging, Corrections & Seed Rules (v4.6.0)

The final phase adds three capabilities that close the loop on categorisation intelligence.

Enhanced Match Logging

• Normalised description captured — the audit trail now records what the engine actually matched against after normalisation. “CARD PAYMENT TO SHELL PETROL” becomes “SHELL PETROL” — you can see exactly what the normaliser stripped.
• Bank name resolution — each decision records the canonical bank name (NatWest, Starling, Monzo, etc.) for bank-specific analytics. No more fragmentation from “NatWest” vs “NATWEST” vs “Nat West”.
• Outcome consistency enforced — Known decisions cannot have a failure reason; Unknown decisions must have one. The database enforces this constraint.

Correction Tracking

• User overrides logged — when you change an auto-categorised account during import preview, or recategorise a Suspense transaction later, the correction is recorded with the original decision, the new account, and the source of the change.
• Append-only history — multiple corrections on the same transaction are valid. The latest is authoritative; earlier corrections are training data for future rule improvements.
• Survives log maintenance — if older audit entries are purged, corrections remain intact with a null reference to the original decision rather than being cascade-deleted.

Seed Rules for New Accounts

New organisations are created with 26 high-confidence categorisation rules across 9 groups, tailored for UK sole traders and contractors.

• The Seed 9 — Fuel (Shell, BP, Esso, Texaco → 7300), Telecoms (BT, Vodafone, EE, O2, Three → 7540), Post (Royal Mail, Post Office → 7550), Parking (NCP, APCOA, RingGo, PayByPhone + catch-all → 7310), Subsistence (Greggs, Costa, Pret, Starbucks, Uber Eats → 7460), Travel (TfL, Uber, Trainline → 7320), Companies House (→ 7900), and ICO (→ 7900).
• Operator precision — BT uses starts with "BT " (not contains) to avoid matching DEBT, SUBTOTAL, or ABT. O2 uses starts with "O2 " to avoid CO2. UBER EATS has priority 110 vs UBER at 90 for explicit separation.
• Low regret only — we deliberately exclude HMRC (could be VAT, PAYE, SA, or Corp Tax), supermarkets (ambiguous between subsistence and office supplies), SCREWFIX/TOOLSTATION (context-dependent), AMAZON (massively ambiguous), and utility providers (sole traders claim flat-rate use-of-home, not actual bills).
• Marked as defaults — seed rules show a “(default)” badge in the Rules page. You can edit or delete them freely — they’re yours to customise.

The Complete Picture

No other accounting platform — Xero, FreeAgent, QuickBooks, or otherwise — provides typed categorisation failures with machine-readable reasons, evidence-backed decisions, specificity-aware matching, or full audit trails on every categorisation decision. This is safety-kernel engineering applied to financial data.

Categorisation Audit Log

Every categorisation decision that affects the ledger is now persisted to an audit trail. When the rules engine evaluates a transaction during import, the outcome, matched rule, score vector, and full evidence are logged.

• Complete decision history — query which rule categorised any transaction, when, and why.
• Score vectors stored — the 6-dimension lattice score is preserved as a native PostgreSQL array for efficient querying.
• Evidence as JSONB — the full evidence object (matched field, operator, normalised input, reason) is stored for regulatory audit and replay.
• Scoped to ledger changes — only import confirmations are logged. Test panel queries and preview evaluations are excluded to keep the audit trail focused.

This completes the three-phase implementation of the categorisation architecture: typed results (v4.4.0), lattice scoring (v4.5.0), and audit persistence (v4.5.1).

Lattice-Scored Rule Matching

The categorisation engine now uses a formal lexicographic lattice to select the best matching rule, replacing the previous “highest priority wins” approach. When multiple rules match a transaction, the engine scores each across six dimensions and selects the mathematically strongest match.

Score Dimensions

Each matching rule is scored as a 6-dimension vector, compared left to right:

1. Operator specificity — equals (5) beats starts_with (4) beats contains (3). Regex is scored dynamically based on literal character density.
2. Field strength — reference and contact_name (4) outrank description (2) and amount (1). More informative fields win.
3. Pattern specificity — longer match values are more specific. A rule matching “BRITISH GAS” (11 chars) outranks one matching “GAS” (3 chars).
4. Value fit — how much of the input the rule covers. An equals match scores 100%; a short contains on a long description scores proportionally less.
5. Priority — user-assigned priority (0–999), as before.
6. Tie-break — earliest creation date, then lowest ID. Guarantees determinism even when all other dimensions are equal.

What This Means

• Specific rules win automatically — an equals "TESCO STORES" rule beats a contains "TESCO" rule at the same priority, without manual priority tuning.
• Regex penalty — lazy patterns like .* are penalised. A regex TESCO.*LTD with 8 literal characters scores well; a regex .* scores near zero and loses to any literal match.
• Visible scoring — the test panel now displays the score vector with labelled dimensions, so you can see exactly why one rule won over another.
• Backward compatible — existing rules and priorities continue to work. The lattice adds specificity resolution on top of priority, it doesn’t replace it.

Evidence Improvements

• The test panel now shows the score vector: [3, 2, 12, 100, 10, -8] with dimension labels (op · field · pattern · fit · priority · tie).
• When multiple rules match, the evidence explains which dimension decided the winner (e.g. “won by operator specificity”).
• Ambiguity detection now compares full score vectors rather than just priority.

Server-Side Rule Creation

Rule creation during bank import is now handled entirely by the server. Previously, the import preview performed keyword extraction and rule creation in the browser — this has been moved to a dedicated API endpoint.

• Single source of truth — normalisation, keyword extraction, and rule creation logic now lives exclusively in the API. No duplicated business logic in the frontend.
• Smarter similar-row detection — when you categorise a transaction, the server identifies other rows in the batch with matching merchants and applies the same account automatically.
• Correct upsert behaviour — changing a categorisation during import updates the existing rule rather than silently failing.

This is an internal refactor with no change to user-facing behaviour. The import preview works exactly as before — categorise one transaction and similar ones update automatically.

Typed Categorisation Results

The categorisation engine now returns typed results for every decision — never a silent null. Every match includes an evidence object explaining why a rule won, and every non-match includes a typed reason explaining why no rule applied.

• Evidence on every decision — the test panel now shows what matched, which operator was used, the normalised input, and how many rules were evaluated.
• Typed Unknown reasons — when no rule matches, the engine explains why: no rules exist, no rules matched, or multiple rules matched with conflicting accounts (ambiguity detection).
• Ambiguity detection — if two rules at the same priority match a transaction but target different accounts, the engine flags the conflict instead of silently picking one. Shown with amber highlighting in the test panel.
• Normalised input visibility — the test panel shows the normalised form of your input (e.g. “TESCO STORES 4532” → “TESCO STORES”), so you can see exactly what the rules engine is matching against.

This is Phase 1 of the Lattice-Scored Total Matching architecture described in the TMADD. The matching logic is unchanged — the same rules match the same transactions. What’s new is that every decision is now typed, explainable, and never silent.

Bug Fixes

• Fixed keyword extraction during import — when categorising transactions in the import preview, rules were being created from raw descriptions (e.g. a rule for “CARD” from “CARD PAYMENT TO SCREWFIX”). Banking prefixes are now correctly stripped before keyword extraction, producing proper merchant-name rules like “SCREWFIX”, “BRITISH GAS”, “COSTA COFFEE”.
• Fixed “apply to similar” matching — categorising one transaction now correctly applies to other transactions from the same merchant, not all transactions with the same banking prefix.

Technical Detail

The categorisation engine’s return type changed from Account | null to a typed CategorisationResult containing outcome, evidence, and reason fields. All callers (test endpoint, transaction suggestions, and import confirmation) have been updated. This is a non-breaking change — existing integrations continue to work with the addition of new response fields.

Rules Management Page

A dedicated page for viewing, editing, and testing the auto-categorisation rules that drive bank import matching. Rules are created automatically when you assign an account during import — this page lets you manage them after the fact.

What’s New

• Full rules table — see every rule at a glance with its name, match condition, target account, priority, and active status.
• Test panel — enter a transaction description and instantly see which rule matches, or whether it would fall through to Suspense (9999).
• Inline active toggle — enable or disable rules without opening an editor. Disabled rules are skipped during import matching.
• Edit modal — change any field on a rule including the match condition, target account, priority, and description.
• Create new rules — add rules manually via the “New Rule” button, not just through import.
• Delete with confirmation — remove rules you no longer need. Existing categorised transactions are unaffected.
• Priority ordering — each rule now displays its priority number. Use the up/down arrows to reorder, or set a specific priority (0–999) in the edit modal. Higher numbers are evaluated first.
• Auto-assigned priorities — new rules automatically receive a priority 10 higher than the current maximum, so they slot in at the top without manual numbering.

Improvements

• Typed API client — the categorisation rules API client now uses proper TypeScript interfaces instead of any types, with full type safety on all methods including the new reorder endpoint.
• Sidebar navigation — “Rules” now appears in the main sidebar between Import and Reports with a filter icon.

Dark Mode

Full semantic token compliance across the rules page, edit modal, delete confirmation, and test panel. No raw colour values.

Import Fixes & Description Normalisation

Description Normalisation

Transaction descriptions are now normalised before rule matching and rule creation. This dramatically improves auto-categorisation accuracy across imports.

• Trailing branch codes stripped — “TESCO STORES 4532” is normalised to “TESCO STORES” before matching. A single rule now covers all branches.
• Common prefixes removed — “CARD PAYMENT TO”, “DIRECT DEBIT TO”, “FASTER PAYMENT TO” and similar banking prefixes are stripped before matching.
• Bidirectional normalisation — normalisation applies both when matching incoming transactions against rules AND when creating new rules from user categorisations. Rules are stored with clean keywords automatically.

Account Badges with Names

The Transactions page now shows full account names alongside codes in the Account column.

• Named badges — “7460 Subsistence” instead of just “7460”. Long names are truncated with a tooltip showing the full text on hover.
• Cleaner Suspense badge — simplified to just “Suspense” in amber.

Bug Fixes

• Zero-amount rows now skipped at upload time — rows with £0.00 amounts (e.g. LIDL GB INVERNESS) are marked as skipped during CSV parsing rather than appearing selectable in the preview and being silently rejected at confirm time.
• Account column shows names — the Transactions page Account column previously showed only numeric codes (e.g. 7460), now shows the full account name.

Known Issues

• Zero-amount rows display an “Error” badge in the import preview instead of “Skipped”. The row is correctly disabled and excluded — this is a cosmetic label issue only.

Transaction Categorisation & Import Enhancements

Inline Categorisation During Import

The import preview now includes an Account column where you can categorise transactions before they’re created. No more importing everything to Suspense and categorising afterwards.

• Inline account selection — every row in the preview shows either an auto-suggested account (green tick) or a dropdown to pick one manually. Uncategorised rows still post to Suspense (9999) as a safe fallback.
• Categorisation progress bar — shows “8 of 19 transactions categorised — 42%” with a colour-coded progress bar. Motivates you to clear the remaining uncategorised rows before importing.
• Silent rule creation — when you pick an account from the dropdown, a categorisation rule is automatically created in the background. No prompts, no extra clicks. Next time you import, those transactions categorise themselves.
• Apply to similar — categorising one TESCO row instantly applies the same account to all other TESCO rows in the import. The progress bar jumps accordingly.
• Rule upsert — change your mind? Pick a different account and the existing rule updates automatically. No stale rules accumulating.
• Per-row account overrides — each transaction can go to a different account during import. Priority: user override → rules engine → Suspense.

Auto-Categorisation on Import

The categorisation rules engine now runs during the confirm step. If you’ve set up rules (or they’ve been silently created from previous imports), matching transactions skip Suspense entirely.

• Rules engine integration — each row is evaluated against active categorisation rules before transaction creation.
• Cumulative learning — the more you import, the fewer manual categorisations you need. Rules created from one import apply to all future imports.

Bank Format Auto-Detection

Selecting a bank account now auto-populates the Bank Format dropdown. Pick “NatWest - Business Current Account” and the format switches to NatWest automatically. Still changeable if the auto-detect gets it wrong.

Supported mappings: NatWest, RBS, Royal Bank of Scotland, Starling, Monzo, HSBC, Lloyds, Halifax, Bank of Scotland.

Account Column on Transactions List

The Transactions page now shows an Account column with colour-coded badges:

• Green badge with the account code for categorised transactions (e.g. 7460, 7530, 8020)
• Amber badge showing “9999 Suspense” for uncategorised transactions awaiting review

Duplicate Import Protection

Two layers of protection against importing the same CSV twice:

• Upload-time detection — rows are checked against previous completed imports on the same bank account. Matches are flagged as duplicates and auto-deselected in the preview.
• Confirm-time guard — already-imported rows are excluded from processing at the database level, preventing duplicates even if the same CSV is uploaded multiple times.
• Auto-deselect duplicates — duplicate rows are unchecked by default in the preview, so the Import button only counts genuinely new transactions.
• “Nothing to Import” messaging — when all rows are duplicates, the Done step shows an informative message instead of a misleading “0 imported successfully”.

Categorise from Transaction Detail

Transactions sitting on the Suspense account show an amber banner with an account dropdown and a “Categorise” button. The rules engine pre-suggests an account if a matching rule exists.

Bug Fixes

• Fixed transaction detail page journal lines display — both legs of the double-entry now render correctly.
• Minor frontend build fixes.

Known Issues

• Zero-amount rows (e.g. LIDL £0.00) pass duplicate detection but are skipped at confirm time. They appear as “New” in the preview but result in “1 skipped” on import. Rare in practice.
• Account badges on the transactions list show codes only (e.g. 7460) without names. A hover tooltip is planned.
• No “undo import” capability yet — incorrectly imported transactions must be deleted individually or via reversing entries.

Bank Statement Import

Upload a CSV file from your bank and SpeyBooks will parse it, detect duplicates, and create transactions automatically.

• 4-step import wizard — Upload, Map Columns, Preview, Confirm. Each step validates before moving on.
• NatWest format support — auto-detects columns from NatWest CSV exports including date, description, amount, and balance. Additional UK bank formats coming soon.
• Preview with running balances — review every row before committing, with total in/out summaries and date range at a glance.
• Duplicate detection — matches against existing transactions by date and amount to flag potential double-imports. You choose what to include.
• Zero-amount filtering — rows with £0.00 amounts are automatically skipped during import.
• Double-entry posting — each imported row creates a proper journal entry against the Suspense account (9999), ready for you to categorise into the correct expense or income accounts.
• Import history — every upload is tracked with row counts, date ranges, and completion status.

Bug Fixes

• Fixed a database connection initialisation bug that could cause intermittent query failures on new pool connections.
• Fixed API key authentication failing under certain conditions after server restart.
• Corrected status values in the import pipeline to match database constraints.
• Fixed column references in the import confirmation flow to align with the transaction schema.

Known Issues

• Transaction detail page only renders one journal line instead of both legs — the data is correct, this is a display bug.
• Imported transactions need a categorisation workflow to move them from Suspense to the appropriate expense or income accounts. This is the next priority.
• Additional bank formats (Starling, Monzo, HSBC, Lloyds) are planned for a future release.

Database Connection Fix

• Fixed search_path assignment on pool connections — a tagged template literal was silently failing to set the schema search path on new database connections, meaning queries could miss the accounting schema entirely. Existed since the file was written but was masked by routes that set search_path on their own client connections.
• Fixed console.warn slow query logging — same tagged template issue prevented slow query warnings from appearing in logs.

API Key Authentication Fix

• Fixed RLS policy blocking API key lookup — the authentication middleware needs to read the api_keys table before it knows which organisation the request belongs to. Row Level Security was requiring an organisation context that doesn’t exist yet at that point. Updated the SELECT policy to allow key lookup when no tenant context is set, while continuing to enforce tenant isolation for all other queries.

Invoice Form Fix

• Customer dropdown no longer shows “Loading…” indefinitely — the contacts query filters by type, and no customer contacts existed after the v4.0.0 data migration. Resolved by correcting test data. A follow-up improvement to show “No customers found” instead of “Loading…” when zero results are returned is planned.

SpeyBooks 4.0.0 is a foundational release. The chart of accounts, security posture, and frontend performance have been rebuilt from the ground up. Every new signup now gets a Sage-aligned UK chart of accounts that any accountant will recognise.

This release consolidates 13 incremental versions (3.6.4–3.6.17) shipped in a single day of focused development.

Chart of Accounts — Sage UK Standard

The default chart of accounts has been completely replaced with 118 accounts aligned to the Sage UK convention — the de facto standard used by thousands of UK accountants.

• Plan-aware seeding — sole traders and limited companies receive the correct accounts at signup
• Sole trader: Capital, Capital Introduced, Drawings
• Limited company: Share Capital, Director Loan Account, Dividends, Corporation Tax
• Full VAT breakdown across four accounts (VAT on Sales, VAT on Purchases, VAT Liability, VAT Allocations) — ready for Making Tax Digital
• Fixed assets with depreciation pairs — property, plant and machinery, office equipment, fixtures, motor vehicles
• Control accounts with typed constraints — 30+ control types enforced at database level
• Opening Balances (9998) and Suspense (9999) — essential for data migration and reconciliation
• Granular overheads — premises, utilities, vehicle, travel, office, professional fees, each with correct default VAT rates (20% standard, 5% reduced, 0% exempt)

Security Hardening

Every item on the pre-launch security checklist has been completed.

• Automated daily database backups to S3 with verified restore and 90-day lifecycle
• PostgreSQL 15 → 17 upgrade with security improvements
• Auth rate limiting on all 7 authentication endpoints
• Session invalidation on password change — existing sessions revoked immediately
• Fail2ban with 4 jails protecting SSH, nginx, and application endpoints
• UFW firewall — only ports 22, 80, 443 open
• Content Security Policy on all 4 domains
• HSTS preload submitted to browser inclusion lists
• security.txt deployed on all domains with correct contact and policy URLs
• DNS CAA records restricting certificate issuance to Let’s Encrypt
• Database role separation — application connects with least-privilege role
• SSL Labs A+ rating — TLS 1.3, HSTS, EC 256-bit key
• robots.txt on app and API domains to prevent indexing of authenticated content
• Docker removed — direct process management, reduced attack surface
• OS-level updates applied

API Key Rotation

• New endpoint: POST /api/v1/api-keys/:id/rotate generates a replacement key with the same name and scopes
• 24-hour grace period — the old key remains valid during transition, then auto-expires
• Double-rotation protection — cannot rotate a key that is already rotating
• Full audit trail — rotation events logged with key lineage tracking
• Frontend UI — rotate button, amber status indicator, grace period countdown, new key reveal

Performance

• Code splitting — 41 pages lazy-loaded on demand with vendor chunk separation
• Initial bundle reduced from 1,020 kB to 84 kB — users download only the JavaScript they need
• Vendor chunks cached independently: React, data layer, utilities, UI components
• Build time improved from 15s to 14s

Infrastructure

• Log retention aligned to GDPR and HMRC requirements (7-year financial, 2-year access, 30-day debug)
• Failed login monitoring with real-time alerting
• CORS configuration corrected for production domains
• Duplicate TLS certificates cleaned
• pg_hba.conf reviewed and hardened
• SEO fixes — favicon.ico, registration error hardening

Code Splitting

• 41 pages now lazy-loaded on demand with loading spinner fallback
• Vendor chunk splitting — shared libraries cached separately from application code
• Initial bundle reduced from 1,020 kB to 84 kB — pages load only the JavaScript they need
• Faster first paint and reduced bandwidth for all users

DNS & Security

• DNS CAA records added — only the authorised certificate authority can issue SSL certificates for SpeyBooks domains
• security.txt contact and policy URLs corrected
• robots.txt added to application and API domains to prevent search engine indexing of authenticated content

API Key Rotation

Seamless key rotation with zero-downtime grace period.

• Rotate endpoint — generates a new key while the old key continues to work during a grace period
• Grace period — old key remains valid for 24 hours after rotation, then stops working automatically
• Key linking — rotated keys are linked to their replacement for audit trail
• Double-rotation protection — a key that is already being rotated cannot be rotated again
• Auth middleware — automatically rejects keys whose grace period has expired
• Full audit logging on all rotation events

Database Role Separation

Replaced the single shared database role with proper separation of duties:

• Admin role — owns all database objects, used for maintenance and manual administration
• Application role — least-privilege connection with DML-only access, row-level security enforced
• Elevated role — unchanged, used for specific admin queries via role switching

Legacy shared role has been dropped. Application now connects with minimum required privileges.

Cleanup

• Removed stale development-era table from public schema
• Removed duplicate SSL certificate (covered by multi-domain cert)

Content Security Policy

• All SpeyBooks domains now return Content-Security-Policy headers
• Each domain has a tailored CSP matching its content requirements
• API endpoints use a strict restrictive policy

HSTS Preload

• speybooks.com submitted to the HSTS preload list — browsers will enforce HTTPS-only before first visit once propagated to Chrome, Firefox, and Safari

CORS Origin Fix

• Fixed stale CORS origin — updated to match current application domain

Log Retention Policy (GDPR / HMRC)

• Audit logs: 12-month retention with automatic cleanup
• Authentication tokens: 30-day cleanup for used tokens
• Accounting data: never deleted (7-year HMRC requirement)
• Access logs: extended retention to 90 days
• Application logs: weekly rotation with 12-week retention
• Automated monthly cleanup job

Infrastructure

• OS packages updated to latest stable versions
• Removed unused package repositories

Firewall

• Default deny incoming — only SSH, HTTP, and HTTPS traffic is allowed
• Intrusion prevention integrated with firewall for immediate banned-IP drops
• Previously unnecessary open ports now blocked

Attack Surface Reduction

• Removed unused container runtime and related packages
• All internal services bind to localhost only — nginx handles all external traffic

SEO Fixes

• Title lengths — shortened article titles to stay within optimal length including suffix
• Description lengths — trimmed article and page descriptions to stay within recommended limits
• favicon.ico — generated multi-resolution ICO from existing SVG

Failed Login Monitoring

• Automated monitoring for suspicious authentication activity
• Email alerts sent to ops when failed login thresholds are exceeded, including top offending IPs

Security Hardening

Batch of pre-launch security improvements across infrastructure and application.

• security.txt published at /.well-known/security.txt on all SpeyBooks domains per RFC 9116
• Intrusion prevention — automated brute force detection and IP banning for SSH, HTTP auth failures, bot scanning, and excessive 404 requests
• Backup lifecycle — automatic expiration policy applied to offsite backups
• Registration error hardening — error messages no longer reveal whether an email address is registered

Session Invalidation

Refresh tokens are now invalidated when a user changes their password.

• Password change revokes all existing refresh tokens immediately
• New tokens include a generation identifier validated on each refresh
• Mismatched generation returns 401 — user must re-authenticate
• Existing login sessions are unaffected until their refresh token expires or is used

This ensures a compromised session cannot persist after a password change.

Auth Endpoint Rate Limiting

Per-route rate limits applied to all public authentication endpoints, layered on top of the existing global rate limit.

Covers login, TOTP verification, token refresh, registration, password reset, and email verification — all keyed by IP address. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Existing account lockout on repeated failed passwords remains as a second layer of defence.

Automated Database Backups

Daily automated backups with cross-provider disaster recovery.

• Scheduled backups with local retention and offsite copy
• Cross-provider redundancy — backups stored on a separate cloud provider from the application server, in a UK region
• IAM scoped — backup credentials have minimum required permissions
• Restore verified — full dump-and-restore cycle tested against a separate database

PostgreSQL Upgrade

• Upgraded from PostgreSQL 15 to 17 with zero data loss
• PG 17 brings improved VACUUM, better JSON handling, and incremental backup support
• Old cluster removed, disk space reclaimed
• All data verified intact post-upgrade
• Fresh post-upgrade backup taken and uploaded offsite

Article CTA Overhaul

Replaced per-article markdown CTAs with a single consistent CTA section in the [slug].astro template. Full-width gradient background with soft launch messaging and early access positioning.

• Removed duplicate “Ready to Try It?” CTAs from all 11 Insights articles
• New CTA copy — “Early access for developers” with soft launch messaging, 90-day trial, and “Start free trial” / “Read the docs” buttons
• Full-width gradient — from-slate-50 to-slate-200 flows seamlessly into the dark footer
• Removed “Questions or feedback?” discuss box (redundant with contact page link in footer)

Footer Mobile Responsiveness

• Single-column stacking on mobile (grid-cols-1) with two columns from sm: breakpoint
• Larger tap targets — links scale to text-base with py-1.5 padding on mobile, reset to text-sm on desktop
• Heading size — bumped to text-base on mobile for better visual hierarchy
• Hidden spacer columns on mobile to prevent empty gaps in the grid

Terminal-Style Code Blocks

Insights article code blocks now render as terminal windows with macOS-style chrome (red/amber/green dots), automatic language labels detected from markdown fence tags, and a copy-to-clipboard button.

• Title bar — three-dot window chrome with language label (bash, TypeScript, JSON, etc.) aligned right
• Copy button — appears on hover in the bottom-right corner, shows “Copied!” confirmation for 2 seconds
• Line wrapping — long lines wrap instead of horizontal scrolling, improving readability on mobile
• Dark terminal background — #0f172a (slate-950) for authentic terminal feel

No changes to existing markdown files required — the terminal chrome is injected automatically from the article template.

Early Access Live Counter

• Homepage pricing section — Replaced static “first 50 users receive a 90-day free trial” text with live counter fetched from API (“49 of 50 early access spots remaining — 90-day free trial”)
• PricingCard API URL — Fixed incorrect /api/v1/stats/early-access → /api/v1/early-access/stats
• PricingCard response mapping — Fixed totalSpots → total field mismatch and unwrapped { success, data } response envelope

Early Access Query

• Accurate signup counting — Changed early access stats query from COUNT(*) FROM organisations to count only verified, non-admin users. Test and admin accounts no longer inflate the claimed count

API Fixes

• Public route auth bypass — Added /api/v1/early-access/stats to publicAuthPaths with correct full path (was matching prefix only, returning 401)
• Fastify 5 type fix — decorateRequest('audit', null as any) for v5 reference type restriction

Hydration

• Homepage flash fix — Reverted PricingSection from client:only="react" back to client:load to eliminate footer layout jump. No hydration mismatch because early access text renders from state (null on SSR, populated after fetch)

Accessibility

• Footer contrast — Bumped text-gray-400 to text-gray-300 and text-gray-600 to text-gray-400 across all footer text on dark backgrounds. Bottom bar elements (version, status, copyright, support email, data location) upgraded to meet WCAG AA 4.5:1 contrast ratio
• Pricing card contrast — Bumped text-gray-400 to text-gray-500 on white card backgrounds for “/mo”, “Cancel anytime”, and disclaimer text
• Lighthouse Accessibility score: 95 → 100

Performance

• Logo CLS fix — Added explicit width="224" height="56" to header logo <img> tag, eliminating Cumulative Layout Shift on load
• Astro asset caching — Fixed _astro/* cache serving 7-day TTL instead of 1 year. Added ^~ prefix to nginx location block so it takes priority over regex \.(css|js)$ match. Now serves Cache-Control: public, immutable with 1-year expiry
• React hydration errors — Switched PricingCard and PricingSection from client:load to client:only="react" to eliminate 6 console errors caused by SSR/client mismatch on components with dynamic fetch state

Security

• CSP tightened — Removed fonts.googleapis.com from style-src and fonts.gstatic.com from font-src since Google Fonts CDN was removed in v3.6.1

Scores (PageSpeed Insights, 8 Feb 2026)

• Desktop: Performance 100, Accessibility 100, Best Practices 100, SEO 100
• Mobile: Performance 96–99, Accessibility 100, Best Practices 100, SEO 100

Improved

• Self-hosted fonts on marketing site — Removed Google Fonts CDN dependency from speybooks.com. Inter and JetBrains Mono now served from /fonts/ as woff2 files, matching the app portal. Eliminates a 750ms render-blocking request on every page load and removes Google tracking
• Astro build compression — Added @playform/compress integration to the marketing site build pipeline. HTML (145 KB saved across 30 pages), SVG (13.8 KB across 18 files), PNG (19 KB, 64% reduction), CSS and JS all compressed at build time, before Nginx gzip
• Lighthouse Performance — Mobile score improved from 92 to 96. First Contentful Paint dropped from 2.6s to 1.8s. All requests now served from speybooks.com with zero external dependencies

Known

• Logo SVG missing explicit width/height attributes (minor CLS impact)
• _astro/* cache TTL is 7 days — could be extended to 1 year since Astro hashes filenames
• Footer and pricing card text contrast flagged by Lighthouse accessibility audit (text-gray-400/text-gray-500 on dark backgrounds)

Improved

• Fastify v5 upgrade — Migrated from Fastify 4.29.1 to 5.7.4 with all plugins updated to v5-compatible versions. Fastify v4 reached end-of-life on 30 June 2025; this resolves 3 outstanding security advisories (Content-Type bypass, sendWebStream DoS, fast-jwt iss validation)
• Request-scoped audit logging — Audit writes now use the RLS-aware database client inside the request transaction, with organisation_id auto-injected from request context. Replaces the previous instance-scoped decorator that bypassed tenant isolation
• Route response schemas — Added missing HTTP status codes (400, 404, 409) to route response schemas across auth, registration, accounts, transactions, and email verification routes. Fastify v5 enforces strict type-checking against declared response codes

Fixed

• Silent audit log failures — Since RLS was enabled in v3.5.0, all tenant audit writes were silently rejected because the audit decorator used a raw pool connection without RLS context. 282 total audit entries preserved; new entries now write correctly with full tenant isolation
• Plugin version constraints — Updated api-request-logger and rls-transaction plugins from fastify: '4.x' to '5.x' to resolve FST_ERR_PLUGIN_VERSION_MISMATCH startup failures
• Error handler type safety — Fastify v5 changed error handler signature to unknown. Added type narrowing for Zod, validation, database, and generic error branches

Security

• Dependency audit — Reduced vulnerabilities from 4 to 1. Remaining 1 is esbuild (moderate, dev-only via vitest/vite, not in production)
• Audit trail integrity — Tenant audit entries are now part of the same database transaction as the data change. If a transaction rolls back, the audit entry rolls back with it, preventing phantom audit records

Migration notes

• Zero breaking changes to the SpeyBooks API contract
• 16 files changed across server core, middleware, and 8 route modules (23 audit call sites migrated)
• authAudit remains instance-scoped and writes to the global auth_audit_log table (intentionally pre-tenant for security events)

Known

• esbuild dev server vulnerability (GHSA-67mh-4wv8-2f99) — dev-only dependency via vitest/vite, not present in production. Fix requires vite/vitest bump

Improved

• Self-hosted fonts — Inter and JetBrains Mono now served from /fonts/ instead of Google Fonts CDN. Eliminates external stylesheet dependency, removes Google tracking, and resolves CSP style-src violation in browser console
• Umami analytics — Privacy-focused, cookie-free analytics added to speybooks.com and docs.speybooks.com (same site ID, filterable by domain). No analytics on app.speybooks.com
• About page — Added “Defence in depth” principle card and expanded Technology section with dedicated row-level security subsection
• Changelog page — Fixed heading hierarchy (H1/H2), aligned stats bar layout, added progressive “Show more releases” button (10 entries per page)

Fixed

• CSP violation — Refused to load stylesheet fonts.googleapis.com error resolved by self-hosting fonts. Zero console errors in production
• @aws-sdk/client-ses — Updated 3.980.0 → 3.985.0, resolving fast-xml-parser RangeError DoS vulnerability (GHSA-37qj-frw5-hhjh)

Security

• Dependency audit — Reduced vulnerabilities from 5 to 4. Remaining 4 are all tied to Fastify v4→v5 major migration (post-launch backlog) or dev-only dependencies
• Security doc created — Doc with prioritised hardening checklist, threat model, and incident response plan

Known

• Fastify v4 has 2 advisories (Content-Type bypass, sendWebStream DoS) — requires v4→v5 migration, scheduled post-launch
• fast-jwt iss validation — requires @fastify/jwt upgrade tied to Fastify v5
• esbuild dev server vulnerability — dev-only, not in production

Fixed

• bug_reports table — RLS FORCE was set but ENABLE was not, meaning policies existed but were not being enforced. The table owner (accounting role) could bypass the four tenant isolation policies. ENABLE now applied — all operations enforced through RLS (bug_qfhk)
• user_organisations table removed from RLS scope — Was incorrectly included in the v3.5.0 batch migration. This is a global lookup table used by tenant middleware to establish org context, so it fundamentally cannot require org context to read. RLS disabled, policies removed. Now correctly classified alongside users, organisations, and sessions as a global table (bug_qfhk)
• rls-verify.sql script — Fixed three bugs: uses pg_class for FORCE column (was missing from pg_tables), nil UUID for no-context test (was empty string failing UUID cast), correct tl.amount column in P&L EXPLAIN (was nonexistent tl.entry_type)

Root Cause

Both table issues originated in the v3.5.0 RLS batch migration (rls-enable.sql). bug_reports only partially applied (FORCE without ENABLE). user_organisations was included in the tenant table list but should have been classified as global — it’s queried by the tenant middleware via the connection pool before any RLS context exists, causing 403 NO_ORGANISATION errors on all tenant-scoped routes.

Discovery

Found during post-RLS verification (step 1 of rls-verify.sql) which checks both relrowsecurity and relforcerowsecurity via pg_class.

Verification

• 25 tenant-scoped tables show rls_on=t, forced=t
• user_organisations correctly excluded from RLS (global table)
• Full 8-step RLS verification suite passing
• Dashboard and all tenant routes loading correctly
• No application errors after fix

Files Changed

• db/migrations/rls-verify.sql — Three bug fixes, org UUIDs populated

Fixed

• Auth audit logging restored — Login, logout, TOTP verification, password change, password reset, and email verification events are now recorded again after RLS broke the audit trail on auth routes (bug_azq6)

Root Cause

The fastify.audit.log() helper writes to the tenant-scoped audit_log table via the connection pool. After RLS was enabled in v3.5.0, INSERT operations on auth routes failed silently because no app.current_org_id session variable is set outside the tenant middleware. Auth events were lost — no user-facing impact, but security events went unrecorded.

Resolution

• New auth_audit_log table — Global table outside RLS scope, purpose-built for security events that occur before tenant context exists. Captures event_type, user_id, email, ip_address, user_agent, and details (JSONB)
• New fastify.authAudit.log() decorator — Writes directly to auth_audit_log via the pool, mirroring the existing fastify.audit.log() pattern
• Auth routes migrated — All 12 audit calls across auth.ts, password-reset.ts, and email-verification.ts now use authAudit.log() instead of audit.log()
• Tenant-scoped audit_log table unchanged — business event audit trail remains RLS-protected

Files Changed

• db/migrations/v3.5.2-auth-audit-log.sql — Migration: table, indexes, grants
• src/server.ts — AuthAuditEntry interface, authAudit decorator
• src/routes/auth.ts — 8 audit calls migrated
• src/routes/password-reset.ts — 2 audit calls migrated
• src/routes/email-verification.ts — 2 audit calls migrated

Housekeeping

• Removed stale organisation.ts.bak file

Security & Infrastructure

• RLS runtime repairs — Fixed 6 broken files from the v3.5.0 sed migration: admin-bug-reports.ts (corrupted handlers), admin.ts (handler signatures), admin-additions.ts (webhook handler), bug-reports.ts, server.ts (admin cleanup hooks). All replaced as complete drop-ins — no more sed.
• Admin middleware — requireAdmin now checks out a dedicated PoolClient and elevates to speybooks_admin role (BYPASSRLS). Cleanup via onResponse hook in server.ts.
• Transparency page — Fixed tagged template literal bug in fetch calls (fetch\…`→fetch(`…“). Stats and recent bug reports now load correctly.
• Status page CSP — Added app.speybooks.com and docs.speybooks.com to connect-src so health checks work.

Nginx Hardening (all 4 domains)

• IPv6 — Added [::]:80 and [::]:443 listeners across app, api, docs, and marketing configs.
• Per-site logging — Each domain now logs to /var/log/nginx/{domain}.{access,error}.log.
• Gzip — Enabled JSON compression on api.speybooks.com.
• OCSP — Removed non-functional OCSP stapling block from docs.speybooks.com (Let’s Encrypt ECDSA certs lack OCSP responder URL in chain).
• Symlink fix — docs.speybooks.com in sites-enabled was a standalone file, not a symlink. Replaced with proper symlink to sites-available.

Marketing Site

• Insights featured card — Changed from side-by-side layout to stacked (text top, hero bottom full-width), matching SpeyTech design.
• Page width consistency — Standardised max-w-4xl for status and insights article pages.
• Transparency status link — “All systems operational” indicator now links to /status/ page.

Known Issue

• Audit log on auth routes — Login/register audit trail silently fails when no tenant context is set. Auth works correctly; only the audit write is affected. Tracked for v3.5.2.

Summary

Database-enforced tenant isolation via PostgreSQL Row Level Security (RLS). Every tenant query now passes through a transaction-scoped session variable (app.current_org_id), and PostgreSQL itself rejects any row that doesn’t belong to the requesting organisation. This is defence in depth — even if application code omits a WHERE organisation_id = ? filter, the database returns zero rows.

What Changed

RLS Transaction Middleware (rls-transaction.ts)

New Fastify plugin wrapping every tenant-scoped request in a database transaction:

• onRequest: checks out a PoolClient from the pool, opens BEGIN, attaches to request.dbClient
• preHandler: calls set_config('app.current_org_id', orgId, true) after auth and tenant middleware have resolved the organisation
• onResponse: COMMIT and release
• onError: ROLLBACK and release

Registered on the tenantApi scope only — auth, registration, and public routes are unaffected.

Route Migration (7 files)

All tenant route handlers migrated from fastify.db.query() / pool.query() to request.dbClient.query():

• quotes.ts — 4 transaction blocks converted to savepoints (sp_quote_create, sp_quote_update, sp_quote_convert, sp_quote_delete)
• organisation.ts — settings update converted to savepoint (sp_org_settings), removed redundant SET search_path
• categorisation-rules.ts — reorder converted to savepoint (sp_reorder_rules)
• transactions.ts — create transaction converted to savepoint (sp_txn_create)
• invoice-email.ts — pool references replaced with request.dbClient
• invoice-service.ts — refactored with Queryable interface and withTransaction() helper that uses savepoints when called within the middleware transaction, or BEGIN/COMMIT when called at registration time

Savepoint Pattern

Routes that previously checked out a second connection (pool.connect() → BEGIN/COMMIT/ROLLBACK → client.release()) now use savepoints within the middleware’s transaction. The pattern: get request.dbClient, issue SAVEPOINT sp_name, do the work, then RELEASE SAVEPOINT sp_name on success or ROLLBACK TO SAVEPOINT sp_name on error. No finally block, no client.release() — the middleware handles that.

This keeps all queries on the RLS-scoped connection. No second connection, no leaked org context.

RLS Policies (25 tables)

Enabled ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY on all tenant-scoped tables:

accounts, api_keys, api_request_log, attachments, audit_log, bank_accounts, bank_imports, bank_statement_rows, bug_reports, categorisation_rules, contacts, entities, financial_periods, idempotency_keys, invoice_lines, invoices, recurring_transaction_log, recurring_transactions, settings, transaction_lines, transactions, vat_returns, webhook_deliveries, webhook_endpoints, year_end_log

Each table has four policies (SELECT, INSERT, UPDATE, DELETE) matching on organisation_id = current_setting('app.current_org_id', true)::uuid.

Exemptions

• user_organisations — excluded from RLS. This join table is queried during auth to resolve which org a user belongs to, before app.current_org_id can be set. No tenant data in this table.
• users — no organisation_id column, not a tenant table.

Database Role

Created speybooks_admin role with BYPASSRLS for admin panel queries and future migration scripts.

Technical Notes

• SET LOCAL doesn’t support parameterised queries in pg. Used set_config('app.current_org_id', $1, true) instead — the true parameter makes it transaction-local, equivalent to SET LOCAL.
• Fastify plugin hooks run before hooks added directly to the encapsulated instance. The set_config call is registered as a preHandler on tenantApi (not inside the plugin) to ensure it runs after apiKeyAuth and tenantMiddleware.
• The fastify.audit.log() helper in server.ts uses the pool directly and doesn’t include organisation_id. Auth route audit logs (e.g. LOGIN_SUCCESS) silently fail under RLS. This is a known issue — will be addressed in v3.5.1.
• Existing WHERE organisation_id = $N filters in route handlers remain in place. RLS is a safety net, not a replacement for correct application logic.

Migration

Run in order after deploying the updated code:

1. Build and restart (middleware must be live before enabling RLS): pnpm build then sudo systemctl restart speybooks
2. Enable RLS on all 25 tables: sudo -u postgres psql speytech_accounting -f db/migrations/rls-enable.sql
3. Verify with SELECT relname, relrowsecurity, relforcerowsecurity FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'accounting' AND c.relkind = 'r' AND c.relrowsecurity = true ORDER BY relname

What This Means

Before v3.5.0, tenant isolation relied entirely on application code — every query had to include WHERE organisation_id = ?. Miss one, and tenant A could see tenant B’s data.

After v3.5.0, PostgreSQL enforces the boundary at the database layer. The application filters are still there (belt), and RLS is the braces. For an accounting platform handling financial data, this is the standard you’d expect.

Improved

• SEO Validator v7.2.1 — Reduced false positives: relaxed title length thresholds (min 15, max 70), exempt utility pages from title checks, scoped heading hierarchy and soft 404 detection to <main> content only, added changelog exemption for legitimate 404-mentioning content
• docs.speybooks.com SEO — Disambiguated duplicate titles (Authentication ×2, Webhooks ×3), expanded 8 short meta descriptions on API reference pages, excluded internal DOCS-CONTENT-STATUS page from sitemap, fixed robots.txt and llms.txt MIME types to text/plain
• Security headers hardened across all four subdomains — added Content-Security-Policy to speybooks.com and docs.speybooks.com, added full security header suite to api.speybooks.com (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy), fixed nginx header inheritance in static asset location blocks
• Insights articles 9 & 10 — “Building Idempotent Financial APIs” (27 Feb) and “Why Accounting Software Shouldn’t Need a UI” (1 Mar) published with hero SVGs

Fixed

• nginx header inheritance — Static asset location blocks (/_astro/, images, CSS/JS) were silently dropping all server-level security headers due to nginx’s add_header inheritance model. Added X-Content-Type-Options to each block.
• api.speybooks.com security — Was serving zero security headers. Added HSTS, nosniff, DENY framing, referrer policy, and permissions policy to all three location blocks (proxy, root, catch-all).
• Bank feeds article polish — Softened Plaid settlement language, clarified PSD2 refresh phrasing, added SpeyBooks to CSV parties list for completeness

Data Corrections

Pricing in LLM Files

Both llms.txt and llms-full.txt were serving stale pricing (£14.95/£24.95 instead of £15/£25). The static public/llms-full.txt was also shadowing the dynamic Astro route, causing nginx to serve the pre-built file without charset=utf-8 — resulting in garbled characters for non-ASCII text (£, —, →). Removed the static file; dynamic route now serves as the single source of truth.

Email in LLM Files

Both LLM files referenced hello@speybooks.com instead of the correct support@speybooks.com. Updated to match all other pages.

Legal Entity in Privacy & Terms

Privacy policy and Terms of Service referred to “SpeyTech Ltd” — corrected to “SpeyTech” (sole trader, not limited company). Matches the JSON-LD legalName (“William Murray trading as SpeyTech”) and footer copyright already fixed in v3.3.8. Same correction applied to both LLM files.

FAQ Trial Period

FAQ answer for “Is there a free trial?” said “30-day” without mentioning the early access 90-day offer. Updated to explain both tiers: 90-day for early access (first 50), 30-day standard thereafter.

Content

Six New Insights Articles

Content pipeline for soft launch. Seven articles total including the original “What is Accounting as Code?” from v3.4.0:

• Double-Entry Bookkeeping for Developers (13 Feb) — Technical
• Why We Store Money in Pence (15 Feb) — Technical
• Zero Cookies: How We Built SpeyBooks Without Tracking (17 Feb) — Privacy
• MTD for Developers: A Technical Guide (19 Feb) — Compliance
• Designing an Accounting API: Lessons Learned (21 Feb) — Technical
• VAT Schemes Explained (With Code) (23 Feb) — Compliance

RSS feed at /rss.xml now serves all seven articles.

Infrastructure

nginx UTF-8 Charset

Added charset utf-8 and charset_types text/plain text/xml application/json to the main HTTPS server block. All plain text responses now include charset=utf-8 in the Content-Type header.

Sitemap Sync

Renamed “Documentation” → “Developers” column to match footer. Added root docs link, fixed RSS URL (/rss → /rss.xml), added SpeyTech and Open Source sections. All seven sitemap sections now mirror the footer exactly.

Cleanup

Mobile Menu Parity

Added missing “Insights” link to the mobile navigation menu. Desktop and mobile nav now have identical links in the same order.

Content Collection Schema

Added explicit changelog collection schema to content/config.ts. Astro now validates changelog frontmatter (version, date, title, tags) at build time.

Changelog Filename

Renamed v3.3.2.md → 3.3.2.md for consistency with all other changelog entries.

Footer Indentation

Fixed misaligned “View all projects →” link in the Open Source footer column. Added missing text-sm class to match sibling links.

Stale Directories Removed

Deleted src/public/ (duplicate of root public/) and src/src/ (20 legacy pre-migration files with old pricing). Neither was served or imported.

New Pages

Custom 404 /404

Branded not-found page with the SpeyBooks identity. Large faint 404 watermark, “Page not found” heading, and a developer-friendly tagline: “This page has a zero balance.” Links back to homepage and documentation. Served by nginx via error_page 404 /404.html with correct HTTP status code.

FAQ /faq

Ten frequently asked questions across five categories: Pricing, Platform, Data, Compliance, and API. Native <details>/<summary> accordions — zero JavaScript for expand/collapse. Category filter pills with minimal JS for show/hide. Colour-coded category badges per question. “Still have questions?” CTA section linking to contact and docs. FAQPage JSON-LD schema auto-generated from the data array, validated in Google Rich Results Test — all 10 questions detected as valid.

SEO & Social

Open Graph Meta Tags

Added og:image and twitter:image meta tags to BaseLayout.astro pointing to a branded 1200×630 OG image. Image includes the SpeyBooks logo (river wave + two-tone wordmark), “Accounting as Code” tagline, subtitle, and URL. Validated with LinkedIn Post Inspector — preview card renders correctly.

JSON-LD Structured Data

Expanded the SoftwareApplication schema from a basic stub to a comprehensive block. Now includes both pricing tiers (Sole Trader £15/mo, Limited Company £25/mo) with 30-day free trial, applicationSuite (“SpeyTech Accounting as Code”), audience targeting, publisher and author details, documentation link, changelog, terms, privacy policy, status and transparency URLs, and UK country support. Validated in Google Rich Results Test — all fields parsed, one optional non-critical note (aggregateRating).

Infrastructure

nginx 404 Handling

Updated the main HTTPS server block for speybooks.com from try_files $uri $uri/ /index.html to try_files $uri $uri/ =404 with error_page 404 /404.html. Missing URLs now return a proper 404 status code instead of silently serving the homepage.

Footer & Sitemap

New Links

Added FAQ to the Service column in the footer and the Service section in the sitemap. Accessibility and Anti-Tax Evasion pages (built in v3.4.1) wired into the sitemap Legal section.

Bug Fixes

Features Page Layout Break

Unescaped curly braces { } in the Astro template were interpreted as JSX expression delimiters, causing all sections after Developer Shell to collapse into a narrow right column. Escaped 10 occurrences across the API-first JSON code block and dark mode CSS preview.

Insights Code Block Styling

Fenced code blocks in articles rendered with individual white chips per line instead of a unified dark terminal block. Added pre code override in Tailwind config and changed <style> to <style is:global> in the slug template for Astro <Content /> compatibility.

Footer Grid Structure

Service column was rendering outside the grid on a separate row due to a premature closing </div>. Also fixed a missing <li> wrapper on Insights link, removed a stray <li> in Developers column, and added Features to the Product column.

Governance Pages

Accessibility (/accessibility)

WCAG 2.1 AA accessibility statement covering both marketing site and application. Includes POUR principles, concrete practices (semantic HTML, keyboard navigation, ARIA, screen reader testing), honest known limitations (PDF tagging, Stripe embeds, SVG illustrations), EASS enforcement route, and annual review schedule.

Anti-Tax Evasion Policy (/anti-tax-evasion)

Criminal Finances Act 2017, Part 3 compliance. Covers SpeyTech’s zero-tolerance position, product-level controls (double-entry enforcement, immutable records, integer arithmetic, API audit trail), all six HMRC prevention procedure principles, and a confidential reporting channel with non-retaliation commitment.

Infrastructure

RSS Feed (/rss.xml)

Production RSS feed using @astrojs/rss. Pulls Insights articles at build time, sorted newest first. Includes title, description, pubDate, categories, author, and custom metadata (language, copyright, lastBuildDate). Replaced old placeholder page.

Dynamic Sitemap (/sitemap)

Replaced static placeholder with a dynamic sitemap that pulls Insights articles from getCollection('insights') at build time. Three-column responsive grid with descriptions. New articles appear automatically on rebuild.

Deploy Script

Replaced cp -r dist/* with rsync -av --delete so the live site mirrors the build output exactly. Stale files (like the old /rss/ directory) are removed automatically on each deploy.

Line Counter

Shared count_lines function with consistent file extensions across all projects. Added missing types (.tsx, .jsx, .md, .mdx), safe xargs handling, and node_modules exclusion. Total: 59,803 lines.

Insights Section

Full content platform for “Accounting as Code” technical articles at /insights.

Listing Page

• Live search filtering by title and description
• Category filter buttons with article counts (Philosophy, Technical, Compliance, Privacy, Automation, Migration, Journey)
• Featured article card for the latest post (2-column layout on desktop)
• Article grid with load-more pagination (9 initial)
• Article count display with visible/total tracking

Article Pages

• Breadcrumbs (Home → Insights → Article)
• Reading time calculation (238 WPM)
• Category badge, author, date, and tags
• schema.org Article structured data
• Author footer and discussion link
• Trial and API docs CTA

Infrastructure

• Astro content collection with Zod schema validation
• @tailwindcss/typography plugin for prose styling
• Site-wide pre code override to prevent code block corruption
• <style is:global> for Astro <Content /> compatibility

First Article

“What is Accounting as Code?” — the manifesto article defining the category. Covers the five principles (API-first, immutable records, server-side truth, plain-text formats, data ownership) with a curl vs dashboard comparison.

Removed

• Old placeholder Insights page (Coming Soon / Topics we’ll cover)

Features Page

New /features page presenting the platform’s technical capabilities for a developer audience. Not a feature matrix — a curated walkthrough of the things that make SpeyBooks different.

Spotlight

• Developer Shell — full-width section with custom terminal SVG showing a live GET /invoices request, JSON response with clickable prefixed IDs, ghost-text hints, and minor units annotation

Deep-Dive Sections

• API-First Design — prefixed IDs, minor units, idempotency keys, Zod validation. Includes curl code block with sample response
• Double-Entry Accounting — trigger-enforced balanced transactions with custom SVG showing a split journal entry alongside the PostgreSQL constraint. Database stats: 37 tables, 78 foreign keys, 28 CHECK constraints
• Display Math Only — server-authoritative arithmetic. Reuses the architecture diagram from the About page
• Scoped API Keys — 17 granular permissions across 9 resources with custom SVG showing a key card and permission matrix. Argon2id hashing, 403 rejection example
• Dark Mode — semantic token system with colour swatches and CSS custom property preview

Everything Else Grid

Twelve cards covering the remaining platform capabilities in a 4×3 responsive grid:

• Invoicing & Quotes, Bank Reconciliation, VAT Returns, Expense Tracking, Contact Management, Financial Reports, API Request Log, Audit Trail, Public Bug Transparency, Webhooks, No Tracking

Technical

• Three custom SVGs: devshell.svg, double-entry.svg, api-keys.svg
• Anchor IDs on all seven sections for future deep-linking (#developer-shell, #api-first, #double-entry, #display-math, #api-keys, #dark-mode, #more)

Header Navigation

Added Features and About to the site header navigation (desktop and mobile).

New order: Features → Pricing → Docs → About → Changelog → Transparency

Conversion path first, reference second, trust signals last.

Fix: Astro JSX Brace Escaping

Literal { and } characters in the API-first JSON code block and dark mode CSS preview were consumed by Astro’s JSX parser, collapsing the DOM tree from the first occurrence downward. All ten literal braces now wrapped in {'{'} / {'}'} expressions.