peachsim 0.1.1625 → 0.1.1640

package/cli/pause-aware-timeout.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// the team machine load governor SIGSTOPs a job and records its pids in this
+// ledger (`{ [rootPid]: [{ pid, started_at_ms }] }`, `{}` when nothing is
+// held) until it resumes them. a plain setTimeout keeps running across that
+// hold, so a command the paused browser could not answer times out for load
+// it never caused. a deadline only stops advancing while the pid it waits on
+// is held; a dead or unrelated process never extends it.
+const LEDGER_PATH = path.join(
+  process.env.TM_HOME || path.join(os.homedir(), '.team-machine'),
+  'governor-pauses.json',
+)
+const TICK_MS = 500
+
+interface Timer {
+  hostPid: number
+  remaining: number
+  accountedAt: number
+  fire: () => void
+}
+
+const timers = new Set<Timer>()
+let poll: ReturnType<typeof setInterval> | undefined
+
+function pausedPids(): number[] {
+  try {
+    const ledger: Record<string, { pid: number }[]> = JSON.parse(
+      readFileSync(LEDGER_PATH, 'utf8'),
+    )
+    return Object.values(ledger).flatMap((procs) => procs.map((proc) => proc.pid))
+  } catch {
+    return []
+  }
+}
+
+// the pids in `paused` that are `rootPid` or descend from it, by ps ancestry.
+function heldRoots(paused: number[], roots: Set<number>): Set<number> {
+  const parents = new Map<number, number>()
+  for (const line of execFileSync('ps', ['-A', '-o', 'pid=,ppid='], {
+    encoding: 'utf8',
+  }).split('\n')) {
+    const [pid, ppid] = line.trim().split(/\s+/).map(Number)
+    if (pid && ppid !== undefined) parents.set(pid, ppid)
+  }
+  const held = new Set<number>()
+  for (const start of paused) {
+    for (let pid: number | undefined = start, hops = 0; pid && hops < 64; hops++) {
+      if (roots.has(pid)) {
+        held.add(pid)
+        break
+      }
+      pid = parents.get(pid)
+    }
+  }
+  return held
+}
+
+function tick() {
+  const now = Date.now()
+  const paused = pausedPids()
+  const held = paused.length
+    ? heldRoots(paused, new Set([...timers].map((timer) => timer.hostPid)))
+    : new Set<number>()
+  for (const timer of [...timers]) {
+    // each timer accounts only since its own creation or last accounting
+    if (!held.has(timer.hostPid)) timer.remaining -= now - timer.accountedAt
+    timer.accountedAt = now
+    if (timer.remaining <= 0) {
+      timers.delete(timer)
+      timer.fire()
+    }
+  }
+  if (timers.size === 0 && poll) {
+    clearInterval(poll)
+    poll = undefined
+  }
+}
+
+// like setTimeout, but the budget does not advance while the governor holds
+// `hostPid` (the browser host the command waits on) or a descendant paused.
+// one shared poll serves every timer. returns the clear function.
+export function setPauseAwareTimeout(
+  fn: () => void,
+  budgetMs: number,
+  hostPid: number | undefined,
+): () => void {
+  if (hostPid === undefined) {
+    const timer = setTimeout(fn, budgetMs)
+    return () => clearTimeout(timer)
+  }
+  const timer: Timer = { hostPid, remaining: budgetMs, accountedAt: Date.now(), fire: fn }
+  timers.add(timer)
+  if (!poll) {
+    poll = setInterval(tick, TICK_MS)
+  }
+  return () => {
+    timers.delete(timer)
+    if (timers.size === 0 && poll) {
+      clearInterval(poll)
+      poll = undefined
+    }
+  }
+}

package/cli/scene-video.ts

