Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .agent/skills/merovingian-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: merovingian-review
description: "Review a Merovingian pull request, branch or local diff against this project's binding rules: docs/coding-rules.md, the security coding rules, the per-module AGENTS.md invariants, the Matrix v1.19 spec, and the change obligations (CHANGELOG, docs, ADR, version bump, PR headings). It targets the defect classes this project has actually shipped. Use when asked to review a PR, branch, diff or commit in this repository, to check a change before merge, to verify a subagent's or another session's work, or to post review comments on a Merovingian PR."
description: "Review a Merovingian pull request, branch or local diff against this project's binding rules: docs/coding-rules.md, the security coding rules, the per-module AGENTS.md invariants, the Matrix v1.19 spec, and the change obligations (CHANGELOG, docs, ADR, version and PR headings). It targets the defect classes this project has actually shipped. Use when asked to review a PR, branch, diff or commit in this repository, to check a change before merge, to verify a subagent's or another session's work, or to post review comments on a Merovingian PR."
---

# Merovingian review
Expand All @@ -22,7 +22,7 @@ against this skill.
| [references/rule-checks.md](references/rule-checks.md) | Grep-able rule checks and judgement checks from the coding and security rules |
| [references/recurring-defects.md](references/recurring-defects.md) | Defect classes this project has shipped and fixed, as questions to ask of a diff |
| [references/tests.md](references/tests.md) | Where a test belongs, required structure, what the gates catch and miss, how to run and read tests |
| [references/obligations.md](references/obligations.md) | CHANGELOG, docs, ADR, version bump, PR description: rules and commands |
| [references/obligations.md](references/obligations.md) | CHANGELOG, docs, ADR, version, PR description: rules and commands |

## Modes

Expand Down Expand Up @@ -192,7 +192,7 @@ under Verification as not reviewed.
| Tag | Meaning in this project | Blocks merge |
|---|---|---|
| **[Blocker]** | Wrong result, auth or signature bypass, a worker-trust violation, data loss, a crash, a deadlock or timeout, an unbounded cost reachable by an unprivileged client or remote, a weakened conformance assertion, a broken build or test | Yes |
| **[Major]** | Real defect on a plausible path; incomplete fix; behaviour without a test that fails if reverted; missing CHANGELOG, docs, ADR or version bump the project rules require | Yes, unless the author shows it is wrong |
| **[Major]** | Real defect on a plausible path; incomplete fix; behaviour without a test that fails if reverted; missing CHANGELOG, docs or ADR the project rules require, or a version change the owner did not ask for | Yes, unless the author shows it is wrong |
| **[Minor]** | Correct but fragile, unclear or wasteful; a missing negative-path test on non-security code; doc drift | No |
| **[Nit]** | Wording, naming, or style no tool owns | Never; collapse them |

Expand Down Expand Up @@ -260,10 +260,10 @@ One or two sentences: what the change does, and whether the diff supports what i

## Obligations
| Item | State | Evidence |
| CHANGELOG bullet in current version, right section | | |
| CHANGELOG bullet in the newest version's entry, right section | | |
| Docs per docs/AGENTS.md table | | |
| ADR (needed? numbered above all branches? index line?) | | |
| Version bump (or docs-only exemption) and all places agree | | |
| Version unchanged from the base unless the owner asked (ADR-0835), and all places agree | | |
| PR description headings | | |

