Introduction

What a Kit is

A Kit is a focused piece of SlashBuilder’s platform that owns one job and says plainly what it will not do. The App Context Kit owns an app’s identity, its folders for files and settings, test and scratch modes, and a presence entry other apps can read. The Venue (a resource broker) owns machine time on a shared computer. A storage Kit owns where bytes live; an identity Kit owns who is allowed to do what. Each Kit lives in its own repository with its own tests and documentation, and an app is built by composing the ones it needs.

What this repository is

This repository is the book, not a Kit. It is the starting point for using the Kits: it holds this documentation, a set of demo apps that compose Kits, and a Makefile that prepares your computer, runs every test and builds the apps. It never appears in the Kit registry or the catalog, and nothing depends on it.

The Kits themselves are not copied in. make setup downloads each one, at the commit named in kits.lock, into a folder called .kits/. That keeps the Kits’ own repositories as the single place their code changes, and it keeps this book honest: the demos build against exactly the versions the book describes.

How to use this book

• Read Start here first. It takes you from an empty folder to a running app in four commands.
• Then read the guides in 20-guides/. The demo apps guide shows the Kits composed into real apps, with measurements of what each Kit saved. The guide on fitting the App Context Kit to other Kits shows where its design meets its neighbours.
• Reference pages live in 90-reference/: every make target and a glossary.
• The Kit catalog lives in 30-kits/: a status card for every Kit in the registry, including the ones that are not public yet. See Kits. A Kit’s own reference pages are pulled into the book from the Kit, so you never need its repository to read them; today that is the App Context Kit’s reference, and the others are still to come.

What is written and what is not

How much to trust it

Every number in the guides says what it was measured on. A claim that was reasoned but not tested says so. Where something is not known, the page says that instead of guessing. If you find a page that does not do this, that is a bug; see CONTRIBUTING.

Start here

From an empty folder to a running app. You need make (it comes with the Xcode command line tools on macOS and with build-essential on Debian and Ubuntu) and a way to get this repository onto your computer: either git clone, or the “Download ZIP” button on GitHub. After that, no git is needed: the Kits are downloaded as plain archives.

1. Check your computer

make doctor

This prints a table of the tools the demos need (Flutter and Dart, Rust, a C toolchain, and a few optional ones such as Docker), what it found, and the exact install command for your system where something is missing. It installs nothing, and it fails only when a required tool is missing. Run the commands it prints yourself, then run make doctor again until the last line says everything required is installed.

If you would rather have the tool run the install commands for the required tools, SETUP_INSTALL=1 make setup prints them and asks “y/N” before running anything.

2. Fetch the Kits and the packages

make setup

This runs the doctor, downloads each Kit listed in kits.lock into .kits/ at its pinned commit (printing one line per Kit: fetched, up to date, or skipped and why), then fetches the Dart, Flutter and Rust packages every project needs. It is safe to run again.

While some Kits are private, fetch them too. This needs a GitHub login: install the GitHub CLI and run gh auth login, or set a GITHUB_TOKEN environment variable that can read the repositories.

make setup KITS=all

Without a login, private Kits are skipped with a one-line explanation. A demo app that needs a Kit that was skipped is skipped too, with a line that says which (for example skipped apps/notes_rust: needs storage-kit (private; fetch with KITS=all)); everything else still sets up and tests. The demo apps all need the App Context Kit, so while that is private they cannot be built or tested without a login.

3. Run the tests

make test-fast

This runs every fetched Kit’s own tests, the components in labs/, and the tests of all seven demo apps (the Rust core of notes_rust is tested with cargo test), then prints a table: suite, passed, failed, skipped and seconds. It finishes with OK or FAILED. make test additionally runs the suites that need Docker, Redis or a running daemon, and skips them with a message when the tool is absent.

4. Build and run an app

make app APP=calculator    # a debug build for this computer
make run APP=calculator    # run it (tried on macOS; on Linux the apps build and launch headless in a container, a real desktop has not been tried)
make apps                  # build all seven

The apps are Flutter desktop apps. On macOS this needs the full Xcode app, not only the command line tools; on Linux it needs a few packages (make doctor lists them); the demo apps guide says what the Linux test did and did not show. Windows is not covered.

To see two copies of an app find each other, follow run two copies and watch them find each other.

When something goes wrong

Where to go next

Read the demo apps guide to see what each app asks of the Kits, then the make targets for everything else the Makefile can do.

Demo apps

Seven small Flutter desktop apps in apps/ that use the App Context Kit (the resource broker the Kit talks to is Venue). They were written to measure the Kit: what it removes from an app, what it still leaves for the app to write, and where it falls short.

One rule shaped them: an app does not edit the Kit. If an app needs something the Kit lacks, it writes it under lib/kit_gaps/ with a // KIT GAP: comment. The line count of those directories is the measurement of what the Kit is missing. When the Kit absorbs a gap, the app deletes its copy.

How the numbers were taken for the first six apps, on 2026-10-24 with Flutter 3.41.9 and Dart 3.11.5 on macOS (Apple silicon): tests are the result of flutter test in each app directory; main.dart and gap lines are wc -l (raw lines, comments and blanks included) of lib/main.dart and lib/kit_gaps/*.dart; coordination lines are wc -l of lib/coordination/*.dart. The five skipped render-queue tests need a running resource-broker daemon and skip themselves when no token is set. The venue entry in kits is a label: only peers is checked against the kits list today (see the App Context Kit’s architecture guide, section 1).

Contents: running and testing any app · the seven apps · how much code the Kit saved · run two copies and watch them find each other

Running and testing any app

Each app is a standard Flutter project. Desktop runners exist for macOS and Linux; the apps were run on macOS, and on Linux they were built and launched headless in a container (see Linux smoke test). Every command below assumes you are in the repository root, and that you have run make setup once (add KITS=all while the App Context Kit is private) so the Kits the apps depend on are in .kits/.

The Makefile wraps the common cases: make test-fast runs every app’s tests, make app APP=stopwatch builds one app for this computer and make run APP=stopwatch runs it. The plain Flutter commands work too:

cd apps/stopwatch        # or any app
flutter pub get
flutter run -d macos     # run it
flutter test             # run its tests

An app reads its settings from environment variables before it opens. These are the ones that matter. PREFIX is the app’s envPrefix, or the last segment of its id, upper-cased: CALC, MINES, NOTEPAD, STOPWATCH, RENDER_QUEUE, LAUNCHER.

Details are in the App Context Kit’s specification (spec/APP-CONTEXT.md in that Kit), sections 2 and 6.3.

flutter run -d macos starts the app as a child of the Flutter tool, which passes your shell’s variables on (this is from reading the tool’s source; no window was opened for this page). An app started from Finder or the Dock does not see your shell’s variables.

The macOS sandbox rule. Three apps have the macOS App Sandbox on: calculator, minesweeper and notepad. The other three (launcher, render-queue, stopwatch) have it off. A sandboxed app can only write inside its own container, ~/Library/Containers/<bundle id>/Data/, and that container also has its own HOME and TMPDIR. Two things follow:

• A path outside the container, such as /tmp/..., in APP_CONTEXT_SCRATCH or APP_CONTEXT_PEERS_DIR does not work for a sandboxed app. With APP_CONTEXT_SCRATCH the app cannot create its directories: the companion shows its startup error screen (the calculator’s first version, before the companion package, crashed with an unhandled PathAccessException). With APP_CONTEXT_PEERS_DIR the process stays up and works alone, and the footer says “Peers: off (peers unavailable: …)” (asserted in a widget test, not seen). Use a path under the container instead, for example ~/Library/Containers/com.slashbuilder.demo.notepad/Data/tmp/ak-scratch. The bundle ids are com.slashbuilder.demo.calc, com.slashbuilder.demo.minesweeper and com.slashbuilder.demo.notepad.
• The default roster and peers directories are inside the container too. Two copies of one sandboxed app share the container and find each other with no variables set. Two different sandboxed apps have different containers, so they are not expected to share a roster (reasoned, not tested).

The sandboxed apps that use peers, notepad and minesweeper, also need the com.apple.security.network.client and com.apple.security.network.server entitlements; both projects have them in Debug and Release. With only the server entitlement, two copies listen but never connect, and nothing is logged. That observation was recorded in the apps’ development notes (not published) and was not repeated for this page.

Everything about the sandbox is macOS-specific, and the entitlement files are native build files that a running Dart app cannot change. The App Context Kit’s platforms guide has the full table of what each capability needs.

Linux smoke test

make linux-smoke-image and then make linux-smoke build every app with flutter build linux --release in an Ubuntu 24.04 container (Flutter 3.41.9, the same version as the macOS runs, and Rust 1.98.1 for notes_rust) and launch each one under a virtual display (Xvfb, 1280x800x24). Run on 2026-10-24, all seven apps built and started; the table is the summary (the full output, every warning line and the screenshots are what the command writes to build/linux-smoke/; the target is described in make targets).

What this is not. It is headless, under a virtual display, in a container, on linux/arm64 only (Docker on Apple silicon). There was no window manager and no compositor, no real GPU (software OpenGL), no click on a window’s close button (only SIGTERM), no notification daemon (the stopwatch’s desktop notification was not exercised), and no other distribution, Wayland or x86_64. It is independent evidence that the Linux runners build and the apps start, draw, take input and keep their state; it does not replace a session on a real Linux desktop.

One thing it found outside the apps: with a clean ~/.cargo, notes_rust does not build, because the Storage Kit’s manifest names a private cargo registry that only the Kit’s own .cargo/config.toml defines, and cargo reads that file only when run inside the Kit. The smoke test copies it into the container’s cargo configuration, as the Kit’s own README says to; the fix belongs in the Kit (for example by not naming the registry in a dev-dependency).

calculator

Folder: apps/calculator.

Exercises. The least an app can ask of the Kit. A four-function calculator with no stored state, written to find the minimum useful adoption.

Run and test.

cd apps/calculator
CALC_MODE=mock flutter run -d macos    # shows a "mock" chip in the app bar
flutter test                           # 32 tests

What the Kit gave it. AppContextKit.run loads app.json from the asset bundle and closes the app once on window close, quit, SIGINT or SIGTERM. AppContextScope supplies the app name for the title. ModeBadge shows the mock and scratch chip. pumpKitApp in the tests runs the app in mock mode under a scratch directory. The Kit also writes a roster entry that nothing in this app reads.

What it still writes itself. Nothing: lib/kit_gaps/ does not exist. The whole of main.dart is:

import 'package:app_context_kit_flutter/app_context_kit_flutter.dart';

import 'ui/calculator_app.dart';

Future<void> main() => AppContextKit.run(manifestAsset: 'app.json', app: (_) => const CalculatorApp());

Did it need the Kit? No. It is the floor: the Kit is nearly free here, and what it gives back is the app name, test isolation and a roster entry nobody reads.

minesweeper

Folder: apps/minesweeper.

Exercises. A game saved to disk (the game in progress, high scores, two settings), and, through the peer layer, handing a game to another copy or playing one board together. It is the case where a state change has to happen on two sides.

Run and test.

cd apps/minesweeper
flutter run -d macos
flutter test                           # 86 tests

This app is sandboxed. To run two copies that find each other, see the walkthrough and use paths under the container. To exercise the handoff without a window, run the probe (below).

What the Kit gave it. The data directory and AppJsonFile for the saved game and scores, SessionSettings for the two settings, ctx.startPeers to find and connect to other copies, PeerJson for the message bodies, PeersIndicator for “This copy / Peers: N”, NotesBanner and ModeBadge.

What it still writes itself. No gap files. lib/coordination/ (329 lines) is the game protocol: the offer, the person’s yes or no, the pull of the board, the confirmation, and the checks that refuse anything inconsistent. That is the app’s meaning and stays the app’s.

A probe, not a window. tool/peer_probe.dart runs the app’s own coordination code without a window, over the real loopback provider. Two probes on one machine, one offering a game and one accepting:

cd apps/minesweeper
dart run tool/peer_probe.dart --scratch /tmp/ak-ms/laptop  --peers /tmp/ak-ms/peers --device laptop  --for 9 --accept &
sleep 3
dart run tool/peer_probe.dart --scratch /tmp/ak-ms/desktop --peers /tmp/ak-ms/peers --device desktop --for 6 --game --offer 1:handoff

A run of exactly this on 2026-10-24 printed, trimmed to the lines about the handoff (the first number is epoch milliseconds):

laptop:   1792851222914 HOOK message="desktop #c694 wants to send you a game." incoming=1 sharing=null
laptop:   1792851222924 ADOPT status=playing sum=649a874f5e98919e
laptop:   1792851222925 ACCEPTED -> Took over the game from desktop #c694.
desktop:  1792851221880 GAME in progress sum=649a874f5e98919e
desktop:  1792851222907 COMMAND offer handoff
desktop:  1792851222925 RELEASE to laptop #f142

The offer arrived 7 ms after it was sent, the board was applied 10 ms later and the sender released its game when the receiver confirmed. Both boards have the same checksum. This is two probes, not two windows, so it shows the protocol and not what a person sees.

Did it need the Kit? For handing a game to another copy it needs a way to find and reach that copy, and the Kit supplies it; the protocol that makes a handoff safe, and what happens when a message is lost, is the app’s 329 lines.

notepad

Folder: apps/notepad.

Exercises. One JSON file per note in the data directory, autosave 600 ms after the last keystroke, damaged-file handling, and the close hook that flushes unsaved typing on quit. With peers: syncing notes between copies, including conflicts and notes too large for one message. It is the heaviest user of the hook.

Run and test.

cd apps/notepad
flutter run -d macos
flutter test                           # 63 tests

This app is sandboxed; see the sandbox rule above. Two copies need different APP_CONTEXT_DEVICE values: notepad refuses a peer with its own device id, because two copies with one device id share one notes folder and are one replica.

What the Kit gave it. The data directory, ctx.dataJson('sync.json') and AppJsonFile for atomic JSON files, SessionSettings, ctx.onClose to save the last keystrokes, ctx.startPeers, PeerJson, PeersIndicator, NotesBanner, ModeBadge.

What it still writes itself. One gap file: lib/kit_gaps/blob_pull.dart (79 lines), a chunked transfer for notes larger than one message, pulled part by part over request and reply. It stays because only one app wants it. lib/coordination/ (619 lines) is the sync engine: version vectors, conflict copies, the digest exchange. The hook itself, note_sync_hook.dart, is 29 lines.

A probe, not a window. Two probes over the real loopback provider; the second creates a 300-character note after the first is ready:

cd apps/notepad
dart run tool/peer_probe.dart --scratch /tmp/ak-np/laptop  --peers /tmp/ak-np/peers --device laptop  --for 10 &
sleep 3
dart run tool/peer_probe.dart --scratch /tmp/ak-np/desktop --peers /tmp/ak-np/peers --device desktop --for 7 --create 1:Shopping:300

A run on 2026-10-24 (trimmed):

desktop: 1792851200930 COMMAND created hniggyzhs0ggau "Shopping" body=300
laptop:  1792851200960 NOTE hniggyzhs0ggau "Shopping" body=300 chars

The note was a file in the other copy’s notes folder 30 ms after it was created. Afterwards find /tmp/ak-np -name '*.json' lists the same note file under both scratch directories, plus each side’s sync.json. A person typing would add the 600 ms autosave pause to that number; that was not measured.

Did it need the Kit? The Kit supplied find, connect and route; replicated notes still cost about 620 lines of the app’s own code (versions, conflicts, chunked transfer) that the Kit does not provide.

stopwatch

Folder: apps/stopwatch.

Exercises. A stopwatch with laps and a countdown. Its state is a point in time plus banked time, saved on every change, so it tests the state directory, settings, and a clean quit and relaunch. With peers: one countdown shared between copies, and a “timer finished” signal announced by one copy.

Run and test.

cd apps/stopwatch
flutter run -d macos
flutter test                           # 49 tests

This app is not sandboxed, so /tmp paths work.

What the Kit gave it. The state directory and settings file, ctx.onClose to save, the exit path, test isolation (the “start, lap, relaunch” test is two opens on one scratch directory), ctx.startPeers, PeerJson, PeersIndicator, NotesBanner, ModeBadge.

What it still writes itself. One gap file: lib/kit_gaps/notifier.dart (35 lines), which shows a desktop notification through osascript or notify-send. It is not something the App Context Kit should own. lib/coordination/ (332 lines) is the shared-countdown rule.

Did it need the Kit? It needed the state directory, settings, the exit path and, for coordination, discovery and routing; it never needed the resource broker.

render-queue

Folder: apps/render-queue.

Exercises. A session with a resource broker. Each job takes a hold (ctx.venue.withHoldWaiting), runs, and releases it. It tests what the app does when the broker refuses, waits for capacity, or loses the app (a killed app keeps its hold until the lease runs out).

Run and test.

cd apps/render-queue
RENDER_QUEUE_MODE=mock flutter run -d macos   # an in-memory broker that grants 2 holds at once
flutter run -d macos                          # real mode
flutter test                                  # 38 passed, 5 skipped

In real mode, with no broker token configured, the session is a local one with no limit, and the app says so. Connecting to a real broker daemon needs a token and the daemon’s address; the variables are in the App Context Kit’s specification (spec/APP-CONTEXT.md in that Kit), section 3. The daemon is not part of this repository, which is why the real-daemon tests skip. The app’s behaviour when refused is a setting in config.json: policy (wait or failFast), maxWaitSeconds, retrySeconds and leaseSeconds.

What the Kit gave it. The session that hides fake, local and real, withHoldWaiting (retry a refusal for up to maxWait, with cancel), typed refusals, the settings file, ctx.onClose to cancel running jobs and wait for their holds to be released before the session closes, and the roster scan it uses to tell whether another copy of the app is running.

What it still writes itself. No gap files. The app keeps the policy (wait or fail fast) and the words the person reads.

Did it need the Kit? Yes, and this is the clearest case: the one thing it needed from the broker session that the Kit lacked, waiting for capacity, is now in the Kit.

launcher

Folder: apps/launcher.

Exercises. The roster. The launcher lists the apps that are running on this machine, which tests whether a file-based presence list is enough.

Run and test.

cd apps/launcher
LAUNCHER_APPS_DIR="$PWD/.." flutter run -d macos   # also lists the manifests found in apps/*/app.json
flutter test                                       # 24 tests

The launcher is not sandboxed. It sees an app only if that app writes its presence file to the same roster directory. The three sandboxed apps write inside their own containers, so to see apps in the launcher run the unsandboxed ones (stopwatch, render-queue) with the same APP_CONTEXT_ROSTER_DIR as the launcher.

A probe, not a window. tool/rows_probe.dart prints the rows the launcher would show for a roster directory. A hand-made roster directory with one live entry and one damaged file:

mkdir -p /tmp/ak-roster
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "{\"id\":\"com.slashbuilder.demo.stopwatch\",\"instance\":\"a0000001\",\"name\":\"Stopwatch\",\"version\":\"0.1.0\",\"pid\":$$,\"startedAt\":\"$NOW\",\"heartbeatAt\":\"$NOW\"}" > /tmp/ak-roster/com.slashbuilder.demo.stopwatch@a0000001.json
echo '{broken' > /tmp/ak-roster/junk.json
cd apps/launcher && dart run tool/rows_probe.dart /tmp/ak-roster

It printed, on 2026-10-24 (the pid is your shell’s):

running  Stopwatch  com.slashbuilder.demo.stopwatch copy=a0000001 pid=70742 
unreadable: junk.json

A file whose last heartbeat is more than 15 seconds old shows as stale, and a file the launcher cannot parse is listed as unreadable instead of being hidden.

What the Kit gave it. Roster.scan() and RosterRecord (status live, stale or unreadable), the instance id in the file name so two copies of one app are two rows, ctx.venue.nodes() for the node strip, settings, and scratch isolation for the tests.

What it still writes itself. Two gap files, 50 lines: manifest_scan.dart (36), which walks a folder for */app.json because nothing lists installed apps, and pid_alive.dart (14), which asks the operating system whether a pid is alive (kill -0), because scan() reports live for up to 15 seconds after a crash. Each has one user. A pid check does not work inside the macOS sandbox, and a reused pid reads as alive.

Did it need the Kit? For the roster, yes: Roster.scan() and instance ids replaced a 70-line shim (roster_scan.dart) and fixed two copies erasing each other’s entry; the pid check, the app index and the memory of “gone” are still the launcher’s own, and they are most of what makes it a launcher.

notes_rust

Folder: apps/notes_rust. The only demo app with a Rust core, and the only one that uses a Kit written in Rust.

Exercises. The intended shape of an app: a Flutter interface over a Rust core, joined by flutter_rust_bridge. The core (notes_core) stores notes as content-addressed blocks on the Storage Kit and works inside the App Context Kit context that the Flutter side opened. The question it answers is how two halves share one context. The Dart side opens the context once and hands the Rust side a snapshot of it; the Rust side adopts it (an adopt API added to the App Context Kit for this) and so announces nothing, writes no settings, and creates files only under data and state. Notes have a version history (restoring a version writes one small manifest and copies no body). Two copies sync over the App Context Kit’s peer layer: Dart carries the bytes, Rust holds the blocks, checks every hash before storing anything, and reports conflicts with both versions.

Run and test.

make app APP=notes_rust               # needs make setup KITS=all, flutter_rust_bridge_codegen 2.12.0 and, on macOS, CocoaPods
make run APP=notes_rust
make test-fast                        # cargo test (29) and flutter test (19, in-memory stand-in for the core)
make test-integration                 # flutter test integration_test -d macos (10, the real library inside the app)
sh apps/notes_rust/tool/smoke.sh      # launch the built macOS app for 10 s, check what it wrote, SIGTERM it

What the Kits gave it. From the App Context Kit: the directories and instance id (shared with Rust through the snapshot), AppContextKit.run, the config file the Dart side owns and the Rust side only reads, ctx.startPeers and the peer hub. From the Storage Kit: PartitionStore, per-partition de-duplication, hash-verified reads and the fragment trees.

What it still writes itself. lib/kit_gaps/blob_pull.dart (81 lines, copied from the notepad) for moves bigger than one message; in Rust, the head index (the Storage Kit has no mutable store implementation), a verified insert (its put files tampered bytes under their own hash), the child list of a list node, and the flush of the pack before a head moves. lib/coordination/ is 416 lines of Dart; the Rust core is about 1,800 lines (plus 5,130 generated bridge lines).

What it showed. See the app’s README for the measurements, what the bridge made awkward and how the shared context behaved in practice.

Did it need the Kits? The Storage Kit supplied what a notes store is made of; the App Context Kit’s adopt API is what made one app with two runtimes possible without announcing twice. Neither supplied the sync protocol, the conflict policy or the head index.

What the demo apps do not cover

• One Rust core, not a family. Only notes_rust has a Rust crate and a flutter_rust_bridge dependency; the other six are Flutter on a Dart core. It was built and run on macOS; on Linux it was built and launched headless in a container (see Linux smoke test), not on a real desktop. The bridge was not tried with a Rust-to-Dart stream, hot reload, or a second Rust core in the same app.
• Two Kits used from Rust, the rest not. notes_rust uses the App Context Kit’s Rust crate and the Storage Kit. Identity, messaging and transport Kits were probed in separate Rust packages in a private repository (the public-safe summary is Fitting the App Context Kit to other Kits), and the other apps’ own sync, conflict handling and large-note transfer are written in Dart. Even in notes_rust the transport is Dart: the peer layer has no Rust half.
• notes_rust needs a private Kit. The Storage Kit is not public yet, so the app cannot be built from a public clone alone: it needs make setup KITS=all and a GitHub login with access. Without it, make setup, make test and make apps skip the app with one line (skipped apps/notes_rust: needs storage-kit (private; fetch with KITS=all)) and carry on with the other six; the Kit it needs is named in its kits.need file. The App Context Kit’s Rust crate, which the app also uses, is part of the pinned release candidate.
• No real network. Peers find each other through announcement files and loopback sockets on one machine. That holds for notes_rust too: nothing in it was run on a second machine.

How much code the Kit saved

The measurement is the size of lib/kit_gaps/ across the six apps (raw wc -l), and the length of each main.dart.

These were counted from the App Context Kit repository’s history on 2026-10-24: the first column at the Kit’s first round, the next three at the commits that migrated the apps, added coordination, and moved the repeated parts into the Kit. The “now” column matches the apps in this repository.

What the numbers say. Migrating to the Kit removed about 400 lines of shims. Then adding coordination added about 450 new ones, taking the total to 777, higher than before the Kit. For a while the Kit had made main.dart tiny and the apps’ total gap code worse. Moving the repeated parts into the Kit (ctx.startPeers, PeerJson, PeersIndicator, AppJsonFile, SessionSettings, VenueSession.withHoldWaiting) brought the total to 164, 77% below the start and 79% below the peak. Calculator, minesweeper and render-queue have no gap code left. What remains is four helpers that one app each uses: notifier, blob_pull, manifest_scan, pid_alive.

