@rubytech/create-maxy-code 0.1.489 → 0.1.490

package/payload/platform/plugins/cloudflare/bin/portal-index-push.mjs

@@ -178,22 +178,71 @@ export async function pushAccount(opts) {
 
   const rows = await walkExposed(accountDir, r.exposed)
 
-  await client.query('DELETE FROM directory WHERE accountId = ?', [accountId])
+  // Stage, flip, then sweep (Task 1910, superseding backlog Task 1842).
+  //
+  // The replace used to be DELETE-then-INSERT, which left the account's tree
+  // empty or half-built for the whole insert run. A client listing inside that
+  // window saw a portal with nothing in it. At sixty-second cadence that window
+  // is hit sixty times more often than it was hourly, which is what turned a
+  // known defect into a blocking one.
+  //
+  // Now every row is written at the NEXT generation, one statement moves the
+  // pointer, and only then are superseded rows removed. The flip is the atomic
+  // point: a reader sees the old tree or the new one, never a mixture. The
+  // sweep afterwards need not be atomic, because nothing reads a generation the
+  // pointer does not name.
+  const state = await client.query(
+    'SELECT currentGeneration FROM directory_state WHERE accountId = ?',
+    [accountId],
+  )
+  const current = Number(state[0]?.currentGeneration ?? 0)
+  const next = current + 1
+
   for (const row of rows) {
     await client.query(
-      'INSERT INTO directory (accountId, relPath, sizeBytes, modifiedAt, indexedAt, isDir) VALUES (?, ?, ?, ?, ?, ?)',
-      [accountId, row.relPath, row.sizeBytes, row.modifiedAt, nowIso, row.isDir ? 1 : 0],
+      'INSERT INTO directory (accountId, relPath, sizeBytes, modifiedAt, indexedAt, isDir, generation) ' +
+        'VALUES (?, ?, ?, ?, ?, ?, ?)',
+      [accountId, row.relPath, row.sizeBytes, row.modifiedAt, nowIso, row.isDir ? 1 : 0, next],
+    )
+  }
+  log(`${TAG} op=stage account=${accountId} generation=${next} inserted=${rows.length}`)
+
+  // THE atomic point. Upsert rather than insert-or-update, so an account
+  // publishing for the first time and one republishing take the same path.
+  await client.query(
+    'INSERT INTO directory_state (accountId, currentGeneration) VALUES (?, ?) ' +
+      'ON CONFLICT (accountId) DO UPDATE SET currentGeneration = excluded.currentGeneration',
+    [accountId, next],
+  )
+  log(`${TAG} op=flip account=${accountId} generation=${next}`)
+
+  // Housekeeping only. A failure here leaves stale rows nothing reads, which is
+  // waste rather than incorrectness — so it must not fail the publish that has
+  // already succeeded.
+  try {
+    await client.query('DELETE FROM directory WHERE accountId = ? AND generation != ?', [
+      accountId,
+      next,
+    ])
+  } catch (err) {
+    log(
+      `${TAG} op=sweep account=${accountId} generation=${next} result=failed ` +
+        `err="${err instanceof Error ? err.message : String(err)}"`,
     )
   }
-  log(`${TAG} op=replace account=${accountId} deleted=all inserted=${rows.length}`)
 
   // Read back rather than trusting the write: "issued the inserts" is not "the
-  // rows are there", and a half-applied batch is otherwise invisible.
-  const check = await client.query('SELECT COUNT(*) AS n FROM directory WHERE accountId = ?', [accountId])
+  // rows are there", and a half-applied batch is otherwise invisible. Counted
+  // through the pointer, so this measures what a client would actually see.
+  const check = await client.query(
+    'SELECT COUNT(*) AS n FROM directory d JOIN directory_state s ' +
+      'ON s.accountId = d.accountId AND s.currentGeneration = d.generation WHERE d.accountId = ?',
+    [accountId],
+  )
   const after = Number(check[0]?.n ?? -1)
   log(`${TAG} op=verify account=${accountId} rowsAfter=${after} expected=${rows.length}`)
 
-  return { exposed: r.exposed, rows: rows.length, schemaPresent: true }
+  return { exposed: r.exposed, rows: rows.length, schemaPresent: true, generation: next }
 }
 
 /**
@@ -323,39 +372,44 @@ function resolveCloudflareCredentials(platformRoot) {
   return { cfAccountId: house.CLOUDFLARE_ACCOUNT_ID, token }
 }
 
-async function main() {
-  const platformRoot = process.env.PLATFORM_ROOT
-  if (!platformRoot) {
-    console.error(`${TAG} op=usage reason=no-platform-root PLATFORM_ROOT is required`)
-    process.exit(1)
-  }
+/**
+ * Publish every portal-serving account's index.
+ *
+ * Exported so the admin server's 60s loop and this script's CLI entry run the
+ * SAME code (Task 1910). The loop replaced an hourly heartbeat spawn whose own
+ * header recorded it had never been observed running on a device; two
+ * implementations of the publish would have reintroduced exactly that class of
+ * problem one layer along.
+ *
+ * Returns a summary rather than exiting, so a caller inside a long-lived
+ * process can report it. Throwing is reserved for a genuine break — an absent
+ * house credential where portals exist — which the loop registry surfaces as a
+ * failed run rather than a silent one.
+ *
+ * @param {string} platformRoot
+ * @returns {Promise<{accounts: number, pushed: number, failed: number}>}
+ */
+export async function pushAllAccounts(platformRoot) {
+  const accountsRoot = resolve(platformRoot, '..', 'data', 'accounts')
+  const targets = await portalAccounts(accountsRoot)
+  console.error(`${TAG} op=enumerate accountsRoot="${accountsRoot}" accounts=${targets.length}`)
+  // Before minting a credential, exactly as the pull and the audit do: most
+  // installs have neither a portal nor a house credential, and minting
+  // unconditionally would make this loop report an error on every one forever.
+  if (targets.length === 0) return { accounts: 0, pushed: 0, failed: 0 }
 
   const cred = resolveCloudflareCredentials(platformRoot)
   if ('error' in cred) {
-    console.error(`${TAG} op=skip reason=${cred.error}`)
-    process.exit(1)
-  }
-
-  /** @type {{accountDir: string, accountId: string, dbName: string, exposeFolders: string[]}[]} */ let targets
-  if (process.argv.includes('--all-accounts')) {
-    // Same derivation as the platform's own DATA_ROOT (data-path.ts:19), from
-    // the PLATFORM_ROOT the heartbeat already passes.
-    const accountsRoot = resolve(platformRoot, '..', 'data', 'accounts')
-    targets = await portalAccounts(accountsRoot)
-    console.error(`${TAG} op=enumerate accountsRoot="${accountsRoot}" accounts=${targets.length}`)
-  } else {
-    const accountDir = arg('--account-dir')
-    const accountId = arg('--account')
-    const dbName = arg('--db')
-    if (!accountDir || !accountId || !dbName) {
-      console.error(`${TAG} op=usage --account-dir <dir> --account <id> --db <name>`)
-      process.exit(1)
-    }
-    targets = [{ accountDir, accountId, dbName, exposeFolders: await readExposeFolders(accountDir) }]
+    throw new Error(cred.error)
   }
+  return runTargets(platformRoot, cred, targets)
+}
 
