@rubytech/create-maxy-code 0.1.561 → 0.1.563

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-visit-status-write.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect } from 'vitest'
+import {
+  MAX_STATUS_LENGTH,
+  processVisitStatus,
+} from '../../skills/data-portal/template/functions/api/visit-status'
+import type {
+  D1Database,
+  PortalEnv,
+} from '../../skills/data-portal/template/functions/api/_lib/types'
+
+interface Row {
+  accountId: string
+  ownerId: string
+  visitId: string
+}
+
+/**
+ * A fake that HONOURS the INSERT ... SELECT, because the gate IS the SELECT.
+ *
+ * It applies the same account and owner filters the statement names and reports
+ * `meta.changes` as the number of rows the SELECT admitted. A fake that always
+ * reported one change would pass a handler with no gate at all.
+ */
+function db(rows: Row[], person: { ownerId: string; recordScope: string; accountId: string }) {
+  const inserted: unknown[][] = []
+  const database = {
+    prepare(sql: string) {
+      let bound: unknown[] = []
+      const stmt = {
+        bind(...v: unknown[]) {
+          bound = v
+          return stmt
+        },
+        async first<T>() {
+          return person as unknown as T
+        },
+        async run() {
+          if (!sql.startsWith('INSERT INTO visit_status')) return { meta: { changes: 0 } }
+          // Bind order matches the statement: the SELECT's literals first, then
+          // the WHERE's account, the optional owner, and the visitId last.
+          const acct = bound[0] as string
+          const visitId = bound[bound.length - 1] as string
+          const owner = bound[1] as string
+          let admitted = rows.filter((r) => r.accountId === acct && r.visitId === visitId)
+          if (sql.includes('AND v.ownerId = ?')) admitted = admitted.filter((r) => r.ownerId === owner)
+          if (admitted.length) inserted.push(bound)
+          return { meta: { changes: admitted.length } }
+        },
+        async all<T>() {
+          return { results: [] as T[] }
+        },
+      }
+      return stmt
+    },
+  }
+  return { database: database as unknown as D1Database, inserted }
+}
+
+const env = (d: D1Database): PortalEnv =>
+  ({ DB: d, BUCKET: {}, PORTAL_ACCOUNT_ID: 'acc-a' }) as unknown as PortalEnv
+
+const ROWS: Row[] = [
+  { accountId: 'acc-a', ownerId: 'alice', visitId: 'v1' },
+  { accountId: 'acc-a', ownerId: 'bob', visitId: 'v2' },
+  { accountId: 'acc-a', ownerId: '', visitId: 'v3' },
+  { accountId: 'acc-b', ownerId: 'alice', visitId: 'v4' },
+]
+
+const person = (ownerId: string, recordScope: string) => ({
+  ownerId,
+  recordScope,
+  accountId: 'acc-a',
+})
+
+const body = (visitId: string, status = 'on-site') => ({ visitId, status })
+
+describe('the visit-status write gate', () => {
+  it('accepts an own-scoped person setting status on their own visit', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(body('v1'), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(200)
+    expect(inserted).toHaveLength(1)
+  })
+
+  it('refuses an own-scoped person setting status on someone else visit', async () => {
+    // A read leak shows someone a day that is not theirs. A write leak lets
+    // them change it, which is why the gate is the same one and is structural.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(body('v2'), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(404)
+    expect(inserted).toEqual([])
+  })
+
+  it('refuses an own-scoped person setting status on an unbound visit', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(body('v3'), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(404)
+    expect(inserted).toEqual([])
+  })
+
+  it('lets an account-scoped person set status on any visit for the account', async () => {
+    const { database, inserted } = db(ROWS, person('marie', 'account'))
+    const h = await processVisitStatus(body('v2'), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(200)
+    expect(inserted).toHaveLength(1)
+  })
+
+  it('refuses another account visit even at account scope', async () => {
+    const { database, inserted } = db(ROWS, person('marie', 'account'))
+    const h = await processVisitStatus(body('v4'), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(404)
+    expect(inserted).toEqual([])
+  })
+
+  it('denies when the session does not resolve', async () => {
+    const d = {
+      prepare: () => ({ bind: () => ({ first: async () => null }) }),
+    } as unknown as D1Database
+    const h = await processVisitStatus(body('v1'), '', env(d), () => {}, 1)
+    expect(h.status).toBe(401)
+  })
+
+  it('refuses a body with no visitId or no status', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const e = env(database)
+    expect((await processVisitStatus({ status: 'x' }, 'sess', e, () => {}, 1)).status).toBe(400)
+    expect((await processVisitStatus({ visitId: 'v1' }, 'sess', e, () => {}, 1)).status).toBe(400)
+    expect((await processVisitStatus(null, 'sess', e, () => {}, 1)).status).toBe(400)
+    expect(inserted).toEqual([])
+  })
+
+  it('refuses a status longer than the cap, rather than writing it into the graph', async () => {
+    // The value reaches :Visit.status through the pull. An unbounded free-text
+    // field written from the open web is refused at the door, not truncated:
+    // a truncated status is a different status, silently.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(
+      body('v1', 'x'.repeat(MAX_STATUS_LENGTH + 1)),
+      'sess',
+      env(database),
+      () => {},
+      1,
+    )
+    expect(h.status).toBe(400)
+    expect(inserted).toEqual([])
+  })
+
+  it('stamps the setter own id, never one the request supplies', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    await processVisitStatus(
+      { visitId: 'v1', status: 'on-site', ownerId: 'bob' },
+      'sess',
+      env(database),
+      () => {},
+      1,
+    )
+    expect(inserted[0]).toContain('alice')
+    expect(inserted[0]).not.toContain('bob')
+  })
+
+  it('logs the scope and the outcome, and no status text', async () => {
+    const lines: string[] = []
+    const { database } = db(ROWS, person('alice', 'own'))
+    await processVisitStatus(
+      body('v1', 'on-site-at-granary-court'),
+      'sess',
+      env(database),
+      (l) => lines.push(l),
+      1,
+    )
+    const joined = lines.join('\n')
+    expect(joined).toContain('scope=own')
+    expect(joined).toContain('result=ok')
+    expect(joined).not.toContain('granary')
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-visits-scope.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest'
+import { processVisits } from '../../skills/data-portal/template/functions/api/visits'
+import type {
+  D1Database,
+  PortalEnv,
+} from '../../skills/data-portal/template/functions/api/_lib/types'
+
+interface Row {
+  accountId: string
+  ownerId: string
+  visitId: string
+}
+
+/**
+ * A fake that HONOURS the SQL it is handed rather than replaying a fixture.
+ *
+ * It reads the WHERE clause and the bound values and filters accordingly, so
+ * deleting the scope branch in the endpoint changes what comes back. A fake
+ * that replayed rows would pass whatever the gate did, which is the same defect
+ * shape as 1689's upload fake accepting duplicates the schema rejected.
+ */
+function db(rows: Row[], person: { ownerId: string; recordScope: string; accountId: string }) {
+  return {
+    prepare(sql: string) {
+      let bound: unknown[] = []
+      const stmt = {
+        bind(...v: unknown[]) {
+          bound = v
+          return stmt
+        },
+        async first<T>() {
+          return person as unknown as T
+        },
+        async run() {
+          return { meta: { changes: 0 } }
+        },
+        async all<T>() {
+          if (!sql.includes('FROM visits')) return { results: [] as T[] }
+          const [acct, owner] = bound as string[]
+          let out = rows.filter((r) => r.accountId === acct)
+          if (sql.includes('v.ownerId = ?')) out = out.filter((r) => r.ownerId === owner)
+          return { results: out as unknown as T[] }
+        },
+      }
+      return stmt
+    },
+  } as unknown as D1Database
+}
+
+const env = (d: D1Database): PortalEnv =>
+  ({ DB: d, BUCKET: {}, PORTAL_ACCOUNT_ID: 'acc-a' }) as unknown as PortalEnv
+
+const ROWS: Row[] = [
+  { accountId: 'acc-a', ownerId: 'alice', visitId: 'v1' },
+  { accountId: 'acc-a', ownerId: 'bob', visitId: 'v2' },
+  { accountId: 'acc-a', ownerId: '', visitId: 'v3' },
+  { accountId: 'acc-b', ownerId: 'alice', visitId: 'v4' },
+]
+
+const ids = (h: { payload: Record<string, unknown> }) =>
+  (h.payload.visits as Row[]).map((v) => v.visitId).sort()
+
+const asPerson = (ownerId: string, recordScope: string) => ({
+  ownerId,
+  recordScope,
+  accountId: 'acc-a',
+})
+
+describe('the visits scope gate', () => {
+  it('shows an own-scoped person only their own visits', async () => {
+    const h = await processVisits('sess', env(db(ROWS, asPerson('alice', 'own'))), () => {}, 1)
+    expect(ids(h)).toEqual(['v1'])
+  })
+
+  it('shows an account-scoped person every visit for the account', async () => {
+    const h = await processVisits('sess', env(db(ROWS, asPerson('marie', 'account'))), () => {}, 1)
+    expect(ids(h)).toEqual(['v1', 'v2', 'v3'])
+  })
+
+  it('never returns another account rows, at either scope', async () => {
+    // The tenant filter is the baked-in var, not the session, and it is applied
+    // whichever scope the person holds. `v4` belongs to acc-b.
+    const own = await processVisits('sess', env(db(ROWS, asPerson('alice', 'own'))), () => {}, 1)
+    const acct = await processVisits('sess', env(db(ROWS, asPerson('marie', 'account'))), () => {}, 1)
+    expect(ids(own)).not.toContain('v4')
+    expect(ids(acct)).not.toContain('v4')
+  })
+
+  it('hides an unbound visit from an own-scoped person', async () => {
+    // An unbound visit carries ownerId ''. Enrolment pins ownerId to
+    // ^[a-z0-9-]+$ (portal-enrol.mjs), so no enrolled person's id is ever '',
+    // and the own-scoped filter cannot match the unbound sentinel.
+    const h = await processVisits('sess', env(db(ROWS, asPerson('alice', 'own'))), () => {}, 1)
+    expect(ids(h)).not.toContain('v3')
+  })
+
+  it('denies when the session does not resolve', async () => {
+    const d = {
+      prepare: () => ({ bind: () => ({ first: async () => null }) }),
+    } as unknown as D1Database
+    const h = await processVisits('', env(d), () => {}, 1)
+    expect(h.status).toBe(401)
+    expect(h.payload).toEqual({ ok: false, error: 'denied' })
+  })
+
+  it('logs the scope it applied, and no visit detail', async () => {
+    const lines: string[] = []
+    await processVisits('sess', env(db(ROWS, asPerson('alice', 'own'))), (l) => lines.push(l), 1)
+    expect(lines.join('\n')).toContain('scope=own')
+    expect(lines.join('\n')).toContain('visits=1')
+  })
+})

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

@@ -90,6 +90,7 @@ For each person:
 ```bash
 node platform/plugins/cloudflare/bin/portal-enrol.mjs --owner <ownerId> --name <name> \
   --account <accountId> [--storage-model shared|dedicated] [--folders <a,b,c>] \
+  [--record-scope own|account] \
   | npx wrangler d1 execute <portalDbName> --remote --file=-
 ```
 
@@ -124,6 +125,28 @@ the same upsert that rotates the passcode. The grant lives only in the portal's
 below the account's exposed set and never widens past it: a portal compromise returns a person to the
 account set, which the install re-derives and enforces regardless.
 
+`--record-scope` is a different question from `--folders` and answers it for RECORDS rather than
+files: `own` lets the person read only records carrying their own id, `account` lets them read every
+record for the account. Two values and no third; a typo is refused rather than resolved to whichever
+is nearer. Omitting it gives `own`, so nobody is granted account-wide visibility by leaving a flag
+off. Re-enrolment replaces it, the same upsert that rotates the passcode, and that is the only way
+to narrow a person back. The office person who schedules gets `account`; a field worker gets `own`.
+
+The scope's only reader is `functions/api/visits.ts`, which the template ships. An account's own page
+renders what that endpoint returns and never re-implements the filter — a gate written once per
+client is a gate got wrong once per client.
+
+**On a store that predates this column, run the `ALTER` once before enrolling anyone.** `IF NOT
+EXISTS` adds no column to an existing table, so `schema.sql` will not do it for you and enrolment's
+INSERT names the column, which means it fails loudly rather than writing a scopeless row:
+
+```sql
+ALTER TABLE people ADD COLUMN recordScope TEXT NOT NULL DEFAULT 'own';
+```
+
+No backfill follows it. Everyone already enrolled lands on the narrow scope, which is the intended
+outcome, and widening one person is a re-run of enrolment for that person.
+
 **A passcode is never stored in plaintext** — not in `data-portal.json`, not in a log line, nowhere
 on the device. The operator conveys it to the person out of band. Rotating a passcode is a re-run of
 the script for that person; there is no separate editor.

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

@@ -47,6 +47,22 @@
 -- to a `people` table that predates it, and enrolment's INSERT names `folders`,
 -- so it fails loudly on such a table. Add it by hand in that case:
 --   ALTER TABLE people ADD COLUMN folders TEXT NOT NULL DEFAULT '';
+-- `recordScope` is which RECORDS this person may read, as distinct from
+-- `folders` above, which is which FILES they may browse. Two values and no
+-- third: `own` sees only records carrying their ownerId, `account` sees every
+-- record for the account. `functions/api/visits.ts` is its only reader, and it
+-- is deliberately the only one — a gate written once per client is a gate got
+-- wrong once per client.
+--
+-- The default is the NARROW value, and that is the whole of the migration
+-- story. Like `accountId` and `folders`, IF NOT EXISTS will NOT add this column
+-- to a `people` table that predates it, and enrolment's INSERT names it, so
+-- such a table fails loudly. Add it by hand in that case:
+--   ALTER TABLE people ADD COLUMN recordScope TEXT NOT NULL DEFAULT 'own';
+-- Every person already enrolled then lands on the narrow scope. A default of
+-- `account` would have handed all of them account-wide visibility by migration,
+-- which is the one thing a scope column must never do.
+--
 -- The key is (accountId, ownerId), not ownerId alone. On the shared store two
 -- clients may each enrol a person called `rob`, and a bare ownerId key would
 -- reject the second enrolment outright. Worse, the enrolment upsert would treat
@@ -60,6 +76,7 @@ CREATE TABLE IF NOT EXISTS people (
   createdAt  TEXT NOT NULL,
   accountId  TEXT NOT NULL DEFAULT '',
   folders    TEXT NOT NULL DEFAULT '',
+  recordScope TEXT NOT NULL DEFAULT 'own',
   PRIMARY KEY (accountId, ownerId)
 );
 
@@ -228,3 +245,80 @@ CREATE TABLE IF NOT EXISTS directory_state (
   accountId         TEXT PRIMARY KEY,
   currentGeneration INTEGER NOT NULL
 );
+
+-- One row per :Visit the device has published, per staging generation
+-- (Task 2425). Metadata only, and only what the ontology already declares
+-- (schema-construction.md): a job sheet's contents are files, which the
+-- manifest above already carries.
+--
+-- READ THE ASYMMETRY WITH THE COLUMN NOTES ABOVE. Those warn that
+-- IF NOT EXISTS adds no COLUMN to an existing table. It does create an absent
+-- TABLE, so these three need no hand step on a database that predates them.
+-- Stated because a reader who has just absorbed the column warning would
+-- otherwise carry it across and go looking for a migration that is not needed.
+--
+-- `ownerId` is the enrolled portal person the visit is assigned to, resolved by
+-- the push from an explicit `portalOwnerId` on the :Person carrying :Engineer.
+-- It is '' when the engineer carries no such property. That row is NOT dropped:
+-- it stays invisible to every own-scoped person, visible to account-scoped
+-- ones, and counted by the audit as `unboundVisits`, so an unbound engineer is
+-- found in the journal rather than by a worker opening an empty day.
+--
+-- `generation` and `visits_state` mirror `directory`/`directory_state` exactly,
+-- and for the same reason: the push writes a whole generation, moves a pointer
+-- in one forward-only statement, then sweeps what the pointer no longer names.
+-- A listing that races a push reads the old set or the new one, never a
+-- half-built one.
+CREATE TABLE IF NOT EXISTS visits (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  accountId  TEXT NOT NULL,
+  visitId    TEXT NOT NULL,
+  ownerId    TEXT NOT NULL DEFAULT '',
+  jobId      TEXT NOT NULL DEFAULT '',
+  status     TEXT NOT NULL DEFAULT '',
+  startDate  TEXT NOT NULL DEFAULT '',
+  purpose    TEXT NOT NULL DEFAULT '',
+  generation INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (accountId, visitId, generation)
+);
+
+CREATE INDEX IF NOT EXISTS visits_account ON visits (accountId);
+-- The own-scoped read filters on both columns, so it carries its own index
+-- rather than riding the account one.
+CREATE INDEX IF NOT EXISTS visits_owner ON visits (accountId, ownerId);
+
+-- Which generation of an account's visit rows is the live one. The flip of this
+-- single row is the atomic point of a push, exactly as directory_state is.
+-- An account with no row here has never completed one, and every reader joins
+-- through this table, so it shows nothing rather than a staged generation that
+-- no flip ever blessed.
+CREATE TABLE IF NOT EXISTS visits_state (
+  accountId         TEXT PRIMARY KEY,
+  currentGeneration INTEGER NOT NULL
+);
+
+-- The inbound half: a status a person set on the portal, waiting for the device
+-- to carry it into the graph (Task 2425).
+--
+-- `claimed` is set only AFTER the graph write returns. Claiming first is
+-- unrecoverable: if the write then failed, the row would read as delivered and
+-- the person's edit would be gone with nothing saying so. Claiming after costs
+-- a repeated MERGE on a lost response, which is idempotent.
+--
+-- A row whose visitId resolves to no :Visit in that account stays unclaimed and
+-- is counted by the audit. It is never written under another id and never
+-- dropped: a dropped edit is a promise broken to the person who made it, and it
+-- emits nothing at the time it happens.
+CREATE TABLE IF NOT EXISTS visit_status (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  accountId TEXT NOT NULL,
+  visitId   TEXT NOT NULL,
+  ownerId   TEXT NOT NULL,
+  status    TEXT NOT NULL,
+  statusAt  TEXT NOT NULL,
+  claimed   INTEGER NOT NULL DEFAULT 0
+);
+
+-- The pull selects unclaimed rows for one account every sixty seconds, so the
+-- pair carries its own index or every cycle is a full scan.
+CREATE INDEX IF NOT EXISTS visit_status_pending ON visit_status (accountId, claimed);

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/session.ts

@@ -60,16 +60,32 @@ export async function mintSession(
   return sessionId
 }
 
+/**
+ * Which records a person may read.
+ *
+ * Two values and no third: `own` sees only records carrying their ownerId,
+ * `account` sees every record for the account. Distinct from `folders`, which
+ * governs which FILES they browse — a person can hold any combination, and
+ * neither narrows or widens the other.
+ */
+export type RecordScope = 'own' | 'account'
+
 export async function resolveSession(
   db: D1Database,
   sessionId: string,
   accountId: string,
   nowMs: number,
-): Promise<{ ownerId: string; accountId: string; folders: string[] } | null> {
+): Promise<{
+  ownerId: string
+  accountId: string
+  folders: string[]
+  recordScope: RecordScope
+} | null> {
   if (!sessionId) return null
   const row = await db
     .prepare(
-      `SELECT s.ownerId AS ownerId, p.accountId AS accountId, p.folders AS folders
+      `SELECT s.ownerId AS ownerId, p.accountId AS accountId, p.folders AS folders,
+              p.recordScope AS recordScope
          FROM sessions s
          JOIN people p ON p.ownerId = s.ownerId AND p.accountId = s.accountId
         WHERE s.sessionId = ?
@@ -78,7 +94,12 @@ export async function resolveSession(
           AND s.pcCheck = substr(p.hash, 1, 16)`,
     )
     .bind(sessionId, accountId, nowMs)
-    .first<{ ownerId: string; accountId: string; folders: string }>()
+    .first<{
+      ownerId: string
+      accountId: string
+      folders: string
+      recordScope: unknown
+    }>()
   if (!row || typeof row.ownerId !== 'string') return null
   // The join matches on BOTH columns and the lookup is already scoped to this
   // portal's own account, which is what stops a same-named person in another
@@ -92,7 +113,13 @@ export async function resolveSession(
   // means no grant, which the two client surfaces read as no filter (full set).
   const folders =
     typeof row.folders === 'string' ? row.folders.split(',').map((s) => s.trim()).filter(Boolean) : []
-  return { ownerId: row.ownerId, accountId, folders }
+  // ONLY the exact token widens the scope. An empty string, an unknown value, a
+  // null, a legacy row with no such column: every one of them is `own`. An
+  // unreadable scope is the narrow scope, because the alternative is a read
+  // failure that hands out account-wide visibility — the one outcome this
+  // column exists to prevent.
+  const recordScope: RecordScope = row.recordScope === 'account' ? 'account' : 'own'
+  return { ownerId: row.ownerId, accountId, folders, recordScope }
 }
 
 /** Whether a person's folder grant admits `relPath`. An empty grant admits

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/visit-status.ts

@@ -0,0 +1,136 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+
+/**
+ * The longest status a person may set.
+ *
+ * The value reaches `:Visit.status` through the device-side pull, so it is
+ * graph content arriving from the open web. It is refused at the door rather
+ * than truncated: a truncated status is a different status, silently, and the
+ * person who set it is never told.
+ */
+export const MAX_STATUS_LENGTH = 64
+
+/**
+ * Record a status a person set against one of their visits.
+ *
+ * THE GATE IS THE SELECT, not a check beside it. The insert is
+ * `INSERT ... SELECT` over the same `visits` join, under the same two filters
+ * the read applies — the account from the baked-in var, and the owner when and
+ * only when the person's scope is `own`. A visit the person may not see admits
+ * no row, so `meta.changes` is 0 and the handler answers 404. There is no
+ * separate authorisation step that a later edit could reorder past the write.
+ *
+ * This ships in the platform template for the same reason the read does, and
+ * more sharply. A read leak shows someone a working day that is not theirs; a
+ * write leak lets them change it. Neither gate is something to re-implement per
+ * client.
+ *
+ * `ownerId` is stamped from the resolved session and never from the body. A
+ * request that names one is ignored rather than refused, because the field
+ * carries no authority here — the session already decided who is writing.
+ */
+export async function processVisitStatus(
+  body: unknown,
+  sessionId: string,
+  env: PortalEnv,
+  log: Logger,
+  nowMs: number,
+): Promise<Handler> {
+  const session = await resolveSession(env.DB, sessionId, env.PORTAL_ACCOUNT_ID, nowMs)
+  if (!session) {
+    log('[data-portal] op=visit-status owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+
+  const b = (body ?? {}) as Record<string, unknown>
+  const visitId = typeof b.visitId === 'string' ? b.visitId : ''
+  const status = typeof b.status === 'string' ? b.status : ''
+  if (!visitId || !status) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=bad-request`)
+    return { status: 400, payload: { ok: false, error: 'visitId and status are required' } }
+  }
+  if (status.length > MAX_STATUS_LENGTH) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=status-too-long`)
+    return { status: 400, payload: { ok: false, error: 'status too long' } }
+  }
+
+  const scoped = session.recordScope === 'own'
+  const sql =
+    `INSERT INTO visit_status (accountId, ownerId, status, statusAt, claimed, visitId)
+     SELECT ?, ?, ?, ?, 0, v.visitId
+       FROM visits v
+       JOIN visits_state s
+         ON s.accountId = v.accountId AND s.currentGeneration = v.generation
+      WHERE v.accountId = ?` +
+    (scoped ? ' AND v.ownerId = ?' : '') +
+    ' AND v.visitId = ?'
+  const statusAt = new Date(nowMs).toISOString()
+  const stmt = env.DB.prepare(sql)
+  const bound = scoped
+    ? stmt.bind(
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        status,
+        statusAt,
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        visitId,
+      )
+    : stmt.bind(
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        status,
+        statusAt,
+        env.PORTAL_ACCOUNT_ID,
+        visitId,
+      )
+  const result = await bound.run()
+  const changes = result.meta?.changes ?? 0
+
+  if (changes === 0) {
+    // One answer for "no such visit" and "not yours", deliberately. The two are
+    // the same fact to a caller who may not see it, and distinguishing them
+    // would let anyone enumerate the account's visit ids.
+    log(
+      `[data-portal] op=visit-status owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+        `scope=${session.recordScope} result=not-found`,
+    )
+    return { status: 404, payload: { ok: false, error: 'not found' } }
+  }
+
+  // Counts, the scope and the outcome. Never the status text: it describes what
+  // a real person was doing.
+  log(
+    `[data-portal] op=visit-status owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+      `scope=${session.recordScope} queued=${changes} result=ok`,
+  )
+  return { status: 200, payload: { ok: true, queued: changes } }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestPost(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  let body: unknown = null
+  try {
+    body = await context.request.json()
+  } catch {
+    // A malformed body is a bad request, not a crash. processVisitStatus
+    // resolves the session first, so an unauthenticated caller still gets 401
+    // rather than learning that the body parse is what failed.
+    body = null
+  }
+  const { status, payload } = await processVisitStatus(
+    body,
+    sessionId,
+    context.env,
+    (line) => console.log(line),
+    Date.now(),
+  )
+  return Response.json(payload, { status })
+}