@rubytech/create-maxy-code 0.1.562 → 0.1.564

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

@@ -0,0 +1,294 @@
+import { describe, it, expect } from 'vitest'
+import {
+  MAX_NOTE_LENGTH,
+  MAX_STATUS_LENGTH,
+  WORK_DATE_RE,
+  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')
+  })
+})
+
+describe('the working day a status edit may carry', () => {
+  const day = (extra: Record<string, unknown>) => ({ visitId: 'v1', status: 'done', ...extra })
+
+  it('inserts the day, the date and the note when the claim is well formed', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(
+      day({ dayHundredths: 100, workDate: '2026-08-05', workNote: 'second fix' }),
+      'sess',
+      env(database),
+      () => {},
+      1,
+    )
+    expect(h.status).toBe(200)
+    expect(inserted[0]).toContain(100)
+    expect(inserted[0]).toContain('2026-08-05')
+    expect(inserted[0]).toContain('second fix')
+  })
+
+  it('defaults to no claim when the body carries no day', async () => {
+    // A status-only edit is the common case and must stay a one-field write.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(day({}), 'sess', env(database), () => {}, 1)
+    expect(h.status).toBe(200)
+    expect(inserted[0]).toContain(0)
+    expect(inserted[0]).toContain('')
+  })
+
+  it('refuses a day outside 0..100 rather than writing it into the graph', async () => {
+    // A value above a full day is described by no shipped surface. Refused at
+    // the door, exactly as an over-long status is.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const e = env(database)
+    for (const d of [101, -1, 50.5, '100']) {
+      const h = await processVisitStatus(
+        day({ dayHundredths: d, workDate: '2026-08-05' }),
+        'sess',
+        e,
+        () => {},
+        1,
+      )
+      expect(h.status).toBe(400)
+    }
+    expect(inserted).toEqual([])
+  })
+
+  it('refuses a claim whose date is missing or malformed', async () => {
+    // The date becomes part of the cost key. A claim the roll-up cannot date is
+    // told to the person now, not left sitting in the queue.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const e = env(database)
+    for (const wd of [undefined, '', '5th Aug', '2026-8-5']) {
+      const h = await processVisitStatus(
+        day({ dayHundredths: 100, workDate: wd }),
+        'sess',
+        e,
+        () => {},
+        1,
+      )
+      expect(h.status).toBe(400)
+    }
+    expect(inserted).toEqual([])
+  })
+
+  it('accepts a date only in the shape the pull will key on', () => {
+    expect(WORK_DATE_RE.test('2026-08-05')).toBe(true)
+    expect(WORK_DATE_RE.test('2026-08-05T09:00:00Z')).toBe(false)
+  })
+
+  it('refuses a note longer than the cap rather than truncating it', async () => {
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(
+      day({
+        dayHundredths: 100,
+        workDate: '2026-08-05',
+        workNote: 'x'.repeat(MAX_NOTE_LENGTH + 1),
+      }),
+      'sess',
+      env(database),
+      () => {},
+      1,
+    )
+    expect(h.status).toBe(400)
+    expect(inserted).toEqual([])
+  })
+
+  it('logs whether the edit carried a day, and never the note', async () => {
+    const lines: string[] = []
+    const { database } = db(ROWS, person('alice', 'own'))
+    await processVisitStatus(
+      day({ dayHundredths: 100, workDate: '2026-08-05', workNote: 'granary court rewire' }),
+      'sess',
+      env(database),
+      (l) => lines.push(l),
+      1,
+    )
+    const joined = lines.join('\n')
+    expect(joined).toContain('labour=true')
+    expect(joined).not.toContain('granary')
+    expect(joined).not.toContain('2026-08-05')
+  })
+
+  it('still refuses another person visit when the edit carries a day', async () => {
+    // The gate is the SELECT and the new fields must not have moved it.
+    const { database, inserted } = db(ROWS, person('alice', 'own'))
+    const h = await processVisitStatus(
+      { visitId: 'v2', status: 'done', dayHundredths: 100, workDate: '2026-08-05' },
+      'sess',
+      env(database),
+      () => {},
+      1,
+    )
+    expect(h.status).toBe(404)
+    expect(inserted).toEqual([])
+  })
+})

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,43 @@ 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 status edit may also carry a working day, and a store that predates those three columns needs
+them added once too.** `dayHundredths` is integer hundredths of a day, which is what the timesheet
+engine consumes: 100 is a full day, and 0 means the edit claims no labour. `workDate` is the day
+worked, and the pull refuses a claim without one rather than dating it from when the sheet was filed.
+`workNote` is what the worker did. The same `IF NOT EXISTS` rule applies, so run all three:
+
+```sql
+ALTER TABLE visit_status ADD COLUMN dayHundredths INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE visit_status ADD COLUMN workDate TEXT NOT NULL DEFAULT '';
+ALTER TABLE visit_status ADD COLUMN workNote TEXT NOT NULL DEFAULT '';
+```
+
+Until they exist the endpoint's INSERT names columns the table lacks and fails loudly, which is the
+intended outcome: a status edit silently losing its hours is the failure worth avoiding.
+
 **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,98 @@ 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.
+-- `dayHundredths`, `workDate` and `workNote` are the working day the edit
+-- carries (Task 2432). `dayHundredths` is integer hundredths of a day, which is
+-- exactly what the timesheet engine consumes: 100 is a full day. 0 means this
+-- edit carries no labour claim, the same absent-sentinel convention `ownerId`
+-- uses above for unbound. The pull writes a labour :JobCost only when it is
+-- above 0, and refuses a claim carrying no `workDate` rather than dating it
+-- from anything else: `statusAt` would record the wrong day for a sheet filed
+-- the next morning, and a visit's scheduled date is not evidence of when it was
+-- attended.
+--
+-- IF NOT EXISTS adds none of the three to a table that predates them. Add them
+-- by hand in that case, in this order:
+--   ALTER TABLE visit_status ADD COLUMN dayHundredths INTEGER NOT NULL DEFAULT 0;
+--   ALTER TABLE visit_status ADD COLUMN workDate TEXT NOT NULL DEFAULT '';
+--   ALTER TABLE visit_status ADD COLUMN workNote TEXT NOT NULL DEFAULT '';
+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,
+  dayHundredths INTEGER NOT NULL DEFAULT 0,
+  workDate      TEXT NOT NULL DEFAULT '',
+  workNote      TEXT NOT NULL DEFAULT '',
+  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