CR: feat/biometrics-calibration

.github/workflows/mutation.yml

@@ -59,6 +59,8 @@ jobs:
             mutate: "src/streaming/**/*.ts,!src/**/tests/**,!src/**/*.test.ts,!src/**/*.test.tsx,!src/**/*.d.ts"
           - name: hooks
             mutate: "src/hooks/**/*.ts,src/hooks/**/*.tsx,!src/**/tests/**,!src/**/*.test.ts,!src/**/*.test.tsx,!src/**/*.d.ts"
+          - name: biometrics
+            mutate: "src/biometrics/**/*.ts,!src/**/tests/**,!src/**/*.test.ts,!src/**/*.test.tsx,!src/**/*.d.ts"
           - name: db
             mutate: "src/db/**/*.ts,!src/**/tests/**,!src/**/*.test.ts,!src/**/*.test.tsx,!src/**/*.d.ts"
     name: mutate (${{ matrix.shard.name }})

.github/workflows/python-modules.yml

@@ -5,6 +5,8 @@ on:
     branches: [dev]
     paths:
       - 'modules/**/*.py'
+      - 'modules/common/biometrics/*.json'
+      - 'modules/piezo-processor/fixtures/*.json'
       - 'modules/**/pyproject.toml'
       - 'modules/**/uv.lock'
       - 'modules/.coveragerc'
@@ -14,6 +16,8 @@ on:
     types: [opened, synchronize, reopened]
     paths:
       - 'modules/**/*.py'
+      - 'modules/common/biometrics/*.json'
+      - 'modules/piezo-processor/fixtures/*.json'
       - 'modules/**/pyproject.toml'
       - 'modules/**/uv.lock'
       - 'modules/.coveragerc'
@@ -50,9 +54,9 @@ jobs:
             workdir: modules
             target: common
             cov_source: common
-            # cbor2 is needed to decode the real NATS capture fixtures through
-            # NatsFollower's decode path (test_nats_follower).
-            deps: "cbor2"
+            # Build-identity tests inspect installed NumPy/SciPy metadata;
+            # use the piezo module's locked environment, including cbor2.
+            deps: ""
           - name: cover-buttons
             workdir: modules/cover-buttons
             target: .
@@ -72,6 +76,7 @@ jobs:
             workdir: modules/piezo-processor
             target: .
             cov_source: .
+            cov_extra: "--cov=../common/biometrics"
             deps: "numpy scipy"
           - name: sleep-detector
             workdir: modules/sleep-detector
@@ -95,7 +100,7 @@ jobs:
         with:
           # Pod runtime is pinned to 3.10 by every module's pyproject
           # (`requires-python = ">=3.9,<3.11"`). Match it in CI.
-          python-version: '3.14'
+          python-version: '3.10'
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
@@ -105,7 +110,10 @@ jobs:
       - name: Install test deps
         working-directory: ${{ matrix.module.workdir }}
         run: |
-          if [ -f uv.lock ]; then
+          if [ "${{ matrix.module.name }}" = "common" ]; then
+            # Keep common's cwd/import layout while using the numerical lock.
+            UV_PROJECT_ENVIRONMENT="$PWD/.venv" uv sync --project piezo-processor --locked --no-install-project
+          elif [ -f uv.lock ]; then
             uv sync --locked --no-install-project
           else
             uv venv .venv
@@ -125,6 +133,7 @@ jobs:
           pytest ${{ matrix.module.target }} \
             --cov-config=${{ github.workspace }}/modules/.coveragerc \
             --cov=${{ matrix.module.cov_source }} \
+            ${{ matrix.module.cov_extra }} \
             --cov-report=xml:coverage.xml \
             --junit-xml=junit.xml \
             -o junit_family=legacy

.github/workflows/test.yml

