inbuxa-server/docs/spec/compat-tests.md

Running the compat tests against a copy of INBUXA's data

Status: 2026-09-19. All eight run against a copy of INBUXA's data; see "The first run".

Each feature spec has one (compat) acceptance test: the check that INBUXA's own data opens in inbuxa-server and reads back as it did on the Enterprise server (SPEC.md §7). They are written, #[ignore]d, and unrun, because the repository has no copy of that data.

The fork's other #[ignore]d suites, the ones that need containers rather than INBUXA's data, are in container-tests.md.

Run them against a copy, never against the live server. Two of them delete data as part of what they check: monitoring_compat purges the telemetry history it has just read, and per_domain_directory_compat reads only, but the monitoring one is enough reason to treat the whole set as destructive. The brief bars touching INBUXA's production server, and these tests are not an exception.

What you need

1. A copy of the data store, opened with the same STORE backend the copy was taken from. TMPDIR is the copy's parent, not the copy. The harness opens $TMPDIR/<test name> (tests/src/utils/temp_dir.rs), so the copy for tenant_compat has to sit at $TMPDIR/tenant_compat, the one for scim_compat at $TMPDIR/scim_compat, and so on. Point TMPDIR at the copy itself and the harness quietly creates an empty store beside it and the test reports INBUXA's data as missing — a cutover blocker that isn't one. Each test wants its own copy anyway: monitoring_compat purges what it reads.

2. NO_INSERT=1, which stops the harness resetting and seeding the store. Every one of the eight refuses to run without it, before the store is touched (verified, "The dry run" below).

3. INBUXA_COMPAT_ADMIN, as name:password, for a server-level administrator in that copy.

4. For tenant_compat only: INBUXA_COMPAT_EXPECTED, a JSON file recorded from the Enterprise server before the move:

   {
     "tenants": {"<id>": {"name": "...", "quotas": {}, "members": ["<id>"]}},
     "tenantAdmins": {"<name>": {"password": "...", "accounts": ["<id>"],
                                  "domains": ["<id>"]}}
   }
   

5. For masked_email_compat only: INBUXA_COMPAT_MASKS, recorded the same way: [{"id": "...", "accountId": "...", "email": "...", "enabled": true}].

6. For undelete_compat only: INBUXA_COMPAT_ARCHIVED, the x:ArchivedItem/get results, each with its id and accountId: [{"id": "...", "accountId": "..."}].

Recording the three files

tools/fork/record-compat.py writes all three, and has to run while the Enterprise server is still up — after the cutover there is nothing left to record from, and SPEC.md §7 gives that 45 days from the notice.

tools/fork/record-compat.py --server https://mail.example.org \
    --admin '[email protected]:PASSWORD' --out ./compat \
    --tenant-admin '[email protected]:PASSWORD'

It only reads: it issues /get and /query and refuses to send anything else, so it is safe against the live server that the hand-off brief otherwise bars touching. It is the one thing that has to run there rather than on a copy.

Pass --tenant-admin once for each tenant administrator whose view should be checked: the script signs in as each and records the accounts and domains that administrator can see, which is what tenant_compat compares against. Without any, tenantAdmins is empty and the test checks only the tenants themselves. expected.json holds those passwords and is written 0600. --insecure skips certificate verification.

It was exercised on 2026-09-19 against the fork's own test server, which answers the same JMAP: it recorded 3 tenants with their members, 8 masked addresses and 3 archived items, in the shapes above.

Running them

tools/fork/run-compat.sh copies the store for each test and runs it:

tools/fork/run-compat.sh --store /srv/inbuxa-copy/rocks.db \
    --admin '[email protected]:PASSWORD' --recordings ~/compat

It takes --only <test name> for one, and --keep to leave each copy behind for a post-mortem. A test whose recording is missing is skipped by name rather than run against nothing.

The source copy has to be pristine. Several of these write to the store they open — monitoring_compat purges the history it reads, undelete_compat restores what it finds — and the harness adds its own listeners on the way in, so a copy that a run has already touched is not a copy of INBUXA's data any more. The script copies from the source for each test and removes the copy afterwards, so the source stays clean; take it from a stopped server or a snapshot, never from under a running one.

Why the copy's own listeners are ignored. A real server listens on 25, 443, 993 and the rest. Nothing in a test run is root, so every one of those fails to bind and the run died before reading any data, with eight Permission denied (os error 13) errors and nothing about what to do. Under NO_INSERT the harness now drops build errors belonging to listeners it did not add itself, and keeps every other error, including a bind that fails on one of its own (tests/src/utils/server.rs). The copy is not edited to achieve this; its listeners are simply not what a compat run needs.

Why the copy's task queue is ignored. A real server's pending tasks come with its store: ACME renewals due months from now, work that can never run on this machine. The harness waits for tasks to drain, so the first run against INBUXA's copy sat printing Waiting for pending task AcmeRenewal(...) until it was interrupted. Under NO_INSERT it now skips tasks that aren't due and ones that have failed for good, and gives up after a minute with the task printed, so the test fails on its own assertion instead of spinning.

Why compat- listeners appear in the copy. The harness needs listeners on its own ports, and the registry keys listeners by name. A real server has its own, and a production listener called jmap or imap collided with the harness's, killing every compat test at startup with Primary key conflict on property "name" before it checked anything. Under NO_INSERT the harness now names its listeners compat-jmap and so on (tests/src/utils/server.rs), out of the way of whatever the copy holds.

