parity

name	parity
description	Audit and enforce three-client feature parity (iOS / Linux GTK / macOS AppKit). Prints the capability matrix, validates the manifests, and drives closing gaps. Use before starting any user-facing feature, when asked about parity or drift, and when closing a declared gap or partial.

Three-client feature parity

One product, three clients: Tailscode (iOS UIKit), TailscodeLinux (GTK4), TailscodeMac (AppKit, macOS 26+). The source of truth is TailscodeCore/Sources/TailscodeCore/Parity.swift:

• AppCapability — every user-facing capability, one enum case.
• CapabilityRegistry.all — the toolkit-free spec for each capability. Ports are judged against the spec, not against another platform's widgets.
• Each client answers every case in its own Parity.swift manifest (Tailscode/App/, TailscodeLinux/Sources/TailscodeLinux/, TailscodeMac/) with .implemented(anchor), .partial(anchor, missing:), .gap(reason), or .notApplicable(reason). The switches are exhaustive and have no default: — a new capability refuses to compile all three clients until each decides what it does about it.

The Mac client ships two ways — TailscodeMac (ad-hoc, what scripts/install-macapp.sh installs) and TailscodeMacStore (sandboxed, Mac App Store, built with TAILSCODE_MAS) — so its manifest may answer .varies(direct:appStore:because:) and the matrix has four columns: iOS, linux, mac, mac-store. Only the Mac may use .varies; a varies in a client that ships one way is rejected.

scripts/parity.sh prints the matrix and greps every anchor against that client's own tree (manifest excluded), so a stale anchor fails; --check is the quiet gating mode the repo's Stop hook runs. The anchor grep runs through scripts/lib/gating.awk, which resolves #if TAILSCODE_MAS frames, so the mac-store column cannot claim an anchor the store build compiles out. The Linux and Mac selftests also walk the manifest (checkParity), and the Mac one additionally runs MacParity.audit().

The iron rule

Every user-facing feature starts and ends in the registry.

1. New capability → add the AppCapability case + CapabilityDefinition FIRST. The compiler now lists everyone who owes an answer.
2. Implement per client — or record an honest .gap/.partial with a reason a future agent can act on. .notApplicable is only for platform impossibility (no shell on iOS), never "later".
3. Changed behavior on one client → re-read the spec, update the others or downgrade their evidence honestly. Renamed a symbol → the anchor grep will catch you; fix the manifest.
4. A feature is DONE when scripts/parity.sh prints PARITY_OK and every touched client builds + passes its validation below.

Per-client validation loops

• Linux (this box): cd TailscodeLinux && swift build → .build/debug/tailscode --selftest → scripts/install-linuxapp.sh (install + restart is part of done).
• Mac (remote): follow TailscodeMac/AGENTS.md — rsync CodingAgentKit + repo to macbook, xcodegen && xcodebuild -scheme TailscodeMac -derivedDataPath build-tsmac, then --selftest with TAILSCODE_HOST=100.91.211.44:4098 TAILSCODE_PASSWORD=tailscode.
• iOS (remote compile): scripts/build-mac.sh; run on a simulator with scripts/run-mac.sh when rendering changed.

Closing gaps

scripts/parity.sh lists every .gap and .partial with its reason — that list is the backlog. To close one: read the spec in CapabilityRegistry, read the richest existing implementation (the matrix shows who has it), port the semantics into the client's toolkit, upgrade the manifest line to .implemented(anchor), validate, commit atomically. Shared logic goes to TailscodeCore first (toolkit-free) and only rendering stays in the client.