@@ -0,0 +1,89 @@
+import { writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { readSceneRecordingUpload } from 'peach-engine/remote-stream/scene-recording'
+import { launchReapedChrome } from '../../../scripts/lib/reap-browser'
+import {
+  ensurePlaywrightBrowser,
+  provisionPlaywright,
+} from './drivers/playwright-provisioning'
+
+// render the saved display stream in an isolated viewer. guest code never runs,
+// and capture time is independent of the machine that recorded the app.
+export async function renderSceneToVideo(options: {
+  scene: Uint8Array
+  shellUrl: string
+  output: string
+}): Promise<{
+  durationMs: number
+  frameCount: number
+  renderTimeMs: number
+  sizeBytes: number
+}> {
+  const { header } = await readSceneRecordingUpload(options.scene)
+  const resolved = await provisionPlaywright()
+  const installed = await ensurePlaywrightBrowser(resolved, true)
+  if (!installed.ok) throw new Error(installed.message)
+  const require = createRequire(import.meta.url)
+  const { chromium }: typeof import('playwright-core') = require(resolved.modulePath)
+  const browser = await launchReapedChrome((opts) => chromium.launch(opts), {
+    headless: true,
+    ...(installed.libraryPath
+      ? { env: { ...process.env, LD_LIBRARY_PATH: installed.libraryPath } }
+      : {}),
+  })
+  try {
+    const source = new URL(options.shellUrl)
+    const url = new URL(source.pathname, source.origin)
+    url.searchParams.set('device', header.peer.deviceProfile)
+    url.searchParams.set('colorScheme', header.peer.appearance)
+    for (const key of ['orientation']) {
+      const value = source.searchParams.get(key)
+      if (value) url.searchParams.set(key, value)
+    }
+    const sceneUrl = new URL('__scene_export.psr.gz', url).href
+    const page = await browser.newPage({
+      viewport: { width: 600, height: 1000 },
+      deviceScaleFactor: 3,
+    })
+    await page.route(sceneUrl, (route) =>
+      route.fulfill({
+        contentType: 'application/vnd.peach.scene-stream+gzip',
+        body: Buffer.from(options.scene),
+      }),
+    )
+    url.searchParams.set(
+      'remoteEngine',
+      JSON.stringify({ url: sceneUrl, expectedPeer: header.peer, autoplay: false }),
+    )
+    await page.goto(url.href)
+    await page
+      .locator('[data-sootsim-boot-splash="hidden"]')
+      .waitFor({ state: 'attached', timeout: 120_000 })
+    await page.waitForFunction(
+      () => !!window.SootSim?.bridges.recorder && !!window.SootSim.bridges.sceneStream,
+      undefined,
+      { timeout: 120_000 },
+    )
+    const result = await page.evaluate(async () => {
+      const recorder = window.SootSim?.bridges.recorder
+      if (!recorder) throw new Error('scene recorder bridge unavailable')
+      return recorder.renderScene()
+    })
+    const chunks: Buffer[] = []
+    let offset = 0
+    for (;;) {
+      const chunk = await page.evaluate(async (at) => {
+        return window.SootSim?.bridges.recorder?.getBlobBase64({ offset: at })
+      }, offset)
+      if (!chunk) throw new Error('scene render returned no video')
+      chunks.push(Buffer.from(chunk.data, 'base64'))
+      offset = chunk.offset
+      if (chunk.done) break
+    }
+    const video = Buffer.concat(chunks)
+    await writeFile(options.output, video)
+    return { ...result, sizeBytes: video.byteLength }
+  } finally {
+    await browser.close()
+  }
+}

package/cli/ws-bridge.ts

@@ -10,6 +10,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { WebSocket } from 'ws'
 import {
+  assertPeachPortEnvironment,
   DEFAULT_SOOTSIM_BRIDGE_PORT,
   resolveSootsimBridgePort,
 } from '../src/bridge-constants'
@@ -31,6 +32,7 @@ import {
   readCurrentSimId,
   saveCurrentSimId,
 } from './current-sim'
+import { setPauseAwareTimeout } from './pause-aware-timeout'
 import type { WsBridgeCommand } from '../src/bridge-contract'
 
 // --- bridge world resolution ---------------------------------------------
@@ -297,6 +299,7 @@ export function resolveBridgePortForPin(pin: {
  *  vs repo checkout) — invocation-path heuristics made `peach list` flap
  *  between worlds. */
 export function resolveDefaultBridgePort(): number {
+  assertPeachPortEnvironment(process.env)
   return resolveBridgeWorld().bridgePort
 }
 
@@ -330,9 +333,11 @@ export function printBridgeWorldNotice(
 export interface WsBridge {
   readonly plane?: 'local' | 'cloud'
   // `opts.timeoutMs` overrides the bridge-wide commandTimeoutMs for a single
-  // call — used for fast readiness probes so a dead/unresponsive sim fails in
-  // seconds instead of stalling the full command timeout.
-  send(cmd: WsBridgeCommand, opts?: { timeoutMs?: number }): Promise<any>
+  // call. defaultTimeoutMs supplies a probe cap unless --timeout was explicit.
+  send(
+    cmd: WsBridgeCommand,
+    opts?: { timeoutMs?: number; defaultTimeoutMs?: number },
+  ): Promise<any>
   // includeRetained appends the bridge's retained disconnected sims
   // (readyState 'closed' with disconnectCause) after the live ones. only
   // loss-reporting surfaces pass it; every other consumer keeps the
@@ -378,6 +383,7 @@ interface WsResponse {
 interface WsBridgeOptions {
   connectTimeoutMs?: number
   commandTimeoutMs?: number
+  explicitTimeout?: boolean
   simId?: string
   cliLabel?: string
   leaseScope?: 'connection'
@@ -452,12 +458,14 @@ export interface ParsedBridgeCliArgs {
   simId?: string
   simIdSource: 'flag' | 'saved' | 'none'
   commandTimeoutMs: number
+  explicitTimeout?: boolean
 }
 
 interface BridgeFlagState {
   wsPort: number
   explicitPort: boolean
   commandTimeoutMs: number
+  explicitTimeout?: boolean
   simId: string | undefined
   simIdSource: ParsedBridgeCliArgs['simIdSource']
 }
@@ -484,7 +492,10 @@ const BRIDGE_VALUE_FLAGS_TABLE: readonly {
   {
     names: ['--timeout'],
     apply: (state, value) => {
-      if (value !== undefined) state.commandTimeoutMs = Number(value)
+      if (value !== undefined) {
+        state.commandTimeoutMs = Number(value)
+        state.explicitTimeout = true
+      }
     },
   },
   {
@@ -570,10 +581,12 @@ export function parseBridgeCliArgs(
     simId: state.simId,
     simIdSource: state.simIdSource,
     commandTimeoutMs: state.commandTimeoutMs,
+    explicitTimeout: state.explicitTimeout,
   }
 }
 
 export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBridge {
+  assertPeachPortEnvironment(process.env)
   let nextId = 1
   const commandTimeoutMs = opts.commandTimeoutMs ?? 15000
   const pending = new Map<
@@ -745,7 +758,10 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
     async send(cmd, callOpts) {
       // NOTE: `opts` (the createBridge closure arg) carries simId; do not
       // shadow it with the per-call arg.
-      const effectiveTimeoutMs = callOpts?.timeoutMs ?? commandTimeoutMs
+      const effectiveTimeoutMs =
+        callOpts?.timeoutMs ??
+        (opts.explicitTimeout ? commandTimeoutMs : callOpts?.defaultTimeoutMs) ??
+        commandTimeoutMs
       const sendOnce = async (
         defaultSimId?: string,
         cmdOverride?: Record<string, any>,
@@ -754,30 +770,31 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
         if (terminalError) throw terminalError
         const id = nextId++
         return new Promise((resolve, reject) => {
-          const timeout = setTimeout(() => {
-            pending.delete(id)
-            reject(
-              new Error(
-                `command timed out after ${Math.round(effectiveTimeoutMs / 1000)}s`,
-              ),
-            )
-          }, effectiveTimeoutMs)
+          const payload = { ...(cmdOverride ?? cmd), id } as Record<string, any>
+          if (payload.simId === undefined && defaultSimId) {
+            payload.simId = defaultSimId
+          }
+
+          const clearTimeoutFn = setPauseAwareTimeout(
+            () => {
+              pending.delete(id)
+              reject(new Error(`command timed out after ${effectiveTimeoutMs / 1000}s`))
+            },
+            effectiveTimeoutMs,
+            lineageBySimId.get(payload.simId)?.hostPid,
+          )
 
           pending.set(id, {
             resolve: (v) => {
-              clearTimeout(timeout)
+              clearTimeoutFn()
               resolve(v)
             },
             reject: (e) => {
-              clearTimeout(timeout)
+              clearTimeoutFn()
               reject(e)
             },
           })
 
-          const payload = { ...(cmdOverride ?? cmd), id } as Record<string, any>
-          if (payload.simId === undefined && defaultSimId) {
-            payload.simId = defaultSimId
-          }
           maybeNoticeTarget(payload.type ?? '', payload.simId)
           ws.send(JSON.stringify(payload))
         })
@@ -946,6 +963,7 @@ export function createBridgeFromParsed(parsed: ParsedBridgeCliArgs): WsBridge {
   if (cloudBridge) return cloudBridge
   const options = {
     commandTimeoutMs: parsed.commandTimeoutMs,
+    explicitTimeout: parsed.explicitTimeout,
     simId: parsed.simId,
     simIdSource: parsed.simIdSource,
   }

package/detox/attempt-events.cjs

@@ -43,6 +43,15 @@ function proofBoundPath(root, relative) {
   return resolved
 }
 
+// lifecycle receipts bind every clock and census read to the retained bytes.
+function boundText(root, relative, sha256, label) {
+  const bytes = fs.readFileSync(proofBoundPath(root, relative))
+  if (proofByteHash(bytes) !== sha256)
+    throw new Error(`${label} does not match its recorded hash`)
+  return bytes.toString('utf8')
+}
+module.exports.boundText = boundText
+
 function authenticateDiscreteFrameAsset(root, declaration, calibrate = false) {
   const cadence = parseDiscreteFrameCadence(declaration)
   const fixture = fs.readFileSync(proofBoundPath(root, cadence.asset.fixturePath))
@@ -125,6 +134,10 @@ function beginDiscreteFrameCapture({
 }) {
   if (target.startsWith('android'))
     throw new Error('discrete frame cadence is uncalibrated on Android')
+  if (!fs.existsSync(path.join(root, 'capture-context.json')))
+    throw new Error(
+      `discrete frame cadence needs an attempt minted by the paired proof capture (bun run test:conformance:proof); ${root} has no capture-context.json`,
+    )
   const attempt = JSON.parse(
     fs.readFileSync(path.join(root, 'capture-context.json'), 'utf8'),
   )
@@ -318,13 +331,21 @@ function authenticateNativeCadenceCensus(root, sourceRoot, life, decoded) {
       )
   )
     throw new Error('native cadence has no source-matched framebuffer consumer')
-  const frames = fs
-    .readFileSync(proofBoundPath(root, native.receipt), 'utf8')
+  const frames = boundText(
+    root,
+    native.receipt,
+    native.receiptSha256,
+    'native cadence source receipt',
+  )
     .trim()
     .split('\n')
     .map(JSON.parse)
-  const media = fs
-    .readFileSync(proofBoundPath(root, native.mediaFrames), 'utf8')
+  const media = boundText(
+    root,
+    native.mediaFrames,
+    native.mediaFramesSha256,
+    'native cadence presentation census',
+  )
     .trim()
     .split('\n')
     .map(JSON.parse)
@@ -335,11 +356,34 @@ function authenticateNativeCadenceCensus(root, sourceRoot, life, decoded) {
     requireNativeRawFrame,
   } = require('../../peach-conformance/e2e/utils/native-frame-receipt.cjs')
   const rawRoot = path.dirname(proofBoundPath(root, native.receipt))
+  // a callback whose frame a newer one overwrote mid-read keeps no bytes; its
+  // superseded receipt fills exactly the gap it leaves in the callback order
+  const superseded = new Set(
+    boundText(
+      root,
+      native.superseded,
+      native.supersededSha256,
+      'native cadence superseded receipt',
+    )
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const row = JSON.parse(line)
+        if (
+          !Number.isSafeInteger(row.callbackIndex) ||
+          row.seedBeforeRead === row.seedAfterRead
+        )
+          throw new Error('native superseded receipt is not an overwritten read')
+        return row.callbackIndex
+      }),
+  )
   const origin = frames[0].consumerArrival
+  let expectedCallback = 0
   for (const [index, frame] of frames.entries()) {
+    while (superseded.delete(expectedCallback)) expectedCallback++
     const clock = frame.consumerArrival
     if (
-      frame.callbackIndex !== index ||
+      frame.callbackIndex !== expectedCallback++ ||
       media[index].sourceFrameIndex !== index ||
       !clock ||
       clock.domain !== 'host-mach-absolute-time' ||
@@ -370,6 +414,9 @@ function authenticateNativeCadenceCensus(root, sourceRoot, life, decoded) {
       ),
     )
   }
+  while (superseded.delete(expectedCallback)) expectedCallback++
+  if (superseded.size)
+    throw new Error('native superseded receipts fall outside the callback order')
 }
 
 function readDiscreteFrameReceipt(root, sourceRoot, reference, expected) {
@@ -706,9 +753,23 @@ function discreteFrameEvidenceFiles(root, evidence) {
       const life = JSON.parse(
         fs.readFileSync(proofBoundPath(root, receipt.lifecycle.path), 'utf8'),
       )
+      // the app's ui frame clock and delivered input are replayed from their
+      // own receipts, so their bytes travel bound to the hashes the lifecycle
+      // recorded
+      for (const [label, auxiliary] of [
+        ['ui frame clock', life.uiFrameClock],
+        ['delivered input', life.deliveredUIKitInput],
+      ]) {
+        if (!auxiliary) continue
+        const bytes = fs.readFileSync(proofBoundPath(root, auxiliary.sourceReceipt))
+        if (proofByteHash(bytes) !== auxiliary.sourceReceiptSha256)
+          throw new Error(`native ${label} receipt does not match its recorded hash`)
+        paths.add(auxiliary.sourceReceipt)
+      }
       const native = life.nativeFramebuffer
       if (native) {
         paths.add(native.receipt)
+        paths.add(native.superseded)
         paths.add(native.mediaFrames)
         const rows = fs
           .readFileSync(proofBoundPath(root, native.receipt), 'utf8')

package/detox/attempt-events.d.cts

@@ -104,3 +104,10 @@ export function writeDiscreteFrameReceipt(
   context: DiscreteProofContext,
   trace: DiscreteFrameTrace,
 ): DiscreteProofReference
+
+export function boundText(
+  root: string,
+  relative: string,
+  sha256: string,
+  label: string,
+): string

package/detox/expectations.ts

@@ -54,8 +54,12 @@ export function isNodeVisible(node: SootSimNodeInfo | null | undefined): boolean
 }
 
 // a native host is focused when its editor child holds focus.
-export function focusIsWithin(focused: SootSimFocusedNodeInfo, nodeId: number): boolean {
-  return focused.nodeId === nodeId || focused.ancestorNodeIds.includes(nodeId)
+export function focusIsWithin(
+  focused: SootSimFocusedNodeInfo,
+  node: SootSimNodeInfo,
+): boolean {
+  const nativeNodeId = node.nativeTag ?? node.nodeId
+  return focused.nodeId === nativeNodeId || focused.ancestorNodeIds.includes(nativeNodeId)
 }
 
 // the engine owns focus for canvas inputs and hosted native editors.
@@ -64,7 +68,7 @@ export async function isTextInputNodeFocused(
   page: Page,
 ): Promise<boolean> {
   const focused = await page.evaluate(async () => window.__sootsimTest!.getFocusedNode())
-  return focused !== null && focusIsWithin(focused, node.nodeId)
+  return focused !== null && focusIsWithin(focused, node)
 }
 
 async function isNodeFocused(node: SootSimNodeInfo, page: Page): Promise<boolean> {