@rubytech/create-maxy-code 0.1.488 → 0.1.490

package/payload/platform/plugins/cloudflare/mcp/__tests__/template-config.test.ts

@@ -143,6 +143,16 @@ describe('device binding', () => {
     expect(text).toMatch(/UNIQUE \(accountId, relPath\)/)
     expect(text).toMatch(/accountId\s+TEXT NOT NULL DEFAULT ''/)
   })
+
+  // IF NOT EXISTS is a no-op on an existing table, so a portal deployed before
+  // this column will NOT gain it from a re-apply. The push names isDir in its
+  // INSERT, so such a table fails loudly rather than silently publishing
+  // nothing — the ALTER has to be findable at the point that happens.
+  it('declares isDir and carries the ALTER for a table that predates it', () => {
+    const text = schema()
+    expect(text).toMatch(/isDir\s+INTEGER NOT NULL DEFAULT 0/)
+    expect(text).toContain('ALTER TABLE directory ADD COLUMN isDir INTEGER NOT NULL DEFAULT 0')
+  })
 })
 
 const portalJs = () => readFileSync(join(TEMPLATE, 'portal.js'), 'utf8')
@@ -170,3 +180,172 @@ describe('login error surfacing and passcode reveal (Task 1872)', () => {
     expect(portalJs()).toMatch(/dp-reveal/)
   })
 })