+/** @returns {Promise<{accounts: number, pushed: number, failed: number}>} */
+async function runTargets(platformRoot, cred, targets) {
   const state = readState(platformRoot)
   let failed = 0
+  let pushed = 0
   for (const t of targets) {
     try {
       // cfAccountId addresses the D1 endpoint; t.accountId scopes the rows.
@@ -382,6 +436,7 @@ async function main() {
           exposed: r.exposed,
         })
       }
+      pushed++
       console.error(`${TAG} op=done account=${t.accountId} rows=${r.rows}`)
     } catch (err) {
       // One account's failure must not stop the rest, and it must never be
@@ -392,10 +447,53 @@ async function main() {
       )
     }
   }
-  if (failed > 0) process.exit(1)
+  return { accounts: targets.length, pushed, failed }
+}
+
+async function main() {
+  const platformRoot = process.env.PLATFORM_ROOT
+  if (!platformRoot) {
+    console.error(`${TAG} op=usage reason=no-platform-root PLATFORM_ROOT is required`)
+    process.exit(1)
+  }
+
+  if (process.argv.includes('--all-accounts')) {
+    try {
+      const r = await pushAllAccounts(platformRoot)
+      if (r.failed > 0) process.exit(1)
+    } catch (err) {
+      console.error(`${TAG} op=skip reason=${err instanceof Error ? err.message : String(err)}`)
+      process.exit(1)
+    }
+    return
+  }
+
+  const accountDir = arg('--account-dir')
+  const accountId = arg('--account')
+  const dbName = arg('--db')
+  if (!accountDir || !accountId || !dbName) {
+    console.error(`${TAG} op=usage --account-dir <dir> --account <id> --db <name>`)
+    process.exit(1)
+  }
+  const cred = resolveCloudflareCredentials(platformRoot)
+  if ('error' in cred) {
+    console.error(`${TAG} op=skip reason=${cred.error}`)
+    process.exit(1)
+  }
+  const r = await runTargets(platformRoot, cred, [
+    { accountDir, accountId, dbName, exposeFolders: await readExposeFolders(accountDir) },
+  ])
+  if (r.failed > 0) process.exit(1)
 }
 
 // Only when invoked directly, so the module stays importable by tests.
