@gotcos/glasses-server 6.25.0 → 6.27.0

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+## 6.27.0
+
+### Video review frames: 8-16 stills instead of 1-3
+
+A video attachment is summarized from stills. The old rule was one still per 15
+seconds, floored at 1 and capped at 8, which gave a 12 second clip **one** frame
+and a 44 second clip **three** - not enough to tell what a video contains. Miles,
+on a fridge sweep: "it only selects three chunks from the video."
+
+- Frame count is now `clamp(round(seconds / 6), 8, 16)`. A 12s clip and a 44s
+  clip both get 8; a 72s clip gets 12; anything past 96s gets 16.
+- Each frame is the **sharpest** of 5 candidates sampled around its position,
+  ranked by encoded JPEG size at fixed quality. Measured on real footage the
+  spread within one second was 1.45x, and the large frame read product label
+  text that the small one rendered as smear.
+- Candidate count is `frames * 5`, so a 20 minute recording costs the same temp
+  I/O as a 12 second one - the sampling rate adapts, the work does not grow.
+- Fixed an upscale: `scale=1280:-2` was enlarging a 480x360 source to 1280x960,
+  paying roughly 7x the image tokens for detail that was never captured. Now
+  `scale='min(1280,iw)':-2`, so small sources pass through at native size.
+- `MAX_DERIVATIVE_IMAGES` (8) is untouched, so PDF page extraction is unchanged.
+  Video no longer shares that constant.
+
+## 6.26.0
+
+Chunked, resumable upload: video is no longer limited by what fits in one request.
+
+- A video can now be uploaded in pieces, so length is bounded by storage rather than by a
+  single request. A 3-minute 4K clip is roughly 570 MB and could never fit a one-shot
+  limit; it now transfers as a sequence of 8 MiB chunks, losslessly, and is compressed
+  afterwards for storage.
+- Interrupted uploads resume. The phone asks the server what it actually received and
+  continues from there rather than trusting its own count, because a chunk whose
+  acknowledgement was lost makes the client's number wrong. Resume covers network drops,
+  which is the common case; a server restart clears in-flight uploads and the phone starts
+  over cleanly rather than resuming onto nothing.
+- Cancelling or giving up releases the server's slot and staging disk immediately instead
+  of holding them for four hours. Without this, a handful of give-ups on a poor connection
+  could make new uploads unavailable until the sessions expired.
+- Assembly is verified before anything is published: the reassembled size must match what
+  the phone declared, a chunk that arrives out of order is refused rather than appended,
+  and a partial write is rejected rather than producing a correctly-sized file with a hole
+  in it.
+- Finalizing a chunked upload runs the same validation, size cap, atomic publish and
+  background compression as a single-shot upload — one path, so the safety rules cannot
+  drift between them. Only video is allowed the larger chunked ceiling; documents and
+  images keep the existing limit, because reading a multi-gigabyte text file into memory
+  would fail in a far worse way than refusing it.
+- `GET /api/health` advertises chunked availability and the chunk size, so the phone
+  decides from what this server actually supports rather than from a built-in assumption.
+
 ## 6.25.0
 
 Large video uploads: a 100 MiB cap, streamed to disk, compressed in the background.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.25.0",
+  "version": "6.27.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/lib/media-store.ts

@@ -55,6 +55,7 @@ import {
 } from './image-safety.js'
 import {
   prepareRichMediaFromFile,
+  type MediaTransferMode,
   type PreparedRichMediaFile,
 } from './rich-media-safety.js'
 import { VIDEO_COMPRESSION_LABEL, compressVideoFile } from './video-compression.js'