+
+// Task 1900. The device pushes a new tree hourly, so a client who stays signed
+// in reads an index frozen at sign-in. These assertions pin the control that
+// re-reads it: the button in the pinned header, and the click that drives it.
+describe('refresh control', () => {
+  it('puts a refresh button inside the pinned header', () => {
+    const header = indexHtml().match(/<header class="dp-header">[\s\S]*?<\/header>/)
+    expect(header).not.toBeNull()
+    expect(header![0]).toMatch(/id="dp-refresh"/)
+    expect(header![0]).toMatch(/class="dp-iconbtn"/)
+    expect(header![0]).toMatch(/aria-label="Refresh"/)
+  })
+
+  it('sits between the crumbs and the upload control', () => {
+    const text = indexHtml()
+    expect(text.indexOf('id="dp-crumbs"')).toBeLessThan(text.indexOf('id="dp-refresh"'))
+    expect(text.indexOf('id="dp-refresh"')).toBeLessThan(text.indexOf('id="dp-upload-open"'))
+  })
+
+  it('binds a click on it', () => {
+    expect(portalJs()).toMatch(/refreshEl\.addEventListener\('click'/)
+  })
+
+  it('drives refresh() rather than reloading the page', () => {
+    expect(portalJs()).not.toMatch(/location\.reload/)
+  })
+
+  // The status line has to survive a failed re-read. refresh() catches its own
+  // failure, so the promise resolves either way; only a reported outcome tells
+  // the handler whether clearing the status would erase an error.
+  it('has refresh() report its outcome on all three exits', () => {
+    const body = portalJs().match(/function refresh\(\)[\s\S]*?\n  }\n/)
+    expect(body).not.toBeNull()
+    expect(body![0]).toMatch(/return true/)
+    expect((body![0].match(/return false/g) || []).length).toBe(2)
+  })
+
+  // Task 1900 asserted "never polls", on the reasoning that a poll against an
+  // hourly tree is waste. Task 1910 moved the push to a 60s loop, so that
+  // premise no longer holds: the poll is now the thing that makes a device-side
+  // change appear without the client clicking anything.
+  //
+  // What still must hold is that the poll cannot run away. It is gated on tab
+  // visibility and on a re-entry guard, so a background tab costs nothing and a
+  // slow response cannot stack reads on a portal running on a free plan.
+  it('polls once a minute, gated on visibility and not re-entrant', () => {
+    const text = portalJs()
+    const timer = text.match(/setInterval\(function \(\)[\s\S]*?\}, 60000\)/)
+    expect(timer).not.toBeNull()
+    expect(timer![0]).toMatch(/document\.hidden/)
+    expect(timer![0]).toMatch(/polling/)
+  })
+})
+
+// refresh() now writes its own failure text, which would bury the outcome of
+// the delete or upload the client just asked for. Both callers compose instead,
+// so a stale list is reported without losing what happened to the file.
+describe('an action that outlives its re-list', () => {
+  it('keeps the delete and upload outcome when the re-list fails', () => {
+    const text = portalJs()
+    expect((text.match(/The list could not be reloaded\./g) || []).length).toBe(2)
+  })
+
+  it('has both callers read the boolean refresh() returns', () => {
+    const text = portalJs()
+    const removeBody = text.match(/function remove\(key\)[\s\S]*?\n  }\n/)
+    const uploadBody = text.match(/function uploadFile\(file, target\)[\s\S]*?\n  }\n/)
+    expect(removeBody).not.toBeNull()
+    expect(uploadBody).not.toBeNull()
+    expect(removeBody![0]).toMatch(/refresh\(\)\.then\(function \(ok\)/)
+    expect(uploadBody![0]).toMatch(/refresh\(\)\.then\(function \(ok\)/)
+  })
+})
+
+// The two-way client (Task 1910). These are text assertions over the shipped
+// template, which is the only harness this dependency-free page has — there is
+// no bundler and no DOM test runner for it. They pin the behaviours that make
+// the exchange two-way; the live drag-and-drop itself is an on-device check.
+describe('the client can send a file to a folder', () => {
+  it('makes every folder row a drop target', () => {
+    // The interaction the whole task exists for: drop onto the folder, not
+    // into a modal that decides for you.
+    const text = portalJs()
+    expect(text).toMatch(/li\.addEventListener\('drop'/)
+    expect(text).toMatch(/dp-drop-target/)
+  })
+
+  it('sends the row own path as the target, not the folder merely open', () => {
+    const text = portalJs()
+    expect(text).toMatch(/uploadMany\(dt\.files, e\.relPath\)/)
+  })
+
+  it('does not upload a row drop twice', () => {
+    // A drop on a folder row bubbles to the listing, whose handler would
+    // otherwise upload the same file again into whichever folder is open.
+    const text = portalJs()
+    expect(text).toMatch(/ev\.dpHandled = true/)
+    expect(text).toMatch(/if \(e\.dpHandled\) return/)
+  })
+
+  it('takes every dropped file, not the first', () => {
+    const text = portalJs()
+    expect(text).not.toMatch(/dt\.files\[0\]/)
+    expect(text).toMatch(/function uploadMany\(files, target\)/)
+  })
+
+  it('accepts a multiple selection in the picker', () => {
+    expect(indexHtml()).toMatch(/id="dp-file"[^>]*multiple/)
+  })
+
+  it('names the destination folder in the modal', () => {
+    // An upload whose folder the client has to infer is the defect this task
+    // removes; stating it is part of the fix, not decoration.
+    expect(portalJs()).toMatch(/Uploading into /)
+    expect(indexHtml()).toMatch(/id="dp-upload-target"/)
+  })
+})
+
+describe('the client can take a file out', () => {
+  it('offers drag-out on the client own uploads, not only device files', () => {
+    // Before this there were two stores and only one of them could be dragged
+    // out of. DownloadURL is what makes the OS write real bytes.
+    const text = portalJs()
+    expect((text.match(/setData\(\s*'DownloadURL'/g) || []).length).toBe(2)
+  })
+})
+
+describe('the client can send a large file', () => {
+  it('slices at the same 25 MiB bound the server gates on', () => {
+    const text = portalJs()
+    expect(text).toMatch(/PART_BYTES = 25 \* 1024 \* 1024/)
+    expect(text).toMatch(/MAX_TOTAL_BYTES = 1024 \* 1024 \* 1024/)
+  })
+
+  it('checks the size before sending rather than after', () => {
+    // The browser should not spend minutes sending a gigabyte only to be told
+    // at the end that it was too large.
+    expect(portalJs()).toMatch(/file\.size > MAX_TOTAL_BYTES/)
+  })
+
+  it('runs the three multipart stages', () => {
+    const text = portalJs()
+    for (const action of ['create', 'part', 'complete']) {
+      expect(text).toContain(`'action', '${action}'`)
+    }
+  })
+
+  it('shows progress across the parts', () => {
+    expect(portalJs()).toMatch(/showProgress\(i \/ total\)/)
+    expect(indexHtml()).toMatch(/id="dp-progress-bar"/)
+  })
+})
+
+describe('a failed upload says which failure it was', () => {
+  it('maps each status to its own message', () => {
+    // Every failure used to read 'Upload failed.', which tells a client nothing
+    // about whether to retry, sign in again, or pick a smaller file.
+    const text = portalJs()
+    const fn = text.match(/function uploadFailureMessage\(status\)[\s\S]*?\n  }\n/)
+    expect(fn).not.toBeNull()
+    for (const status of ['401', '403', '413', '400']) {
+      expect(fn![0]).toContain(status)
+    }
+  })
+
+  it('distinguishes a network failure from a server refusal', () => {
+    expect(portalJs()).toMatch(/Could not reach the server/)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/upload-route.test.ts

@@ -78,7 +78,7 @@ describe('processUpload', () => {
     const res = await processUpload(
       'sess-a',
       'invoice.pdf',
-      new Uint8Array([1, 2, 3]),
+      '', new Uint8Array([1, 2, 3]),
       env,
       (l) => lines.push(l),
       () => 'up-1',
@@ -94,7 +94,7 @@ describe('processUpload', () => {
     await processUpload(
       'sess-a',
       'invoice.pdf',
-      new Uint8Array([1]),
+      '', new Uint8Array([1]),
       env,
       () => {},
       () => 'up-1',
@@ -110,7 +110,7 @@ describe('processUpload', () => {
     await processUpload(
       'sess-a',
       'invoice.pdf',
-      new Uint8Array([1]),
+      '', new Uint8Array([1]),
       env,
       (l) => lines.push(l),
       () => 'up-1',
@@ -128,7 +128,7 @@ describe('processUpload', () => {
     const res = await processUpload(
       '',
       'invoice.pdf',
-      new Uint8Array([1]),
+      '', new Uint8Array([1]),
       env,
       () => {},
       () => 'up-1',
@@ -144,7 +144,7 @@ describe('processUpload', () => {
     const res = await processUpload(
       'sess-a',
       '../bob/evil.pdf',
-      new Uint8Array([1]),
+      '', new Uint8Array([1]),
       env,
       () => {},
       () => 'up-1',
@@ -162,7 +162,7 @@ describe('processUpload', () => {
         await processUpload(
           'sess-a',
           '',
-          new Uint8Array([1]),
+          '', new Uint8Array([1]),
           env,
           () => {},
           () => 'up-1',
@@ -179,6 +179,7 @@ describe('processUpload', () => {
     const res = await processUpload(
       'sess-a',
       'huge.bin',
+      '',
       tooBig,
       env,
       (l) => lines.push(l),
@@ -198,7 +199,7 @@ describe('processUpload', () => {
     await processUpload(
       'sess-a',
       'invoice.pdf',
-      new Uint8Array([1]),
+      '', new Uint8Array([1]),
       env,
       (l) => lines.push(l),
       () => 'up-1',
@@ -217,11 +218,11 @@ describe('processUpload', () => {
   describe('re-uploading the same filename', () => {
     it('replaces the object, keeps exactly one row, and succeeds', async () => {
       const { env, manifestRows, objects } = makeEnv()
-      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      await processUpload('sess-a', 'invoice.pdf', '', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
       const second = await processUpload(
         'sess-a',
         'invoice.pdf',
-        new Uint8Array([9, 9, 9]),
+        '', new Uint8Array([9, 9, 9]),
         env,
         () => {},
         () => 'up-2',
@@ -234,8 +235,8 @@ describe('processUpload', () => {
 
     it('updates the row to describe the new object, not the old one', async () => {
       const { env, manifestRows } = makeEnv()
-      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
-      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
+      await processUpload('sess-a', 'invoice.pdf', '', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      await processUpload('sess-a', 'invoice.pdf', '', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
       // Column order: fileId, ownerId, filename, objectKey, size, uploadedAt, ingested
       expect(manifestRows[0][4]).toBe(3)
       expect(manifestRows[0][5]).toBe(new Date(2_000).toISOString())
@@ -246,9 +247,9 @@ describe('processUpload', () => {
       // ingested=1, a replacement that left the flag set would never be
       // ingested, and nothing would ever say so.
       const { env, manifestRows } = makeEnv()
-      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      await processUpload('sess-a', 'invoice.pdf', '', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
       manifestRows[0][6] = 1 // the device-side sweep marks it ingested
-      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
+      await processUpload('sess-a', 'invoice.pdf', '', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
       expect(manifestRows[0][6]).toBe(0)
     })
   })

package/payload/platform/plugins/cloudflare/skills/data-portal/SKILL.md

@@ -13,9 +13,11 @@ references with `plugin-read` before issuing their commands.
 ## What this skill produces, and what it does not
 
 It produces a Pages project on a custom domain, an R2 bucket holding one prefix per enrolled person,
-and a D1 database holding the manifest, the enrolment records, and the sessions. It does not ingest
-the dropped files: a separate device-side sweep reads un-ingested manifest rows and pulls them into
-the graph. This skill delivers the manifest that sweep consumes.
+and a D1 database holding the manifest, the enrolment records, and the sessions. It does not carry a
+dropped file onto the device: the `portal-uploads-pull` loop in the admin server does that, every
+minute, writing each un-ingested manifest row's object to `uploads/<ownerName>/` and setting
+`ingested = 1` only once the bytes are on disk at the right size. This skill delivers the manifest
+that loop consumes. Nothing here or there ingests a pulled file into the graph.
 
 ## Why the portal is on Pages and not the install
 
@@ -110,6 +112,17 @@ with the same `bin/cf-store-name.sh` scheme as the bucket, and apply
 `platform/plugins/cloudflare/skills/data-portal/schema.sql` to the remote database from there. It is
 `IF NOT EXISTS` throughout, so re-applying is safe.
 
+Safe, but not a migration: `IF NOT EXISTS` adds no column to a table that already exists. A portal
+whose `directory` table predates the `isDir` column keeps failing every index push, because the push
+names the column in its `INSERT`. Add it once by hand against that database:
+
+```bash
+npx wrangler d1 execute <portalDbName> --remote \
+  --command "ALTER TABLE directory ADD COLUMN isDir INTEGER NOT NULL DEFAULT 0"
+```
+
+No backfill follows it. The push replaces every row for the account each cycle.
+
 The copied `portal.css` carries the template's default palette, which is nobody's brand. Apply the
 install's before handing the tree to the deploy:
 
@@ -164,7 +177,7 @@ anyway. That check is what contains a stale index or a compromised project, and
 
 ## Publish the folder index
 
-The device publishes file metadata — names, sizes, times, never bytes:
+The device publishes file and folder metadata — names, sizes, times, never bytes:
 
 ```bash
 node platform/plugins/cloudflare/bin/portal-index-push.mjs \
@@ -178,6 +191,13 @@ brand with a different vertical publishes different folders with no change to th
 data (`documents/`, `contacts/`, `projects/`), the client's own `uploads/`, plugin workspaces and
 everything platform-internal are in neither source and are never published.
 
+Every walked folder gets a row of its own, not only the files inside it. An exposed folder holding
+nothing at any depth is therefore a real entry: it renders in the tree and opens to an empty listing,
+rather than reading as absent to the person who has to put the first file into it. A folder row
+carries no bytes, so the download path refuses it and logs `result=is-directory`. A folder named in
+the schema but absent from the device's disk still publishes nothing, so the tree never offers a
+folder the device does not have.
+
 An account with no `SCHEMA.md` publishes nothing at all. That is deliberate and it is the opposite of
 what the write-path guard does — the guard fails open so an unseeded account is not write-blocked,
 while a surface facing a client must fail closed.
@@ -190,15 +210,25 @@ dot-prefixed. These extras are added on top of the schema-derived set and, unlik
 are not intersected with the `allowed-top-level` block. An empty or absent list behaves exactly as
 before.
 
-The heartbeat runs this hourly for every account carrying a `data-portal.json`. Run it once by hand
+The admin server runs this every sixty seconds for every account carrying a `data-portal.json`
+. It used to be an hourly spawn from the scheduling heartbeat, which had never been
+observed running on a device and left the client's tree up to an hour stale. Run it once by hand
 after assembly so the client has something to see on their first sign-in, and check the output names
 the folders you expect:
 
 ```
 [portal-index] op=resolve account=<id> schemaPresent=true allowed=22 domainBuckets=quotes extraFolders=1 exposed=inbound-invoices,output,quotes
+[portal-index] op=stage account=<id> generation=7 inserted=41
+[portal-index] op=flip account=<id> generation=7
 [portal-index] op=verify account=<id> rowsAfter=41 expected=41
 ```
 
+The publish stages every row at the next generation, moves a pointer in one statement, then sweeps
+the superseded rows. That flip is the atomic point: a client listing mid-publish reads the old tree
+or the new one and never a half-built one. Before this the replace was delete-then-insert, so the
+tree was empty for the length of the insert run, which was tolerable hourly and is not at sixty
+seconds.
+
 `exposed=none` on an account that has deliverables means the schema was missing or its ontology
 region was absent — not that the walk found nothing. `extraFolders=<n>` counts the folders the
 operator requested in `exposeFolders`; a non-zero `extraFolders` with none of those names in
@@ -208,9 +238,26 @@ operator requested in `exposeFolders`; a non-zero `extraFolders` with none of th
 
 Signed in, the panel has a pinned header that stays put while the file lists
 scroll under it. The header carries the folder breadcrumbs, an up control that
-moves to the parent folder (disabled at the root), and an upload icon. Filenames
-render on one line: the stem truncates with an ellipsis and the extension stays
-pinned, so `.pdf` and `.html` on two same-named orders are still told apart.
+moves to the parent folder (disabled at the root), a refresh control, and an
+upload icon. Filenames render on one line: the stem truncates with an ellipsis
+and the extension stays pinned, so `.pdf` and `.html` on two same-named orders
+are still told apart.
+
+Refresh re-reads the index in the folder that is already open. The page also
+re-reads itself every sixty seconds while its tab is visible, which is what
+makes a file the device published appear without the client clicking anything.
+That poll was deliberately absent while the push was hourly, when it would have
+been waste; it arrived with the sixty-second push. It is skipped for a hidden
+tab and while a read is already in flight, so a background tab costs nothing and
+a slow response cannot stack requests. The refresh button is inert while its own
+request is in flight, and the status line clears on success or keeps the failure
+message on screen.
+
+Delete and upload both re-read the list when they finish. If that re-read
+fails, the status keeps the outcome and adds to it, so a client reads
+`Deleted. The list could not be reloaded.` rather than a bare load error that
+would leave them unsure whether the file went. The rows on screen are then
+known to be stale, and refresh is how they clear that.
 
 A shared (device-held) file downloads three ways, all through the same signed
 `/api/download?path=` route: a left click, a right-click that opens a one-item
@@ -220,11 +267,38 @@ saves the file rather than a JSON body. The three download methods share the one
 `op=fetch-through` log line, so a broken method shows as a missing line under the
 same signal.
 
-Upload opens from the header icon into a dismissable modal holding the file
-picker and Upload button. It posts to `/api/upload` exactly as before; a kept
-upload refreshes the list and closes the modal. Dropping a file onto the modal's
-upload area uploads the same way. The modal dismisses on the close button, a
-click on the backdrop, or Escape.
+A client's own uploaded file drags out the same way, so both lists behave alike
+rather than only the device-held one supporting it.
+
+**Uploads go to a folder the client chooses.** Dropping files onto a
+folder row sends them into that folder; dropping onto the open listing sends
+them into the folder currently open; the modal states which folder it will use.
+An upload with no folder chosen lands in the client's own uploads area, which
+stays unexposed to the folder tree. The client still sees and downloads it from
+their own list, through a signed link scoped to them.
+
+A legal target is one the client can already see: it must pass their folder
+grant and carry a row in the published index. The device re-derives that set
+itself and refuses anything outside it, so a stale index or a compromised Pages
+project cannot route a file into a folder the device does not expose. A refused
+target leaves the file pending and logs the exact reason; it is never quietly
+rerouted somewhere the client did not choose.
+
+Several files may be dropped or picked at once and upload one after another.
+Anything over 25 MiB is sliced into parts against a multipart session, up to
+1 GB, with a progress bar; a file over the limit is refused before any bytes are
+sent. Failures now read differently by cause: an expired session, a folder that
+is not allowed, a file that is too large, and an unreachable server are four
+messages, not one.
+
+Once the device has collected an upload it deletes the portal's copy, so the
+file lives in one place rather than two. A targeted file then appears in its
+folder rather than in the uploads list; an untargeted one stays in the uploads
+list and downloads through the device. Deleting a file the device already
+collected removes it from the device too, within a minute; the client is told it
+is pending rather than gone, because for that minute it is.
+
+The modal dismisses on the close button, a click on the backdrop, or Escape.
 
 ## Deploy through site-deploy
 

package/payload/platform/plugins/cloudflare/skills/data-portal/schema.sql

@@ -58,9 +58,40 @@ CREATE TABLE IF NOT EXISTS sessions (
 
 CREATE INDEX IF NOT EXISTS sessions_owner ON sessions (ownerId);
 
--- One row per stored object. `ingested` is the claim flag the device-side
--- sweep (a separate task) reads and sets; a row stays 0 until its file has
--- been pulled into the graph, so the backlog survives the device being offline.
+-- One row per stored object, carrying a three-state lifecycle (Task 1910).
+--
+--   in transit  ingested=0, devicePath=''   bytes in R2
+--   moved       ingested=1, devicePath set  bytes on the device, R2 object gone
+--   withdrawn   deleted=1                   device file pending removal
+--
+-- `ingested` is the claim flag the admin server's `portal-uploads-pull` loop
+-- reads and sets; a row stays 0 until its object is on the device at the size
+-- recorded here, so the backlog survives the device being offline and a
+-- half-finished transfer never reads as delivered.
+--
+-- `targetPath` is the exposed folder the client chose at upload, '' when they
+-- chose none. It is part of `objectKey` (ownerId/targetPath/filename), because
+-- a flat key collides the same filename dropped into two folders: the upsert
+-- below would overwrite the first object, reset ingested, and the first file
+-- would never land on the device at all.
+--
+-- `devicePath` is written only after a verified device write, so its presence
+-- IS the proof the move happened. A boolean would say a move occurred without
+-- saying where, and the audit's unpublishedRouted check needs the path to
+-- compare against the published index.
+--
+-- `deleted` marks a withdrawal of an already-moved file, whose bytes are on the
+-- device and whose R2 object is already gone. The row is removed outright once
+-- the device file is confirmed absent — not kept as a tombstone, which would
+-- grow this table without bound and force every listing read to filter it while
+-- describing bytes that no longer exist anywhere.
+--
+-- IF NOT EXISTS adds no column to an existing table. A portal deployed before
+-- this needs the three run by hand, once:
+--   ALTER TABLE manifest ADD COLUMN targetPath TEXT NOT NULL DEFAULT '';
+--   ALTER TABLE manifest ADD COLUMN devicePath TEXT NOT NULL DEFAULT '';
+--   ALTER TABLE manifest ADD COLUMN deleted INTEGER NOT NULL DEFAULT 0;
+-- Their absence is loud: upload names targetPath in its INSERT.
 CREATE TABLE IF NOT EXISTS manifest (
   id         INTEGER PRIMARY KEY AUTOINCREMENT,
   fileId     TEXT UNIQUE NOT NULL,
@@ -69,11 +100,17 @@ CREATE TABLE IF NOT EXISTS manifest (
   objectKey  TEXT UNIQUE NOT NULL,
   size       INTEGER NOT NULL,
   uploadedAt TEXT NOT NULL,
-  ingested   INTEGER NOT NULL DEFAULT 0
+  ingested   INTEGER NOT NULL DEFAULT 0,
+  targetPath TEXT NOT NULL DEFAULT '',
+  devicePath TEXT NOT NULL DEFAULT '',
+  deleted    INTEGER NOT NULL DEFAULT 0
 );
 
 CREATE INDEX IF NOT EXISTS manifest_uningested ON manifest (ingested);
 CREATE INDEX IF NOT EXISTS manifest_owner ON manifest (ownerId);
+-- The pull selects `ingested = 0 OR deleted = 1`, so the withdrawal half needs
+-- its own index or a withdrawal costs a full scan every sixty seconds.
+CREATE INDEX IF NOT EXISTS manifest_deleted ON manifest (deleted);
 
 -- Fixed-window auth attempt counter. Pages Functions are stateless, so the
 -- counter cannot live in process memory the way every other rate limiter in
@@ -88,16 +125,36 @@ CREATE TABLE IF NOT EXISTS auth_attempts (
 
 CREATE UNIQUE INDEX IF NOT EXISTS auth_attempts_scope_window ON auth_attempts (scope, windowStart);
 
--- One row per file the device has published to this portal. Metadata only: the
--- bytes stay on the device and are fetched on demand through a short-lived
--- signed link, which is what lets the folder tree render while the device is
--- offline.
+-- One row per file OR folder the device has published to this portal. Metadata
+-- only: the bytes stay on the device and are fetched on demand through a
+-- short-lived signed link, which is what lets the folder tree render while the
+-- device is offline.
 --
 -- Written by a full replace per account (delete-all, then insert the current
 -- walk), which is why there is no tombstone column: a file deleted or renamed on
 -- the device simply stops being inserted on the next cycle. The UNIQUE key is
 -- what makes that replace safe to retry — a double insert of the same path
 -- fails loudly instead of silently doubling the row.
+--
+-- `isDir` marks a folder row. Folders are stored rather than derived from file
+-- path prefixes, because a folder holding no files at any depth has no prefix
+-- to derive it from and would not exist to the client at all. A folder row
+-- carries sizeBytes 0 and the folder's own modified time, and the download path
+-- refuses to mint a signed link for one.
+--
+-- Like `people.accountId` and `people.folders`, IF NOT EXISTS will NOT add this
+-- column to a `directory` table that predates it, and the push names `isDir` in
+-- its INSERT, so such a table fails loudly on the next cycle. Add it by hand in
+-- that case:
+--   ALTER TABLE directory ADD COLUMN isDir INTEGER NOT NULL DEFAULT 0;
+-- No backfill follows it: the push replaces every row each cycle.
+--
+-- `generation` is which staging round a row belongs to (Task 1910). The push
+-- writes the next generation, flips the pointer below in ONE statement, then
+-- deletes rows of earlier generations. Uniqueness is scoped by generation
+-- because two of them hold the same relPath between the write and the flip;
+-- UNIQUE (accountId, relPath) would reject the staged write outright.
+--   ALTER TABLE directory ADD COLUMN generation INTEGER NOT NULL DEFAULT 0;
 CREATE TABLE IF NOT EXISTS directory (
   id         INTEGER PRIMARY KEY AUTOINCREMENT,
   accountId  TEXT NOT NULL,
@@ -105,7 +162,28 @@ CREATE TABLE IF NOT EXISTS directory (
   sizeBytes  INTEGER NOT NULL,
   modifiedAt TEXT NOT NULL,
   indexedAt  TEXT NOT NULL,
-  UNIQUE (accountId, relPath)
+  isDir      INTEGER NOT NULL DEFAULT 0,
+  generation INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (accountId, relPath, generation)
 );
 
 CREATE INDEX IF NOT EXISTS directory_account ON directory (accountId);
+
+-- Which generation of an account's rows is the live one.
+--
+-- The flip of this single row is the atomic point of a publish: a client
+-- listing that races a push reads the old tree or the new one, and never a
+-- half-built one. Cleanup of superseded rows afterwards need not be atomic,
+-- because nothing reads a generation this pointer does not name.
+--
+-- This replaces the delete-then-insert window recorded as backlog Task 1842.
+-- At sixty-second cadence that window would be hit sixty times more often than
+-- it was hourly, which is what turned a known defect into a blocking one.
+--
+-- An account with no row here has never completed a publish, and every reader
+-- joins through this table, so it correctly shows nothing rather than showing
+-- a staged generation that no flip ever blessed.
+CREATE TABLE IF NOT EXISTS directory_state (
+  accountId         TEXT PRIMARY KEY,
+  currentGeneration INTEGER NOT NULL
+);

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/portal-sign.mjs

@@ -25,6 +25,25 @@ function message(accountId, relPath, expiresAtMs) {
   return `${accountId}\n${relPath}\n${expiresAtMs}`
 }
 
+/**
+ * The own-upload message (Task 1910).
+ *
+ * A SECOND shape rather than an extended first one, for two reasons.
+ *
+ * The literal `uploads` discriminator is what stops an exposed-folder signature
+ * ever admitting an uploads path, so the owner binding is load-bearing rather
+ * than decorative. And the two ends redeploy at different times — the device
+ * through an installer publish, the portal through site-deploy — so a single
+ * extended message would break every existing download in the window between
+ * them. An already-deployed portal never mints this type, so nothing regresses.
+ *
+ * @param {string} accountId @param {string} ownerId @param {string} relPath
+ * @param {number} expiresAtMs
+ */
+function ownUploadMessage(accountId, ownerId, relPath, expiresAtMs) {
+  return `${accountId}\nuploads\n${ownerId}\n${relPath}\n${expiresAtMs}`
+}
+
 /** @param {string} secret */
 async function keyFor(secret) {
   return crypto.subtle.importKey(
@@ -85,3 +104,58 @@ export async function buildSignedUrl(origin, secret, accountId, relPath, expires
   url.searchParams.set('sig', sig)
   return url.toString()
 }
+
+/**
+ * Sign one own-upload path. Lowercase hex, same algorithm as signPath — only
+ * the message differs.
+ * @param {string} secret @param {string} accountId @param {string} ownerId
+ * @param {string} relPath @param {number} expiresAtMs @returns {Promise<string>}
+ */
+export async function signOwnUpload(secret, accountId, ownerId, relPath, expiresAtMs) {
+  const key = await keyFor(secret)
+  const mac = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    new TextEncoder().encode(ownUploadMessage(accountId, ownerId, relPath, expiresAtMs)),
+  )
+  return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * @param {string} secret @param {string} accountId @param {string} ownerId
+ * @param {string} relPath @param {number} expiresAtMs @param {string} signature
+ * @param {number} nowMs @returns {Promise<boolean>}
+ */
+export async function verifyOwnUpload(
+  secret,
+  accountId,
+  ownerId,
+  relPath,
+  expiresAtMs,
+  signature,
+  nowMs,
+) {
+  if (!secret || !signature) return false
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) return false
+  const expected = await signOwnUpload(secret, accountId, ownerId, relPath, expiresAtMs)
+  return constantTimeEqual(expected, signature)
+}
+
+/**
+ * The owner travels as a query parameter as well as inside the HMAC: the device
+ * needs to know which folder is being claimed before it can verify the claim.
+ * The parameter is never trusted on its own — a mismatch simply fails to verify.
+ * @param {string} origin @param {string} secret @param {string} accountId
+ * @param {string} ownerId @param {string} relPath @param {number} expiresAtMs
+ * @returns {Promise<string>}
+ */
+export async function buildOwnUploadUrl(origin, secret, accountId, ownerId, relPath, expiresAtMs) {
+  const sig = await signOwnUpload(secret, accountId, ownerId, relPath, expiresAtMs)
+  const url = new URL('/api/portal/fetch', origin)
+  url.searchParams.set('accountId', accountId)
+  url.searchParams.set('owner', ownerId)
+  url.searchParams.set('path', relPath)
+  url.searchParams.set('exp', String(expiresAtMs))
+  url.searchParams.set('sig', sig)
+  return url.toString()
+}