## Evidence log
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that
tests. `src/database/AGENTS.md#Security rules — non-negotiable`
- Every BLOB write sets `BoundValue::binary`.
- One transaction is one pooled lease. Never take a second lease while holding one: that deadlocks (ADR-0154).
SQLite has exactly one write connection; a change that lets it open more brings back writes refused after
SQLite's 5 s busy timeout (ADR-0834).
- A read that combines several tables into one picture of a room runs in one read transaction (ADR-0161).
Federated join writes are single transactions (ADR-0714).
- Reads go by index, never scan. `PersistentStore` mutexes follow ADR-0517. A member added to `PersistentStore`
Expand Down
14 changes: 6 additions & 8 deletions .agent/skills/merovingian-review/references/obligations.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,24 +13,22 @@ ADR-0000/0001/0543/0740/0741. Only the formats are checked by tooling (`test_cha
upgrading.
- The bullet says what changed for the operator or client, not how, and ends with its ADR or finding ID.
- `CHANGELOG-pre-release.md` is frozen (ADR-0740). Any diff to it is a finding.
- A docs-only branch adds its bullets to the **current** version's entry and does not bump.
- Every branch adds its bullets to the **newest** version's entry; it opens a new entry only when the owner asked
for a new version (ADR-0835).

## Version

- One bump per branch, BUILD + 1, except documentation-only changes (ADR-0464). `AGENTS.md` and coding-guidance
edits count as documentation. Any code, build, packaging or test change means the bump applies.
- The version changes only when the owner asks (ADR-0835). A branch whose version differs from its base's, with no
request from the owner in its PR or linked discussion, is a finding, whatever the branch changes.
- Every place agrees with `meson.build`. The list is in `docs/versioning.md`: `src/main.cpp`,
`src/db_migrate.cpp`, the FreeBSD manifest, the NetBSD Makefile, three RPM specs (each also with a new dated
`%changelog` entry), the `scripts/build-*.sh` scripts, and the CHANGELOG heading.
- The number must not be taken by another open branch. Check before approving.
`%changelog` entry when the version changes), the `scripts/build-*.sh` scripts, and the CHANGELOG heading.

```bash
git show origin/main:meson.build | grep -m1 "version:"; grep -m1 "version:" meson.build
git show <base>:meson.build | grep -m1 "version:"; grep -m1 "version:" meson.build
grep -n 'version = std::string_view' src/main.cpp src/db_migrate.cpp
grep -n '^Version:' packaging/{rpm,rhel,opensuse}/merovingian.spec
grep -nE '^VERSION=' scripts/build-*.sh
for r in $(git for-each-ref --format='%(refname)' refs/remotes/origin); do
git show "$r:meson.build" 2>/dev/null | grep -m1 -o "version: '[^']*'" | sed "s|^|$r |"; done | sort -k3 | tail
```

## Docs
Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ report any unresolved conflict or unmet requirement. See
- Flag potential bugs or edge cases after the code explanation if relevant.
- With every change, update the relevant docs. See [docs/AGENTS.md](docs/AGENTS.md) for the update table.
- Before creating a new branch from main, pull from origin so that main is up to date.
- Bump the version number on creating a new branch, except for documentation-only changes. See versioning doc for all the places where the version number needs updating.
- Never change the version number unless the owner asks for it; a new branch keeps its base's version, and its
CHANGELOG bullets go in the newest version's entry. See the [bump policy](docs/versioning.md#bump-policy) and
[ADR-0835](docs/adr/0835-the-version-changes-only-when-the-owner-asks.md).
- Update the docs when code change invalidates something.
- Record a decision in the ADR register (`docs/adr/`) whenever you make one. A
decision qualifies when a future reader would otherwise be likely to undo it
Expand Down
7 changes: 6 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md)
tokens for this server's SFU, judged by the main process and refused to a server the room's ACL denies (ADR-0831).
* `delegate_delayed_leave` (MSC4195): this server sends a caller's delayed leave once LiveKit no longer shows them,
checked every 30 s and sooner on LiveKit's signed webhook, kept across restarts (ADR-0832, ADR-0833).
* A branch no longer bumps the version: it changes only when the owner asks, and a change adds its bullets to the
newest version's entry here (ADR-0835).

## Security Fixes

Expand All @@ -28,12 +30,15 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md)

* `use_state_after`: a room forked at `since` now gets exactly what changed since what the client was told, read from an
in-memory log of state changes, and so does a left room (ADR-0827).
* SQLite writes share one connection, whatever `database.pool_size` says: a second write connection waited for the
first's lock by polling, lost to its back-to-back commits and was refused after 5 s, failing the write (ADR-0834).

## Release notes

Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, with delegated leaves,
and an exact `state_after` on `/sync`. It adds migration 004 (`livekit_delegations`). After a restart, the first
`state_after` sync of each room with news carries its whole state once.
`state_after` sync of each room with news carries its whole state once. A SQLite server no longer refuses writes under
sustained write load, and `database.pool_size` now applies to PostgreSQL only.

# Version 1.1.2

Expand Down
4 changes: 2 additions & 2 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ new documents.

| Document | What to add/update |
|---|---|
| `../CHANGELOG.md` (repo root) | Describe what changed. Add a new `# Version X.Y.Z` entry when the version changes, with exactly the headings `## Features`, `## Security Fixes`, `## Bug fixes` and `## Release notes`: bullets of two lines at most, and one short release-notes paragraph ([changelog format](versioning.md#changelog-format), [ADR-0741](adr/0741-each-changelog-version-has-features-security-fixes-bug-fixes-and-release-notes.md)). Documentation-only changes add bullets to the current version's entry without a bump. Never add to `../CHANGELOG-pre-release.md`, the frozen record of the 0.x series ([ADR-0740](adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). |
| `../CHANGELOG.md` (repo root) | Describe what changed. Add a new `# Version X.Y.Z` entry only when the owner asks for a new version, with exactly the headings `## Features`, `## Security Fixes`, `## Bug fixes` and `## Release notes`: bullets of two lines at most, and one short release-notes paragraph ([changelog format](versioning.md#changelog-format), [ADR-0741](adr/0741-each-changelog-version-has-features-security-fixes-bug-fixes-and-release-notes.md)). Every other change, documentation-only or not, adds bullets to the newest version's entry and never changes the version ([ADR-0835](adr/0835-the-version-changes-only-when-the-owner-asks.md)). Never add to `../CHANGELOG-pre-release.md`, the frozen record of the 0.x series ([ADR-0740](adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). |

## Update when the matching domain changes

Expand All @@ -17,7 +17,7 @@ new documents.
| `coding-rules.md` | A project-wide coding rule is added, changed, or removed. Maintain the rule here; the root `AGENTS.md` requires this document rather than copying its rules. |
| `security-coding-rules.md` | A security-relevant rule is added, changed, or removed in any module `AGENTS.md` file |
| `testing-standards.md` | A new testing convention is adopted |
| `versioning.md` | Version scheme changes; see also the version bump table |
| `versioning.md` | Version scheme or bump policy changes; see also its table of version locations |
| `auth-identity.md` | Auth, session token, or identity changes |
| `crypto-boundary.md` | Crypto interface, key management, or signing changes |
| `database-persistence.md` | Schema changes (migrations), store interface changes |
Expand Down
5 changes: 5 additions & 0 deletions docs/adr/0154-pool-database-write-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,8 @@ copies of it; `bootstrap_local_database` applies `database.pool_size` through
a fresh connection dying mid-transaction always did.
* A replaced SQLite file is not reopened by pooled handles until restart (they keep the file they
opened, which is also what the DB-10 no-follow checks protected).

## Links

* Refined by [ADR-0834](0834-sqlite-writes-share-one-pooled-connection.md): SQLite writes use one pooled connection,
because the busy timeout does not absorb contention between this process's own connections.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Documentation-only changes do not require a version bump

* Status: accepted
* Status: superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md)
* Date: 2026-11-05

## Context and Problem Statement
Expand Down Expand Up @@ -32,3 +32,7 @@ The maintained policy is in [versioning](../versioning.md#bump-policy).
### Negative Consequences

* Authors must check whether later changes make a branch more than documentation-only.

## Links

* Superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md)
3 changes: 2 additions & 1 deletion docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Versions from 1.0.0 are MAJOR.MINOR.BUILD

* Status: accepted
* Status: accepted; its per-branch `BUILD` increment is superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md)
* Date: 2026-11-11

## Context and Problem Statement
Expand Down Expand Up @@ -43,4 +43,5 @@ Chosen option: "`MAJOR.MINOR.BUILD`".
## Links

* Supersedes [ADR-0047](0047-keep-project-phase-out-of-the-version-string.md)
* Partly superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md): the per-branch `BUILD` increment
* [docs/versioning.md](../versioning.md)
86 changes: 86 additions & 0 deletions docs/adr/0834-sqlite-writes-share-one-pooled-connection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# SQLite writes share one pooled connection, whatever database.pool_size says