@@ -230,6 +231,10 @@ export interface IngestRichMediaFileInput {
   declaredMime?: string
   capturedAt?: string
   sessionId?: string
+  /** How the bytes arrived. Omitted means single_shot, so /api/media/file keeps its
+   *  existing ceiling; chunked finalize passes 'chunked' so a multi-hundred-MB video
+   *  is judged against the chunked cap instead of being refused AFTER transfer. */
+  transfer?: MediaTransferMode
 }
 
 /** Handle for a streaming upload's staging file. `dispose()` is idempotent and
@@ -520,6 +525,10 @@ export class MediaStore {
       label: input.label,
       declaredMime: input.declaredMime,
       byteLength: input.byteLength,
+      // Chunked finalize must be judged against the chunked ceiling, not the
+      // single-shot one it used to inherit. Defaults to single_shot, so
+      // /api/media/file is unchanged.
+      transfer: input.transfer,
     })
     return this.publishPreparedRichMedia(input, prepared)
   }

package/server/lib/rich-media-safety.ts

@@ -14,6 +14,7 @@ import {
   readSync,
   readdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -44,6 +45,76 @@ export const MEDIA_SNIFF_BYTES = 12
 export const MAX_DOCUMENT_TEXT_CHARS = 100_000
 export const MAX_VIDEO_DURATION_MS = 20 * 60_000
 export const MAX_DERIVATIVE_IMAGES = 8
+
+// ── Video summary frames ────────────────────────────────────────────────────────
+// DELIBERATELY SEPARATE from MAX_DERIVATIVE_IMAGES, which the PDF path also uses
+// (pdftoppm -l): raising that shared constant would silently give every PDF 16 pages.
+//
+// What was here: min(8, max(1, ceil(durationMs / 15_000))) — one frame per 15 seconds,
+// capped at 8. Measured against real assets that produced:
+//   11.7s 4K clip     ->  1 frame
+//   43.6s fridge sweep ->  3 frames   (Msg 796: "I only got 3 samples")
+//   20 min (the cap)  ->  8 frames, one per 2.5 MINUTES
+// A 12-second video summarised by a single still is not a summary, and 3 frames missed
+// the entire contents of a refrigerator the user was asking about.
+export const VIDEO_SUMMARY_FRAMES_MIN = 8
+export const VIDEO_SUMMARY_FRAMES_MAX = 16
+/** One frame per ~6s of footage, between the floor and the ceiling. */
+const VIDEO_SUMMARY_SECONDS_PER_FRAME = 6
+/** Candidates sampled per window; the sharpest one is kept. More candidates cost
+ *  only temp I/O, but the search is pointless beyond a handful per window. */
+export const VIDEO_SUMMARY_CANDIDATES_PER_FRAME = 5
+
+/**
+ * How many stills represent a video.
+ *
+ * Uniform intervals, not random: random sampling clusters and leaves gaps, while a
+ * uniform grid provably covers start to finish and is reproducible across runs — which
+ * matters when the same video is asked about twice.
+ *
+ * 12 frames is the target for a typical clip: roughly one per 8% of the runtime, about
+ * 15K tokens at 1280px wide, leaving room for a transcript and the question in one turn.
+ * Below the floor of 8 whole segments go unseen; above the ceiling of 16 the marginal
+ * still adds little to a SUMMARY and that budget is better spent on a targeted
+ * native-resolution pass over a named time window.
+ */
+export function videoSummaryFrameCount(durationMs: number): number {
+  const seconds = Number.isFinite(durationMs) ? Math.max(0, durationMs) / 1000 : 0
+  const scaled = Math.round(seconds / VIDEO_SUMMARY_SECONDS_PER_FRAME)
+  return Math.min(VIDEO_SUMMARY_FRAMES_MAX, Math.max(VIDEO_SUMMARY_FRAMES_MIN, scaled))
+}
+
+/**
+ * Pick the sharpest candidate in each window, by encoded JPEG size.
+ *
+ * At a FIXED quality setting, a sharper frame carries more high-frequency detail and
+ * therefore encodes larger; a motion-blurred one compresses down. Measured on the real
+ * 480x360 fridge sweep: within one second the spread was 1.45x (27,311 vs 18,852 bytes),
+ * and inspecting both ends confirmed it — the largest frame reads "Mootopia WHOLE / 13g /
+ * LACTOSE FREE" and the smallest is unreadable smear. Those are the exact labels that
+ * previously required a manual frame-by-frame pass to recover.
+ *
+ * This is a proxy, not a Laplacian: it needs no image library, no new dependency, and one
+ * ffmpeg pass. It can be fooled by a window where the sharp frames are also the emptiest,
+ * which costs a slightly worse still rather than a wrong answer.
+ */
+export function pickSharpestPerWindow(
+  candidates: readonly { name: string; bytes: number }[],
+  windows: number,
+): string[] {
+  if (candidates.length === 0 || windows <= 0) return []
+  const ordered = [...candidates].sort((a, b) => a.name.localeCompare(b.name))
+  const perWindow = Math.max(1, Math.floor(ordered.length / windows))
+  const picked: string[] = []
+  for (let w = 0; w < windows; w++) {
+    const start = w * perWindow
+    // The final window absorbs any remainder, so no candidate is silently dropped.
+    const slice = w === windows - 1 ? ordered.slice(start) : ordered.slice(start, start + perWindow)
+    if (slice.length === 0) continue
+    picked.push(slice.reduce((best, c) => (c.bytes > best.bytes ? c : best), slice[0]).name)
+  }
+  return picked
+}
 const PROCESS_STDERR_MAX = 8_192
 const PROCESS_TIMEOUT_MS = 30_000
 
