# Platform Parity Invariants in pi‑computer‑use: Ensuring macOS and Windows Backend Consistency

> Discover platform parity invariants in pi-computer-use ensuring macOS and Windows backend consistency. Learn about seven strict invariants for cross-platform behavioral integrity.

- Repository: [injaneity/pi-computer-use](https://github.com/injaneity/pi-computer-use)
- Tags: architecture
- Published: 2026-07-16

---

**The pi‑computer‑use framework enforces seven strict platform parity invariants—state-scoped observations, bounded observation history, multi-root forest, progressive disclosure, atomic physical input, concurrent requests, and transactional batching—that both macOS and Windows backends must implement to ensure cross-platform behavioral consistency.**

The `pi‑computer‑use` repository by `injaneity` abstracts UI automation across operating systems through a shared architecture contract. Understanding the platform parity invariants between the macOS and Windows backends is essential for developers extending the framework or debugging conformance failures. These invariants, defined in the core architecture module, guarantee that regardless of the underlying platform, the system behaves identically regarding state management, observation limits, and input handling.

## The Seven Required Platform Parity Invariants

The canonical list of invariants resides in [`src/platform/architecture.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/architecture.ts) as the `REQUIRED_PLATFORM_INVARIANTS` constant. This array defines the behavioral contract that every platform backend must satisfy:

```ts
export const REQUIRED_PLATFORM_INVARIANTS = [
  "state-scoped-observations",
  "bounded-observation-history",
  "multi-root-forest",
  "progressive-disclosure",
  "atomic-physical-input",
  "concurrent-requests",
  "transactional-batching",
] as const;

```

Each invariant establishes a specific runtime guarantee:

- **state-scoped-observations** – Observations are strictly tied to a specific UI state, preventing cross-state leakage.
- **bounded-observation-history** – The observation store maintains a finite, capped history to manage memory consumption.
- **multi-root-forest** – Backends must support reporting multiple UI roots simultaneously (e.g., multiple windows).
- **progressive-disclosure** – UI outlines support folding and unfolding to respect computational budgets.
- **atomic-physical-input** – Mouse and keyboard actions execute atomically without partial states.
- **concurrent-requests** – The helper process must handle simultaneous requests, such as concurrent `act` calls.
- **transactional-batching** – Batches of actions process transactionally, ensuring all-or-nothing consistency.

## Runtime Validation with assertPlatformArchitecture

During startup, each backend reports diagnostics including `architectureVersion` and the `invariants` array it implements. The framework validates compliance through the `assertPlatformArchitecture` function in [`src/platform/architecture.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/architecture.ts):

```ts
export function assertPlatformArchitecture(platform: string, diagnostics: PlatformDiagnostics): void {
  // …version check omitted…
  const reported = new Set(diagnostics.invariants ?? []);
  const missing = REQUIRED_PLATFORM_INVARIANTS.filter(invariant => !reported.has(invariant));
  if (missing.length > 0) {
    throw new Error(`${platform} helper does not satisfy the shared computer-use contract: ${missing.join(", ")}.`);
  }
}

```

If a backend omits any required invariant, the function throws an error identifying the missing contracts, and the backend is considered non-conforming.

## Cross-Platform Verification Testing

The conformance of both macOS and Windows backends is verified in `scripts/check-platform-windows.mjs`. This script constructs diagnostic fixtures and asserts that removing any invariant triggers a contract violation:

```ts
const conforming = {
  protocolVersion: 1,
  pid: 1,
  architectureVersion: PLATFORM_ARCHITECTURE_VERSION,
  invariants: [...REQUIRED_PLATFORM_INVARIANTS],
};
assert.doesNotThrow(() => assertPlatformArchitecture("fixture", conforming));
assert.throws(
  () => assertPlatformArchitecture("fixture", { ...conforming, invariants: conforming.invariants.slice(1) }),
  /shared computer-use contract/,
);

```

This automated check ensures that both [`src/platform/macos/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/backend.ts) and [`src/platform/windows/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/backend.ts) maintain parity as the codebase evolves.

## Retrieving and Validating Backend Diagnostics

Both backends expose diagnostics through a unified interface. You can retrieve and verify these programmatically using the platform factory:

```ts
// Example: retrieving the invariants from a back-end diagnostics object
import { platformBackendForRuntime } from "./src/platform/index.ts";

const mac = platformBackendForRuntime("darwin");
const win = platformBackendForRuntime("win32");

// Both back-ends expose a `diagnostics` method (or similar) that yields:
const macDiagnostics = await mac.getDiagnostics();   // contains `invariants`
const winDiagnostics = await win.getDiagnostics();   // contains `invariants`

// Verify parity
import { REQUIRED_PLATFORM_INVARIANTS } from "./src/platform/architecture.ts";
function hasAllInvariants(diag) {
  const set = new Set(diag.invariants);
  return REQUIRED_PLATFORM_INVARIANTS.every(i => set.has(i));
}
console.log(hasAllInvariants(macDiagnostics)); // true
console.log(hasAllInvariants(winDiagnostics)); // true

```

For custom helper implementations, enforce compliance using the assertion utility:

```ts
// Example: enforcing invariants in a custom helper (Node.js side)
import { assertPlatformArchitecture } from "./src/platform/architecture.ts";

function validateHelperDiagnostics(name, diagnostics) {
  try {
    assertPlatformArchitecture(name, diagnostics);
    console.log(`${name} helper satisfies all platform invariants`);
  } catch (e) {
    console.error(e.message);
    process.exit(1);
  }
}

```

## Summary

- pi‑computer‑use defines seven non-negotiable platform parity invariants in [`src/platform/architecture.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/architecture.ts) that ensure behavioral consistency between macOS and Windows.
- The `REQUIRED_PLATFORM_INVARIANTS` array includes state-scoping, bounded history, multi-root support, progressive disclosure, atomic input, concurrency handling, and transactional batching.
- Runtime validation occurs through `assertPlatformArchitecture`, which throws if any backend omits required invariants.
- Cross-platform verification scripts in `scripts/check-platform-windows.mjs` automatically test conformance across operating systems.
- Both [`src/platform/macos/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/macos/backend.ts) and [`src/platform/windows/backend.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/windows/backend.ts) must report these invariants in their diagnostics to be considered conformant.

## Frequently Asked Questions

### What happens if a backend fails to report all platform parity invariants?

The `assertPlatformArchitecture` function throws an error indicating which specific invariants are missing, and the backend is deemed non-conforming. The error message references the "shared computer-use contract" and lists the omitted identifiers, preventing the system from initializing with an incompatible implementation.

### Are the platform parity invariants extensible for custom backends?

While the `REQUIRED_PLATFORM_INVARIANTS` constant defines the minimum contract, custom backends can report additional invariants in their diagnostics array. However, they must include all seven required identifiers exactly as defined in [`src/platform/architecture.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/platform/architecture.ts) to pass validation.

### How does pi‑computer‑use handle concurrent requests across platforms?

The **concurrent-requests** invariant requires that both macOS and Windows helper processes handle simultaneous `act` calls without race conditions. This ensures that multiple automation commands can execute in parallel while maintaining atomicity guarantees for individual physical input operations.

### What distinguishes bounded-observation-history from state-scoped-observations?

**state-scoped-observations** ensures that UI observations are isolated to specific application states, preventing data from leaking between contexts. **bounded-observation-history** imposes a hard limit on how many historical observations the system retains, ensuring memory usage remains predictable regardless of session duration.