Running one

# the copy is at $TMPDIR/<test name>, e.g. /srv/compat/tenant_compat
NO_INSERT=1 STORE=<backend> TMPDIR=/srv/compat \
INBUXA_COMPAT_ADMIN='[email protected]:<password>' \
RUST_MIN_STACK=8388608 \
cargo test -p tests --features <backends> <test name> -- --ignored --exact

<test name> is the full path, such as system::tenant::tenant_compat. Run them one at a time: each starts a server on fixed ports.

The eight tests

Test	Feature	What it checks
system::tenant::tenant_compat	1, multi-tenancy	Tenants, their members and quotas read back unchanged, and each tenant administrator sees what it saw before (needs INBUXA_COMPAT_EXPECTED)
system::masked_email::masked_email_compat	2, masked email	Existing masked addresses still deliver, and their state reads back
system::undelete::undelete_compat	3, undelete	Archived items are still listed and restorable
system::branding::branding_compat	4, branding	Every domain's and tenant's logo, logoUrl and the three templates read back as stored
system::ai::ai_compat	5, AI spam	The twelve LLM_* tags and their scores
system::monitoring::monitoring_compat	6, monitoring	Retention, stores and indexTelemetry as observed; old history in the stripped encoding is skipped, not an error, and is gone after one purge (deletes history)
scim::scim_compat	7, SCIM	No domain open to SCIM, and no account with an externalId, as observed
directory::per_domain::per_domain_directory_compat	9, per-domain directories	No directory, no server default, and no domain with its own directory: any domain with one is a cutover blocker

The dry run

None of the eight has ever run against INBUXA's data, so on 2026-09-19 all eight were run against an empty store with synthetic inputs, to prove the plumbing before the day the copy exists. What that established:

• NO_INSERT protects the copy. A sentinel file was left in each store directory. Every run kept it, and the run without NO_INSERT stopped at "NO_INSERT must be set, or the copy of INBUXA's data is wiped" before the harness deleted anything. The guard is ahead of the store in all eight.
• TMPDIR is the parent. The store appeared at $TMPDIR/<test name>/rocks.db in every run, which is where the finding in "What you need" comes from.
• The documented JSON shapes parse. The three files above, written exactly as this page gives them, were read without complaint by tenant_compat, masked_email_compat and undelete_compat.
• A bad administrator now says so. Each test authenticates once before it asserts anything, and fails with INBUXA_COMPAT_ADMIN did not authenticate as <name> and the 401 body. Before that check the first call simply panicked with "Missing list in response", which reads like INBUXA's data is wrong when the login is what's wrong.

What it can't establish is anything about INBUXA's data: every run ended at the authentication check, since an empty store holds no such administrator.

What was recorded, 2026-09-19

record-compat.py ran against the live Enterprise server as a server-level administrator and saw 8 accounts, which is what the dashboard reports, so it reached all of them. It recorded:

File	Contents
expected.json	1 tenant, with its quotas and members. tenantAdmins empty: no --tenant-admin was passed
masks.json	nothing
archived.json	nothing

The two empty files are right, not a short recording: INBUXA has no masked addresses and deleted-mail retention is off (John, 2026-09-19). So masked_email_compat and undelete_compat iterate over an empty list. They pass without comparing anything, and a green run from either proves nothing about compatibility — the same standing as scim_compat and per_domain_directory_compat, which assert INBUXA uses neither feature.

That leaves one recording that carries weight, expected.json, and it is made. Should either feature be switched on before the cutover, record again: the files are a picture of the day they were taken.

The first run, 2026-09-19

All eight ran against a copy of INBUXA's RocksDB store, taken from the stopped server, with run-compat.sh and [email protected] as the administrator. All eight pass. SPEC.md §7's cutover steps 2 and 3 are met: INBUXA's data opens in the fork and reads back as it did.

What each one actually proved, which is not the same as eight green lines:

Test	What the pass means
tenant_compat	The tenant, its quotas and its members read back unchanged. tenantAdmins was empty, so what each tenant administrator can see is still unchecked
branding_compat	Every domain's logo answered, and the stored templates read back
ai_compat	The twelve LLM_* tags are there with the scores observed: real, not vacuous
monitoring_compat	Retention and stores read back; old history in the stripped encoding was skipped rather than erroring, and went after one purge
scim_compat, per_domain_directory_compat	Confirm INBUXA still uses neither feature
masked_email_compat, undelete_compat	Nothing. No masked addresses, retention off: they iterate an empty list

So six of the eight carry weight today, and one of those six is only half-checked until a tenant administrator's view is recorded (--tenant-admin, "Recording the three files").

Three things had to be fixed before any of this ran, each of which failed every test identically and none of which was about the data: the copy's listener names, its privileged ports, and its pending tasks. They are described below, because the next import's copy will bring the same three.

What a failure means

• tenant_compat, branding_compat, ai_compat: the fork reads that data differently from the Enterprise server. Treat as a cutover blocker and fix before moving.
• masked_email_compat and undelete_compat would mean the same, but as of 2026-09-19 they have nothing to read: see "What was recorded" above. They can only fail once INBUXA has masked addresses or retention on.
• monitoring_compat: old telemetry that can't be decoded is expected and is skipped; a failure here means the settings differ from what was observed.
• scim_compat and per_domain_directory_compat: they assert what was observed on 2026-09-18, that INBUXA uses neither feature. A failure means it has started to, and that feature's cutover notes then apply.