* Status: accepted
* Date: 2026-11-18

Technical Story: the DB-7 scenario "concurrent writes to SQLite reuse at most database.pool_size connections" lost
three of its 64 writes in a full test run on a loaded VM: three writers logged `connection.rejected sqlite_code=5`
and `transaction.failed stage=open` together, 5.3 s after the store opened. Refines
[ADR-0154](0154-pool-database-write-connections.md), which assumed that SQLite's 5-second busy timeout absorbs
contention for its single writer lock.

## Context and Problem Statement

SQLite in rollback-journal mode (`journal_mode = DELETE`, pinned by every connection) has one writer at a time,
and a connection that wants a lock another connection holds does not queue for it. Its busy handler polls: it
sleeps 1, 2, 5 ... ms, then every 100 ms, and gives up after 5 s of sleeps (`sqliteDefaultBusyCallback`). A
committing connection holds PENDING or EXCLUSIVE for the whole commit, journal syncs, database write and database
sync included (`syncJournal` takes EXCLUSIVE before its first sync), and PENDING refuses every new SHARED lock. A
pooled connection that commits back to back therefore holds the lock nearly all the time. Its next lease takes the
lock again within microseconds, while another connection of the same process, polling every 100 ms by then,
rarely arrives in the gap.

With `database.pool_size` connections allowed, the pool opened a second, third and fourth SQLite connection while
the first was committing. Each needs a SHARED lock to read the schema when it pins its pragmas, and each of
them polled against the first for 5 s and was refused: a write the client is told failed, because another write of
the same process was busy. The same refusal follows for a write that waits behind one slow write for longer than
5 s.