The lesson: build a Kit piece when the second app copies it, not before. Each piece that moved into the Kit had been written independently by several apps and was identical across them: the exit handling in all six, the JSON file store and settings wrapper in two, and the three peers helpers in three. The four that stayed out have one user each. One exception to be honest about: the wait-for-capacity loop (withHoldWaiting) had one app writing it, and moved because the resource-broker session was incomplete without it. These counts measure how much the Kit absorbed, not how long the work took. Lines are a proxy.

Run two copies and watch them find each other

This uses the stopwatch because it is not sandboxed, so /tmp works. The first part is a probe: no window, but the app’s real coordination code over real loopback TCP and a real announcement directory. The second part opens windows and was not run for this page.

Part 1: two probes (run on 2026-10-24)

In one terminal:

cd apps/stopwatch
flutter pub get
dart run tool/peer_probe.dart --scratch /tmp/ak-demo/laptop --peers /tmp/ak-demo/peers --device laptop --for 12

Within a few seconds, in a second terminal:

cd apps/stopwatch
dart run tool/peer_probe.dart --scratch /tmp/ak-demo/desktop --peers /tmp/ak-demo/peers --device desktop --for 10 --start-after-ready 1

What the variables are: --scratch is APP_CONTEXT_SCRATCH (this copy’s own data, config and state), --peers is APP_CONTEXT_PEERS_DIR (shared by both copies), --device is APP_CONTEXT_DEVICE. Each probe prints a line per event, starting with the epoch milliseconds. After the second probe is ready it plays the person on the second copy: it resets the countdown to 6 seconds and starts it. This is what the two probes printed, with the once-a-second TICK lines and a few STATE lines removed:

desktop: 1792850582509 START desktop@efe50421 stamp=0
desktop: 1792850582511 PEER found laptop@a8def94c hello=null
desktop: 1792850582524 PEER ready laptop@a8def94c hello=null
desktop: 1792850583526 COMMAND reset 6s + start (this is the person on the probe copy)
desktop: 1792850583532 STATE duration=6000 running=true remaining=5999 phase=running stamp=2/desktop@efe50421
desktop: 1792850589539 NOTIFY Timer finished: 00:06 countdown is done

laptop:  1792850582523 PEER found desktop@efe50421 hello=null
laptop:  1792850582524 PEER ready desktop@efe50421 hello=null
laptop:  1792850583538 STATE duration=6000 running=true remaining=5998 phase=running stamp=2/desktop@efe50421
laptop:  1792850589540 NOTIFY Timer finished: 00:06 countdown finished on desktop #efe5

Read it like this. The desktop probe started and saw the laptop as found 2 ms later and ready 15 ms after it started. The countdown the desktop started was running on the laptop 12 ms after the desktop’s command. When it ended, the desktop, as the writer of the current state, announced; the laptop said where it finished. While both ran, ls /tmp/ak-demo/peers/local/com.slashbuilder.demo.stopwatch/ showed one announcement file for each copy, named DEVICE@INSTANCE.json: the directory is <peers dir>/<account>/<app id>/, and the account is local because nothing set one.

See a crash

Start the two probes as above, but give the first --for 20, the second --for 30, and leave out --start-after-ready. Find its process id in its announcement file and kill it hard:

kill -9 "$(python3 -c "import json,glob; print(json.load(open(glob.glob('/tmp/ak-demo/peers/local/com.slashbuilder.demo.stopwatch/desktop@*.json')[0]))['pid'])")"

The surviving probe (the laptop) printed this on 2026-10-24, TICK lines removed:

1792851139352 PEER found desktop@9bb7531b hello=null
1792851139361 PEER ready desktop@9bb7531b hello=null
1792851143134 PEER lost desktop@9bb7531b hello=null
1792851143134 PEER found desktop@9bb7531b hello=null
1792851146452 PEER lost desktop@9bb7531b hello=null

One death is three events. The operating system closed the dead copy’s socket, so lost arrives at once. The dead copy’s announcement file was still there with a recent beat, so it was found again. About 3.3 seconds later the beat was old enough, the provider withdrew the candidate, and the final lost came. The dead copy’s file stays on disk until a live copy reaps it after 60 seconds. The numbers behind the rule are in the App Context Kit’s coordination guide, section 6 (providers).

Part 2: two windows (not run for this page)

Build once, then run the binary twice, rather than running flutter run twice from one directory.

cd apps/stopwatch
flutter build macos --debug
BIN="$PWD/build/macos/Build/Products/Debug/stopwatch.app/Contents/MacOS/stopwatch"
APP_CONTEXT_DEVICE=laptop  APP_CONTEXT_SCRATCH=/tmp/ak-demo/win-laptop  APP_CONTEXT_PEERS_DIR=/tmp/ak-demo/win-peers "$BIN" &
APP_CONTEXT_DEVICE=desktop APP_CONTEXT_SCRATCH=/tmp/ak-demo/win-desktop APP_CONTEXT_PEERS_DIR=/tmp/ak-demo/win-peers "$BIN" &

Each window’s footer should read “This copy: laptop #xxxx” and “Peers: 1” with one chip for the other copy. Start the countdown in one window and the other follows. Give each copy its own APP_CONTEXT_SCRATCH as well as its own APP_CONTEXT_DEVICE: copies that share a config directory share a generated device id. The peers directory is the one thing they share, which is why it is set with APP_CONTEXT_PEERS_DIR. If APP_CONTEXT_SCRATCH were the only variable, each copy would announce in <its scratch>/roster-peers and never see the other.

For the sandboxed apps (notepad, minesweeper), the same recipe works with every path under ~/Library/Containers/<bundle id>/Data/tmp/, for example APP_CONTEXT_SCRATCH=~/Library/Containers/com.slashbuilder.demo.notepad/Data/tmp/ak/laptop and APP_CONTEXT_PEERS_DIR=~/Library/Containers/com.slashbuilder.demo.notepad/Data/tmp/ak/peers, with the binary at build/macos/Build/Products/Debug/notepad.app/Contents/MacOS/notepad. A copy that cannot reach the peers directory keeps working alone and its footer says why. That route was recorded in the apps’ development notes (not published) and was not repeated for this page.

See also: the App Context Kit’s own getting-started, coordination, platforms and design-decisions guides, which ship with the Kit (after make setup they are under .kits/app-context-kit/docs/), and Fitting the App Context Kit to other Kits for how it meets its neighbours.

Fitting the App Context Kit to other Kits

The App Context Kit is the root namespace for one running app: identity, directories, settings, a session with a resource broker (Venue), and a way for copies of the same app to find each other. It is not the only Kit an app touches. During its first round of work, six neighbours were probed to find out where the App Context Kit’s design meets theirs.

This page records, for each one: the question, what was built, what it showed, what the App Context Kit does about it, and what is still open and with whom.

How to read the evidence:

• The probes run in a private repository; the public-safe summary is here. Each probe was a standalone Rust package that exercised a neighbouring Kit directly. You cannot rebuild them from this repository, and this page does not point at them. The numbers below were measured when the page was written.
• None of this is inside a demo app. No Flutter app calls the Rust App Context Kit crate or any of these Kits through a bridge, so “works in a probe” is not “works in an app”. See what the demo apps do not cover.
• The one piece that lives in this repository is labs/interface_candidates, the proposed shared UI components. Nothing in the Kit’s own packages depends on it.
• Numbers come from debug builds on one machine, usually single runs. Latencies are to show magnitude, not to rank anything.
• Where a page below says “tested”, it was tested while this page was written. Anything else is from the project’s own notes and says so.

Summary

Hearth (transport)

The question. Hearth is SlashBuilder’s messaging protocol, with a hub that fans messages out to devices on an account. Can the App Context Kit use it to carry traffic between copies of one app, using topics scoped to the app?

What was built. A prototype adapter, HearthTransport: join(account, app, device), then broadcast, send(device, bytes), recv, leave. It validates ids before anything reaches the wire. It came with 53 tests in eight files (topics, delivery, isolation, presence, request/reply, payload, catch-up, adapter), run against a real local hub and Redis on loopback ports, plus a patched copy of the hub whose topic module changed by about 60 lines. Nothing touched a production service.

Re-run when this page was written: 53 passed, 0 failed (with the 90-second idle-timeout test skipped).

What it showed.

• The stock hub rejects app-scoped topics. account/<id>/app/<app>/... gets TOPIC_INVALID on subscribe and publish. The hub’s topic grammar is a closed list of four shapes. The patch adds two. Until the protocol’s topic naming is amended, the adapter carries app traffic on the existing broadcast and device topics, marks each message payload_type = ak.app/<app>, and filters at the receiver.
• The usable payload is 64 KiB minus the Kit’s header. Re-run: a 65,536-byte payload was delivered intact; 65,537 bytes was refused with ENVELOPE_TOO_LARGE and the connection survived. The 1 MiB figure is the cap on the whole envelope; above it the hub closes the connection without an error.
• The hub does things the Kit must handle itself. It echoes a broadcast back to the sender. Its message id is not a safe correlation key: 1 of 40 replies was already buffered before the requester’s own publish receipt. Subscribing and then catching up can deliver the same message live and in the catch-up page, so de-duplicate on message id. A copy that goes silent with its socket open is noticed only after the hub’s 90-second idle timeout; a killed copy is reported offline in under a millisecond.
• Rate limits matter for liveness. On one connection, 10 of 25 rapid publishes were accepted (limit 10 per second). Hourly caps of 600 per connection and 6,000 per account were read in the hub’s code, not measured. By that arithmetic a heartbeat every 30 s uses 20% of one connection’s hourly cap, and every 5 s exceeds it.
• Ordering holds per sender only. 200 messages from one sender arrived 200 of 200, in order. Four concurrent senders kept their own order, but arrival order across senders disagreed with message-id order.
• Loopback latency is small. Publish to peer receipt: p50 about 1.4 ms, p95 about 2 ms (60 samples, debug build, one machine).
• Catch-up paging can skip messages. Paging by a millisecond timestamp with a strict comparison skips messages that share a millisecond across a page boundary. With five synchronized senders and one message per page, a run recovered 9 of 40 messages; an earlier run recovered 10 of 40. The count depends on timing.
• A retention field means two things. The hub reads field 5 of the publish message as a “do not retain” flag. The published schema and the client SDK call it a retention class. An explicit “history” class is silently not stored.

What the App Context Kit does because of it.

• The peer layer has a provider interface (discover, connect, send, inbound stream). The Kit ships a fake provider and a loopback provider. There is no Hearth provider yet.
• Payload limits differ by provider, so a provider has to declare its own maximum and send has to fail before the wire when it is exceeded. The App Context Kit’s specification says so (section 6.2). Not built: today the app passes the limit to PeerJson (for Hearth: 64 KiB minus the header).
• The Kit’s own envelope carries a Kit-owned correlation id and from.device plus from.instance, which is how echo is suppressed. What a Hearth provider must still add: request deadlines, de-duplication across live delivery and catch-up, a no_retain heartbeat no more often than every 30 s, and reconnect.

What is still open, and who owns it.

Message Kit

The question. The Kit’s coordination envelope is {account, app, channel, from, seq, kind} plus an opaque, app-owned payload. Can Message Kit carry it between processes on one machine, and across its remote-provider seam to another machine?

What was built. A mapping of the envelope inside a Message Kit frame (19 mapping tests), a small peer process for local exchange tests (6 tests), a TCP provider of under 200 lines through the remote seam (4 tests), and a test of an oversize message (1 test).

What it showed.

• The envelope fits without bending either side. The whole Kit message goes inside one Message Kit payload. One header works for Message Kit and for Hearth, with two mappings. They differ in who acknowledges a publish, whether a peer can send a directed message, size limits, rates, retention, and echo.

  	Message Kit, local	Hearth
  Largest message	about 200 KiB with default socket buffers (204,800 bytes sent; 212,992 failed)	64 KiB including the Kit header
  Round trip	p50 about 70 microseconds (1,000 requests, two processes, container, debug build)	about 2 ms, hub on loopback
  Echo to the sender	none	yes, suppress by from

• The local transport is Linux-only. It uses AF_UNIX with SOCK_SEQPACKET, which the macOS kernel does not implement. Checked here: creating such a socket on macOS fails with “Protocol not supported” (Errno 43). Windows is also out: the local bus code is compiled for Linux and Android only (read in Message Kit’s source; not run on Windows). So same-machine peers on macOS and Windows use the Kit’s loopback provider, which is plain TCP on 127.0.0.1.

• On macOS the integration tests pass without testing anything. Re-run on macOS: 19 mapping tests passed, and the 11 integration tests print SKIP ... local bus unavailable and report “passed”. Read the SKIP lines, not the totals. In a Linux container the same 30 tests ran with none skipped and all passed.

• What Message Kit cannot express today: an application answer inside a reply message; local fan-out to several receivers; a caller-chosen socket path; a configurable request timeout; and anything on macOS or iOS.

• The remote seam has gaps. Several were found and reported to the Kit’s maintainers.

What the App Context Kit does because of it.

• It ships the loopback provider for same-machine peers, so macOS and Windows do not wait on Message Kit.
• The envelope header needs additions, tracked in the specification: an in_reply_to correlation field, a to field for directed messages, a per-message retain hint, and a provider-declared maximum payload checked before the wire. The Dart core already has a request id (rid, kind kit.reply) for correlation.
• A Message Kit provider is not built.

What is still open, and who owns it.

Storage Kit

The question. Storage Kit is content-addressed storage. The App Context Kit names an app by (account, app id). Can that name also name the app’s slice of storage, and is syncing a note between two copies cheap when only a little of it changed?

What was built. A mapping from (account, app id) to a storage partition, so copies of one app on one account share a partition and different accounts never do; a notes model on that partition; and copy-to-copy sync. The “wire” was an in-process call, so this measured bytes and blocks, not network time. Conflict handling used manifest ancestry. The Kit never merges: the app’s resolver chooses between keep-local, take-remote, merged, or defer.

What it showed. Re-run when this page was written, 10 MiB pseudo-random body, two contexts, debug build:

The 3 blocks are one manifest, the rewritten list node (about 25 KiB), and the one chunk that changed. 541 blocks were already present. The list node is the floor for any edit to a large body.

Also tested: identical bodies under two names store one set of chunks; each of the 10 blocks of one version, corrupted in turn, was rejected and the old body still read back.

What the App Context Kit does because of it. Nothing yet in the Kit. The findings point at three changes to the Kit’s directory model, none made:

• Reserve names under data for the block store (a convention, not a sixth directory kind).
• Add an account dimension. The specification’s section 6 uses (account, app id) as the scope, but the Kit’s directories are per operating-system user, not per account.
• Quotas cannot be enforced until Storage Kit can delete.

Gaps in Storage Kit (for its maintainers): no insert that verifies a hash before filing the bytes, so a receiver must hash first; no way to list a list node’s children from a half-synced tree; no mutable head; no delete, garbage collection or quota; compression hides the payload from a sync; the async API has no chunking; heavy dependencies are always built (about 327 packages).

What is still open, and who owns it.

Identity Kit

The question. Identity Kit has service principals with scopes. Can the App Context Kit’s admit(peer, hello) hook use them to decide whether a peer may join an app’s coordination: accept, accept read-only, or reject?

What was built. An admit module with scopes app:<id>:run, app:<id>:coordinate and app:<id>:storage. coordinate is accept, run alone is read-only, storage alone is refused. An in-memory fake issuer stood in for issuance, which Identity Kit does not have yet. The fake is a test double, not a design for the real one.

What it showed.

• The shape works. A program that only types an app id is refused. One app’s principal cannot join another app. A principal from another account is refused. A household rule (a child account may not run a given app) can be checked at each join, so changing a role takes effect without reissuing anything. Identity Kit keeps role out of the principal on purpose, so that rule can only live in whoever verifies.
• Gaps in Identity Kit: issuance, signing and verification are not built; the principal carries no account; scopes are opaque strings with no constructor or parser; the family graph is not built, so the role rule cannot read real roles.

What the App Context Kit does because of it. The Kit’s only authenticators are an open one that accepts everyone and a shared-secret one marked as a test fake, and the code says plainly that they are for one machine and tests, never a network. The loopback provider has no encryption or authentication; do not use it across a trust boundary. A real authenticator waits on Identity Kit issuance and signing. Until then the App Context Kit scopes copies by account and app id as a naming convention and does not authenticate them: do not treat peers as trusted.

What is still open, and who owns it.

Interface Kit (candidates)

The question. Six demo apps and a larger production app each wrote the same UI pieces by hand. Which pieces are shared enough to belong in the Interface Kit?

What was built. labs/interface_candidates: small, plain-Material components derived from what the apps duplicate. This is not the Interface Kit. The real Kit is untouched and nothing here is published. Every colour and text style comes from the ambient Theme, so the components can later be mapped onto the real design system. The package’s README lists the accessibility contract that the tests enforce.

Re-run when this page was written: flutter test in that package, 158 passed (make test-fast runs it).

What it showed. The catalog’s table has nine entries. Use in the demo apps, counted from the apps’ source:

The catalog marks four entries THIN: fewer than three real users, so a candidate rather than a recommendation. The rule for promotion is that at least three real screens duplicate the piece and it needs nothing from the app.

Two attempts were reverted, per the project’s notes (not re-run): EmptyState in the minesweeper demo (three one-line rows grew from 20 to 72 dp each) and StatusDotRow in the launcher (it worked, but turned a scannable table into a list; a design call).

No screen reader was run. The accessibility checks are semantics-tree and guideline tests.

What the App Context Kit does because of it. The core package stays free of Flutter. The Flutter companion carries ModeBadge, NotesBanner and the exit coordinator. The candidates stay in their own package. The Kit’s notes carry a severity (info, warning, error) so a banner can pick its style.

What is still open, and who owns it.

Venue

The question. Can an app hold a reservation on a shared machine the same way whether Venue is real, absent or faked?

What was built. A session type in both languages (Dart and Rust) and the render-queue demo app, which uses it harder than the others.

What it showed. The session hides the three cases. It also showed what the Kit’s first version got wrong: the daemon’s refusal for a live-hold limit was mistyped as “unavailable”; a failed lease renewal was swallowed; apps had no way to find holds left by a crash; and every app that could be refused wrote the same wait-and-retry loop. All four are addressed in the Dart Kit (the wait helper is not in the Rust Kit). What remains needs changes in Venue itself.

What the App Context Kit does because of it. Typed refusals, holds(), lease-loss reporting and withHoldWaiting (Dart). Registering an app with a daemon is still four manual steps that need an operator with authority. The render-queue demo app and the demo apps guide show the session in use; the full story, with code and measurements, is in the App Context Kit’s Venue guide.

What is still open, and who owns it.

Cross-cutting

Three themes recur across the probes.

1. Most of what makes the Kit hard lives in the other Kits. The Kit’s own part (find, connect, route) held on the first try in three very different apps. The gaps were payload limits, topic grammar, identity and signing, and storage lifecycle.
2. App identity is a naming convention until the Identity Kit issues and verifies capabilities. Hearth, Storage Kit and Identity Kit each showed a different face of the same fact.
3. Build a shared piece when the second app copies it, not before. The same rule decided what moved into the Kit (a wait helper, JSON helpers, a peers handle) and what stayed out (single-user helpers).

Kits

This is the catalog of every Kit in the SlashBuilder Kit registry: public or private, working or banked or archived. Each Kit has a status card. A Kit that is not public yet is listed anyway, because a catalog that hid its unfinished parts would not be honest about the platform.

The catalog is generated from the registry, not written by hand, so it cannot drift from it. The pages are committed to this repository so you can read them without access to the registry. A link to a repository appears only when that repository is public today.

Generated from registry commit 389c4a5.

19 Kits: 2 pre-release, 11 alpha, 4 design, 1 banked, 1 legacy. 1 of them has a public repository today.

How to read the cards

• Status says how real the Kit is, judged by evidence (code and tests), not by intent. See the status vocabulary.
• Has real code today is Yes for the statuses alpha, pre-release and stable. It says nothing about whether you can read the code: that depends on the Source line.
• Kind is the registry’s own label for the Kit (cross-platform, hybrid, substrate, infrastructure or core). It is not defined further yet.
• Some cards are brief because the registry entry behind them is brief. They say so.
• A Kit that was merged into another keeps its card and says which. Things that are not registered Kits, and this book itself, are on Not in the registry.

pre-release

Published, and depended on by products. The API is settling but not frozen.

alpha

Real code and tests exist, but the API is not stable. Expect it to change.

design

A document. There is no code to speak of yet.

banked

Deliberately paused, together with the program it belonged to. Not abandoned, but not being worked on.

legacy

Archived or retired. Kept in the catalog for the record; do not build new things on it.

Regenerating

Maintainers regenerate this folder with make docs-catalog; see Make targets.

Status vocabulary

Every Kit card carries one status. The test for a status is evidence, not intent: what the repository holds today (code, tests, a published version), not what is planned.

stable

The API is frozen, with a versioning promise.

No Kit has this status today.

pre-release

Published, and depended on by products. The API is settling but not frozen.

Kits with this status: Fabric Kit, Message Kit.

alpha

Real code and tests exist, but the API is not stable. Expect it to change.

Kits with this status: Inference Kit, Manifest Kit, Spec Kit, Identity Kit, Service Kit, Storage Kit, Substrate Kit, Interface Kit, Venue Kit, Mold Kit, Stash Kit.

scaffold

A skeleton of code that nothing depends on yet.

No Kit has this status today.

design

A document. There is no code to speak of yet.

Kits with this status: Platform Kit, Device Kit, Score Kit, App Store Kit.

banked

Deliberately paused, together with the program it belonged to. Not abandoned, but not being worked on.

Kits with this status: Thunderhead Kit.

legacy

Archived or retired. Kept in the catalog for the record; do not build new things on it.

Kits with this status: Design Kit.

All Kits

Not in the registry

The catalog lists the Kits in the registry. Some things this book talks about are not registered Kits, so they have no card. They are listed here so that nobody has to wonder why.

App Context Kit

• Registered Kit: no, so it is not in the catalog
• Source: not public yet

The App Context Kit is the root namespace for one running app: its identity, its folders for files and settings, test and scratch modes, a roster entry other apps can read, a session with a resource broker, and an opt-in way to find other copies of the app. The seven demo apps in this book are built on it (six are Flutter on a Dart core; notes_rust is a Flutter UI over a Rust core that shares the UI’s context through the Kit’s adopt API), and the demo apps guide measures what it saved and what it still leaves for an app to write. Its name is final, and it is a candidate for the registry rather than a member of it.

Its own reference documentation is pulled into this book from the Kit, at the commit this book pins (make docs-pull), so you can read it without access to the Kit’s repository. It is the only Kit pulled so far. Start at the reference index.

• Reference index
• Overview
• Getting started
• Context guide
• Venue guide
• Coordination guide: copies of one app talking to each other
• Testing
• Architecture
• Platforms
• Design decisions
• The app context spec
• Example: dart_cli
• Example: rust_cli
• Example: flutter_hello

This book

This repository, kit-book, is the book, not a Kit. It has no card, it is not in the registry, and nothing depends on it.

All Kits · Status vocabulary

Fabric Kit

The Hearth SDK: pub/sub, pairing, and the family-graph client.