-if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+// The basename check is what survives the UI bundler inlining this file into
+// server.js: when bundled, `process.argv[1]` (server.js) and `import.meta.url`
+// (server.js after esbuild's transform) resolve to the same path, and a pure
+// path-equality guard fires main() at server boot, exiting the payload before
+// its first line served. Matching on the mjs basename keeps this cheap CLI
+// entry point from tripping in-process.
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : ''
+if (invokedPath && invokedPath.endsWith('/portal-index-push.mjs') && invokedPath === resolve(fileURLToPath(import.meta.url))) {
   void main()
 }

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-delete-withdraw.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import { processDelete } from '../../skills/data-portal/template/functions/api/delete'
+import type { PortalEnv } from '../../skills/data-portal/template/functions/api/_lib/types'
+
+/** `row` is what the manifest holds for the key under test, or null when the
+ *  key is unknown. The fake tracks which of the three writes actually happened
+ *  so a test can assert the R2 object was never touched. */
+function harness(row: { devicePath: string } | null) {
+  const state = { objectDeleted: false, rowDeleted: false, marked: false }
+  const lines: string[] = []
+
+  const env = {
+    BUCKET: {
+      async delete() {
+        state.objectDeleted = true
+      },
+      async head() {
+        return state.objectDeleted ? null : { size: 1 }
+      },
+    },
+    DB: {
+      prepare(sql: string) {
+        return {
+          bind() {
+            return {
+              async first() {
+                if (sql.includes('FROM sessions')) {
+                  return { ownerId: 'alice', accountId: 'acct', folders: '' }
+                }
+                if (sql.includes('SELECT devicePath')) return row
+                if (sql.includes('SELECT deleted')) return { deleted: state.marked ? 1 : 0 }
+                if (sql.includes('SELECT fileId FROM manifest')) {
+                  return state.rowDeleted || !row ? null : { fileId: 'f1' }
+                }
+                return null
+              },
+              async run() {
+                if (/^UPDATE manifest/.test(sql)) state.marked = true
+                if (/^DELETE FROM manifest/.test(sql)) state.rowDeleted = true
+              },
+            }
+          },
+        }
+      },
+    },
+  } as unknown as PortalEnv
+
+  return { env, state, lines, log: (l: string) => lines.push(l) }
+}
+
+describe('delete branches on whether the file has moved', () => {
+  it('deletes object and row outright when the file is still in transit', async () => {
+    const h = harness({ devicePath: '' })
+    const res = await processDelete('s', 'alice/a.pdf', h.env, h.log, () => 1)
+    expect(res.status).toBe(200)
+    expect(h.state.objectDeleted).toBe(true)
+    expect(h.state.rowDeleted).toBe(true)
+    expect(h.state.marked).toBe(false)
+  })
+
+  it('marks a moved file for withdrawal instead of touching R2', async () => {
+    // The bytes are on the device and the R2 object is already gone. Deleting
+    // here would report success while the client's file stayed on the device
+    // forever — the exact failure this branch exists to prevent.
+    const h = harness({ devicePath: 'jobs/a.pdf' })
+    const res = await processDelete('s', 'alice/jobs/a.pdf', h.env, h.log, () => 1)
+    expect(res.status).toBe(200)
+    expect(h.state.marked).toBe(true)
+    expect(h.state.rowDeleted).toBe(false)
+    expect(h.state.objectDeleted).toBe(false)
+    expect(h.lines.some((l) => l.includes('op=withdraw') && l.includes('result=marked'))).toBe(true)
+  })
+
+  it('tells the client the withdrawal is pending, not complete', async () => {
+    const h = harness({ devicePath: 'jobs/a.pdf' })
+    const res = await processDelete('s', 'alice/jobs/a.pdf', h.env, h.log, () => 1)
+    expect(res.payload).toMatchObject({ ok: true, pending: true })
+  })
+
+  it('reports an unknown key as not found without writing anything', async () => {
+    const h = harness(null)
+    const res = await processDelete('s', 'alice/nope.pdf', h.env, h.log, () => 1)
+    expect(res.status).toBe(404)
+    expect(h.state.objectDeleted).toBe(false)
+    expect(h.state.marked).toBe(false)
+    expect(h.state.rowDeleted).toBe(false)
+  })
+
+  it('still refuses another person key before reading anything', async () => {
+    const h = harness({ devicePath: '' })
+    const res = await processDelete('s', 'bob/a.pdf', h.env, h.log, () => 1)
+    expect(res.status).toBe(403)
+    expect(h.state.objectDeleted).toBe(false)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-index-push.test.ts

@@ -49,12 +49,13 @@ function fakeClient() {
     calls,
     async query(sql: string, params: unknown[] = []) {
       calls.push({ sql, params })
-      if (/DELETE FROM directory/i.test(sql)) {
-        rows.clear()
+      // The open paren is load-bearing: `INSERT INTO directory_state` would
+      // otherwise register as a row insert and inflate every count.
+      if (/INSERT INTO directory \(/i.test(sql)) {
+        rows.add(String(params[1]))
         return []
       }
-      if (/INSERT INTO directory/i.test(sql)) {
-        rows.add(String(params[1]))
+      if (/DELETE FROM directory\b/i.test(sql)) {
         return []
       }
       if (/SELECT COUNT/i.test(sql)) return [{ n: rows.size }]
@@ -140,14 +141,17 @@ describe('walkExposed', () => {
 
 describe('pushAccount', () => {
   // 7 rows: the 3 files plus output/, quotes/, quotes/CR2969/, quotes/CR2974/.
-  it('deletes the account rows then inserts the current walk', async () => {
+  it('stages the current walk, then flips the pointer to it', async () => {
+    // Task 1910 replaced delete-then-insert with stage-flip-sweep. The first
+    // statement now READS the pointer rather than emptying the table, which is
+    // what removes the window where a client saw nothing.
     const c = fakeClient()
     const r = await push(c)
     expect(r.exposed).toEqual(['output', 'quotes'])
     expect(r.rows).toBe(7)
-    expect(/DELETE FROM directory/i.test(c.calls[0].sql)).toBe(true)
+    expect(/SELECT currentGeneration/i.test(c.calls[0].sql)).toBe(true)
     expect(c.calls[0].params).toEqual(['acc-1'])
-    expect(c.calls.filter((x) => /INSERT INTO directory/i.test(x.sql)).length).toBe(7)
+    expect(c.calls.filter((x) => /INSERT INTO directory \(/i.test(x.sql)).length).toBe(7)
   })
 
   // The folder itself survives its last file: emptied is not the same as gone,
@@ -201,12 +205,13 @@ describe('pushAccount', () => {
     expect(c.calls.length).toBe(0)
   })
 
-  it('logs resolve, replace and verify lines', async () => {
+  it('logs resolve, stage, flip and verify lines', async () => {
     const lines: string[] = []
     const c = fakeClient()
     await push(c, { log: (l: string) => lines.push(l) })
     expect(lines.some((l) => l.includes('op=resolve') && l.includes('exposed=output,quotes'))).toBe(true)
-    expect(lines.some((l) => l.includes('op=replace') && l.includes('inserted=7'))).toBe(true)
+    expect(lines.some((l) => l.includes('op=stage') && l.includes('inserted=7'))).toBe(true)
+    expect(lines.some((l) => l.includes('op=flip') && l.includes('generation=1'))).toBe(true)
     expect(lines.some((l) => l.includes('op=verify') && l.includes('rowsAfter=7') && l.includes('expected=7'))).toBe(true)
   })
 
@@ -265,3 +270,130 @@ describe('pushAccount', () => {
     expect(lines.some((l) => /op=resolve .*extraFolders=0/.test(l))).toBe(true)
   })
 })
+
+// The atomic replace (Task 1910), superseding backlog Task 1842.
+//
+// A generation-aware client: rows carry a generation, and a reader sees only
+// the generation the pointer names. That is what makes "never a half-built
+// tree" a measurable property rather than an assertion.
+function generationClient() {
+  const calls: { sql: string; params: unknown[] }[] = []
+  /** @type {{accountId: string, relPath: string, generation: number}[]} */
+  const rows: { accountId: string; relPath: string; generation: number }[] = []
+  let pointer: number | null = null
+  return {
+    calls,
+    rows,
+    /** What a client listing right now would see. */
+    visible() {
+      return pointer === null ? [] : rows.filter((r) => r.generation === pointer)
+    },
+    pointerValue() {
+      return pointer
+    },
+    async query(sql: string, params: unknown[] = []) {
+      calls.push({ sql, params })
+      if (/SELECT\s+currentGeneration/i.test(sql)) {
+        return pointer === null ? [] : [{ currentGeneration: pointer }]
+      }
+      if (/INSERT INTO directory_state|UPDATE directory_state/i.test(sql)) {
+        pointer = Number(params[1] ?? params[0])
+        return []
+      }
+      if (/INSERT INTO directory\b/i.test(sql)) {
+        rows.push({
+          accountId: String(params[0]),
+          relPath: String(params[1]),
+          generation: Number(params[6]),
+        })
+        return []
+      }
+      if (/DELETE FROM directory\b/i.test(sql)) {
+        const keep = Number(params[1])
+        for (let i = rows.length - 1; i >= 0; i--) {
+          if (rows[i].generation !== keep) rows.splice(i, 1)
+        }
+        return []
+      }
+      if (/SELECT COUNT/i.test(sql)) {
+        return [{ n: rows.filter((r) => r.generation === pointer).length }]
+      }
+      return []
+    },
+  }
+}
+
+describe('the index replace is atomic', () => {
+  it('never issues a delete before the pointer flip', async () => {
+    // The delete-then-insert window this replaces was Task 1842: a client
+    // listing mid-push saw an empty or half-built tree. At 60s cadence that
+    // window would be hit sixty times more often than it was hourly.
+    const c = generationClient()
+    await push(c)
+    const flipAt = c.calls.findIndex((x) => /INSERT INTO directory_state/i.test(x.sql))
+    const deleteAt = c.calls.findIndex((x) => /^DELETE FROM directory\b/i.test(x.sql.trim()))
+    expect(flipAt).toBeGreaterThanOrEqual(0)
+    expect(deleteAt).toBeGreaterThan(flipAt)
+  })
+
+  it('writes every row before the flip', async () => {
+    const c = generationClient()
+    await push(c)
+    const flipAt = c.calls.findIndex((x) => /INSERT INTO directory_state/i.test(x.sql))
+    const lastInsert = c.calls.map((x) => /INSERT INTO directory\b/i.test(x.sql)).lastIndexOf(true)
+    expect(lastInsert).toBeLessThan(flipAt)
+  })
+
+  it('a reader mid-push sees the old tree, never a partial one', async () => {
+    // First publish establishes generation 1.
+    const c = generationClient()
+    await push(c)
+    const first = c.visible().map((r) => r.relPath).sort()
+    expect(first.length).toBeGreaterThan(0)
+
+    // A second publish stages generation 2. Until the flip, `visible()` must
+    // still be exactly the first tree — not a mixture, not an empty set.
+    const seen: string[][] = []
+    const watched = {
+      ...c,
+      async query(sql: string, params: unknown[] = []) {
+        const out = await c.query(sql, params)
+        seen.push(c.visible().map((r) => r.relPath).sort())
+        return out
+      },
+    }
+    await push(watched)
+
+    const flipIdx = c.calls.findIndex(
+      (x, i) => i > first.length && /INSERT INTO directory_state/i.test(x.sql),
+    )
+    for (let i = 0; i < flipIdx; i++) {
+      expect(seen[i]).toEqual(first)
+    }
+  })
+
+  it('advances the generation on each publish', async () => {
+    const c = generationClient()
+    await push(c)
+    expect(c.pointerValue()).toBe(1)
+    await push(c)
+    expect(c.pointerValue()).toBe(2)
+  })
+
+  it('deletes superseded generations after the flip', async () => {
+    const c = generationClient()
+    await push(c)
+    await push(c)
+    expect(c.rows.every((r) => r.generation === 2)).toBe(true)
+  })
+
+  it('writes nothing at all when the exposed set is empty', async () => {
+    // Fail closed must not delete the account rows: that state would be
+    // indistinguishable from a successful publish of an account with no
+    // deliverables.
+    rmSync(join(dir, 'SCHEMA.md'))
+    const c = generationClient()
+    await push(c)
+    expect(c.calls.filter((x) => /INSERT|DELETE|directory_state/i.test(x.sql))).toEqual([])
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-moved-download.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+import { processDownload } from '../../skills/data-portal/template/functions/api/download'
+import type { PortalEnv } from '../../skills/data-portal/template/functions/api/_lib/types'
+
+const ACC = '098a18a3-1741-447f-9778-65470645d57d'
+
+function harness(row: { devicePath: string } | null, opts: { configured?: boolean } = {}) {
+  const configured = opts.configured ?? true
+  const lines: string[] = []
+  const env = {
+    BUCKET: {
+      async get(key: string) {
+        // Only an in-transit object exists. A moved row's bytes are gone from
+        // R2 entirely, which is what makes reading them here the wrong move.
+        return row && !row.devicePath ? { body: null, size: 4, key } : null
+      },
+    },
+    DB: {
+      prepare(sql: string) {
+        return {
+          bind() {
+            return {
+              async first() {
+                if (sql.includes('FROM sessions')) {
+                  return { ownerId: 'alice', accountId: ACC, folders: '' }
+                }
+                if (sql.includes('devicePath')) return row
+                return null
+              },
+            }
+          },
+        }
+      },
+    },
+    PORTAL_FETCH_SECRET: configured ? 'test-secret-value' : undefined,
+    PORTAL_INSTALL_ORIGIN: configured ? 'https://install.example' : undefined,
+  } as unknown as PortalEnv
+  return { env, lines, log: (l: string) => lines.push(l) }
+}
+
+describe('downloading an upload that has moved to the device', () => {
+  it('streams R2 bytes while the row is still in transit', async () => {
+    const h = harness({ devicePath: '' })
+    const res = await processDownload('s', 'alice/a.pdf', h.env, h.log, 1000)
+    expect(res.status).toBe(200)
+    expect(res.body).not.toBeNull()
+    expect(res.url).toBeUndefined()
+  })
+
+  it('mints an own-upload link once the row has moved', async () => {
+    // The object is gone from R2. Without this branch the client's own upload
+    // would 404 the moment the device collected it.
+    const h = harness({ devicePath: 'uploads/alice/a.pdf' })
+    const res = await processDownload('s', 'alice/a.pdf', h.env, h.log, 1000)
+    expect(res.status).toBe(200)
+    expect(res.url).toContain('/api/portal/fetch')
+    expect(new URL(res.url!).searchParams.get('owner')).toBe('alice')
+    expect(new URL(res.url!).searchParams.get('path')).toBe('uploads/alice/a.pdf')
+    expect(h.lines.some((l) => l.includes('op=download') && l.includes('result=moved'))).toBe(true)
+  })
+
+  it('refuses another person key before anything is minted', async () => {
+    const h = harness({ devicePath: 'uploads/bob/a.pdf' })
+    const res = await processDownload('s', 'bob/a.pdf', h.env, h.log, 1000)
+    expect(res.status).toBe(403)
+    expect(res.url).toBeUndefined()
+  })
+
+  it('reports device-offline rather than a server error when unconfigured', async () => {
+    // Same reasoning as the indexed path: from the client's side the file
+    // genuinely is unreachable, and the operator's signal is the log line.
+    const h = harness({ devicePath: 'uploads/alice/a.pdf' }, { configured: false })
+    const res = await processDownload('s', 'alice/a.pdf', h.env, h.log, 1000)
+    expect(res.status).toBe(503)
+    expect(h.lines.some((l) => l.includes('result=unconfigured'))).toBe(true)
+  })
+
+  it('reports absent for a key with no manifest row at all', async () => {
+    const h = harness(null)
+    const res = await processDownload('s', 'alice/gone.pdf', h.env, h.log, 1000)
+    expect(res.status).toBe(404)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-schema-shape.test.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+// The schema is applied by the skill, not by any code this suite can call, so
+// its shape is asserted textually. A missing column here is not a test failure
+// in some other file — it is an upload naming a column D1 does not have.
+const SQL = readFileSync(
+  join(__dirname, '../../skills/data-portal/schema.sql'),
+  'utf8',
+)
+
+describe('portal schema shape', () => {
+  it('carries the manifest lifecycle columns', () => {
+    expect(SQL).toMatch(/targetPath\s+TEXT\s+NOT NULL\s+DEFAULT\s+''/)
+    expect(SQL).toMatch(/devicePath\s+TEXT\s+NOT NULL\s+DEFAULT\s+''/)
+    expect(SQL).toMatch(/deleted\s+INTEGER\s+NOT NULL\s+DEFAULT\s+0/)
+  })
+
+  it('carries the directory generation and its pointer table', () => {
+    expect(SQL).toMatch(/generation\s+INTEGER\s+NOT NULL\s+DEFAULT\s+0/)
+    expect(SQL).toMatch(/CREATE TABLE IF NOT EXISTS directory_state/)
+    expect(SQL).toMatch(/currentGeneration\s+INTEGER\s+NOT NULL/)
+  })
+
+  it('keeps objectKey UNIQUE, which the upsert conflict target still needs', () => {
+    // objectKey is now ownerId/targetPath/filename. The upsert still conflicts
+    // on it, so this pins that the constraint was not dropped by accident while
+    // the key shape changed underneath it.
+    expect(SQL).toMatch(/objectKey\s+TEXT\s+UNIQUE\s+NOT NULL/)
+  })
+
+  it('scopes the directory uniqueness by generation', () => {
+    // Two generations hold the same relPath at once between the write and the
+    // flip. UNIQUE (accountId, relPath) would reject the second write and the
+    // push could never stage a new generation at all.
+    expect(SQL).toMatch(/UNIQUE\s*\(\s*accountId,\s*relPath,\s*generation\s*\)/)
+  })
+
+  it('documents the hand-run ALTER for every added column', () => {
+    // IF NOT EXISTS adds no column to an existing table, so a portal deployed
+    // before this needs each one by hand. An undocumented column is an operator
+    // reading "no such column" with nothing telling them what to run.
+    for (const col of ['targetPath', 'devicePath', 'deleted', 'generation']) {
+      expect(SQL).toMatch(new RegExp(`ALTER TABLE \\w+ ADD COLUMN ${col}\\b`))
+    }
+  })
+})