@@ -364,15 +435,25 @@ async function processVideo(
     if (durationMs > MAX_VIDEO_DURATION_MS) {
       throw new RichMediaSafetyError('video_too_long', `video exceeds ${MAX_VIDEO_DURATION_MS / 60_000} minute limit`)
     }
-    const frameCount = Math.min(MAX_DERIVATIVE_IMAGES, Math.max(1, Math.ceil(durationMs / 15_000)))
-    const fps = Math.max(0.001, frameCount / (durationMs / 1000))
+    // Uniform windows across the whole runtime, then the SHARPEST candidate in each.
+    // Sampling candidates at a duration-derived rate keeps the total constant no matter
+    // how long the video is: a 20-minute recording costs the same temp I/O as a 12-second
+    // one, in ONE ffmpeg pass.
+    const frameCount = videoSummaryFrameCount(durationMs)
+    const candidateCount = frameCount * VIDEO_SUMMARY_CANDIDATES_PER_FRAME
+    const fps = Math.max(0.001, candidateCount / (durationMs / 1000))
     await runProcess('ffmpeg', [
       '-nostdin', '-v', 'error', '-i', input,
-      '-vf', `fps=${fps.toFixed(6)},scale=1280:-2:force_original_aspect_ratio=decrease`,
-      '-frames:v', String(frameCount), '-q:v', '3', join(work, 'frame-%02d.jpg'),
+      // min(1280,iw) rather than a bare 1280: the old filter UPSCALED a 480x360 source to
+      // 1280x960, paying ~7x the image tokens for detail that was never captured. It only
+      // ever downscales now.
+      '-vf', `fps=${fps.toFixed(6)},scale='min(1280,iw)':-2`,
+      '-frames:v', String(candidateCount), '-q:v', '3', join(work, 'cand-%04d.jpg'),
     ])
-    const frames = readdirSync(work)
-      .filter(name => /^frame-\d+\.jpg$/i.test(name)).sort().slice(0, MAX_DERIVATIVE_IMAGES)
+    const candidates = readdirSync(work)
+      .filter(name => /^cand-\d+\.jpg$/i.test(name))
+      .map(name => ({ name, bytes: statSync(join(work, name)).size }))
+    const frames = pickSharpestPerWindow(candidates, frameCount)
       .map(name => readFileSync(join(work, name)))
     if (frames.length === 0) throw new RichMediaSafetyError('corrupt_attachment', 'video produced no review frames')
     const mime: PreparedVideoFile['mime'] = declaredMime === 'video/quicktime' || ext === '.mov'
@@ -390,16 +471,47 @@ async function processVideo(
 /** Production entry point: validate an already-staged upload file in place.
  *  The returned `originalPath` is the caller's own staged file — this module
  *  never moves, renames, or deletes it. */
+/**
+ * How the bytes arrived. This decides the ceiling, and it has to be threaded in
+ * rather than assumed.
+ *
+ * THE DEFECT THIS FIXES. finalize for a chunked upload calls this same function —
+ * deliberately, so validation, the cap, the atomic rename and compression are not
+ * forked. But it inherited the SINGLE-SHOT cap, so a 200 MB video transferred all
+ * 25 chunks and was then refused at finalize with a raw 413. That is worse than the
+ * feature not existing: before it, the same file was refused in milliseconds with a
+ * readable message. Two independent reviewers found this, and the suite already
+ * contained the proof (prepareRichMediaFromFile rejects above the cap) without ever
+ * wiring it to the chunked route.
+ */
+export type MediaTransferMode = 'single_shot' | 'chunked'
+
+/**
+ * The applicable ceiling. Per-kind on purpose, and NOT a flat chunked number.
+ *
+ * Only VIDEO gets the chunked ceiling. Documents and images stay at the single-shot
+ * cap even when chunked, because the text path does
+ * `capText(decodeStrictUtf8(readFileSync(sourcePath)))` — a whole-file Buffer plus a
+ * whole-file JS string. A 2 GiB .txt would allocate 2 GiB and then throw
+ * ERR_STRING_TOO_LONG at V8's ~512 MB string limit, inside the request, in the
+ * process that also owns the G2 bridge and whisper. Streaming the upload only to
+ * blow up reading it back would defeat the entire point of the rewrite.
+ */
+export function mediaCeilingBytes(isVideo: boolean, transfer: MediaTransferMode = 'single_shot'): number {
+  if (!isVideo) return MAX_OTHER_MEDIA_BYTES
+  return transfer === 'chunked' ? MAX_CHUNKED_MEDIA_BYTES : MAX_VIDEO_MEDIA_BYTES
+}
+
 export async function prepareRichMediaFromFile(
   sourcePath: string,
-  options: { label?: string; declaredMime?: string; byteLength: number },
+  options: { label?: string; declaredMime?: string; byteLength: number; transfer?: MediaTransferMode },
 ): Promise<PreparedRichMediaFile> {
   if (options.byteLength === 0) throw new RichMediaSafetyError('corrupt_attachment', 'attachment is empty')
   const head = readHead(sourcePath)
   // Two caps now, so the cap check has to know WHAT it is looking at. The
   // classification is byte-authoritative for exactly that reason.
   const isVideo = isVideoUploadHead(head)
-  const cap = isVideo ? MAX_VIDEO_MEDIA_BYTES : MAX_OTHER_MEDIA_BYTES
+  const cap = mediaCeilingBytes(isVideo, options.transfer)
   if (options.byteLength > cap) {
     throw new RichMediaSafetyError('attachment_too_large', `attachment exceeds ${cap} byte limit`)
   }

package/server/lib/upload-session.ts

@@ -0,0 +1,409 @@
+// Chunked upload sessions (contract §2 wire shape, §6 v1 decisions).
+//
+// A chunked upload is ONE staging file appended across many requests, then handed
+// to the EXISTING ingest. This module owns only the bookkeeping — which upload,
+// how many bytes are committed, which index comes next, when it expires. It never
+// validates media, never writes into assets/, and never ingests: forking any of
+// that would be a second place for the safety rules to rot (contract §6).
+//
+// Time and filesystem are injectable so the route tests can drive expiry and a
+// failed write without real timers or a real disk fault. media-store.ts already
+// uses that constructor-dependency style for compressVideoFile.
+
+import { randomBytes } from 'node:crypto'
+import { closeSync, ftruncateSync, openSync, statSync, writeSync } from 'node:fs'
+import { getMediaStore, STAGED_TTL_MS, type MediaStagingFile } from './media-store.js'
+import { MAX_CHUNKED_MEDIA_BYTES, MEDIA_CHUNK_BYTES } from './rich-media-safety.js'
+
+/** An in-flight chunked upload IS an unsubmitted upload, so it retires on the
+ *  same retention clock as one — contract §2, "expire on the existing
+ *  quarantine/retention clock". Fixed from init rather than sliding: the
+ *  advertised 2 GiB ceiling at the client's own 250 KiB/s floor is ~2.4 hours,
+ *  so 4 hours covers a legitimate worst case, while a sliding window would let
+ *  a slow drip hold that disk indefinitely. */
+export const CHUNKED_UPLOAD_TTL_MS = STAGED_TTL_MS
+
+/** Every live session may hold up to `chunkedMaxBytes` of staging file, so this
+ *  count is a DISK bound, not a throughput one. The client sends one chunk at a
+ *  time from one device (§6, "sequential and in-order"); this leaves headroom
+ *  for a retry and a second device without letting a looping client reserve
+ *  unbounded disk. */
+export const MAX_CONCURRENT_CHUNKED_UPLOADS = 8
+
+const UPLOAD_ID_PATTERN = /^u_[0-9a-f]{24}$/
+
+/** Ids are minted here, so they are validated here. A value that cannot have
+ *  come from this module is treated as unknown (404) rather than reaching the
+ *  registry map — the id is a path component. */
+export function isValidUploadId(value: unknown): value is string {
+  return typeof value === 'string' && UPLOAD_ID_PATTERN.test(value)
+}
+
+export type UploadSessionErrorCode =
+  | 'upload_not_found'
+  | 'chunk_out_of_order'
+  | 'attachment_too_large'
+  | 'incomplete_upload'
+  | 'upload_size_mismatch'
+  | 'invalid_total_bytes'
+  | 'chunk_bytes_required'
+  | 'chunked_upload_unavailable'
+  | 'upload_staging_failed'
+
+/** `detail` is merged into the JSON error body by the route, so a 409 can carry
+ *  `expectedIndex` and a 400 can carry the byte counts without the route
+ *  re-deriving them from state it would have to look up again. */
+export class UploadSessionError extends Error {
+  constructor(
+    readonly code: UploadSessionErrorCode,
+    message: string,
+    readonly detail: Readonly<Record<string, number>> = {},
+  ) {
+    super(message)
+    this.name = 'UploadSessionError'
+  }
+}
+
+export interface UploadSession {
+  uploadId: string
+  /** Absolute path inside the media store's tmp/. Boot reconcile rm -rf's that
+   *  directory, which is exactly why resume is within a boot only (§6). */
+  stagingPath: string
+  /** The client's DECLARED total from init, already bounded to the ceiling. */
+  totalBytes: number
+  receivedBytes: number
+  nextIndex: number
+  mime?: string
+  label?: string
+  capturedAt?: string
+  sessionId?: string
+  createdAtMs: number
+  expiresAtMs: number
+  /** Removes the staging file. Idempotent, and a no-op once ingest has moved
+   *  the file out — same handle contract as MediaStore.createStagingFile(). */
+  dispose: () => void
+}
+
+/** The resume-probe view (contract §2 GET). `expiresAt` is ISO 8601 to match
+ *  every other expiresAt on the media wire (MediaAttachmentRef.expiresAt). */
+export interface UploadSessionProgress {
+  uploadId: string
+  totalBytes: number
+  receivedBytes: number
+  nextIndex: number
+  expiresAt: string
+}
+
+export interface CreateUploadInput {
+  /** Untrusted client claim. Validated here because the ceiling is this
+   *  module's business. */
+  totalBytes: unknown
+  mime?: string
+  label?: string
+  capturedAt?: string
+  sessionId?: string
+}
+
+/** Filesystem seam. `writeAt` MUST leave the file exactly `position +
+ *  bytes.length` bytes long — the truncation is load-bearing, see appendChunk. */
+export interface UploadSessionFs {
+  create: (path: string) => void
+  writeAt: (path: string, bytes: Buffer, position: number) => void
+  sizeOf: (path: string) => number
+}
+
+/**
+ * fs.writeSync MAY RETURN SHORT, and discarding the count is the one path that defeats
+ * finalize's assembled-size re-verification: writeAt then ftruncates to the ASSUMED
+ * length, so the file ends up exactly the expected size with a zero-filled hole where
+ * the unwritten tail belongs. The size check passes and a silently corrupt video is
+ * published.
+ *
+ * Throwing is the correct response and needs no new client handling: the session
+ * counters commit only after writeAt returns, so a throw leaves them untouched and the
+ * client's retry at the same nextIndex overwrites from the same offset.
+ *
+ * Extracted rather than inlined so it is directly testable — inline, no test could
+ * reach it without stubbing a module-level fs import, and a mutation removing it passed.
+ */
+export function assertFullWrite(written: number, expected: number): void {
+  if (written !== expected) {
+    throw new Error(`short chunk write: ${written} of ${expected} bytes`)
+  }
+}
+
+/** The real implementation, exported so a test can DECORATE it (inject one
+ *  failing write and delegate the rest) rather than re-implement it — a fake that
+ *  restates writeAt would pass forever while this drifted. */
+export const defaultUploadSessionFs: UploadSessionFs = {
+  create: (path) => {
+    // Created eagerly and synchronously so the file provably exists before init
+    // answers: an upload whose staging file appears later cannot be swept, and
+    // a resume probe would report progress against a path that is not there.
+    closeSync(openSync(path, 'w', 0o600))
+  },
+  writeAt: (path, bytes, position) => {
+    const fd = openSync(path, 'r+')
+    try {
+      // fs.writeSync MAY RETURN SHORT. Discarding the count and then truncating to
+      // the assumed length is the one path that defeats finalize's assembled-size
+      // re-verification: the file ends up exactly the expected length with a
+      // zero-filled hole where the unwritten tail should be, so the size check
+      // passes and a silently corrupt video is published. Throwing instead leaves
+      // the counters untouched (they commit only after this returns), so the client's
+      // retry at the same nextIndex overwrites from the same offset — the existing
+      // idempotency path, no new client handling required.
+      assertFullWrite(writeSync(fd, bytes, 0, bytes.length, position), bytes.length)
+      // Truncate to the exact committed length. A previous attempt at this same
+      // index may have written MORE bytes here (it is retried after a reconnect,
+      // and the last chunk is short), which would otherwise leave a tail beyond
+      // the counters and make the finalize size check fail on a healthy upload.
+      ftruncateSync(fd, position + bytes.length)
+    } finally {
+      closeSync(fd)
+    }
+  },
+  sizeOf: (path) => statSync(path).size,
+}
+
+export interface UploadSessionRegistryOptions {
+  createStagingFile?: () => MediaStagingFile
+  now?: () => number
+  fs?: Partial<UploadSessionFs>
+  ttlMs?: number
+  /** The assembled ceiling — contract's `chunkedMaxBytes`. Test seam. */
+  maxBytes?: number
+  /** Per-chunk ceiling — contract's `chunkBytes`. Test seam. */
+  maxChunkBytes?: number
+  maxConcurrent?: number
+}
+
+export class UploadSessionRegistry {
+  private readonly sessions = new Map<string, UploadSession>()
+  private readonly createStaging: () => MediaStagingFile
+  private readonly now: () => number
+  private readonly fs: UploadSessionFs
+  private readonly ttlMs: number
+  private readonly maxBytes: number
+  private readonly maxChunkBytes: number
+  private readonly maxConcurrent: number
+
+  constructor(options: UploadSessionRegistryOptions = {}) {
+    this.createStaging = options.createStagingFile ?? (() => getMediaStore().createStagingFile())
+    this.now = options.now ?? Date.now
+    this.fs = { ...defaultUploadSessionFs, ...options.fs }
+    this.ttlMs = options.ttlMs ?? CHUNKED_UPLOAD_TTL_MS
+    this.maxBytes = options.maxBytes ?? MAX_CHUNKED_MEDIA_BYTES
+    this.maxChunkBytes = options.maxChunkBytes ?? MEDIA_CHUNK_BYTES
+    this.maxConcurrent = options.maxConcurrent ?? MAX_CONCURRENT_CHUNKED_UPLOADS
+  }
+
+  create(input: CreateUploadInput): UploadSession {
+    this.sweepExpired()
+    const totalBytes = input.totalBytes
+    if (typeof totalBytes !== 'number' || !Number.isSafeInteger(totalBytes) || totalBytes <= 0) {
+      throw new UploadSessionError('invalid_total_bytes', 'totalBytes must be a positive integer')
+    }
+    // The declared size is a CLAIM (§6). Bounding it here is the cheap refusal;
+    // appendChunk still enforces it as bytes actually arrive.
+    if (totalBytes > this.maxBytes) {
+      throw new UploadSessionError(
+        'attachment_too_large',
+        `declared size exceeds ${this.maxBytes} byte ceiling`,
+        { maxBytes: this.maxBytes },
+      )
+    }
+    if (this.sessions.size >= this.maxConcurrent) {
+      throw new UploadSessionError('chunked_upload_unavailable', 'too many uploads in flight')
+    }
+
+    const staged = this.createStaging()
+    try {
+      this.fs.create(staged.path)
+    } catch (err) {
+      staged.dispose()
+      throw new UploadSessionError(
+        'upload_staging_failed',
+        `staging file could not be created: ${err instanceof Error ? err.message : 'unknown error'}`,
+      )
+    }
+    const startedAt = this.now()
+    const session: UploadSession = {
+      uploadId: `u_${randomBytes(12).toString('hex')}`,
+      stagingPath: staged.path,
+      totalBytes,
+      receivedBytes: 0,
+      nextIndex: 0,
+      ...(input.mime ? { mime: input.mime } : {}),
+      ...(input.label ? { label: input.label } : {}),
+      ...(input.capturedAt ? { capturedAt: input.capturedAt } : {}),
+      ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+      createdAtMs: startedAt,
+      expiresAtMs: startedAt + this.ttlMs,
+      dispose: staged.dispose,
+    }
+    this.sessions.set(session.uploadId, session)
+    return session
+  }
+
+  /** Resume probe. Sweeps first, so an expired upload reads as unknown rather
+   *  than reporting progress that can never be finalized. */
+  peek(uploadId: string): UploadSession | undefined {
+    this.sweepExpired()
+    if (!isValidUploadId(uploadId)) return undefined
+    return this.sessions.get(uploadId)
+  }
+
+  appendChunk(uploadId: string, index: number, bytes: Buffer): UploadSession {
+    const session = this.require(uploadId)
+    if (bytes.length === 0) {
+      // A zero-byte chunk would advance nextIndex without progress, so a client
+      // looping on it would never finish and never fail.
+      throw new UploadSessionError('chunk_bytes_required', 'chunk body is empty')
+    }
+    // Repairable, so the session survives: the client can re-send this index at
+    // the advertised chunk size.
+    if (bytes.length > this.maxChunkBytes) {
+      throw new UploadSessionError(
+        'attachment_too_large',
+        `chunk exceeds ${this.maxChunkBytes} byte chunk size`,
+        { maxBytes: this.maxChunkBytes, expectedIndex: session.nextIndex },
+      )
+    }
+    if (!Number.isSafeInteger(index) || index !== session.nextIndex) {
+      // Strictly in-order (§6). A re-send of an ALREADY-committed index lands
+      // here too and gets the recovery information it needs rather than a blind
+      // second append of the same bytes.
+      throw new UploadSessionError('chunk_out_of_order', `expected chunk ${session.nextIndex}`, {
+        expectedIndex: session.nextIndex,
+      })
+    }
+    // "whichever is lower" (§6). create() already bounds totalBytes to maxBytes,
+    // so the DECLARED value is the operative half and the ceiling half is
+    // unreachable through the public API — measured: replacing this min() with
+    // `session.totalBytes` alone leaves the whole suite green, while replacing it
+    // with `this.maxBytes` alone fails. It stays as the contract's literal rule,
+    // and as what keeps this correct if init's bound ever loosens.
+    const limit = Math.min(session.totalBytes, this.maxBytes)
+    if (session.receivedBytes + bytes.length > limit) {
+      // Fatal, not repairable: the assembled file can no longer match what was
+      // declared, so the upload is dropped and its disk released immediately.
+      this.drop(uploadId)
+      throw new UploadSessionError('attachment_too_large', `upload exceeds ${limit} declared bytes`, {
+        maxBytes: limit,
+      })
+    }
+
+    this.fs.writeAt(session.stagingPath, bytes, session.receivedBytes)
+    // Committed only after the write RETURNED. A throw above leaves the counters
+    // untouched, so the retry of this same index writes at the same offset and
+    // overwrites whatever the failed attempt left — that positional write, not
+    // an open(path,'a'), is what makes re-sending the chunk at nextIndex
+    // idempotent instead of duplicating bytes.
+    session.receivedBytes += bytes.length
+    session.nextIndex += 1
+    return session
+  }
+
+  /** Completeness first (non-destructive: `incomplete_upload` means keep going),
+   *  then hand the session over and forget it. The caller owns the staging file
+   *  from that moment, so a duplicate finalize is a clean 404 rather than a
+   *  second ingest of the same bytes. */
+  finalize(uploadId: string): UploadSession {
+    const session = this.require(uploadId)
+    if (session.receivedBytes !== session.totalBytes) {
+      throw new UploadSessionError('incomplete_upload', 'upload is not complete', {
+        receivedBytes: session.receivedBytes,
+        totalBytes: session.totalBytes,
+      })
+    }
+    // §6: re-verify the ASSEMBLED size before ingest. The counters are ours and
+    // the file is the thing being ingested — when they disagree, the counters
+    // are the ones that cannot be trusted, so refuse rather than ingest a
+    // truncated or over-long body.
+    let actualBytes: number
+    try {
+      actualBytes = this.fs.sizeOf(session.stagingPath)
+    } catch (err) {
+      this.drop(uploadId)
+      throw new UploadSessionError(
+        'upload_size_mismatch',
+        `assembled upload could not be measured: ${err instanceof Error ? err.message : 'unknown error'}`,
+      )
+    }
+    if (actualBytes !== session.totalBytes) {
+      this.drop(uploadId)
+      throw new UploadSessionError('upload_size_mismatch', 'assembled size does not match the declared total', {
+        receivedBytes: actualBytes,
+        totalBytes: session.totalBytes,
+      })
+    }
+    this.sessions.delete(uploadId)
+    return session
+  }
+
+  /** Forget the session AND release its staging file. */
+  drop(uploadId: string): boolean {
+    const session = this.sessions.get(uploadId)
+    if (!session) return false
+    this.sessions.delete(uploadId)
+    try { session.dispose() } catch { /* already moved or gone */ }
+    return true
+  }
+
+  /** Lazy sweep on every access rather than a second interval timer: tmp/ is
+   *  wiped by MediaStore boot reconcile, so the only case a timer would add is a
+   *  server that never touches media again before restarting. */
+  sweepExpired(now = this.now()): number {
+    let dropped = 0
+    for (const [uploadId, session] of this.sessions) {
+      if (session.expiresAtMs <= now) {
+        this.sessions.delete(uploadId)
+        try { session.dispose() } catch { /* already moved or gone */ }
+        dropped++
+      }
+    }
+    return dropped
+  }
+
+  progressOf(session: UploadSession): UploadSessionProgress {
+    return {
+      uploadId: session.uploadId,
+      totalBytes: session.totalBytes,
+      receivedBytes: session.receivedBytes,
+      nextIndex: session.nextIndex,
+      expiresAt: new Date(session.expiresAtMs).toISOString(),
+    }
+  }
+
+  size(): number {
+    return this.sessions.size
+  }
+
+  private require(uploadId: string): UploadSession {
+    const session = this.peek(uploadId)
+    // A wiped, expired, or never-existent upload is the SAME answer (§6): 404,
+    // never a partial success. A restart legitimately produces this.
+    if (!session) throw new UploadSessionError('upload_not_found', 'unknown or expired upload')
+    return session
+  }
+}
+
+// ── Default singleton ────────────────────────────────────────────────────────
+
+let defaultRegistry: UploadSessionRegistry | null = null
+
+export function getUploadSessions(): UploadSessionRegistry {
+  if (!defaultRegistry) defaultRegistry = new UploadSessionRegistry()
+  return defaultRegistry
+}
+
+/** Test hook — mirrors _setMediaStoreForTests so a route test can install a
+ *  registry with a fake clock and tiny ceilings. Returns the previous one. */
+export function _setUploadSessionsForTests(
+  registry: UploadSessionRegistry | null,
+): UploadSessionRegistry | null {
+  const prev = defaultRegistry
+  defaultRegistry = registry
+  return prev
+}

package/server/routes/media.ts

@@ -2,6 +2,10 @@
 // content endpoints backed by server/lib/media-store.ts.
 //
 //   POST   /api/media                 — upload images (base64 JSON batch)
+//   POST   /api/media/upload/init     — open a chunked upload (contract §2)
+//   PUT    /api/media/upload/:id/:n   — append chunk n (raw bytes, in order)
+//   GET    /api/media/upload/:id      — resume probe, safe to poll
+//   POST   /api/media/upload/:id/finalize — assemble, then the SAME ingest
 //   POST   /api/media/reserve         — bind staged media to a queue item
 //   POST   /api/media/associate       — bind media to a run/message (replay-safe)
 //   POST   /api/media/release         — drop staged/reserved media (cancel path)
@@ -42,20 +46,28 @@ import {
 import {
   MAX_OTHER_MEDIA_BYTES,
   MAX_VIDEO_MEDIA_BYTES,
+  MEDIA_CHUNK_BYTES,
   MEDIA_SNIFF_BYTES,
   RichMediaSafetyError,
   isVideoUploadHead,
 } from '../lib/rich-media-safety.js'
+import {
+  UploadSessionError,
+  getUploadSessions,
+  isValidUploadId,
+  type UploadSessionErrorCode,
+} from '../lib/upload-session.js'
 
 // Route-scoped parser: 16 MB covers the max valid batch after base64 + JSON
 // overhead. Mounted only for /api/media in server/index.ts — the global
 // server limit is unchanged.
 export const mediaBodyParser = json({ limit: '16mb' })
 
-/** Chunked upload (contract §2) is not registered on this router yet, so health
- *  must advertise it as unavailable — a client told `true` would try endpoints
- *  that 404. Flip this in the SAME change that adds the routes below. */
-export const MEDIA_CHUNKED_UPLOAD_ENABLED = false
+/** Chunked upload (contract §2) is registered on this router below, so health may
+ *  advertise it. The flag lives beside the routes it describes precisely so the
+ *  two cannot drift: flipping it without mounting them sends clients to 404s,
+ *  and mounting them without flipping it advertises nothing. */
+export const MEDIA_CHUNKED_UPLOAD_ENABLED = true
 
 /** One streamed upload body, staged on disk. Held in a WeakMap keyed by the
  *  request so the handoff stays private to this module instead of widening the
@@ -198,6 +210,106 @@ function takeStagedUploadBody(req: Request): StagedUploadBody | undefined {
   return staged
 }
 
+/** One chunk's raw bytes, held per-request like the streamed single-shot body. */
+const chunkBodies = new WeakMap<Request, Buffer>()
+
+export interface MediaChunkParserOptions {
+  /** Per-chunk ceiling — the contract's advertised `chunkBytes`. Test seam. */
+  maxChunkBytes?: number
+}
+
+/** Raw-bytes parser for PUT /api/media/upload/:uploadId/:index.
+ *
+ *  This one BUFFERS where the single-shot parser streams, and the difference is
+ *  deliberate: a chunk is bounded by the advertised chunkBytes (8 MiB), and
+ *  holding the whole chunk before a single byte reaches the staging file is what
+ *  makes the append atomic per chunk. A dropped connection therefore cannot
+ *  leave a half-written chunk on disk, which is what lets the client re-send the
+ *  chunk at `nextIndex` safely (§6). Streaming straight to the file would trade
+ *  8 MiB of memory for a partial-write recovery problem on every reconnect.
+ *
+ *  Mounted as route-level middleware on the PUT below, so init/finalize keep the
+ *  JSON parser and this can never see them. It is also safe to mount with
+ *  app.use('/api/media/upload', …) ahead of the JSON parsers — the guard below
+ *  makes a second pass a no-op. */
+export function createMediaChunkBodyParser(options: MediaChunkParserOptions = {}) {
+  const maxChunkBytes = options.maxChunkBytes ?? MEDIA_CHUNK_BYTES
+
+  return function mediaChunkUploadParser(req: Request, res: Response, next: NextFunction): void {
+    if (req.method !== 'PUT') {
+      next()
+      return
+    }
+    if (chunkBodies.has(req)) {
+      next()
+      return
+    }
+
+    const refuse = (status: number, body: Record<string, unknown>): void => {
+      res.status(status).json(body)
+      res.once('finish', () => req.destroy())
+    }
+
+    // An upstream JSON parser already drained this body — verified: a PUT sent as
+    // application/json arrives here with req.body set and readableEnded true.
+    // Attaching 'end' to a finished stream would HANG the request, so convert it
+    // into a legible refusal instead. Chunks must be raw bytes.
+    if (req.readableEnded || req.body !== undefined) {
+      refuse(400, {
+        error: 'chunk_bytes_required',
+        detail: 'chunk body must be sent as raw bytes (application/octet-stream)',
+      })
+      return
+    }
+
+    const declaredLength = Number(req.header('content-length'))
+    if (Number.isFinite(declaredLength) && declaredLength > maxChunkBytes) {
+      refuse(413, { error: 'attachment_too_large', maxBytes: maxChunkBytes })
+      return
+    }
+
+    const parts: Buffer[] = []
+    let received = 0
+    let settled = false
+
+    req.on('data', (chunk: Buffer) => {
+      if (settled) return
+      received += chunk.length
+      if (received > maxChunkBytes) {
+        settled = true
+        parts.length = 0
+        refuse(413, { error: 'attachment_too_large', maxBytes: maxChunkBytes })
+        return
+      }
+      parts.push(chunk)
+    })
+    const abandon = (): void => {
+      if (settled) return
+      settled = true
+      parts.length = 0
+    }
+    req.once('aborted', abandon)
+    req.once('error', abandon)
+    req.once('end', () => {
+      if (settled) return
+      settled = true
+      chunkBodies.set(req, Buffer.concat(parts))
+      next()
+    })
+  }
+}
+
+/** Chunk parser at the advertised chunk size. */
+export const mediaChunkBodyParser = createMediaChunkBodyParser()
+
+function takeChunkBody(req: Request): Buffer | undefined {
+  const bytes = chunkBodies.get(req)
+  // `!== undefined`, not truthiness: a zero-length chunk is a real (rejected)
+  // body, and the registry owns that refusal.
+  if (bytes !== undefined) chunkBodies.delete(req)
+  return bytes
+}
+
 export const mediaRouter = Router()
 
 const MEDIA_ERROR_STATUS: Record<string, number> = {
@@ -223,7 +335,25 @@ const SAFETY_ERROR_STATUS: Record<string, number> = {
   video_too_long: 400,
 }
 
+const UPLOAD_ERROR_STATUS: Record<UploadSessionErrorCode, number> = {
+  upload_not_found: 404,
+  chunk_out_of_order: 409,
+  attachment_too_large: 413,
+  incomplete_upload: 400,
+  upload_size_mismatch: 400,
+  invalid_total_bytes: 400,
+  chunk_bytes_required: 400,
+  chunked_upload_unavailable: 503,
+  upload_staging_failed: 500,
+}
+
 function sendMediaError(res: Response, err: unknown): void {
+  // Chunked-upload failures go through the SAME funnel as every other media
+  // error, so there is one place that decides the error body's shape.
+  if (err instanceof UploadSessionError) {
+    res.status(UPLOAD_ERROR_STATUS[err.code] ?? 500).json({ error: err.code, ...err.detail })
+    return
+  }
   if (err instanceof MediaStoreError) {
     res.status(MEDIA_ERROR_STATUS[err.code] ?? 500).json({ error: err.code })
     return
@@ -344,6 +474,152 @@ mediaRouter.post('/media/file', async (req: Request, res: Response) => {
   }
 })
 
+// ── Chunked upload (contract §2) ──────────────────────────────────────────────
+//
+// Registered ahead of the GET /media/:id reads below so a future single-segment
+// param route can never shadow /media/upload/…. Compression does not unlock
+// length — only this does: a 3-minute 4K original is ~570 MB and cannot pass any
+// sane single-shot cap.
+
+/** Read the label the same way POST /media/file does. The two paths must agree,
+ *  or the same phone video gets a different label depending on its size. */
+function uploadLabelFrom(req: Request): string | undefined {
+  const rawLabel = safeString(req.header('x-cos-filename'), 360)
+  if (!rawLabel) return undefined
+  try { return decodeURIComponent(rawLabel).slice(0, 120) } catch { return rawLabel.slice(0, 120) }
+}
+
+mediaRouter.post('/media/upload/init', (req: Request, res: Response) => {
+  try {
+    const body = req.body ?? {}
+    const session = getUploadSessions().create({
+      totalBytes: body.totalBytes,
+      // MIME arrives in the BODY, not Content-Type: this request's Content-Type
+      // is application/json. It stays a hint either way — finalize sniffs the
+      // assembled bytes.
+      mime: safeString(body.mime, 120),
+      label: uploadLabelFrom(req),
+      capturedAt: safeString(req.header('x-cos-captured-at'), 40),
+      sessionId: safeString(req.header('x-cos-session-id'), 64),
+    })
+    res.json({
+      uploadId: session.uploadId,
+      chunkBytes: MEDIA_CHUNK_BYTES,
+      receivedBytes: session.receivedBytes,
+    })
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.put('/media/upload/:uploadId/:index', mediaChunkBodyParser, (req: Request, res: Response) => {
+  const bytes = takeChunkBody(req)
+  try {
+    if (!isValidUploadId(req.params.uploadId)) {
+      // A malformed id cannot name a session this server minted, so it is the
+      // same answer as an expired one — never a partial success (§6).
+      throw new UploadSessionError('upload_not_found', 'unknown or expired upload')
+    }
+    if (bytes === undefined) {
+      throw new UploadSessionError('chunk_bytes_required', 'chunk body was not read as raw bytes')
+    }
+    // Parsed strictly, then compared: a non-numeric segment is definitionally
+    // not the expected index, so it answers 409 with the index to send.
+    const rawIndex = req.params.index
+    const index = typeof rawIndex === 'string' && /^\d{1,9}$/.test(rawIndex)
+      ? Number(rawIndex)
+      : Number.NaN
+    const session = getUploadSessions().appendChunk(req.params.uploadId, index, bytes)
+    res.json({ receivedBytes: session.receivedBytes, nextIndex: session.nextIndex })
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.get('/media/upload/:uploadId', (req: Request, res: Response) => {
+  const sessions = getUploadSessions()
+  const session = isValidUploadId(req.params.uploadId)
+    ? sessions.peek(req.params.uploadId)
+    : undefined
+  if (!session) {
+    res.status(404).json({ error: 'upload_not_found' })
+    return
+  }
+  res.json(sessions.progressOf(session))
+})
+
+/**
+ * Abandon an upload and release its resources NOW.
+ *
+ * WHY THIS EXISTS. Without it an abandoned session held one of only
+ * MAX_CONCURRENT_CHUNKED_UPLOADS (8) slots plus up to chunkedMaxBytes of tmp/ for the
+ * full 4-hour TTL, with no way to release it early. The client's recovery ladder fires
+ * on a flaky phone link BY DESIGN, so give-ups are expected traffic rather than an edge
+ * case: eight of them in one bad session — plausible on a large file — then made init
+ * answer 503 for up to four hours, with the user seeing a feature that simply stopped
+ * working and no way to clear it.
+ *
+ * IDEMPOTENT BY CONSTRUCTION. An unknown, already-cancelled, or expired id answers 200,
+ * not 404. The client calls this best-effort while giving up on something that already
+ * failed; making it fail again would invite a retry loop over a request whose only job
+ * is to release resources. `dropped` reports whether this call was the one that freed
+ * it, for logs — never as a signal the client must act on.
+ *
+ * A malformed id is still 400: that is a client bug worth surfacing, not a resource to
+ * release.
+ */
+mediaRouter.delete('/media/upload/:uploadId', (req: Request, res: Response) => {
+  if (!isValidUploadId(req.params.uploadId)) {
+    res.status(400).json({ error: 'invalid_upload_id' })
+    return
+  }
+  // drop() forgets the session AND disposes its staging file, so the slot and the disk
+  // are both released here rather than waiting on the TTL sweep.
+  const dropped = getUploadSessions().drop(req.params.uploadId)
+  res.json({ ok: true, dropped })
+})
+
+mediaRouter.post('/media/upload/:uploadId/finalize', async (req: Request, res: Response) => {
+  let claimed: { stagingPath: string; dispose: () => void } | null = null
+  try {
+    if (!isValidUploadId(req.params.uploadId)) {
+      throw new UploadSessionError('upload_not_found', 'unknown or expired upload')
+    }
+    // Throws `incomplete_upload` WITHOUT consuming the session, so a client that
+    // finalized early can keep sending chunks. Anything it returns is a session
+    // this request now owns.
+    const session = getUploadSessions().finalize(req.params.uploadId)
+    claimed = session
+    // The SAME ingest as POST /media/file — validation, the per-kind cap from
+    // magic bytes, the atomic rename, and compression scheduling all stay in one
+    // place. A second ingest path would be a second place for those to rot.
+    const attachment = await getMediaStore().ingestRichMediaFromFile({
+      sourcePath: session.stagingPath,
+      byteLength: session.totalBytes,
+      label: session.label,
+      declaredMime: session.mime,
+      capturedAt: session.capturedAt,
+      sessionId: session.sessionId,
+      // The one line that makes chunked upload actually work. Without it this
+      // inherits the SINGLE-SHOT per-kind cap, so every chunked video transferred
+      // in full and was then refused at finalize with a raw 413 — strictly worse
+      // than the pre-flight refusal it replaced. Only video gets the chunked
+      // ceiling; documents stay at the single-shot cap, because the text path reads
+      // the whole file into a Buffer and a JS string.
+      transfer: 'chunked',
+    })
+    res.json({ attachment })
+  } catch (err) {
+    sendMediaError(res, err)
+  } finally {
+    // No-op once ingest moved the file into the asset dir. The case that matters
+    // is a REJECTED assembly (unsupported format, over the per-kind cap): ingest
+    // is atomic, so nothing is half-published, and this is what stops the
+    // assembled body leaking in tmp/.
+    claimed?.dispose()
+  }
+})
+
 // ── Lifecycle ────────────────────────────────────────────────────────────────
 
 mediaRouter.post('/media/reserve', async (req: Request, res: Response) => {