• Status: pre-release (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet

What it owns

Fabric Kit is the Hearth protocol SDK: pub/sub messaging, device pairing, and family-graph primitives.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Message Kit, Score Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Message Kit

The Hearth wire envelope: T/R/D grammar and RemoteTransport.

• Status: pre-release (what this means)
• Language: Rust
• Kind: hybrid
• Has real code today: Yes
• Source: not public yet

What it owns

Message Kit’s core is the envelope proto, the T/R/D grammar, and the RemoteTransport trait; its substrate binding is AF_UNIX SOCK_SEQPACKET (in-crate, not a separate repo). Inference Kit’s optional async inference fallback rides this kit via its message-kit-binding module.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Fabric Kit, Inference Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Inference Kit

Local-first inference orchestration for Hearth households.

• Status: alpha (what this means)
• Language: Rust
• Kind: hybrid
• Has real code today: Yes
• Source: slash-builder/inference-kit

What it owns

Inference Kit is a cross-platform inference service for Hearth household clusters. Apps declare model dependencies (semantic versions); Inference Kit resolves, loads, and caches model weights via Storage Kit (shared across apps, mmap’d RO). Models are OS-shipped, signed at build time, and verified immutably at boot. Capability gating via Score Kit.

What it will not do

• Training or fine-tuning (inference-only; no backprop, no graph construction)
• Model serving infrastructure (multi-model load balancing, LLM-specific optimizations like LoRA/flash-attention deferred to app logic)
• Runtime model distribution (models ship with OS; no OTA, no remote fetch)
• Prompt filtering or jailbreak detection (application-layer concern)
• Output safety gates (application-layer concern)
• Model-specific tuning (quantization strategy is app config, not Inference Kit)
• Cloud hub relay in MVP (future feature gate; local-only MVP)
• TPM attestation (optional future enhancement; not MVP)

Related Kits

Storage Kit, Message Kit, Score Kit, Service Kit, Spec Kit, Device Kit, Platform Kit

Reference docs

This Kit’s own reference documentation has not been pulled into the book yet. make docs-pull pulls it once the Kit has a section in tools/docs-pull.conf; see Make targets.

All Kits · Status vocabulary

Manifest Kit

Generate operating systems from a single manifest.

• Status: alpha (what this means)
• Language: Rust
• Kind: infrastructure
• Has real code today: Yes
• Source: not public yet

What it owns

Build-time infrastructure kit: each OS or app is one manifest over a common component catalog. Also owns the shared cross-platform target axis schema that any kit with more than one build target selects against, instead of inventing its own per-kit target list.

What it will not do

• Board bring-up or device drivers (Platform Kit / Device Kit concern)

Related Kits

Platform Kit, Device Kit, Substrate Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Spec Kit

Conformance and spec primitives shared by every Kit.

• Status: alpha (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet

What it owns

Spec Kit provides the conformance and spec primitives imported into every other Kit’s test suite: the invariants list pattern, the CHANGELOG-freeze convention, and the conformance::{Case, run_suite, ...} harness that Storage Kit and Inference Kit already reference.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Storage Kit, Inference Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Identity Kit

OIDC client and account/family identity types for the household.

• Status: alpha (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet

What it owns

Identity Kit provides the OIDC client, capability primitives, and account/family types used across the fabric.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Substrate Kit, Score Kit, Service Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Service Kit

axum/tower service foundation: metrics, structured errors, audit trail.

• Status: alpha (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet

What it owns

Service Kit is the axum/tower service foundation used across SlashBuilder’s Rust services: no dockerd dependency. It provides the observability primitives (latency metrics, structured error codes, logging, audit trail) that other kits emit to; Inference Kit’s service-kit-bridge module is a live consumer.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Inference Kit, Spec Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Storage Kit

Content-addressed storage core: BLAKE3, dedup, per-household partitions.

• Status: alpha (what this means)
• Language: Rust
• Kind: hybrid
• Has real code today: Yes
• Source: not public yet

What it owns

The registry has no public-safe description for this Kit yet.

Related Kits

Inference Kit, Spec Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Substrate Kit

The Linux+dockerd container/process substrate for the household box.

• Status: alpha (what this means)
• Language: Rust
• Kind: substrate
• Has real code today: Yes
• Source: not public yet

What it owns

Substrate Kit covers container/process lifecycle, cgroups, mount/volume, and service-principal embodiment (embodies identity-kit’s ServicePrincipal verbatim, never redefines it).

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Identity Kit, App Store Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Interface Kit

• Status: alpha (what this means)
• Language: Rust + Dart
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet

What it owns

Interface Kit provides shared composed UI/interaction patterns for household-computing surfaces (service tiles, install/status flows, navigation shells, pairing/onboarding chrome): not raw design tokens and not a full app.

The registry entry for this Kit is still a short summary, so this card is brief.

It is made up of: Interface Kit (module patterns), Mold Kit (module mold).

Related Kits

Mold Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Venue Kit

One registry and planner for every place work can run.

• Status: alpha (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet
• Name: provisional; it may change

What it owns

Venue Kit describes and plans over the places work can run: a machine, a VM, an API provider, a cloud pool you can rent from, a peripheral behind a host. What each is, how to reach it, what it has, what it can do, what it will accept, what it costs, and who may use it. It is a Kubernetes Resource Model vocabulary rather than a new format: Node, Endpoint, NodePool, ContractClass, ContractClaim, Placement and Budget in the API group node.slashbuilder.com/v1alpha1, with PriorityClass and Lease accepted verbatim from Kubernetes. Kubernetes (and DRA, Karpenter) is treated as the standards body: its names, shapes and semantics are followed unless a divergence is recorded with a reason.

Every answer is Yes, No or Unknown, and an Unknown says what would settle it. Nothing is trusted because a document says so: each manager writes its own observation, the effective view is computed on read and keeps disagreements visible, and work that carries data classes needs both a use grant and the data owner’s egress grant or the answer is Unknown.

What it will not do

• Running the work, or provisioning anything: Venue plans and records, something else provisions
• Inference, storage, messaging: those are their own Kits, which sit on top of or beside this one
• Containers and other workloads (many, short-lived; their names and images describe the estate): another layer’s job
• Changing a machine: accounts, keys, sudo, packages, policies.

Related Kits

Identity Kit, Storage Kit, Inference Kit, Interface Kit, Manifest Kit, Score Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Mold Kit

• Status: alpha (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: Yes
• Source: not public yet
• Registry entry: merged into Interface Kit; this Kit’s repository and crate names are unchanged

What it owns

The registry has no public-safe description for this Kit yet.

What it will not do

• Mold rendering / UI widgets

Related Kits

Fabric Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Stash Kit

Content-addressed working-memory substrate with per-principal keys and real deletion.

• Status: alpha (what this means)
• Language: Rust
• Kind: core
• Has real code today: Yes (not published)
• Source: Repository not created yet
• Registry entry: pending; not yet a published Kit

What it owns

The registry has no public-safe description for this Kit yet.

What it will not do

• Inference of any kind: that is Inference Kit
• Retrieval ranking, graph retrieval, consolidation, decay curves
• Bytes, chunking, packfiles, dedup: Storage Kit

Related Kits

Storage Kit, Inference Kit, Message Kit, Score Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Platform Kit

• Status: design (what this means)
• Language: Rust
• Kind: substrate
• Has real code today: No
• Source: not public yet
• Registry entry: merged into Thunderhead Kit; this Kit’s repository and crate names are unchanged

What it owns

The registry has no public-safe description for this Kit yet.

Related Kits

Device Kit, Substrate Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Device Kit

Hardware peripheral access, DRM, audio, input, on the reference boards.

• Status: design (what this means)
• Language: Rust
• Kind: substrate
• Has real code today: No
• Source: not public yet
• Registry entry: merged into Thunderhead Kit; this Kit’s repository and crate names are unchanged

What it owns

Device Kit covers hardware peripherals (DRM display, PipeWire audio, evdev input) on the Thunderhead reference boards. Score Kit’s conductor/sonic logic routes hardware audio output through this kit. Attributed to the parked Thunderhead hardware program alongside Platform Kit.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Platform Kit, Score Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Score Kit

Capability grants, rate limiting, and the household’s conductor/notification/sonic logic.

• Status: design (what this means)
• Language: Rust
• Kind: cross-platform
• Has real code today: No
• Source: not public yet
• Registry entry: merged into Thunderhead Kit; this Kit’s repository and crate names are unchanged

What it owns

Score Kit covers capability grants, rate limiting, SLA tracking, and conductor/notification/sonic logic; hardware audio output routes through Device Kit.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Inference Kit, Device Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

App Store Kit

Manifest, capability, and signing core for installable household services.

• Status: design (what this means)
• Language: Rust
• Kind: hybrid
• Has real code today: No
• Source: not public yet
• Registry entry: merged into Thunderhead Kit; this Kit’s repository and crate names are unchanged

What it owns

App Store Kit’s core is the manifest/capability/signing/catalog logic for installable household services; its runtime binding is currently Podman/crun and must move onto the Linux+dockerd substrate (via Substrate Kit) per the single-dockerd-substrate commitment.

The registry entry for this Kit is still a short summary, so this card is brief.

Related Kits

Substrate Kit, Score Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Thunderhead Kit

The Thunderhead device stack: board bring-up, peripherals, the conductor and the app runtime. Banked with the Thunderhead program.

• Status: banked (what this means)
• Language: Rust
• Kind: substrate
• Has real code today: No
• Source: not public yet
• Name: provisional; it may change

What it owns

The registry has no public-safe description for this Kit yet.

It is made up of: Platform Kit (module platform), Device Kit (module device), Score Kit (module conductor), App Store Kit (module appstore).

Related Kits

Substrate Kit, Identity Kit, Venue Kit, Inference Kit

Reference docs

No reference docs yet.

All Kits · Status vocabulary

Design Kit

• Status: legacy (what this means)
• Language: Dart
• Kind: cross-platform
• Has real code today: No
• Source: not public yet

What it owns

Design Kit shipped Flutter/Dart design tokens.

The registry entry for this Kit is still a short summary, so this card is brief.

Reference docs

No reference docs yet.

All Kits · Status vocabulary

App Context Kit documentation

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

Overview · Getting started · Context guide · Venue guide · Coordination · Architecture · Platforms · Testing · Design decisions · Spec · Contributing · Repository home

The App Context Kit is the root namespace for one running app. It gives an app an identity, a place for its files and settings, test and scratch modes, a presence entry other apps can see, a session with a resource broker, and an opt-in way to find and talk to other copies of itself. It does not decide what any of that means for your app.

It is a piece of a larger platform, it is not published to a package registry yet, and the question behind it is: does the BeOS idea of an Application Kit still make sense when you build several small apps instead of one big one? These pages say what was built, how it was checked, and what is not yet known.

Start here

Every page

Learn

Build

Evidence

Runnable examples

Every code sample in these pages is copied from one of these, or from a passing test or one of the demo apps in The Kit Book. Run them rather than trusting the text.

The short version of the results

• One contract, two implementations. Dart and Rust pass the same 61 fixtures. The second implementation found about a dozen behaviours the first had decided silently.
• Less code per app. Helper code the six apps wrote themselves went from 727 lines to 330, up to 777 after coordination was added, and down to 164 once the repeated parts moved into the Kit. Every main.dart is 5 to 11 lines. Build a Kit piece when the second app copies it, not before.
• The hook is the right shape, and not enough on its own. It carried a shared timer and a game handoff cleanly, and live play only just. For sync it was a small shell around a lot of app code, because the Kit gives no acknowledgement, large transfer, replay or liveness tick.
• Same-machine coordination works; across machines is not built. Two copies found each other in under half a second on one machine; a crashed copy disappeared in about 3.5 s.

What is not verified

A real Linux desktop session (the cores are tested in Linux containers, and the demo apps were built in release mode and launched headless in a Linux container), window close on a real window, signed or packaged release builds, Windows beyond the pure path rules, and the peer code against a real remote hub. Each page marks its own unverified claims. “Verified” in these pages means a test, a command or a measurement in the App Context Kit repository; anything else is labelled as reasoned or reported.

The demo apps

Several pages quote six small demo apps (a calculator, minesweeper, a notepad, a stopwatch, a render queue and a launcher) and the helper code each one had to write. The apps are not in the App Context Kit repository: they live in The Kit Book (the Kit Book repository), which documents the Kit and holds the demo apps. Paths such as lib/kit_gaps/ or lib/coordination/ in these pages are paths inside those apps.

Conventions

• Page names are stable; sections are linked by their headings.
• Code blocks are checked against the App Context Kit repository. Where a block is illustrative, it says so.
• Some findings about other systems are deliberately not described here: where a review is pending, the page says that and nothing more.
• Numbers come with what they were measured on (macOS debug builds, loopback, a throwaway local broker). They are not benchmarks.

Repository home · Spec · Contributing · Licence (Apache-2.0)

Pages in this book

Every page pulled from the Kit, in reading order.

Overview

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

The App Context Kit is a small library that gives one running application its root namespace: who it is, where its files live, where its settings are, whether it is running for real or under test, who else is running, and how it shuts down. You describe the app in a short app.json, open an AppContext, and the rest of your code asks that object instead of working these things out itself.

It is a work in progress. App Context Kit borrows its idea from the BeOS Application Kit; it is not a reimplementation of it and is not affiliated with Haiku. Nothing here is published to a package registry. See Status.

The problem

Every desktop or mobile app starts main() by answering the same questions, and most answer them differently:

• Identity. What is this app called, what version is it, and what is its reverse-DNS id? The answer ends up in four places that can disagree: the pubspec.yaml, the macOS bundle, the Linux runner and a string in the code.
• Where files live. Data, settings, cache and runtime files each have a conventional home on macOS, Linux and Windows. Apps hard-code one of them, or copy a path helper from the last project.
• Settings. Reading and writing a small JSON file safely: atomically, and without overwriting a file you could not read.
• Test modes. A way to run the app against fakes, in a throwaway folder, without touching the developer’s real data. Each app grows its own --mock switch.
• Who else is running. Is another copy of this app already open? Which apps are running at all?
• Quitting cleanly. Window close, Quit and Ctrl-C are different events. Cleanup that runs on one of them is often skipped on the others.

None of this is hard. It is the same code, written again for each app, and it is where small bugs live: a settings file that is silently replaced after one bad byte, a lock file left behind after a crash, a test that wrote into the real home directory.

The idea

Put all of it in one place, under one object, driven by one file.

app.json  ->  AppManifest  ->  resolve (pure function)  ->  AppContext.open  ->  your app

Resolution (which directory, which mode) is a pure function of the manifest, the platform, the home directory and the environment. It does no I/O, so it can be specified exactly and tested with fixtures. Opening a context then creates the directories, reads the settings, opens a Venue session and announces the app in the roster. Closing it undoes that, in a fixed order, once.

Where it comes from

The idea and the shape come from the BeOS Application Kit. In BeOS every program had a BApplication object that was the program’s root, and a BRoster that knew which programs were running. This Kit keeps those two ideas: one root object per running app, and a roster of running apps.

It differs on purpose in three ways:

• No looper or handler model. BeOS built the Kit around message loops (BLooper, BHandler). This Kit does not own your event loop or your threads. Flutter already has one. The Kit gives you a context object, and the only messaging it provides is the opt-in peers piece, between copies of the same app.
• Cross-language. The contract is a written spec plus shared test fixtures, not one implementation. A Dart implementation and a Rust implementation both pass every fixture.
• Flutter on top of a Rust-or-Dart core. The intended shape is a Flutter UI over a core that may be written in either language. Today six of the demo apps (in The Kit Book) use the Dart core, and a seventh puts a Rust core under a Flutter UI. The Rust crate implements the same spec and passes the same fixtures, and the two sides share one context: the Dart side opens it and the Rust side adopts it (see Sharing one context with a Rust core).

The pieces

Venue is a resource broker. An app asks it for a lease on something, such as a slot to run a job, holds it while it works and releases it. The Kit does not implement Venue; it provides the client side and hides whether a Venue is configured. With no Venue the session is local and says so, and in mock mode it is an in-memory fake. The client for a real daemon exists in the Dart core only: the Rust crate has local and fake sessions and no remote Venue session.

Peers are off unless the manifest lists "peers" in its kits. The Kit ships two providers: an in-memory fake network for mock mode and tests, and a loopback provider for copies on one machine. Peers between machines are not part of the Dart core.

A Flutter companion package, app_context_kit_flutter, adds what the pure-Dart core cannot do: load app.json from the asset bundle, close the context exactly once however the app ends, and a few small widgets (a mode badge, a notes banner, a peers indicator, a startup error screen). It also provides widget-test helpers.

Design rules

1. The spec is the contract. spec/APP-CONTEXT.md and the fixtures in spec/conformance/ define behaviour. Both implementations must pass every fixture. If the prose and a fixture disagree, the fixture wins and the prose is corrected.
2. Apps compose the Kit and never fork it. An app that needs something the Kit lacks writes it in the app (the demo apps keep these under lib/kit_gaps/) and marks it // KIT GAP:. That code is the record of what is missing.
3. The Kit never interprets an app’s payload. It finds peers, connects to them and carries bytes. What a message means is the app’s decision.
4. The core stays pure Dart. app_context_kit has no Flutter import. Anything that needs Flutter goes in app_context_kit_flutter.
5. Build a piece when the second app copies it. Code only one app needs stays in that app. A helper moves into the Kit once a second app has written the same thing.

What it does not do

• No UI toolkit. The companion package has a handful of plain Material widgets for the Kit’s own state. It has no design system, theming, routing or state management.
• No sync engine. Peers gives you discovery, a connection and best-effort ordered delivery. Reconciling data between copies is your code. Large transfers are not built.
• No installer or updater. The Kit does not install, update or launch apps. The roster reports which apps are running, not which are installed.
• No authentication or accounts. The peers scope key is (account, app id), and the account defaults to the string local. The default authenticator, OpenAuthenticator, accepts every peer, so an account or app id is a claim, not a proof. The only other authenticator in the code is a test fake. The Kit does not issue accounts or credentials.
• No window title, bundle id or version sync. Those live in native build files that a running app cannot change. A script, dart/app_context_kit_flutter/tool/check_identity.dart, checks that they agree with app.json.

Repository map

Documentation:

• Getting started: a running app, step by step
• Context guide: reference for fields, directories, environment variables and lifecycle
• Testing: testing an app built on the Kit, and running the App Context Kit repository’s suites
• Contributing: building and changing the Kit itself

Status

• The Dart packages are marked publish_to: none; none is on pub.dev. The Rust crate slashbuilder-app-context-kit is not published to crates.io yet.
• The spec is version 0.1. Behaviour may change, including in breaking ways.
• Verified for this documentation: the Dart core and companion test suites, the Rust test suite and the conformance fixtures in both languages, run on macOS; the Linux runs of the cores in Docker; and the demo apps built in release mode and launched headless in a Linux container (see Platforms). No Windows test run is recorded in the App Context Kit repository, although the fixtures cover Windows path resolution.

Getting started

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

This guide takes you from an empty folder to a Flutter desktop app that runs on the App Context Kit, then shows the same thing in plain Dart and in Rust. For what the Kit is, read the overview. For every field and rule, see the context guide.

The app you build is a window with a button. Each tap is counted, saved as a setting and written to a file. The finished project is in docs/examples/flutter_hello/. Every code block below is a file from that directory, or a file from docs/examples/dart_cli/ or docs/examples/rust_cli/.

You need Flutter 3.24 or later with desktop support enabled. The steps were walked through with Flutter 3.41.9 and Dart 3.11.5 on macOS. The demo apps built on the Kit were also built in release mode and launched on Linux, headless in a container (see Platforms). Where a step differs on Linux or Windows and was not run there, the text says so.

1. Create the project

The app id you choose in app.json should match the bundle id Flutter generates, so create the project with a package name and organisation that join up. Package hello with organisation dev.example gives the id dev.example.hello:

flutter create --platforms=macos,linux,windows --org dev.example hello
cd hello
rm test/widget_test.dart   # the template's counter test; it does not fit this app

2. Add the dependencies

The two Kit packages are not published. They are publish_to: none, so you point at them by path or by git.

By path (what the demo apps use). Check out the App Context Kit repository somewhere and point at it. Add to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  app_context_kit:
    path: ../app-context-kit/dart/app_context_kit
  app_context_kit_flutter:
    path: ../app-context-kit/dart/app_context_kit_flutter

Adjust the relative path to wherever your checkout is. List both packages: app_context_kit_flutter depends on app_context_kit, and your code imports both.

By git, once the App Context Kit repository is reachable by URL. Pin both entries to the same full 40-character commit hash in ref:

  app_context_kit:
    git:
      url: <repository-url>
      path: dart/app_context_kit
      ref: <full-commit-sha>
  app_context_kit_flutter:
    git:
      url: <repository-url>
      path: dart/app_context_kit_flutter
      ref: <full-commit-sha>

This form was tested against a local clone of the App Context Kit repository. With the default branch instead of a pinned hash, or with an abbreviated hash, pub get failed with a version-solving error, because the companion’s own dependency on the core resolved to a different reference than yours. I have not tested it against a public URL, because there is none yet.

Then declare the manifest as an asset, and make the pubspec.yaml version match the manifest:

version: 0.1.0+1

flutter:
  uses-material-design: true
  assets:
    - app.json

The template’s version is 1.0.0+1. The Kit does not read the pubspec.yaml, but app.json and the pubspec.yaml should say the same thing, and the check in step 9 fails if they do not.

3. Write app.json

Create app.json next to pubspec.yaml. This is docs/examples/flutter_hello/app.json:

{
  "id": "dev.example.hello",
  "name": "Hello",
  "version": "0.1.0",
  "kits": [],
  "envPrefix": "HELLO",
  "venue": { "mode": "off" }
}

If the manifest is wrong, the app shows an error screen with a code such as bad-id. The context guide lists every code. The rules are in spec section 1.

4. Write main.dart

Replace lib/main.dart with this. It is docs/examples/flutter_hello/lib/main.dart, and apart from the import it is the same line as the calculator demo app’s lib/main.dart (the demo apps are in The Kit Book):

import 'package:app_context_kit_flutter/app_context_kit_flutter.dart';

import 'hello_app.dart';

Future<void> main() => AppContextKit.run(manifestAsset: 'app.json', app: (_) => const HelloApp());

AppContextKit.run does the work a hand-written main() would: it initialises Flutter’s binding, loads and validates app.json from the asset bundle, opens the AppContext, mounts an AppContextScope above your widget, and makes window close, Quit, SIGINT and SIGTERM all close the context exactly once before the process ends. If it cannot start, it shows an error screen instead of crashing.

5. Read the context, save a setting, write a file

Create lib/hello_app.dart. This is docs/examples/flutter_hello/lib/hello_app.dart:

import 'package:app_context_kit/app_context_kit.dart';
import 'package:app_context_kit_flutter/app_context_kit_flutter.dart';
import 'package:flutter/material.dart';

class HelloApp extends StatefulWidget {
  const HelloApp({super.key});

  @override
  State<HelloApp> createState() => _HelloAppState();
}

class _HelloAppState extends State<HelloApp> {
  late final AppContext ctx;
  late final SessionSettings settings;
  late int taps;
  var _started = false;

  // An InheritedWidget cannot be read in initState, so read the context on the first didChangeDependencies.
  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    if (_started) return;
    _started = true;
    ctx = AppContextScope.of(context);
    settings = SessionSettings(ctx.config);
    taps = settings.get<int>('taps', 0);
  }

  void _tap() {
    setState(() => taps++);
    settings.set('taps', taps); // a setting, in <config>/config.json
    ctx.dataFile('taps.log').writeAsStringSync('$taps\n'); // a file, under <data>
  }

  @override
  Widget build(BuildContext context) => MaterialApp(
        title: ctx.manifest.name,
        home: Scaffold(
          appBar: AppBar(title: Text(ctx.manifest.name), actions: [ModeBadge.forContext(ctx)]),
          body: Column(children: [
            NotesBanner.forContext(ctx),
            Text('Taps: $taps'),
            FilledButton(onPressed: _tap, child: const Text('Tap')),
          ]),
        ),
      );
}

What this uses:

• AppContextScope.of(context) returns the AppContext that AppContextKit.run mounted. It throws a FlutterError that says how to fix it if there is no scope above the widget. There is also maybeOf, which returns null.
• ctx.manifest is the parsed app.json.
• A setting. ctx.config is a ConfigStore over <config>/config.json. ctx.config.set('taps', 3) saves at once, atomically. If config.json is damaged, set throws DamagedConfigError rather than overwrite a file it could not read. This example wraps the store in SessionSettings, whose set never throws: while the file is damaged it keeps the change in memory for the session, and settings.readOnly tells you so. See settings.
• A file under data. ctx.dataFile('taps.log') is a File under ctx.dirs.data. The directory already exists. For a JSON file with an atomic write and a read that tells “missing” from “damaged”, use ctx.dataJson('name.json').
• ModeBadge.forContext(ctx) shows nothing in a normal run and a chip reading mock, scratch or mock + scratch otherwise.
• NotesBanner.forContext(ctx) shows warnings and errors the Kit recorded in ctx.notes, such as a damaged settings file. It hides information-level notes.

ctx.notes is a plain list that notifies nobody. If your app adds a note, rebuild the banner yourself.

6. Run it

flutter run -d macos     # or -d linux, -d windows

On macOS the app wrote its folders here (checked by running a fresh project built as above):

flutter create turns the macOS App Sandbox on, so the ~ above is the app’s container, ~/Library/Containers/dev.example.hello/Data. See the macOS sandbox. The context guide has the table for Linux and Windows.

Scratch and mock

Two environment variables let you run the app without touching real data:

• APP_CONTEXT_SCRATCH=<folder> puts every directory, and the roster, under that folder.
• APP_CONTEXT_MODE=mock swaps Venue for an in-memory fake. HELLO_MODE=mock does the same for this app only.

flutter run passes your shell’s environment to the app (checked with APP_CONTEXT_SCRATCH on macOS). On Linux:

APP_CONTEXT_SCRATCH="$(mktemp -d)" APP_CONTEXT_MODE=mock flutter run -d linux

That exact command was not run on Linux (the demo apps were built there with flutter build linux --release and launched headless in a container; see Platforms). With both variables set, the app bar shows the chip mock + scratch. On macOS the scratch folder has to be inside the sandbox container, so the command is different there; see the macOS sandbox.

7. Venue, and the default

Venue is a resource broker. ctx.venue is the one object an app uses to ask it for something. The manifest’s venue.mode decides how the Kit opens it:

So an app does not need a Venue to run, and does not need "mode": "off" for that: auto already degrades to a local session when nothing is configured. This example sets off to say plainly that it does not use Venue. In a normal run the Kit records one information-level note carrying the Venue description. NotesBanner hides it unless you pass showInfo: true.

In mock mode the session is always the in-memory FakeVenue, whatever venue.mode says. The environment variables that configure a real Venue are in the context guide.

8. Write the first widget test

Create test/hello_test.dart. This is docs/examples/flutter_hello/test/hello_test.dart:

import 'dart:io';

import 'package:app_context_kit_flutter/testing.dart';
import 'package:hello/hello_app.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('taps are saved and survive a quit and relaunch', (tester) async {
    final kit = await pumpKitApp(
      tester,
      manifest: File('app.json').readAsStringSync(),
      app: (ctx) => const HelloApp(),
    );
    expect(find.text('Taps: 0'), findsOneWidget);
    expect(find.text('mock + scratch'), findsOneWidget);

    await tester.tap(find.text('Tap'));
    await tester.pump();
    expect(find.text('Taps: 1'), findsOneWidget);
    expect(kit.ctx.dataFile('taps.log').readAsStringSync(), '1\n');

    await kit.relaunch(); // close, open again on the same scratch directory, mount again
    expect(find.text('Taps: 1'), findsOneWidget);
  });
}

flutter test

Expected: All tests passed!.

pumpKitApp makes a temporary scratch folder, sets APP_CONTEXT_MODE=mock, opens the context without a roster entry, mounts your widget under an AppContextScope, and deletes the folder when the test ends. It never reads the environment of the machine running the tests. kit.relaunch() closes the context, so your onClose hooks run, opens a new one on the same files and mounts the app again. Testing has the rest.

9. Check that the identity agrees

An app’s identity lives in app.json, in pubspec.yaml, in the macOS runner and in the Linux runner. The Kit cannot change native build files, so a script compares them. From a checkout of the App Context Kit repository:

cd dart/app_context_kit_flutter
dart tool/check_identity.dart /path/to/hello

For the project above it printed:

== /path/to/hello
  note      name: app.json says "Hello" but the macOS PRODUCT_NAME is "hello" (same name, different letter case)
  note      name: app.json says "Hello" but the Linux window title is "hello" (same name, different letter case)
  ok: id, name and version agree everywhere they were checked

With the template’s version: 1.0.0+1 it reported MISMATCH version and exited 1. It does not check Windows, Android or iOS, and it never edits a file.

macOS sandbox

The macOS runner that flutter create generates has the App Sandbox on. Three things follow, each checked on macOS with a project built as above.

Files go in the app’s container. Inside the sandbox, HOME and TMPDIR point into ~/Library/Containers/<bundle id>/Data, so the default directories and the roster all land there. You do not need to do anything.

A scratch folder must be inside the container too. The sandbox refuses writes elsewhere. With APP_CONTEXT_SCRATCH=/tmp/somewhere, the app created nothing and showed its start-up error screen: “This app could not start. The app’s folders could not be created or read: Creation failed (/tmp/somewhere)”, with Error code: open-failed. A path under the container works:

APP_CONTEXT_SCRATCH="$HOME/Library/Containers/dev.example.hello/Data/tmp/scratch" flutter run -d macos

The container folder only exists after the app has run once.

Network access needs an entitlement. flutter create writes these files in macos/Runner/: DebugProfile.entitlements (sandbox, JIT and network.server) and Release.entitlements (sandbox only). A Venue daemon is reached over HTTP, and peers connect to each other, so an app that does either is likely to need outgoing connections allowed. Add this to both files:

<key>com.apple.security.network.client</key>
<true/>

For reference, in release builds the calculator demo app (Venue off, no peers) declares the sandbox and nothing else, and the notepad demo app (peers on) declares network.server and network.client. What happens to an app that uses peers or Venue without these entitlements was not tested. Two of the demo apps, launcher and render-queue, turn the sandbox off.

Plain Dart

The core package has no Flutter dependency, so a command-line tool or server can use it. The program is docs/examples/dart_cli/. It reads the same kind of app.json:

{
  "id": "dev.example.hello",
  "name": "Hello",
  "version": "0.1.0",
  "envPrefix": "HELLO",
  "venue": { "mode": "off" }
}

pubspec.yaml depends on the core only:

name: dart_cli
description: A command-line program built on the App Context Kit core. Example from docs/GETTING-STARTED.md.
publish_to: none

environment:
  sdk: ^3.0.0

dependencies:
  app_context_kit:
    path: ../../../dart/app_context_kit

dev_dependencies:
  test: ^1.24.0

bin/main.dart:

import 'dart:io';

import 'package:app_context_kit/app_context_kit.dart';

Future<void> main() async {
  final manifest = AppManifest.parse(File('app.json').readAsStringSync());

  await AppContext.run(manifest, (ctx) async {
    // A setting: kept in <config>/config.json, written atomically.
    final launches = ctx.config.get<int>('launches', 0) + 1;
    ctx.config.set('launches', launches);

    // A file of the app's own: under <data>.
    ctx.dataFile('hello.txt').writeAsStringSync('launch $launches\n');

    print('app      ${ctx.manifest.id} ${ctx.manifest.version}');
    print('mode     ${ctx.mode.name}${ctx.scratch ? ' (scratch)' : ''}');
    print('data     ${ctx.dirs.data}');
    print('config   ${ctx.dirs.config}');
    print('launches $launches');
    print('venue    ${ctx.venue.description}');
  });
}

cd docs/examples/dart_cli
dart pub get
APP_CONTEXT_SCRATCH=/tmp/app-context-demo dart run bin/main.dart

app      dev.example.hello 0.1.0
mode     real (scratch)
data     /tmp/app-context-demo/dev.example.hello/data
config   /tmp/app-context-demo/dev.example.hello/config
launches 1
venue    Venue: local (Venue is off for this app)

Run it again and launches is 2. AppContext.run opens the context, runs your function and closes the context afterwards, also when your function throws. A bad manifest throws ManifestError with the code; a bad HELLO_MODE throws ResolveError(bad-mode).

AppContext.run closes as soon as your function returns. That is right for a command-line tool. It is wrong for a Flutter app, where runApp returns at once, which is why Flutter apps use AppContextKit.run.

Rust

The crate in rust/ implements the same manifest, the same directory rules and the same settings file. It does not have peers, SessionSettings, AppJsonFile or a remote Venue session. The program is docs/examples/rust_cli/, with the same app.json.

Cargo.toml:

[package]
name = "rust_cli"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
app-context-kit = { package = "slashbuilder-app-context-kit", path = "../../../rust" }
serde_json = "1"

[workspace]

src/main.rs:

use app_context_kit::{AppContext, Manifest, OpenOptions};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let manifest = Manifest::parse(&std::fs::read_to_string("app.json")?)?;

    AppContext::run(manifest, OpenOptions::default(), |ctx| {
        // A setting: kept in <config>/config.json, written atomically.
        let launches = ctx.config.get_or::<i64>("launches", 0) + 1;
        ctx.config.set("launches", json!(launches)).expect("settings are writable");

        // A file of the app's own: under <data>.
        std::fs::write(ctx.data_file("hello.txt"), format!("launch {launches}\n")).expect("data dir is writable");

        println!("app      {} {}", ctx.manifest.id, ctx.manifest.version);
        println!("mode     {}{}", ctx.mode().as_str(), if ctx.is_scratch() { " (scratch)" } else { "" });
        println!("data     {}", ctx.resolved.dirs.data);
        println!("config   {}", ctx.resolved.dirs.config);
        println!("launches {launches}");
        println!("venue    {}", ctx.venue.description());
    })?;
    Ok(())
}

cd docs/examples/rust_cli
APP_CONTEXT_SCRATCH=/tmp/app-context-demo-rs cargo run

It prints the same six lines as the Dart program, with /tmp/app-context-demo-rs in the paths.

The Kit’s Rust crate has no remote Venue session. Its Venue sessions are local and fake only, so the last line above always reports a local session. A token that is found cannot connect to a daemon: with venue.mode auto the session is local and says so, and with on the context fails to open. The crate builds from the App Context Kit repository alone; its dependencies (serde, serde_json and chrono) come from crates.io.

Next

• Context guide: every manifest code, directory rule, environment variable and lifecycle detail
• Testing: scratch and mock modes, the fakes, the conformance fixtures and every test suite in the App Context Kit repository
• The demo apps in The Kit Book run from a calculator (the smallest app) to a notepad (the largest: settings, files, peers and tests).

Context guide

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

Reference for the AppContext and everything it is built from. It describes the Dart core (app_context_kit) and the Flutter companion (app_context_kit_flutter), and says where the Rust crate differs. The contract these rules come from is spec/APP-CONTEXT.md; this guide links to its sections instead of repeating them, and adds what the code does that the spec leaves open. If the guide and a fixture in spec/conformance/ disagree, the fixture is right.

To build something, start with Getting started.

Contents: the manifest · directories · environment variables · modes · the config store · AppJsonFile and ctx.dataJson · SessionSettings · notes · the Venue session · lifecycle · what the Flutter companion adds · the roster · peers · errors · the Rust crate

The manifest

app.json is parsed by AppManifest.parse(text) (JSON text) or AppManifest.fromJson(value) (an already-decoded value). Both throw ManifestError, whose code is the first rule that failed, checked in the order below. A field that is present but null is present and invalid. Every pattern must match the whole string, so a trailing newline fails. Spec: section 1.

AppManifest exposes id, name, version, kits (unmodifiable), envPrefix (nullable: only what the file says) and venue (VenueSettings: mode, consumer). Unknown fields are ignored.

kits is checked in one place today: ctx.peerHub and ctx.startPeers throw KitNotDeclared unless it contains "peers". A Venue session is opened whether or not kits lists "venue".

Directories

resolve(manifest:, platform:, home:, env:) is a pure function: it reads no files and touches no disk. AppContext.open calls it and then creates every directory with createSync(recursive: true). Spec: section 2.

ID is the manifest id. Paths are joined with / on Linux and macOS and with \ on Windows, whatever the host is.

The roster is one directory shared by every app for the user, so it has no ID in its path.

A trailing separator on a base such as TMPDIR=/var/T/ is dropped before joining, using the target platform’s separators only. A base that is only a separator (/) is not reduced to nothing: / and ID join to /ID.

On Windows, a missing LOCALAPPDATA, APPDATA or TEMP is the error missing-env, but only if a default that needs it is actually used. A directory fixed by an override or by scratch needs none.

Overrides, highest priority first, for each of data, config, state, cache and runtime:

1. <PREFIX>_<KIND>_DIR (for example HELLO_DATA_DIR): used exactly as given. No id is appended and nothing is trimmed.
2. Scratch: if APP_CONTEXT_SCRATCH=S is set, the directory is S/ID/<kind> and the roster is S/roster. Scratch always joins with /, on every platform.
3. The platform default.

APP_CONTEXT_ROSTER_DIR overrides the roster directory and beats scratch.

AppContext.hostPlatform() returns macos on macOS, windows on Windows, and linux on every other host, including Android and iOS. The home directory is HOME, else USERPROFILE, else /.

Environment variables

Every variable the Kit reads. An empty value counts as unset for all of them except HOME and USERPROFILE in the Dart core, where an empty HOME is used as it is (the Rust crate skips an empty one). <PREFIX> is envPrefix, or the last segment of the id upper-cased with each character outside A-Z0-9 replaced by _ (com.slashbuilder.demo.render-queue gives RENDER_QUEUE).

By default the Kit reads the process environment. AppContext.open(manifest, env: {...}) replaces it with a map you supply, and then nothing from the real environment is read. That is how the tests in the App Context Kit repository stay isolated.

The fake Venue’s capacity is not an environment variable. It is the fakeCapacity parameter of AppContext.open (default 1). The Rust tests confirm that <PREFIX>_FAKE_CAPACITY, APP_CONTEXT_FAKE_CAPACITY and VENUE_FAKE_CAPACITY have no effect.

Token lookup, in order: VENUE_TOKEN; the file named by VENUE_TOKEN_FILE; <config>/venue-token. See spec section 5, item 2.

Modes

Any other value is ResolveError('bad-mode'). Only the variable that wins is checked: a garbage APP_CONTEXT_MODE is ignored when <PREFIX>_MODE is set. bad-mode is reported before missing-env.

Scratch is separate from mode. APP_CONTEXT_SCRATCH moves the files; mock swaps the services. They are independent, and tests normally set both. ctx.mode, ctx.isMock and ctx.scratch report what was resolved; ModeBadge shows it.

The config store

ctx.config is a ConfigStore over <config>/config.json. It is a flat JSON object that you read and write by key.

Writes are atomic: the content goes to config.json.tmp, which is then renamed over config.json. The file is pretty-printed JSON.

A missing file is an empty store, not a problem. A damaged file is one that is not valid UTF-8, not valid JSON, not a JSON object, or cannot be read. AppContext.open still succeeds, problem says why, a warning note is added, and every write is refused until you decide what to do. The file is never replaced silently (spec section 5, item 3).

setAsideCorrupt() is that decision. It renames the file to config.json.corrupt (replacing an older .corrupt copy), empties the store, clears problem and returns the new File. It returns null when nothing was damaged. The damaged content is kept, never deleted. If you want the person to choose, show them problem and call it from a button.

Each copy of an app keeps its own in-memory values and rewrites the whole file on set. Two copies running at once can overwrite each other’s keys, and the Kit takes no lock. This follows from reading the code; there is no test for it.

AppJsonFile and ctx.dataJson

ConfigStore is for the one settings file. AppJsonFile does the same careful handling for any JSON file your app owns, usually under ctx.dirs.data. ctx.dataJson('notes.json') returns the AppJsonFile for that name under the data directory, and AppJsonFile(file) wraps any File.

AppJsonRead has exists, value, problem and ok (true when problem is null, which includes the file not existing). The three outcomes:

A file that contains the JSON literal null is exists: true, ok: true, value: null; check exists to tell it from a missing file.

SessionSettings

SessionSettings(ctx.config) wraps a ConfigStore for UI code that should not throw when the file is damaged.

• While the file is healthy it is the store: set saves, get reads the file’s values.
• While the file is damaged, set keeps the value in memory for this session only and never touches the file. get returns that session value, then the file’s value, then the fallback. readOnly is true, so you can tell the person their change will not be kept.
• After setAsideCorrupt() on the store, readOnly is false and writes reach the file again. Values set during the damage are not written then.

SessionSettings.set never throws DamagedConfigError. It can still throw FileSystemException if the disk refuses a write.

Notes

ctx.notes is a List<AppNote>; each has a severity (NoteSeverity.info, warning or error) and text. ctx.noteTexts gives the texts only. Notes are plain data: adding one notifies nobody.

AppContext.open adds these:

AppContext.run adds an error note if closing fails after your function threw (see lifecycle). Your app can add its own; the notepad demo app adds a warning when a note file is damaged.

The Venue session

ctx.venue is a VenueSession. Its kind is local, fake or venue; isConnected is true only for venue; description is one sentence. The same calls work for all three, so app code does not branch. The wire details (the daemon’s HTTP API) belong to Venue, not to this Kit; spec section 3 and section 5, items 2, 6 and 7.

Refusals are typed. VenueRefused carries a kind: doesNotFit (HTTP 409; retrying later can succeed) or forbidden (HTTP 403). VenueRefused.retryable is true only for doesNotFit, and plainReason unwraps the daemon’s JSON error message. VenueUnavailable is everything else: a transport failure, a timeout, 401, 5xx. It carries the HTTP status when there was an answer.

withHoldWaiting retries forbidden only while holds() shows this consumer still has live holds, because the daemon uses the same status for “over your live-hold limit” and for “no grant”. This is a heuristic and the spec records its known failure: a consumer that holds something and lacks a grant waits the full maxWait for nothing. See spec section 7.

The three sessions:

• LocalVenue(why): no Venue. Work still runs. Holds exist in this process only, so two apps can both “hold” the same thing, and a second hold with the same name in one process is refused as doesNotFit.
• FakeVenue({capacity: 1}): in memory, one node. It refuses a hold when capacity holds are live, keeps a log of calls (hold <name>, start <name>, renew <name>, release <name>), and refuseNext(n, {kind}) makes the next n holds refuse. Use it in tests.
• RemoteVenue (Dart only): the daemon over HTTP with a bearer token. IoTransport does the HTTP; with VENUE_DAEMON_FINGERPRINT it trusts exactly one certificate and no authority. A fingerprint that is not 32 bytes of hex, or a certificate that does not match, is reported as VenueUnavailable with an explanation. Pass your own DaemonTransport to AppContext.open(transport: ...) to supply replies without a socket.

Lifecycle

Open

AppContext.open(manifest, {env, platform, home, transport, announce, heartbeat, fakeCapacity}) does these steps in this order:

1. Resolve (may throw ResolveError).
2. Create the five directories (may throw FileSystemException).
3. Open the settings; add a warning note if damaged.
4. Open the Venue session; add its note. In venue.mode: on, this step throws VenueUnavailable if Venue cannot be used. Nothing has been announced yet, so nothing is left behind.
5. Draw this copy’s instance id: eight random lower-case hex digits.
6. Write the roster entry and start the heartbeat, unless announce: false. If that fails, Venue is closed and the error is rethrown.

announce: false is for tests and tools that should not appear in the roster. heartbeat (default 5 seconds) is how often the roster entry is refreshed.

Run

AppContext.run(manifest, body, {...}) is open, then body(ctx), then close, also when body throws. If body throws, that error is what you get; a failure while closing is recorded as an error note instead of replacing it. If body returns and closing fails, run throws the AppCloseError.

run closes the moment body returns. That suits a command-line tool. It does not suit a Flutter app, where runApp returns at once; use AppContextKit.run there.

Close

ctx.close() does these steps in this order and always does all of them:

1. Stop the heartbeat and delete this copy’s own roster entry (only that file).
2. Run every ctx.onClose hook, last added first. A hook may be async; each is awaited. Peer hubs made by ctx.peerHub or ctx.startPeers are closed by a hook of their own, so they follow the same order.
3. Close Venue, last, so a hook can still use it.

If any step threw, the errors are raised together afterwards as one AppCloseError (its errors and stackTraces lists hold every failure). A failing hook never stops a later hook or the Venue close.

close() is idempotent. A second call, even a concurrent one, runs nothing again and returns when the first has finished. Only the first caller sees an AppCloseError.

Register hooks with ctx.onClose(() async { ... }). Typical uses are flushing unsaved edits and closing your own resources. The notepad demo app registers its flush hook after starting peers, so on quit the last keystrokes are saved and announced while the hub is still open.

What the Flutter companion adds

import 'package:app_context_kit_flutter/app_context_kit_flutter.dart'; gives you everything below. Widget-test helpers are in package:app_context_kit_flutter/testing.dart, kept apart so a release build does not link flutter_test.

AppContextKit.run

Future<AppContextKitSession> AppContextKit.run({
  required String manifestAsset,
  required Widget Function(AppContext ctx) app,
  // passed to AppContext.open:
  Map<String, String>? env, String? platform, String? home, DaemonTransport? transport,
  bool announce = true, Duration heartbeat = const Duration(seconds: 5), int fakeCapacity = 1,
  // for tests:
  AssetBundle? bundle, bool handleSignals = true, void Function(int code)? exitProcess,
  void Function(String message)? report,
  String errorTitle = 'This app could not start',
})

It ensures the Flutter binding, loads and validates the manifest from the bundle, opens the context, mounts AppContextScope(ctx:, child: app(ctx)) and wires the exit coordinator. If anything before that point fails, it mounts the startup error screen and returns a session whose error is set. If your app builder throws, the context is closed (so no roster entry is left) and the screen shows app-build-failed.

Other static members: AppContextKit.quit() (for a Quit button: closes once, then ends the process), AppContextKit.loadManifest(asset, {bundle}), AppContextKit.openContext(...) (the first half of run, without the lifecycle wiring) and AppContextKit.buildRoot(ctx, app).

AppContextScope

An InheritedWidget holding the context. AppContextScope.of(context) returns it or throws a FlutterError saying how to fix it; maybeOf returns null. Dependents rebuild only if a different context is swapped in, which happens in tests that relaunch.

The exit coordinator

ExitCoordinator funnels every way an app can end into one shutdown that calls ctx.close() at most once.

Nothing exits before the close has finished. A failing close never blocks the exit: the error is written to stderr, in full. There is no timeout and no “second signal forces it”; a hung onClose hook is a bug, and SIGKILL is the way out. A platform that cannot watch a signal (Windows has no SIGTERM) is skipped. On mobile, the onDetach close is best effort; the OS may not give it time. With SIGTERM and SIGINT sent to a built macOS app, the roster entry was gone afterwards. The exit paths are otherwise tested through injected sources, not through a real window close.

Widgets

The startup error screen and its codes

AppContextKitStartupError has a stable code, a message (what happened), a hint (what to do) and the original cause. AppContextKitStartupError.from(error) sorts any failure into one:

Sharing one context with a Rust core

A Flutter app with a Rust core must not open the context twice: it would be in the roster twice, under two instance ids, and two code paths would write one config.json. The Dart side opens the context (AppContextKit.run) and hands the Rust side a snapshot; the Rust side adopts it. The full rule is spec section 8.

Dart, the owner. ctx.snapshot() returns a map {schema, appId, instance, mode, scratch, dirs: {data, config, state, cache, runtime}, roster} you can jsonEncode and pass over the bridge. It has no secrets and no handles, and asking for it announces nothing.

Rust, the adopter.

#![allow(unused)]
fn main() {
let snapshot = ContextSnapshot::parse(&json_from_dart)?;   // strict: unknown schema, missing field, relative path are errors
let ctx = AppContext::adopt(&snapshot);                    // no roster entry, no heartbeat, no config.json written
let blocks = ctx.create_data_dir("blocks")?;               // directories under data and state only
let file = ctx.data_file("heads.json")?;                   // a path under data (no `..`, nothing created)
let theme: String = ctx.settings().get_or("theme", "light".into());  // read-only: `set` and `save` return Err(ReadOnly)
}

One owner per file. The owner (the side that opened the context) owns config.json and the roster entry. The adopter reads settings, never writes them, and owns the files it creates under data and state. A setting the Rust core wants changed is a request to the Dart side. After the owner changes a setting, ReadOnlySettings::reload() shows it.

The roster

The roster answers “who is running?”. Each running copy writes one JSON file into the shared roster directory (see directories) and refreshes it.

• File name: <ID>@<INSTANCE>.json, for example com.slashbuilder.demo.calc@1a2b3c4d.json. The instance is eight lower-case hex digits, drawn at random per opened context.
• Content: id, instance, name, version, pid, startedAt and heartbeatAt (UTC, ISO 8601). ctx.instance is this copy’s instance id.
• Heartbeat: the file is rewritten every 5 seconds (heartbeat:), through a temporary file and a rename. A failed heartbeat is recorded in RosterAnnouncement.lastError and does not stop the app.
• Two copies of one app are two files. Withdrawing one removes only its own.
• Stale: an entry whose heartbeatAt is more than 15 seconds old (staleAfter:) is stale. A copy that exited cleanly deletes its file. A copy that crashed leaves it behind, and the Kit never deletes it.

Reading it, on ctx.roster (or Roster(dir)):

A RosterRecord has file, status, entry (null when unreadable), id and instance. For an unreadable file, id and instance come from the file name, so it can still be attributed. Use scan() to tell a crash (stale) from “never ran” (no record) from a damaged file (unreadable). A file named <ID>.json with no instance part, from before instance ids existed, has a null instance. parseRosterFileName(name) splits a name; the id contains dots, so it splits at the last @.

The PID in an entry means something only on the same machine and for the same user. The roster does not check that the process is alive; it trusts the heartbeat.

Spec: section 4 and section 5, item 5. The spec asks whether the roster belongs in the Kit, in Venue or nowhere; the Kit keeps the smallest version so that use can answer.

Peers

Peers are other running copies of the same app for the same account. They are opt-in: list "peers" in kits, or ctx.peerHub and ctx.startPeers throw KitNotDeclared. This guide covers only how the context supplies them; the design is in spec sections 6 and 7.

• Who this copy is: ctx.peerAccount (APP_CONTEXT_ACCOUNT, else config account, else local), ctx.peerDevice (APP_CONTEXT_DEVICE, else config device; generated once as d- and eight hex digits and saved, or kept for this run only if the settings file is damaged) and ctx.instance. The first call to ctx.peerDevice writes device to the config file.
• Provider by mode: an explicit provider if you pass one to peerHub; in mock mode, an in-memory fake network (pass one FakePeerNetwork to several contexts to make them see each other); otherwise the loopback provider over ctx.peersDirectory (APP_CONTEXT_PEERS_DIR), which finds copies on one machine.
• ctx.startPeers(hook, {network, options}) builds and starts a hub and never throws for a runtime condition. It returns a PeersHandle at once: hub (null when peers are unavailable), started (a future that completes when the hub is open or has failed, never with an error), error (a sentence starting peers unavailable: ), isStarting, isRunning and changes (a broadcast Stream<void> that fires when the hub opens or fails and on every peer change). handle.hub?.broadcast(...) is always safe. KitNotDeclared is not swallowed: that is a bug in the app.
• ctx.peerHub(hook, {provider, network, authenticator, options}) builds a hub without starting it; call hub.start(). Use it for a custom provider or authenticator.
• The hook is an AppCoordination that you write: channel, hello(), admit(peer, theirHello), onPeer(peer, change), onMessage(from, message) and an optional attach(hub). The Kit never reads a payload; it carries bytes and an app-declared schema integer.
• PeerJson has helpers for JSON payloads: encode, decode (null on malformed input, never throws), fits, encodeWithin (throws PeerPayloadTooLarge), quiet and label. AppMessage.jsonBody decodes a message body.

Hubs are closed with the context. The default authenticator accepts every peer.

Errors

The Rust crate

rust/ implements spec sections 1, 2, 5 and 8 and passes the same conformance fixtures. Names differ by language convention.

Not in Rust: peers, SessionSettings, AppJsonFile and ctx.dataJson, withHoldWaiting and FakeVenue.refuseNext (Rust has with_hold and with_hold_opts), a remote Venue session, and everything in the Flutter companion.

The Kit’s Rust crate has no remote Venue session. It has LocalVenue and FakeVenue only. It still looks for a token (the lookup order and its errors are the same as in Dart), but a token that is found cannot connect to anything: with venue.mode auto the session is local and its description says the crate has no remote Venue session (a warning note), and with on the context fails to open. VENUE_DAEMON and VENUE_DAEMON_FINGERPRINT are not read.

Venue guide

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

How an app built on the App Context Kit asks Venue for a share of a machine’s resources, and what happens when Venue says no, goes away, or the app dies.

Venue is a resource broker: an app asks it for a hold (a reservation of some capability, for example “run a container”), and Venue grants it, refuses it, or takes it back when the lease runs out.

This guide covers the Kit’s Venue session in Dart and Rust. The Kit’s Rust crate has no remote Venue session: it has the local and fake sessions only, so everything below that talks to a daemon (the venue session, pinned TLS) is Dart only. The rules behind it are in spec/APP-CONTEXT.md (sections 3, 5 and 7). Each snippet below was run: against the mock session, against the local fallback, and against a throwaway Venue daemon (see Testing against a daemon). The daemon is not part of the App Context Kit repository.

Contents: the session · choosing a session · API · refusals · leases and orphans · pinned TLS · registering an app · local-only · testing against a daemon · open items

The session

ctx.venue is a VenueSession. It has three implementations, and app code calls the same methods on all of them.

ctx.venue.description is one sentence saying which you got, for example Venue: local (Venue not configured). The context also puts it in ctx.notes, with severity warning when Venue was expected but could not be used. Show it somewhere. The local session gives no cross-app protection, and the person using the app should be able to tell.

Hiding the difference is the point: the app has one code path. The cost is the local row above. The session cannot make a promise only a daemon can keep, so it tells you instead.

How a session is chosen

The manifest (app.json) has an optional venue block:

{
  "id": "com.slashbuilder.demo.render-queue",
  "name": "Render Queue",
  "version": "0.1.0",
  "kits": ["venue"],
  "venue": { "mode": "auto", "consumer": "render-queue" }
}

venue.mode is auto (the default), on or off. venue.consumer is the name Venue knows this app by. It defaults to the last segment of id, so dev.a.notepad and org.b.notepad would both default to notepad. Set it explicitly if that could clash.

The context decides in this order and stops at the first step that applies.

1. Mock mode (APP_CONTEXT_MODE=mock, or <PREFIX>_MODE=mock): always the fake session, whatever venue.mode says.
2. venue.mode is off: always local, with the description “Venue is off for this app”.

Steps 1 and 2 never look at the token or the daemon. Otherwise:

Checked against the code and run when this page was written: off, auto and on with no token, on and auto with a dead daemon, and a missing token file.

Token lookup

First match wins:

1. VENUE_TOKEN: the token itself.
2. VENUE_TOKEN_FILE: a path to a file holding the token.
3. <config>/venue-token, where <config> is the app’s config directory (see Platforms).

Whitespace around the token is trimmed. An empty variable counts as unset.

A named-but-missing token file is an error, not a fall-through. If VENUE_TOKEN_FILE is set and the file is missing, empty or unreadable, the Kit does not go on to try <config>/venue-token. It reports the problem (step 3 above). A typo in the variable shows up as an error instead of being hidden by another token source. VENUE_TOKEN still wins over a broken VENUE_TOKEN_FILE. The default file (item 3 of the lookup) is different: if it is missing or empty, that just means “not configured”.

Dart and Rust implement this the same way, with tests in both. In Rust a token that is found cannot connect to anything: with auto the session is local and its description says the crate has no remote Venue session, and with on the context fails to open.

$ APP_CONTEXT_SCRATCH=$(mktemp -d) VENUE_TOKEN_FILE=/tmp/nonexistent-token dart run bin/hold.dart
Venue: local (VENUE_TOKEN_FILE is set to /tmp/nonexistent-token but the file does not exist)
ran under a local hold named job-1

Other variables

The health check waits up to 2 seconds for an answer. Opening a connection to an unreachable address is capped at 5 seconds by the Dart transport, so it can delay startup. In auto mode that delay is followed by the local fallback.

The token belongs to one consumer name. Use the token issued for the name in venue.consumer. A token used under another name is refused by the daemon with HTTP 403 (forbidden, see Refusals); this was seen with a real daemon.

The health check needs no token, so a wrong token is not caught when the context opens. The session connects, and the first call fails with HTTP 401 as VenueUnavailable (status=401: holds: HTTP 401: {"error":{"code":"unauthorized",...}}, checked when this page was written).

The API

Dart (dart/app_context_kit/lib/src/venue/venue_session.dart) and Rust (rust/src/venue.rs) expose the same operations.

In Rust the calls block and release consumes the hold, so releasing twice does not compile. In Dart everything returns a Future.

A VenueNeed is a name, a contract class, and optional parameters. The name must be unique among your live holds. The render-queue demo builds it from a run id plus a job number, because a leftover hold with the same name is refused. The Kit cannot choose the contract class for you; only the app knows what kind of work it is asking for. The examples use container.run.v1.

Take a hold

Dart (runs unchanged in real, mock and with no Venue at all):

import 'package:app_context_kit/app_context_kit.dart';

Future<void> main() async {
  final manifest = AppManifest.fromJson({
    'id': 'com.slashbuilder.demo.render-queue',
    'name': 'Render Queue',
    'version': '0.1.0',
    'kits': ['venue'],
    'venue': {'mode': 'auto', 'consumer': 'render-queue'},
  });

  await AppContext.run(manifest, (ctx) async {
    print(ctx.venue.description);

    const need = VenueNeed(name: 'job-1', contractClass: 'container.run.v1');
    final result = await ctx.venue.withHold(
      need,
      (hold) async => 'ran under a ${hold.where} hold named ${hold.name}',
      leaseSeconds: 30,
    );
    print(result);
  });
}

Output with nothing configured, in mock mode, and against a daemon:

Venue: local (Venue not configured)
ran under a local hold named job-1

Venue: fake (mock mode)
ran under a fake hold named job-1

Venue: connected to http://127.0.0.1:7878 as render-queue
ran under a venue hold named job-1

To run it, depend on the package by path (it is not published) and set APP_CONTEXT_SCRATCH so the run writes to a temporary directory instead of your real app directories:

dependencies:
  app_context_kit:
    path: ../app-context-kit/dart/app_context_kit

APP_CONTEXT_SCRATCH=$(mktemp -d) dart run bin/hold.dart

Rust (app-context-kit = { package = "slashbuilder-app-context-kit", path = "../app-context-kit/rust" }; the crate has no remote Venue session, so this runs on the local session, or on the fake one in mock mode):

use app_context_kit::{
    AppContext, HoldOptions, Manifest, OpenOptions, RefusalKind, VenueError, VenueNeed,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let manifest = Manifest::parse(
        r#"{
            "id": "com.slashbuilder.demo.render-queue",
            "name": "Render Queue",
            "version": "0.1.0",
            "kits": ["venue"],
            "venue": { "mode": "auto", "consumer": "render-queue" }
        }"#,
    )?;
    // Reads the process environment (VENUE_TOKEN_FILE, APP_CONTEXT_MODE, ...).
    let mut ctx = AppContext::open(manifest, OpenOptions::default())?;
    println!("{}", ctx.venue.description());

    // Hold, start, renew in the background, release; also if the body panics.
    let need = VenueNeed::new("job-1", "container.run.v1");
    let outcome = ctx.venue.with_hold_opts(
        &need,
        30,
        &HoldOptions {
            on_lease_lost: Some(&|e: &VenueError| eprintln!("lease lost: {e}")),
        },
        |hold| format!("ran under a {} hold named {}", hold.kind, hold.name),
    )?;
    println!("{}", outcome.value);
    println!("renewals failed: {}", outcome.hold.renewal_failure_count());

    ctx.close()?;
    Ok(())
}

