← Team guide

Team — technical notes for developers

Team mode makes promises: a station cannot read another station's mail, a Complete by the wrong role is refused on every device, and so on. This page shows how each promise is checked, how to run the checks yourself, and what is still a stated limit. It is for developers and reviewers; people using team mode only need the Team guide.

What is checked

Each promise is a term. A term is ENFORCED only when a test (a witness) passes and every one of its broken controls is found in the test's output. A broken control is the same test aimed at a deliberately broken case, so it shows the test can fail. A term that is stated but not tested is OPEN and is never shown as met. A test that judged nothing prints INCONCLUSIVE, never PASS.

Current record: 13 enforced, 0 open (run of 2026-10-31). It is published as Project quality objectives (tested properties and stated limits, not a warranty; see GOVERNANCE.md) and as the Terms button in the Team panel. The raw record is team_terms.json (schema terms-v1).

The checker can say no. Removing one broken control from a test's output turns that term UNCONTROLLED and the whole run FAIL; this was tried for the newest term (sealing). Many tests also run mutants: the product code is edited on purpose (one exact line, which must be found exactly once), and the test must go red. A mutant that crashes the test does not count as caught.

Run the checks yourself

The checks run in Node on your own machine. Two public repositories are needed: BIMCompiler (the terms runner and the comm-engine tests) and bim-ootb (this app, its browser tests).

git clone https://github.com/red1oon/BIMCompiler.git
git clone https://github.com/red1oon/bim-ootb.git
cd BIMCompiler && npm install
node scripts/dev_env_fetch.js --root-bim-ootb ../bim-ootb   # files git does not carry, from public storage, hash-checked
cd ../bim-ootb/tests && npm install                    # the bim-ootb tests need it (sql.js), with or without the browser layer
npx playwright install chromium                          # only for the browser layer (the real page in headless Chromium)
cd ../../BIMCompiler
node scripts/witness_terms.js --ootb ../bim-ootb

The last line it prints is the verdict, for example §TERMS_VERDICT PASS enforced=13 open=0 witness_failed=0 uncontrolled=0 browser=judged 5/skipped 0. Every test's log is written under build/scriptor/terms_run/.

The test cache

A full run takes minutes, and most of it repeats tests whose inputs have not changed. The runner therefore keeps each passing test's result together with a fingerprint of every file the test actually read. The files are recorded while the test runs, not taken from a hand-written list. If none of those files changed, the stored result is replayed, marked §CACHED with its fingerprint; nothing runs.

• What counts as an input: files loaded with require, files read by name, files the test serves to headless Chromium through its own small web server, folders it lists, files it checks for (a file that was missing and now exists counts as a change), and files read by any Node program the test starts. The arguments and the settings the runner gives the test count too.
• Never stored: a failing run; a run in which nothing inside the two repositories was read; a run whose Node code contains import( (Node loads those modules without going through the recorded file calls); and a run that starts any program other than Node (git, a database client, a shell), because that program's reads cannot be recorded. Playwright's own browser is the exception: it reads only what the test's recorded server sends it. These always run again and say why (§CACHE_SKIP).
• Databases opened by native code count too. A database opened through better-sqlite3 is read by native code, not by Node's file calls; it is recorded separately, so a changed database re-runs the test. This was missing at first: the check for files git does not carry exposed it, before a stale result was ever published (2026-11-01).
• Not part of the fingerprint: the network, the clock, and the Playwright/Chromium version. Use --fresh 1 when one of those changed.
• A change to the cache code itself invalidates every stored result.
• Measured (2026-10-31): the terms runner without the browser layer took 269 s, and 6 s when run again unchanged, with the same 13 results (one test re-ran because of the import( rule). One browser test (the Publish screen) read 348 files and went from 158 s to 0 s with the same result.
• The cache lives in ~/.cache/bim-witness/; deleting it is always safe.

How team data moves

• The relay is a shared folder of files (on GitHub, or a plain folder in the tests). It runs no logic and is never asked a question in real time. Each device keeps its own full copy and sends small bundles of signed changes.
• Encryption: business changes are encrypted with AES-GCM under a team key; a device gets that key wrapped for it alone (ECDH + HKDF). Identity records (who is in the team, roles) are signed but not encrypted.
• Mailboxes (POS teams founded since 2026-10-31): a till's sales go to head office's inbox and a message for one person goes to that person's box, so a device downloads only its own mail. The first download of a station stayed at about 384–399 bytes whether the team had 10, 100 or 1,000 stations (it was 367 KB, 4.5 MB and 45.8 MB).
• Sealing between a station and head office: in those teams, mail between one station (or person) and head office is sealed with a key only that pair holds. Another member of the team who holds the team key, even running a modified app that downloads everything, opens none of it; with the team key alone the same member opens all of it. A key minted by another member for someone else's pair is never used to seal. A device removed from the team gets none of the new keys.
• Nothing withheld goes unnoticed: every message in a mailbox carries a signed running number, and each device's signed summary says how far it has sent. If the relay holds back a bundle, in the middle or the last one, the receiver reports the gap.
• Checked on the real GitHub relay too: the same isolation test was run against a private GitHub repository, not only a folder. A member running a modified app downloaded 6 of another station's sealed messages and opened none (a control with the sealing switched off opened all 3 it tried); a withheld middle bundle and a withheld last bundle were both reported as gaps. 9 of 9 checks passed.
• Older teams are unchanged: office teams and teams founded before mailboxes existed keep the shared stream and the single team key, byte for byte as before.

Stated limits: the relay still sees who sent how much and when (sender, box, counts, sizes); someone who holds a pair key can pass it on outside the system; an older app in a new POS team does not read mailboxes and silently misses that mail (the version floor is the lever); the first-ever download of a new device still contains the whole member list; in a mailbox team a checkpoint (a compacted history) carries no state at all, so a light client that would have adopted a checkpoint reads the history instead, which costs it more to download.

Where the specifications are

Design, test specifications and results, each with its log: TEAMWORK_FRAMEWORK.md in BIMCompiler — §48 the terms and their wording, §45.10 mailboxes, §45.11 sealing and the per-mailbox number, §51 the cost of keeping the checks honest and the cache. The tests themselves: scripts/witness_terms.js, scripts/witness_witness_cache.js (BIMCompiler); common/tests/witness_f1_mailbox.js, common/tests/witness_read_scope.js, erp/tests/witness_team_*.js (bim-ootb).