Should SQLite writes keep up to `database.pool_size` connections?

## Considered Options

* **One SQLite write connection: the SQLite write pool's limit is always 1 (chosen).**
* Keep `database.pool_size` connections and lengthen the busy timeout, or retry a refused open.
* Keep `database.pool_size` connections and serialise their transactions with a mutex.
* Write-ahead logging (`journal_mode = WAL`).

## Decision Outcome

Chosen option: one connection, because SQLite runs one write transaction at a time anyway, so a second connection
adds no parallelism and only a second place to wait, and that place is SQLite's polling, unfair, time-limited
busy handler. With one connection, every write of this process waits in the pool, on a condition variable that
wakes the next writer when a lease ends and never times out, which is how ADR-0154 already waits for a PostgreSQL
connection.

* `SqliteWritePool` holds a `ConnectionPool` of limit 1, and `set_write_connection_limit` (that is,
`database.pool_size`) changes only the PostgreSQL pool. `write_connections_opened` reports 1 for SQLite unless a
connection could not be opened.
* SQLite's busy timeout still governs this process's reads against its writer, and every lock another process
takes (`merovingian-db-migrate`, an operator's `sqlite3` shell). A read can still be refused after 5 s of
back-to-back commits; that is not changed here.

### Positive Consequences

* No write is refused because another write of this process holds SQLite's lock, however long it holds it.
* A waiting writer is woken when the lease ends rather than at its next poll, and does no busy polling.

### Negative Consequences

* A write that never ends blocks every later write instead of failing them after 5 s each. A write is one
transaction of statements built before the lease is taken, so nothing in it waits on anything but SQLite.

## Pros and Cons of the Options

### Lengthen the busy timeout, or retry a refused open

* Good, because it is a one-line change.
* Bad, because the wait stays unfair: a longer budget lowers the odds of a refusal under load but keeps it, and
every waiter polls. It raises the tolerance instead of removing the contention.

### Several connections, serialised by a mutex

* Bad, because the connections would never be used at once; the extra handles are idle weight, and
`database.pool_size` would claim a parallelism that does not exist.

### Write-ahead logging

* Good, because readers would no longer block a writer or be blocked by one.
* Bad, because the read-only connections refuse WAL on purpose
([ADR-0157](0157-never-open-a-sqlite-database-file-outside-sqlite.md): a read-only connection can still write
the WAL index), and the pinned journal mode is a durability decision (#447). Changing them is a decision of its
own.

## Links

* Refines [ADR-0154](0154-pool-database-write-connections.md)
Loading
Loading