with_hold is the same without the options and returns only the body’s value. with_hold_opts also hands back the hold, so you can read after the call whether any renewal failed.

What withHold does

1. hold. If Venue refuses, the body never runs and nothing is released.
2. start. If that fails, the hold is released and the start error is what you see.
3. Renews every third of the lease (clamped to between 1 second and 1 hour), unless you pass renewEvery. Renewals never overlap, and none is sent after release.
4. Runs your body.
5. Releases, whether the body returned, threw, or (in Rust) panicked.

Two things are recorded, not thrown:

• A failed renewal sets hold.leaseLost (Rust: lease_lost()), counts in renewalFailures, and calls onLeaseLost once, on the first failure. The body keeps running. Stopping the work is your decision. leaseLost is latched by a single failed renewal, so one network blip sets it even if most of the lease is still left. Renewing does not update hold.expiresAt, so the hold object cannot tell you how much lease remains.
• A failed release never replaces your body’s result or error. It is kept in hold.releaseError.

The render-queue demo treats a lost lease as a failed job: it cancels the work, shows the reason, and offers Retry, because after a failed renewal the app cannot be sure Venue still counts the slot as its own. That is a policy choice for one app, not something the Kit does for you. It is tested with a session whose renewals fail. A daemon that stops answering mid-job was not tested.