@@ -29,6 +29,7 @@ jobs:
           - { name: "Lint", cmd: "CHANGED=$(git diff --name-only --diff-filter=d origin/${BASE_REF#refs/heads/}...HEAD -- '*.ts' '*.tsx' | head -200); if [ -n \"$CHANGED\" ]; then echo \"$CHANGED\" | xargs -d '\\n' pnpm eslint --; else echo 'No TS/TSX files changed'; fi" }
           - { name: "Typecheck", cmd: "pnpm tsc" }
           - { name: "Unit Tests", cmd: "pnpm test run --coverage --passWithNoTests" }
+          - { name: "Browser Tests", cmd: "NODE_ENV=production CI=1 pnpm build && pnpm test:browser" }
 
     steps:
       - name: Checkout
@@ -51,6 +52,27 @@ jobs:
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Setup Python for runtime integration
+        if: matrix.task.name == 'Unit Tests' || matrix.task.name == 'Browser Tests'
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+
+      - name: Setup uv for runtime integration
+        if: matrix.task.name == 'Unit Tests' || matrix.task.name == 'Browser Tests'
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install locked runtime integration dependencies
+        if: matrix.task.name == 'Unit Tests' || matrix.task.name == 'Browser Tests'
+        working-directory: modules/piezo-processor
+        run: uv sync --locked --no-install-project
+
+      - name: Install browser
+        if: matrix.task.name == 'Browser Tests'
+        run: pnpm exec playwright install --with-deps chromium
+
       - name: Cache Assets (Vitest)
         id: asset-cache
         uses: actions/cache@v5
@@ -89,4 +111,12 @@ jobs:
           fail_ci_if_error: false
           slug: sleepypod/core
           files: test-results/junit.xml
-          flags: javascript
+          flags: javascript
+
+      - name: Upload browser evidence
+        if: matrix.task.name == 'Browser Tests' && !cancelled()
+        uses: actions/upload-artifact@v6
+        with:
+          name: calibration-browser-results
+          path: test-results/browser
+          retention-days: 7

app/api/raw/[filename]/route.ts

@@ -20,26 +20,26 @@ export async function GET(
   }
 
   const resolved = path.resolve(RAW_DIR, filename)
