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

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 as the REQUIRED_PLATFORM_INVARIANTS constant. This array defines the behavioral contract that every platform backend must satisfy:

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:

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:

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 and 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:

// 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:

// 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 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 and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}