developer-toolchains.md

Developer toolchains

Web toolchain pins

Tool	Version
Node.js	24.18.1
pnpm	10.34.0
React	19.2.8
React DOM	19.2.8
TypeScript	6.0.3
Vite	8.2.1
Vitest	4.1.10
Testing Library React	16.3.2
Testing Library jest-dom	7.0.1
Playwright	1.62.1
Biome	2.3.2

Native toolchain pins

Tool	Version
Rust toolchain	1.95.0
Tauri CLI	2.11.4
Tauri crate	2.11.2
tauri-build	2.6.2
serde	1.0.228

Deterministic local ports

• Vite dev server: 127.0.0.1:4173
• Vite preview server: 127.0.0.1:4174
• Tauri dev URL: http://127.0.0.1:4173

Phase 1 boundary notes

• The repository consumes exact vendored packed @opencoven/* artifacts from vendor/opencoven-sdk; production imports never resolve to SDK workspace source.
• src/lib/desktop-host.ts is the only typed webview-to-host bridge and is limited to the non-secret app_identity and app_installation_id commands. The latter validates the canonical UUID v4 pairing identity returned from native secure storage.
• src/lib/sdk/native-boundary.ts is the narrow SDK-managed Cave bridge. It accepts only opaque authority handles, bounded page options, canonical conversation IDs, and SDK-safe result snapshots. SDK operation contexts are reduced to an unpredictable, epoch/counter-bound single-use attempt ID plus a timeout of at most five seconds; aborts use the dedicated cave_cancel_operation command with only the attempt ID and the canonical aborted or timeout reason.
• The same bounded operation and cancellation controls expose only the exact raw ordinary { status: "ok" } Coven health result. A dedicated native single-worker executor rejects overlapping health work with a retryable bounded diagnostic and releases capacity only after the synchronous producer call actually returns. Caller timeout or cancellation does not stop the OS call. Native production code consumes the producer-owned Rust coven-client at exact Coven revision 721437b84026c042e431b0882dcd14fdb29ac07d; it resolves explicit COVEN_HOME or the current account's real platform home plus .coven, then relies on that crate for live Unix connected-peer credentials or Windows named-pipe ownership and connected identity. Native trust unavailability fails closed, with no pathname-only, constructed-pipe, shell, PowerShell, lsof, or Node-private fallback.
• Native credential mutations use one bounded worker reservation. Work cancelled while queued never acquires the keyring lock; once an irreversible mutation starts, concurrent retries fail with non-retryable credential_update_in_progress until the authoritative result is coherent.
• Credential records use binary secret-store APIs and zeroizing transient buffers. Windows entries require Local persistence and migrate prior Enterprise values plus legacy UTF-16 password encoding; mutation locking uses a current-user-only Global\ mutex with verified ownership/DACL and the shipped session-local mutex during the compatibility window. Unix lock acquisition is owner-private and bounded.
• Packed tarballs are verified by the cross-repository canary against the exact canonical release manifest, package paths, sizes, and digests in a temporary install copy rather than by a source-relative or absolute path dependency.
• Run the local canary with pnpm test:contract-canary -- --sdk-root <sdk-root> --cave-root <cave-root>.
• Run the packaged real-authority matrix through the trusted outer launcher: /bin/sh scripts/phase1-conformance-launcher.sh "$(command -v node)". Its independent phase1-conformance.lock.json pins Chat, the SDK package candidate, Cave, Coven, all four frozen SDK artifacts, and the SDK evidence authority; the harness creates exact clean detached clones rather than trusting source repositories' current branches.
• CI reads contract-canary.lock.json, checks out those exact reviewed SDK and Cave revisions, rejects dirty SDK or Cave checkouts, and verifies the checked-out HEADs before the canary runs. The SDK lock targets canonical main commit acc38488f00860d246c3c553375634d64806eabb and manifest digest b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c. The lock also pins the Cave producer's Client v1 contract fixture and hpke-bound-v1 vector digests; the canary proves packed vector byte identity and the ancestry of the SDK's historical contract fixture provenance.
• src-tauri/gen/schemas/desktop-schema.json is intentionally kept outside the ignore rules so the capability $schema can ship with fresh checkouts.
• Tauri capabilities are limited to reviewed autogenerated allow-app-identity, allow-app-installation-id, and Cave adapter permissions for the main window.
• No shell, filesystem, opener, or network plugin permissions are configured.
• The feature-gated phase1-native-rpc binary is a headless conformance-only NDJSON bridge. It is excluded from default Cargo and Tauri builds. Unit scenarios default to in-memory custody, while the real-authority runner explicitly selects the production NativeKeyring, restarts the RPC process, and verifies credential reuse and deletion. Cave launch paths are accepted only through its two explicit OPENCOVEN_PHASE1_CONFORMANCE_NODE_PATH and OPENCOVEN_PHASE1_CONFORMANCE_CAVE_SERVER_PATH environment variables.
• Run its subprocess integration gate with pnpm test:native-e2e; normal pnpm app:dev selects the opencoven-chat desktop binary by default.
• Run the persisted Windows GNU cross-target compile gate with pnpm cargo:check:windows-gnu.
• The Phase 1 harness creates mode-0700 process-owned roots under the real OS temporary directory, reaps only tracked child processes, scans the completed SDK platform record for secrets and private content, and retains only test-results/phase1-conformance/report.json. See phase1-conformance.md.
• Coven conformance starts the real locked daemon and invokes Chat phase1-native-rpc command coven_health; it never uses coven daemon status or reimplements producer-owned peer/pipe identity checks.