-  if (!resolved.startsWith(path.resolve(RAW_DIR))) {
+  if (!resolved.startsWith(path.resolve(/* turbopackIgnore: true */ RAW_DIR))) {
     return NextResponse.json({ error: 'Path traversal detected' }, { status: 400 })
   }
 
   try {
     // Reject symlinks to prevent escaping RAW_DIR
-    const lstats = await lstat(resolved)
+    const lstats = await lstat(/* turbopackIgnore: true */ resolved)
     if (lstats.isSymbolicLink()) {
       return NextResponse.json({ error: 'Path traversal detected' }, { status: 400 })
     }
 
     // Verify canonical path is still inside RAW_DIR
-    const canonicalFile = await realpath(resolved)
-    const canonicalDir = await realpath(RAW_DIR)
+    const canonicalFile = await realpath(/* turbopackIgnore: true */ resolved)
+    const canonicalDir = await realpath(/* turbopackIgnore: true */ RAW_DIR)
     if (!canonicalFile.startsWith(canonicalDir)) {
       return NextResponse.json({ error: 'Path traversal detected' }, { status: 400 })
     }
 
-    const s = await stat(resolved)
-    const stream = createReadStream(resolved)
+    const s = await stat(/* turbopackIgnore: true */ resolved)
+    const stream = createReadStream(/* turbopackIgnore: true */ resolved)
     const webStream = Readable.toWeb(stream) as ReadableStream
 
     return new Response(webStream, {

app/api/raw/[filename]/tests/route.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment node
+import { Readable } from 'node:stream'
+import { beforeEach, expect, it, vi } from 'vitest'
+import { GET } from '../route'
+const fs = vi.hoisted(() => ({ lstat: vi.fn(), realpath: vi.fn(), stat: vi.fn(), createReadStream: vi.fn() }))
+vi.mock('node:fs/promises', () => ({ lstat: fs.lstat, realpath: fs.realpath, stat: fs.stat }))
+vi.mock('node:fs', () => ({ createReadStream: fs.createReadStream }))
+const request = (filename = 'capture.RAW') => GET(new Request('http://localhost/api/raw/' + filename), { params: Promise.resolve({ filename }) })
+beforeEach(() => {
+  vi.resetAllMocks()
+  fs.lstat.mockResolvedValue({ isSymbolicLink: () => false })
+  fs.realpath.mockImplementation(async (path: string) => path)
+  fs.stat.mockResolvedValue({ size: 3 })
+  fs.createReadStream.mockImplementation(() => Readable.from([Buffer.from([1, 2, 3])]))
+})
+it('streams the original bytes with explicit download metadata', async () => {
+  const response = await request()
+  expect(response.status).toBe(200)
+  expect(response.headers.get('Content-Type')).toBe('application/octet-stream')
+  expect(response.headers.get('Content-Disposition')).toBe('attachment; filename="capture.RAW"')
+  expect(response.headers.get('Content-Length')).toBe('3')
+  expect(new Uint8Array(await response.arrayBuffer())).toEqual(new Uint8Array([1, 2, 3]))
+})
+it.each(['../private.RAW', 'nested/capture.RAW', 'capture.txt', 'capture.RAW\n'])('rejects invalid filename %s before filesystem access', async (filename) => {
+  expect((await request(filename)).status).toBe(400)
+  expect(fs.lstat).not.toHaveBeenCalled()
+  expect(fs.createReadStream).not.toHaveBeenCalled()
+})
+it('refuses symbolic links and canonical paths outside the configured directory', async () => {
+  fs.lstat.mockResolvedValueOnce({ isSymbolicLink: () => true })
+  expect((await request()).status).toBe(400)
+  expect(fs.realpath).not.toHaveBeenCalled()
+  fs.realpath.mockResolvedValueOnce('/outside/capture.RAW').mockResolvedValueOnce('/owned')
+  expect((await request()).status).toBe(400)
+  expect(fs.createReadStream).not.toHaveBeenCalled()
+})
+it.each([['ENOENT', 404, 'File not found'], ['EACCES', 500, 'Failed to read file']] as const)('sanitizes %s filesystem failures', async (code, status, error) => {
+  fs.lstat.mockRejectedValue(Object.assign(new Error('/private/source'), { code }))
+  const response = await request()
+  expect(response.status).toBe(status)
+  expect(await response.json()).toEqual({ error })
+  expect(fs.createReadStream).not.toHaveBeenCalled()
+})

docs/DEPLOYMENT.md

@@ -293,3 +293,19 @@ sudo bash /tmp/sleepypod-install --purge-free-sleep
 It also flushes the running iptables and ip6tables rules; the install then reconfigures iptables itself. Without the flag, run the cleanup block the installer prints, reboot, and re-run the installer. free-sleep's `unblock_internet_access.sh` is not a substitute: it flushes runtime rules only and leaves the persisted files in place.
 
 Run `sp-uninstall` if you want to revert (the script flushes iptables and removes sleepypod's units); the purge is not undone, so reinstall free-sleep from its own installer.
+
+
+### Runtime filesystem reads and standalone tracing
+
+Pod data (RAW captures, saved alarm state, HomeKit identity seeds, archive-push
+configuration, procfs and storage-accounting paths) is read on the destination
+pod. These dynamic filesystem reads use `turbopackIgnore` call annotations so
+Next does not infer that the build machine's whole checkout belongs in the
+standalone output. The annotations affect packaging only; existing validation,
+file access and error handling still run on the pod.
+
+The biometrics worker location probes are also excluded from automatic tracing:
+`scripts/build/biometrics-worker.mjs` explicitly generates `worker.cjs`,
+`coordinator.cjs` and `shadow-host.cjs` in the standalone bundle after Next builds.
+Keep that packaging step and its dependency-graph checks when changing tracing.
+Do not apply these annotations to shipped assets that need inclusion in a release.