The context does not release holds taken with hold() directly. ctx.close() closes the session and nothing else. Only withHold and withHoldWaiting release what they took. If you call hold() yourself, release it yourself.

Wait for room

withHoldWaiting retries a refused hold until it is granted or maxWait is used up.

import 'dart:async';
import 'package:app_context_kit/app_context_kit.dart';

Future<void> main() async {
  final manifest = AppManifest.fromJson({
    'id': 'com.slashbuilder.demo.render-queue', 'name': 'Render Queue', 'version': '0.1.0',
  });
  // Run with APP_CONTEXT_MODE=mock: the fake node has room for one hold at a time, so the second job has to wait.
  final ctx = await AppContext.open(manifest, fakeCapacity: 1);
  final venue = ctx.venue;

  final first = await venue.hold(const VenueNeed(name: 'first', contractClass: 'container.run.v1'));
  Timer(const Duration(seconds: 2), () => venue.release(first));

  try {
    final answer = await venue.withHoldWaiting(
      const VenueNeed(name: 'second', contractClass: 'container.run.v1'),
      (hold) async => 'got ${hold.name}',
      maxWait: const Duration(seconds: 10),
      retryEvery: const Duration(seconds: 1),
      onWaiting: (refusal, attempt) => print('refused (${refusal.kind.name}), attempt $attempt: ${refusal.plainReason}'),
      onLeaseLost: (hold, error) => print('lease lost on ${hold.name}: $error'),
    );
    print(answer);
  } on VenueRefused catch (e) {
    print('gave up: ${e.kind.name}${e.retryable ? " (could have been retried)" : ""}: ${e.plainReason}');
  } on VenueUnavailable catch (e) {
    print('Venue could not be asked: ${e.reason}');
  } on HoldWaitCancelled {
    print('cancelled');
  } finally {
    await ctx.close();
  }
}

$ APP_CONTEXT_MODE=mock APP_CONTEXT_SCRATCH=$(mktemp -d) dart run bin/wait.dart
refused (doesNotFit), attempt 1: the fake node is full
refused (doesNotFit), attempt 2: the fake node is full
got second

Rules:

• maxWait is required. Duration.zero makes it exactly withHold (fail fast).
• It retries doesNotFit always. It retries forbidden only while holds() shows this consumer still holds something. See the next section for why, and for when that is wrong.
• It never retries VenueUnavailable, and never retries an error thrown by your body.
• Waiting is counted in naps of retryEvery, not read from a clock, so it behaves under a test’s fake time. It naps at most maxWait ~/ retryEvery times and then rethrows the last refusal.
• cancel (a Future) ends the wait at once with HoldWaitCancelled. A hold granted in that same instant is released, not leaked.
• retryEvery must be positive.

Every waiting consumer polls Venue about once per retryEvery. Venue has no queue and no push, so there is no way to be told “there is room now”. In one earlier test with five waiting jobs against a real daemon, each job asked 15 to 20 times.

Rust has no with_hold_waiting. The refusal kinds are enough to write the loop yourself (see below), but the Kit does not ship it.

Refusals

Venue’s answer to hold is one of three things.

VenueUnavailable.status carries the HTTP status when there was one. A hold Venue no longer has shows up this way too, as a failed renewal. Against a real daemon, renewing a hold that had been released gave renew: HTTP 404 with the code not_held. The Kit treats 404 and 410 on release as “already gone”. What renew returns for a lapsed lease was not observed.

VenueRefused.retryable is true only for doesNotFit. VenueRefused.reason is the daemon’s raw response body (shortened to 300 characters). plainReason unwraps the daemon’s error.message so you can show a sentence. In Rust the message is hold: HTTP 403: <raw body>; there is no plain_reason.

Real answers from a daemon (consumer calc, live-hold limit 3):

refused: kind=forbidden retryable=false
reason: calc already holds 3 live placements (limit 3); many small holds are how a node gets starved

kind=doesNotFit retryable=true: Placement/clash-doc is already held; renew it, release it, or choose another name

status=401: holds: HTTP 401: {"error":{"code":"unauthorized","message":"a valid token is required"}}

Handling them

Rust, telling the three apart:

#![allow(unused)]
fn main() {
match ctx.venue.hold(&need, 30) {
    Ok(h) => ctx.venue.release(h)?,
    Err(e) => match e.refusal_kind() {
        Some(RefusalKind::DoesNotFit) => println!("full right now, retry later: {e}"),
        Some(RefusalKind::Forbidden) => println!("not allowed, do not retry: {e}"),
        None => println!("Venue could not be asked: {e}"),
    },
}
}

With the fake session at capacity this prints full right now, retry later: Venue refused (doesNotFit): the fake node is full.

The documented limitation: one code for the limit and for everything else

Venue answers its per-consumer live-hold limit with HTTP 403 and the code forbidden. It gives the same code for a missing grant, an observer token, and a token that does not match the consumer. There is no machine-readable reason, so the Kit cannot tell “you are over your own limit” (will clear when you release something) from “you may never do this” (will not).

The Kit’s current rule: forbidden is not retryable. withHoldWaiting adds a heuristic: if the daemon says forbidden and holds() shows this consumer still has live holds of its own, assume it is the limit and wait. If you have none, give up at once.

The heuristic is wrong in one case. A consumer that both holds something and lacks the grant for a new kind of work will wait the full maxWait for nothing and then get the real refusal. Checking costs one extra GET /v1/holds per retry. Verified against a real daemon: a consumer at its limit waits, is granted when one of its own holds ends, and gives up at maxWait with forbidden when nothing is released. The case where the heuristic is wrong was reasoned from the code, not run.

The fix belongs to Venue: a distinct reason, or status, for “over the live-hold limit”. The Kit would then drop the heuristic. See Open items.

Leases, crashes and orphan holds

A hold is a lease. Venue frees it when the lease runs out unless you renew it. That is what gives a dead app’s reservation back, and it is also why a crash costs you something.

What happens to a killed app’s holds. They stay live, and keep counting against the consumer’s limit, until the lease lapses. A clean exit releases them; kill -9 does not.

Measured against a real throwaway daemon, three running holds with a 6 second lease, the process killed with kill -9, then the app relaunched at once:

The spread is arithmetic. The app renews every third of the lease (2 s here), so the last renewal happened up to 2 s before the kill and the lease ends 4 to 6 s after it. The relaunched job then polled once a second, so it was granted at the next poll after the lapse.

With the Kit’s default lease of 300 seconds, the same crash keeps the consumer’s quota for up to five minutes. The render-queue demo’s 30 second lease (renewed every 10 s) would cost up to about 30 s.

So keep leases short. Choose the shortest lease that still survives your renewal being late by a couple of intervals. Tradeoff: a shorter lease means more renewal traffic and a smaller margin for a slow network or a stalled event loop. Do not take the default 300 seconds for work that lasts seconds.

A clean quit of the render-queue demo with three jobs running left no holds within 1.5 seconds. That works because the app’s close hook cancels its jobs and waits for each withHold to release. This was measured earlier and not re-run for this guide.

Finding orphans at startup

holds() lists this consumer’s own live holds. Subtract the ones this run took, and what remains came from a crash, or from another running copy of the same app.

import 'package:app_context_kit/app_context_kit.dart';

/// Holds this consumer still has that this run did not take: left by a crash, or taken by another copy.
Future<List<VenueHold>> findOrphans(VenueSession venue, String thisRunPrefix) async {
  return [
    for (final h in await venue.holds())
      if (!h.name.startsWith(thisRunPrefix)) h,
  ];
}

Future<void> main() async {
  final manifest = AppManifest.fromJson({'id': 'com.slashbuilder.demo.calc', 'name': 'Calc', 'version': '0.1.0'});
  final ctx = await AppContext.open(manifest, fakeCapacity: 3);
  final venue = ctx.venue;

  // Pretend an earlier run died holding this.
  await venue.hold(const VenueNeed(name: 'run-old-1', contractClass: 'container.run.v1'), leaseSeconds: 60);

  final orphans = await findOrphans(venue, 'run-new-');
  for (final h in orphans) {
    final left = h.expiresAt?.difference(DateTime.now()).inSeconds;
    print('orphan ${h.name}, lapses in about ${left}s');
    await venue.release(h);
  }
  print('after release: ${(await venue.holds()).length} holds');
  await ctx.close();
}

orphan run-old-1, lapses in about 59s
after release: 0 holds

This needs hold names that identify the run. The render-queue demo names holds rq-<runId>-<n>, shows “N holds from an earlier run still count against your quota”, lists each with its time to lapse, and offers a Release button.

Caveat: two running copies of one app share a consumer, so each sees the other’s holds as orphans. Check the roster (Roster.scan()) before telling the person a hold is stale; the demo does, and only changes its wording.

A second liveness clock

The roster (the presence file each app writes) and the Venue lease both answer “is this process still alive?”, with separate timers. After kill -9 they disagreed in an earlier measurement: Venue freed the hold in 6 s, the roster still said “running, stale” for up to 15 s. The Kit has not merged them. Treat the Venue lease as the answer for Venue, and the roster as the answer for “who is on this machine”.

Pinned TLS

By default the daemon is plain HTTP on the loopback interface. The bearer token travels in a header, in the clear. That is acceptable on 127.0.0.1. For any daemon on another machine, use HTTPS.

A self-signed daemon (venued --tls) prints its certificate fingerprint when it starts. Give the app that value:

VENUE_DAEMON=https://127.0.0.1:17879 \
VENUE_DAEMON_FINGERPRINT=sha256:<the 64 hex digits venued printed> \
VENUE_TOKEN_FILE=/path/to/token \
  dart run bin/hold.dart

How the pin works:

• With a fingerprint, no certificate authority is trusted at all. Every certificate is shown to a check, and only one whose SHA-256 equals the pin is accepted. There is no hostname check and no expiry check. The pin is the identity.
• Nothing is sent, not even the token, to a server that does not present the pinned certificate.
• These spellings are accepted: with or without sha256:, upper or lower case, with or without colons. They are normalised to sha256: and 64 lower-case hex digits. (Covered by dart/app_context_kit/test/transport_pin_test.dart; the Rust crate has no TLS client.)
• Without a fingerprint, Dart falls back to the system’s trusted roots, so a CA-signed daemon should work (not tested).

What a wrong pin looks like depends on how you reach the daemon.

Through AppContext.open, the health check fails first, and the context reports only that the daemon did not answer. In auto mode:

Venue: local (Venue did not answer at https://127.0.0.1:17879)

The note has severity warning. In on mode, open fails with “Venue is required but https://127.0.0.1:17879 did not answer”. This is the same text whether the pin is wrong, missing or malformed. The reason is not in the text.

Through a session you build yourself (RemoteVenue with IoTransport(fingerprint: ...)), the reason is in the error. These are the three VenueUnavailable messages from a real TLS daemon:

GET /v1/nodes: the daemon's certificate (sha256:0aded5...5974) is not the one that was pinned (sha256:abab...abab)
GET /v1/nodes: the daemon's certificate is not trusted by the system; a self-signed venued needs its fingerprint (VENUE_DAEMON_FINGERPRINT=sha256:...)
GET /v1/nodes: the fingerprint "nonsense" is not 32 bytes of hex (sha256:...)

(The first line has the fingerprints shortened here.) If an app shows “did not answer” and you expect TLS, build a RemoteVenue by hand as above to see the cause.

Plain http:// pointed at a TLS port fails quickly rather than hanging (well under 10 s in Dart).

Verification: dart/app_context_kit/test/venue_tls_test.dart (14 daemon-backed tests) runs against a daemon that serves a self-signed certificate. It skips unless VENUE_TLS_DAEMON, VENUE_TLS_FINGERPRINT and VENUE_TOKEN_FILE are set, and the case list is in Testing. The 14 passed when this page was written, against a throwaway daemon; they were not re-run for the public release. A further 4 Dart tests that need no daemon (transport_pin_test.dart) are part of the normal Dart run (365 passed, 7 skipped).

Registering an app with Venue

Venue only grants holds to consumers it knows about, and only for the kinds of work they have been granted. Today, introducing an app to a daemon takes four manual steps. These are the four a throwaway registry needed for each demo app, written as the Venue project’s own command line (that command line is not part of the App Context Kit repository):

1. Add an entry for the consumer to the registry’s authority.yaml, with a class, a priority cap and a live-hold limit: - {name: render-queue, class: Consumer, maxPriority: 100, maxLiveHolds: 3}
2. venue --as declared principal add render-queue
3. venue --as declared grant use container.run.v1 --principal render-queue
4. venue --as declared token add render-queue --manager render-queue, which prints the token.

Steps 2 and 3 need an operator with authority over the registry; the commands pass --as declared on steps 2 to 4; what that flag does is described in Venue’s own documentation. Grants are authority: they decide what a program may ask the machine to do.

The Kit cannot do this for the app, and should not. An app that could grant itself the right to run work would make the limit meaningless. So “Venue wired in from the first launch” cannot be done by the app on its own. The app can only ship its manifest and wait for someone with authority to provision it.

What a provisioning step would need (none of this is built; it is a description of the gap):

• Input. The manifest’s venue block gives the consumer name. It does not say which contract classes the app will ask for. Today that is in the app’s code (container.run.v1 above). The manifest could declare it, so the provisioner can build the grants. The Kit does not.
• Decisions only an operator can make. The priority cap and the live-hold limit (3 in the demo registry).
• Authority. Something that holds the right to edit the registry and run steps 2 to 4: an installer, an app store, or a person. Which of these runs it is undecided.
• Delivery. The token has to reach the app: a file at <config>/venue-token, or an environment variable set by whatever launches it. Under the macOS sandbox, a token file outside the app’s container cannot be read; see Platforms.
• Repeatability. Running it twice on upgrade should not fail or duplicate, and uninstalling should remove the grant. Not designed.

Running without Venue

Venue is optional. An app can run entirely local:

• Set "venue": { "mode": "off" } and nothing ever connects. The session is local with the description “Venue is off for this app”.
• Leave the mode at auto and configure nothing. The session is local (“Venue not configured”). If a daemon is configured later, the same binary connects.

What local does:

• Holds exist only in your process. A second hold with the same name in the same process is refused with doesNotFit. Different names are all granted, with no limit. In an earlier test, five render jobs ran at once under local, where a real daemon with a limit of 3 would have run three.
• renew does nothing, nodes() is empty, and holds() lists this process’s holds.
• Nothing protects against another app, or another copy of yours, using the same resource at the same time.

If your app can wait for capacity, the people using it get the right behaviour only on a venue session. On local, say so (the description already does).

Testing against a daemon

The App Context Kit repository does not contain a Venue daemon and does not ship a script that starts one. To run the real-daemon tests, start any compatible daemon yourself and give it what the tests expect:

• A consumer named calc, granted container.run.v1, with a limit of 3 live holds (the limit test relies on it). Introduce it with the four registration steps above.
• A token file for that consumer.
• A node whose heartbeat stays fresh. A daemon whose node was last probed about two minutes ago refuses every hold with 409 does_not_fit (“the node’s heartbeat has lapsed”); if you write your own setup, keep the node probed (for example every 30 seconds).
• Plain HTTP on the loopback address is fine for these tests. TLS is only for the pinned-TLS tests.
• The container.run.v1 capability was chosen because the machine the tests were written on has Docker and no GPU. Whether it needs Docker, and any other contract class, was not tested.

Then:

cd dart/app_context_kit
VENUE_DAEMON=http://127.0.0.1:7878 \
VENUE_TOKEN_FILE=<path to calc's token file> \
  dart test test/venue_real_test.dart

Without VENUE_TOKEN_FILE the tests skip with a message, and a skipped run proves nothing about the daemon. When this page was written the file passed 5 of 5 tests against a throwaway daemon; that was not re-run for the public release. The Rust crate has no real-daemon test, because it has no remote session.

The pinned-TLS tests are separate; see Testing.

Open items and who owns them

Coordination guide: copies of one app talking to each other

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

This guide is for a developer who wants two running copies of the same app to find each other, agree on who is there, and exchange messages. It covers the peer layer of the App Context Kit: what the Kit does, what you write, how to start it, and what it does not do.

Status, so you know what you are reading. The peer layer is implemented in the Dart core (dart/app_context_kit/lib/src/peers/). Two providers are built: an in-memory fake network (tests and mock mode) and a loopback provider (copies on one machine). No provider for a real network exists yet, and the Rust implementation has no peer code. Every example in this guide that has a file under examples/coordination/ runs as a test; the commands are in Run the examples.

Contents: the model · the scope key · the hook · starting a hub · the hub API · providers · the envelope · ordering and loss · delivery · backpressure · PeerJson and size limits · testing · three worked patterns · what the hook does not give you · real transports

1. The model

The Kit finds, authenticates, connects and routes. Your app supplies a hook and decides what the messages mean. The Kit never reads the payload.

“Never reads the payload” is literal. A message carries a kind string and a schema integer that you choose, and an opaque byte payload. The Kit routes on its own header (see the envelope) and hands you the bytes.

You get one hub per channel. A hub is one PeerHub object that owns the links to every other copy of your app. An app with several unrelated conversations either starts one hub per conversation or writes one hook that routes by kind prefix (a sample is MuxHook in sample_hooks.dart).

2. The scope key

Two copies are peers only if they have the same account and the same app id. Anything else is never offered to your hook and never admitted.

A peer is identified by (device, instance), the PeerId. Two copies on one device are two peers. local is the account of a machine that has no household account; it is a placeholder until something issues a real one.

Scope is checked in three places, so a bug in one does not open the others:

• The provider does not list candidates from another scope and refuses to dial or accept one. The loopback provider also keeps one directory per account and app, so it never reads another scope’s files.
• The hub drops a candidate or an incoming link whose claimed scope differs from its own, and counts it in hub.stats.scopeViolations.
• Every frame carries account and app in its header. A frame with a different scope cuts the link.

ping_test.dart checks this: a copy of the app, a copy with another app id and a copy with another account share one network, and none of the three sees any peer.

Scope is a name, not a credential. The default authenticator (OpenAuthenticator) accepts every peer in scope, and no per-app credential exists yet. Treat the scope key as a way to keep copies of different apps and accounts apart, not as access control. The authenticator is the seam where a real check goes; see per-app credentials. A security review is pending; details withheld.

Identifier rules for the loopback provider: account, app, device and instance become directory and file names, so they may contain only letters, digits, ., _ and -, may not start with ., and may be at most 128 characters. Anything else makes the hub fail to open, which ctx.startPeers reports in handle.error.

3. The hook: five jobs

A hook is a subclass of AppCoordination (coordination.dart). It has five jobs and one convenience:

acceptReadOnly only sets peer.readOnly. The Kit does not filter anything for a read-only peer, and the other side is not told. You decide what read-only means, for example by ignoring that peer’s write messages in onMessage.

A hook must not throw. If it does, the hub catches the error, counts it in hub.stats.hookErrors, passes it to PeerHubOptions.onHookError if you set one, and carries on.

A complete hook: “ping”

This is the whole of a working app’s coordination code. Any copy can ping another, and the other answers with its device name. It is examples/coordination/lib/ping_hook.dart, unchanged.

import 'dart:async';

import 'package:app_context_kit/app_context_kit.dart';

/// A complete coordination hook: the five jobs, and nothing else.
///
/// "ping": any copy can ask another copy "are you there?", and the other copy answers with its device name.
class PingHook extends AppCoordination {
  PeerHub? hub;

  /// Peer changes as the Kit reported them, e.g. "ready desktop".
  final List<String> events = [];

  /// Messages this hook did not understand. A hook counts these instead of throwing.
  int ignored = 0;

  // 1. Which conversation inside the app this hook owns.
  @override
  String get channel => 'ping';

  // The Kit hands the hook its hub once, from PeerHub.start().
  @override
  void attach(PeerHub hub) => this.hub = hub;

  // 2. What to tell a peer when a link opens. Any JSON-encodable value.
  @override
  Object? hello() => {'proto': 1};

  // 3. Whether to talk to this peer, given what it said in its hello.
  @override
  FutureOr<Admit> admit(Peer peer, Object? theirHello) =>
      theirHello is Map && theirHello['proto'] == 1
          ? const Admit.accept()
          : const Admit.reject('ping protocol 1 only');

  // 4. A peer was found, became ready, or was lost.
  @override
  void onPeer(Peer peer, PeerChange change) =>
      events.add('${change.name} ${peer.id.device}');

  // 5. The app's meaning lives here. Answer a ping; count anything else.
  @override
  void onMessage(Peer from, AppMessage message) {
    if (message.kind == 'ping' && message.schema == 1 && message.requestId != null) {
      PeerJson.quiet(hub!.reply(message, PeerJson.encode({'pong': hub!.device}), schema: 1));
    } else {
      ignored++;
    }
  }

  /// Ask [peer] if it is there. Returns the name it answered with, or null for an answer in the wrong shape.
  /// Throws a PeerError (PeerTimeout, PeerLost, ...) if there is no answer.
  Future<String?> ping(Peer peer) async {
    final reply = await hub!.request(peer, PeerJson.encode({'n': 1}), kind: 'ping', schema: 1);
    final body = reply.jsonBody;
    return body is Map && body['pong'] is String ? body['pong'] as String : null;
  }
}

And this is how two copies of it run in one test process. Each copy is an AppContext in mock mode; they share one FakePeerNetwork. The manifest must list "peers" in kits, or ctx.startPeers throws KitNotDeclared. From ping_test.dart:

/// The manifest must list "peers", or ctx.startPeers throws KitNotDeclared.
const manifestJson = {
  'id': 'dev.example.ping',
  'name': 'Ping',
  'version': '0.1.0',
  'kits': ['peers'],
};

/// One copy of the app: its own AppContext, in mock mode, on the shared fake network.
Future<({AppContext ctx, PingHook hook, PeersHandle peers})> copy(
  String device,
  FakePeerNetwork network, {
  Map<String, Object?> manifest = manifestJson,
  String account = 'home',
}) async {
  final ctx = await AppContext.open(
    AppManifest.fromJson(manifest),
    env: {
      'APP_CONTEXT_MODE': 'mock',
      'APP_CONTEXT_SCRATCH': '${scratch.path}/$device',
      'APP_CONTEXT_DEVICE': device,
      'APP_CONTEXT_ACCOUNT': account,
    },
    platform: 'linux',
    home: '/unused',
    announce: false,
  );
  final hook = PingHook();
  final peers = ctx.startPeers(hook, network: network);
  await peers.started;
  return (ctx: ctx, hook: hook, peers: peers);
}

test('two copies of one app find each other, ping, and get a pong', () async {
  final network = FakePeerNetwork();
  final laptop = await copy('laptop', network);
  final desktop = await copy('desktop', network);

  expect(await until(() => laptop.peers.hub!.readyPeers.isNotEmpty && desktop.peers.hub!.readyPeers.isNotEmpty), isTrue);

  final desktopFromLaptop = laptop.peers.hub!.readyPeers.single;
  expect(desktopFromLaptop.id.device, 'desktop');
  expect(await laptop.hook.ping(desktopFromLaptop), 'desktop');

  final laptopFromDesktop = desktop.peers.hub!.readyPeers.single;
  expect(await desktop.hook.ping(laptopFromDesktop), 'laptop');

  // The hook heard found, then ready, in that order, on both sides.
  expect(laptop.hook.events, ['found desktop', 'ready desktop']);
  expect(desktop.hook.events, ['found laptop', 'ready laptop']);
  expect(laptop.hook.ignored + desktop.hook.ignored, 0);

  await laptop.ctx.close();
  await desktop.ctx.close();
});

until(...) is a small polling helper defined at the top of that file. Discovery and the handshake are asynchronous, so the test waits for readyPeers instead of sleeping.

Run the examples

cd docs/examples/coordination
dart pub get
dart test

The package depends on app_context_kit by path and on nothing else except test. It contains three test files: ping_test.dart (the example above), hub_behaviour_test.dart (tests for the behavioural claims in this guide: sequence numbers, loss, outbox, size caps, timeouts, admit and reject, hello) and loopback_test.dart (two copies over real TCP and announcement files).

4. Starting a hub

Declare the Kit in the manifest, then call ctx.startPeers with your hook.

{ "id": "dev.example.ping", "name": "Ping", "version": "0.1.0", "kits": ["peers"] }

ctx.startPeers(hook, {network, options}) builds a hub and starts it. It returns a PeersHandle at once, before the hub has opened, and it does not throw for a runtime condition. If the peers directory cannot be created or the provider fails to open, the handle carries the reason and your app keeps working alone.

KitNotDeclared is the one exception that startPeers does throw: forgetting to list "peers" is a bug in the app, not something that happens to a person. The hub is closed with the context (ctx.onClose), so you do not close it yourself.

The provider is chosen from the mode, in this order:

1. In mock mode (<PREFIX>_MODE=mock or APP_CONTEXT_MODE=mock): the FakePeerNetwork you pass as network:, or a private one if you pass none. A private network contains only your own context, so to have two contexts find each other in a test, pass the same FakePeerNetwork to both. Apps do this by taking a network: parameter in their own production code; the demo apps’ constructors show the shape.
2. Otherwise: a LoopbackProvider over the peers directory.

Building a hub writes a generated device value into the app’s config.json the first time, unless APP_CONTEXT_DEVICE is set. Two copies that share a config directory therefore share a device id and differ only by instance. Give each copy its own APP_CONTEXT_DEVICE, or its own config directory.

In a Flutter app, PeersIndicator.forHandle(handle) from package:app_context_kit_flutter/app_context_kit_flutter.dart shows “This copy: laptop #3fa2”, the number of peers, a chip for each ready copy, and “Peers: off (reason)” when handle.error is set. It follows handle.changes itself.

ctx.peerHub(hook, {provider, network, authenticator, options}) is the lower-level call. It builds the hub and registers it for closing with the context, but does not start it: you await hub.start() yourself and handle the failure. Use it when you need your own provider, a custom authenticator, or a specific LoopbackProvider configuration. It also throws KitNotDeclared when "peers" is missing.

5. The hub API

PeerHub (hub.dart) is the management interface.

kind defaults to "msg" and schema to 0. kind is 1 to 256 characters and may not start with kit.; schema is 0 to 2,147,483,647. A bad value is an ArgumentError.

Peers and their states

A Peer is read-only to you. Its state is one of found, connecting, ready, rejected or lost. found means the provider announced it; connecting means a link is being opened or the handshake is running; ready means both sides admitted each other. peer.hello is the decoded hello once received, and peer.rejectReason and peer.lostReason say why a peer ended (goodbye, link closed, hub closed, withdrawn, and others).

A Peer object is never reused. A copy that goes away and comes back is a new Peer with the same PeerId. Keep the PeerId if you need to find the peer again; calling send with a Peer that has been replaced throws PeerNotAvailable. A rejected peer is not redialed until the provider withdraws it and announces it again.

A rejection shows up as a lost event on both sides, with peer.state == rejected. hub_behaviour_test.dart checks it: one side’s admit rejects with "proto 2 only", and the other side’s peer ends with rejectReason == 'rejected by peer: proto 2 only'.

Errors

All failures in this layer are subclasses of PeerError.

If you call send without awaiting it, attach a handler or use PeerJson.quiet(...). A late failure of an un-awaited future is an uncaught async error.

6. Providers

The hub talks to two small interfaces, PeerProvider and PeerLink (provider.dart), so the same hook runs over any provider. A provider announces this copy, reports other copies in the same scope (discover()), dials one (connect), and hands over links that others dialed (incoming). A link is one ordered, message-framed connection: one send arrives as one inbound event.

Fake network: tests and mock mode

FakePeerNetwork (fake_network.dart) is an in-memory network. Several hubs join one network, each through its own provider. It enforces the scope key itself and lets a test change the world while it runs:

For deterministic time, build a PeerHub directly with a ManualPeerClock (see World in support.dart). ctx.startPeers and ctx.peerHub do not take a clock, so hubs they build run on real time.

Loopback: copies on one machine

LoopbackProvider (loopback_provider.dart) connects copies that run on one machine, as processes. It needs nothing but a shared directory.

Announcement files. Each copy listens on a TCP port on 127.0.0.1 (never a routable address; the operating system picks the port) and writes one file:

<peers dir>/<account>/<app id>/<device>@<instance>.json

with these fields. This file was written by a run of the stopwatch probe; loopback_test.dart asserts the key set and the path.

{"account":"local","app":"com.slashbuilder.demo.stopwatch","device":"desktop","instance":"48e784da","port":52367,"pid":63779,"beat":1792850562108}

beat is a wall-clock time in epoch milliseconds. The file is written to a temporary name and renamed, so a reader never sees half a file.

Finding each other. Each provider reads the directory for its own account and app every 100 ms (pollInterval). A file naming another scope than its directory is ignored. A candidate is offered if its file is under 4 KiB, parses, has a valid port, and has a recent beat.

Connecting. Only the copy with the lower PeerId dials, so two copies never open two links. A frame on the wire is a 4-byte big-endian length followed by the envelope bytes. The dialer’s first frame is a preface naming who it claims to be; the accepting side closes the socket if the preface names another scope or is garbage, before the hub sees a link. A dial that fails is retried after 0.2 s, doubling to a 5 s ceiling, at most 10 attempts; after that the hub waits for the provider to announce the copy again.

Beat, staleness and reaping. This is how a crashed copy disappears.

A file with no beat (one made by hand) is aged by its modification time. The provider does not check whether the pid in the file is alive: a pid means nothing across pid namespaces, can be reused, and Dart has no portable check that does not spawn a process. The cost of the beat is one small write per second per process.

What a crash looks like. On a clean close() the copy sends kit.bye, deletes its file, and the other copy sees lost with reason goodbye; it is not redialed. If the process is killed, the operating system closes its sockets, so the survivor sees the link drop at once. But the file is still there and still has a recent beat, so the dead copy is still announced and the survivor sees it as found again. It stays that way until the beat is older than staleAfter. One death is therefore three events: lost, found, lost.

Measured today on macOS (Apple silicon) by dart test test/peers/two_process_test.dart -r expanded in dart/app_context_kit, which starts real operating-system processes over one temporary directory and kills one with SIGKILL. Two runs, one for each side of the dial rule:

The same test passes in a Linux container (numbers in Platforms). Before the beat was added, the dead copy stayed found for ever. The found after the first lost is a known rough edge: the hub cannot yet tell “link dropped” from “gone” earlier than the beat allows. Make onPeer idempotent, and do not assume found cannot follow lost.

Run as two macOS debug builds of the stopwatch, notepad and minesweeper apps, the second copy’s announcement appeared 257 to 439 ms after launch and a TCP link 31 to 35 ms after that. These figures are recorded in the apps’ notes; they were not re-run for this guide.

Tuning. ctx.startPeers and ctx.peerHub take PeerHubOptions but not the loopback timings. To change staleAfter or announceEvery, build the provider yourself and pass it: ctx.peerHub(hook, provider: LoopbackProvider(directory: ..., staleAfter: ...)).

Limits.

• One machine, one user. The loopback provider has no encryption and no authentication. Use it for same-user coordination on one machine and for tests, not across users or trust boundaries.
• On macOS, a sandboxed app has its own container. The peers directory (and the roster) must be reachable by every copy: the default location is inside the container and works for copies of one app; a path outside the container leaves the app working alone. The sandbox entitlements com.apple.security.network.client and com.apple.security.network.server are both needed to dial and to listen. Flutter’s macOS template grants only network.server in Debug and neither in Release; the notepad and minesweeper projects add both. With only server, the recorded observation was that two sandboxed copies listen but never connect, with nothing in the log. PLATFORMS.md has the full table; the observation was not re-run for this guide.
• Environment variables you set in a shell reach an app you start from that shell. They do not reach one started from Finder or the Dock.

7. The envelope

Every frame between two copies is one envelope: a header the Kit reads and a payload it does not (envelope.dart). The wire form is UTF-8 JSON with the keys in a fixed order:

{"v":1,"account":"a","app":"dev.x","channel":"default","from":{"device":"d","instance":"i"},
 "seq":1,"kind":"msg","schema":0,"rid":7,"payload":"<base64>"}

Unknown extra keys are ignored, so a later version can add fields.

The outer cap is 1 MiB. A payload over 1,048,576 bytes is an EnvelopeError on send. The largest frame the decoder will look at is 1,406,296 bytes (the base64 of a full payload plus 8,192 bytes of header room). That is the Kit’s limit. A provider may carry less; see real transports.

Reserved kinds. Kinds that start with kit. belong to the Kit, and your app cannot send them (ArgumentError). The Kit uses these:

An unknown kit. kind from a peer is ignored. kit.reply is consumed by the hub and completes the request future; it never reaches onMessage.

Request and reply. request gives the outgoing frame an rid from a per-hub counter that starts at 1. The other side’s onMessage sees it as AppMessage.requestId; hub.reply(message, payload) sends a kit.reply with the same rid. The hub matches replies to waiting requests by (peer, rid), so the Kit’s correlation does not depend on a transport’s own message ids. A reply that is late or unknown is ignored. A request that times out cancels its frame if the frame has not been written yet.

8. Ordering and loss

seq numbers the frames in one direction of one link. It starts at 1 on every new link, so a reconnect restarts it. It counts the Kit’s own frames too. kit.hello, kit.auth and kit.ready take 1, 2 and 3, so the first message your app receives from a peer has seq 4. A kit.reply or kit.bye takes a number as well.

The hub delivers each peer’s frames to you in seq order, once:

• A frame that arrives early waits in a reorder buffer of 16 frames.
• A gap that is not filled within 500 ms, or a buffer that overflows, is skipped. The hub counts it in hub.stats.gapsSkipped and delivers what it has.
• A frame at or below the last delivered seq is a duplicate or a late arrival after a skip, and is dropped (duplicatesDropped).
• A peer that floods more than 256 undelivered frames on one link has the link dropped.

You see loss as a jump in AppMessage.seq. hub_behaviour_test.dart drops the second of three messages on the fake network. The receiver gets two:

expect(seqs, [4, 6]);

A jump says that one or more frames from that peer were skipped. It cannot say which: the lost frame might have been a reply. If you need to detect a lost message precisely, put your own counter or version in the payload.

Ordering is per sender. The Kit gives you no order between messages from two different peers.

9. Delivery

Delivery is best effort.

• send completes when the transport took the frame, not when the peer received or applied it. hub_behaviour_test.dart sets the fake network to drop every frame and shows that send still completes without error.
• If the link ends before a queued frame is written, the send future fails with PeerLost. Queued messages are dropped when the peer is lost.
• There is no retry and no replay. A message sent before a peer exists is not kept for it: a broadcast with nobody ready returns an empty sent list, and a copy that arrives later never sees it.
• send to a peer that is found or connecting is queued and written once the peer is ready. App frames from a peer are not delivered to you before it is ready.
• request/reply is the one acknowledgement the Kit has: a reply proves the other hook ran. A request that gets no reply fails with PeerTimeout (the other hook may still have run).

If you need “it was applied”, build it from a reply. The minesweeper and notepad apps did; the stopwatch accepted a possible duplicate instead. See the patterns.

10. Backpressure

Each peer has an outgoing queue of messages not yet handed to the transport. It holds at most 256 messages or 8 MiB of payload (PeerHubOptions.outboxMessages, outboxBytes). When it is full, send, request and reply fail with PeerOutboxFull on the returned future, and broadcast reports that peer in failed. The Kit does not drop an older message to make room, because only your app knows what is safe to drop.

What to do depends on the message. For state (“the current note”, “the timer”), send the newest value and let PeerOutboxFull mean “skip this one; the next change carries the state anyway”. For events that all matter, await each send before the next. hub_behaviour_test.dart sets outboxMessages: 2, sends ten messages without awaiting, and counts the PeerOutboxFull failures.

11. PeerJson and size limits

Apps that speak JSON need the same few helpers, so they are in the Kit (PeerJson, peer_json.dart):

decode returns null both for malformed input and for the JSON literal null. Send an object ({"v": 1}) rather than a bare value when you must tell “nothing” from “malformed”.

The Kit does not know your provider’s payload limit. You pass it. The fake and loopback providers carry up to the 1 MiB envelope cap; a Hearth transport would carry 64 KiB minus the Kit’s header. If your app may run on a smaller transport, size to the smaller one with fits or encodeWithin. Keep the hello small as well: it travels in one frame like any other message, so carry a version or a digest, not the data.

There is no second envelope inside the payload. The Kit envelope already has kind and schema, so switch on message.kind, check message.schema, then read the body with message.jsonBody. The three coordinating demo apps do.

12. Testing coordination

Run two copies in one process. Open two AppContexts in mock mode (APP_CONTEXT_MODE=mock), give each its own APP_CONTEXT_DEVICE, call ctx.startPeers(hook, network: network) with one shared FakePeerNetwork, wait for readyPeers, and drive the hooks. The example in section 3 is this setup. The demo apps use it for their hook tests, including a hostile peer that sends malformed JSON, wrong types and an unknown schema, and tests that cut the network with partition/heal.

For tests that depend on timing (reorder timeout, request timeout, redial backoff), build the PeerHub directly with a ManualPeerClock so the test controls time. That is how the Kit’s own tests in dart/app_context_kit/test/peers/ work. For a real process boundary, two_process_test.dart starts operating-system processes over a shared temporary directory.

Count what your hook ignores. The demo hooks keep an ignored counter, and their tests assert it after sending garbage.

13. Three worked patterns

The three demo apps that use peers (stopwatch, notepad and minesweeper, in The Kit Book) each used the hook for a different kind of meaning. The snippets below are copied from their code.

A signal: “the timer finished” (stopwatch)

The stopwatch app shares one countdown between copies. This pattern is only the announcement: when the countdown ends, exactly one copy should say so, and the others should show “finished on laptop #3fa2” instead of announcing it again.

Which copy announces is the app’s decision, not the Kit’s. Every start, pause or reset bumps a stamp, a pair of a revision number and the id of the copy that made the change (its “writer”). The rule: the writer of the current stamp announces. If the writer is no longer among hub.readyPeers, the lowest-numbered live copy announces. Any other copy waits for the timer.finished message and, if it has not arrived after a 2-second grace, announces itself. The announcement is a broadcast with a kind and schema the app chose. A late joiner is not told what it missed; the countdown state rides in its hello() instead (see the replay entry in section 14).

Delivery is best effort, so the announcement can be lost. The app does not try to prevent that with an acknowledgement; it prevents silence instead. Under a partition two copies may both announce. The app chose “at least once” on purpose, and the comment at the top of the file says so. It accepts a possible duplicate announcement rather than a possible missing one.

The Kit contributes the list of ready peers (hub.readyPeers, used to decide who is alive), the broadcast, and the guarantee that one peer’s messages arrive in order. The stopwatch also replicates the countdown itself with a last-writer-wins stamp; that is a second use of the same hook, and this section covers only the signal. From the stopwatch demo app’s lib/coordination/shared_timer.dart:

/// This copy's countdown ran out. Announce if we are the announcer, else wait for the announcer.
void countdownEnded(CountdownModel done) {
  if (_told == stamp) return;
  if (_isAnnouncer()) return _announce(done);
  final at = stamp;
  _grace = Timer(takeoverGrace, () {
    if (_told != at && stamp == at) _announce(done);
  });
}

bool _isAnnouncer() {
  final h = hub;
  if (h == null || stamp.rev == 0 || stamp.writer == _me) return true;
  final ready = h.readyPeers;
  if (ready.any((p) => p.id.toString() == stamp.writer)) return false; // the owner is alive: it announces
  return ready.every((p) => h.id.compareTo(p.id) < 0); // owner gone: the lowest live copy does
}

void _announce(CountdownModel done) {
  _told = stamp;
  final label = formatMs(done.durationMs, tenths: false);
  onFinished(Finished(label: label, by: hub?.id ?? const PeerId('local', 'local'), local: true));
  final h = hub;
  if (h != null) {
    final ended = _stateJson(done)..['label'] = label;
    PeerJson.quiet(h.broadcast(PeerJson.encode(ended), kind: 'timer.finished', schema: 1));
  }
}

A sync with an app-defined conflict rule (notepad)

The notepad app keeps the same notes on every copy. The Kit carries bytes between copies; it has no store, no merge and no idea what a note is. The hook file is 29 lines and forwards each of the five jobs to a sync engine, about 500 lines in note_sync.dart, which is the app’s own.

The central choice is what happens when two copies edit the same note while apart. The engine tracks a version vector per note, so it can tell “you are behind” from “we both edited”. A timestamp cannot tell those apart: it always orders two edits, and one edit silently loses. When the versions are concurrent, the engine keeps both: the version that sorts later (by updatedAt, then device, then a content hash) keeps the note’s title and place, and the other becomes a new note titled <title> (conflict from <device>). The rule is symmetric and total, so both copies reach the same decision without talking, and they derive the same id for the new note, so they converge instead of duplicating. The person is told what happened. Edit beats delete: a delete never destroys a concurrent edit. Identical text on both sides is not a conflict.

Content moves by pull. Small sync.have messages say “note X is at version V”. A copy that is behind asks with request, one part at a time, because request/reply is the only acknowledgement the Kit has. A late joiner puts only a digest in its hello(); if the digests differ, each side sends its index and the one that is behind pulls.

None of this is in the Kit, by design: the Kit does not interpret payloads. The hook is the right shape for meaning; it is not a sync framework. From the notepad demo app’s lib/coordination/note_sync.dart:

void _applyRemote(Note remote, Vv rvv, String rby) {
  final id = remote.id;
  if (host.isDamaged(id)) return;
  host.flushNote(id);
  final local = meta[id];
  final order = local == null ? VvOrder.before : local.vv.compare(rvv);
  try {
    switch (order) {
      case VvOrder.equal || VvOrder.after:
        return;
      case VvOrder.before:
        _put(remote, rvv, rby);
      case VvOrder.concurrent:
        final mine = host.note(id);
        if (local!.deleted || mine == null) {
          _put(remote, local.vv.join(rvv), rby); // edit beats delete
        } else if (hashNote(mine) == hashNote(remote)) {
          meta[id] = Meta(local.vv.join(rvv), by: local.by, hash: local.hash); // same text on both: only the histories merge
          _save();
          _announce([id]);
        } else {
          _conflict(mine, local, remote, rvv, rby);
        }
    }
  } on FileSystemException catch (e) {
    report('Could not store a synced note: ${e.message}. It will be tried again at the next sync.');
  }
}

/// Does A sort after B? Symmetric and total, so both copies pick the same winner with no conversation.
bool _beats(Note a, String aBy, Note b, String bBy) {
  final t = a.updatedAt.compareTo(b.updatedAt);
  if (t != 0) return t > 0;
  final d = aBy.compareTo(bBy);
  return d != 0 ? d > 0 : hashNote(a).compareTo(hashNote(b)) > 0;
}

A handoff with confirmation (minesweeper)

The minesweeper app can hand a game to another copy. “Give the game away” changes state on two sides, and the Kit has no transaction, so the app builds the handoff from request/reply:

1. The sender offers (game.offer: difficulty, status, seconds, squares open; no board).
2. The receiving person says yes or no. An offer never changes a board by itself.
3. The receiver requests the board (game.take). The reply is the data. The sender serves it only for an offer it made, to the peer it made it to.
4. The receiver applies the board. Minesweeper.fromJson is strict: anything inconsistent is refused and nothing changes.
5. The receiver requests game.taken. Only when that request arrives does the sender release its game.

If the confirmation is lost, both copies keep the game: a duplicate, never zero. The receiver is told “did not confirm”. The app accepts one known hole, and says so in its source: moves made on the sender between serving the board and hearing game.taken are lost to the receiver. Closing it needs a lock on UI state that the hook cannot own.

The same offer also starts “play together”, where each move is sent as a small absolute message plus a checksum of the sender’s board, and a receiver whose checksum differs pulls the whole board. Two players who make the first move at the same instant are resolved by an epoch, then the lower PeerId. All of that is the app’s. The Kit supplied request/reply, the ordered delivery per sender, and admit, which the hook uses to refuse a peer with another protocol number. From the minesweeper demo app’s lib/coordination/game_hook.dart:

/// The person said yes to [o]: pull the board, apply it, confirm. Returns what happened, in words.
Future<String> accept(Offer o) async {
  final h = hub!;
  final peer = h.readyPeers.where((p) => p.id == o.from).firstOrNull;
  incoming.remove(o.from);
  if (peer == null) return _done('${PeerJson.label(o.from)} is no longer connected.');
  try {
    final reply = await h.request(peer, PeerJson.encode({'offer': o.id}), kind: 'game.take', schema: 1);
    final j = reply.jsonBody;
    if (j is! Map || j['ok'] != true || j['board'] is! Map) return _done('${PeerJson.label(o.from)} no longer has that game to give.');
    try {
      host.adoptBoard((j['board'] as Map).cast<String, Object?>());
    } on FormatException catch (e) {
      return _done('The game from ${PeerJson.label(o.from)} was not accepted: ${e.message}');
    }
    if (o.mode == 'share') sharing = o.from;
    try {
      final ack = (await h.request(peer, PeerJson.encode({'offer': o.id}), kind: 'game.taken', schema: 1)).jsonBody;
      if (ack is Map && ack['ok'] == true) return _done(o.mode == 'share' ? 'Playing together with ${PeerJson.label(o.from)}.' : 'Took over the game from ${PeerJson.label(o.from)}.');
    } on PeerError {
      // fall through
    }
    return _done('Took the game, but ${PeerJson.label(o.from)} did not confirm: it may still show the game too.');
  } on PeerError catch (e) {
    return _done('Could not get the game from ${PeerJson.label(o.from)}: ${e.message}');
  }
}

14. What the hook does not give you

These are the places where the hook is not enough. Each has the pattern the demo apps used. None is built into the Kit. Section 7.1 of the spec records why large transfer was not built and what it would need.

Smaller gaps you will meet:

• onMessage is synchronous. The hub processes one link’s frames one at a time. If a message needs async work, queue it in your hook (notepad has a pump with a bound).
• One hub is one channel, and admit is one answer per peer. “Accept this peer but not its offers” cannot be expressed. Use one hub per facet or a mux hook.
• No “same device” signal. Two copies with one device id are one replica to your files. Notepad compares peer.id.device itself in admit and rejects them.
• No place for hook state, and no clock. A stamp or a version that must survive a restart goes in your own file. A timer inside a hook is a plain Timer.
• hello() is a snapshot taken at connect. A command can land between the hello and ready; the stopwatch re-checks on ready for that reason.

15. Real transports

Only the fake network and the loopback provider are built. There is no provider for a real network, and no Hearth provider for the Dart hub. What follows is what a provider has to do, and what was learned about Hearth before writing one.

What every provider must do

The contract is in provider.dart. In short:

• open(self) announces this copy and starts accepting. discover() replays what is known, then follows changes, and re-emits a candidate with available: false when it goes away. connect(candidate) throws PeerScopeError outside the scope and PeerConnectError when it cannot reach the candidate. incoming buffers until listened to. close() is idempotent.
• Never offer, dial or accept another account or app id. The hub checks too, but a provider that leaks scope is a bug.
• Discovery must be symmetric. Only the lower PeerId dials, so both copies have to see each other, or neither connects.
• A link delivers one send as one inbound event. Framing is the provider’s job. send completes when the transport has taken the bytes.
• A link’s remote identity is a claim. The hub checks it against the frame headers and the authenticator’s proof and drops the link if the scope differs. Only a real authenticator makes the proof mean anything.

What Hearth would add

These come from the spec and from tests against a local Hearth hub. They are requirements for a provider, not code that exists in the Dart hub.

• Payload limit. Hearth’s effective payload cap is 64 KiB minus the Kit’s header. The 1 MiB figure is the whole envelope on the Hearth side, and above it the hub drops the connection. A provider should declare its maximum payload and send should fail before the wire when it is exceeded. This is not built: PeerProvider has no member for a payload maximum today, so the app passes its limit to PeerJson.fits and encodeWithin.
• Echo suppression. The hub delivers a broadcast back to its sender. Drop frames whose from.device and from.instance are this copy’s.
• Its own correlation ids. The hub’s message id is not a safe key for matching replies. The Kit’s rid plus (peer, rid) matching is already independent of it, and a provider must not rely on the transport’s ids.
• Deduplication by message id across live delivery and catch-up, liveness by a heartbeat sent no more often than every 30 seconds (the hub’s idle timeout is 90 seconds, and it caps publishes per hour per connection and per account), and reconnect.
• Topics. The stock hub’s topic grammar rejects app-scoped topics. The Hearth tests carried app traffic on the stock topics, set payload_type = ak.app/<app>, and filtered at the receiver. That is a filter, not access control.

What is built

See also: Architecture for the handshake and the roster versus the peers announcement, Context guide for the context the hub is built from, spec/APP-CONTEXT.md section 6 for the contract.

Testing

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

Two things are covered here: how to test an app built on the Kit, and how to run the App Context Kit repository’s own test suites.

The Kit is built so that an app’s tests need no network, no real home directory and no Venue. Two settings do that, and both are ordinary environment variables:

• Scratch (APP_CONTEXT_SCRATCH) puts every directory and the roster under one throwaway folder, so a test never touches real data.
• Mock (APP_CONTEXT_MODE=mock) replaces Venue with an in-memory fake and peers with an in-memory fake network.

Part 1 is for app authors. Part 2 is for working on the Kit itself.

Part 1: testing an app

Pass the environment in; do not read the machine’s

AppContext.open takes env:, platform: and home:. When you pass env, nothing from the real process environment is read, so a developer’s own APP_CONTEXT_* variables cannot change a test. The Dart test in docs/examples/dart_cli/test/kit_test.dart opens every context like this:

final env = {'APP_CONTEXT_MODE': 'mock'}; // the scratch directory is added per test

Future<AppContext> launch(AppManifest m, [Map<String, String> more = const {}]) =>
    AppContext.open(m, env: {...env, 'APP_CONTEXT_SCRATCH': scratch.path, ...more}, announce: false);

announce: false keeps the test out of the roster. scratch is a temporary directory made in setUp and deleted in tearDown:

late Directory scratch;
setUp(() => scratch = Directory.systemTemp.createTempSync('app-context-example-'));
tearDown(() => scratch.deleteSync(recursive: true));

Because the scratch directory outlives a context, “quit and launch again” is two opens on the same directory. This test is from the same file:

test('a setting written by one launch is read by the next, on the same scratch directory', () async {
  var ctx = await launch(manifest);
  ctx.config.set('launches', 1);
  await ctx.close();

  ctx = await launch(manifest);
  expect(ctx.config.get<int>('launches', 0), 1);
  await ctx.close();
});

Run it with dart test in that directory. Expected: All tests passed! (three tests).

To pin a platform for a test about paths, add platform: 'linux', home: '/x'. resolve() itself is a pure function, so you can also call it directly with a platform, home and env and compare the strings; that is what the conformance fixtures do.

Flutter: pumpKitApp and testAppContext

Import package:app_context_kit_flutter/testing.dart from test/ only; it depends on flutter_test.

A testWidgets body runs in fake async, and AppContext.open does real file I/O and starts real timers, so it cannot simply be awaited there. The helpers do that work inside tester.runAsync for you.

manifest can be an AppManifest, the JSON text of app.json, or a decoded map. Optional parameters: env (added to the isolated environment, and it may override it: {'APP_CONTEXT_SCRATCH', 'APP_CONTEXT_MODE': 'mock', 'HOME'}), scratch (reuse a directory; it is then not deleted), announce (default false), heartbeat, platform, fakeCapacity, transport, and for pumpKitApp, settle (also pumpAndSettle). The directory it made is deleted when the test ends. The host’s environment is never consulted.

The KitTestContext it returns:

This is the test from docs/examples/flutter_hello/test/hello_test.dart:

testWidgets('taps are saved and survive a quit and relaunch', (tester) async {
  final kit = await pumpKitApp(
    tester,
    manifest: File('app.json').readAsStringSync(),
    app: (ctx) => const HelloApp(),
  );
  expect(find.text('Taps: 0'), findsOneWidget);
  expect(find.text('mock + scratch'), findsOneWidget);

  await tester.tap(find.text('Tap'));
  await tester.pump();
  expect(find.text('Taps: 1'), findsOneWidget);
  expect(kit.ctx.dataFile('taps.log').readAsStringSync(), '1\n');

  await kit.relaunch(); // close, open again on the same scratch directory, mount again
  expect(find.text('Taps: 1'), findsOneWidget);
});

Run it with flutter test in docs/examples/flutter_hello. Expected: All tests passed! (one test).

If your test is about something that must have happened before the app ends (a flush on quit, a hook), call kit.close() or kit.quit() yourself and then assert. The calculator demo app’s test/calculator_screen_test.dart shows a test that passes announce: true to see the real roster entry appear and disappear, and one that asserts every directory the app resolved is under the scratch directory.

To test the real manifest asset bundle, AppContextKit.loadManifest('app.json') works in a widget test; the calculator demo app’s test/manifest_asset_test.dart does exactly that.

The fake Venue

In mock mode, ctx.venue is a FakeVenue. It has one node and a capacity (the fakeCapacity parameter of AppContext.open, default 1), refuses a hold with doesNotFit when it is full, and logs each call. refuseNext(n, {kind}) makes the next n holds refuse whatever the capacity, so a wait-and-retry loop can be tested without arranging a full node. This test is from kit_test.dart:

test('mock mode gives a fake Venue that can be made to refuse, so a waiting loop is testable', () async {
  final ctx = await launch(manifest);
  final venue = ctx.venue as FakeVenue;
  venue.refuseNext(2); // the next two holds are refused as "does not fit"

  const need = VenueNeed(name: 'job', contractClass: 'container.run.v1');
  final result = await venue.withHoldWaiting(need, (hold) async => 'done',
      maxWait: const Duration(seconds: 5), retryEvery: const Duration(milliseconds: 2));

  expect(result, 'done');
  expect(venue.log, ['hold job', 'hold job', 'hold job', 'start job', 'release job']);
  await ctx.close();
});

Use a small retryEvery in tests. withHoldWaiting counts waiting in naps rather than reading a clock, so it behaves under fake time. To test against a Venue that answers in particular ways without a socket, implement DaemonTransport (one send method and one close) and pass it as transport:. The App Context Kit repository’s own tests do this in dart/app_context_kit/test/support/fake_transport.dart.

The fake peer network

Peers are off unless the manifest lists "peers" in kits. In mock mode, ctx.peerHub and ctx.startPeers use an in-memory network. Give two contexts the same FakePeerNetwork and they find each other. Nothing touches the real network or the disk. This test is from kit_test.dart; Listener is a small AppCoordination defined in the same file, which records the messages it gets:

test('two copies of an app find each other on one fake network and exchange a message', () async {
  final peerManifest = AppManifest.fromJson({'id': 'dev.example.hello', 'name': 'Hello', 'version': '0.1.0', 'kits': ['peers']});
  final network = FakePeerNetwork(); // pass the same network to both copies
  final laptop = await launch(peerManifest, {'APP_CONTEXT_DEVICE': 'laptop'});
  final phone = await launch(peerManifest, {'APP_CONTEXT_DEVICE': 'phone'});

  final listener = Listener();
  final laptopHub = laptop.peerHub(Listener(), network: network);
  final phoneHub = phone.peerHub(listener, network: network);
  await laptopHub.start();
  await phoneHub.start();

  for (var i = 0; i < 100 && laptopHub.readyPeers.isEmpty; i++) {
    await Future<void>.delayed(const Duration(milliseconds: 20));
  }
  expect(laptopHub.readyPeers, isNotEmpty);

  await laptopHub.broadcast(PeerJson.encode({'text': 'hi'}), kind: 'greeting');
  for (var i = 0; i < 100 && listener.received.isEmpty; i++) {
    await Future<void>.delayed(const Duration(milliseconds: 20));
  }
  expect(listener.received, ['laptop: {text: hi}']);

  await laptop.close();
  await phone.close();
});

Set APP_CONTEXT_DEVICE per copy so the two have different device names; the instance ids are random. In a widget test, run the second copy inside tester.runAsync next to the one under pumpKitApp, and pass the same network to the app. The notepad demo app’s test/peers_ui_test.dart does this end to end.

FakePeerNetwork can also be made unreliable, to test how your hook copes:

FakePeerNetwork(seed: n) makes the randomness repeatable, and a ManualPeerClock passed as clock: makes time repeatable too. A test that checks a hook with startPeers should also check the case where peers cannot start: the handle’s error is set and the app keeps working alone. The demo apps each have such a test (for example the notepad demo app’s test/peers_ui_test.dart, “when peers cannot start the footer says why and the notes still work”).

The conformance fixtures

The fixtures are the contract in executable form. spec/conformance/manifest_cases.json has one case per manifest rule (valid and invalid), and spec/conformance/context_cases.json has one per directory or mode rule: given a manifest, a platform, a home directory and an environment, the expected directories, roster, scratch flag and mode. Both implementations load the same files:

• Dart: dart/app_context_kit/test/conformance_test.dart
• Rust: rust/tests/conformance.rs

The files are generated, not written by hand. tools/gen_fixtures.py spells every expectation out from templates, and never asks an implementation what the answer should be. That is deliberate: an implementation that agrees with the fixture has been checked against the prose spec, not against itself.

Add a case

1. Add one line to the cases list (context) or the mc list (manifest) in tools/gen_fixtures.py. A manifest case is bad(name, manifest, code) or ok(name, manifest, defaults):

   bad("kit-underscore", man(kits=["my_kit"]), "bad-kits"),
   

2. Regenerate:

   python3 tools/gen_fixtures.py
   

   It prints 25 context cases, 37 manifest cases (the counts with the example case added) and rewrites both JSON files.

3. Update the counts in the Rust test. rust/tests/conformance.rs asserts how many cases each file holds, so that a silently shortened fixture file cannot pass. Change the number in the matching run_all("manifest_cases.json", 36, ...) or run_all("context_cases.json", 25, ...) line. Without this the Rust run fails with fixture count changed; update this test. The Dart test needs no change.

4. Run both languages:

   (cd dart/app_context_kit && dart test test/conformance_test.dart)
   (cd rust && cargo test --test conformance)
   

   Expected: All tests passed! from Dart (+62 with the example case) and test result: ok. 2 passed from Rust.

If one implementation disagrees, the fixture is right unless the spec text says otherwise, and the prose is then corrected. A failing Dart case looks like this (shortened; here the expected code was wrong on purpose):

manifest conformance kit-underscore [E]
  Expected: throws <Instance of 'ManifestError'> with `code`: 'bad-id'
    Which: threw ManifestError:<ManifestError(bad-kits)>

This procedure was run on a copy of the App Context Kit repository with the example case; the checked-in fixtures were not changed. Regenerating the committed fixtures produces files identical to the ones in spec/conformance/.

Part 2: running the App Context Kit repository’s suites

Every command below was run on macOS (Apple silicon) when this page was written, and the Linux script in Docker. Counts will change as tests are added; what matters is the pass line. Paths are relative to the root of the App Context Kit repository. Nothing here needs anything outside it except the public package registries (pub.dev and crates.io).

The Dart core’s skipped tests are the five that need a real Venue daemon, the pinned-TLS group, and one that only applies on Linux. A skip is not a failure, but it means that test proved nothing on this machine.

The Rust crate builds from the App Context Kit repository alone. It has no remote Venue session, so it has no real-daemon or TLS tests: the real-daemon and TLS suites below are Dart only.

The conformance fixtures, again

Both languages must pass every fixture before anything else matters. Run the two conformance commands above first. If a fixture file was edited by hand, python3 tools/gen_fixtures.py will overwrite it.

Tests against a real Venue daemon

test/venue_real_test.dart talks to a real Venue daemon. The daemon is not part of the App Context Kit repository, and the Kit does not ship a script that starts one: start any compatible daemon yourself, then set the variables the test reads. The daemon needs a consumer named calc, granted container.run.v1, with a limit of three live holds (the limit test relies on it), a token file for that consumer, and a node whose heartbeat is kept fresh (without that, the daemon refuses every hold after about two minutes with does_not_fit). The Venue guide has the details.

cd dart/app_context_kit
VENUE_DAEMON=http://127.0.0.1:7878 VENUE_TOKEN_FILE=<path to calc's token file> dart test test/venue_real_test.dart

Expected: All tests passed! (5 tests). Without VENUE_TOKEN_FILE the file is skipped, and a skipped run proves nothing about the daemon.

Pinned TLS

test/venue_tls_test.dart checks pinned TLS against a daemon that serves a self-signed certificate. Start any compatible daemon with TLS, note the SHA-256 fingerprint of its certificate, and set three variables; without them the tests skip with a message.

cd dart/app_context_kit
VENUE_TLS_DAEMON=https://127.0.0.1:17879 VENUE_TLS_FINGERPRINT=sha256:<64 hex digits> VENUE_TOKEN_FILE=<path to calc's token file> \
  dart test test/venue_tls_test.dart

Expected: All tests passed! (14 tests). They cover:

Four more tests need no daemon (test/transport_pin_test.dart): the fingerprint spellings and a malformed pin. The first run of these cases against a real daemon found three problems around a pin that was itself sound (SecurityContext(withTrustedRoots: false) plus the certificate callback accepts exactly the pinned certificate and no other): an upper-case or colon-separated fingerprint was silently refused, and a wrong or malformed pin surfaced as an opaque handshake error. Both are fixed (parseFingerprint normalises the spellings; TlsPinException says what is wrong and what to do), and these cases keep them fixed.

Linux

tools/linux-test.sh [dart|rust|both] runs the Dart and Rust cores in throwaway Docker containers, as a non-root user, with the App Context Kit repository mounted read-only. It needs Docker running and a network connection, because each container fetches its packages. Set LINUX_AS_ROOT=1 to run as root, where a few tests behave differently because root ignores file mode bits (for example, a token file with mode 000 is read anyway, so that test is skipped). It uses dart:stable and rust:1.94 unless DART_IMAGE and RUST_IMAGE say otherwise. It copies spec/, rust/ and dart/app_context_kit into a tmpfs and builds there; no other checkout is needed.

It was run with Docker 28.5.2 on an aarch64 Linux VM (kernel 6.12.54), Dart 3.13.6 and Rust 1.94.1. It printed -- conformance fixtures (Dart): exit 0 --, -- whole package (Dart): exit 0 --, -- conformance fixtures (Rust): exit 0 -- and -- whole crate (Rust): exit 0 --, then exited 0. The Dart package ran 366 tests with 6 skipped (the Linux-only test runs there, so one fewer skip than on macOS); run as root it ran 365 with 7 skipped, because the mode-000 token test is skipped when root can read the file. The Rust crate ran 83 unit tests, 2 conformance tests, 6 host_os tests and 4 snapshot-conformance tests (one host_os test is Linux-only, so 6 there against 5 on macOS).

The two-process test

Every peers test except this one runs inside one process. dart/app_context_kit/test/peers/two_process_test.dart starts each hub in its own operating-system process (two_process_worker.dart), over the loopback provider and one shared temporary directory. Two copies of one app and account find each other, exchange hello and admit (ready on both sides), send, broadcast and request/reply. A third process with a different app id and a fourth with a different account saw no peer event and no message in over 600 ms, and neither appeared in the others’ peer lists. A graceful quit is lost with the reason goodbye, and the announcement is gone.

It also kills one process with kill -9 to see what a dying process looks like to its neighbour, and prints the numbers it measures: how long the survivor takes to see the peer lost, and how long the dead copy’s announcement file stays behind. Run it with -r expanded to read them. APP_CONTEXT_GHOST_SECONDS (default 12) sets how long the survivor is watched after the kill. This variable is read by the test only; the Kit does not read it. The numbers and the fix they led to are in Platforms; test/peers/loopback_ghost_test.dart (6 tests) covers the heartbeat rules without a second process.

Architecture

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

This page explains how the App Context Kit is put together: the layers, what happens when an app starts and stops, how two copies of an app connect, and how the spec, the shared test fixtures and the two implementations fit together.

The Kit gives one running app a root object, AppContext. An app gets its identity (the reverse-DNS id in app.json), its directories, its settings, a test mode, a presence entry in a shared roster, a session with a resource broker, and an opt-in way to find and talk to other copies of itself.

Diagrams are Mermaid, which GitHub renders. Every diagram is checked against the code named under it.

Contents: layers · startup · shutdown · the peer handshake · roster and peers announcement · spec, fixtures, implementations · why these boundaries

1. Layers and the direction of dependency

flowchart TB
  subgraph apps["Apps, for example the demo apps in The Kit Book"]
    app["Six demo apps. main.dart is 5 to 11 lines"]
  end
  subgraph companion["Companion: dart/app_context_kit_flutter"]
    comp["AppContextKit.run, ExitCoordinator, ModeBadge, NotesBanner, PeersIndicator, test helpers"]
  end
  subgraph core["Core: dart/app_context_kit - pure Dart, no Flutter import"]
    ctx["AppContext: manifest, resolve, config, roster"]
    broker["Resource-broker session (VenueSession). venue.mode in app.json: auto, on, off"]
    peers["Peers (opt-in: app.json kits lists peers): PeerHub, envelope, providers"]
  end
  subgraph outside["Outside the Kit"]
    daemon["Resource broker daemon, over HTTP"]
    os["Files and loopback TCP on this machine"]
    hearth["Hearth hub: no provider built yet"]
  end
  app --> comp
  app --> ctx
  app --> peers
  comp --> ctx
  ctx --> broker
  broker --> daemon
  ctx --> os
  peers --> os
  peers -.-> hearth

Arrows point from a layer to what it depends on. The dotted arrow is planned, not built.

What to notice. The core, dart/app_context_kit, imports no Flutter and depends on one package, crypto. The companion depends on the core and adds only what needs Flutter: loading app.json from an asset, one guarded exit path, a mode badge, a notes banner, a peers indicator, and widget-test helpers. Nothing in the Kit depends on an app. The Rust crate in rust/ is a separate implementation of spec sections 1 to 5 and is not part of this stack.

The apps use the core directly for their own logic and hooks, and the companion for startup and widgets.

Peers are opt-in in a literal way: ctx.startPeers throws KitNotDeclared unless app.json lists "peers" in kits. That is the only place the kits list gates anything today. The resource-broker session is controlled by venue.mode instead (off never connects, auto connects if a token exists and the daemon answers, otherwise falls back to a local session and says so, on fails to open if it cannot connect), and in mock mode it is always an in-memory fake.

2. Startup

sequenceDiagram
  participant M as AppContextKit.run
  participant C as AppContext.open
  participant D as Directories and config.json
  participant V as Resource-broker session
  participant R as Roster
  participant A as Your app
  M->>M: load app.json from the asset bundle
  M->>C: open(manifest, env)
  C->>C: resolve platform, home, env into paths, mode, roster dir
  C->>D: create data, config, state, cache, runtime directories
  C->>D: read config.json (a damaged file becomes a note)
  C->>V: open session (fake, local or remote)
  C->>R: announce ID@INSTANCE.json and start a 5 s heartbeat
  C-->>M: AppContext
  M->>A: app(ctx) under AppContextScope
  A->>C: ctx.startPeers(hook), ctx.onClose(...)
  M->>M: install exit paths (window close, SIGINT, SIGTERM), runApp

Source: AppContextKit.run in app_context_kit.dart and AppContext.open in app_context.dart.

What to notice. The order is chosen so a failure leaves nothing behind. The resource-broker session opens before the roster entry is written, so a session that refuses to open (mode on) fails before anything is announced. If announcing fails, the session is closed again. If the manifest cannot be read or the context cannot open, AppContextKit.run shows an error screen with the error code instead of crashing. Your app’s builder runs before the exit paths are installed, so any hook it registers with ctx.onClose is in place before the window can be closed. If the builder throws, the context is closed again and the error screen shows app-build-failed.

3. Shutdown

sequenceDiagram
  participant E as Exit path
  participant X as ExitCoordinator
  participant C as AppContext.close
  participant R as Roster
  participant H as onClose hooks
  participant V as Resource-broker session
  E->>X: window close, quit, SIGINT, SIGTERM or AppContextKit.quit
  X->>C: close, once
  C->>R: stop heartbeat, delete this copy's own file
  C->>H: run hooks, last added first
  Note over H: PeerHub.close sends kit.bye to ready peers, closes links, removes the peers announcement
  C->>V: close the session, last
  C-->>X: done, or all errors raised together
  X->>E: allow exit, or end the process (130 SIGINT, 143 SIGTERM, 0 quit, 1 if close failed)

Source: ExitCoordinator in exit_coordinator.dart and AppContext._closeOnce in app_context.dart.

What to notice. Every exit path funnels into one shutdown that closes the context at most once; a second signal gets the same future instead of a second close. Every step runs even if an earlier one throws, and the errors are raised together afterwards. A failing close is written to stderr and does not block the exit, and there is no timeout, so a hung hook is a bug in the hook. SIGKILL skips all of this, which is why the roster and the peers announcement both carry a timestamp that goes stale.

4. The peer handshake

sequenceDiagram
  participant A as Copy A, lower PeerId
  participant B as Copy B
  Note over A,B: Providers announce and watch. Each hub sees the other as found.
  A->>B: connect (only the lower PeerId dials)
  par on attach, both sides
    A->>B: kit.hello (nonce, app hello)
  and
    B->>A: kit.hello (nonce, app hello)
  end
  A->>B: kit.auth (proof over B's nonce)
  B->>A: kit.auth (proof over A's nonce)
  Note over A,B: each side verifies the proof, then calls admit(peer, hello)
  A->>B: kit.ready (or kit.reject with a reason)
  B->>A: kit.ready
  Note over A,B: ready means I admitted you and your kit.ready arrived. onPeer(ready) fires.
  A->>B: app messages, requests and kit.reply
  A->>B: kit.bye
  Note over B: lost with reason goodbye, not redialed

Source: the protocol comment at the top of hub.dart, checked against _onHello, _onAuth and _checkReady.

What to notice. Only the copy with the lower PeerId dials, so two copies never open two links; the other side waits for the incoming link. That works only if discovery is symmetric, which it is for both built providers. “Ready” needs two things on each side: your admit said yes, and the other side’s kit.ready arrived. A link that is not ready after 5 seconds is dropped. A kit.reject marks the peer rejected on both sides, and it is not redialed until the provider withdraws and announces it again.

5. The roster and the peers announcement are different things

Both are small JSON files that a process rewrites on a timer and others treat as dead when the timer stops. They answer different questions.

flowchart LR
  subgraph roster["Roster directory, one per machine"]
    rf["ID@INSTANCE.json: id, name, version, pid, heartbeatAt"]
  end
  subgraph peersdir["Peers directory, one subdirectory per account and app"]
    pf["DEVICE@INSTANCE.json: account, app, device, instance, port, pid, beat"]
  end
  ctx["AppContext, every app"] -->|"writes, every 5 s"| rf
  viewer["Launcher: Roster.scan"] -->|"reads"| rf
  prov["LoopbackProvider, apps that list peers"] -->|"writes, every 1 s"| pf
  other["Other copy of the same app"] -->|"reads, every 100 ms"| pf
  other -->|"TCP to the port in the file"| prov

What to notice. The roster is for people and tools that want to see every app. The peers announcement is for copies of one app that want to connect, so it carries a port and is partitioned by scope. The staleness numbers differ because the cost of being wrong differs: a launcher that shows a crashed app as running for a few seconds is a cosmetic problem, while a hub that keeps a dead copy in its peer list wastes dials and shows a peer that is not there. Other providers have no files at all: the fake network is in memory, and a Hearth provider would use topics.

These are two separate implementations of one idea (write a file, rewrite it on a timer, treat it as dead when the timer stops) with different constants. Folding them into one shared primitive is a possible simplification that has not been done.

6. Where the spec, the fixtures and the two implementations meet

flowchart LR
  spec["spec/APP-CONTEXT.md"]
  gen["tools/gen_fixtures.py"]
  fix["spec/conformance: manifest_cases.json 36 cases, context_cases.json 25 cases"]
  dart["Dart: dart/app_context_kit, test/conformance_test.dart"]
  rust["Rust: rust/, tests/conformance.rs"]
  only["Spec sections 6 and 7: peers and helpers, Dart only, tested in test/peers"]
  spec -->|"expectations written out from the text"| gen
  gen --> fix
  fix --> dart
  fix --> rust
  spec -.-> only

The fixtures cover the manifest rules (spec section 1) and path, mode and roster resolution (section 2). They are pure functions: no files, no network, which is what lets two languages check the same cases. tools/gen_fixtures.py writes the expectations out by hand from the spec text; no implementation computes them. Run the conformance checks with cd dart/app_context_kit && dart test test/conformance_test.dart and cd rust && cargo test --no-default-features --test conformance.

What to notice. The rule is that the fixture wins: if the prose and a fixture disagree, the prose is fixed. Behaviour that touches the outside world (config files, the roster, the resource-broker session, token lookup) is in the spec but not in the fixtures, so each language tests it itself. The Rust crate covers spec sections 1 to 5. The peer layer (section 6) and the later helpers (section 7) exist in Dart only, and are covered by Dart tests, including real processes in test/peers/two_process_test.dart.

Why these boundaries

The Kit does not interpret payloads. The same hub carries three very different meanings in the demo apps: a signal (stopwatch), replicated notes with a conflict rule (notepad), and handing a game to another copy (minesweeper). Adding coordination to those three apps changed no file under dart/app_context_kit. If the Kit knew what a message meant, the first app whose meaning was different would have needed a Kit change. Keeping it opaque also means the Kit has nothing to get wrong about your data, and nothing in your data can confuse it: the Kit parses its own header and passes the payload on untouched.

The core avoids Flutter. Closing an app cleanly on window close or quit needs Flutter’s lifecycle, and starting needs its asset bundle, so those live in the companion package. Everything else runs under plain dart test with no engine. The core test suite (365 passed, 7 skipped) runs in about half a minute, and the peers logic runs as a headless process; the three demo apps that use peers each have a tool/peer_probe.dart that runs the app’s own coordination code without a window. The same boundary is what makes a second implementation possible: the Rust crate follows the same spec without touching Flutter.

One spec, with shared fixtures. A written spec alone lets two implementations drift. The fixtures turn the pure parts of it into data that both languages must pass, and the rule that the fixture wins keeps the prose honest. The fixtures are generated from spelled-out expectations, so a bug in one implementation cannot leak into the expected answer.

The second implementation found things the first could not. The Rust crate passed all 41 fixtures that existed when it was first written, and still disagreed with the Dart core on several behaviours that no fixture covered. Among them: how a root path joins (/ plus an id gave //id in Dart), whether a trailing backslash on a Linux path is trimmed, and whether a later set() may overwrite a config file that was found damaged (Dart did; Rust refused until the file is set aside). Each became either a spec decision, a fixture, or a per-language test: the fixture set grew from 41 to 61 cases. Those cases came from comparing the two implementations, not from reading either one alone.

Apps do not edit the Kit. A demo app that needs something the Kit lacks writes it under lib/kit_gaps/ with a // KIT GAP: comment. The line count of those directories is the measurement of what the Kit is missing; the ledger is kept with the demo apps in The Kit Book.

See also: Overview for what the Kit is and is not, Design decisions for the decisions in more detail, Context guide for AppContext, Coordination guide for the peer layer.

Platforms

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

What runs where, how it was checked, and what was not. If a row says “not verified”, nobody has run it.

The two cores are dart/app_context_kit (pure Dart) and rust/. Both read the same 61 conformance fixtures in spec/conformance/ (25 for path resolution, 36 for the manifest). The rules they implement are in spec/APP-CONTEXT.md. The Rust crate has no remote Venue session, so the Venue column describes the Dart core.

Where things go

For an app whose manifest id is ID, the Kit resolves five directories and a roster directory. home is the user’s home directory.

Overrides, from highest priority: <PREFIX>_<KIND>_DIR (used exactly as given), then APP_CONTEXT_SCRATCH (puts everything under one directory, for tests), then the table. On Windows a missing LOCALAPPDATA, APPDATA or TEMP is the error missing-env, but only if a default that needs it is actually used.

~/Library/Preferences/ID/config.json is an unusual place for a JSON file on macOS, where that folder is meant for property-list files. No problem was seen. It is an open spec question.

macOS

What was checked.

• Both cores’ tests pass natively. Run for this page: Dart 365 passed, 7 skipped by default (the pinned-TLS group and 5 real-daemon tests, which need a daemon, and 1 Linux-only test). Rust: 83 unit, 2 conformance, 5 host-OS and 4 snapshot-conformance tests. The Dart real-daemon tests (5) and TLS tests (14) passed against throwaway daemons when this page was first written; they skip without one, so the run for this page did not exercise them.
• All six demo apps were built with flutter build macos --debug and launched during development. Cmd-Q and SIGTERM close the app cleanly (the roster entry is removed and Venue holds are released). Recorded in notes taken at the time; not re-run for this page.
• Two real processes find each other over loopback, exchange messages, and see each other disappear after kill -9 (the link drop is seen in milliseconds; the peer is withdrawn in about 3.5 seconds). Tested in dart/app_context_kit/test/peers/two_process_test.dart; it passed in the full run for this page.
• A copy killed with kill -9. The surviving copy sees the link drop at once (about 3 ms) and withdraws the dead copy’s announcement 3.5 to 3.8 s later (3.5 s on macOS, 3.8 s on Linux). Before the announcement carried a heartbeat the picture was worse: the survivor that had dialled gave up after 10 failed dials (about 31 s) but left the dead copy listed as found for ever (watched for 45 s); a survivor that never dials never learned the announcement was dead at all; and a restarted copy with the same device id appeared beside the ghost. The fix is in dart/app_context_kit/lib/src/peers/loopback_provider.dart: each provider rewrites its announcement file every second with a wall-clock beat; a file whose last beat is older than 4 s is not offered, and a peer already known from it is withdrawn (the hub then reports the final lost and stops dialling); a file older than 60 s is deleted by whoever notices. Checking the announcing process id was rejected: it means nothing across process-id namespaces (containers), ids are reused, and Dart has no portable way to ask whether a pid is alive without starting a process. The cost is one small write per second per process. Not fixed: a brief found right after the first lost, which for a crash lasts up to the 4 s limit (a graceful quit has none), because the hub deliberately re-announces a copy that is still advertised.

What was not checked. Release builds of the demo apps on macOS (only one, notes_rust, was built in release mode). Signed or notarized builds. The red window-close button on a real window (Cmd-Q and SIGTERM were). Launching from Finder or the Dock (see below). The text on screen in a real window: the display was off for most of the runs, so UI behaviour was read from the widget tree and from the apps’ own code, not seen.

Environment variables do not reach an app launched from Finder or the Dock. APP_CONTEXT_MODE, APP_CONTEXT_SCRATCH, VENUE_TOKEN_FILE and the rest are read from the process environment. To use them, start the app’s binary from a terminal. For a normal launch, put the Venue token at <config>/venue-token and use config.json for settings.

The App Sandbox

Flutter’s macOS template turns the App Sandbox on. A sandboxed app sees a private HOME and TMPDIR inside ~/Library/Containers/<bundle id>/Data. Apple requires the sandbox for Mac App Store apps (that is Apple’s rule, not something verified here).

The sandbox changes what the Kit means:

• Every directory in the table above moves into the container. Data lands under Data/Library/Application Support/ID/, and the default roster is Data/tmp/app-context-roster. Each app has its own, so the default roster is no longer shared between apps.
• APP_CONTEXT_SCRATCH and other overrides that point outside the container fail.

Today the demo apps (in The Kit Book) are mixed: the calculator, minesweeper and notepad have the sandbox on; the launcher, render-queue and stopwatch have it off (their entitlement files say app-sandbox is false). The reason is that no sandbox-on setup was found that works for all of them; see the roster row below.

How these results were obtained: copies of the built debug apps were re-signed ad hoc (no team ID) with the entitlement variants below, launched by running the binary directly, and observed through the container directory, the system log, and the widget tree. No entitlement file in the demo apps was changed by that work. These results come from notes taken at the time and were not re-run for this page.

Entitlements by capability

Entitlements the demo apps carry today, from the files in each demo app’s macos/Runner/ (the demo apps are in The Kit Book):

A sandboxed render-queue (talking to Venue) would need app-sandbox plus network.client. A sandboxed stopwatch alone runs with app-sandbox and keeps its data in its container. The files above are what the apps carry now; they are not those minimal sets.

Identity is declared four times

An app’s id appears in app.json, the macOS bundle id, the Linux application id, and (name and version) pubspec.yaml. Nothing makes them agree. The companion package ships a check:

cd dart/app_context_kit_flutter
dart tool/check_identity.dart <path to render-queue> <path to calculator>

Output for two of the demo apps (exit code 1, because of the first app; the headers repeat the paths that were given):

== render-queue
  MISMATCH  id: app.json says com.slashbuilder.demo.render-queue but the macOS bundle id (PRODUCT_BUNDLE_IDENTIFIER) is com.slashbuilder.demo.renderQueue
  note      name: app.json says "Render Queue" but the macOS PRODUCT_NAME is "render_queue" (same name, different letter case)
  MISMATCH  id: app.json says com.slashbuilder.demo.render-queue but the Linux application id (APPLICATION_ID) is com.slashbuilder.demo.render_queue
  note      name: app.json says "Render Queue" but the Linux window title is "render_queue" (same name, different letter case)
== calculator
  note      name: app.json says "Calculator" but the macOS PRODUCT_NAME is "calculator" (same name, different letter case)
  note      name: app.json says "Calculator" but the Linux window title is "calculator" (same name, different letter case)
  ok: id, name and version agree everywhere they were checked

The manifest id grammar allows hyphens, but macOS bundle ids and Linux application ids are written differently on each platform, so a hyphenated id cannot match all three. Whether the manifest may contain hyphens is an open spec decision. The check reports; it never edits. It does not look at Windows, Android or iOS.

Linux

What was checked. Both cores’ tests ran in Docker containers, as a non-root user, on a 6.12 linuxkit kernel, aarch64 (so not x86_64), with the images dart:stable and rust:1.94 (override with DART_IMAGE and RUST_IMAGE). The App Context Kit repository is mounted read-only; each container copies spec/, rust/ and dart/app_context_kit into a tmpfs and builds there, so nothing is written back and nothing persists. The command is tools/linux-test.sh:

tools/linux-test.sh            # both cores
tools/linux-test.sh dart       # one
LINUX_AS_ROOT=1 tools/linux-test.sh

Re-run for this page: Dart (SDK 3.13.6) conformance 61 passed and the whole package passed (366 passed, 6 skipped; the Linux-only test runs here, and the real-daemon tests skip); Rust 1.94.1: 2 conformance, 83 unit, 6 host-OS and 4 snapshot-conformance tests passed. No other checkout is needed, because the Rust crate no longer has an optional dependency on a Venue client.

When the suites were first run on Linux, the outcomes of the 306 tests that existed then were compared by name against the macOS run: no test differed. That proves less than it sounds, because almost none of them touch the real operating system (they pass platform: in). So test/host_os_test.dart and rust/tests/host_os.rs were added with no platform override; they check the directory conventions of the host, the rename-based config write, and the default five-second roster heartbeat (a wait of about 5.6 s: the entry is rewritten and stays live).

Directories follow the XDG variables when set and the home-relative defaults when not. This is tested without a platform override in test/host_os_test.dart and rust/tests/host_os.rs. The roster is in /tmp/app-context-roster when XDG_RUNTIME_DIR is unset. Config writes are renames, and a reader polling during a rewrite never saw a partial file (tested on Linux and macOS, both languages).

Two real processes found each other over loopback in a container too, including after a kill -9.

Things that differ from macOS and are worth knowing:

• Run as root, a token file with permissions 000 is read anyway. A container that runs your app as root will use a token file the mode was meant to hide.
• Dart returns file modification times to the microsecond on Linux and truncated to whole seconds on macOS. Nothing in the Kit relies on file times.
• Reasoned, not tested: /tmp/app-context-roster is created with the first user’s umask, so a second user on the same machine probably cannot announce into it.

What was not checked. A real Linux desktop session. The demo apps (in The Kit Book) were built with flutter build linux --release and launched headless under a virtual display (Xvfb) in an aarch64 Ubuntu 24.04 container with Flutter 3.41.9; the test is make linux-smoke in The Kit Book. All seven launched, exited with status 143 on SIGTERM, wrote a roster file and withdrew it, and kept their state across a relaunch (minesweeper, notepad, stopwatch and notes_rust). Two copies of the stopwatch and two of the notepad found each other, and the notepad synced a seeded note. There were no uncaught exceptions; the only warnings were the container’s missing accessibility bus and missing GPU. Still unchecked: window close by click, a compositor or window manager, a real GPU, notify-send (used by the stopwatch demo), other distributions, Wayland, and x86_64. The Linux application id in each runner has to match the manifest; see the identity check above.

Windows

Verified: the path-resolution rules, as pure functions. Five of the 25 resolution fixtures use platform: "windows"; they cover the default locations, the missing-variable error, scratch needing no variable, trimming either kind of trailing separator, and a bad mode being reported before a missing variable. Both cores pass them. The fixtures never touch a filesystem.

Nothing else is verified. Neither core was built or tested on Windows. Not run: file I/O, the atomic config write, the roster and its heartbeat, loopback peers, the Flutter companion, any Venue session, the demo apps. Same-machine peers there would use the loopback provider, which has not been run on Windows. There are no Windows runner folders in the demo apps.

iOS and Android

Not attempted. The Flutter companion’s notes say there is no mobile exit story: window close, Quit and signals are desktop events, and the one mobile hook (onDetach) closes on a best-effort basis with no guarantee the OS gives it time. Nothing about directories, the roster, peers or Venue was checked on a phone.

Packaging checklist

For shipping an app that is built on the Kit. Each line says what to do and where it was observed to matter.

1. Make the ids agree. Run dart tool/check_identity.dart <app dir> (from dart/app_context_kit_flutter). It must exit 0. Decide what a hyphenated manifest id does on each platform.
2. Declare what you use. "kits": ["venue"] for Venue, "peers" for the peer layer. ctx.peerHub throws KitNotDeclared if peers is missing.
3. Choose sandbox on or off per channel, and add entitlements for every capability you use (table above). Debug and Release are separate files. For peers, network.client and network.server in both.
4. Put the Venue token where the app can read it. Under the sandbox that is <config>/venue-token inside the container, or VENUE_TOKEN. Not a path outside it.
5. Provision the app with Venue before it ships. An app cannot register itself; see the Venue guide. Without that, the app runs on the local session and says so.
6. Use short Venue leases. A killed app keeps its quota until the lease lapses.
7. Start through AppContextKit.run (the companion package), so window close, Quit, SIGINT and SIGTERM all end in one ctx.close(). Test Cmd-Q and SIGTERM on the built app. kill -9 leaves a stale roster entry (hidden after 15 seconds) and any Venue holds until the lease lapses.
8. Test in mock and scratch modes (APP_CONTEXT_MODE=mock, APP_CONTEXT_SCRATCH=<dir>) from a terminal; they do not reach a Finder or Dock launch.
9. Do not use the loopback peer provider across a trust boundary. It has no encryption or authentication. It is for copies of an app on one machine, run by one user.
10. Run on the real target. On Linux the Kit has headless container evidence only (see “What was not checked” under Linux above); on Windows and mobile it has none.

Design decisions

Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.

Why the App Context Kit is shaped the way it is, what we tried instead, and what is still undecided. Each entry says what the evidence was, so you can disagree with the right thing.

Decisions that held

1. One written contract, two implementations, shared fixtures

The behaviour lives in spec/APP-CONTEXT.md. Dart and Rust both implement it, and both must pass the same fixtures in spec/conformance/. Why. The first implementation passed its own 41 fixtures on the first run, which proved almost nothing because the same author wrote the spec, the fixtures and the code. The Rust implementation, written from the spec text, passed the same 41 and still disagreed with Dart on about a dozen behaviours no fixture covered (what happens to / as a base path, which separator gets trimmed, what a name made only of a byte-order mark is, what happens when a named token file is missing…). Closing them took 20 more fixtures. The suite is the product; the prose is commentary. Cost. About twice the code in Rust as in Dart for the same behaviour, and a spec that must be kept honest.

2. The core is pure Dart; Flutter lives in a companion

The core package has no Flutter import, so it runs in a command-line tool, a server, or a test with no engine. Everything that needs Flutter (loading the manifest from an asset, exiting cleanly on window close or a signal, a mode badge, a notes banner, test helpers) is in app_context_kit_flutter. Why. In all six demo apps the same shims were written by hand (a 20 to 56 line exit hook was rewritten six times out of six). They are Flutter-shaped, so they belong in a Flutter package, and the rest should not pay for them.

3. The Kit never interprets an app’s payload

The Kit finds peers, checks scope, connects and routes. Meaning is the app’s, supplied through a five-method hook (channel, hello, admit, onPeer, onMessage). Why. The same hook expressed a live signal, a handoff and a conflict-resolving sync without the Kit knowing which was which. A Kit that knew about “notes” or “games” would have to be changed for every app. Cost. The hook is only just enough for live play, and for sync it is a small shell around a lot of app code. See what the hook does not give you.